=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.25.0.

=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

Each C<assuming> parameter is optional and defaults to the zero-attribute
tuple if no explicit argument is given to it.

=over

=item C<function sys.std.Bag.cardinality result UInt params { 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.

=item C<function sys.std.Bag.is_member result Bool params { bag(Bag),
value(ScaTupRel) }>

This function is the same as C<sys.std.Set.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>.

=item C<function sys.std.Bag.is_not_member result Bool params { bag(Bag),
value(ScaTupRel) }>

This function is exactly the same as C<sys.std.Bag.is_member> except that
it results in the opposite boolean value when given the same arguments.

=item C<function sys.std.Bag.count result UInt params { bag(Bag),
value(ScaTupRel) }>

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.

=item C<function sys.std.Bag.insertion result Bag params { bag(Bag),
value(ScaTupRel) }>

This function is the same as C<sys.std.Set.insertion> as per C<is_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.

=item C<function sys.std.Bag.deletion result Bag params { bag(Bag),
value(ScaTupRel) }>

This function is the same as C<sys.std.Set.deletion> as per C<is_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> is C<value> is deleted.

=item C<function sys.std.Bag.reduction result ScaTupRel params {
topic(Bag), func(Cat.FuncRef), assuming(QuasiTuple)?, identity(ScaTupRel)
}>

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.

=item C<function sys.std.Bag.maybe_reduction result Maybe params {
topic(Bag), func(Cat.FuncRef), assuming(QuasiTuple)? }>

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

=item C<function sys.std.Bag.Set_from_Bag result Set params { topic(Bag) }>

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

=item C<function sys.std.Bag.Bag_from_Set result Bag params { 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.

=item C<function sys.std.Bag.Bag_from_wrap result bag_of.Tuple params {
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>; 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.

=item C<function sys.std.Bag.Bag_from_attr result Bag params {
topic(Relation), name(Cat.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.

=item C<function sys.std.Bag.is_subset result Bool params { look_in(Bag),
look_for(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<look_for>
value is less than or equal to the multiplicity of its counterpart
C<look_in> value.

=item C<function sys.std.Bag.is_not_subset result Bool params {
look_in(Bag), look_for(Bag) }>

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

=item C<function sys.std.Bag.is_proper_subset result Bool params {
look_in(Bag), look_for(Bag) }>

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

=item C<function sys.std.Bag.is_not_proper_subset result Bool params {
look_in(Bag), look_for(Bag) }>

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

=item C<function sys.std.Bag.union result Bag params { 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.

=item C<function sys.std.Bag.intersection result Bag params {
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.

=item C<function sys.std.Bag.difference result Bag params { source(Bag),
filter(Bag) }>

This function is like C<sys.std.Core.Relation.difference> 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.

=back

=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-2008, Darren Duncan.

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