Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

Set::Bag
bag class

Set::Bag - bag class



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->delete(mangos => 1);

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

    my @b_elements = $bag_b->elements;  # ('apples','cherries','mangos')

    my @b_grab_app = $bag_b->grab('apples', 'cherries'); # (3, 1)

    my @a_grab_all = $bag_a->grab;      # (apples => 3, oranges => 4)

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

    print "bag_a  difference  bag_b = ", $bag_b->difference($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;                                   # Delete

    print "bag_b = $bag_b\n";

    print "bag_a + bag_b = ", $bag_b + $bag_b, "\n";    # Sum

    print "bag_a - bag_b = ", $bag_b - $bag_b, "\n";    # Difference

    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->delete(apples => 5);                        # Would abort.

    print "Can",                                        # Cannot ...

          $bag_c->over_delete() ? "" : "not",

          " over delete from bag_c\n";

    $bag_c->over_delete(1);

    print "Can",                                        # Can ...

          $bag_c->over_delete() ? "" : "not",

          " over delete from bag_c\n";

    $bag_c->delete(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 and delete one or more instances at a time.

If one attempts to delete more instances than there are to delete from, the default behavious of delete is to raise an exception. The over_delete method can be used to control this behaviour.

Inserting or removing negative number of instances translates into removing or inserting positive number of instances, respectively.

The sum is also known as the additive union. It leaves in the result bag the sum of all the instances of all bags.

Before using the difference you very often will need the over_delete.

The union is also known as the maximal union. It leaves in the result bag the maximal number of instances in all bags.

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

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

The grab method returns the contents of a bag. If used with parameters the parameters are the elements and their number of instances in the bag are returned. If an element that does not exist in the bag is grabbed for, the number of instances returned for that element will be undef. If used without parameters the elements are returned in pseudorandom order.


NOTES

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


AUTHOR

Jarkko Hietaniemi <jhi@iki.fi>


COPYRIGHT

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

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy