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

NAME

6       List::Compare - Compare elements of two or more lists
7

VERSION

9       This document refers to version 0.55 of List::Compare.  This version
10       was released August 16 2020.
11

SYNOPSIS

13       The bare essentials:
14
15           @Llist = qw(abel abel baker camera delta edward fargo golfer);
16           @Rlist = qw(baker camera delta delta edward fargo golfer hilton);
17
18           $lc = List::Compare->new(\@Llist, \@Rlist);
19
20           @intersection = $lc->get_intersection;
21           @union = $lc->get_union;
22
23       ... and so forth.
24

DISCUSSION: Modes and Methods

26   Regular Case:  Compare Two Lists
27       ·   Constructor:  "new()"
28
29           Create a List::Compare object.  Put the two lists into arrays
30           (named or anonymous) and pass references to the arrays to the
31           constructor.
32
33               @Llist = qw(abel abel baker camera delta edward fargo golfer);
34               @Rlist = qw(baker camera delta delta edward fargo golfer hilton);
35
36               $lc = List::Compare->new(\@Llist, \@Rlist);
37
38           By default, List::Compare's methods return lists which are sorted
39           using Perl's default "sort" mode:  ASCII-betical sorting.  Should
40           you not need to have these lists sorted, you may achieve a speed
41           boost by constructing the List::Compare object with the unsorted
42           option:
43
44               $lc = List::Compare->new('-u', \@Llist, \@Rlist);
45
46           or
47
48               $lc = List::Compare->new('--unsorted', \@Llist, \@Rlist);
49
50       ·   Alternative Constructor
51
52           If you prefer a more explicit delineation of the types of arguments
53           passed to a function, you may use this 'single hashref' kind of
54           constructor to build a List::Compare object:
55
56               $lc = List::Compare->new( { lists => [\@Llist, \@Rlist] } );
57
58           or
59
60               $lc = List::Compare->new( {
61                   lists    => [\@Llist, \@Rlist],
62                   unsorted => 1,
63               } );
64
65       ·   "get_intersection()"
66
67           Get those items which appear at least once in both lists (their
68           intersection).
69
70               @intersection = $lc->get_intersection;
71
72       ·   "get_union()"
73
74           Get those items which appear at least once in either list (their
75           union).
76
77               @union = $lc->get_union;
78
79       ·   "get_unique()"
80
81           Get those items which appear (at least once) only in the first
82           list.
83
84               @Lonly = $lc->get_unique;
85               @Lonly = $lc->get_Lonly;    # alias
86
87       ·   "get_complement()"
88
89           Get those items which appear (at least once) only in the second
90           list.
91
92               @Ronly = $lc->get_complement;
93               @Ronly = $lc->get_Ronly;            # alias
94
95       ·   "get_symmetric_difference()"
96
97           Get those items which appear at least once in either the first or
98           the second list, but not both.
99
100               @LorRonly = $lc->get_symmetric_difference;
101               @LorRonly = $lc->get_symdiff;       # alias
102               @LorRonly = $lc->get_LorRonly;      # alias
103
104       ·   "get_bag()"
105
106           Make a bag of all those items in both lists.  The bag differs from
107           the union of the two lists in that it holds as many copies of
108           individual elements as appear in the original lists.
109
110               @bag = $lc->get_bag;
111
112       ·   Return references rather than lists
113
114           An alternative approach to the above methods:  If you do not
115           immediately require an array as the return value of the method
116           call, but simply need a reference to an (anonymous) array, use one
117           of the following parallel methods:
118
119               $intersection_ref = $lc->get_intersection_ref;
120               $union_ref        = $lc->get_union_ref;
121               $Lonly_ref        = $lc->get_unique_ref;
122               $Lonly_ref        = $lc->get_Lonly_ref;                 # alias
123               $Ronly_ref        = $lc->get_complement_ref;
124               $Ronly_ref        = $lc->get_Ronly_ref;                 # alias
125               $LorRonly_ref     = $lc->get_symmetric_difference_ref;
126               $LorRonly_ref     = $lc->get_symdiff_ref;               # alias
127               $LorRonly_ref     = $lc->get_LorRonly_ref;              # alias
128               $bag_ref          = $lc->get_bag_ref;
129
130       ·   "is_LsubsetR()"
131
132           Return a true value if the first argument passed to the constructor
133           ('L' for 'left') is a subset of the second argument passed to the
134           constructor ('R' for 'right').
135
136               $LR = $lc->is_LsubsetR;
137
138           Return a true value if R is a subset of L.
139
140               $RL = $lc->is_RsubsetL;
141
142       ·   "is_LequivalentR()"
143
144           Return a true value if the two lists passed to the constructor are
145           equivalent, i.e. if every element in the left-hand list ('L')
146           appears at least once in the right-hand list ('R') and vice versa.
147
148               $eqv = $lc->is_LequivalentR;
149               $eqv = $lc->is_LeqvlntR;            # alias
150
151       ·   "is_LdisjointR()"
152
153           Return a true value if the two lists passed to the constructor are
154           disjoint, i.e. if the two lists have zero elements in common (or,
155           what is the same thing, if their intersection is an empty set).
156
157               $disj = $lc->is_LdisjointR;
158
159       ·   "print_subset_chart()"
160
161           Pretty-print a chart showing whether one list is a subset of the
162           other.
163
164               $lc->print_subset_chart;
165
166       ·   "print_equivalence_chart()"
167
168           Pretty-print a chart showing whether the two lists are equivalent
169           (same elements found at least once in both).
170
171               $lc->print_equivalence_chart;
172
173       ·   "is_member_which()"
174
175           Determine in which (if any) of the lists passed to the constructor
176           a given string can be found.  In list context, return a list of
177           those indices in the constructor's argument list corresponding to
178           lists holding the string being tested.
179
180               @memb_arr = $lc->is_member_which('abel');
181
182           In the example above, @memb_arr will be:
183
184               ( 0 )
185
186           because 'abel' is found only in @Al which holds position 0 in the
187           list of arguments passed to "new()".
188
189           In scalar context, the return value is the number of lists passed
190           to the constructor in which a given string is found.
191
192           As with other List::Compare methods which return a list, you may
193           wish the above method returned a (scalar) reference to an array
194           holding the list:
195
196               $memb_arr_ref = $lc->is_member_which_ref('baker');
197
198           In the example above, $memb_arr_ref will be:
199
200               [ 0, 1 ]
201
202           because 'baker' is found in @Llist and @Rlist, which hold positions
203           0 and 1, respectively, in the list of arguments passed to "new()".
204
205           Note:  methods "is_member_which()" and "is_member_which_ref" test
206           only one string at a time and hence take only one argument.  To
207           test more than one string at a time see the next method,
208           "are_members_which()".
209
210       ·   "are_members_which()"
211
212           Determine in which (if any) of the lists passed to the constructor
213           one or more given strings can be found.  The strings to be tested
214           are placed in an array (named or anonymous); a reference to that
215           array is passed to the method.
216
217               $memb_hash_ref =
218                   $lc->are_members_which([ qw| abel baker fargo hilton zebra | ]);
219
220           Note:  In versions of List::Compare prior to 0.25 (April 2004), the
221           strings to be tested could be passed as a flat list.  This is no
222           longer possible; the argument must now be a reference to an array.
223
224           The return value is a reference to a hash of arrays.  The key for
225           each element in this hash is the string being tested.  Each
226           element's value is a reference to an anonymous array whose elements
227           are those indices in the constructor's argument list corresponding
228           to lists holding the strings being tested.  In the examples above,
229           $memb_hash_ref will be:
230
231               {
232                    abel     => [ 0    ],
233                    baker    => [ 0, 1 ],
234                    fargo    => [ 0, 1 ],
235                    hilton   => [    1 ],
236                    zebra    => [      ],
237               };
238
239           Note:  "are_members_which()" can take more than one argument;
240           "is_member_which()" and "is_member_which_ref()" each take only one
241           argument.  Unlike those two methods, "are_members_which()" returns
242           a hash reference.
243
244       ·   "is_member_any()"
245
246           Determine whether a given string can be found in any of the lists
247           passed as arguments to the constructor.  Return 1 if a specified
248           string can be found in any of the lists and 0 if not.
249
250               $found = $lc->is_member_any('abel');
251
252           In the example above, $found will be 1 because 'abel' is found in
253           one or more of the lists passed as arguments to "new()".
254
255       ·   "are_members_any()"
256
257           Determine whether a specified string or strings can be found in any
258           of the lists passed as arguments to the constructor.  The strings
259           to be tested are placed in an array (named or anonymous); a
260           reference to that array is passed to "are_members_any".
261
262               $memb_hash_ref = $lc->are_members_any([ qw| abel baker fargo hilton zebra | ]);
263
264           Note:  In versions of List::Compare prior to 0.25 (April 2004), the
265           strings to be tested could be passed as a flat list.  This is no
266           longer possible; the argument must now be a reference to an array.
267
268           The return value is a reference to a hash where an element's key is
269           the string being tested and the element's value is 1 if the string
270           can be found in any of the lists and 0 if not.  In the examples
271           above, $memb_hash_ref will be:
272
273               {
274                    abel     => 1,
275                    baker    => 1,
276                    fargo    => 1,
277                    hilton   => 1,
278                    zebra    => 0,
279               };
280
281           "zebra"'s value is 0 because "zebra" is not found in either of the
282           lists passed as arguments to "new()".
283
284       ·   "get_version()"
285
286           Return current List::Compare version number.
287
288               $vers = $lc->get_version;
289
290   Accelerated Case:  When User Only Wants a Single Comparison
291       ·   Constructor "new()"
292
293           If you are certain that you will only want the results of a single
294           comparison, computation may be accelerated by passing '-a' or
295           "'--accelerated" as the first argument to the constructor.
296
297               @Llist = qw(abel abel baker camera delta edward fargo golfer);
298               @Rlist = qw(baker camera delta delta edward fargo golfer hilton);
299
300               $lca = List::Compare->new('-a', \@Llist, \@Rlist);
301
302           or
303
304               $lca = List::Compare->new('--accelerated', \@Llist, \@Rlist);
305
306           As with List::Compare's Regular case, should you not need to have a
307           sorted list returned by an accelerated List::Compare method, you
308           may achieve a speed boost by constructing the accelerated
309           List::Compare object with the unsorted option:
310
311               $lca = List::Compare->new('-u', '-a', \@Llist, \@Rlist);
312
313           or
314
315               $lca = List::Compare->new('--unsorted', '--accelerated', \@Llist, \@Rlist);
316
317       ·   Alternative Constructor
318
319           You may use the 'single hashref' constructor format to build a
320           List::Compare object calling for the Accelerated mode:
321
322               $lca = List::Compare->new( {
323                   lists    => [\@Llist, \@Rlist],
324                   accelerated => 1,
325               } );
326
327           or
328
329               $lca = List::Compare->new( {
330                   lists    => [\@Llist, \@Rlist],
331                   accelerated => 1,
332                   unsorted => 1,
333               } );
334
335       ·   Methods
336
337           All the comparison methods available in the Regular case are
338           available to you in the Accelerated case as well.
339
340               @intersection     = $lca->get_intersection;
341               @union            = $lca->get_union;
342               @Lonly            = $lca->get_unique;
343               @Ronly            = $lca->get_complement;
344               @LorRonly         = $lca->get_symmetric_difference;
345               @bag              = $lca->get_bag;
346               $intersection_ref = $lca->get_intersection_ref;
347               $union_ref        = $lca->get_union_ref;
348               $Lonly_ref        = $lca->get_unique_ref;
349               $Ronly_ref        = $lca->get_complement_ref;
350               $LorRonly_ref     = $lca->get_symmetric_difference_ref;
351               $bag_ref          = $lca->get_bag_ref;
352               $LR               = $lca->is_LsubsetR;
353               $RL               = $lca->is_RsubsetL;
354               $eqv              = $lca->is_LequivalentR;
355               $disj             = $lca->is_LdisjointR;
356                                   $lca->print_subset_chart;
357                                   $lca->print_equivalence_chart;
358               @memb_arr         = $lca->is_member_which('abel');
359               $memb_arr_ref     = $lca->is_member_which_ref('baker');
360               $memb_hash_ref    = $lca->are_members_which(
361                                       [ qw| abel baker fargo hilton zebra | ]);
362               $found            = $lca->is_member_any('abel');
363               $memb_hash_ref    = $lca->are_members_any(
364                                       [ qw| abel baker fargo hilton zebra | ]);
365               $vers             = $lca->get_version;
366
367           All the aliases for methods available in the Regular case are
368           available to you in the Accelerated case as well.
369
370   Multiple Case:  Compare Three or More Lists
371       ·   Constructor "new()"
372
373           Create a List::Compare object.  Put each list into an array and
374           pass references to the arrays to the constructor.
375
376               @Al     = qw(abel abel baker camera delta edward fargo golfer);
377               @Bob    = qw(baker camera delta delta edward fargo golfer hilton);
378               @Carmen = qw(fargo golfer hilton icon icon jerky kappa);
379               @Don    = qw(fargo icon jerky);
380               @Ed     = qw(fargo icon icon jerky);
381
382               $lcm = List::Compare->new(\@Al, \@Bob, \@Carmen, \@Don, \@Ed);
383
384           As with List::Compare's Regular case, should you not need to have a
385           sorted list returned by a List::Compare method, you may achieve a
386           speed boost by constructing the object with the unsorted option:
387
388               $lcm = List::Compare->new('-u', \@Al, \@Bob, \@Carmen, \@Don, \@Ed);
389
390           or
391
392               $lcm = List::Compare->new('--unsorted', \@Al, \@Bob, \@Carmen, \@Don, \@Ed);
393
394       ·   Alternative Constructor
395
396           You may use the 'single hashref' constructor format to build a
397           List::Compare object to process three or more lists at once:
398
399               $lcm = List::Compare->new( {
400                   lists    => [\@Al, \@Bob, \@Carmen, \@Don, \@Ed],
401               } );
402
403           or
404
405               $lcm = List::Compare->new( {
406                   lists    => [\@Al, \@Bob, \@Carmen, \@Don, \@Ed],
407                   unsorted => 1,
408               } );
409
410       ·   Multiple Mode Methods Analogous to Regular and Accelerated Mode
411           Methods
412
413           Each List::Compare method available in the Regular and Accelerated
414           cases has an analogue in the Multiple case.  However, the results
415           produced usually require more careful specification.
416
417           Note:  Certain of the following methods available in
418           List::Compare's Multiple mode take optional numerical arguments
419           where those numbers represent the index position of a particular
420           list in the list of arguments passed to the constructor.  To
421           specify this index position correctly,
422
423           ·   start the count at 0 (as is customary with Perl array indices);
424               and
425
426           ·   do not count any unsorted option ('-u' or '--unsorted')
427               preceding the array references in the constructor's own
428               argument list.
429
430           Example:
431
432               $lcmex = List::Compare->new('--unsorted', \@alpha, \@beta, \@gamma);
433
434           For the purpose of supplying a numerical argument to a method which
435           optionally takes such an argument, '--unsorted' is skipped, @alpha
436           is 0, @beta is 1, and so forth.
437
438           ·   "get_intersection()"
439
440               Get those items found in each of the lists passed to the
441               constructor (their intersection):
442
443                   @intersection = $lcm->get_intersection;
444
445           ·   "get_union()"
446
447               Get those items found in any of the lists passed to the
448               constructor (their union):
449
450                   @union = $lcm->get_union;
451
452           ·   "get_unique()"
453
454               To get those items which appear only in one particular list,
455               provide "get_unique()" with that list's index position in the
456               list of arguments passed to the constructor (not counting any
457               '-u' or '--unsorted' option).
458
459               Example:  @Carmen has index position 2 in the constructor's @_.
460               To get elements unique to @Carmen:
461
462                   @Lonly = $lcm->get_unique(2);
463
464               If no index position is passed to "get_unique()" it will
465               default to 0 and report items unique to the first list passed
466               to the constructor.
467
468           ·   "get_complement()"
469
470               To get those items which appear in any list other than one
471               particular list, provide "get_complement()" with that list's
472               index position in the list of arguments passed to the
473               constructor (not counting any '-u' or '--unsorted' option).
474
475               Example:  @Don has index position 3 in the constructor's @_.
476               To get elements not found in @Don:
477
478                   @Ronly = $lcm->get_complement(3);
479
480               If no index position is passed to "get_complement()" it will
481               default to 0 and report items found in any list other than the
482               first list passed to the constructor.
483
484           ·   "get_symmetric_difference()"
485
486               Get those items each of which appears in only one of the lists
487               passed to the constructor (their symmetric_difference);
488
489                   @LorRonly = $lcm->get_symmetric_difference;
490
491           ·   "get_bag()"
492
493               Make a bag of all items found in any list.  The bag differs
494               from the lists' union in that it holds as many copies of
495               individual elements as appear in the original lists.
496
497                   @bag = $lcm->get_bag;
498
499           ·   Return reference instead of list
500
501               An alternative approach to the above methods:  If you do not
502               immediately require an array as the return value of the method
503               call, but simply need a reference to an array, use one of the
504               following parallel methods:
505
506                   $intersection_ref = $lcm->get_intersection_ref;
507                   $union_ref        = $lcm->get_union_ref;
508                   $Lonly_ref        = $lcm->get_unique_ref(2);
509                   $Ronly_ref        = $lcm->get_complement_ref(3);
510                   $LorRonly_ref     = $lcm->get_symmetric_difference_ref;
511                   $bag_ref          = $lcm->get_bag_ref;
512
513           ·   "is_LsubsetR()"
514
515               To determine whether one particular list is a subset of another
516               list passed to the constructor, provide "is_LsubsetR()" with
517               the index position of the presumed subset (ignoring any
518               unsorted option), followed by the index position of the
519               presumed superset.
520
521               Example:  To determine whether @Ed is a subset of @Carmen,
522               call:
523
524                   $LR = $lcm->is_LsubsetR(4,2);
525
526               A true value (1) is returned if the left-hand list is a subset
527               of the right-hand list; a false value (0) is returned
528               otherwise.
529
530               If no arguments are passed, "is_LsubsetR()" defaults to "(0,1)"
531               and compares the first two lists passed to the constructor.
532
533           ·   "is_LequivalentR()"
534
535               To determine whether any two particular lists are equivalent to
536               each other, provide "is_LequivalentR" with their index
537               positions in the list of arguments passed to the constructor
538               (ignoring any unsorted option).
539
540               Example:  To determine whether @Don and @Ed are equivalent,
541               call:
542
543                   $eqv = $lcm->is_LequivalentR(3,4);
544
545               A true value (1) is returned if the lists are equivalent; a
546               false value (0) otherwise.
547
548               If no arguments are passed, "is_LequivalentR" defaults to
549               "(0,1)" and compares the first two lists passed to the
550               constructor.
551
552           ·   "is_LdisjointR()"
553
554               To determine whether any two particular lists are disjoint from
555               each other (i.e., have no members in common), provide
556               "is_LdisjointR" with their index positions in the list of
557               arguments passed to the constructor (ignoring any unsorted
558               option).
559
560               Example:  To determine whether @Don and @Ed are disjoint, call:
561
562                   $disj = $lcm->is_LdisjointR(3,4);
563
564               A true value (1) is returned if the lists are equivalent; a
565               false value (0) otherwise.
566
567               If no arguments are passed, "is_LdisjointR" defaults to "(0,1)"
568               and compares the first two lists passed to the constructor.
569
570           ·   "print_subset_chart()"
571
572               Pretty-print a chart showing the subset relationships among the
573               various source lists:
574
575                   $lcm->print_subset_chart;
576
577           ·   "print_equivalence_chart()"
578
579               Pretty-print a chart showing the equivalence relationships
580               among the various source lists:
581
582                   $lcm->print_equivalence_chart;
583
584           ·   "is_member_which()"
585
586               Determine in which (if any) of the lists passed to the
587               constructor a given string can be found.  In list context,
588               return a list of those indices in the constructor's argument
589               list (ignoring any unsorted option) corresponding to i lists
590               holding the string being tested.
591
592                   @memb_arr = $lcm->is_member_which('abel');
593
594               In the example above, @memb_arr will be:
595
596                   ( 0 )
597
598               because 'abel' is found only in @Al which holds position 0 in
599               the list of arguments passed to "new()".
600
601           ·   "is_member_which_ref()"
602
603               As with other List::Compare methods which return a list, you
604               may wish the above method returned a (scalar) reference to an
605               array holding the list:
606
607                   $memb_arr_ref = $lcm->is_member_which_ref('jerky');
608
609               In the example above, $memb_arr_ref will be:
610
611                   [ 3, 4 ]
612
613               because 'jerky' is found in @Don and @Ed, which hold positions
614               3 and 4, respectively, in the list of arguments passed to
615               "new()".
616
617               Note:  methods "is_member_which()" and "is_member_which_ref"
618               test only one string at a time and hence take only one
619               argument.  To test more than one string at a time see the next
620               method, "are_members_which()".
621
622           ·   "are_members_which()"
623
624               Determine in "which" (if any) of the lists passed to the
625               constructor one or more given strings can be found.  The
626               strings to be tested are placed in an anonymous array, a
627               reference to which is passed to the method.
628
629                   $memb_hash_ref =
630                       $lcm->are_members_which([ qw| abel baker fargo hilton zebra | ]);
631
632               Note:  In versions of List::Compare prior to 0.25 (April 2004),
633               the strings to be tested could be passed as a flat list.  This
634               is no longer possible; the argument must now be a reference to
635               an anonymous array.
636
637               The return value is a reference to a hash of arrays.  The key
638               for each element in this hash is the string being tested.  Each
639               element's value is a reference to an anonymous array whose
640               elements are those indices in the constructor's argument list
641               corresponding to lists holding the strings being tested.
642
643               In the two examples above, $memb_hash_ref will be:
644
645                   {
646                        abel     => [ 0             ],
647                        baker    => [ 0, 1          ],
648                        fargo    => [ 0, 1, 2, 3, 4 ],
649                        hilton   => [    1, 2       ],
650                        zebra    => [               ],
651                   };
652
653               Note:  "are_members_which()" can take more than one argument;
654               "is_member_which()" and "is_member_which_ref()" each take only
655               one argument.  "are_members_which()" returns a hash reference;
656               the other methods return either a list or a reference to an
657               array holding that list, depending on context.
658
659           ·   "is_member_any()"
660
661               Determine whether a given string can be found in any of the
662               lists passed as arguments to the constructor.
663
664                   $found = $lcm->is_member_any('abel');
665
666               Return 1 if a specified string can be found in any of the lists
667               and 0 if not.
668
669               In the example above, $found will be 1 because 'abel' is found
670               in one or more of the lists passed as arguments to "new()".
671
672           ·   "are_members_any()"
673
674               Determine whether a specified string or strings can be found in
675               any of the lists passed as arguments to the constructor.  The
676               strings to be tested are placed in an array (anonymous or
677               named), a reference to which is passed to the method.
678
679                   $memb_hash_ref = $lcm->are_members_any([ qw| abel baker fargo hilton zebra | ]);
680
681               Note:  In versions of List::Compare prior to 0.25 (April 2004),
682               the strings to be tested could be passed as a flat list.  This
683               is no longer possible; the argument must now be a reference to
684               an anonymous array.
685
686               The return value is a reference to a hash where an element's
687               key is the string being tested and the element's value is 1 if
688               the string can be found in "any" of the lists and 0 if not.  In
689               the two examples above, $memb_hash_ref will be:
690
691                   {
692                        abel     => 1,
693                        baker    => 1,
694                        fargo    => 1,
695                        hilton   => 1,
696                        zebra    => 0,
697                   };
698
699               "zebra"'s value will be 0 because "zebra" is not found in any
700               of the lists passed as arguments to "new()".
701
702           ·   "get_version()"
703
704               Return current List::Compare version number:
705
706                   $vers = $lcm->get_version;
707
708       ·   Multiple Mode Methods Not Analogous to Regular and Accelerated Mode
709           Methods
710
711           ·   "get_nonintersection()"
712
713               Get those items found in any of the lists passed to the
714               constructor which do not appear in all of the lists (i.e., all
715               items except those found in the intersection of the lists):
716
717                   @nonintersection = $lcm->get_nonintersection;
718
719           ·   "get_shared()"
720
721               Get those items which appear in more than one of the lists
722               passed to the constructor (i.e., all items except those found
723               in their symmetric difference);
724
725                   @shared = $lcm->get_shared;
726
727           ·   "get_nonintersection_ref()"
728
729               If you only need a reference to an array as a return value
730               rather than a full array, use the following alternative
731               methods:
732
733                   $nonintersection_ref = $lcm->get_nonintersection_ref;
734                   $shared_ref = $lcm->get_shared_ref;
735
736           ·   "get_unique_all()"
737
738               Get a reference to an array of array references where each of
739               the interior arrays holds the list of those items unique to the
740               list passed to the constructor with the same index position.
741
742                   $unique_all_ref = $lcm->get_unique_all();
743
744               In the example above, $unique_all_ref will hold:
745
746                   [
747                       [ qw| abel | ],
748                       [ ],
749                       [ qw| jerky | ],
750                       [ ],
751                       [ ],
752                   ]
753
754           ·   "get_complement_all()"
755
756               Get a reference to an array of array references where each of
757               the interior arrays holds the list of those items in the
758               complement to the list passed to the constructor with the same
759               index position.
760
761                   $complement_all_ref = $lcm->get_complement_all();
762
763               In the example above, $complement_all_ref will hold:
764
765                   [
766                       [ qw| hilton icon jerky | ],
767                       [ qw| abel icon jerky | ],
768                       [ qw| abel baker camera delta edward | ],
769                       [ qw| abel baker camera delta edward jerky | ],
770                       [ qw| abel baker camera delta edward jerky | ],
771                   ]
772
773   Multiple Accelerated Case:  Compare Three or More Lists but Request Only a
774       Single Comparison among the Lists
775       ·   Constructor "new()"
776
777           If you are certain that you will only want the results of a single
778           comparison among three or more lists, computation may be
779           accelerated by passing '-a' or "'--accelerated" as the first
780           argument to the constructor.
781
782               @Al     = qw(abel abel baker camera delta edward fargo golfer);
783               @Bob    = qw(baker camera delta delta edward fargo golfer hilton);
784               @Carmen = qw(fargo golfer hilton icon icon jerky kappa);
785               @Don    = qw(fargo icon jerky);
786               @Ed     = qw(fargo icon icon jerky);
787
788               $lcma = List::Compare->new('-a',
789                           \@Al, \@Bob, \@Carmen, \@Don, \@Ed);
790
791           As with List::Compare's other cases, should you not need to have a
792           sorted list returned by a List::Compare method, you may achieve a
793           speed boost by constructing the object with the unsorted option:
794
795               $lcma = List::Compare->new('-u', '-a',
796                           \@Al, \@Bob, \@Carmen, \@Don, \@Ed);
797
798           or
799
800               $lcma = List::Compare->new('--unsorted', '--accelerated',
801                           \@Al, \@Bob, \@Carmen, \@Don, \@Ed);
802
803           As was the case with List::Compare's Multiple mode, do not count
804           the unsorted option ('-u' or '--unsorted') or the accelerated
805           option ('-a' or '--accelerated') when determining the index
806           position of a particular list in the list of array references
807           passed to the constructor.
808
809           Example:
810
811               $lcmaex = List::Compare->new('--unsorted', '--accelerated',
812                              \@alpha, \@beta, \@gamma);
813
814       ·   Alternative Constructor
815
816           The 'single hashref' format may be used to construct a
817           List::Compare object which calls for accelerated processing of
818           three or more lists at once:
819
820               $lcmaex = List::Compare->new( {
821                   accelerated => 1,
822                   lists       => [\@alpha, \@beta, \@gamma],
823               } );
824
825           or
826
827               $lcmaex = List::Compare->new( {
828                   unsorted    => 1,
829                   accelerated => 1,
830                   lists       => [\@alpha, \@beta, \@gamma],
831               } );
832
833       ·   Methods
834
835           For the purpose of supplying a numerical argument to a method which
836           optionally takes such an argument, '--unsorted' and
837           "'--accelerated" are skipped, @alpha is 0, @beta is 1, and so
838           forth.  To get a list of those items unique to @gamma, you would
839           call:
840
841               @gamma_only = $lcmaex->get_unique(2);
842
843   Passing Seen-hashes to the Constructor Instead of Arrays
844       ·   When Seen-Hashes Are Already Available to You
845
846           Suppose that in a particular Perl program, you had to do extensive
847           munging of data from an external source and that, once you had
848           correctly parsed a line of data, it was easier to assign that datum
849           to a hash than to an array.  More specifically, suppose that you
850           used each datum as the key to an element of a lookup table in the
851           form of a seen-hash:
852
853              my %Llist = (
854                  abel     => 2,
855                  baker    => 1,
856                  camera   => 1,
857                  delta    => 1,
858                  edward   => 1,
859                  fargo    => 1,
860                  golfer   => 1,
861              );
862
863              my %Rlist = (
864                  baker    => 1,
865                  camera   => 1,
866                  delta    => 2,
867                  edward   => 1,
868                  fargo    => 1,
869                  golfer   => 1,
870                  hilton   => 1,
871              );
872
873           In other words, suppose it was more convenient to compute a lookup
874           table implying a list than to compute that list explicitly.
875
876           Since in almost all cases List::Compare takes the elements in the
877           arrays passed to its constructor and internally assigns them to
878           elements in a seen-hash, why shouldn't you be able to pass
879           (references to) seen-hashes directly to the constructor and avoid
880           unnecessary array assignments before the constructor is called?
881
882       ·   Constructor "new()"
883
884           You can now do so:
885
886               $lcsh = List::Compare->new(\%Llist, \%Rlist);
887
888       ·   Methods
889
890           All of List::Compare's output methods are supported without further
891           modification when references to seen-hashes are passed to the
892           constructor.
893
894               @intersection         = $lcsh->get_intersection;
895               @union                = $lcsh->get_union;
896               @Lonly                = $lcsh->get_unique;
897               @Ronly                = $lcsh->get_complement;
898               @LorRonly             = $lcsh->get_symmetric_difference;
899               @bag                  = $lcsh->get_bag;
900               $intersection_ref     = $lcsh->get_intersection_ref;
901               $union_ref            = $lcsh->get_union_ref;
902               $Lonly_ref            = $lcsh->get_unique_ref;
903               $Ronly_ref            = $lcsh->get_complement_ref;
904               $LorRonly_ref         = $lcsh->get_symmetric_difference_ref;
905               $bag_ref              = $lcsh->get_bag_ref;
906               $LR                   = $lcsh->is_LsubsetR;
907               $RL                   = $lcsh->is_RsubsetL;
908               $eqv                  = $lcsh->is_LequivalentR;
909               $disj                 = $lcsh->is_LdisjointR;
910                                       $lcsh->print_subset_chart;
911                                       $lcsh->print_equivalence_chart;
912               @memb_arr             = $lsch->is_member_which('abel');
913               $memb_arr_ref         = $lsch->is_member_which_ref('baker');
914               $memb_hash_ref        = $lsch->are_members_which(
915                                           [ qw| abel baker fargo hilton zebra | ]);
916               $found                = $lsch->is_member_any('abel');
917               $memb_hash_ref        = $lsch->are_members_any(
918                                           [ qw| abel baker fargo hilton zebra | ]);
919               $vers                 = $lcsh->get_version;
920               $unique_all_ref       = $lcsh->get_unique_all();
921               $complement_all_ref   = $lcsh->get_complement_all();
922
923       ·   Accelerated Mode and Seen-Hashes
924
925           To accelerate processing when you want only a single comparison
926           among two or more lists, you can pass '-a' or "'--accelerated" to
927           the constructor before passing references to seen-hashes.
928
929               $lcsha = List::Compare->new('-a', \%Llist, \%Rlist);
930
931           To compare three or more lists simultaneously, pass three or more
932           references to seen-hashes.  Thus,
933
934               $lcshm = List::Compare->new(\%Alpha, \%Beta, \%Gamma);
935
936           will generate meaningful comparisons of three or more lists
937           simultaneously.
938
939       ·   Unsorted Results and Seen-Hashes
940
941           If you do not need sorted lists returned, pass '-u' or "--unsorted"
942           to the constructor before passing references to seen-hashes.
943
944               $lcshu  = List::Compare->new('-u', \%Llist, \%Rlist);
945               $lcshau = List::Compare->new('-u', '-a', \%Llist, \%Rlist);
946               $lcshmu = List::Compare->new('--unsorted', \%Alpha, \%Beta, \%Gamma);
947
948           As was true when we were using List::Compare's Multiple and
949           Multiple Accelerated modes, do not count any unsorted or
950           accelerated option when determining the array index of a particular
951           seen-hash reference passed to the constructor.
952
953       ·   Alternative Constructor
954
955           The 'single hashref' form of constructor is also available to build
956           List::Compare objects where seen-hashes are used as arguments:
957
958               $lcshu  = List::Compare->new( {
959                   unsorted => 1,
960                   lists    => [\%Llist, \%Rlist],
961               } );
962
963               $lcshau = List::Compare->new( {
964                   unsorted    => 1,
965                   accelerated => 1,
966                   lists       => [\%Llist, \%Rlist],
967               } );
968
969               $lcshmu = List::Compare->new( {
970                   unsorted => 1,
971                   lists    => [\%Alpha, \%Beta, \%Gamma],
972               } );
973

