1Array::Compare(3)     User Contributed Perl Documentation    Array::Compare(3)
2
3
4

NAME

6       Array::Compare - Perl extension for comparing arrays.
7

SYNOPSIS

9         use Array::Compare;
10
11         my $comp1 = Array::Compare->new;
12         $comp->Sep('|');
13         $comp->Skip({3 => 1, 4 => 1});
14         $comp->WhiteSpace(0);
15         $comp->Case(1);
16
17         my $comp2 = Array::Compare->new(Sep => '|',
18                                         WhiteSpace => 0,
19                                         Case => 1,
20                                         Skip => {3 => 1, 4 => 1});
21
22         my @arr1 = 0 .. 10;
23         my @arr2 = 0 .. 10;
24
25         $comp1->compare(\@arr1, \@arr2);
26         $comp2->compare(\@arr1, \@arr2);
27

DESCRIPTION

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
32       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
35         my @arr1 = 0 .. 10;
36         my @arr2 = 0 .. 10;
37
38         my $comp = Array::Compare->new;
39
40         if ($comp->compare(\@arr1, \@arr2)) {
41           print "Arrays are the same\n";
42         } else {
43           print "Arrays are different\n";
44         }
45
46       Notice that you pass references to the two arrays to the comparison
47       method.
48
49       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
56       To avoid this, it is possible to override the default separator
57       character, either by passing an alternative to the "new" function
58
59         my $comp = Array::Compare->new(Sep => '|');
60
61       or by changing the separator for an existing comparator object
62
63         $comp->Sep('|');
64
65       In general you should choose a separator character that won't appear in
66       your data.
67
68       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
75         my $comp = Array::Compare->new(WhiteSpace => 0);
76
77       or by altering an existing object:
78
79         $comp->WhiteSpace(0);
80
81       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
86         my $comp = Array::Compare->new(Case => 0);
87
88       or by altering an existing object:
89
90         $comp->Case(0);
91
92       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
102         my $comp = Array::Compare->new(DefFull => 1);
103         $comp->compare(\@arr1, \@arr2); # Full comparison
104
105         $comp->DefFull(0);
106         $comp->compare(\@arr1, \@arr2); # Simple comparison
107
108         $comp->DefFull(1);
109         $comp->compare(\@arr1, \@arr2); # Full comparison again
110
111       Secondly, you can access the full comparison method directly
112
113         $comp->full_compare(\@arr1, \@arr2);
114
115       For symmetry, there is also a direct method to use to call the simple
116       comparison.
117
118         $comp->simple_compare(\@arr1, \@arr2);
119
120       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
129       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
132         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
136         my $comp = Array::Compare->new(Skip => \%skip);
137
138         $comp->compare(\@a, \@b);
139
140       This should return true, as we are explicitly ignoring the columns
141       which differ.
142
143       Of course, having created a comparator object with no skip hash, it is
144       possible to add one later:
145
146         $comp->Skip({1 => 1, 2 => 1});
147
148       or:
149
150         my %skip = (1 => 1, 2 => 2);
151         $comp->Skip(\%skip);
152
153       To reset the comparator so that no longer skips elements, call
154       NoSkip().
155
156         $comp->NoSkip();
157
158       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
161         if ($comp->perm(\@a, \@b) {
162           print "Arrays are perms\n";
163         else {
164           print "Nope. Arrays are completely different\n";
165         }
166
167       In this case the values of "WhiteSpace" and "Case" are still used, but
168       "Skip" is ignored for, hopefully, obvious reasons.
169

METHODS

171   new [ %OPTIONS ]
172       Constructs a new comparison object.
173
174       Takes an optional hash containing various options that control how
175       comparisons are carried out. Any omitted options take useful defaults.
176
177       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
181       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
187       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
191       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
196       NoSkip
197           Reset skipped column details. It assigns {} to the attribute
198           "Skip".
199
200       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
206   compare_len \@ARR1, \@ARR2
207       Very simple comparison. Just checks the lengths of the arrays are the
208       same.
209
210   different_len \@ARR1, \@ARR2
211       Passed two arrays and returns true if they are of different lengths.
212
213       This is just the inverse of "compare_len" (which is badly named).
214
215   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
221       Uses the value of DefFull to determine which comparison routine to use.
222
223   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
227       Returns true if the arrays are the same or false if they differ.
228
229       Uses the values of 'Sep', 'WhiteSpace' and 'Skip' to influence the
230       comparison.
231
232   full_compare \@ARR1, \@ARR2
233       Do a full comparison between two arrays.
234
235       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
240       Uses the values of 'Sep' and 'WhiteSpace' to influence the comparison.
241
242       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
247   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
251       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

AUTHOR

257       Dave Cross <dave@mag-sol.com>
258

SEE ALSO

260       perl(1).
261
263       Copyright (C) 2000-2005, Magnum Solutions Ltd.  All Rights Reserved.
264
265       This script is free software; you can redistribute it and/or modify it
266       under the same terms as Perl itself.
267
268
269
270perl v5.32.0                      2020-07-28                 Array::Compare(3)
Impressum