1List::Compare(3) User Contributed Perl Documentation List::Compare(3)
2
6 List::Compare - Compare elements of two or more lists
7
9 This document refers to version 0.55 of List::Compare. This version
10 was released August 16 2020.
11
13 The bare essentials:
14 @Llist = qw(abel abel baker camera delta edward fargo golfer);
16 @Rlist = qw(baker camera delta delta edward fargo golfer hilton);
17 $lc = List::Compare->new(\@Llist, \@Rlist);
19 @intersection = $lc->get_intersection;
21 @union = $lc->get_union;
22 ... and so forth.
24
26 Regular Case: Compare Two Lists
27 • Constructor: new()
28 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 @Llist = qw(abel abel baker camera delta edward fargo golfer);
34 @Rlist = qw(baker camera delta delta edward fargo golfer hilton);
35 $lc = List::Compare->new(\@Llist, \@Rlist);
37 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 $lc = List::Compare->new('-u', \@Llist, \@Rlist);
45 or
47 $lc = List::Compare->new('--unsorted', \@Llist, \@Rlist);
49 • Alternative Constructor
51 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 $lc = List::Compare->new( { lists => [\@Llist, \@Rlist] } );
57 or
59 $lc = List::Compare->new( {
61 lists => [\@Llist, \@Rlist],
62 unsorted => 1,
63 } );
64 • get_intersection()
66 Get those items which appear at least once in both lists (their
68 intersection).
69 @intersection = $lc->get_intersection;
71 • get_union()
73 Get those items which appear at least once in either list (their
75 union).
76 @union = $lc->get_union;
78 • get_unique()
80 Get those items which appear (at least once) only in the first
82 list.
83 @Lonly = $lc->get_unique;
85 @Lonly = $lc->get_Lonly; # alias
86 • get_complement()
88 Get those items which appear (at least once) only in the second
90 list.
91 @Ronly = $lc->get_complement;
93 @Ronly = $lc->get_Ronly; # alias
94 • get_symmetric_difference()
96 Get those items which appear at least once in either the first or
98 the second list, but not both.
99 @LorRonly = $lc->get_symmetric_difference;
101 @LorRonly = $lc->get_symdiff; # alias
102 @LorRonly = $lc->get_LorRonly; # alias
103 • get_bag()
105 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 @bag = $lc->get_bag;
111 • Return references rather than lists
113 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 $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 • is_LsubsetR()
131 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 $LR = $lc->is_LsubsetR;
137 Return a true value if R is a subset of L.
139 $RL = $lc->is_RsubsetL;
141 • is_LequivalentR()
143 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 $eqv = $lc->is_LequivalentR;
149 $eqv = $lc->is_LeqvlntR; # alias
150 • is_LdisjointR()
152 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 $disj = $lc->is_LdisjointR;
158 • print_subset_chart()
160 Pretty-print a chart showing whether one list is a subset of the
162 other.
163 $lc->print_subset_chart;
165 • print_equivalence_chart()
167 Pretty-print a chart showing whether the two lists are equivalent
169 (same elements found at least once in both).
170 $lc->print_equivalence_chart;
172 • is_member_which()
174 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 @memb_arr = $lc->is_member_which('abel');
181 In the example above, @memb_arr will be:
183 ( 0 )
185 because 'abel' is found only in @Al which holds position 0 in the
187 list of arguments passed to new().
188 In scalar context, the return value is the number of lists passed
190 to the constructor in which a given string is found.
191 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 $memb_arr_ref = $lc->is_member_which_ref('baker');
197 In the example above, $memb_arr_ref will be:
199 [ 0, 1 ]
201 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 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 • are_members_which()
211 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 $memb_hash_ref =
218 $lc->are_members_which([ qw| abel baker fargo hilton zebra | ]);
219 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 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 {
232 abel => [ 0 ],
233 baker => [ 0, 1 ],
234 fargo => [ 0, 1 ],
235 hilton => [ 1 ],
236 zebra => [ ],
237 };
238 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 a
242 hash reference.
243 • is_member_any()
245 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 $found = $lc->is_member_any('abel');
251 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 • are_members_any()
256 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 $memb_hash_ref = $lc->are_members_any([ qw| abel baker fargo hilton zebra | ]);
263 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 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 {
274 abel => 1,
275 baker => 1,
276 fargo => 1,
277 hilton => 1,
278 zebra => 0,
279 };
280 "zebra"'s value is 0 because "zebra" is not found in either of the
282 lists passed as arguments to new().
283 • get_version()
285 Return current List::Compare version number.
287 $vers = $lc->get_version;
289 Accelerated Case: When User Only Wants a Single Comparison
291 • Constructor new()
292 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 @Llist = qw(abel abel baker camera delta edward fargo golfer);
298 @Rlist = qw(baker camera delta delta edward fargo golfer hilton);
299 $lca = List::Compare->new('-a', \@Llist, \@Rlist);
301 or
303 $lca = List::Compare->new('--accelerated', \@Llist, \@Rlist);
305 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 $lca = List::Compare->new('-u', '-a', \@Llist, \@Rlist);
312 or
314 $lca = List::Compare->new('--unsorted', '--accelerated', \@Llist, \@Rlist);
316 • Alternative Constructor
318 You may use the 'single hashref' constructor format to build a
320 List::Compare object calling for the Accelerated mode:
321 $lca = List::Compare->new( {
323 lists => [\@Llist, \@Rlist],
324 accelerated => 1,
325 } );
326 or
328 $lca = List::Compare->new( {
330 lists => [\@Llist, \@Rlist],
331 accelerated => 1,
332 unsorted => 1,
333 } );
334 • Methods
336 All the comparison methods available in the Regular case are
338 available to you in the Accelerated case as well.
339 @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 All the aliases for methods available in the Regular case are
368 available to you in the Accelerated case as well.
369 Multiple Case: Compare Three or More Lists
371 • Constructor new()
372 Create a List::Compare object. Put each list into an array and
374 pass references to the arrays to the constructor.
375 @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 $lcm = List::Compare->new(\@Al, \@Bob, \@Carmen, \@Don, \@Ed);
383 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 $lcm = List::Compare->new('-u', \@Al, \@Bob, \@Carmen, \@Don, \@Ed);
389 or
391 $lcm = List::Compare->new('--unsorted', \@Al, \@Bob, \@Carmen, \@Don, \@Ed);
393 • Alternative Constructor
395 You may use the 'single hashref' constructor format to build a
397 List::Compare object to process three or more lists at once:
398 $lcm = List::Compare->new( {
400 lists => [\@Al, \@Bob, \@Carmen, \@Don, \@Ed],
401 } );
402 or
404 $lcm = List::Compare->new( {
406 lists => [\@Al, \@Bob, \@Carmen, \@Don, \@Ed],
407 unsorted => 1,
408 } );
409 • Multiple Mode Methods Analogous to Regular and Accelerated Mode
411 Methods
412 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 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 • start the count at 0 (as is customary with Perl array indices);
424 and
425 • do not count any unsorted option ('-u' or '--unsorted')
427 preceding the array references in the constructor's own
428 argument list.
429 Example:
431 $lcmex = List::Compare->new('--unsorted', \@alpha, \@beta, \@gamma);
433 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 • get_intersection()
439 Get those items found in each of the lists passed to the
441 constructor (their intersection):
442 @intersection = $lcm->get_intersection;
444 • get_union()
446 Get those items found in any of the lists passed to the
448 constructor (their union):
449 @union = $lcm->get_union;
451 • get_unique()
453 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 Example: @Carmen has index position 2 in the constructor's @_.
460 To get elements unique to @Carmen:
461 @Lonly = $lcm->get_unique(2);
463 If no index position is passed to get_unique() it will default
465 to 0 and report items unique to the first list passed to the
466 constructor.
467 • get_complement()
469 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 Example: @Don has index position 3 in the constructor's @_.
476 To get elements not found in @Don:
477 @Ronly = $lcm->get_complement(3);
479 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 • get_symmetric_difference()
485 Get those items each of which appears in only one of the lists
487 passed to the constructor (their symmetric_difference);
488 @LorRonly = $lcm->get_symmetric_difference;
490 • get_bag()
492 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 @bag = $lcm->get_bag;
498 • Return reference instead of list
500 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 $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 • is_LsubsetR()
514 To determine whether one particular list is a subset of another
516 list passed to the constructor, provide is_LsubsetR() with the
517 index position of the presumed subset (ignoring any unsorted
518 option), followed by the index position of the presumed
519 superset.
520 Example: To determine whether @Ed is a subset of @Carmen,
522 call:
523 $LR = $lcm->is_LsubsetR(4,2);
525 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 If no arguments are passed, is_LsubsetR() defaults to "(0,1)"
531 and compares the first two lists passed to the constructor.
532 • is_LequivalentR()
534 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 Example: To determine whether @Don and @Ed are equivalent,
541 call:
542 $eqv = $lcm->is_LequivalentR(3,4);
544 A true value (1) is returned if the lists are equivalent; a
546 false value (0) otherwise.
547 If no arguments are passed, "is_LequivalentR" defaults to
549 "(0,1)" and compares the first two lists passed to the
550 constructor.
551 • is_LdisjointR()
553 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 Example: To determine whether @Don and @Ed are disjoint, call:
561 $disj = $lcm->is_LdisjointR(3,4);
563 A true value (1) is returned if the lists are equivalent; a
565 false value (0) otherwise.
566 If no arguments are passed, "is_LdisjointR" defaults to "(0,1)"
568 and compares the first two lists passed to the constructor.
569 • print_subset_chart()
571 Pretty-print a chart showing the subset relationships among the
573 various source lists:
574 $lcm->print_subset_chart;
576 • print_equivalence_chart()
578 Pretty-print a chart showing the equivalence relationships
580 among the various source lists:
581 $lcm->print_equivalence_chart;
583 • is_member_which()
585 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 @memb_arr = $lcm->is_member_which('abel');
593 In the example above, @memb_arr will be:
595 ( 0 )
597 because 'abel' is found only in @Al which holds position 0 in
599 the list of arguments passed to new().
600 • is_member_which_ref()
602 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 $memb_arr_ref = $lcm->is_member_which_ref('jerky');
608 In the example above, $memb_arr_ref will be:
610 [ 3, 4 ]
612 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 Note: methods is_member_which() and "is_member_which_ref" test
618 only one string at a time and hence take only one argument. To
619 test more than one string at a time see the next method,
620 are_members_which().
621 • are_members_which()
623 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 $memb_hash_ref =
630 $lcm->are_members_which([ qw| abel baker fargo hilton zebra | ]);
631 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 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 In the two examples above, $memb_hash_ref will be:
644 {
646 abel => [ 0 ],
647 baker => [ 0, 1 ],
648 fargo => [ 0, 1, 2, 3, 4 ],
649 hilton => [ 1, 2 ],
650 zebra => [ ],
651 };
652 Note: are_members_which() can take more than one argument;
654 is_member_which() and is_member_which_ref() each take only one
655 argument. are_members_which() returns a hash reference; the
656 other methods return either a list or a reference to an array
657 holding that list, depending on context.
658 • is_member_any()
660 Determine whether a given string can be found in any of the
662 lists passed as arguments to the constructor.
663 $found = $lcm->is_member_any('abel');
665 Return 1 if a specified string can be found in any of the lists
667 and 0 if not.
668 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 • are_members_any()
673 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 $memb_hash_ref = $lcm->are_members_any([ qw| abel baker fargo hilton zebra | ]);
680 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 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 {
692 abel => 1,
693 baker => 1,
694 fargo => 1,
695 hilton => 1,
696 zebra => 0,
697 };
698 "zebra"'s value will be 0 because "zebra" is not found in any
700 of the lists passed as arguments to new().
701 • get_version()
703 Return current List::Compare version number:
705 $vers = $lcm->get_version;
707 • Multiple Mode Methods Not Analogous to Regular and Accelerated Mode
709 Methods
710 • get_nonintersection()
712 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 @nonintersection = $lcm->get_nonintersection;
718 • get_shared()
720 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 @shared = $lcm->get_shared;
726 • get_nonintersection_ref()
728 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 $nonintersection_ref = $lcm->get_nonintersection_ref;
734 $shared_ref = $lcm->get_shared_ref;
735 • get_unique_all()
737 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 $unique_all_ref = $lcm->get_unique_all();
743 In the example above, $unique_all_ref will hold:
745 [
747 [ qw| abel | ],
748 [ ],
749 [ qw| jerky | ],
750 [ ],
751 [ ],
752 ]
753 • get_complement_all()
755 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 $complement_all_ref = $lcm->get_complement_all();
762 In the example above, $complement_all_ref will hold:
764 [
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 Multiple Accelerated Case: Compare Three or More Lists but Request Only a
774 Single Comparison among the Lists
775 • Constructor new()
776 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 @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 $lcma = List::Compare->new('-a',
789 \@Al, \@Bob, \@Carmen, \@Don, \@Ed);
790 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 $lcma = List::Compare->new('-u', '-a',
796 \@Al, \@Bob, \@Carmen, \@Don, \@Ed);
797 or
799 $lcma = List::Compare->new('--unsorted', '--accelerated',
801 \@Al, \@Bob, \@Carmen, \@Don, \@Ed);
802 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 Example:
810 $lcmaex = List::Compare->new('--unsorted', '--accelerated',
812 \@alpha, \@beta, \@gamma);
813 • Alternative Constructor
815 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 $lcmaex = List::Compare->new( {
821 accelerated => 1,
822 lists => [\@alpha, \@beta, \@gamma],
823 } );
824 or
826 $lcmaex = List::Compare->new( {
828 unsorted => 1,
829 accelerated => 1,
830 lists => [\@alpha, \@beta, \@gamma],
831 } );
832 • Methods
834 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 @gamma_only = $lcmaex->get_unique(2);
842 Passing Seen-hashes to the Constructor Instead of Arrays
844 • When Seen-Hashes Are Already Available to You
845 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 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 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 In other words, suppose it was more convenient to compute a lookup
874 table implying a list than to compute that list explicitly.
875 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 • Constructor new()
883 You can now do so:
885 $lcsh = List::Compare->new(\%Llist, \%Rlist);
887 • Methods
889 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 @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 • Accelerated Mode and Seen-Hashes
924 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 $lcsha = List::Compare->new('-a', \%Llist, \%Rlist);
930 To compare three or more lists simultaneously, pass three or more
932 references to seen-hashes. Thus,
933 $lcshm = List::Compare->new(\%Alpha, \%Beta, \%Gamma);
935 will generate meaningful comparisons of three or more lists
937 simultaneously.
938 • Unsorted Results and Seen-Hashes
940 If you do not need sorted lists returned, pass '-u' or "--unsorted"
942 to the constructor before passing references to seen-hashes.
943 $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 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 • Alternative Constructor
954 The 'single hashref' form of constructor is also available to build
956 List::Compare objects where seen-hashes are used as arguments:
957 $lcshu = List::Compare->new( {
959 unsorted => 1,
960 lists => [\%Llist, \%Rlist],
961 } );
962 $lcshau = List::Compare->new( {
964 unsorted => 1,
965 accelerated => 1,
966 lists => [\%Llist, \%Rlist],
967 } );
968 $lcshmu = List::Compare->new( {
970 unsorted => 1,
971 lists => [\%Alpha, \%Beta, \%Gamma],
972 } );
973
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 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 List::Compare Modes
1003 In its current implementation List::Compare has four modes of
1004 operation.
1005 • Regular Mode
1007 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 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 • Accelerated Mode
1025 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 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 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 • Multiple Mode
1047 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 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 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 get_complement())
1069 or a specific pair of lists (for is_LsubsetR() and
1070 is_LequivalentR()).
1071 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 • Multiple Accelerated Mode
1077 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 • Unsorted Option
1088 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 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 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 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 Similarly, the method is_RsubsetL() is appropriate for the Regular and
1121 Accelerated modes but is not really appropriate for Multiple mode. As
1122 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 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 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 use List::Compare::SeenHash;
1146 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 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 my $lcsh = List::Compare::SeenHash->new(\%Llist, \%Rlist);
1168 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 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 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 :1,$s/List::Compare::SeenHash/List::Compare/gc
1185 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
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
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 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 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 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 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 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 In May-June 2003, Glenn Maciag made valuable suggestions which led to
1262 changes in method names and documentation in v0.20.
1263 Another presentation at Perl Seminar New York in October 2003 prompted
1265 me to begin planning List::Compare::Functional.
1266 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 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 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 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 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 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 • Algorithm::Diff - Compute 'intelligent' differences between two
1328 files/lists (<http://search.cpan.org/dist/Algorithm-Diff/>)
1329 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 • Array::Compare - Perl extension for comparing arrays
1341 (<http://search.cpan.org/dist/Array-Compare/>)
1342 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 • Data::Compare - compare perl data structures
1354 (<http://search.cpan.org/dist/Data-Compare/>)
1355 This library compares Perl data structures recursively. Comes
1357 recommended by Slaven Rezić!
1358 • List::Util - A selection of general-utility list subroutines
1360 (<http://search.cpan.org/dist/Scalar-List-Utils/>)
1361 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 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 • 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 • Set::Scalar - basic set operations
1382 (<http://search.cpan.org/dist/Set-Scalar/>)
1383 Set::Bag - bag (multiset) class
1385 (<http://search.cpan.org/dist/Set-Bag/>)
1386 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 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 • 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 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
1412 • Syohei YOSHIDA
1413 Pull request accepted May 22 2015.
1415 • Paulo Custodio
1417 Pull request accepted June 07 2015, correcting errors in
1419 _subset_subengine().
1420
1422 There are no bug reports outstanding on List::Compare as of the most
1423 recent CPAN upload date of this distribution.
1424
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
1430 James E. Keenan (jkeenan@cpan.org). When sending correspondence,
1431 please include 'List::Compare' or 'List-Compare' in your subject line.
1432 Creation date: May 20, 2002. Last modification date: August 16 2020.
1434 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
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 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.
1463perl v5.36.0 2023-01-20 List::Compare(3)