1Array::Compare(3) User Contributed Perl Documentation Array::Compare(3)
2
6 Array::Compare - Perl extension for comparing arrays.
7
9 use Array::Compare;
10 my $comp1 = Array::Compare->new;
12 $comp->Sep('|');
13 $comp->Skip({3 => 1, 4 => 1});
14 $comp->WhiteSpace(0);
15 $comp->Case(1);
16 my $comp2 = Array::Compare->new(Sep => '|',
18 WhiteSpace => 0,
19 Case => 1,
20 Skip => {3 => 1, 4 => 1});
21 my @arr1 = 0 .. 10;
23 my @arr2 = 0 .. 10;
24 $comp1->compare(\@arr1, \@arr2);
26 $comp2->compare(\@arr1, \@arr2);
27
29 If you have two arrays and you want to know if they are the same or
30 different, then Array::Compare will be useful to you.
31 All comparisons are carried out via a comparator object. In the
33 simplest usage, you can create and use a comparator object like this:
34 my @arr1 = 0 .. 10;
36 my @arr2 = 0 .. 10;
37 my $comp = Array::Compare->new;
39 if ($comp->compare(\@arr1, \@arr2)) {
41 print "Arrays are the same\n";
42 } else {
43 print "Arrays are different\n";
44 }
45 Notice that you pass references to the two arrays to the comparison
47 method.
48 Internally the comparator compares the two arrays by using "join" to
50 turn both arrays into strings and comparing the strings using "eq". In
51 the joined strings, the elements of the original arrays are separated
52 with the "^G" character. This can cause problems if your array data
53 contains "^G" characters as it is possible that two different arrays
54 can be converted to the same string.
55 To avoid this, it is possible to override the default separator
57 character, either by passing an alternative to the "new" function
58 my $comp = Array::Compare->new(Sep => '|');
60 or by changing the separator for an existing comparator object
62 $comp->Sep('|');
64 In general you should choose a separator character that won't appear in
66 your data.
67 You can also control whether or not whitespace within the elements of
69 the arrays should be considered significant when making the comparison.
70 The default is that all whitespace is significant. The alternative is
71 for all consecutive white space characters to be converted to a single
72 space for the purposes of the comparison. Again, this can be turned on
73 when creating a comparator object:
74 my $comp = Array::Compare->new(WhiteSpace => 0);
76 or by altering an existing object:
78 $comp->WhiteSpace(0);
80 You can also control whether or not the case of the data is significant
82 in the comparison. The default is that the case of data is taken into
83 account. This can be changed in the standard ways when creating a new
84 comparator object:
85 my $comp = Array::Compare->new(Case => 0);
87 or by altering an existing object:
89 $comp->Case(0);
91 In addition to the simple comparison described above (which returns
93 true if the arrays are the same and false if they're different) there
94 is also a full comparison which returns a list containing the indexes
95 of elements which differ between the two arrays. If the arrays are the
96 same it returns an empty list. In scalar context the full comparison
97 returns the length of this list (i.e. the number of elements that
98 differ). You can access the full comparison in two ways. Firstly, there
99 is a "DefFull" attribute. If this is "true" then a full comparison is
100 carried out whenever the "compare" method is called.
101 my $comp = Array::Compare->new(DefFull => 1);
103 $comp->compare(\@arr1, \@arr2); # Full comparison
104 $comp->DefFull(0);
106 $comp->compare(\@arr1, \@arr2); # Simple comparison
107 $comp->DefFull(1);
109 $comp->compare(\@arr1, \@arr2); # Full comparison again
110 Secondly, you can access the full comparison method directly
112 $comp->full_compare(\@arr1, \@arr2);
114 For symmetry, there is also a direct method to use to call the simple
116 comparison.
117 $comp->simple_compare(\@arr1, \@arr2);
119 The final complication is the ability to skip elements in the
121 comparison. If you know that two arrays will always differ in a
122 particular element but want to compare the arrays ignoring this
123 element, you can do it with Array::Compare without taking array slices.
124 To do this, a comparator object has an optional attribute called "Skip"
125 which is a reference to a hash. The keys in this hash are the indexes
126 of the array elements and the values should be any true value for
127 elements that should be skipped.
128 For example, if you want to compare two arrays, ignoring the values in
130 elements two and four, you can do something like this:
131 my %skip = (2 => 1, 4 => 1);
133 my @a = (0, 1, 2, 3, 4, 5);
134 my @b = (0, 1, X, 3, X, 5);
135 my $comp = Array::Compare->new(Skip => \%skip);
137 $comp->compare(\@a, \@b);
139 This should return true, as we are explicitly ignoring the columns
141 which differ.
142 Of course, having created a comparator object with no skip hash, it is
144 possible to add one later:
145 $comp->Skip({1 => 1, 2 => 1});
147 or:
149 my %skip = (1 => 1, 2 => 2);
151 $comp->Skip(\%skip);
152 To reset the comparator so that no longer skips elements, call
154 NoSkip().
155 $comp->NoSkip();
157 You can also check to see if one array is a permutation of another,
159 i.e. they contain the same elements but in a different order.
160 if ($comp->perm(\@a, \@b) {
162 print "Arrays are perms\n";
163 } else {
164 print "Nope. Arrays are completely different\n";
165 }
166 In this case the values of "WhiteSpace" and "Case" are still used, but
168 "Skip" is ignored for, hopefully, obvious reasons.
169
171 new [ %OPTIONS ]
172 Constructs a new comparison object.
173 Takes an optional hash containing various options that control how
175 comparisons are carried out. Any omitted options take useful defaults.
176 Sep This is the value that is used to separate fields when the array is
178 joined into a string. It should be a value which doesn't appear in
179 your data. Default is '^G'.
180 WhiteSpace
182 Flag that indicates whether or not whitespace is significant in the
183 comparison. If this value is false then all multiple whitespace
184 characters are changed into a single space before the comparison
185 takes place. Default is 1 (whitespace is significant).
186 Case
188 Flag that indicates whther or not the case of the data should be
189 significant in the comparison. Default is 1 (case is significant).
190 Skip
192 a reference to a hash which contains the numbers of any columns
193 that should be skipped in the comparison. Default is an empty hash
194 (all columns are significant).
195 NoSkip
197 Reset skipped column details. It assigns {} to the attribute
198 "Skip".
199 DefFull
201 Flag which indicates whether the default comparison is simple (just
202 returns true if the arrays are the same or false if they're not) or
203 full (returns an array containing the indexes of the columns that
204 differ). Default is 0 (simple comparison).
205 compare_len \@ARR1, \@ARR2
207 Very simple comparison. Just checks the lengths of the arrays are the
208 same.
209 different_len \@ARR1, \@ARR2
211 Passed two arrays and returns true if they are of different lengths.
212 This is just the inverse of "compare_len" (which is badly named).
214 compare \@ARR1, \@ARR2
216 Compare the values in two arrays and return a data indicating whether
217 the arrays are the same. The exact return values differ depending on
218 the comparison method used. See the descriptions of simple_compare and
219 full_compare for details.
220 Uses the value of DefFull to determine which comparison routine to use.
222 simple_compare \@ARR1, \@ARR2
224 Compare the values in two arrays and return a flag indicating whether
225 or not the arrays are the same.
226 Returns true if the arrays are the same or false if they differ.
228 Uses the values of 'Sep', 'WhiteSpace' and 'Skip' to influence the
230 comparison.
231 full_compare \@ARR1, \@ARR2
233 Do a full comparison between two arrays.
234 Checks each individual column. In scalar context returns the number of
236 columns that differ (zero if the arrays are the same). In list context
237 returns a list containing the indexes of the columns that differ (an
238 empty list if the arrays are the same).
239 Uses the values of 'Sep' and 'WhiteSpace' to influence the comparison.
241 Note: If the two arrays are of different lengths then this method just
243 returns the indexes of the elements that appear in one array but not
244 the other (i.e. the indexes from the longer array that are beyond the
245 end of the shorter array). This might be a little counter-intuitive.
246 perm \@ARR1, \@ARR2
248 Check to see if one array is a permutation of the other (i.e. contains
249 the same set of elements, but in a different order).
250 We do this by sorting the arrays and passing references to the assorted
252 versions to simple_compare. There are also some small changes to
253 simple_compare as it should ignore the Skip hash if we are called from
254 perm.
255
257 Dave Cross <dave@mag-sol.com>
258
260 perl(1).
261
263 Copyright (C) 2000-2005, Magnum Solutions Ltd. All Rights Reserved.
264 This script is free software; you can redistribute it and/or modify it
266 under the same terms as Perl itself.
267perl v5.36.0 2023-01-19 Array::Compare(3)