view release on metacpan or  search on metacpan

README  view on Meta::CPAN

           @vals = $obj->splice([$start,] [$length,] [@list]);

        This performs the perl splice command on a list.

        If $start is omitted (or is undefined), it defaults to 0. If $length
        is omitted (or undefined), it defaults to the end of the list.

        The values removed are returned, and are replaced with @list if
        present.

    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.

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.

    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.

    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.

    is_equal
    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).

    is_subset
    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).

    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.

    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.

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 what
    I wanted.

    Unfortunately, I discovered almost immediately that Set::Array suffered
    from a fairly serious problem. It depends on the Want module which, at