=pod

=encoding utf8

=head1 NAME

Muldis::D::Core::Routines -
Muldis D general purpose routines

=head1 VERSION

This document is Muldis::D::Core::Routines version 0.28.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 contains one or more sections that were moved here from
L<Muldis::D::Core> so that that other document would not be too
large.

=head1 SYSTEM-DEFINED GENERIC UNIVERSAL FUNCTIONS

These functions are applicable to values of any data type at all.

=over

=item C<function sys.std.Core.Universal.is_identical result Bool params {
topic(Universal), other(Universal) }>

This function results in C<Bool:true> iff its 2 arguments are exactly the
same value, and C<Bool:false> otherwise.  This function's 2 parameters are
mutually commutative.  This function will warn if, in regards to the
declared types of its arguments, none the following are true: 1. they are
both subtypes of a common scalar root type; 2. they are both subtypes of a
common non-incomplete tuple or relation type, that is they essentially have
the same headings; 3. at least one type is a generic (eg-C<Universal>) or
incomplete (eg-C<Array>) type, and it is a supertype of the other.

=item C<function sys.std.Core.Universal.is_not_identical result Bool params
{ topic(Universal), other(Universal) }>

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

=item C<function sys.std.Core.Universal.is_value_of_type result Bool params
{ topic(Universal), type(Cat.TypeRef) }>

This function results in C<Bool:true> iff the value of its C<topic>
argument is a member of the data type whose name is given in the C<type>
argument, and C<Bool:false> otherwise.  As trivial cases, this function
always results in C<Bool:true> if the named type is C<Universal>, and
C<Bool:false> if it is C<Empty>.  This function will fail if the named type
doesn't exist in the virtual machine.

=item C<function sys.std.Core.Universal.treated result Universal params {
topic(Universal), as(Cat.TypeRef) }>

This function results in the value of its C<topic> argument, but that the
declared type of the result is the not-C<Empty> data type whose name is
given in the C<as> argument.  This function will fail if the named type
doesn't exist in the virtual machine, or if C<topic> isn't a member of the
named type.  The purpose of C<treated> is to permit taking values from a
context having a more generic declared type, and using them in a context
having a more specific declared type; such an action would otherwise be
blocked at compile time due to a type-mismatch error; C<treated> causes the
type-mismatch validation, and possible failure, to happen at runtime
instead, on the actual value rather than declared value.  For example, if
you are storing an C<Int> value in a C<Scalar>-typed variable, using
C<treated> will cause the compiler to let you use that variable as an
argument to C<sys.std.Integer.difference>, which it otherwise wouldn't.

=item C<function sys.std.Core.Universal.default result Universal params {
of(Cat.TypeRef) }>

This function is the externalization of a not-C<Empty> data type's
C<type_default> function.  This function results in the default value of
the not-C<Empty> data type whose name is given in the C<of> argument, and
the declared type of the result is that same type.  This function will fail
if the named type doesn't exist in the virtual machine, either at compile
or runtime depending whether the type is in the system or user namespace.
This function is conceptually implicitly used to provide default values for
variables, so they always hold valid values of their declared type.

=item C<function sys.std.Core.Universal.assertion result Universal params {
is_true(Bool), result(Universal) }>

This function results in the value of its C<result> argument, when its
C<is_true> argument is C<Bool:true>.  This function will fail if its
C<is_true> argument is C<Bool:false>.  The purpose of C<assertion> is to
perform condition assertions in a pure functional context that may be
better done without the overhead of creating a new constrained data type,
especially when the assertion is on some fact that is only known after
performing calculations from multiple function arguments; this can
potentially be done at compile time as per type constraints.

=back

=head1 SYSTEM-DEFINED GENERIC SCALAR-CONCERNING FUNCTIONS

These functions are applicable to mainly scalar types, but are generic in
that they typically work with any scalar types.  Now some of these
functions (those with a parameter named C<possrep>) work only with scalar
values that have possreps, and not with values of the 6 system-defined
scalar types lacking any possreps: C<Bool>, C<Int>, C<Blob>, C<Text>,
C<Cat.Name>, C<Cat.Comment>; other functions are not limited in that way,
but may be limited in other ways.  Note that the terminology used to
describe these functions is taking advantage of the fact that a scalar
possrep looks just like a tuple.  Each C<possrep> parameter is optional and
defaults to the empty string if no explicit argument is given to it.

=over

=item C<function sys.std.Core.Scalar.attr result ScaTupRel params {
topic(Scalar), possrep(Cat.Name)?, name(Cat.Name) }>

This function results in the scalar or nonscalar value of the possrep
attribute of C<topic> where the possrep name is given by C<possrep> and the
attribute name is given by C<name>.  This function will fail if C<possrep>
specifies a possrep name that C<topic> doesn't have or C<name> specifies an
attribute name that the named possrep of C<topic> doesn't have.

=item C<function sys.std.Core.Scalar.update_attr result Scalar params {
topic(Scalar), possrep(Cat.Name)?, name(Cat.Name), value(ScaTupRel) }>

