=pod

=encoding utf8

=head1 NAME

Muldis::D::Ext::Bag -
Muldis D extension for Bag specific operators

=head1 VERSION

This document is Muldis::D::Ext::Bag version 0.96.1.

=head1 PREFACE

This document is part of the Muldis D language specification, whose root
document is L<Muldis::D>; you should read that root document
before you read this one, which provides subservient details.

=head1 DESCRIPTION

Muldis D has a mandatory core set of system-defined (eternally available)
entities, which is referred to as the I<Muldis D core> or the I<core>; they
are the minimal entities that all Muldis D implementations need to provide;
they are mutually self-describing and are used to bootstrap the language;
any entities outside the core, called I<Muldis D extensions>, are
non-mandatory and are defined in terms of the core or each other, but the
reverse isn't true.

This current C<Bag> document describes the system-defined I<Muldis D Bag
Extension>, which consists of generic operators that are specific to the
C<Bag> parameterized relation type, and said operators are short-hands
for generic relational operators in the language core.

This current document does not describe the polymorphic operators that all
types, or some types including core types, have defined over them; said
operators are defined once for all types in L<Muldis::D::Core>.

I<This documentation is pending.>

=head1 SYSTEM-DEFINED BAG-CONCERNING FUNCTIONS

=head2 sys.std.Bag.cardinality

C<< function sys.std.Bag.cardinality (NNInt <-- $topic : Bag) >>

This function is like C<sys.std.Core.Relation.cardinality> but that it
accounts for the greater-than-one multiplicity of values in its argument;
it results in the sum of the C<count> attribute of its argument.  Note that
this operation is also known as C<M#>.

=head2 sys.std.Bag.has_member

C<< function sys.std.Bag.has_member (Bool <-- $bag : Bag,
$value : Universal) >>

This function is the same as C<sys.std.Set.has_member>, including that
matching of C<value> is done against the C<value> attribute, except that it
works with a C<Bag> rather than a C<Set>.  Note that this operation is also
known as C<B∋>.

=head2 sys.std.Bag.has_not_member

C<< function sys.std.Bag.has_not_member (Bool <-- $bag : Bag,
$value : Universal) >>

This function is exactly the same as C<sys.std.Bag.has_member> except that
it results in the opposite boolean value when given the same arguments.
Note that this operation is also known as C<B∌>.

=head2 sys.std.Bag.value_is_member

C<< function sys.std.Bag.value_is_member (Bool <--
$value : Universal, $bag : Bag) >>

This function is an alias for C<sys.std.Bag.has_member>.  This function is
the same as C<sys.std.Set.value_is_member>, including that matching of
C<value> is done against the C<value> attribute, except that it works with
a C<Bag> rather than a C<Set>.  Note that this operation is also known as
C<B∈>.

=head2 sys.std.Bag.value_is_not_member

C<< function sys.std.Bag.value_is_not_member (Bool <--
$value : Universal, $bag : Bag) >>

This function is an alias for C<sys.std.Bag.has_not_member>.  This function
is exactly the same as C<sys.std.Bag.value_is_member> except that it
results in the opposite boolean value when given the same arguments.  Note
that this operation is also known as C<B∉>.

=head2 sys.std.Bag.count

C<< function sys.std.Bag.count (NNInt <-- $bag : Bag, $value : Universal)
>>

This function results in the multiplicity / count of occurrances of
C<value> in C<bag>; if a tuple exists in C<bag> whose C<value> attribute
is C<value>, then the result is its C<count> attribute; otherwise the
result is zero.

=head2 sys.std.Bag.insertion

C<< function sys.std.Bag.insertion (Bag <-- $bag : Bag, $value : Universal)
>>

This function is the same as C<sys.std.Set.insertion> as per C<has_member>
but that its result differs depending on whether C<value> already exists in
C<bag>; if it does, then no new tuple is added, but the C<count>
attribute for the matching tuple is incremented by 1; if it does not,
then a new tuple is added where its C<value> is C<value> and its C<count>
is 1.  Actually this function differs in another way, such that it is
semantically the single-tuple case of C<sys.std.Bag.union_sum>, and is
not the single-tuple case of C<sys.std.Bag.union> (which is the direct
analogy to set union).

=head2 sys.std.Bag.deletion

C<< function sys.std.Bag.deletion (Bag <-- $bag : Bag, $value : Universal)
>>

