NAME

Template::Plugin::ListCompare - Compare the elements of 2 or more lists in a TT template

VERSION

This is the POD documentation for the version 0.05 of Template::Plugin::ListCompare, written in January 2011.

SYNOPSIS

The bare essentials:

 [% Llist = ['abel', 'abel', 'baker', 'camera', 'delta', 'edward', 'fargo', 'golfer'] %]
 [% Rlist = ['baker', 'camera', 'delta', 'delta', 'edward', 'fargo', 'golfer', 'hilton'] %]

 [% USE lc = ListCompare(Llist, Rlist) %]

 [% intersection = lc.get_intersection %]
 [% union = lc.get_union %]

... and so forth.

DESCRIPTION

Regular Case: Compare Two Lists

Constructor

Create a ListCompare object. Put the two lists into arrays (named or anonymous) and pass references to the arrays to the constructor.
```
 [% Llist = ['abel', 'abel', 'baker', 'camera', 'delta', 'edward', 'fargo', 'golfer'] %]
 [% Rlist = ['baker', 'camera', 'delta', 'delta', 'edward', 'fargo', 'golfer', 'hilton'] %]

 [% USE lc = ListCompare(Llist, Rlist) %]
```
By default, ListCompare's methods return lists which are sorted using Perl's default sort mode: ASCII-betical sorting. Should you not need to have these lists sorted, you may achieve a speed boost by constructing the ListCompare object with the unsorted option:
```
 [% USE lc = ListCompare('-u', Llist, Rlist) %]
```
or [% USE lc = ListCompare('--unsorted', Llist, Rlist) %]
Alternative Constructor

If you prefer a more explicit delineation of the types of arguments passed to a function, you may use this 'single hashref' kind of constructor to build a ListCompare object:
```
 [% USE lc = ListCompare({lists => [Llist, Rlist]}) %]
```
or
```
 [% USE lc = ListCompare({
   lists => [Llist, Rlist],
   unsorted => 1,
 }) %]
```
get_intersection()

Get those items which appear at least once in both lists (their intersection).
```
 [% intersection = lc.get_intersection %]
```
get_union()

Get those items which appear at least once in either list (their union).
```
 [% union = lc.get_union %]
```
get_unique()

Get those items which appear (at least once) only in the first list.
```
 [% Lonly = lc.get_unique %]
 [% Lonly = lc.get_Lonly # alias %]
```
get_complement()

Get those items which appear (at least once) only in the second list.
```
 [% Ronly = lc.get_complement %]
 [% Ronly = lc.get_Ronly # alias %]
```

get_symmetric_difference()