This function results in its C<topic> argument but that its possrep
attribute whose possrep name is C<possrep> and whose attribute name is
C<name> has been updated with a new scalar or nonscalar value given by
C<value>.  This function will fail if C<possrep> specifies a possrep name
that C<topic> doesn't have or C<name> specifies an attribute name that the
named possrep of C<topic> doesn't have, or if C<value> isn't of the
declared type of the attribute; this function will otherwise warn if the
declared type of C<value> isn't a subtype of the declared type of the
attribute.

=item C<function sys.std.Core.Scalar.multi_update result Scalar params {
topic(Scalar), possrep(Cat.Name)?, attrs(Tuple) }>

This function is like C<sys.std.Core.Scalar.update_attr> except that it
handles N scalar possrep attributes at once rather than just 1.  The
heading of the C<attrs> argument must be a subset of the heading of the
C<topic> argument's possrep named by C<possrep>; this function's result is
C<topic> with all the possrep attribute values of C<attrs> substituted into
it.  This function could alternately be named
I<sys.std.Core.Scalar.static_substitution>.

=item C<function sys.std.Core.Scalar.projection result Tuple params {
topic(Scalar), possrep(Cat.Name)?, attrs(set_of.Cat.Name) }>

This function results in the C<Tuple> that is the projection of the possrep
(whose name is given in the C<possrep> argument) of its C<topic> argument
that has just the subset of attributes of C<topic> which are named in its
C<attrs> argument.  As a trivial case, this function's result is the entire
named possrep of C<topic> if C<attrs> lists all attributes of that possrep;
or, it is the nullary tuple if C<attrs> is empty.  This function will fail
if C<possrep> specifies a possrep name that C<topic> doesn't have or
C<attrs> specifies any attribute names that C<topic> doesn't have.

=item C<function sys.std.Core.Scalar.cmpl_projection result Tuple params {
topic(Scalar), possrep(Cat.Name)?, attrs(set_of.Cat.Name) }>

This function is the same as C<projection> but that it results in the
complementary subset of possrep attributes of C<topic> when given the same
arguments.

=item C<function sys.std.Core.Scalar.Tuple_from_Scalar result Tuple params
{ topic(Scalar), possrep(Cat.Name)? }>

This function results in the C<Tuple> that has all the same attributes of
the possrep of C<topic> whose name is given in C<possrep>; in other words,
the function results in the externalization of one of a scalar value's
possreps.  This function will fail if C<possrep> specifies a possrep name
that C<topic> doesn't have.

=item C<function sys.std.Core.Scalar.Scalar_from_Tuple result Scalar
params { topic(Tuple), type(Cat.TypeRef), possrep(Cat.Name)? }>

This function results in the C<Scalar> value whose scalar root (|sub)type
is named by C<type>, which has a possrep whose name matches C<possrep>, and
whose complete set of attributes of that named possrep match the attributes
of C<topic>.  This function can be used to select any scalar value at all
that has a possrep.

=item C<function sys.std.Core.Scalar.order result Cat.Order params {
topic(Scalar), other(Scalar), assuming(QuasiTuple)? }>

This function is the externalization of a scalar root type's type-default
(total) C<order_determination> function.  This function results in
C<Cat.Order:same> iff its C<topic> and C<other> arguments are exactly the
same value, and otherwise it results in C<Cat.Order:increase> if the value
of the C<other> argument is considered to be an increase (as defined by the
type) over the value of the C<topic> argument, and otherwise it results in
C<Cat.Order:decrease> as the reverse of the last condition would be true.
This function will fail if its C<topic> and C<other> arguments are not
values of a common scalar root type that declares a type-default
C<order_determination> function; this function will otherwise warn if the
declared types of those arguments are not both subtypes of such a common
scalar root type.  Note that C<order_determination> functions are
considered the only fundamental order-sensitive operators, and all others
are defined over them.  This function also has a C<Tuple>-typed third
parameter, named C<assuming>, which carries optional customization details
for the order-determination algorithm; this permits the function to
implement a choice between multiple (typically similar) ordering algorithms
rather than just one, which reduces the number of functions needed for
supporting that choice; if the algorithm is not customizable, then a tuple
argument would be of degree zero.  The C<assuming> parameter is optional
and defaults to the zero-attribute tuple if no explicit argument is given
to it.

=back

=head1 SYSTEM-DEFINED BOOLEAN-CONCERNING FUNCTIONS

These functions select values of the C<Bool> enumeration.

=over

=item C<function sys.std.Core.Bool.(false|true) result Bool params {}>

This selector function results in the C<Bool:(false|true)> value.

=back

These functions implement commonly used boolean operations.

=over

=item C<function sys.std.Core.Bool.not result Bool params { topic(Bool) }>

This function results in the logical I<not> of its argument.

=item C<function sys.std.Core.Bool.and result Bool params {
topic(set_of.Bool) }>

