NAME¶
Array::Compare - Perl extension for comparing arrays.
SYNOPSIS¶
use Array::Compare;
my $comp1 = Array::Compare->new;
$comp->Sep('|');
$comp->Skip({3 => 1, 4 => 1});
$comp->WhiteSpace(0);
$comp->Case(1);
my $comp2 = Array::Compare->new(Sep => '|',
WhiteSpace => 0,
Case => 1,
Skip => {3 => 1, 4 => 1});
my @arr1 = 0 .. 10;
my @arr2 = 0 .. 10;
$comp1->compare(\@arr1, \@arr2);
$comp2->compare(\@arr1, \@arr2);
DESCRIPTION¶
If you have two arrays and you want to know if they are the same or different,
then Array::Compare will be useful to you.
All comparisons are carried out via a comparator object. In the simplest usage,
you can create and use a comparator object like this:
my @arr1 = 0 .. 10;
my @arr2 = 0 .. 10;
my $comp = Array::Compare->new;
if ($comp->compare(\@arr1, \@arr2)) {
print "Arrays are the same\n";
} else {
print "Arrays are different\n";
}
Notice that you pass references to the two arrays to the comparison method.
Internally the comparator compares the two arrays by using "join" to
turn both arrays into strings and comparing the strings using "eq".
In the joined strings, the elements of the original arrays are separated with
the "^G" character. This can cause problems if your array data
contains "^G" characters as it is possible that two different arrays
can be converted to the same string.
To avoid this, it is possible to override the default separator character,
either by passing and alternative to the "new" function
my $comp = Array::Compare->new(Sep => '|');
or by changing the seperator for an existing comparator object
$comp->Sep('|');
In general you should choose a separator character that won't appear in your
data.
You can also control whether or not whitespace within the elements of the arrays
should be considered significant when making the comparison. The default is
that all whitespace is significant. The alternative is for all consecutive
white space characters to be converted to a single space for the pruposes of
the comparison. Again, this can be turned on when creating a comparator
object:
my $comp = Array::Compare->new(WhiteSpace => 0);
or by altering an existing object:
$comp->WhiteSpace(0);
You can also control whether or not the case of the data is significant in the
comparison. The default is that the case of data is taken into account. This
can be changed in the standard ways when creating a new comparator object:
my $comp = Array::Compare->new(Case => 0);
or by altering an existing object:
$comp->Case(0);
In addition to the simple comparison described above (which returns true if the
arrays are the same and false if they're different) there is also a full
comparison which returns a list containing the indexes of elements which
differ between the two arrays. If the arrays are the same it returns an empty
list. In scalar context the full comparison returns the length of this list
(i.e. the number of elements that differ). You can access the full comparision
in two ways. Firstly, there is a "DefFull" attribute. If this is
"true" then a full comparison if carried out whenever the
"compare" method is called.
my $comp = Array::Compare->new(DefFull => 1);
$comp->compare(\@arr1, \@arr2); # Full comparison
$comp->DefFull(0);
$comp->compare(\@arr1, \@arr2); # Simple comparison
$comp->DefFull(1);
$comp->compare(\@arr1, \@arr2); # Full comparison again
Secondly, you can access the full comparison method directly
$comp->full_compare(\@arr1, \@arr2);
For symmetry, there is also a direct method to use to call the simple
comparison.
$comp->simple_compare(\@arr1, \@arr2);
The final complication is the ability to skip elements in the comparison. If you
know that two arrays will always differ in a particular element but want to
compare the arrays
ignoring this element, you can do it with
Array::Compare without taking array slices. To do this, a comparator object
has an optional attribute called "Skip" which is a reference to a
hash. The keys in this hash are the indexes of the array elements and the
values should be any true value for elements that should be skipped.
For example, if you want to compare two arrays, ignoring the values in elements
two and four, you can do something like this:
my %skip = (2 => 1, 4 => 1);
my @a = (0, 1, 2, 3, 4, 5);
my @b = (0, 1, X, 3, X, 5);
my $comp = Array::Compare->new(Skip => \%skip);
$comp->compare(\@a, \@b);
This should return
true, as we are explicitly ignoring the columns which
differ.
Of course, having created a comparator object with no skip hash, it is possible
to add one later:
$comp->Skip({1 => 1, 2 => 1});
or:
my %skip = (1 => 1, 2 => 2);
$comp->Skip(\%skip);
To reset the comparator so that no longer skips elements, set the skip hash to
an empty hash.
$comp->Skip({});
You can also check to see if one array is a permutation of another, i.e. they
contain the same elements but in a different order.
if ($comp->perm(\@a, \@b) {
print "Arrays are perms\n";
else {
print "Nope. Arrays are completely different\n";
}
In this case the values of "WhiteSpace" and "Case" are still
used, but "Skip" is ignored for, hopefully, obvious reasons.
METHODS¶
new [ %OPTIONS ]¶
Constructs a new comparison object.
Takes an optional hash containing various options that control how comparisons
are carried out. Any omitted options take useful defaults.
- Sep
- This is the value that is used to separate fields when the array is joined
into a string. It should be a value which doesn't appear in your data.
Default is '^G'.
- WhiteSpace
- Flag that indicates whether or not whitespace is significant in the
comparison. If this value is false then all multiple whitespace characters
are changed into a single space before the comparison takes place. Default
is 1 (whitespace is significant).
- Case
- Flag that indicates whther or not the case of the data should be
significant in the comparison. Default is 1 (case is significant).
- Skip
- a reference to a hash which contains the numbers of any columns that
should be skipped in the comparison. Default is an empty hash (all columns
are significant).
- DefFull
- Flag which indicates whether the default comparison is simple (just
returns true if the arrays are the same or false if they're not) or full
(returns an array containing the indexes of the columns that differ).
Default is 0 (simple comparison).
compare_len \@ARR1, \@ARR2¶
Very simple comparison. Just checks the lengths of the arrays are the same.
compare \@ARR1, \@ARR2¶
Compare the values in two arrays and return a data indicating whether the arrays
are the same. The exact return values differ depending on the comparison
method used. See the descriptions of simple_compare and full_compare for
details.
Uses the value of DefFull to determine which comparison routine to use.
simple_compare \@ARR1, \@ARR2¶
Compare the values in two arrays and return a flag indicating whether or not the
arrays are the same.
Returns true if the arrays are the same or false if they differ.
Uses the values of 'Sep', 'WhiteSpace' and 'Skip' to influence the comparison.
full_compare \@ARR1, \@ARR2¶
Do a full comparison between two arrays.
Checks each individual column. In scalar context returns the number of columns
that differ (zero if the arrays are the same). In list context returns an list
containing the indexes of the columns that differ (an empty list if the arrays
are the same).
Uses the values of 'Sep' and 'WhiteSpace' to influence the comparison.
Note: If the two arrays are of different lengths then this method just
returns the indexes of the elements that appear in one array but not the other
(i.e. the indexes from the longer array that are beyond the end of the shorter
array). This might be a little counter-intuitive.
perm \@ARR1, \@ARR2¶
Check to see if one array is a permutation of the other (i.e. contains the same
set of elements, but in a different order).
We do this by sorting the arrays and passing references to the assorted versions
to simple_compare. There are also some small changes to simple_compare as it
should ignore the Skip hash if we are called from perm.
AUTHOR¶
Dave Cross <dave@mag-sol.com>
SEE ALSO¶
perl(1).
COPYRIGHT AND LICENSE¶
Copyright (C) 2000-2005, Magnum Solutions Ltd. All Rights Reserved.
This script is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.