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 an
       alternative to the "new" function

         my $comp = Array::Compare->new(Sep => '|');

       or by changing the separator 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
       purposes 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 comparison in two ways. Firstly, there is a "DefFull" attribute. If this
       is "true" then a full comparison is 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, call NoSkip().

         $comp->NoSkip();

       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).

       NoSkip
           Reset skipped column details. It assigns {} to the attribute "Skip".

       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.

   different_len \@ARR1, \@ARR2
       Passed two arrays and returns true if they are of different lengths.

       This is just the inverse of "compare_len" (which is badly named).

   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 a 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.

perl v5.32.0                                       2020-12-22                                Array::Compare(3pm)