=pod

=encoding utf8

=head1 NAME

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

=head1 VERSION

This document is Muldis::D::Ext::QBag version 0.58.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<QBag> document describes the system-defined I<Muldis D QBag
Extension>, which consists of generic operators that are specific to the
C<QBag> parameterized q/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 QUASI-/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.QBag.cardinality result NNInt params { topic(QBag)
}>

This function is like C<sys.std.Core.QRelation.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.QBag.is_member result Bool params { bag(QBag),
value(Universal) }>

This function is the same as C<sys.std.QSet.is_member>, including that
matching of C<value> is done against the C<value> attribute, except that it
works with a C<QBag> rather than a C<QSet>.

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

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

=item C<function sys.std.QBag.count result NNInt params { bag(QBag),
value(Universal) }>

This function results in the multiplicity / count of occurrances of
C<value> in C<bag>; if a q/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.QBag.insertion result QBag params { bag(QBag),
value(Universal) }>

This function is the same as C<sys.std.QSet.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 q/tuple is added, but the C<count>
attribute for the matching q/tuple is incremented by 1; if it does not,
then a new q/tuple is added where its C<value> is C<value> and its C<count>
is 1.

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

This function is the same as C<sys.std.QSet.deletion> as per C<is_member>
but that its result differs depending on what the C<count> for any q/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
q/tuple whose C<value> is C<value> is deleted.

=item C<function sys.std.QBag.reduction result Universal params {
topic(QBag), func(FuncRef), assuming(QTuple)?, identity(Universal) }>

This function is the same as C<sys.std.QSet.reduction>, including that
input values for the reduction come from the C<value> attribute of
C<topic>, except that it works with a C<QBag> rather than a C<QSet>;
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.QBag.maybe_reduction result QMaybe params {
topic(QBag), func(FuncRef), assuming(QTuple)? }>

This function is to C<sys.std.QSet.maybe_reduction> as
C<sys.std.QBag.reduction> is to C<sys.std.QSet.reduction>.

=item C<function sys.std.QBag.QSet_from_QBag result QSet params {
topic(QBag) }>

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

=item C<function sys.std.QBag.QBag_from_QSet result QBag params {
topic(QSet) }>

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

=item C<function sys.std.QBag.QBag_from_wrap result quasi_bag_of.QTuple
params { topic(QRelation) }>

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

=item C<function sys.std.QBag.QBag_from_attr result QBag params {
topic(QRelation), name(Name) }>

This function results in a C<QBag> 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 q/relation-typed attribute, and then extending the result of the
group with a new positive integer attribute whose values are the
cardinality of the q/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.QBag.is_subset result Bool params { look_in(QBag),
look_for(QBag) }>

This function is like C<sys.std.Core.QRelation.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.QBag.is_not_subset result Bool params {
look_in(QBag), look_for(QBag) }>

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

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

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

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

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

=item C<function sys.std.QBag.union result QBag params {
topic(quasi_set_of.QBag) }>

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

=item C<function sys.std.QBag.intersection result QBag params {
topic(quasi_set_of.QBag) }>

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

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

This function is like C<sys.std.Core.QRelation.difference> as C<union> is
like C<sys.std.Core.QRelation.union>; for corresponding input q/tuples, the
result only has a q/tuple with the same C<value> if the C<count> of the
C<source> q/tuple is greater than the C<count> of the C<filter> q/tuple,
and the C<count> of the result q/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-2009, 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
