view release on metacpan or  search on metacpan

lib/Array/AsObject.pod  view on Meta::CPAN

present.

=item unique

   $obj->unique();

This removes any duplicates in a list. The first occurrence of each element
is kept, and the order of those first occurrences is preserved.

=back

=head1 SET METHODS

The following methods work with two Array::AsObject objects. They apply
a set operation to the two of them and produce a value or a third
Array::AsObject object containing the results.

If an error occurs, it is set in the returned object, NOT in any of the
original objects.

The original objects are unmodified in all cases.

=over 4

=item difference

   $obj3 = $obj->difference($obj2 [,$unique]);

This takes two lists and removes the second list from the first.

By default, one occurence of every element in the second list is
removed from the first list.

If $unique is given, every element in the first list is removed.

For example, the difference of the two lists (a a b b c) and (a)
is either (a b b c) or (b b c). If $unique is non-zero, the second
is given.

It should be noted that both "b" elements in the example will be
kept regardless of the value of $unique because the $unique
flag only affects elements being removed.

=item intersection

   $obj3 = $obj->intersection($obj2 [,$unique]);

This takes two lists and finds the intersection of the two. The
intersection are elements that are in both lists. The returned
list is in the order they appear in the first list.

By default, duplicate elements are treated individually unless
$unique is passed in.

For example, the intersection of two lists (a a b b c) and (a a c d)
is either (a a c) or (a c). If $unique is non-zero, the second is
given.

=item is_equal

=item not_equal

   $flag = $obj->is_equal($obj2 [,$unique]);
   $flag = $obj->not_equal($obj2 [,$unique]);

These take two lists and test to see if they are equal. If an
error is encountered, undef is returned, but no error is stored.

The order of the elements is ignored so (a,b) = (b,a).

If $unique is non-zero, the count of each type of element is
ignored so (a,a,b) = (a,b). Otherwise, the count is important
so (a,a,b) != (a,b).

=item is_subset

=item not_subset

   $flag = $obj->is_subset($obj2 [,$unique]);
   $flag = $obj->not_subset($obj2 [,$unique]);

These return 1 if the list in $obj2 is a subset of the list in $obj
(or is NOT a subset).

If $unique is not passed in, every element in $obj2 must have an
instance in $obj. So (a a b) is a subset of (a a a b c) but NOT of
(a b c).

If $unique is passed in, every element in $obj2 must exists in $obj
but the count is unimportant, so (a a b) is a subset of (a b c).

=item symmetric_difference

   $obj3 = $obj->symmetric_difference($obj2 [,$unique]);

This takes two lists and finds the symmetric difference of the
two. The symmetric difference are elements that are in either list,
but not both. The order of the list produced are the elements from
the first object (order preserved) followed by those from the
second object.

If $unique is non-zero, one instance of an element cancels out
all of the instances in the other list.

For example, the symmetric difference between the two lists (a a b b
c) and (a c) is either (a b b) or (b b). If $unique is non-zero, the
second is used.

Note that both instances of 'b' are kept because the $unique flag
only affects elements which exist in both objects.

=item union

   $obj3 = $obj->union($obj2 [,$unique]);

This takes two lists and combines them.

By default, every element is preserved. If $unique is passed in,
the duplicates are removed.

For example, the union of the two lists (a a b) and (a c) is either
(a a b a c) or (a b c). The second is returned if $unique is non-zero.

=back

=head1 HISTORY AND RATIONALE

With several other modules out there that do various set and array
operations, a brief history of why I wrote this module is in order.

The origin of this module came when I needed better list handling
operations (especially involving lists that might contain duplicate
elements) inside of a Template::Toolkit template. The built in list
functions in Template::Toolkit weren't sufficent for my needs, so I
looked around.

The module that came closest to my needs was Set::Array. Although not
a perfect match for what I wanted (I really wanted better support for
lists with duplicate elements), it came close enough, so I wrote a
wrapper module (Template::Plugin::ListOps) around it to do most of