This function is a reduction operator that recursively takes each pair of
its N input element values and does a logical I<and> (which is both
commutative and associative) on them until just one is left, which is the
function's result.  If C<topic> has zero values, then C<and> results in
C<Bool:true>, which is the identity value for logical I<and>.

=item C<function sys.std.Core.Bool.or result Bool params {
topic(set_of.Bool) }>

This function is a reduction operator that recursively takes each pair of
its N input element values and does a logical inclusive-or (which is both
commutative and associative) on them until just one is left, which is the
function's result.  If C<topic> has zero values, then C<or> results in
C<Bool:false>, which is the identity value for logical inclusive-or.

=item C<function sys.std.Core.Bool.xor result Bool params {
topic(bag_of.Bool) }>

This function is a reduction operator that recursively takes each pair of
its N input element values and does a logical exclusive-or (which is both
commutative and associative) on them until just one is left, which is the
function's result.  If C<topic> has zero values, then C<xor> results in
C<Bool:false>, which is the identity value for logical exclusive-or.

=back

=head1 SYSTEM-DEFINED GENERIC TUPLE-CONCERNING FUNCTIONS

These functions are applicable to mainly tuple types, but are generic in
that they typically work with any tuple types.

=over

=item C<function sys.std.Core.Tuple.attr result ScaTupRel params {
topic(Tuple), name(Cat.Name) }>

This function results in the scalar or nonscalar value of the attribute of
C<topic> whose name is given by C<name>.  This function will fail if
C<name> specifies an attribute name that C<topic> doesn't have.

=item C<function sys.std.Core.Tuple.update_attr result Tuple params {
topic(Tuple), name(Cat.Name), value(ScaTupRel) }>

This function results in its C<topic> argument but that its attribute whose
name is C<name> has been updated with a new scalar or nonscalar value given
by C<value>.  This function will fail if C<name> specifies an attribute
name that C<topic> doesn't have; this function will otherwise warn if the
declared type of C<value> isn't a subtype of the declared type of the
attribute.

=item C<function sys.std.Core.Tuple.multi_update result Tuple params {
topic(Tuple), attrs(Tuple) }>

This function is like C<sys.std.Core.Tuple.update_attr> except that it
handles N tuple attributes at once rather than just 1.  The heading of the
C<attrs> argument must be a subset of the heading of the C<topic> argument;
this function's result is C<topic> with all the attribute values of
C<attrs> substituted into it.  This function could alternately be named
I<sys.std.Core.Tuple.static_substitution>.

=item C<function sys.std.Core.Tuple.rename result Tuple params {
topic(Tuple), map(Cat.AttrRenameMap) }>

This function results in a C<Tuple> value that is the same as its C<topic>
argument but that some of its attributes have different names.  Each tuple
of the argument C<map> specifies how to rename one C<topic> attribute, with
the C<before> and C<after> attributes of a C<map> tuple representing the
old and new names of a C<topic> attribute, respectively.  As a trivial
case, this function's result is C<topic> if C<map> has no tuples.  This
function supports renaming attributes to each others' names.  This function
will fail if C<map> specifies any old names that C<topic> doesn't have, or
any new names that are the same as C<topic> attributes that aren't being
renamed.

=item C<function sys.std.Core.Tuple.projection result Tuple params {
topic(Tuple), attrs(set_of.Cat.Name) }>

This function results in the projection of its C<topic> argument that has
just the subset of attributes of C<topic> which are named in its C<attrs>
argument.  As a trivial case, this function's result is C<topic> if
C<attrs> lists all attributes of C<topic>; or, it is the nullary tuple if
C<attrs> is empty.  This function will fail if C<attrs> specifies any
attribute names that C<topic> doesn't have.

=item C<function sys.std.Core.Tuple.cmpl_projection result Tuple params {
topic(Tuple), attrs(set_of.Cat.Name) }>

This function is the same as C<projection> but that it results in the
complementary subset of attributes of C<topic> when given the same
arguments.

=item C<function sys.std.Core.Tuple.wrap result Tuple params {
topic(Tuple), inner(set_of.Cat.Name), outer(Cat.Name) }>

This function results in a C<Tuple> value that is the same as its C<topic>
argument but that some of its attributes have been wrapped up into a new
C<Tuple>-typed attribute, which exists in place of the original attributes.
The C<inner> argument specifies which C<topic> attributes are to be removed
and wrapped up, and the C<outer> argument specifies the name of their
replacement attribute.  As a trivial case, if C<inner> is empty, then the
result has all the same attributes as before plus a new tuple-typed
attribute of degree zero; or, if C<inner> lists all attributes of C<topic>,
then the result has a single attribute whose value is the same as C<topic>.
This function supports the new attribute having the same name as an old one
being wrapped into it.  This function will fail if C<inner> specifies any
attribute names that C<topic> doesn't have, or if C<outer> is the same as
C<topic> attributes that aren't being wrapped.

=item C<function sys.std.Core.Tuple.cmpl_wrap result Tuple params {
topic(Tuple), cmpl_inner(set_of.Cat.Name), outer(Cat.Name) }>