Get those items which appear at least once in either the first or the second list, but not both.

 [% LorRonly = lc.get_symmetric_difference %]
 [% LorRonly = lc.get_symdiff # alias %]
 [% LorRonly = lc.get_LorRonly # alias %]

get_bag()

Make a bag of all those items in both lists. The bag differs from the union of the two lists in that it holds as many copies of individual elements as appear in the original lists.
```
 [% bag = lc.get_bag %]
```

Return references rather than lists

These methods are kept in Template::Plugin::ListCompare for symetry with List::Compare but they are not useful.

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

 [% intersection_ref = lc.get_intersection_ref %]
[% union_ref = lc.get_union_ref %]
[% Lonly_ref = lc.get_unique_ref %]
[% Lonly_ref = lc.get_Lonly_ref # alias %]
[% Ronly_ref = lc.get_complement_ref %]
[% Ronly_ref = lc.get_Ronly_ref # alias %]
[% LorRonly_ref = lc.get_symmetric_difference_ref %]
[% LorRonly_ref = lc.get_symdiff_ref # alias %]
[% LorRonly_ref = lc.get_LorRonly_ref # alias %]
[% bag_ref = lc.get_bag_ref %]

is_LsubsetR()

Return a true value if the first argument passed to the constructor ('L' for 'left') is a subset of the second argument passed to the constructor ('R' for 'right').
```
 [% LR = lc.is_LsubsetR %]
```
Return a true value if R is a subset of L.
```
 [% RL = lc.is_RsubsetL %]
```
is_LequivalentR()

Return a true value if the two lists passed to the constructor are equivalent, i.e. if every element in the left-hand list ('L') appears at least once in the right-hand list ('R') and vice versa.
```
 [% eqv = lc.is_LequivalentR %]
 [% eqv = lc.is_LeqvlntR # alias %]
```
is_LdisjointR()

Return a true value if the two lists passed to the constructor are disjoint, i.e. if the two lists have zero elements in common (or, what is the same thing, if their intersection is an empty set).
```
 [% disj = lc.is_LdisjointR %]
```
print_subset_chart()

Pretty-print a chart showing whether one list is a subset of the other.
```
 [% c.print_subset_chart %]
```
print_equivalence_chart()

Pretty-print a chart showing whether the two lists are equivalent (same elements found at least once in both).
```
 [% lc.print_equivalence_chart %]
```
is_member_which()

Determine in which (if any) of the lists passed to the constructor a given string can be found. In list context, return a list of those indices in the constructor's argument list corresponding to lists holding the string being tested.
```
 [% memb_arr = lc.is_member_which('abel') %]
```
In the example above, @memb_arr will be:
```
 ( 0 )
```
because 'abel' is found only in @Al which holds position 0 in the list of arguments passed to new().

In scalar context, the return value is the number of lists passed to the constructor in which a given string is found.

As with other ListCompare methods which return a list, you may wish the above method returned a (scalar) reference to an array holding the list:
```
 [% memb_arr_ref = lc.is_member_which_ref('baker') %]
```
In the example above, $memb_arr_ref will be:
```
 [ 0, 1 ]
```
because 'baker' is found in @Llist and @Rlist, which hold positions 0 and 1, respectively, in the list of arguments passed to new().

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

Determine in which (if any) of the lists passed to the constructor one or more given strings can be found. The strings to be tested are placed in an array (named or anonymous); a reference to that array is passed to the method.
```
 [% memb_hash_ref = lc.are_members_which(['abel', 'baker', 'fargo', 'hilton', 'zebra']) %]
```
The return value is a reference to a hash of arrays. The key for each element in this hash is the string being tested. Each element's value is a reference to an anonymous array whose elements are those indices in the constructor's argument list corresponding to lists holding the strings being tested. In the examples above, $memb_hash_ref will be:
```
 {
  abel => [0],
  baker => [0, 1],
  fargo => [0, 1],
  hilton => [1],
  zebra => [],
 }
```
Note: are_members_which() can take more than one argument; is_member_which() and is_member_which_ref() each take only one argument. Unlike those two methods, are_members_which() returns a hash reference.
is_member_any()

Determine whether a given string can be found in any of the lists passed as arguments to the constructor. Return 1 if a specified string can be found in any of the lists and 0 if not.
```
 [% found = lc.is_member_any('abel') %]
```
In the example above, $found will be 1 because 'abel' is found in one or more of the lists passed as arguments to new().
are_members_any()

Determine whether a specified string or strings can be found in any of the lists passed as arguments to the constructor. The strings to be tested are placed in an array (named or anonymous); a reference to that array is passed to are_members_any.
```
 [% memb_hash_ref = lc.are_members_any(['abel', 'baker', 'fargo', 'hilton', 'zebra']) %]
```
The return value is a reference to a hash where an element's key is the string being tested and the element's value is 1 if the string can be found in any of the lists and 0 if not. In the examples above, $memb_hash_ref will be:
```
 {
  abel => 1,
  baker => 1,
  fargo => 1,
  hilton => 1,
  zebra => 0,
 }
```
zebra's value is 0 because zebra is not found in either of the lists passed as arguments to new().
get_version()

Return current Template::Plugin::ListCompare version number.
```
 [% vers = lc.get_version %]
```

Accelerated Case: When User Only Wants a Single Comparison

Constructor

If you are certain that you will only want the results of a single comparison, computation may be accelerated by passing '-a' or '--accelerated as the first argument to the constructor.
```
 [% Llist = ['abel', 'abel', 'baker', 'camera', 'delta', 'edward', 'fargo', 'golfer'] %]
 [% Rlist = ['baker', 'camera', 'delta', 'delta', 'edward', 'fargo', 'golfer', 'hilton'] %]

 [% USE lca = ListCompare('-a', Llist, Rlist) %]
```
or
```
 [% USE lca = ListCompare('--accelerated', Llist, Rlist) %]
```
As with ListCompare's Regular case, should you not need to have a sorted list returned by an accelerated ListCompare method, you may achieve a speed boost by constructing the accelerated ListCompare object with the unsorted option:
```
 [% USE lca = ListCompare('-u', '-a', Llist, Rlist) %]
```
or
```
 [% USE lca = ListCompare('--unsorted', '--accelerated', Llist, Rlist) %]
```

Alternative Constructor

You may use the 'single hashref' constructor format to build a ListCompare object calling for the Accelerated mode:

 [% USE lca = ListCompare({
   lists => [Llist, Rlist],
   accelerated => 1,
 }) %]

 [% USE lca = ListCompare({
   lists => [Llist, Rlist],
   accelerated => 1,
   unsorted => 1,
 }) %]

Methods

All the comparison methods available in the Regular case are available to you in the Accelerated case as well.

 [% intersection = lca.get_intersection %]
 [% union = lca.get_union %]
 [% Lonly = lca.get_unique %]
 [% Ronly = lca.get_complement %]
 [% LorRonly = lca.get_symmetric_difference %]
 [% bag = lca.get_bag %]
 [% intersection_ref = lca.get_intersection_ref %]
 [% union_ref = lca.get_union_ref %]
 [% Lonly_ref = lca.get_unique_ref %]
 [% Ronly_ref = lca.get_complement_ref %]
 [% LorRonly_ref = lca.get_symmetric_difference_ref %]
 [% bag_ref = lca.get_bag_ref %]
 [% LR = lca.is_LsubsetR %]
 [% RL = lca.is_RsubsetL %]
 [% eqv = lca.is_LequivalentR %]
 [% disj = lca.is_LdisjointR %]
 [% lca.print_subset_chart %]
 [% lca.print_equivalence_chart %]
 [% memb_arr = lca.is_member_which('abel') %]
 [% memb_arr_ref = lca.is_member_which_ref('baker') %]
 [% memb_hash_ref = lca.are_members_which(['abel', 'baker', 'fargo', 'hilton', 'zebra']) %]
 [% found = lca.is_member_any('abel') %]
[% memb_hash_ref = lca.are_members_any(['abel', 'baker', 'fargo', 'hilton', 'zebra']) %]
 [% vers = lca.get_version %]

All the aliases for methods available in the Regular case are available to you in the Accelerated case as well.

Multiple Case: Compare Three or More Lists

Constructor

Create a ListCompare object. Put each list into an array and pass references to the arrays to the constructor.

 [% Al = ['abel', 'abel', 'baker', 'camera', 'delta', 'edward', 'fargo', 'golfer'] %]
 [% Bob = ['baker', 'camera', 'delta', 'delta', 'edward', 'fargo', 'golfer', 'hilton'] %]
 [% Carmen = ['fargo', 'golfer', 'hilton', 'icon', 'icon', 'jerky', 'kappa'] %]
 [% Don = ['fargo', 'icon', 'jerky'] %]
 [% Ed = ['fargo', 'icon', 'icon', 'jerky'] %]

 [% USE lcm = ListCompare(Al, Bob, Carmen, Don, Ed) %]

As with ListCompare's Regular case, should you not need to have a sorted list returned by a List::Compare method, you may achieve a speed boost by constructing the object with the unsorted option:

 [% USE lcm = ListCompare('-u', Al, Bob, Carmen, Don, Ed) %]

 [% USE lcm = ListCompare('--unsorted', Al, Bob, Carmen, Don, Ed) %]

Alternative Constructor

You may use the 'single hashref' constructor format to build a ListCompare object to process three or more lists at once:

 [% USE lcm = ListCompare({
   lists => [Al, Bob, Carmen, Don, Ed],
 }) %]

 [% USE lcm = ListCompare({
   lists => [Al, Bob, Carmen, Don, Ed],
   unsorted => 1,
 }) %]

Multiple Mode Methods Analogous to Regular and Accelerated Mode Methods

Each ListCompare method available in the Regular and Accelerated cases has an analogue in the Multiple case. However, the results produced usually require more careful specification.

Note: Certain of the following methods available in ListCompare's Multiple mode take optional numerical arguments where those numbers represent the index position of a particular list in the list of arguments passed to the constructor. To specify this index position correctly,
- start the count at 0 (as is customary with Perl array indices); and
- do not count any unsorted option ('-u' or '--unsorted') preceding the array references in the constructor's own argument list.
Example:
```
 [% USE lcmex = ListCompare('--unsorted', alpha, beta, gamma) %]
```
For the purpose of supplying a numerical argument to a method which optionally takes such an argument, '--unsorted' is skipped, @alpha is 0, @beta is 1, and so forth.
- get_intersection()
  
  Get those items found in each of the lists passed to the constructor (their intersection):
```
 [% intersection = lcm.get_intersection %]
```
- get_union()
  
  Get those items found in any of the lists passed to the constructor (their union):
```
 [% union = lcm.get_union %]
```
- get_unique()
  
  To get those items which appear only in one particular list, provide get_unique() with that list's index position in the list of arguments passed to the constructor (not counting any '-u' or '--unsorted' option).
  
  Example: @Carmen has index position 2 in the constructor's @_. To get elements unique to @Carmen:
```
 [% Lonly = lcm.get_unique(2) %]
```
  If no index position is passed to get_unique() it will default to 0 and report items unique to the first list passed to the constructor.
- get_complement()
  
  To get those items which appear in any list other than one particular list, provide get_complement() with that list's index position in the list of arguments passed to the constructor (not counting any '-u' or '--unsorted' option).
  
  Example: @Don has index position 3 in the constructor's @_. To get elements not found in @Don:
```
 [% Ronly = lcm.get_complement(3) %]
```
  If no index position is passed to get_complement() it will default to 0 and report items found in any list other than the first list passed to the constructor.
- get_symmetric_difference()
  
  Get those items each of which appears in only one of the lists passed to the constructor (their symmetric_difference);
```
 [% LorRonly = lcm.get_symmetric_difference %]
```
- get_bag()
  
  Make a bag of all items found in any list. The bag differs from the lists' union in that it holds as many copies of individual elements as appear in the original lists.
```
 [% bag = lcm.get_bag %]
```
- Return reference instead of list
  
  These methods are kept in Template::Plugin::ListCompare for symetry with List::Compare but they are not useful.
  
  An alternative approach to the above methods: If you do not immediately require an array as the return value of the method call, but simply need a reference to an array, use one of the following parallel methods:
```
 [% intersection_ref = lcm.get_intersection_ref %]
 [% union_ref = lcm.get_union_ref %]
 [% Lonly_ref = lcm.get_unique_ref(2) %]
 [% Ronly_ref = lcm.get_complement_ref(3) %]
 [% LorRonly_ref = lcm.get_symmetric_difference_ref %]
 [% bag_ref = lcm.get_bag_ref %]
```
- is_LsubsetR()
  
  To determine whether one particular list is a subset of another list passed to the constructor, provide is_LsubsetR() with the index position of the presumed subset (ignoring any unsorted option), followed by the index position of the presumed superset.
  
  Example: To determine whether @Ed is a subset of @Carmen, call:
```
 [% LR = lcm.is_LsubsetR(4,2) %]
```
  A true value (1) is returned if the left-hand list is a subset of the right-hand list; a false value (0) is returned otherwise.
  
  If no arguments are passed, is_LsubsetR() defaults to (0,1) and compares the first two lists passed to the constructor.
- is_LequivalentR()
  
  To determine whether any two particular lists are equivalent to each other, provide is_LequivalentR with their index positions in the list of arguments passed to the constructor (ignoring any unsorted option).
  
  Example: To determine whether @Don and @Ed are equivalent, call:
```
 [% eqv = lcm.is_LequivalentR(3,4) %]
```
  A true value (1) is returned if the lists are equivalent; a false value (0) otherwise.
  
  If no arguments are passed, is_LequivalentR defaults to (0,1) and compares the first two lists passed to the constructor.
- is_LdisjointR()
  
  To determine whether any two particular lists are disjoint from each other (i.e., have no members in common), provide is_LdisjointR with their index positions in the list of arguments passed to the constructor (ignoring any unsorted option).
  
  Example: To determine whether @Don and @Ed are disjoint, call:
```
 [% disj = lcm.is_LdisjointR(3,4) %]
```
  A true value (1) is returned if the lists are equivalent; a false value (0) otherwise.
  
  If no arguments are passed, is_LdisjointR defaults to (0,1) and compares the first two lists passed to the constructor.
- print_subset_chart()
  
  Pretty-print a chart showing the subset relationships among the various source lists:
```
 [% lcm.print_subset_chart %]
```
- print_equivalence_chart()
  
  Pretty-print a chart showing the equivalence relationships among the various source lists:
```
 [% lcm.print_equivalence_chart %]
```
- is_member_which()
  
  Determine in which (if any) of the lists passed to the constructor a given string can be found. In list context, return a list of those indices in the constructor's argument list (ignoring any unsorted option) corresponding to i lists holding the string being tested.
```
 [% memb_arr = lcm.is_member_which('abel') %]
```
  In the example above, @memb_arr will be:
```
 (0)
```
  because 'abel' is found only in @Al which holds position 0 in the list of arguments passed to new().
- is_member_which_ref()
  
  As with other ListCompare methods which return a list, you may wish the above method returned a (scalar) reference to an array holding the list:
```
 [% memb_arr_ref = lcm.is_member_which_ref('jerky') %]
```
  In the example above, $memb_arr_ref will be:
```
 [3, 4]
```
  because 'jerky' is found in @Don and @Ed, which hold positions 3 and 4, respectively, in the list of arguments passed to new().
  
  Note: methods is_member_which() and is_member_which_ref test only one string at a time and hence take only one argument. To test more than one string at a time see the next method, are_members_which().
- are_members_which()
  
  Determine in which (if any) of the lists passed to the constructor one or more given strings can be found. The strings to be tested are placed in an anonymous array, a reference to which is passed to the method.
```
 [% memb_hash_ref = lcm.are_members_which(['abel', 'baker', 'fargo', 'hilton', 'zebra']) %]
```
  The return value is a reference to a hash of arrays. The key for each element in this hash is the string being tested. Each element's value is a reference to an anonymous array whose elements are those indices in the constructor's argument list corresponding to lists holding the strings being tested.
  
  In the two examples above, $memb_hash_ref will be:
```
 {
   abel => [0],
   baker => [0, 1],
   fargo => [0, 1, 2, 3, 4],
   hilton => [1, 2],
   zebra => [],
 }
```
  Note: are_members_which() can take more than one argument; is_member_which() and is_member_which_ref() each take only one argument. are_members_which() returns a hash reference; the other methods return either a list or a reference to an array holding that list, depending on context.
- is_member_any()
  
  Determine whether a given string can be found in any of the lists passed as arguments to the constructor.
```
 [% found = lcm.is_member_any('abel') %]
```
  Return 1 if a specified string can be found in any of the lists and 0 if not.
  
  In the example above, $found will be 1 because 'abel' is found in one or more of the lists passed as arguments to new().
- are_members_any()
  
  Determine whether a specified string or strings can be found in any of the lists passed as arguments to the constructor. The strings to be tested are placed in an array (anonymous or named), a reference to which is passed to the method.
```
 [% memb_hash_ref = lcm.are_members_any(['abel', 'baker', 'fargo', 'hilton', 'zebra']) %]
```
  The return value is a reference to a hash where an element's key is the string being tested and the element's value is 1 if the string can be found in any of the lists and 0 if not. In the two examples above, $memb_hash_ref will be:
```
 {
   abel => 1,
   baker => 1,
   fargo => 1,
   hilton => 1,
   zebra => 0,
 }
```
  zebra's value will be 0 because zebra is not found in any of the lists passed as arguments to new().
- get_version()
  
  Return current ListCompare version number:
```
 [% vers = lcm.get_version %]
```
Multiple Mode Methods Not Analogous to Regular and Accelerated Mode Methods
- get_nonintersection()
  
  Get those items found in any of the lists passed to the constructor which do not appear in all of the lists (i.e., all items except those found in the intersection of the lists):
```
 [% nonintersection = lcm.get_nonintersection %]
```
- get_shared()
  
  Get those items which appear in more than one of the lists passed to the constructor (i.e., all items except those found in their symmetric difference);
```
 [% shared = lcm.get_shared %]
```
- get_nonintersection_ref()
  
  If you only need a reference to an array as a return value rather than a full array, use the following alternative methods:
```
 [% nonintersection_ref = lcm.get_nonintersection_ref %]
 [% shared_ref = lcm.get_shared_ref %]
```
- get_unique_all()
  
  Get a reference to an array of array references where each of the interior arrays holds the list of those items unique to the list passed to the constructor with the same index position.
```
 [% unique_all_ref = lcm.get_unique_all %]
```
  In the example above, $unique_all_ref will hold:
```
 [
   ['abel'],
   [],
   ['jerky'],
   [],
   [],
 ]
```
- get_complement_all()
  
  Get a reference to an array of array references where each of the interior arrays holds the list of those items in the complement to the list passed to the constructor with the same index position.
```
 [% complement_all_ref = lcm.get_complement_all %]
```
  In the example above, $complement_all_ref will hold:
```
 [
   ['hilton', 'icon', 'jerky'],
   ['abel', 'icon', 'jerky'],
   ['abel', 'baker', 'camera', 'delta', 'edward'],
   ['abel', 'baker', 'camera', 'delta', 'edward', 'jerky'],
   ['abel', 'baker', 'camera', 'delta', 'edward', 'jerky'],
 ]
```

Multiple Accelerated Case: Compare Three or More Lists but Request Only a Single Comparison among the Lists

Constructor

If you are certain that you will only want the results of a single comparison among three or more lists, computation may be accelerated by passing '-a' or '--accelerated as the first argument to the constructor.
```
 [% Al = ['abel', 'abel', 'baker', 'camera', 'delta', 'edward', 'fargo', 'golfer'] %]
 [% Bob = ['baker', 'camera', 'delta', 'delta', 'edward', 'fargo', 'golfer', 'hilton'] %]
 [% Carmen = ['fargo', 'golfer', 'hilton', 'icon', 'icon', 'jerky', 'kappa'] %]
 [% Don = ['fargo', 'icon', 'jerky'] %]
 [% Ed = ['fargo', 'icon', 'icon', 'jerky'] %]

 [% USE lcma = ListCompare('-a', Al, Bob, Carmen, Don, Ed) %]
```
As with ListCompare's other cases, should you not need to have a sorted list returned by a ListCompare method, you may achieve a speed boost by constructing the object with the unsorted option:
```
 [% USE lcma = ListCompare('-u', '-a', Al, Bob, Carmen, Don, Ed) %]
```
or
```
 [% USE lcma = ListCompare('--unsorted', '--accelerated', Al, Bob, Carmen, Don, Ed) %]
```
As was the case with ListCompare's Multiple mode, do not count the unsorted option ('-u' or '--unsorted') or the accelerated option ('-a' or '--accelerated') when determining the index position of a particular list in the list of array references passed to the constructor.

Example:
```
 [% USE lcmaex = ListCompare('--unsorted', '--accelerated', alpha, beta, gamma) %]
```

Alternative Constructor

The 'single hashref' format may be used to construct a ListCompare object which calls for accelerated processing of three or more lists at once:

 [% USE lcmaex = ListCompare({
   accelerated => 1,
   lists => [alpha, beta, gamma],
 }) %]

 [% USE lcmaex = ListCompare({
   unsorted => 1,
   accelerated => 1,
   lists => [alpha, beta, gamma],
 }) %]

Methods

For the purpose of supplying a numerical argument to a method which optionally takes such an argument, '--unsorted' and '--accelerated are skipped, @alpha is 0, @beta is 1, and so forth. To get a list of those items unique to @gamma, you would call:
```
 [% gamma_only = lcmaex.get_unique(2) %]
```

Passing Seen-hashes to the Constructor Instead of Arrays

When Seen-Hashes Are Already Available to You

Suppose that in a particular Perl program, you had to do extensive munging of data from an external source and that, once you had correctly parsed a line of data, it was easier to assign that datum to a hash than to an array. More specifically, suppose that you used each datum as the key to an element of a lookup table in the form of a seen-hash:
```
 [% Llist = ( #array
   abel => 2,
   baker => 1,
   camera => 1,
   delta => 1,
   edward => 1,
   fargo => 1,
   golfer => 1,
 ) %]

 [% Rlist = ( #hash
   baker => 1,
   camera => 1,
   delta => 2,
   edward => 1,
   fargo => 1,
   golfer => 1,
   hilton => 1,
 ) %]
```
In other words, suppose it was more convenient to compute a lookup table implying a list than to compute that list explicitly.

Since in almost all cases ListCompare takes the elements in the arrays passed to its constructor and internally assigns them to elements in a seen-hash, why shouldn't you be able to pass (references to) seen-hashes directly to the constructor and avoid unnecessary array assignments before the constructor is called?
Constructor

You can now do so:

[% USE lcsh = ListCompare(Llist, Rlist);

Methods

All of ListCompare's output methods are supported without further modification when references to seen-hashes are passed to the constructor.

 [% intersection = lcsh.get_intersection %]
 [% union = lcsh.get_union %]
 [% Lonly = lcsh.get_unique %]
 [% Ronly = lcsh.get_complement %]
 [% LorRonly = lcsh.get_symmetric_difference %]
 [% bag = lcsh.get_bag %]
 [% intersection_ref = lcsh.get_intersection_ref %]
 [% union_ref = lcsh.get_union_ref %]
 [% Lonly_ref = lcsh.get_unique_ref %]
 [% Ronly_ref = lcsh.get_complement_ref %]
 [% LorRonly_ref = lcsh.get_symmetric_difference_ref %]
 [% bag_ref = lcsh.get_bag_ref %]
 [% LR = lcsh.is_LsubsetR %]
 [% RL = lcsh.is_RsubsetL %]
 [% eqv = lcsh.is_LequivalentR %]
 [% disj = lcsh.is_LdisjointR %]
 [% lcsh.print_subset_chart %]
 [% lcsh.print_equivalence_chart %]
 [% memb_arr = lsch.is_member_which('abel') %]
 [% memb_arr_ref = lsch.is_member_which_ref('baker') %]
 [% memb_hash_ref = lsch.are_members_which(['abel', 'baker', 'fargo', 'hilton', 'zebra']) %]
 [% found = lsch.is_member_any('abel') %]
 [% memb_hash_ref = lsch.are_members_any(['abel', 'baker', 'fargo', 'hilton', 'zebra']) %]
 [% vers = lcsh.get_version %]
 [% unique_all_ref = lcsh.get_unique_all() %]
 [% complement_all_ref = lcsh.get_complement_all() %]

Accelerated Mode and Seen-Hashes

To accelerate processing when you want only a single comparison among two or more lists, you can pass '-a' or '--accelerated to the constructor before passing references to seen-hashes.
```
 [% USE lcsha = ListCompare('-a', Llist, Rlist) #2 hashes %]
```
To compare three or more lists simultaneously, pass three or more references to seen-hashes. Thus,
```
 [% USE lcshm = ListCompare(Alpha, Beta, Gamma) # 3 hashes %]
```
will generate meaningful comparisons of three or more lists simultaneously.
Unsorted Results and Seen-Hashes

If you do not need sorted lists returned, pass '-u' or --unsorted to the constructor before passing references to seen-hashes.
```
 [% USE lcshu = ListCompare('-u', Llist, Rlist) %]
 [% USE lcshau = ListCompare('-u', '-a', Llist, Rlist) %]
 [% USE lcshmu = ListCompare('--unsorted', Alpha, Beta, Gamma) %]
```
As was true when we were using ListCompare's Multiple and Multiple Accelerated modes, do not count any unsorted or accelerated option when determining the array index of a particular seen-hash reference passed to the constructor.

Alternative Constructor

The 'single hashref' form of constructor is also available to build ListCompare objects where seen-hashes are used as arguments:

 [% USE lcshu = ListCompare({
   unsorted => 1,
   lists => [Llist, Rlist],
 }) %]

 [% USE lcshau = ListCompare({
   unsorted => 1,
   accelerated => 1,
   lists => [Llist, Rlist],
 }) %]

 [% USE lcshmu = ListCompare({
   unsorted => 1,
   lists => [Alpha, Beta, Gamma],
 }) %]

PRINCIPLES

ListCompare is a Template-Toolkit plugin that offers access to List::Compare module. Even this POD documentation mirrors the documentation of List::Compare. (I hope all the methods work fine when used in a TT template.)

SUBROUTINES/METHODS

new()

The object constructor new() shouldn't be specified explicitly because it is called automaticly when using [% USE lc = ListCompare(Llist, Rlist) %].
get_version()

The method get_version was overwritten for beeing able to provide the version of Template::Plugin::ListCompare and not the version of underlying List::Compare.

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

No configuration needed.

DEPENDENCIES

Template::Plugin, List::Compare

INCOMPATIBILITIES

No known incompatibilities

AUTHOR

Octavian Rasnita, <orasnita at gmail.com>

BUGS AND LIMITATIONS

Please report any bugs or feature requests to bug-template-plugin-listcompare at rt.cpan.org, or through the web interface at

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Plugin-ListCompare.

I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Template::Plugin::ListCompare

You can also look for information at:

RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Template-Plugin-ListCompare
AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Template-Plugin-ListCompare
CPAN Ratings

http://cpanratings.perl.org/d/Template-Plugin-ListCompare
Search CPAN

http://search.cpan.org/dist/Template-Plugin-ListCompare/

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

To install Template::Plugin::ListCompare, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Template::Plugin::ListCompare

CPAN shell

perl -MCPAN -e shell
install Template::Plugin::ListCompare

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

Regular Case: Compare Two Lists

Accelerated Case: When User Only Wants a Single Comparison

Multiple Case: Compare Three or More Lists

Multiple Accelerated Case: Compare Three or More Lists but Request Only a Single Comparison among the Lists

Passing Seen-hashes to the Constructor Instead of Arrays

PRINCIPLES

SUBROUTINES/METHODS

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

SEE ALSO

INCOMPATIBILITIES

AUTHOR

BUGS AND LIMITATIONS

SUPPORT

LICENSE AND COPYRIGHT

Module Install Instructions