DISCUSSION: Principles

975   General Comments
976       List::Compare is an object-oriented implementation of very common Perl
977       code (see "History, References and Development" below) used to
978       determine interesting relationships between two or more lists at a
979       time.  A List::Compare object is created and automatically computes the
980       values needed to supply List::Compare methods with appropriate results.
981       In the current implementation List::Compare methods will return new
982       lists containing the items found in any designated list alone (unique),
983       any list other than a designated list (complement), the intersection
984       and union of all lists and so forth.  List::Compare also has (a)
985       methods to return Boolean values indicating whether one list is a
986       subset of another and whether any two lists are equivalent to each
987       other (b) methods to pretty-print very simple charts displaying the
988       subset and equivalence relationships among lists.
989
990       Except for List::Compare's "get_bag()" method, multiple instances of an
991       element in a given list count only once with respect to computing the
992       intersection, union, etc. of the two lists.  In particular,
993       List::Compare considers two lists as equivalent if each element of the
994       first list can be found in the second list and vice versa.
995       'Equivalence' in this usage takes no note of the frequency with which
996       elements occur in either list or their order within the lists.
997       List::Compare asks the question:  Did I see this item in this list at
998       all?  Only when you use "List::Compare::get_bag()" to compute a bag
999       holding the two lists do you ask the question:  How many times did this
1000       item occur in this list?
1001
1002   List::Compare Modes
1003       In its current implementation List::Compare has four modes of
1004       operation.
1005
1006       ·   Regular Mode
1007
1008           List::Compare's Regular mode is based on List::Compare v0.11 -- the
1009           first version of List::Compare released to CPAN (June 2002).  It
1010           compares only two lists at a time.  Internally, its initializer
1011           does all computations needed to report any desired comparison and
1012           its constructor stores the results of these computations.  Its
1013           public methods merely report these results.
1014
1015           This approach has the advantage that if you need to examine more
1016           than one form of comparison between two lists (e.g., the union,
1017           intersection and symmetric difference of two lists), the
1018           comparisons are pre-calculated.  This approach is efficient because
1019           certain types of comparison presuppose that other types have
1020           already been calculated.  For example, to calculate the symmetric
1021           difference of two lists, one must first determine the items unique
1022           to each of the two lists.
1023
1024       ·   Accelerated Mode
1025
1026           The current implementation of List::Compare offers you the option
1027           of getting even faster results provided that you only need the
1028           result from a single form of comparison between two lists. (e.g.,
1029           only the union -- nothing else).  In the Accelerated mode,
1030           List::Compare's initializer does no computation and its constructor
1031           stores only references to the two source lists.  All computation
1032           needed to report results is deferred to the method calls.
1033
1034           The user selects this approach by passing the option flag '-a' to
1035           the constructor before passing references to the two source lists.
1036           List::Compare notes the option flag and silently switches into
1037           Accelerated mode.  From the perspective of the user, there is no
1038           further difference in the code or in the results.
1039
1040           Benchmarking suggests that List::Compare's Accelerated mode (a) is
1041           faster than its Regular mode when only one comparison is requested;
1042           (b) is about as fast as Regular mode when two comparisons are
1043           requested; and (c) becomes considerably slower than Regular mode as
1044           each additional comparison above two is requested.
1045
1046       ·   Multiple Mode
1047
1048           List::Compare now offers the possibility of comparing three or more
1049           lists at a time.  Simply store the extra lists in arrays and pass
1050           references to those arrays to the constructor.  List::Compare
1051           detects that more than two lists have been passed to the
1052           constructor and silently switches into Multiple mode.
1053
1054           As described in the Synopsis above, comparing more than two lists
1055           at a time offers you a wider, more complex palette of comparison
1056           methods.  Individual items may appear in just one source list, in
1057           all the source lists, or in some number of lists between one and
1058           all.  The meaning of 'union', 'intersection' and 'symmetric
1059           difference' is conceptually unchanged when you move to multiple
1060           lists because these are properties of all the lists considered
1061           together.  In contrast, the meaning of 'unique', 'complement',
1062           'subset' and 'equivalent' changes because these are properties of
1063           one list compared with another or with all the other lists
1064           combined.
1065
1066           List::Compare takes this complexity into account by allowing you to
1067           pass arguments to the public methods requesting results with
1068           respect to a specific list (for "get_unique()" and
1069           "get_complement()") or a specific pair of lists (for
1070           "is_LsubsetR()" and "is_LequivalentR()").
1071
1072           List::Compare further takes this complexity into account by
1073           offering the new methods "get_shared()" and "get_nonintersection()"
1074           described in the Synopsis above.
1075
1076       ·   Multiple Accelerated Mode
1077
1078           Beginning with version 0.25, introduced in April 2004,
1079           List::Compare offers the possibility of accelerated computation of
1080           a single comparison among three or more lists at a time.  Simply
1081           store the extra lists in arrays and pass references to those arrays
1082           to the constructor preceded by the '-a' argument as was done with
1083           the simple (two lists only) accelerated mode.  List::Compare
1084           detects that more than two lists have been passed to the
1085           constructor and silently switches into Multiple Accelerated mode.
1086
1087       ·   Unsorted Option
1088
1089           When List::Compare is used to return lists representing various
1090           comparisons of two or more lists (e.g., the lists' union or
1091           intersection), the lists returned are, by default, sorted using
1092           Perl's default "sort" mode: ASCII-betical sorting.  Sorting
1093           produces results which are more easily human-readable but may
1094           entail a performance cost.
1095
1096           Should you not need sorted results, you can avoid the potential
1097           performance cost by calling List::Compare's constructor using the
1098           unsorted option.  This is done by calling '-u' or '--unsorted' as
1099           the first argument passed to the constructor, i.e., as an argument
1100           called before any references to lists are passed to the
1101           constructor.
1102
1103           Note that if are calling List::Compare in the Accelerated or
1104           Multiple Accelerated mode and wish to have the lists returned in
1105           unsorted order, you first pass the argument for the unsorted option
1106           ('-u' or '--unsorted') and then pass the argument for the
1107           Accelerated mode ('-a' or '--accelerated').
1108
1109   Miscellaneous Methods
1110       It would not really be appropriate to call "get_shared()" and
1111       "get_nonintersection()" in Regular or Accelerated mode since they are
1112       conceptually based on the notion of comparing more than two lists at a
1113       time.  However, there is always the possibility that a user may be
1114       comparing only two lists (accelerated or not) and may accidentally call
1115       one of those two methods.  To prevent fatal run-time errors and to
1116       caution you to use a more appropriate method, these two methods are
1117       defined for Regular and Accelerated modes so as to return suitable
1118       results but also generate a carp message that advise you to re-code.
1119
1120       Similarly, the method "is_RsubsetL()" is appropriate for the Regular
1121       and Accelerated modes but is not really appropriate for Multiple mode.
1122       As a defensive maneuver, it has been defined for Multiple mode so as to
1123       return suitable results but also to generate a carp message that
1124       advises you to re-code.
1125
1126       In List::Compare v0.11 and earlier, the author provided aliases for
1127       various methods based on the supposition that the source lists would be
1128       referred to as 'A' and 'B'.  Now that you can compare more than two
1129       lists at a time, the author feels that it would be more appropriate to
1130       refer to the elements of two-argument lists as the left-hand and right-
1131       hand elements.  Hence, we are discouraging the use of methods such as
1132       "get_Aonly()", "get_Bonly()" and "get_AorBonly()" as aliases for
1133       "get_unique()", "get_complement()" and "get_symmetric_difference()".
1134       However, to guarantee backwards compatibility for the vast audience of
1135       Perl programmers using earlier versions of List::Compare (all 10e1 of
1136       you) these and similar methods for subset relationships are still
1137       defined.
1138
1139   List::Compare::SeenHash Discontinued Beginning with Version 0.26
1140       Prior to v0.26, introduced April 11, 2004, if a user wished to pass
1141       references to seen-hashes to List::Compare's constructor rather than
1142       references to arrays, he or she had to call a different, parallel
1143       module: List::Compare::SeenHash.  The code for that looked like this:
1144
1145           use List::Compare::SeenHash;
1146
1147           my %Llist = (
1148              abel     => 2,
1149              baker    => 1,
1150              camera   => 1,
1151              delta    => 1,
1152              edward   => 1,
1153              fargo    => 1,
1154              golfer   => 1,
1155           );
1156
1157           my %Rlist = (
1158              baker    => 1,
1159              camera   => 1,
1160              delta    => 2,
1161              edward   => 1,
1162              fargo    => 1,
1163              golfer   => 1,
1164              hilton   => 1,
1165           );
1166
1167           my $lcsh = List::Compare::SeenHash->new(\%Llist, \%Rlist);
1168
1169       List::Compare::SeenHash is deprecated beginning with version 0.26.  All
1170       its functionality (and more) has been implemented in List::Compare
1171       itself, since a user can now pass either a series of array references
1172       or a series of seen-hash references to List::Compare's constructor.
1173
1174       To simplify future maintenance of List::Compare,
1175       List::Compare::SeenHash.pm will no longer be distributed with
1176       List::Compare, nor will the files in the test suite which tested
1177       List::Compare::SeenHash upon installation be distributed.
1178
1179       Should you still need List::Compare::SeenHash, use version 0.25 from
1180       CPAN, or simply edit your Perl programs which used
1181       List::Compare::SeenHash.  Those scripts may be edited quickly with, for
1182       example, this editing command in Unix text editor vi:
1183
1184           :1,$s/List::Compare::SeenHash/List::Compare/gc
1185
1186   A Non-Object-Oriented Interface:  List::Compare::Functional
1187       Version 0.21 of List::Compare introduced List::Compare::Functional, a
1188       functional (i.e., non-object-oriented) interface to list comparison
1189       functions.  List::Compare::Functional supports the same functions
1190       currently supported by List::Compare.  It works similar to
1191       List::Compare's Accelerated and Multiple Accelerated modes (described
1192       above), bit it does not require use of the '-a' flag in the function
1193       call.  List::Compare::Functional will return unsorted comparisons of
1194       two lists by passing '-u' or '--unsorted' as the first argument to the
1195       function.  Please see the documentation for List::Compare::Functional
1196       to learn how to import its functions into your main package.
1197