This function is the same as C<wrap> but that it wraps the complementary
subset of attributes of C<topic> to those specified by C<cmpl_inner>.

=item C<function sys.std.Core.Tuple.unwrap result Tuple params {
topic(Tuple), outer(Cat.Name) }>

This function is the inverse of C<sys.std.Core.Tuple.wrap>, such that it
will unwrap a C<Tuple>-type attribute into its member attributes.  This
function will fail if C<outer> specifies any attribute name that C<topic>
doesn't have, or if an attribute of C<topic{outer}> is the same as another
C<topic> attribute.

=item C<function sys.std.Core.Tuple.product result Tuple params {
topic(quasi_set_of.Tuple) }>

This function is similar to C<sys.std.Core.Relation.product> but that it
works with tuples rather than relations.  This function is mainly intended
for use in connecting tuples that have all disjoint headings, such as for
extending one tuple with additional attributes.

=back

=head1 SYSTEM-DEFINED GENERIC SINGLE INPUT RELATION FUNCTIONS

These functions are applicable to mainly relation types, but are generic in
that they typically work with any relation types.  Each C<\w*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.Core.Relation.cardinality result UInt params {
topic(Relation) }>

This function results in the cardinality of its argument (that is, the
count of tuples its body has).

=item C<function sys.std.Core.Relation.is_member result Bool params {
r(Relation), t(Tuple) }>

This function results in C<Bool:true> iff its C<t> argument matches a tuple
of its C<r> argument (that is, iff conceptually C<t> is a member of C<r>),
and C<Bool:false> otherwise.  This function is like
C<sys.std.Core.Relation.is_subset> except that the tuple being looked for
doesn't have to be wrapped in a relation.  This function will fail|warn if
its 2 arguments are incompatible as per C<is_subset>.

=item C<function sys.std.Core.Relation.is_not_member result Bool params {
r(Relation), t(Tuple) }>

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

=item C<function sys.std.Core.Relation.Tuple_from_Relation result Tuple
params { topic(Relation) }>

This function results in the C<Tuple> that is the sole member tuple of its
argument.  This function will fail if its argument does not have exactly
one tuple.

=item C<function sys.std.Core.Relation.Relation_from_Tuple result Relation
params { topic(Tuple) }>

This function results in the C<Relation> value those body has just the one
C<Tuple> that is its argument.

=item C<function sys.std.Core.Relation.insertion result Relation params {
r(Relation), t(Tuple) }>

This function results in a C<Relation> that is the relational union of C<r>
and a relation whose sole tuple is C<t>; that is, conceptually the result
is C<t> inserted into C<r>.  As a trivial case, if C<t> already exists in
C<r>, then the result is just C<r>.

=item C<function sys.std.Core.Relation.disjoint_insertion result Relation
params { r(Relation), t(Tuple) }>

This function is exactly the same as C<sys.std.Core.Relation.insertion>
except that it will fail if C<t> already exists in C<r>.

=item C<function sys.std.Core.Relation.deletion result Relation params {
r(Relation), t(Tuple) }>

This function results in a C<Relation> that is the relational difference
from C<r> of a relation whose sole tuple is C<t>; that is, conceptually the
result is C<t> deleted from C<r>.  As a trivial case, if C<t> already
doesn't exist in C<r>, then the result is just C<r>.

=item C<function sys.std.Core.Relation.rename result Relation params {
topic(Relation), map(Cat.AttrRenameMap) }>

This function is the same as C<sys.std.Core.Tuple.rename> but that it
operates on and results in a C<Relation> rather than a C<Tuple>.

=item C<function sys.std.Core.Relation.projection result Relation params {
topic(Relation), attrs(set_of.Cat.Name) }>

This function is the same as C<sys.std.Core.Tuple.projection> but that it
operates on and results in a C<Relation> rather than a C<Tuple>.  But note
that the result relation will have fewer tuples than C<topic> if any
C<topic> tuples were non-distinct for just the projected attributes.

=item C<function sys.std.Core.Relation.cmpl_projection result Relation
params { topic(Relation), attrs(set_of.Cat.Name) }>

This function is the same as C<sys.std.Core.Tuple.cmpl_projection> but that
it operates on and results in a C<Relation> rather than a C<Tuple>.

=item C<function sys.std.Core.Relation.wrap result Relation params {
topic(Relation), inner(set_of.Cat.Name), outer(Cat.Name) }>

This function is the same as C<sys.std.Core.Tuple.wrap> but that it
operates on and results in a C<Relation> rather than a C<Tuple>, where each
of its member tuples was transformed as per C<sys.std.Core.Tuple.wrap>.

=item C<function sys.std.Core.Relation.cmpl_wrap result Relation params {
topic(Relation), cmpl_inner(set_of.Cat.Name), outer(Cat.Name) }>

This function is the same as C<sys.std.Core.Tuple.cmpl_wrap> but that it
operates on and results in a C<Relation> rather than a C<Tuple>, where each
of its member tuples was transformed as per
C<sys.std.Core.Tuple.cmpl_wrap>.