This function is the same as C<sys.std.Set.deletion> as per C<has_member>
but that its result differs depending on what the C<count> for any tuple
matching C<value> that already exists in C<bag> is; if the C<count> is
greater than 1, then it is decremented by 1; if it is equal to 1, then the
tuple whose C<value> attribute is C<value> is deleted.

=head2 sys.std.Bag.reduction

C<< function sys.std.Bag.reduction (Universal <-- $topic : Bag,
$func : ValRedFuncRef, $identity : Universal) >>

This function is the same as C<sys.std.Set.reduction>, including that
input values for the reduction come from the C<value> attribute of
C<topic>, except that it works with a C<Bag> rather than a C<Set>;
C<func> is invoked extra times, where both its C<v1> and C<v2> arguments
might be different instances of the same value having >= 2 multiplicity.

=head2 sys.std.Bag.maybe_reduction

C<< function sys.std.Bag.maybe_reduction (Maybe <-- $topic : Bag,
$func : ValRedFuncRef) >>

This function is to C<sys.std.Set.maybe_reduction> as
C<sys.std.Bag.reduction> is to C<sys.std.Set.reduction>.

=head2 sys.std.Bag.Set_from_Bag

C<< function sys.std.Bag.Set_from_Bag (Set <-- $topic : Bag) >>

This function results in the C<Set> that is the projection of the C<value>
attribute of its C<Bag> argument.

=head2 sys.std.Bag.Bag_from_Set

C<< function sys.std.Bag.Bag_from_Set (Bag <-- $topic : Set) >>

This function results in the C<Bag> that is the extension of its C<Set>
argument with a new C<count> attribute whose value for every tuple is 1.

=head2 sys.std.Bag.Bag_from_wrap

C<< function sys.std.Bag.Bag_from_wrap (bag_of.Tuple <--
$topic : Relation) >>

This function results in a C<Bag> whose C<value> attribute is tuple-typed
and that attribute's values are all the tuples of C<topic>; it is a
short-hand for a relational wrap of all attributes of C<topic> such that
the new tuple-valued attribute is named C<value>, and then that result is
extended with a C<count> attribute whose value for every tuple is 1.

=head2 sys.std.Bag.Bag_from_cmpl_group

C<< function sys.std.Bag.Bag_from_cmpl_group (bag_of.Tuple <--
$topic : Relation, $group_per : set_of.Name) >>

This function is like C<sys.std.Core.Relation.cardinality_per_group> but
that the C<count_attr_name> is C<count> and all the other attributes that
would have been in the result are wrapped in a single tuple-valued
attribute named C<value>.  This function is to C<cardinality_per_group>
what C<sys.std.Array.Array_from_wrap> is to C<sys.std.Relation.rank>.

=head2 sys.std.Bag.Bag_from_attr

C<< function sys.std.Bag.Bag_from_attr (Bag <-- $topic : Relation,
$name : Name) >>

This function results in a C<Bag> consisting of all the values of the
attribute of C<topic> named by C<name>.  It is a short-hand for first doing
a relational group on all attributes of C<topic> besides C<name> to produce
a new relation-typed attribute, and then extending the result of the
group with a new positive integer attribute whose values are the
cardinality of the relation-valued attribute's values, and then doing a
binary projection of the named attribute and the new integer attribute plus
their renaming to C<value> and C<count> respectively.

=head2 sys.std.Bag.is_subset

C<< function sys.std.Bag.is_subset (Bool <-- $topic : Bag, $other : Bag) >>

This function is like C<sys.std.Core.Relation.is_subset> but that it
accounts for the greater-than-one multiplicity of values in its arguments;
this function returns C<Bool:true> iff the multiplicity of each C<topic>
value is less than or equal to the multiplicity of its counterpart
C<other> value.

=head2 sys.std.Bag.is_not_subset

C<< function sys.std.Bag.is_not_subset (Bool <-- $topic : Bag,
$other : Bag) >>

This function is like C<sys.std.Core.Relation.is_not_subset> as per
C<is_subset>.

=head2 sys.std.Bag.is_superset

C<< function sys.std.Bag.is_superset (Bool <-- $topic : Bag, $other : Bag)
>>