ASSUMPTIONS AND QUALIFICATIONS

1199       The program was created with Perl 5.6. The use of h2xs to prepare the
1200       module's template installed "require 5.005_62;" at the top of the
1201       module.  This has been commented out in the actual module as the code
1202       appears to be compatible with earlier versions of Perl; how earlier the
1203       author cannot say.  In particular, the author would like the module to
1204       be installable on older versions of MacPerl.  As is, the author has
1205       successfully installed the module on Linux, Windows 9x and Windows
1206       2000.  See <http://testers.cpan.org/show/List-Compare.html> for a list
1207       of other systems on which this version of List::Compare has been tested
1208       and installed.
1209

HISTORY, REFERENCES AND DEVELOPMENT

1211   The Code Itself
1212       List::Compare is based on code presented by Tom Christiansen & Nathan
1213       Torkington in Perl Cookbook <http://www.oreilly.com/catalog/cookbook/>
1214       (a.k.a. the 'Ram' book), O'Reilly & Associates, 1998, Recipes 4.7 and
1215       4.8.  Similar code is presented in the Camel book:  Programming Perl,
1216       by Larry Wall, Tom Christiansen, Jon Orwant.
1217       <http://www.oreilly.com/catalog/pperl3/>, 3rd ed, O'Reilly &
1218       Associates, 2000.  The list comparison code is so basic and Perlish
1219       that I suspect it may have been written by Larry himself at the dawn of
1220       Perl time.  The "get_bag()" method was inspired by Jarkko Hietaniemi's
1221       Set::Bag module and Daniel Berger's Set::Array module, both available
1222       on CPAN.
1223
1224       List::Compare's original objective was simply to put this code in a
1225       modular, object-oriented framework.  That framework, not surprisingly,
1226       is taken mostly from Damian Conway's Object Oriented Perl
1227       <http://www.manning.com/Conway/index.html>, Manning Publications, 2000.
1228
1229       With the addition of the Accelerated, Multiple and Multiple Accelerated
1230       modes, List::Compare expands considerably in both size and
1231       capabilities.  Nonetheless,  Tom and Nat's Cookbook code still lies at
1232       its core: the use of hashes as look-up tables to record elements seen
1233       in lists.  Please note:  List::Compare is not concerned with any
1234       concept of 'equality' among lists which hinges upon the frequency with
1235       which, or the order in which, elements appear in the lists to be
1236       compared.  If this does not meet your needs, you should look elsewhere
1237       or write your own module.
1238
1239   The Inspiration
1240       I realized the usefulness of putting the list comparison code into a
1241       module while preparing an introductory level Perl course given at the
1242       New School University's Computer Instruction Center in April-May 2002.
1243       I was comparing lists left and right.  When I found myself writing very
1244       similar functions in different scripts, I knew a module was lurking
1245       somewhere.  I learned the truth of the mantra ''Repeated Code is a
1246       Mistake'' from a 2001 talk by Mark-Jason Dominus
1247       <http://perl.plover.com/> to the New York Perlmongers
1248       <http://ny.pm.org/>.  See
1249       <http://www.perl.com/pub/a/2000/11/repair3.html>.
1250
1251       The first public presentation of this module took place at Perl Seminar
1252       New York <http://groups.yahoo.com/group/perlsemny> on May 21, 2002.
1253       Comments and suggestions were provided there and since by Glenn Maciag,
1254       Gary Benson, Josh Rabinowitz, Terrence Brannon and Dave Cross.
1255
1256       The placement in the installation tree of Test::ListCompareSpecial came
1257       as a result of a question answered by Michael Graham in his talk
1258       ''Test::More to Test::Extreme'' given at Yet Another Perl
1259       Conference::Canada in Ottawa, Ontario, on May 16, 2003.
1260
1261       In May-June 2003, Glenn Maciag made valuable suggestions which led to
1262       changes in method names and documentation in v0.20.
1263
1264       Another presentation at Perl Seminar New York in October 2003 prompted
1265       me to begin planning List::Compare::Functional.
1266
1267       In a November 2003 Perl Seminar New York presentation, Ben Holtzman
1268       discussed the performance costs entailed in Perl's "sort" function.
1269       This led me to ask, ''Why should a user of List::Compare pay this
1270       performance cost if he or she doesn't need a human-readable list as a
1271       result (as would be the case if the list returned were used as the
1272       input into some other function)?''  This led to the development of
1273       List::Compare's unsorted option.
1274
1275       An April 2004 offer by Kevin Carlson to write an article for The Perl
1276       Journal (<http://tpj.com>) led me to re-think whether a separate module
1277       (the former List::Compare::SeenHash) was truly needed when a user
1278       wanted to provide the constructor with references to seen-hashes rather
1279       than references to arrays.  Since I had already adapted
1280       List::Compare::Functional to accept both kinds of arguments, I adapted
1281       List::Compare in the same manner.  This meant that
1282       List::Compare::SeenHash and its related installation tests could be
1283       deprecated and deleted from the CPAN distribution.
1284
1285       A remark by David H. Adler at a New York Perlmongers meeting in April
1286       2004 led me to develop the 'single hashref' alternative constructor
1287       format, introduced in version 0.29 the following month.
1288
1289       Presentations at two different editions of Yet Another Perl Conference
1290       (YAPC) inspired the development of List::Compare versions 0.30 and
1291       0.31.  I was selected to give a talk on List::Compare at YAPC::NA::2004
1292       in Buffalo.  This spurred me to improve certain aspects of the
1293       documentation.  Version 0.31 owes its inspiration to one talk at the
1294       Buffalo YAPC and one earlier talk at YAPC::EU::2003 in Paris.  In Paris
1295       I heard Paul Johnson speak on his CPAN module Devel::Cover and on
1296       coverage analysis more generally.  That material was over my head at
1297       that time, but in Buffalo I heard Andy Lester discuss Devel::Cover as
1298       part of his discussion of testing and of the Phalanx project
1299       (<http://qa.perl.org/phalanx>).  This time I got it, and when I
1300       returned from Buffalo I applied Devel::Cover to List::Compare and wrote
1301       additional tests to improve its subroutine and statement coverage.  In
1302       addition, I added two new methods, "get_unique_all" and
1303       "get_complement_all".  In writing these two methods, I followed a model
1304       of test-driven development much more so than in earlier versions of
1305       List::Compare and my other CPAN modules.  The result?  List::Compare's
1306       test suite grew by over 3300 tests to nearly 23,000 tests.
1307
1308       At the Second New York Perl Hackathon (May 02 2015), a project was
1309       created to request performance improvements in certain List::Compare
1310       functions
1311       (<https://github.com/nyperlmongers/nyperlhackathon2015/wiki/List-Compare-Performance-Improvements>).
1312       Hackathon participant Michael Rawson submitted a pull request with
1313       changes to List::Compare::Base::_Auxiliary.  After these revisions were
1314       benchmarked, a patch embodying the pull request was accepted, leading
1315       to CPAN version 0.53.
1316
1317   If You Like List::Compare, You'll Love ...
1318       While preparing this module for distribution via CPAN, I had occasion
1319       to study a number of other modules already available on CPAN.  Each of
1320       these modules is more sophisticated than List::Compare -- which is not
1321       surprising since all that List::Compare originally aspired to do was to
1322       avoid typing Cookbook code repeatedly.  Here is a brief description of
1323       the features of these modules.  (Warning:  The following discussion is
1324       only valid as of June 2002.  Some of these modules may have changed
1325       since then.)
1326
1327       ·   Algorithm::Diff - Compute 'intelligent' differences between two
1328           files/lists (<http://search.cpan.org/dist/Algorithm-Diff/>)
1329
1330           Algorithm::Diff is a sophisticated module originally written by
1331           Mark-Jason Dominus, later maintained by Ned Konz, now maintained by
1332           Tye McQueen. Think of the Unix "diff" utility  and you're on the
1333           right track.  Algorithm::Diff exports methods such as "diff", which
1334           ''computes the smallest set of additions and deletions necessary to
1335           turn the first sequence into the second, and returns a description
1336           of these changes.''  Algorithm::Diff is mainly concerned with the
1337           sequence of elements within two lists.  It does not export
1338           functions for intersection, union, subset status, etc.
1339
1340       ·   Array::Compare - Perl extension for comparing arrays
1341           (<http://search.cpan.org/dist/Array-Compare/>)
1342
1343           Array::Compare, by Dave Cross, asks whether two arrays are the same
1344           or different by doing a "join" on each string with a separator
1345           character and comparing the resulting strings.  Like List::Compare,
1346           it is an object-oriented module.  A sophisticated feature of
1347           Array::Compare is that it allows you to specify how 'whitespace' in
1348           an array (an element which is undefined, the empty string, or
1349           whitespace within an element) should be evaluated for purpose of
1350           determining equality or difference.    It does not directly provide
1351           methods for intersection and union.
1352
1353       ·   Data::Compare - compare perl data structures
1354           (<http://search.cpan.org/dist/Data-Compare/>)
1355
1356           This library compares Perl data structures recursively.  Comes
1357           recommended by Slaven Rezić!
1358
1359       ·   List::Util - A selection of general-utility list subroutines
1360           (<http://search.cpan.org/dist/Scalar-List-Utils/>)
1361
1362           List::Util, by Graham Barr, exports a variety of simple, useful
1363           functions for operating on one list at a time.    The "min"
1364           function returns the lowest numerical value in a list; the "max"
1365           function returns the highest value; and so forth.  List::Compare
1366           differs from List::Util in that it is object-oriented and that it
1367           works on two strings at a time rather than just one -- but it aims
1368           to be as simple and useful as List::Util.  List::Util will be
1369           included in the standard Perl distribution as of Perl 5.8.0.
1370
1371           Lists::Util (<http://search.cpan.org/dist/List-MoreUtils/>), by
1372           Tassilo von Parseval, building on code by Terrence Brannon,
1373           provides methods which extend List::Util's functionality.
1374
1375       ·   Quantum::Superpositions
1376           (<http://search.cpan.org/dist/Quantum-Superpositions/>), originally
1377           by Damian Conway, now maintained by Steven Lembark is useful if, in
1378           addition to comparing lists, you need to emulate quantum
1379           supercomputing as well.  Not for the eigen-challenged.
1380
1381       ·   Set::Scalar - basic set operations
1382           (<http://search.cpan.org/dist/Set-Scalar/>)
1383
1384           Set::Bag - bag (multiset) class
1385           (<http://search.cpan.org/dist/Set-Bag/>)
1386
1387           Both of these modules are by Jarkko Hietaniemi.  Set::Scalar has
1388           methods to return the intersection, union, difference and symmetric
1389           difference of two sets, as well as methods to return items unique
1390           to a first set and complementary to it in a second set.  It has
1391           methods for reporting considerably more variants on subset status
1392           than does List::Compare.  However, benchmarking suggests that
1393           List::Compare, at least in Regular mode, is considerably faster
1394           than Set::Scalar for those comparison methods which List::Compare
1395           makes available.
1396
1397           Set::Bag enables one to deal more flexibly with the situation in
1398           which one has more than one instance of an element in a list.
1399
1400       ·   Set::Array - Arrays as objects with lots of handy methods
1401           (including set comparisons) and support for method chaining.
1402           (<http://search.cpan.org/dist/Set-Array/>)
1403
1404           Set::Array, by Daniel Berger, now maintained by Ron Savage, ''aims
1405           to provide built-in methods for operations that people are always
1406           asking how to do,and which already exist in languages like Ruby.''
1407           Among the many methods in this module are some for intersection,
1408           union, etc.  To install Set::Array, you must first install the Want
1409           module, also available on CPAN.
1410

ADDITIONAL CONTRIBUTORS

1412       ·   Syohei YOSHIDA
1413
1414           Pull request accepted May 22 2015.
1415
1416       ·   Paulo Custodio
1417
1418           Pull request accepted June 07 2015, correcting errors in
1419           "_subset_subengine()".
1420

BUGS

1422       There are no bug reports outstanding on List::Compare as of the most
1423       recent CPAN upload date of this distribution.
1424

SUPPORT

1426       Please report any bugs by mail to "bug-List-Compare@rt.cpan.org" or
1427       through the web interface at <http://rt.cpan.org>.
1428

AUTHOR

1430       James E. Keenan (jkeenan@cpan.org).  When sending correspondence,
1431       please include 'List::Compare' or 'List-Compare' in your subject line.
1432
1433       Creation date:  May 20, 2002.  Last modification date:  August 16 2020.
1434
1435       Development repository: <https://github.com/jkeenan/list-compare>
1436
1438       Copyright (c) 2002-20 James E. Keenan.  United States.  All rights
1439       reserved.  This is free software and may be distributed under the same
1440       terms as Perl itself.
1441

DISCLAIMER OF WARRANTY

1443       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
1444       FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
1445       WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
1446       PARTIES PROVIDE THE SOFTWARE ''AS IS'' WITHOUT WARRANTY OF ANY KIND,
1447       EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
1448       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
1449       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
1450       YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
1451       NECESSARY SERVICING, REPAIR, OR CORRECTION.
1452
1453       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
1454       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
1455       REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
1456       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
1457       CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
1458       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
1459       RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
1460       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
1461       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
1462       DAMAGES.
1463
1464
1465
1466perl v5.32.0                      2020-08-19                  List::Compare(3)
Impressum