=item C<function sys.std.Core.Relation.unwrap result Relation params {
topic(Relation), outer(Cat.Name), inner(set_of.Cat.Name) }>

This function is the inverse of C<sys.std.Core.Relation.wrap> as
C<sys.std.Core.Tuple.unwrap> is to C<sys.std.Core.Tuple.wrap>.  But unlike
the C<Tuple> variant of C<unwrap>, this current function requires the extra
C<inner> argument to prevent ambiguity in the general case where C<topic>
might have zero tuples, because in that situation the most-specific-type of
C<topic{outer}> would be C<Empty>, and the names of the attributes to add
to C<topic> in place of C<topic{outer}> are not known.  This function will
fail if C<topic> has at least 1 tuple and C<inner> does not match the names
of the attributes of C<topic{outer}>.

=item C<function sys.std.Core.Relation.group result Relation params {
topic(Relation), inner(set_of.Cat.Name), outer(Cat.Name) }>

This function is similar to C<sys.std.Core.Relation.wrap> but that the
C<topic> attribute-wrapping transformations result in new C<Relation>-typed
attributes rather than new C<Tuple>-typed attributes, and moreover multiple
C<topic> tuples may be combined into fewer tuples whose new
C<Relation>-typed attributes have multiple tuples.  This function takes a
relation of N tuples and divides the tuples into M groups where all the
tuples in a group have the same values in the attributes which aren't being
grouped (and distinct values in the attributes that are being grouped); it
then results in a new relation of M tuples where the new relation-valued
attribute of the result has the tuples of the M groups.  A grouped relation
contains all of the information in the original relation, but it has less
redundancy due to redundant non-grouped attributes now just being
represented in one tuple per the multiple tuples whose grouped attributes
had them in common.  A relation having relation-valued attributes like this
is a common way to group so-called child tuples under their parents.  As a
trivial case, if C<inner> is empty, then the result has all the same tuples
and attributes as before plus a new relation-typed attribute of degree zero
whose value per tuple is of cardinality one; or, if C<inner> lists all
attributes of C<topic>, then the result has a single tuple of a single
attribute whose value is the same as C<topic>.  This function supports the
new attribute having the same name as an old one being grouped into it.
This function will fail if C<inner> specifies any attribute names that
C<topic> doesn't have, or if C<outer> is the same as C<topic> attributes
that aren't being grouped.

=item C<function sys.std.Core.Relation.cmpl_group result Relation params {
topic(Relation), group_per(set_of.Cat.Name), outer(Cat.Name) }>

This function is the same as C<group> but that it groups the complementary
subset of attributes of C<topic> to those specified by C<group_per>.

=item C<function sys.std.Core.Relation.ungroup result Relation params {
topic(Relation), outer(Cat.Name), inner(set_of.Cat.Name) }>

This function is the inverse of C<sys.std.Core.Relation.group> as
C<sys.std.Core.Relation.unwrap> is to C<sys.std.Core.Relation.wrap>; it
will ungroup a C<Relation>-type attribute into its member attributes and
tuples.  A relation can be first grouped and then that result ungrouped to
produce the original relation, with no data loss.  However, the ungroup of
a relation on a relation-valued attribute will lose the information in any
outer relation tuples whose inner relation value has zero tuples; a group
on this result won't bring them back.  This function will fail if C<outer>
specifies any attribute name that C<topic> doesn't have, or if an attribute
of C<topic{outer}> is the same as another C<topic> attribute.

=item C<function sys.std.Core.Relation.restriction result Relation params {
topic(Relation), func(Cat.FuncRef), assuming(QuasiTuple)? }>

This function results in the relational restriction of its C<topic>
argument as determined by applying the C<Bool>-resulting function named in
its C<func> argument when the latter function is curried by its C<assuming>
argument.  The result relation has the same heading as C<topic>, and its
body contains the subset of C<topic> tuples where, for each tuple, the
function named by C<func> results in C<Bool:true> when passed the tuple as
its C<topic> argument and C<assuming> as its C<assuming> argument.  As a
trivial case, if C<func> is defined to unconditionally result in
C<Bool:true>, then this function results simply in C<topic>; or, for an
unconditional C<Bool:false>, this function results in the empty relation
with the same heading.  Note that this operation is also legitimately known
as I<where>.  See also the C<sys.std.Core.Relation.semijoin> function,
which is a simpler-syntax alternative for
C<sys.std.Core.Relation.restriction> in its typical usage where
restrictions are composed simply of anded or ored tests for attribute value
equality.

=item C<function sys.std.Core.Relation.cmpl_restriction result Relation
params { topic(Relation), func(Cat.FuncRef), assuming(QuasiTuple)? }>

This function is the same as C<restriction> but that it results in the
complementary subset of tuples of C<topic> when given the same arguments.
See also the C<sys.std.Core.Relation.semidifference> function.

=item C<function sys.std.Core.Relation.extension result Relation params {
topic(Relation), func(Cat.FuncRef), assuming(QuasiTuple)? }>