This function is an alias for C<sys.std.Bag.is_subset> except that it
transposes the C<topic> and C<other> arguments.  This function is like
C<sys.std.Core.Relation.is_superset> but that it accounts for the
greater-than-one multiplicity of values in its arguments; this function
returns C<Bool:true> iff the multiplicity of each C<topic> value is greater
than or equal to the multiplicity of its counterpart C<other> value.

=head2 sys.std.Bag.is_not_superset

C<< function sys.std.Bag.is_not_superset (Bool <-- $topic : Bag,
$other : Bag) >>

This function is an alias for C<sys.std.Bag.is_not_subset> except that it
transposes the C<topic> and C<other> arguments.  This function is like
C<sys.std.Core.Relation.is_not_superset> as per C<is_superset>.

=head2 sys.std.Bag.is_proper_subset

C<< function sys.std.Bag.is_proper_subset (Bool <-- $topic : Bag,
$other : Bag) >>

This function is like C<sys.std.Relation.is_proper_subset> as per
C<is_subset>.  I<TODO: What is its definition?>

=head2 sys.std.Bag.is_not_proper_subset

C<< function sys.std.Bag.is_not_proper_subset (Bool <-- $topic : Bag,
$other : Bag) >>

This function is like C<sys.std.Relation.is_not_proper_subset> as per
C<is_subset>.  I<TODO: What is its definition?>

=head2 sys.std.Bag.is_proper_superset

C<< function sys.std.Bag.is_proper_superset (Bool <-- $topic : Bag,
$other : Bag) >>

This function is an alias for C<sys.std.Bag.is_proper_subset> except that
it transposes the C<topic> and C<other> arguments.  This function is
like C<sys.std.Relation.is_proper_superset> as per C<is_superset>.

=head2 sys.std.Bag.is_not_proper_superset

C<< function sys.std.Bag.is_not_proper_superset (Bool <-- $topic : Bag,
$other : Bag) >>

This function is an alias for C<sys.std.Bag.is_not_proper_subset> except
that it transposes the C<topic> and C<other> arguments.  This function
is like C<sys.std.Relation.is_not_proper_superset> as per C<is_superset>.

=head2 sys.std.Bag.union

C<< function sys.std.Bag.union (Bag <-- $topic : set_of.Bag) >>

This function is like C<sys.std.Core.Relation.union> but that it just
looks at the C<value> attribute of its argument elements when determining
what element tuples correspond; then for each tuple in the result, its
C<count> attribute value is the maximum of the C<count> attribute values of
its corresponding input element tuples.

=head2 sys.std.Bag.union_sum

C<< function sys.std.Bag.union_sum (Bag <-- $topic : bag_of.Bag) >>

This function is like C<sys.std.Bag.union> but that for each pair of
argument elements being unioned, the output C<count> value is the sum of
the input C<count> values rather than being the maximum of the inputs.

=head2 sys.std.Bag.intersection

C<< function sys.std.Bag.intersection (Bag <-- $topic : set_of.Bag) >>

This function is like C<sys.std.Core.Relation.intersection> as C<union> is
like C<sys.std.Core.Relation.union>; the minimum of C<count> attribute
values is used rather than the maximum.

=head2 sys.std.Bag.diff

C<< function sys.std.Bag.diff (Bag <-- $source : Bag, $filter : Bag) >>

This function is like C<sys.std.Core.Relation.diff> as C<union> is
like C<sys.std.Core.Relation.union>; for corresponding input tuples, the
result only has a tuple with the same C<value> if the C<count> of the
C<source> tuple is greater than the C<count> of the C<filter> tuple,
and the C<count> of the result tuple is the difference of those two.

=head1 SEE ALSO

Go to L<Muldis::D> for the majority of distribution-internal
references, and L<Muldis::D::SeeAlso> for the majority of
distribution-external references.

=head1 AUTHOR

Darren Duncan (C<perl@DarrenDuncan.net>)

=head1 LICENSE AND COPYRIGHT

This file is part of the formal specification of the Muldis D language.

Muldis D is Copyright © 2002-2009, Muldis Data Systems, Inc.

See the LICENSE AND COPYRIGHT of L<Muldis::D> for details.

=head1 TRADEMARK POLICY

The TRADEMARK POLICY in L<Muldis::D> applies to this file too.

=head1 ACKNOWLEDGEMENTS

The ACKNOWLEDGEMENTS in L<Muldis::D> apply to this file too.

=cut
