1List::Compare::FunctionUasle(r3)Contributed Perl DocumenLtiastti:o:nCompare::Functional(3)
2
6 List::Compare::Functional - Compare elements of two or more lists
7
9 This document refers to version 0.33 of List::Compare::Functional.
10 This version was released February 19, 2006. The first released ver‐
11 sion of List::Compare::Functional was v0.21. Its version numbers are
12 set to be consistent with the other parts of the List::Compare distri‐
13 bution.
14 Notice of Interface Changes
16 Certain significant changes to the interface to List::Compare::Func‐
18 tional were made with the introduction of Version 0.25 in April 2004.
19 The documentation immediately below reflects those changes, so if you
20 are first using this module with that or a later version, simply read
21 and follow the documentation below. If, however, you used List::Com‐
22 pare::Functional prior to that version, see the discussion of interface
23 changes farther below: April 2004 Change of Interface.
24
26 Getting Started
27 List::Compare::Functional exports no subroutines by default.
29 use List::Compare::Functional qw(:originals :aliases);
31 will import all publicly available subroutines from List::Com‐
33 pare::Functional. The model for importing just one subroutine from
34 List::Compare::Functional is:
35 use List::Compare::Functional qw( get_intersection );
37 It will probably be most convenient for the user to import functions by
39 using one of the two following export tags:
40 use List::Compare::Functional qw(:main :mainrefs);
42 The assignment of the various comparison functions to export tags is
44 discussed below.
45 For clarity, we shall begin by discussing comparisons of just two lists
47 at a time. Farther below, we shall discuss comparisons among three or
48 more lists at a time.
49 Comparing Two Lists Held in Arrays
51 · Given two lists:
53 @Llist = qw(abel abel baker camera delta edward fargo golfer);
55 @Rlist = qw(baker camera delta delta edward fargo golfer hilton);
56 · Get those items which appear at least once in both lists (their
58 intersection).
59 @intersection = get_intersection( [ \@Llist, \@Rlist ] );
61 Note that you could place the references to the lists being com‐
63 pared into a named array and then pass "get_intersection()" a ref‐
64 erence to that array.
65 @to_be_compared = ( \@Llist, \@Rlist );
67 @intersection = get_intersection( \@to_be_compared );
68 Beginning with version 0.29 (May 2004), List::Compare::Functional
70 now offers an additional way of passing arguments to its various
71 functions. If you prefer to see a more explicit delineation among
72 the types of arguments passed to a function, pass a single hash
73 reference which holds the lists being compared in an anonymous
74 array which is the value corresponding to key "lists":
75 @intersection = get_intersection( {
77 lists => [ \@Llist, \@Rlist ],
78 } );
79 · Get those items which appear at least once in either list (their
81 union).
82 @union = get_union( [ \@Llist, \@Rlist ] );
84 or
86 @union = get_union( { lists => [ \@Llist, \@Rlist ] } );
88 · Get those items which appear (at least once) only in the first
90 list.
91 @Lonly = get_unique( [ \@Llist, \@Rlist ] );
93 or
95 @Lonly = get_unique( { lists => [ \@Llist, \@Rlist ] } );
97 · Get those items which appear (at least once) only in the second
99 list.
100 @Ronly = get_complement( [ \@Llist, \@Rlist ] );
102 or
104 @Ronly = get_complement( { lists => [ \@Llist, \@Rlist ] } );
106 ·
108 @LorRonly = get_symmetric_difference( [ \@Llist, \@Rlist ] );
109 @LorRonly = get_symdiff( [ \@Llist, \@Rlist ] ); # alias
111 or
113 @LorRonly = get_symmetric_difference( { lists => [ \@Llist, \@Rlist ] } );
115 · Make a bag of all those items in both lists. The bag differs from
117 the union of the two lists in that it holds as many copies of indi‐
118 vidual elements as appear in the original lists.
119 @bag = get_bag( [ \@Llist, \@Rlist ] );
121 or
123 @bag = get_bag( { lists => [ \@Llist, \@Rlist ] } );
125 · An alternative approach to the above functions: If you do not
127 immediately require an array as the return value of the function
128 call, but simply need a reference to an (anonymous) array, use one
129 of the following parallel functions:
130 $intersection_ref = get_intersection_ref( [ \@Llist, \@Rlist ] );
132 $union_ref = get_union_ref( [ \@Llist, \@Rlist ] );
133 $Lonly_ref = get_unique_ref( [ \@Llist, \@Rlist ] );
134 $Ronly_ref = get_complement_ref( [ \@Llist, \@Rlist ] );
135 $LorRonly_ref = get_symmetric_difference_ref( [ \@Llist, \@Rlist ] );
136 $LorRonly_ref = get_symdiff_ref( [ \@Llist, \@Rlist ] );
137 # alias
138 $bag_ref = get_bag_ref( [ \@Llist, \@Rlist ] );
139 or
141 $intersection_ref =
143 get_intersection_ref( { lists => [ \@Llist, \@Rlist ] } );
144 $union_ref =
145 get_union_ref( { lists => [ \@Llist, \@Rlist ] } );
146 $Lonly_ref =
147 get_unique_ref( { lists => [ \@Llist, \@Rlist ] } );
148 $Ronly_ref =
149 get_complement_ref( { lists => [ \@Llist, \@Rlist ] } );
150 $LorRonly_ref =
151 get_symmetric_difference_ref( { lists => [ \@Llist, \@Rlist ] } );
152 $LorRonly_ref =
153 get_symdiff_ref( { lists => [ \@Llist, \@Rlist ] } );
154 # alias
155 $bag_ref =
156 get_bag_ref( { lists => [ \@Llist, \@Rlist ] } );
157 · Return a true value if the first list ('L' for 'left') is a subset
159 of the second list ('R' for 'right').
160 $LR = is_LsubsetR( [ \@Llist, \@Rlist ] );
162 or
164 $LR = is_LsubsetR( { lists => [ \@Llist, \@Rlist ] } );
166 · Return a true value if R is a subset of L.
168 $RL = is_RsubsetL( [ \@Llist, \@Rlist ] );
170 or
172 $RL = is_RsubsetL( { lists => [ \@Llist, \@Rlist ] } );
174 · Return a true value if L and R are equivalent, i.e., if every ele‐
176 ment in L appears at least once in R and vice versa.
177 $eqv = is_LequivalentR( [ \@Llist, \@Rlist ] );
179 $eqv = is_LeqvlntR( [ \@Llist, \@Rlist ] ); # alias
180 or
182 $eqv = is_LequivalentR( { lists => [ \@Llist, \@Rlist ] } );
184 · Return a true value if L and R are disjoint, i.e., if L and R have
186 no common elements.
187 $disj = is_LdisjointR( [ \@Llist, \@Rlist ] );
189 or
191 $disj = is_LdisjointR( { lists => [ \@Llist, \@Rlist ] } );
193 · Pretty-print a chart showing whether one list is a subset of the
195 other.
196 print_subset_chart( [ \@Llist, \@Rlist ] );
198 or
200 print_subset_chart( { lists => [ \@Llist, \@Rlist ] } );
202 · Pretty-print a chart showing whether the two lists are equivalent
204 (same elements found at least once in both).
205 print_equivalence_chart( [ \@Llist, \@Rlist ] );
207 or
209 print_equivalence_chart( { lists => [ \@Llist, \@Rlist ] } );
211 · Determine in which (if any) of the lists a given string can be
213 found. In list context, return a list of those indices in the
214 argument list corresponding to lists holding the string being
215 tested.
216 @memb_arr = is_member_which( [ \@Llist, \@Rlist ] , [ 'abel' ] );
218 or
220 @memb_arr = is_member_which( {
222 lists => [ \@Llist, \@Rlist ], # value is array reference
223 item => 'abel', # value is string
224 } );
225 In the example above, @memb_arr will be:
227 ( 0 )
229 because 'abel' is found only in @Al which holds position 0 in the
231 list of arguments passed to "new()".
232 · As with other List::Compare::Functional functions which return a
234 list, you may wish the above function returned a (scalar) reference
235 to an array holding the list:
236 $memb_arr_ref = is_member_which_ref( [ \@Llist, \@Rlist ] , [ 'baker' ] );
238 or
240 $memb_arr_ref = is_member_which_ref( {
242 lists => [ \@Llist, \@Rlist ], # value is array reference
243 item => 'baker', # value is string
244 } );
245 In the example above, $memb_arr_ref will be:
247 [ 0, 1 ]
249 because 'baker' is found in @Llist and @Rlist, which hold positions
251 0 and 1, respectively, in the list of arguments passed to "new()".
252 Note: functions "is_member_which()" and "is_member_which_ref" test
254 only one string at a time and hence take only one argument. To
255 test more than one string at a time see the next function,
256 "are_members_which()".
257 · Determine in "which" (if any) of the lists passed as arguments one
259 or more given strings can be found. The lists beings searched are
260 placed in an array, a reference to which is the first argument
261 passed to "are_members_which()". The strings to be tested are also
262 placed in an array, a reference to which is the second argument
263 passed to that function.
264 $memb_hash_ref =
266 are_members_which( [ \@Llist, \@Rlist ] ,
267 [ qw⎪ abel baker fargo hilton zebra ⎪ ]
268 );
269 or
271 $memb_hash_ref = are_members_which( {
273 lists => [ \@Llist, \@Rlist ], # value is arrayref
274 items => [ qw⎪ abel baker fargo hilton zebra ⎪ ], # value is arrayref
275 } );
276 The return value is a reference to a hash of arrays. The key for
278 each element in this hash is the string being tested. Each ele‐
279 ment's value is a reference to an anonymous array whose elements
280 are those indices in the constructor's argument list corresponding
281 to lists holding the strings being tested. In the examples above,
282 $memb_hash_ref will be:
283 {
285 abel => [ 0 ],
286 baker => [ 0, 1 ],
287 fargo => [ 0, 1 ],
288 hilton => [ 1 ],
289 zebra => [ ],
290 };
291 Note: "are_members_which()" can take more than one argument;
293 "is_member_which()" and "is_member_which_ref()" each take only one
294 argument. Unlike those functions, "are_members_which()" returns a
295 hash reference.
296 · Determine whether a given string can be found in any of the lists
298 passed as arguments. Return 1 if a specified string can be found
299 in any of the lists and 0 if not.
300 $found = is_member_any( [ \@Llist, \@Rlist ] , [ 'abel' ] );
302 or
304 $found = is_member_any( {
306 lists => [ \@Llist, \@Rlist ], # value is array reference
307 item => 'abel', # value is string
308 } );
309 In the example above, $found will be 1 because 'abel' is found in
311 one or more of the lists passed as arguments to "new()".
312 · Determine whether a specified string or strings can be found in any
314 of the lists passed as arguments. The lists beings searched are
315 placed in an array, a reference to which is the first argument
316 passed to "are_members_any()". The strings to be tested are also
317 placed in an array, a reference to which is the second argument
318 passed to that function.
319 $memb_hash_ref =
321 are_members_any( [ \@Llist, \@Rlist ] ,
322 [ qw⎪ abel baker fargo hilton zebra ⎪ ]
323 );
324 or
326 $memb_hash_ref = are_members_any( {
328 lists => [ \@Llist, \@Rlist ], # value is arrayref
329 items => [ qw⎪ abel baker fargo hilton zebra ⎪ ], # value is arrayref
330 } );
331 The return value is a reference to a hash where an element's key is
333 the string being tested and the element's value is 1 if the string
334 can be found in any of the lists and 0 if not. In the examples
335 above, $memb_hash_ref will be:
336 {
338 abel => 1,
339 baker => 1,
340 fargo => 1,
341 hilton => 1,
342 zebra => 0,
343 };
344 "zebra"'s value is 0 because "zebra" is not found in either of the
346 lists passed as arguments to "are_members_any()".
347 · Return current List::Compare::Functional version number.
349 $vers = get_version;
351 Comparing Three or More Lists Held in Arrays
353 Given five lists:
355 @Al = qw(abel abel baker camera delta edward fargo golfer);
357 @Bob = qw(baker camera delta delta edward fargo golfer hilton);
358 @Carmen = qw(fargo golfer hilton icon icon jerky kappa);
359 @Don = qw(fargo icon jerky);
360 @Ed = qw(fargo icon icon jerky);
361 · Get those items which appear at least once in each list (their
363 intersection).
364 @intersection = get_intersection( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
366 or
368 @intersection = get_intersection( {
370 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
371 } );
372 · Get those items which appear at least once in any of the lists
374 (their union).
375 @union = get_union( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
377 or
379 @union = get_union( {
380 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
381 } );
382 · To get those items which are unique to a particular list, provide
384 "get_unique()" with two array references. The first holds refer‐
385 ences to the arrays which in turn hold the individual lists being
386 compared. The second holds the index position in the first refer‐
387 ence of the particular list under consideration. Example: To get
388 elements unique to @Carmen:
389 @Lonly = get_unique(
391 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
392 [ 2 ]
393 );
394 or
396 @Lonly = get_unique( {
398 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], # value is arrayref
399 item => 2, # value is number
400 } );
401 If no index position is passed to "get_unique()" it will default to
403 0 and report items unique to the first list passed to the function.
404 Hence,
405 @Lonly = get_unique( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
407 is same as:
409 @Lonly = get_unique( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], [ 0 ] );
411 · Should you need to identify the items unique to each of the lists
413 under consideration, call "get_unique_all" and get a reference to
414 an array of array references:
415 $unique_all_ref = get_unique_all(
417 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ]
418 );
419 or
421 $unique_all_ref = get_unique_all( {
423 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
424 } );
425 · To get those items which appear only in lists other than one par‐
427 ticular list, pass two array references to the "get_complement()"
428 function. The first holds references to the arrays which in turn
429 hold the individual lists being compared. The second holds the
430 index position in the first reference of the particular list under
431 consideration. Example: to get all the elements found in lists
432 other than @Don:
433 @Ronly = get_complement(
435 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
436 [ 3 ]
437 );
438 or
440 @Ronly = get_complement( {
442 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], # value is arrayref
443 item => 3, # value is number
444 } );
445 If no index position is passed to "get_complement()" it will
447 default to 0 and report items found in all lists other than the
448 first list passed to "get_complement()".
449 @Lonly = get_complement( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
451 is same as:
453 @Lonly = get_complement( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], [ 0 ] );
455 · Should you need to identify the items not found in each of the
457 lists under consideration, call "get_complement_all" and get a ref‐
458 erence to an array of array references:
459 $complement_all_ref = get_complement_all(
461 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ]
462 );
463 or
465 $complement_all_ref = get_complement_all( {
467 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
468 } );
469 · Get those items which do not appear in more than one of several
471 lists (their symmetric_difference);
472 @LorRonly = get_symmetric_difference( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
474 @LorRonly = get_symdiff( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] ); # alias
475 or
477 @LorRonly = get_symmetric_difference( {
479 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
480 } );
481 · Get those items found in any of several lists which do not appear
483 in "all" of the lists (i.e., all items except those found in the
484 intersection of the lists):
485 @nonintersection = get_nonintersection(
487 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
488 or
490 @nonintersection = get_nonintersection( {
492 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
493 } );
494 · Get those items which appear in more than one of several lists
496 (i.e., all items except those found in their symmetric difference);
497 @shared = get_shared( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
499 or
501 @shared = get_shared( {
503 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
504 } );
505 · Make a bag of every item found in every list. The bag differs from
507 the union of the two lists in that it holds as many copies of indi‐
508 vidual elements as appear in the original lists.
509 @bag = get_bag( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
511 or
513 @bag = get_bag( {
515 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
516 } );
517 · An alternative approach to the above functions: If you do not
519 immediately require an array as the return value of the function,
520 but simply need a reference to an array, use one of the following
521 parallel functions:
522 $intersection_ref = get_intersection_ref(
524 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
525 $union_ref = get_union_ref(
526 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
527 $Lonly_ref = get_unique_ref(
528 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
529 $Ronly_ref = get_complement_ref(
530 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
531 $LorRonly_ref = get_symmetric_difference_ref(
532 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
533 $LorRonly_ref = get_symdiff_ref( # alias
534 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
535 $nonintersection_ref = get_nonintersection_ref(
536 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
537 $shared_ref = get_shared_ref(
538 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
539 $bag_ref = get_bag_ref(
540 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
541 · To determine whether one particular list is a subset of another of
543 the lists passed to the function, pass to "is_LsubsetR()" two array
544 references. The first of these is a reference to an array of array
545 references, the arrays holding the lists under consideration. The
546 second is a reference to a two-element array consisting of the
547 index of the presumed subset, followed by the index position of the
548 presumed superset. A true value (1) is returned if the first
549 (left-hand) element in the second reference list is a subset of the
550 second (right-hand) element; a false value (0) is returned other‐
551 wise.
552 Example: To determine whether @Ed is a subset of @Carmen, call:
554 $LR = is_LsubsetR(
556 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
557 [ 4, 2 ]
558 );
559 or
561 $LR = is_LsubsetR( {
563 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], # value is arrayref
564 pair => [ 4, 2 ], # value is arrayref
565 } );
566 If only the first reference (to the array of lists) is passed to
568 "is_LsubsetR", then the function's second argument defaults to
569 "(0,1)" and compares the first two lists passed to the constructor.
570 So,
571 $LR = is_LsubsetR([ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
573 ... is equivalent to:
575 $LR = is_LsubsetR([ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], [0,1] );
577 · To reverse the order in which the particular lists are evaluated
579 for superset/subset status, call "is_RsubsetL":
580 $RL = is_RsubsetL([ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], [2,4] );
582 or
584 $RL = is_RsubsetL( {
586 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
587 pair => [ 2, 4 ],
588 } );
589 · List::Compare::Functional considers two lists to be equivalent if
591 every element in one list appears at least once in R and vice
592 versa. To determine whether one particular list passed to the
593 function is equivalent to another of the lists passed to the func‐
594 tion, provide "is_LequivalentR()" with two array references. The
595 first is a reference to an array of array references, the arrays
596 holding the lists under consideration. The second of these is a
597 reference to a two-element array consisting of the two lists being
598 tested for equivalence. A true value (1) is returned if the lists
599 are equivalent; a false value (0) is returned otherwise.
600 Example: To determine whether @Don and @Ed are equivalent, call:
602 $eqv = is_LequivalentR(
604 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
605 [3,4]
606 );
607 $eqv = is_LeqvlntR( # alias
609 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
610 [3,4]
611 );
612 or
614 $eqv = is_LequivalentR( {
616 items => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
617 pair => [3,4],
618 } );
619 If no arguments are passed, "is_LequivalentR" defaults to "[0,1]"
621 and compares the first two lists passed to the function. So,
622 $eqv = is_LequivalentR( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
624 ... translates to:
626 $eqv = is_LequivalentR( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], [0,1] );
628 · To determine whether any two of the lists passed to the function
630 are disjoint from one another (i.e., have no common members), pro‐
631 vide "is_LdisjointR()" with two array references. The first is a
632 reference to an array of array references, the arrays holding the
633 lists under consideration. The second of these is a reference to a
634 two-element array consisting of the two lists being tested for dis‐
635 jointedness. A true value (1) is returned if the lists are dis‐
636 joint; a false value (0) is returned otherwise.
637 Example: To determine whether @Don and @Ed are disjoint, call:
639 $disj = is_LdisjointR(
641 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
642 [3,4]
643 );
644 or
646 $disj = is_LdisjointR( {
648 items => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
649 pair => [3,4]
650 } );
651 · Pretty-print a chart showing the subset relationships among the
653 various source lists:
654 print_subset_chart( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
656 or
658 print_subset_chart( { lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] } );
660 · Pretty-print a chart showing the equivalence relationships among
662 the various source lists:
663 print_equivalence_chart( [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] );
665 or
667 print_equivalence_chart( { lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ] } );
669 · Determine in which (if any) of several lists a given string can be
671 found. Pass two array references, the first of which holds refer‐
672 ences to arrays holding the lists under consideration, and the sec‐
673 ond of which holds a single-item list consisting of the string
674 being tested.
675 @memb_arr = is_member_which(
677 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
678 [ 'abel' ]
679 );
680 or
682 @memb_arr = is_member_which( {
684 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], # value is arrayref
685 item => 'abel', # value is string
686 } );
687 In list context, return a list of those indices in the function's
689 argument list corresponding to lists holding the string being
690 tested. In the example above, @memb_arr will be:
691 ( 0 )
693 because 'abel' is found only in @Al which holds position 0 in the
695 list of arguments passed to "is_member_which()".
696 · As with other List::Compare::Functional functions which return a
698 list, you may wish the above function returned a reference to an
699 array holding the list:
700 $memb_arr_ref = is_member_which_ref(
702 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
703 [ 'jerky' ]
704 );
705 or
707 $memb_arr_ref = is_member_which_ref( {
709 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], # value is arrayref
710 item => 'jerky', # value is string
711 } );
712 In the example above, $memb_arr_ref will be:
714 [ 3, 4 ]
716 because 'jerky' is found in @Don and @Ed, which hold positions 3
718 and 4, respectively, in the list of arguments passed to "is_mem‐
719 ber_which()".
720 Note: functions "is_member_which()" and "is_member_which_ref" test
722 only one string at a time and hence take only one element in the
723 second array reference argument. To test more than one string at a
724 time see the next function, "are_members_which()".
725 · Determine in "which" (if any) of several lists one or more given
727 strings can be found. Pass two array references, the first of
728 which holds references to arrays holding the lists under considera‐
729 tion, and the second of which holds a list of the strings being
730 tested.
731 $memb_hash_ref = are_members_which(
733 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
734 [ qw⎪ abel baker fargo hilton zebra ⎪ ]
735 );
736 or
738 $memb_hash_ref = are_members_which( {
740 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], # value is arrayref
741 items => [ qw⎪ abel baker fargo hilton zebra ⎪ ], # value is arrayref
742 } );
743 The return valus is a reference to a hash of arrays. In this hash,
745 each element's value is a reference to an anonymous array whose
746 elements are those indices in the argument list corresponding to
747 lists holding the strings being tested. In the two examples above,
748 $memb_hash_ref will be:
749 {
751 abel => [ 0 ],
752 baker => [ 0, 1 ],
753 fargo => [ 0, 1, 2, 3, 4 ],
754 hilton => [ 1, 2 ],
755 zebra => [ ],
756 };
757 Note: "are_members_which()" tests more than one string at a time.
759 Hence, its second array reference argument can take more than one
760 element. "is_member_which()" and "is_member_which_ref()" each take
761 only one element in their second array reference arguments.
762 "are_members_which()" returns a hash reference; the other functions
763 return either a list or a reference to an array holding that list,
764 depending on context.
765 · Determine whether a given string can be found in any of several
767 lists. Pass two array references, the first of which holds refer‐
768 ences to arrays holding the lists under consideration, and the sec‐
769 ond of which holds a single-item list of the string being tested.
770 $found = is_member_any(
772 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
773 [ 'abel' ]
774 );
775 or
777 $found = is_member_any( {
779 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], # value is arrayref
780 item => 'abel', # value is string
781 } );
782 The return value is 1 if a specified string can be found in any of
784 the lists and 0 if not. In the example above, $found will be 1
785 because "abel" is found in one or more of the lists passed as argu‐
786 ments to "is_member_any()".
787 · Determine whether a specified string or strings can be found in any
789 of several lists. Pass two array references, the first of which
790 holds references to arrays holding the lists under consideration,
791 and the second of which holds a list of the strings being tested.
792 $memb_hash_ref = are_members_any(
794 [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ],
795 [ qw⎪ abel baker fargo hilton zebra ⎪ ]
796 );
797 or
799 $memb_hash_ref = are_members_any( {
801 lists => [ \@Al, \@Bob, \@Carmen, \@Don, \@Ed ], # value is arrayref
802 items => [ qw⎪ abel baker fargo hilton zebra ⎪ ], # value is arrayref
803 } );
804 The return value is a reference to a hash where an element's key is
806 the string being tested and the element's value is 1 if the string
807 can be found in any of the lists and 0 if not. In the example
808 above, $memb_hash_ref will be:
809 {
811 abel => 1,
812 baker => 1,
813 fargo => 1,
814 hilton => 1,
815 zebra => 0,
816 };
817 "zebra"'s value is 0 because "zebra" is not found in any of the
819 lists passed as arguments to "are_members_any()".
820 · Return current List::Compare::Functional version number:
822 $vers = get_version;
824 Comparing Lists Held in Seen-Hashes
826 What is a seen-hash? A seen-hash is a typical Perl implementation of a
828 look-up table: a hash where the value for a given element represents
829 the number of times the element's key is observed in a list. For the
830 purposes of List::Compare::Functional, what is crucial is whether an
831 item is observed in a list or not; how many times the item occurs in a
832 list is, with one exception, irrelevant. (That exception is the
833 "get_bag()" function and its fraternal twin "get_bag_ref()". In this
834 case only, the key in each element of the seen-hash is placed in the
835 bag the number of times indicated by the value of that element.) The
836 value of an element in a List::Compare seen-hash must be a positive
837 integer, but whether that integer is 1 or 1,000,001 is immaterial for
838 all List::Compare::Functional functions except forming a bag.
839 The two lists compared above were represented by arrays; references to
841 those arrays were passed to the various List::Compare::Functional func‐
842 tions. They could, however, have been represented by seen-hashes such
843 as the following and passed in exactly the same manner to the various
844 functions.
845 %Llist = (
847 abel => 2,
848 baker => 1,
849 camera => 1,
850 delta => 1,
851 edward => 1,
852 fargo => 1,
853 golfer => 1,
854 );
855 %Rlist = (
856 baker => 1,
857 camera => 1,
858 delta => 2,
859 edward => 1,
860 fargo => 1,
861 golfer => 1,
862 hilton => 1,
863 );
864 @intersection = get_intersection( [ \%Llist, \%Rlist ] );
866 @union = get_union( [ \%Llist, \%Rlist ] );
867 @complement = get_complement( [ \%Llist, \%Rlist ] );
868 and so forth.
870 To compare three or more lists simultaneously, provide the appropriate
872 List::Compare::Functional function with a first array reference holding
873 a list of three or more references to seen-hashes. Thus,
874 @union = get_intersection( [ \%Alpha, \%Beta, \%Gamma ] );
876 The 'single hashref' format for List::Compare::Functional functions is
878 also available when passing seen-hashes as arguments. Examples:
879 @intersection = get_intersection( {
881 lists => [ \%Alpha, \%Beta, \%Gamma ],
882 } );
883 @Ronly = get_complement( {
885 lists => [ \%Alpha, \%Beta, \%Gamma ],
886 item => 3,
887 } );
888 $LR = is_LsubsetR( {
890 lists => [ \%Alpha, \%Beta, \%Gamma ],
891 pair => [ 4, 2 ],
892 } );
893 $memb_hash_ref = are_members_any( {
895 lists => [ \%Alpha, \%Beta, \%Gamma ],
896 items => [ qw⎪ abel baker fargo hilton zebra ⎪ ],
897 } );
898 Faster Results with the Unsorted Option
900 By default, List::Compare::Function functions return lists sorted in
902 Perl's default ASCII-betical mode. Sorting entails a performance cost,
903 and if you do not need a sorted list and do not wish to pay this per‐
904 formance cost, you may call the following List::Compare::Function func‐
905 tions with the 'unsorted' option:
906 @intersection = get_intersection( '-u', [ \@Llist, \@Rlist ] );
908 @union = get_union( '-u', [ \@Llist, \@Rlist ] );
909 @Lonly = get_unique( '-u', [ \@Llist, \@Rlist ] );
910 @Ronly = get_complement( '-u', [ \@Llist, \@Rlist ] );
911 @LorRonly = get_symmetric_difference('-u', [ \@Llist, \@Rlist ] );
912 @bag = get_bag( '-u', [ \@Llist, \@Rlist ] );
913 For greater readability, the option may be spelled out:
915 @intersection = get_intersection('--unsorted', [ \@Llist, \@Rlist ] );
917 or
919 @intersection = get_intersection( {
921 unsorted => 1,
922 lists => [ \@Llist, \@Rlist ],
923 } );
924 Should you need a reference to an unsorted list as the return value,
926 you may call the unsorted option as follows:
927 $intersection_ref = get_intersection_ref(
929 '-u', [ \@Llist, \@Rlist ] );
930 $intersection_ref = get_intersection_ref(
931 '--unsorted', [ \@Llist, \@Rlist ] );
932
934 General Comments
935 List::Compare::Functional is a non-object-oriented implementation of
937 very common Perl code used to determine interesting relationships
938 between two or more lists at a time. List::Compare::Functional is
939 based on the same author's List::Compare module found in the same CPAN
940 distribution. List::Compare::Functional is closely modeled on the
941 ''Accelerated'' mode in List::Compare.
942 For a discussion of the antecedents of this module, see the discussion
944 of the history and development of this module in the documentation to
945 List::Compare.
946 List::Compare::Functional's Export Tag Groups
948 By default, List::Compare::Functional exports no functions. You may
950 import individual functions into your main package but may find it more
951 convenient to import via export tag groups. Four such groups are cur‐
952 rently defined:
953 use List::Compare::Functional qw(:main)
955 use List::Compare::Functional qw(:mainrefs)
956 use List::Compare::Functional qw(:originals)
957 use List::Compare::Functional qw(:aliases)
958 · Tag group ":main" includes what, in the author's opinion, are the
960 six List::Compare::Functional subroutines mostly likely to be used:
961 get_intersection()
963 get_union()
964 get_unique()
965 get_complement()
966 get_symmetric_difference()
967 is_LsubsetR()
968 · Tag group ":mainrefs" includes five of the six subroutines found in
970 ":main" -- all except "is_LsubsetR()" -- in the form in which they
971 return references to arrays rather than arrays proper:
972 get_intersection_ref()
974 get_union_ref()
975 get_unique_ref()
976 get_complement_ref()
977 get_symmetric_difference_ref()
978 · Tag group ":originals" includes all List::Compare::Functional sub‐
980 routines in their 'original' form, i.e., no aliases for those sub‐
981 routines:
982 get_intersection
984 get_intersection_ref
985 get_union
986 get_union_ref
987 get_unique
988 get_unique_ref
989 get_unique_all
990 get_complement
991 get_complement_ref
992 get_complement_all
993 get_symmetric_difference
994 get_symmetric_difference_ref
995 get_shared
996 get_shared_ref
997 get_nonintersection
998 get_nonintersection_ref
999 is_LsubsetR
1000 is_RsubsetL
1001 is_LequivalentR
1002 is_LdisjointR
1003 is_member_which
1004 is_member_which_ref
1005 are_members_which
1006 is_member_any
1007 are_members_any
1008 print_subset_chart
1009 print_equivalence_chart
1010 get_bag
1011 get_bag_ref
1012 · Tag group ":aliases" contains all List::Compare::Functional subrou‐
1014 tines which are aliases for subroutines found in tag group ":origi‐
1015 nals". These are provided simply for less typing.
1016 get_symdiff
1018 get_symdiff_ref
1019 is_LeqvlntR
1020 April 2004 Change of Interface
1022 Note: You can skip this section unless you used List::Compare::Func‐
1024 tional prior to the release of Version 0.25 in April 2004.
1025 Version 0.25 initiated a significant change in the interface to this
1027 module's various functions. In order to be able to accommodate compar‐
1028 isons among more than two lists, it was necessary to change the type of
1029 arguments passed to the various functions. Whereas previously a typi‐
1030 cal List::Compare::Functional function would be called like this:
1031 @intersection = get_intersection( \@Llist, \@Rlist ); # SUPERSEDED
1033 ... now the references to the lists being compared must now be placed
1035 within a wrapper array (anonymous or named), a reference to which is
1036 now passed to the function, like so:
1037 @intersection = get_intersection( [ \@Llist, \@Rlist ] );
1039 ... or, alternatively:
1041 @to_be_compared = (\@Llist, \@Rlist);
1043 @intersection = get_intersection( \@to_be_compared );
1044 In a similar manner, List::Compare::Functional functions could previ‐
1046 ously take arguments in the form of references to 'seen-hashes' instead
1047 of references to arrays:
1048 @intersection = get_intersection( \%h0, \%h1 );
1050 (See above for discussion of seen-hashes.) Now, those references to
1052 seen-hashes must be placed within a wrapper array (anonymous or named),
1053 a reference to which is passed to the function, like so:
1054 @intersection = get_intersection( [ \%h0, \%h1 ] );
1056 Also, in a similar manner, some List::Compare::Functional functions
1058 previously took arguments in addition to the lists being compared.
1059 These arguments were simply passed as scalars, like this:
1060 @memb_arr = is_member_which(\@Llist, \@Rlist, 'abel');
1062 Now these arguments must also be placed within a wrapper array (anony‐
1064 mous or named), a reference to which is now passed to the function,
1065 like so:
1066 @memb_arr = is_member_which( [ \@Llist, \@Rlist ], [ 'abel' ] );
1068 ... or, alternatively:
1070 @to_be_compared = (\@Llist, \@Rlist);
1072 @opts = ( 'abel' );
1073 @memb_arr = is_member_which( \@to_be_compared, \@opts );
1074 As in previous versions, for a speed boost the user may provide the
1076 '-u' or '--unsorted' option as the first argument to some List::Com‐
1077 pare::Functional functions. Using this option, the "get_intersec‐
1078 tion()" function above would appear as:
1079 @intersection = get_intersection( '-u', [ \@Llist, \@Rlist ] );
1081 ... or, alternatively:
1083 @intersection = get_intersection( '--unsorted', [ \@Llist, \@Rlist ] );
1085 The arguments to any List::Compare::Functional function will therefore
1087 consist possibly of the unsorted option, and then of either one or two
1088 references to arrays, the first of which is a reference to an array of
1089 arrays or an array of seen-hashes.
1090
1092 James E. Keenan (jkeenan@cpan.org). When sending correspondence,
1093 please include 'List::Compare::Functional' or 'List-Compare-Functional'
1094 in your subject line.
1095 Creation date: May 20, 2002. Last modification date: February 19,
1097 2006. Copyright (c) 2002-04 James E. Keenan. United States. All
1098 rights reserved. This is free software and may be distributed under
1099 the same terms as Perl itself.
1100perl v5.8.8 2006-02-18 List::Compare::Functional(3)