Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Array::Compare(3)     User Contributed Perl Documentation    Array::Compare(3)

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-08-23		     Array::Compare(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | AUTHOR | SEE ALSO | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Array::Compare&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help