Provided by: liblist-compare-perl_0.37-2_all bug

NAME

       List::Compare::Functional - Compare elements of two or more lists

VERSION

       This document refers to version 0.37 of List::Compare::Functional.  This version was
       released June 07, 2008.  The first released version of List::Compare::Functional was
       v0.21.  Its version numbers are set to be consistent with the other parts of the
       List::Compare distribution.

   Notice of Interface Changes
       Certain significant changes to the interface to List::Compare::Functional were made with
       the introduction of Version 0.25 in April 2004.  The documentation immediately below
       reflects those changes, so if you are first using this module with that or a later
       version, simply read and follow the documentation below.  If, however, you used
       List::Compare::Functional prior to that version, see the discussion of interface changes
       farther below: April 2004 Change of Interface.

SYNOPSIS

   Getting Started
       List::Compare::Functional exports no subroutines by default.

           use List::Compare::Functional qw(:originals :aliases);

       will import all publicly available subroutines from List::Compare::Functional.  The model
       for importing just one subroutine from List::Compare::Functional is:

           use List::Compare::Functional qw( get_intersection );

       It will probably be most convenient for the user to import functions by using one of the
       two following export tags:

           use List::Compare::Functional qw(:main :mainrefs);

       The assignment of the various comparison functions to export tags is discussed below.

       For clarity, we shall begin by discussing comparisons of just two lists at a time.
       Farther below, we shall discuss comparisons among three or more lists at a time.

   Comparing Two Lists Held in Arrays
       •   Given two lists:

               @Llist = qw(abel abel baker camera delta edward fargo golfer);
               @Rlist = qw(baker camera delta delta edward fargo golfer hilton);

       •   Get those items which appear at least once in both lists (their intersection).

               @intersection = get_intersection( [ \@Llist, \@Rlist ] );

           Note that you could place the references to the lists being compared into a named
           array and then pass "get_intersection()" a reference to that array.

               @to_be_compared = ( \@Llist, \@Rlist );
               @intersection = get_intersection( \@to_be_compared );

           Beginning with version 0.29 (May 2004), List::Compare::Functional now offers an
           additional way of passing arguments to its various functions.  If you prefer to see a
           more explicit delineation among the types of arguments passed to a function, pass a
           single hash reference which holds the lists being compared in an anonymous array which
           is the value corresponding to key "lists":

               @intersection = get_intersection( {
                  lists => [ \@Llist, \@Rlist ],
               } );

       •   Get those items which appear at least once in either list (their union).

               @union = get_union( [ \@Llist, \@Rlist ] );

           or

               @union = get_union( { lists => [ \@Llist, \@Rlist ] } );

       •   Get those items which appear (at least once) only in the first list.

               @Lonly = get_unique( [ \@Llist, \@Rlist ] );

           or

               @Lonly = get_unique( { lists => [ \@Llist, \@Rlist ] } );

       •   Get those items which appear (at least once) only in the second list.

               @Ronly = get_complement( [ \@Llist, \@Rlist ] );

           or

               @Ronly = get_complement( { lists => [ \@Llist, \@Rlist ] } );

       •

               @LorRonly = get_symmetric_difference( [ \@Llist, \@Rlist ] );

               @LorRonly = get_symdiff( [ \@Llist, \@Rlist ] );       # alias

           or

               @LorRonly = get_symmetric_difference( { lists => [ \@Llist, \@Rlist ] } );

       •   Make a bag of all those items in both lists.  The bag differs from the union of the
           two lists in that it holds as many copies of individual elements as appear in the
           original lists.

               @bag = get_bag( [ \@Llist, \@Rlist ] );

           or

               @bag = get_bag( { lists => [ \@Llist, \@Rlist ] } );

       •   An alternative approach to the above functions:  If you do not immediately require an
           array as the return value of the function call, but simply need a reference to an
           (anonymous) array, use one of the following parallel functions:

               $intersection_ref = get_intersection_ref(         [ \@Llist, \@Rlist ] );
               $union_ref        = get_union_ref(                [ \@Llist, \@Rlist ] );
               $Lonly_ref        = get_unique_ref(               [ \@Llist, \@Rlist ] );
               $Ronly_ref        = get_complement_ref(           [ \@Llist, \@Rlist ] );
               $LorRonly_ref     = get_symmetric_difference_ref( [ \@Llist, \@Rlist ] );
               $LorRonly_ref     = get_symdiff_ref(              [ \@Llist, \@Rlist ] );
                                       # alias
               $bag_ref          = get_bag_ref(                  [ \@Llist, \@Rlist ] );

           or

               $intersection_ref =
                   get_intersection_ref(         { lists => [ \@Llist, \@Rlist ] } );
               $union_ref        =
                   get_union_ref(                { lists => [ \@Llist, \@Rlist ] } );
               $Lonly_ref        =
                   get_unique_ref(               { lists => [ \@Llist, \@Rlist ] } );
               $Ronly_ref        =
                   get_complement_ref(           { lists => [ \@Llist, \@Rlist ] } );
               $LorRonly_ref     =
                   get_symmetric_difference_ref( { lists => [ \@Llist, \@Rlist ] } );
               $LorRonly_ref     =
                   get_symdiff_ref(              { lists => [ \@Llist, \@Rlist ] } );
                   # alias
               $bag_ref          =
                   get_bag_ref(                  { lists => [ \@Llist, \@Rlist ] } );

       •   Return a true value if the first list ('L' for 'left') is a subset of the second list
           ('R' for 'right').

               $LR = is_LsubsetR( [ \@Llist, \@Rlist ] );

           or

               $LR = is_LsubsetR( { lists => [ \@Llist, \@Rlist ] } );

       •   Return a true value if R is a subset of L.

               $RL = is_RsubsetL( [ \@Llist, \@Rlist ] );

           or

               $RL = is_RsubsetL( { lists => [ \@Llist, \@Rlist ] } );

       •   Return a true value if L and R are equivalent, i.e., if every element in L appears at
           least once in R and vice versa.

               $eqv = is_LequivalentR( [ \@Llist, \@Rlist ] );
               $eqv = is_LeqvlntR( [ \@Llist, \@Rlist ] );            # alias

           or

               $eqv = is_LequivalentR( { lists => [ \@Llist, \@Rlist ] } );

       •   Return a true value if L and R are disjoint, i.e., if L and R have no common elements.

               $disj = is_LdisjointR( [ \@Llist, \@Rlist ] );

           or

               $disj = is_LdisjointR( { lists => [ \@Llist, \@Rlist ] } );

       •   Pretty-print a chart showing whether one list is a subset of the other.

               print_subset_chart( [ \@Llist, \@Rlist ] );

           or

               print_subset_chart( { lists => [ \@Llist, \@Rlist ] } );

       •   Pretty-print a chart showing whether the two lists are equivalent (same elements found
           at least once in both).

               print_equivalence_chart( [ \@Llist, \@Rlist ] );

           or

               print_equivalence_chart( { lists => [ \@Llist, \@Rlist ] } );

       •   Determine in which (if any) of the lists a given string can be found.  In list
           context, return a list of those indices in the argument list corresponding to lists
           holding the string being tested.

               @memb_arr = is_member_which( [ \@Llist, \@Rlist ] , [ 'abel' ] );

           or

               @memb_arr = is_member_which( {
                   lists => [ \@Llist, \@Rlist ],  # value is array reference
                   item  => 'abel',                # value is string
               } );

           In the example above, @memb_arr will be:

               ( 0 )

           because 'abel' is found only in @Al which holds position 0 in the list of arguments
           passed to "new()".

       •   As with other List::Compare::Functional functions which return a list, you may wish
           the above function returned a (scalar) reference to an array holding the list:

               $memb_arr_ref = is_member_which_ref( [ \@Llist, \@Rlist ] , [ 'baker' ] );

           or

               $memb_arr_ref = is_member_which_ref( {
                   lists => [ \@Llist, \@Rlist ],  # value is array reference
                   item  => 'baker',               # value is string
               } );

           In the example above, $memb_arr_ref will be:

               [ 0, 1 ]

           because 'baker' is found in @Llist and @Rlist, which hold positions 0 and 1,
           respectively, in the list of arguments passed to "new()".

           Note:  functions "is_member_which()" and "is_member_which_ref" test only one string at
           a time and hence take only one argument.  To test more than one string at a time see
           the next function, "are_members_which()".

       •   Determine in "which" (if any) of the lists passed as arguments one or more given
           strings can be found.  The lists beings searched are placed in an array, a reference
           to which is the first argument passed to "are_members_which()".  The strings to be
           tested are also placed in an array, a reference to which is the second argument passed
           to that function.

               $memb_hash_ref =
                   are_members_which( [ \@Llist, \@Rlist ] ,
                                      [ qw| abel baker fargo hilton zebra | ]
                                    );

           or

               $memb_hash_ref = are_members_which( {
                   lists => [ \@Llist, \@Rlist ],                    # value is arrayref
                   items => [ qw| abel baker fargo hilton zebra | ], # value is arrayref
               } );

           The return value is a reference to a hash of arrays.  The key for each element in this
           hash is the string being tested.  Each element's value is a reference to an anonymous
           array whose elements are those indices in the constructor's argument list
           corresponding to lists holding the strings being tested.  In the examples above,
           $memb_hash_ref will be:

               {
                    abel     => [ 0    ],
                    baker    => [ 0, 1 ],
                    fargo    => [ 0, 1 ],
                    hilton   => [    1 ],
                    zebra    => [      ],
               };

           Note:  "are_members_which()" can take more than one argument; "is_member_which()" and
           "is_member_which_ref()" each take only one argument.  Unlike those functions,
           "are_members_which()" returns a hash reference.

       •   Determine whether a given string can be found in any of the lists passed as arguments.
           Return 1 if a specified string can be found in any of the lists and 0 if not.

               $found = is_member_any( [ \@Llist, \@Rlist ] , [ 'abel' ] );

           or

               $found = is_member_any( {
                   lists => [ \@Llist, \@Rlist ], # value is array reference
                   item  => 'abel',               # value is string
               } );

           In the example above, $found will be 1 because 'abel' is found in one or more of the
           lists passed as arguments to "new()".

       •   Determine whether a specified string or strings can be found in any of the lists
           passed as arguments. The lists beings searched are placed in an array, a reference to
           which is the first argument passed to "are_members_any()".  The strings to be tested
           are also placed in an array, a reference to which is the second argument passed to
           that function.

               $memb_hash_ref =
                   are_members_any( [ \@Llist, \@Rlist ] ,
                                    [ qw| abel baker fargo hilton zebra | ]
                                  );

           or

               $memb_hash_ref = are_members_any( {
                   lists => [ \@Llist, \@Rlist ],                    # value is arrayref
                   items => [ qw| abel baker fargo hilton zebra | ], # value is arrayref
               } );

           The return value is a reference to a hash where an element's key is the string being
           tested and the element's value is 1 if the string can be found in any of the lists and
           0 if not.  In the examples above, $memb_hash_ref will be:

               {
                    abel     => 1,
                    baker    => 1,
                    fargo    => 1,
                    hilton   => 1,
                    zebra    => 0,
               };

           "zebra"'s value is 0 because "zebra" is not found in either of the lists passed as
           arguments to "are_members_any()".

       •   Return current List::Compare::Functional version number.

               $vers = get_version;

   Comparing Three or More Lists Held in Arrays
       Given five lists:

           @Al     = qw(abel abel baker camera delta edward fargo golfer);
           @Bob    = qw(baker camera delta delta edward fargo golfer hilton);
           @Carmen = qw(fargo golfer hilton icon icon jerky kappa);
           @Don    = qw(fargo icon jerky);
           @Ed     = qw(fargo icon icon jerky);

       •   Get those items which appear at least once in each list (their intersection).

               @intersection = get_intersection( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );

           or

               @intersection = get_intersection( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
               } );

       •   Get those items which appear at least once in any of the lists (their union).

               @union = get_union( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );

           or
               @union = get_union( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
               } );

       •   To get those items which are unique to a particular list, provide "get_unique()" with
           two array references.  The first holds references to the arrays which in turn hold the
           individual lists being compared.  The second holds the index position in the first
           reference of the particular list under consideration.  Example:  To get elements
           unique to @Carmen:

               @Lonly = get_unique(
                            [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
                            [ 2 ]
                        );

           or

               @Lonly = get_unique( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], # value is arrayref
                   item  => 2,                                      # value is number
               } );

           If no index position is passed to "get_unique()" it will default to 0 and report items
           unique to the first list passed to the function.  Hence,

               @Lonly = get_unique( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );

           is same as:

               @Lonly = get_unique( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], [ 0 ] );

       •   Should you need to identify the items unique to each of the lists under consideration,
           call "get_unique_all" and get a reference to an array of array references:

               $unique_all_ref = get_unique_all(
                   [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ]
               );

           or

               $unique_all_ref = get_unique_all( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
               } );

       •   To get those items which appear only in lists other than one particular list, pass two
           array references to the "get_complement()"  function.  The first holds references to
           the arrays which in turn hold the individual lists being compared.  The second holds
           the index position in the first reference of the particular list under consideration.
           Example:  to get all the elements found in lists other than @Don:

               @Ronly = get_complement(
                            [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
                            [ 3 ]
                        );

           or

               @Ronly = get_complement( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], # value is arrayref
                   item  => 3,                                      # value is number
               } );

           If no index position is passed to "get_complement()" it will default to 0 and report
           items found in all lists other than the first list passed to "get_complement()".

               @Lonly = get_complement( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );

           is same as:

               @Lonly = get_complement( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], [ 0 ] );

       •   Should you need to identify the items not found in each of the lists under
           consideration, call "get_complement_all" and get a reference to an array of array
           references:

               $complement_all_ref = get_complement_all(
                   [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ]
               );

           or

               $complement_all_ref = get_complement_all( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
               } );

       •   Get those items which do not appear in more than one of several lists (their
           symmetric_difference);

               @LorRonly = get_symmetric_difference( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
               @LorRonly = get_symdiff( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] ); # alias

           or

               @LorRonly = get_symmetric_difference( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
               } );

       •   Get those items found in any of several lists which do not appear in "all" of the
           lists (i.e., all items except those found in the intersection of the lists):

               @nonintersection = get_nonintersection(
                                      [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );

           or

               @nonintersection = get_nonintersection( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
               } );

       •   Get those items which appear in more than one of several lists (i.e., all items except
           those found in their symmetric difference);

               @shared = get_shared( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );

           or

               @shared = get_shared( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
               } );

       •   Make a bag of every item found in every list.  The bag differs from the union of the
           two lists in that it holds as many copies of individual elements as appear in the
           original lists.

               @bag = get_bag( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );

           or

               @bag = get_bag( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
               } );

       •   An alternative approach to the above functions:  If you do not immediately require an
           array as the return value of the function, but simply need a reference to an array,
           use one of the following parallel functions:

               $intersection_ref    = get_intersection_ref(
                                        [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
               $union_ref           = get_union_ref(
                                        [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
               $Lonly_ref           = get_unique_ref(
                                        [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
               $Ronly_ref           = get_complement_ref(
                                        [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
               $LorRonly_ref        = get_symmetric_difference_ref(
                                        [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
               $LorRonly_ref        = get_symdiff_ref(            # alias
                                        [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
               $nonintersection_ref = get_nonintersection_ref(
                                        [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
               $shared_ref          = get_shared_ref(
                                        [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
               $bag_ref             = get_bag_ref(
                                        [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );

       •   To determine whether one particular list is a subset of another of the lists passed to
           the function, pass to "is_LsubsetR()" two array references.  The first of these is a
           reference to an array of array references, the arrays holding the lists under
           consideration.  The second is a reference to a two-element array consisting of the
           index of the presumed subset, followed by the index position of the presumed superset.
           A true value (1) is returned if the first (left-hand) element in the second reference
           list is a subset of the second (right-hand) element; a false value (0) is returned
           otherwise.

           Example:  To determine whether @Ed is a subset of @Carmen, call:

               $LR = is_LsubsetR(
                         [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
                         [ 4, 2 ]
                     );

           or

               $LR = is_LsubsetR( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], # value is arrayref
                   pair  => [ 4, 2 ],                               # value is arrayref
               } );

           If only the first reference (to the array of lists) is passed to "is_LsubsetR", then
           the function's second argument defaults to "(0,1)" and compares the first two lists
           passed to the constructor.  So,

               $LR = is_LsubsetR([ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );

           ... is equivalent to:

               $LR = is_LsubsetR([ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], [0,1] );

       •   To reverse the order in which the particular lists are evaluated for superset/subset
           status, call "is_RsubsetL":

               $RL = is_RsubsetL([ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], [2,4] );

           or

               $RL = is_RsubsetL( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
                   pair  => [ 2, 4 ],
               } );

       •   List::Compare::Functional considers two lists to be equivalent if every element in one
           list appears at least once in R and vice versa.  To determine whether one particular
           list passed to the function is equivalent to another of the lists passed to the
           function, provide "is_LequivalentR()" with two array references.  The first is a
           reference to an array of array references, the arrays holding the lists under
           consideration.  The second of these is a reference to a two-element array consisting
           of the two lists being tested for equivalence.  A true value (1) is returned if the
           lists are equivalent; a false value (0) is returned otherwise.

           Example:  To determine whether @Don and @Ed are equivalent, call:

               $eqv = is_LequivalentR(
                          [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
                          [3,4]
                      );

               $eqv = is_LeqvlntR(                                # alias
                          [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
                          [3,4]
                      );

           or

               $eqv = is_LequivalentR( {
                   items => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
                   pair  => [3,4],
               } );

           If no arguments are passed, "is_LequivalentR" defaults to "[0,1]" and compares the
           first two lists passed to the function. So,

               $eqv = is_LequivalentR( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );

           ... translates to:

               $eqv = is_LequivalentR( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], [0,1] );

       •   To determine whether any two of the lists passed to the function are disjoint from one
           another (i.e., have no common members), provide "is_LdisjointR()" with two array
           references.  The first is a reference to an array of array references, the arrays
           holding the lists under consideration.  The second of these is a reference to a two-
           element array consisting of the two lists being tested for disjointedness.  A true
           value (1) is returned if the lists are disjoint; a false value (0) is returned
           otherwise.

           Example:  To determine whether @Don and @Ed are disjoint, call:

               $disj = is_LdisjointR(
                          [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
                          [3,4]
                      );

           or

               $disj = is_LdisjointR( {
                   items => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
                   pair  => [3,4]
               } );

       •   Pretty-print a chart showing the subset relationships among the various source lists:

               print_subset_chart( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );

           or

               print_subset_chart( { lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] } );

       •   Pretty-print a chart showing the equivalence relationships among the various source
           lists:

               print_equivalence_chart( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );

           or

               print_equivalence_chart( { lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] } );

       •   Determine in which (if any) of several lists a given string can be found.  Pass two
           array references, the first of which holds references to arrays holding the lists
           under consideration, and the second of which holds a single-item list consisting of
           the string being tested.

               @memb_arr = is_member_which(
                               [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
                               [ 'abel' ]
                           );

           or

               @memb_arr = is_member_which( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], # value is arrayref
                   item  => 'abel',                                 # value is string
               } );

           In list context, return a list of those indices in the function's argument list
           corresponding to lists holding the string being tested.  In the example above,
           @memb_arr will be:

               ( 0 )

           because 'abel' is found only in @Al which holds position 0 in the list of arguments
           passed to "is_member_which()".

       •   As with other List::Compare::Functional functions which return a list, you may wish
           the above function returned a reference to an array holding the list:

               $memb_arr_ref = is_member_which_ref(
                                   [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
                                   [ 'jerky' ]
                               );

           or

               $memb_arr_ref = is_member_which_ref( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], # value is arrayref
                   item  => 'jerky',                                # value is string
               } );

           In the example above, $memb_arr_ref will be:

               [ 3, 4 ]

           because 'jerky' is found in @Don and @Ed, which hold positions 3 and 4, respectively,
           in the list of arguments passed to "is_member_which()".

           Note:  functions "is_member_which()" and "is_member_which_ref" test only one string at
           a time and hence take only one element in the second array reference argument.  To
           test more than one string at a time see the next function, "are_members_which()".

       •   Determine in "which" (if any) of several lists one or more given strings can be found.
           Pass two array references, the first of which holds references to arrays holding the
           lists under consideration, and the second of which holds a list of the strings being
           tested.

               $memb_hash_ref = are_members_which(
                                    [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
                                    [ qw| abel baker fargo hilton zebra | ]
                                );

           or

               $memb_hash_ref = are_members_which( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],  # value is arrayref
                   items => [ qw| abel baker fargo hilton zebra | ], # value is arrayref
               } );

           The return valus is a reference to a hash of arrays.  In this hash, each element's
           value is a reference to an anonymous array whose elements are those indices in the
           argument list corresponding to lists holding the strings being tested.  In the two
           examples above, $memb_hash_ref will be:

               {
                    abel     => [ 0             ],
                    baker    => [ 0, 1          ],
                    fargo    => [ 0, 1, 2, 3, 4 ],
                    hilton   => [    1, 2       ],
                    zebra    => [               ],
               };

           Note:  "are_members_which()" tests more than one string at a time.  Hence, its second
           array reference argument can take more than one element.  "is_member_which()" and
           "is_member_which_ref()" each take only one element in their second array reference
           arguments.  "are_members_which()" returns a hash reference; the other functions return
           either a list or a reference to an array holding that list, depending on context.

       •   Determine whether a given string can be found in any of several lists.  Pass two array
           references, the first of which holds references to arrays holding the lists under
           consideration, and the second of which holds a single-item list of the string being
           tested.

               $found = is_member_any(
                               [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
                               [ 'abel' ]
                           );

           or

               $found = is_member_any( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], # value is arrayref
                   item  => 'abel',                                 # value is string
               } );

           The return value is 1 if a specified string can be found in any of the lists and 0 if
           not.  In the example above, $found will be 1 because "abel" is found in one or more of
           the lists passed as arguments to "is_member_any()".

       •   Determine whether a specified string or strings can be found in any of several lists.
           Pass two array references, the first of which holds references to arrays holding the
           lists under consideration, and the second of which holds a list of the strings being
           tested.

               $memb_hash_ref = are_members_any(
                                    [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
                                    [ qw| abel baker fargo hilton zebra | ]
                                );

           or

               $memb_hash_ref = are_members_any( {
                   lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],  # value is arrayref
                   items => [ qw| abel baker fargo hilton zebra | ], # value is arrayref
               } );

           The return value is a reference to a hash where an element's key is the string being
           tested and the element's value is 1 if the string can be found in any of the lists and
           0 if not.  In the example above, $memb_hash_ref will be:

               {
                    abel     => 1,
                    baker    => 1,
                    fargo    => 1,
                    hilton   => 1,
                    zebra    => 0,
               };

           "zebra"'s value is 0 because "zebra" is not found in any of the lists passed as
           arguments to "are_members_any()".

       •   Return current List::Compare::Functional version number:

               $vers = get_version;

   Comparing Lists Held in Seen-Hashes
       What is a seen-hash?  A seen-hash is a typical Perl implementation of a look-up table:  a
       hash where the value for a given element represents the number of times the element's key
       is observed in a list.  For the purposes of List::Compare::Functional, what is crucial is
       whether an item is observed in a list or not; how many times the item occurs in a list is,
       with one exception, irrelevant.  (That exception is the "get_bag()" function and its
       fraternal twin "get_bag_ref()".  In this case only, the key in each element of the seen-
       hash is placed in the bag the number of times indicated by the value of that element.)
       The value of an element in a List::Compare seen-hash must be a positive integer, but
       whether that integer is 1 or 1,000,001 is immaterial for all List::Compare::Functional
       functions except forming a bag.

       The two lists compared above were represented by arrays; references to those arrays were
       passed to the various List::Compare::Functional functions.  They could, however, have been
       represented by seen-hashes such as the following and passed in exactly the same manner to
       the various functions.

           %Llist = (
               abel   => 2,
               baker  => 1,
               camera => 1,
               delta  => 1,
               edward => 1,
               fargo  => 1,
               golfer => 1,
           );
           %Rlist = (
               baker  => 1,
               camera => 1,
               delta  => 2,
               edward => 1,
               fargo  => 1,
               golfer => 1,
               hilton => 1,
           );

           @intersection = get_intersection( [ \%Llist, \%Rlist ] );
           @union        = get_union(        [ \%Llist, \%Rlist ] );
           @complement   = get_complement(   [ \%Llist, \%Rlist ] );

       and so forth.

       To compare three or more lists simultaneously, provide the appropriate
       List::Compare::Functional function with a first array reference holding a list of three or
       more references to seen-hashes.  Thus,

           @union = get_intersection( [ \%Alpha, \%Beta, \%Gamma ] );

       The 'single hashref' format for List::Compare::Functional functions is also available when
       passing seen-hashes as arguments.  Examples:

           @intersection = get_intersection( {
               lists => [ \%Alpha, \%Beta, \%Gamma ],
           } );

           @Ronly = get_complement( {
               lists => [ \%Alpha, \%Beta, \%Gamma ],
               item  => 3,
           } );

           $LR = is_LsubsetR( {
               lists => [ \%Alpha, \%Beta, \%Gamma ],
               pair  => [ 4, 2 ],
           } );

           $memb_hash_ref = are_members_any( {
               lists => [ \%Alpha, \%Beta, \%Gamma ],
               items => [ qw| abel baker fargo hilton zebra | ],
           } );

   Faster Results with the Unsorted Option
       By default, List::Compare::Function functions return lists sorted in Perl's default ASCII-
       betical mode.  Sorting entails a performance cost, and if you do not need a sorted list
       and do not wish to pay this performance cost, you may call the following
       List::Compare::Function functions with the 'unsorted' option:

           @intersection = get_intersection(        '-u',  [ \@Llist, \@Rlist ] );
           @union        = get_union(               '-u',  [ \@Llist, \@Rlist ] );
           @Lonly        = get_unique(              '-u',  [ \@Llist, \@Rlist ] );
           @Ronly        = get_complement(          '-u',  [ \@Llist, \@Rlist ] );
           @LorRonly     = get_symmetric_difference('-u',  [ \@Llist, \@Rlist ] );
           @bag          = get_bag(                 '-u',  [ \@Llist, \@Rlist ] );

       For greater readability, the option may be spelled out:

           @intersection = get_intersection('--unsorted',  [ \@Llist, \@Rlist ] );

       or

           @intersection = get_intersection( {
               unsorted => 1,
               lists    => [ \@Llist, \@Rlist ],
           } );

       Should you need a reference to an unsorted list as the return value, you may call the
       unsorted option as follows:

           $intersection_ref = get_intersection_ref(
                                   '-u',         [ \@Llist, \@Rlist ] );
           $intersection_ref = get_intersection_ref(
                                   '--unsorted', [ \@Llist, \@Rlist ] );

DISCUSSION

   General Comments
       List::Compare::Functional is a non-object-oriented implementation of very common Perl code
       used to determine interesting relationships between two or more lists at a time.
       List::Compare::Functional is based on the same author's List::Compare module found in the
       same CPAN distribution.  List::Compare::Functional is closely modeled on the
       ''Accelerated'' mode in List::Compare.

       For a discussion of the antecedents of this module, see the discussion of the history and
       development of this module in the documentation to List::Compare.

   List::Compare::Functional's Export Tag Groups
       By default, List::Compare::Functional exports no functions.  You may import individual
       functions into your main package but may find it more convenient to import via export tag
       groups.  Four such groups are currently defined:

           use List::Compare::Functional qw(:main)
           use List::Compare::Functional qw(:mainrefs)
           use List::Compare::Functional qw(:originals)
           use List::Compare::Functional qw(:aliases)

       •   Tag group ":main" includes what, in the author's opinion, are the six
           List::Compare::Functional subroutines mostly likely to be used:

               get_intersection()
               get_union()
               get_unique()
               get_complement()
               get_symmetric_difference()
               is_LsubsetR()

       •   Tag group ":mainrefs" includes five of the six subroutines found in ":main" -- all
           except "is_LsubsetR()" -- in the form in which they return references to arrays rather
           than arrays proper:

               get_intersection_ref()
               get_union_ref()
               get_unique_ref()
               get_complement_ref()
               get_symmetric_difference_ref()

       •   Tag group ":originals" includes all List::Compare::Functional subroutines in their
           'original' form, i.e., no aliases for those subroutines:

               get_intersection
               get_intersection_ref
               get_union
               get_union_ref
               get_unique
               get_unique_ref
               get_unique_all
               get_complement
               get_complement_ref
               get_complement_all
               get_symmetric_difference
               get_symmetric_difference_ref
               get_shared
               get_shared_ref
               get_nonintersection
               get_nonintersection_ref
               is_LsubsetR
               is_RsubsetL
               is_LequivalentR
               is_LdisjointR
               is_member_which
               is_member_which_ref
               are_members_which
               is_member_any
               are_members_any
               print_subset_chart
               print_equivalence_chart
               get_bag
               get_bag_ref

       •   Tag group ":aliases" contains all List::Compare::Functional subroutines which are
           aliases for subroutines found in tag group ":originals".  These are provided simply
           for less typing.

               get_symdiff
               get_symdiff_ref
               is_LeqvlntR

   April 2004 Change of Interface
       Note:  You can skip this section unless you used List::Compare::Functional prior to the
       release of Version 0.25 in April 2004.

       Version 0.25 initiated a significant change in the interface to this module's various
       functions.  In order to be able to accommodate comparisons among more than two lists, it
       was necessary to change the type of arguments passed to the various functions.  Whereas
       previously a typical List::Compare::Functional function would be called like this:

           @intersection = get_intersection( \@Llist, \@Rlist ); # SUPERSEDED

       ... now the references to the lists being compared must now be placed within a wrapper
       array (anonymous or named), a reference to which is now passed to the function, like so:

           @intersection = get_intersection( [ \@Llist, \@Rlist ] );

       ... or, alternatively:

           @to_be_compared = (\@Llist, \@Rlist);
           @intersection = get_intersection( \@to_be_compared );

       In a similar manner, List::Compare::Functional functions could previously take arguments
       in the form of references to 'seen-hashes' instead of references to arrays:

           @intersection = get_intersection( \%h0, \%h1 );

       (See above for discussion of seen-hashes.)  Now, those references to seen-hashes must be
       placed within a wrapper array (anonymous or named), a reference to which is passed to the
       function, like so:

           @intersection = get_intersection( [ \%h0, \%h1 ] );

       Also, in a similar manner, some List::Compare::Functional functions previously took
       arguments in addition to the lists being compared.  These arguments were simply passed as
       scalars, like this:

           @memb_arr = is_member_which(\@Llist, \@Rlist, 'abel');

       Now these arguments must also be placed within a wrapper array (anonymous or named), a
       reference to which is now passed to the function, like so:

           @memb_arr = is_member_which( [ \@Llist, \@Rlist ], [ 'abel' ] );

       ... or, alternatively:

           @to_be_compared = (\@Llist, \@Rlist);
           @opts = ( 'abel' );
           @memb_arr = is_member_which( \@to_be_compared, \@opts );

       As in previous versions, for a speed boost the user may provide the '-u' or '--unsorted'
       option as the first argument to some List::Compare::Functional functions.  Using this
       option, the "get_intersection()" function above would appear as:

           @intersection = get_intersection( '-u', [ \@Llist, \@Rlist ] );

       ... or, alternatively:

           @intersection = get_intersection( '--unsorted', [ \@Llist, \@Rlist ] );

       The arguments to any List::Compare::Functional function will therefore consist possibly of
       the unsorted option, and then of either one or two references to arrays, the first of
       which is a reference to an array of arrays or an array of seen-hashes.

AUTHOR

       James E. Keenan (jkeenan@cpan.org).  When sending correspondence, please include
       'List::Compare::Functional' or 'List-Compare-Functional' in your subject line.

       Creation date:  May 20, 2002.  Last modification date:  June 07, 2008.  Copyright (c)
       2002-08 James E. Keenan.  United States.  All rights reserved.  This is free software and
       may be distributed under the same terms as Perl itself.