MAN page from Mandrake Other perl-Set-Bag-1.001-1.i386.rpm

Bag

Section: User Contributed Perl Documentation (3)
Updated: perl 5.004, patch 04
Index

NAME

    Set::Bag - bag (multiset) class

SYNOPSIS

    use Set::Bag;

    my $bag_a = Set::Bag->new(apples => 3, oranges => 4);    my $bag_b = Set::Bag->new(mangos => 3);    my $bag_c = Set::Bag->new(apples => 1);    my $bag_d = ...;        # Methods

    $bag_b->insert(apples => 1);    $bag_b->remove(mangos => 1);

    $bag_b->insert(cherries => 1, $bag_c);

    my @b_elements = $bag_b->elements;  # ('apples','cherries','mangos')    my @a_grab_all = $bag_a->grab;      # (apples => 3, oranges => 4)    my @b_grab_app = $bag_b->grab('apples', 'cherries'); # (3, 1)

    print "bag_a     sum      bag_b = ", $bag_b->sum($bag_b),          "\n";    print "bag_a    union     bag_b = ", $bag_a->union($bag_b),        "\n";    print "bag_a intersection bag_b = ", $bag_a->intersection($bag_b), "\n";

    print "bag_b complement = ", $bag_b->complement, "\n";

    # Operator Overloads

    print "bag_a = $bag_a\n";           # (apples => 3, oranges => 4)

    $bag_b += $bag_c;                                   # Insert    $bag_b -= $bag_d;                                   # Remove

    print "bag_b = $bag_b\n";

    print "bag_a + bag_b = ", $bag_b + $bag_b, "\n";    # Sum    print "bag_a | bag_b = ", $bag_a | $bag_b, "\n";    # Union    print "bag_a & bag_b = ", $bag_a & $bag_b, "\n";    # Intersection

    $bag_b |= $bag_c;                                   # Maximize    $bag_b &= $bag_d;                                   # Minimize

    print "good\n" if     $bag_a eq "(apples => 3, oranges => 4)";      # Eq    print "bad\n"  unless $bag_a ne "(apples => 3, oranges => 4)";      # Ne

    print "-bag_b = ", -$bag_b"\n";                     # Complement

    $bag_c->remove(apples => 5);                        # Would abort.    print "Can",                                        # Cannot ...          $bag_c->over_remove() ? "" : "not",          " over remove from bag_c\n";    $bag_c->over_remove(1);    print "Can",                                        # Can ...          $bag_c->over_remove() ? "" : "not",          " over remove from bag_c\n";    $bag_c->remove(apples => 5);                        # Would succeed.    print $bag_c, "\n";                                 # ()

DESCRIPTION

This module implements a simple bag (multiset) class.

A bag may contain one or more instances of elements. One may add andremove one or more instances at a time.

If one attempts to remove more instances than there are to removefrom, the default behavious of remove is to abort. Theover_remove can be used to control this behaviour.

The sum is something called the additive union. It leaves inthe result bag the sum of all the instances of all bags.

The union is something called the maximal union. It leaves inthe result bag the maximal number of instances in all bags.

The intersection leaves in the result bag only the elements thathave instances in all bags and of those the minimal number of instances.

The complement will leave in the result bag the maximal number ofinstances ever seen (via new, insert, sum, or maximize)minus the number of instances in the complemented bag.

Note the low precedence of | and & compared with eq and ne.

AUTHOR

Jarkko Hietaniemi <jhiAATTiki.fi>

COPYRIGHT

O'Reilly and Associates. This module can be distributed under thesame terms as Perl itself.

This document was created byman2html,using the manual pages.