=pod
=encoding utf8
=head1 NAME
Muldis::D::Core::Set -
Muldis D Set and Maybe specific operators
=head1 VERSION
This document is Muldis::D::Core::Set version 0.148.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. Moreover, you
should read the L<Muldis::D::Core> document before this current
document, as that forms its own tree beneath a root document branch.
=head1 DESCRIPTION
This document describes generic operators that are specific to the
C<Set> and C<Maybe> parameterized relation types, and said operators
are short-hands for more generic relational operators.
I<This documentation is pending.>
=head1 FUNCTIONS IMPLEMENTING VIRTUAL COLLECTIVE FUNCTIONS
=head2 sys.std.Core.Set.has_member
C<< function has_member (Bool <-- coll : Set, value : Universal)
implements sys.std.Core.Collective.has_member {...} >>
This function results in C<Bool:True> iff its C<value> argument matches the
sole attribute of a tuple of its C<coll> argument (that is, iff
conceptually C<value> is a member of C<coll>), and C<Bool:False> otherwise.
This function will warn if its 2 arguments are incompatible as per
C<sys.std.Core.Relation.is_subset>.
=head2 sys.std.Core.Set.has_not_member
C<< function has_not_member (Bool <-- coll : Set, value : Universal)
implements sys.std.Core.Collective.has_not_member {...} >>
This function is exactly the same as C<sys.std.Core.Set.has_member> except
that it results in the opposite boolean value when given the same
arguments.
=head2 sys.std.Core.Set.value_is_member
C<< function value_is_member (Bool <-- value : Universal, coll : Set)
implements sys.std.Core.Collective.value_is_member {...} >>
This function is an alias for C<sys.std.Core.Set.has_member>. This
function results in C<Bool:True> iff its C<value> argument matches the
sole attribute of a tuple of its C<coll> argument (that is, iff
conceptually C<value> is a member of C<coll>), and C<Bool:False>
otherwise.
=head2 sys.std.Core.Set.value_is_not_member
C<< function value_is_not_member (Bool <-- value : Universal, coll : Set)
implements sys.std.Core.Collective.value_is_not_member {...} >>
This function is an alias for C<sys.std.Core.Set.has_not_member>. This
function is exactly the same as C<sys.std.Core.Set.value_is_member> except
that it results in the opposite boolean value when given the same
arguments.
=head1 GENERIC RELATIONAL FUNCTIONS FOR SETS
=head2 sys.std.Core.Set.insertion
C<< function insertion (Set <-- set : Set, value : Universal) {...} >>
This function results in a C<Set> that is the relational union of C<set>
and a Set whose sole tuple has the sole attribute value of C<value>;
that is, conceptually the result is C<value> inserted into C<set>. As a
trivial case, if C<value> already exists in C<set>, then the result is just
C<set>.
=head2 sys.std.Core.Set.disjoint_ins
C<< function disjoint_ins (Set <-- set : Set, value : Universal) {...} >>
This function is exactly the same as C<sys.std.Core.Set.insertion> except
that it will fail if C<value> already exists in C<set>.
=head2 sys.std.Core.Set.deletion
C<< function deletion (Set <-- set : Set, value : Universal) {...} >>
This function results in a C<Set> that is the relational difference from
C<set> of a Set whose sole tuple has the sole attribute value of
C<value>; that is, conceptually the result is C<value> deleted from C<set>.
As a trivial case, if C<value> already doesn't exist in C<set>, then the
result is just C<set>.
=head2 sys.std.Core.Set.reduction
C<< function reduction (Universal <-- topic : Set,
func : ValRedCFuncNC, identity : Universal) {...} >>
This function is a generic reduction operator that recursively takes each
pair of input values in C<topic> and applies an argument-specified scalar
or nonscalar value-resulting C<value-reduction> function (which is both
commutative and associative) to the pair until just one input value is
left, which is the result. The C<value-reduction> function to apply is
named in the C<func> argument, and that
function must have 2 parameters named C<v1> and C<v2>, which take
the 2 input scalar or nonscalar values for an
invocation. If C<topic> has zero values, then C<reduction> results in the
value given in C<identity>. I<Note that C<identity> may be changed to take
a function name rather than a value, for consistency with C<func>.> This
function will fail|warn if the |declared type of C<identity> isn't a
subtype of the |declared type of the sole attribute of C<topic>.
=head2 sys.std.Core.Set.Set_from_wrap
C<< function Set_from_wrap (set_of.Tuple <-- topic : Relation) {...} >>
This function results in a C<Set> whose sole attribute is tuple-typed
and the attribute 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>.
=head2 sys.std.Core.Set.Set_from_attr
C<< function Set_from_attr (Set <-- topic : Relation, name : Name) {...} >>
This function results in a C<Set> consisting of all the values of the
attribute of C<topic> named by C<name>. It is a short-hand for a unary
projection of just the named attribute plus its renaming to C<value>.
=head1 GENERIC RELATIONAL FUNCTIONS FOR MAYBES
=head2 sys.std.Core.Set.Maybe.Nothing
C<< function Nothing (Maybe <--) {...} >>
This C<named-value> selector function results in the only zero-tuple Maybe
value, which is known by the special name C<Maybe:Nothing>, aka C<Nothing>,
aka I<empty set> aka C<∅>.
=head2 sys.std.Core.Set.Maybe.just
C<< function just (Just <-- value : Universal) {...} >>
This selector function results in the Maybe value with a single tuple
whose C<value> attribute's value is the C<value> argument.
=head2 sys.std.Core.Set.Maybe.attr
C<< function attr (Universal <-- topic : Just) {...} >>
This function results in the scalar or nonscalar value of the sole
attribute of the sole tuple of its argument, which always exists when the
argument is a C<Just>. Note that this operation is also known as C<.{*}>.
=head2 sys.std.Core.Set.Maybe.attr_or_default
C<< function attr_or_default (Universal <--
topic? : array_of.Maybe, default : APTypeNC) {...} >>
This function results in the scalar or nonscalar value of the sole
attribute of the sole tuple of the lowest-indexed of its N C<topic> input
element values where said element isn't equal to C<Nothing>, if there is
such an element; otherwise, it results in the default value of the scalar
or nonscalar data type whose name is given in the C<default> argument.
This function is a short-hand for invoking C<attr_or_value> with the result
from invoking C<sys.std.Core.Universal.default>.
=head2 sys.std.Core.Set.Maybe.attr_or_value
C<< function attr_or_value (Universal <--
topic? : array_of.Maybe, value : Universal) {...} >>
This function results in the scalar or nonscalar value of the sole
attribute of the sole tuple of the lowest-indexed of its N C<topic> input
element values where said element isn't equal to C<Nothing>, if there is
such an element, and otherwise it results in C<value>. This function will
warn if the declared type of C<value> isn't a subtype of the declared type
of the attribute. Note that this operation is also known as C<//>. In
situations where a C<Maybe> is used analogously to a SQL nullable value,
this function is analogous to the N-adic SQL COALESCE function.
=head2 sys.std.Core.Set.Maybe.order
C<< function order (Order <-- topic : Maybe,
other : Maybe, J_ord_func? : OrdDetCFuncNC, J_is_reverse_order? : Bool,
N_is_after_all_J : Bool, is_reverse_order? : Bool) {...} >>
This function is a generic (total) C<order-determination> function for
C<Maybe> values. Iff both of its C<topic> and C<other> arguments are
identical, this function results in C<Order:Same>. Otherwise, iff both of
those 2 arguments are C<Just> values, then the result of this function
is the result of applying to those 2 arguments the (total)
C<order-determination> function given in its C<J_ord_func> argument, as
curried by its C<J_is_reverse_order> argument; to be specific, the
C<order-determination> function takes the attribute values of C<topic> and
C<other>, not the whole C<Just> values. Otherwise, iff C<topic> is
C<Nothing>, this function results in C<Order:Increase> or C<Order:Decrease>
respectively when C<N_is_after_all_J> is C<Bool:False> (the default) or
C<Bool:True>. Otherwise (iff C<other> is C<Nothing>), this function
results in the reverse of when only C<topic> is C<Nothing>. The
C<is_reverse_order> argument is applied to the result of this function
I<after> all of the other arguments are applied; if it is C<Bool:False>, it
does not change the result; if it is C<Bool:True>, then it reverses the
result. In situations where a C<Maybe> is used analogously to a SQL
nullable value and this function is analogous to the dyadic comparison
underlying a SQL "ORDER BY", then C<J_is_reverse_order> designates SQL's
"ASC|DESC" and C<N_is_after_all_J> designates SQL's "NULLS FIRST|LAST".
=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<darren@DarrenDuncan.net>)
=head1 LICENSE AND COPYRIGHT
This file is part of the formal specification of the Muldis D language.
Muldis D is Copyright © 2002-2011, 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