/ 
Set-Bag-1.004
River stage zero No dependents
/ Set::Bag

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 @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;					# Delete

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->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 abort. The over_delete 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 something called the additive union. It leaves in the result bag the sum of all the instances of all bags.

The union is something called 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) minus the number of instances in the complemented bag.

NOTES

The contents of a bag will be returned from the parameterless grab in pseudorandom order.

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.