This function results in the relational extension of its C<topic> argument
as determined by applying the C<Tuple>-resulting function named in its
C<func> argument when the latter function is curried by its C<assuming>
argument.  The result relation has a heading that is a superset of that of
C<topic>, and its body contains the same number of tuples, with all
attribute values of C<topic> retained, and possibly extra present,
determined as follows; for each C<topic> tuple, the function named by
C<func> results in a second tuple when passed the first tuple as its
C<topic> argument and C<assuming> as its C<assuming> argument; the first
and second tuples must have no attribute names in common, and the result
tuple is derived by joining (cross-product) the tuples together.  As a
trivial case, if C<func> is defined to unconditionally result in the
degree-zero tuple, then this function results simply in C<topic>.

=item C<function sys.std.Core.Relation.static_extension result Relation
params { topic(Relation), attrs(Tuple) }>

This function is a simpler-syntax alternative to both
C<sys.std.Core.Relation.extension> and C<sys.std.Core.Relation.product> in
the typical scenario of extending a relation, given in the C<topic>
argument, such that every tuple has mutually identical values for each of
the new attributes; the new attribute names and common values are given in
the C<attrs> argument.

=item C<function sys.std.Core.Relation.summary result Relation params {
topic(Relation), group_per(set_of.Cat.Name), summ_func(Cat.FuncRef),
summ_assuming(QuasiTuple)? }>

This function provides a convenient context for using aggregate functions
to derive a per-group summary relation, which is its result, from another
relation, which is its C<topic> argument.  This function first performs a
C<cmpl_group> on C<topic> using C<group_per> to specify which attributes
get grouped into a new relation-valued attribute and which don't; those
that don't instead get wrapped into a tuple-valued attribute.  Then, per
tuple in the main relation, this function applies the C<Tuple>-resulting
function named in its C<summ_func> argument when the latter function is
curried by its C<summ_assuming> argument (passed to it as just
C<assuming>); the curried function has, rather than the typical 1 C<topic>
varying parameter, 2 varying parameters named C<summarize> and C<per>,
which are valued with the relation-valued attribute and tuple-valued
attribute, respectively.  As per a function that C<map> applies, the
function named by C<summ_func> effectively takes a whole post-grouping
input tuple and results in a whole tuple; the applied function would
directly invoke any N-ary / aggregate operators, and extract their inputs
from (or calculate) C<summarize> as it sees fit.  Note that C<summary> is
not intended to be used to summarize an entire C<topic> relation at once
(except by chance of it resolving to 1 group); you should instead invoke
your summarize-all C<func> directly, or inline it, rather than by way of
C<summary>, especially if you want a single-tuple result on an empty
C<topic> (which C<summary>) won't do.

=back

=head1 SYSTEM-DEFINED GENERIC MULTIPLE INPUT RELATION FUNCTIONS

These functions are applicable to mainly relation types, but are generic in
that they typically work with any relation types.

=over

=item C<function sys.std.Core.Relation.is_subset result Bool params {
look_in(Relation), look_for(Relation) }>

This function results in C<Bool:true> iff the set of tuples comprising
C<look_for> is a subset of the set of tuples comprising C<look_in>, and
C<Bool:false> otherwise.  This function will fail if the 2 arguments have
attributes with common names but their most specific types would be fatally
incompatible in a common relation value; this function will otherwise warn
with common-named attributes where their declared types are incompatible as
per C<is_identical>.

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

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

=item C<function sys.std.Core.Relation.union result Relation params {
topic(set_of.Relation) }>

This function results in the relational union/inclusive-or of the N element
values of its argument; it is a reduction operator that recursively takes
each pair of input values and relationally unions (which is both
commutative and associative) them together until just one is left, which is
the result.  The result relation has the same heading as all of its inputs,
and its body contains every tuple that is in any of the input relations.
If C<topic> has zero values, then this function will fail.  Note that,
conceptually C<union> I<does> have an identity value which could be this
function's result when C<topic> has zero values, which is the empty
relation with the same heading, which is the per-distinct-heading identity
value for relational union; however, since a C<topic> with zero values
wouldn't know the heading / attribute names for the result relation in
question, it seems the best alternative is to require invoking code to work
around the limitation somehow, which might mean it will supply the identity
value explicitly as an extra C<topic> element.

=item C<function sys.std.Core.Relation.disjoint_union result Relation
params { topic(set_of.Relation) }>

This function is exactly the same as C<sys.std.Core.Relation.union> except
that it will fail if any 2 input values have a tuple in common.

=item C<function sys.std.Core.Relation.intersection result Relation params
{ topic(set_of.Relation) }>

This function results in the relational intersection/and of the N element
values of its argument; it is a reduction operator that recursively takes
each pair of input values and relationally intersects (which is both
commutative and associative) them together until just one is left, which is
the result.  The result relation has the same heading as all of its inputs,
and its body contains only the tuples that are in every one of the input
relations.  If C<topic> has zero values, then this function will fail.
Note that, conceptually C<intersection> I<does> have an identity value
which could be this function's result when C<topic> has zero values, which
is the universal relation with the same heading (that is, the relation
having all the tuples that could ever exist in a relation with that
heading), which is the per-distinct-heading identity value for relational
intersection; however, since a C<topic> with zero values wouldn't know the
heading / attribute names for the result relation in question (and even if
they were, more information on attribute types would be needed to produce
said universal relation, and even then it might be infinite or impossibly
large), it seems the best alternative is to require invoking code to work
around the limitation somehow, which might mean it will supply the identity
value explicitly as an extra C<topic> element.  Note that this
I<intersection> operator is conceptually a special case of C<join>,
applicable when the headings of the inputs are the same, and the other will
produce the same result as this when given the same inputs, but with the
exception that I<intersection> has a different identity value when given
zero inputs.

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

This function results in the relational difference when its C<filter>
argument is subtracted from its C<source> argument.  The result relation
has the same heading as both of its arguments, and its body contains only
the tuples that are in C<source> and are not in C<filter>.  This function
will fail|warn if its 2 arguments are incompatible as per C<is_subset>.
Note that this I<difference> operator is conceptually a special case of
I<semidifference>, applicable when the headings of the inputs are the same.

=item C<function sys.std.Core.Relation.semidifference result Relation
params { source(Relation), filter(Relation) }>

This function is the same as C<semijoin> but that it results in the
complementary subset of tuples of C<source> when given the same arguments.
Note that this operation is also legitimately known as I<antijoin> or
I<anti-semijoin>.

=item C<function sys.std.Core.Relation.semijoin result Relation params {
source(Relation), filter(Relation) }>

This function results in the relational semijoin of its C<source> and
C<filter> arguments.  The result relation has the same heading as
C<source>, and its body contains the subset of C<source> tuples that match
those of C<filter> as per C<join>.  Note that relational semijoin is
conceptually a short-hand for first doing an ordinary relational join
between its 2 arguments, and then performing a relational projection on all
of the attributes that just C<source> has.  This function will fail|warn
any time that C<join> would fail|warn on the same 2 input relations.

=item C<function sys.std.Core.Relation.join result Relation params {
topic(quasi_set_of.Relation) }>

This function results in the relational join of the N element values of its
argument; it is a reduction operator that recursively takes each pair of
input values and relationally joins (which is both commutative and
associative) them together until just one is left, which is the result.
The result relation has a heading that is a union of all of the headings of
its inputs, and its body is the result of first pairwise-matching every
tuple of each input relation with every tuple of each other input relation,
then where each member of a tuple pair has attribute names in common,
eliminating pairs where the values of those attributes differ and unioning
the remaining said tuple pairs, then eliminating any result tuples that
duplicate others.  If C<topic> has zero values, then C<join> results in the
nullary relation with one tuple, which is the identity value for relational
join.  As a trivial case, if any input relation has zero tuples, then the
function's result will too; or, if any input is the nullary relation with
one tuple, that input can be ignored (see identity value); or, if any 2
inputs have no attribute names in common, then the join of just those 2 is
a cartesian product; or, if any 2 inputs have all attribute names in
common, then the join of just those 2 is an intersection; or, if for 2
inputs, one's set of attribute names is a proper subset of another's, then
the join of just those to is a semijoin with the former filtering the
latter.  This function will fail if any input relations have attributes
with common names but their most specific types would be fatally
incompatible in a common relation value; this function will otherwise warn
with common-named attributes where their declared types are incompatible as
per C<is_identical>.  Note that this operation is also legitimately known
as I<natural inner join>.

=item C<function sys.std.Core.Relation.product result Relation params {
topic(quasi_set_of.Relation) }>

This function results in the relational cartesian/cross product of the N
element values of its argument; it is conceptually a special case of
C<join> where all input relations have mutually distinct attribute names;
unlike C<join>, C<product> will fail if any inputs have attribute names in
common.  Note that this operation is also legitimately known as
I<cartesian/cross join>.

=item C<function sys.std.Core.Relation.quotient result Relation params {
dividend(Relation), divisor(Relation) }>

This function results in the quotient when its C<dividend> argument is
divided by its C<divisor> argument using relational division.  Speaking
informally, say the relations C<dividend> and C<divisor> are called C<A>
and C<B>, and their attribute sets are respectively named C<{X,Y}> and
C<{Y}>, then the result relation has a heading composed of attributes
C<{X}> (so the result and C<divisor> headings are both complementary
subsets of the C<dividend> heading); the result has all tuples C<{X}> such
that a tuple C<{X,Y}> appears in C<A> for all tuples C<{Y}> appearing in
C<B>; that is, C<A / B> is shorthand for C<A{X} - ((A{X} join B) - A){X}>.

=back

=head1 SYSTEM-DEFINED GENERIC QUASI- FUNCTIONS

I<This documentation is pending.  But assume that any necessary quasi-
routines are like those of their non-quasi counterparts, and that mapping
functions exist between corresponding quasi- and non-quasi types as well.>

=head1 SYSTEM-DEFINED GENERIC CONTROL FLOW FUNCTIONS

=over

=item C<function sys.std.Core.Control.func_invo result Universal params {
function(Cat.FuncRef), args(QuasiTuple)? }>

This function results in the result of invoking the other function named in
its C<function> argument when the latter function is curried by its C<args>
argument; each attribute name of C<args> is mapped to a parameter name of
the invoked function, and the corresponding attribute value is the
corresponding argument for the function invocation.  This function will
fail if the invoked function has any non-optional parameters such that
there aren't any corresponding attributes in C<args>, or if there are any
attributes in C<args> that don't have corresponding parameters, or if any
attribute values aren't of the declared types of the corresponding
parameters.  The purpose of C<func_invo> is to support invocation of any
function whose name or parameters potentially aren't known until runtime;
it forms the foundation of all other system-defined functions that want to
invoke a function whose name they take as an argument.  The C<args>
parameter is optional and defaults to the zero-attribute quasi-tuple if no
explicit argument is given to it.

=back

=head1 SYSTEM-DEFINED GENERIC UNIVERSAL UPDATERS

These update operators are applicable to values of any data type at all.

=over

=item C<updater sys.std.Core.Universal.assign update { target(Universal) }
read { v(Universal) }>

This update operator will update the variable supplied as its C<target>
argument so that it holds the value supplied as its C<v> argument.  This
updater will fail if C<v> isn't of the declared type of the variable behind
C<target>; this function will otherwise warn if the declared type of C<v>
isn't a subtype of the declared type of the variable behind C<target>.

=back

=head1 SYSTEM-DEFINED GENERIC CONTROL FLOW UPDATERS

=over

=item C<updater sys.std.Core.Control.upd_invo update {
upd_args(QuasiTuple)? } read { updater(Cat.ProcRef), ro_args(QuasiTuple)?
}>

This update operator has the same purpose and features as
C<sys.std.Core.Control.func_invo> but that it invokes an updater rather
than a function; there is no result to deal with, and there are both
subject-to-update parameters and read-only parameters of the invoked
updater to bind to; they are bound with the attributes of this updater's
C<upd_args> and C<ro_args> arguments, respectively.  The C<upd_args> and
C<ro_args> parameters are optional and default as per the C<args> parameter
of C<func_invo>.

=back

=head1 SYSTEM-DEFINED GENERIC SYSTEM SERVICES

These system services are applicable to just one or more specific
system-defined core scalar data type.

Note: Basic I/O procedures go here!

I<This documentation is pending.>

=head1 SYSTEM-DEFINED GENERIC CONTROL FLOW PROCEDURES

These procedures are applicable to use in all kinds of procedures.

=over

=item C<procedure sys.std.Core.Control.proc_invo update {
upd_args(QuasiTuple)? } read { procedure(Cat.ProcRef),
ro_args(QuasiTuple)? }>

This procedure is the same as C<sys.std.Core.Control.upd_invo> but that it
invokes a procedure rather than an updater.

=item C<procedure sys.std.Core.Control.fail update {} read {
topic(Cat.Exception) }>

This procedure will throw the exception given as its argument; this results
in the call stack unwinding, and transaction rollbacks, until it is caught.

=item C<procedure sys.std.Core.Control.try_catch update {
try_updating(QuasiTuple)?, catch_updating(QuasiTuple)? } read {
try(Cat.ProcRef), catch(Cat.ProcRef), try_assuming(QuasiTuple)?,
catch_assuming(QuasiTuple)? }>

This procedure invokes the procedure named in its C<try> argument, giving
it the arguments C<try_updating> and C<try_assuming> as its C<updating> and
C<assuming> arguments, respectively.  If the C<try> procedure throws an
exception, then any state changes it made roll back (but changes made
before that don't), and the call stack unwinds to the C<try_catch> itself;
then the procedure named by C<catch> is invoked similarly to C<try> was,
with corresponding arguments, but with the extra read-only argument
C<topic> whose value is a C<Cat.Exception>; if the C<catch> procedure also
throws an exception (such as to say its not handling the thrown one), then
that one is not caught and the call stack unwinding plus applicable
transaction rollback carries on to the caller of the C<try_catch>.  If the
C<try> procedure succeeds (doesn't throw an exception), then the C<catch>
procedure is not called.  Each of the C<(try|catch)_(updating|assuming)>
parameters is optional and defaults to the zero-attribute tuple if no
explicit argument is given to it.

=back

=head1 SYSTEM-DEFINED GENERIC BOOTLOADER EXCLUSIVES

These system services may only be invoked directly by a C<bootloader>
routine.

=over

=item C<bootloader_exclusive sys.std.Core.Control.start_trans read {}>

This system service starts a new child-most transaction.

=item C<bootloader_exclusive sys.std.Core.Control.commit_trans read {}>

This system service commits the child-most transaction; it will fail if
there isn't one.

=item C<bootloader_exclusive sys.std.Core.Control.rollback_trans read {}>

This system service rolls back the child-most transaction; it will fail if
there isn't one.

=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