=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.99.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 said 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.

=head2 sys.std.Core.Universal.is_identical

C<< function sys.std.Core.Universal.is_identical (Bool <--
$topic : Universal, $other : Universal) >>

This symmetric function results in C<Bool:true> iff its 2
arguments are exactly the same value, and C<Bool:false> otherwise.  This
function will warn if, in regards to the declared types of its arguments,
none of the following are true: 1. they are both subtypes of a common
scalar root type; 2. they are both subtypes of a common complete 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<Relation>) type, and it is a supertype of the other.  Note that
this operation is also known as I<is equal> or C<=>.

=head2 sys.std.Core.Universal.is_not_identical

C<< function sys.std.Core.Universal.is_not_identical (Bool <--
$topic : Universal, $other : Universal) >>

This symmetric 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.  Note that this
operation is also known as I<is not equal> or C<≠> or C<!=>.

=head2 sys.std.Core.Universal.is_value_of_type

C<< function sys.std.Core.Universal.is_value_of_type (Bool <--
$topic : Universal, $type : 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.  Note that this operation is also
known as C<isa>.

=head2 sys.std.Core.Universal.is_not_value_of_type

C<< function sys.std.Core.Universal.is_not_value_of_type (Bool <--
$topic : Universal, $type : TypeRef) >>

This function is exactly the same as
C<sys.std.Core.Universal.is_value_of_type> except that it results in the
opposite boolean value when given the same arguments.  Note that this
operation is also known as C<!isa> or C<not-isa>.

=head2 sys.std.Core.Universal.treated

C<< function sys.std.Core.Universal.treated (Universal <--
$topic : Universal, $as : 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.diff>, which it otherwise wouldn't.  Note
that this operation is also known as C<as>.

=head2 sys.std.Core.Universal.default

C<< function sys.std.Core.Universal.default (Universal <-- $of : TypeRef)
>>

This function is the externalization of a not-C<Empty> data type's I<type
default> C<named-value> 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.  Note that this operation is also known as C<d>.

=head2 sys.std.Core.Universal.assertion

C<< function sys.std.Core.Universal.assertion (Universal <--
$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.  Note that
this operation is also known as C<asserting>.

=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.  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>
and C<name> parameter is optional and each defaults to the empty string if
no explicit argument is given to it.

=head2 sys.std.Core.Scalar.attr

C<< function sys.std.Core.Scalar.attr (Universal <-- $topic : Scalar,
$possrep? : Name, $name? : 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.  Note that
this operation is also known as C<.${}>.

=head2 sys.std.Core.Scalar.update_attr

C<< function sys.std.Core.Scalar.update_attr (Scalar <-- $topic : Scalar,
$possrep? : Name, $name? : Name, $value : Universal) >>

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.

=head2 sys.std.Core.Scalar.multi_update

C<< function sys.std.Core.Scalar.multi_update (Scalar <-- $topic : Scalar,
$possrep? : 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_subst>.

=head2 sys.std.Core.Scalar.projection

C<< function sys.std.Core.Scalar.projection (Tuple <-- $topic : Scalar,
$possrep? : Name, $attr_names : set_of.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<attr_names> argument.  As a trivial case, this function's result
is the entire named possrep of C<topic> if C<attr_names> lists all
attributes of that possrep; or, it is the nullary tuple if C<attr_names> is
empty.  This function will fail if C<possrep> specifies a possrep name that
C<topic> doesn't have or C<attr_names> specifies any attribute names that
C<topic> doesn't have.  Note that this operation is also known as C<${}>.

=head2 sys.std.Core.Scalar.cmpl_proj

C<< function sys.std.Core.Scalar.cmpl_proj (Tuple <--
$topic : Scalar, $possrep? : Name, $attr_names : set_of.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.  Note that this operation is also known as C<${!}>.

=head2 sys.std.Core.Scalar.Tuple_from_Scalar

C<< function sys.std.Core.Scalar.Tuple_from_Scalar (Tuple <--
$topic : Scalar, $possrep? : 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.

=head2 sys.std.Core.Scalar.Scalar_from_Tuple

C<< function sys.std.Core.Scalar.Scalar_from_Tuple (Scalar <--
$topic : Tuple, $type : TypeRef, $possrep? : 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.

=head2 sys.std.Core.Scalar.order

C<< function sys.std.Core.Scalar.order (Order <-- $topic : Scalar,
$other : Scalar, $misc_args? : Tuple, $is_reverse_order? : Bool) >>

This C<order-determination> function is the externalization of a scalar
root type's type-default (total) C<order-determination> function.  This
function results in C<Order:same> iff its C<topic> and C<other> arguments
are exactly the same value, and otherwise it results in C<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<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<misc_args>, 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.  This function also has a
C<Bool>-typed fourth parameter, named C<is_reverse_order>; a C<Bool:false>
argument means the function's algorithm operates as normal when given any
particular 3 other arguments (meaning a sorting operation based on it will
place elements in ascending order), while a C<Bool:true> argument means the
function's algorithm operates in reverse, so the function results in the
reverse C<Order> value it would have otherwise when given the same 3 other
arguments (meaning a sorting operation based on it will place elements in
descending order).  The C<misc_args> and C<is_reverse_order> parameters are
optional and default to the zero-attribute tuple and C<Bool:false>,
respectively, if no explicit arguments are given to them.

=head2 sys.std.Core.Scalar.has_possrep

C<< function sys.std.Core.Scalar.has_possrep (Bool <-- $topic : Scalar,
$possrep? : Name) >>

This function results in C<Bool:true> iff its C<topic> argument has a
possrep whose name is given by C<possrep>; otherwise it results in
C<Bool:false>.

=head2 sys.std.Core.Scalar.possrep_names

C<< function sys.std.Core.Scalar.possrep_names (set_of.Name <--
$topic : Scalar) >>

This function results in the set of the names of the possreps of its
argument.

=head2 sys.std.Core.Scalar.degree

C<< function sys.std.Core.Scalar.degree (NNInt <-- $topic : Scalar,
$possrep? : Name) >>

This function results in the degree of its C<topic> argument's possrep
whose name is given by C<possrep> (that is, the count of attributes the
possrep has).

=head2 sys.std.Core.Scalar.has_attrs

C<< function sys.std.Core.Scalar.has_attrs (Bool <-- $topic : Scalar,
$possrep? : Name, $attr_names : set_of.Name) >>

This function results in C<Bool:true> iff, for every one of the attribute
names specified by its C<attr_names> argument, its C<topic> argument's
possrep whose name is given by C<possrep> has an attribute with that name;
otherwise it results in C<Bool:false>.  As a trivial case, this function's
result is C<Bool:true> if C<attr_names> is empty.

=head2 sys.std.Core.Scalar.attr_names

C<< function sys.std.Core.Scalar.attr_names (set_of.Name <--
$topic : Scalar, $possrep? : Name) >>

This function results in the set of the names of the attributes of its
C<topic> argument's possrep whose name is given by C<possrep>.

=head1 SYSTEM-DEFINED BOOLEAN-CONCERNING FUNCTIONS

These functions implement commonly used boolean logic operations.  See also
L<Muldis::D::Ext::Bool> for all the other standard boolean logic operators
which aren't shown below.

=head2 sys.std.Core.Bool.not

C<< function sys.std.Core.Bool.not (Bool <-- $topic : Bool) >>

This function results in the logical I<not> of its argument.  This function
results in C<Bool:true> iff its argument is C<Bool:false>, and
C<Bool:false> otherwise.  Note that this operation is also known as
I<negation> or C<¬> or C<!>.

There also exists conceptually the logical monadic operation called
I<proposition> which results simply in its argument; this is the complement
operation of I<negation>.  Now in practice any value expression that is an
invocation of I<proposition> can simply be replaced with its argument, so
there is no reason for I<proposition> to exist as an actual function.

=head2 sys.std.Core.Bool.and

C<< function sys.std.Core.Bool.and (Bool <-- $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 commutative,
associative, and idempotent) on them until just one is left, which is the
function's result.  For each pair of input values, the I<and> of that pair
is C<Bool:true> iff both input values are C<Bool:true>, and C<Bool:false>
otherwise.  If C<topic> has zero values, then C<and> results in
C<Bool:true>, which is the identity value for logical I<and>.  Note that
this operation is also known as I<all> or I<every> or I<conjunction> or
C<∧>.

=head2 sys.std.Core.Bool.all

C<< function sys.std.Core.Bool.all (Bool <-- $topic? : set_of.Bool) >>

This function is an alias for C<sys.std.Core.Bool.and>.  This function
results in C<Bool:true> iff all of its input element values are
C<Bool:true> (or it has no input values), and C<Bool:false> otherwise (when
it has at least one input value that is C<Bool:false>).

=head2 sys.std.Core.Bool.or

C<< function sys.std.Core.Bool.or (Bool <-- $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
commutative, associative, and idempotent) on them until just one is left,
which is the function's result.  For each pair of input values, the I<or>
of that pair is C<Bool:false> iff both input values are C<Bool:false>, and
C<Bool:true> otherwise.  If C<topic> has zero values, then C<or> results in
C<Bool:false>, which is the identity value for logical inclusive-or.  Note
that this operation is also known as I<any> or I<some> or I<disjunction> or
C<∨>.

=head2 sys.std.Core.Bool.any

C<< function sys.std.Core.Bool.any (Bool <-- $topic? : set_of.Bool) >>

This function is an alias for C<sys.std.Core.Bool.or>.  This function
results in C<Bool:true> iff any of its input element values are
C<Bool:true>, and C<Bool:false> otherwise (when all of its input values are
C<Bool:false> or if it has no input values).

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

=head2 sys.std.Core.Tuple.attr

C<< function sys.std.Core.Tuple.attr (Universal <-- $topic : Tuple,
$name : 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.  Note that
this operation is also known as C<.%{}>.

=head2 sys.std.Core.Tuple.update_attr

C<< function sys.std.Core.Tuple.update_attr (Tuple <-- $topic : Tuple,
$name : Name, $value : Universal) >>

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.

=head2 sys.std.Core.Tuple.multi_update

C<< function sys.std.Core.Tuple.multi_update (Tuple <-- $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_subst>.

=head2 sys.std.Core.Tuple.rename

C<< function sys.std.Core.Tuple.rename (Tuple <-- $topic : Tuple,
$map : 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<after> and C<before> attributes of a C<map> tuple representing the
new and old 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.  Note that this operation is also known as C<< %{<-} >>.

=head2 sys.std.Core.Tuple.projection

C<< function sys.std.Core.Tuple.projection (Tuple <-- $topic : Tuple,
$attr_names : set_of.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<attr_names> argument.  As a trivial case, this function's result is
C<topic> if C<attr_names> lists all attributes of C<topic>; or, it is the
nullary tuple if C<attr_names> is empty.  This function will fail if
C<attr_names> specifies any attribute names that C<topic> doesn't have.
Note that this operation is also known as C<%{}>.

=head2 sys.std.Core.Tuple.cmpl_proj

C<< function sys.std.Core.Tuple.cmpl_proj (Tuple <-- $topic : Tuple,
$attr_names : set_of.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.  Note that this operation is also known as C<%{!}>.

=head2 sys.std.Core.Tuple.static_exten

C<< function sys.std.Core.Tuple.static_exten (Tuple <--
$topic : Tuple, $attrs : Tuple) >>

This function results in the extension of its C<topic> argument by joining
that with its C<attrs> argument; the attribute names of the 2 arguments
must be disjoint.  See also C<sys.std.Core.Tuple.product> for an N-adic
version of this.

=head2 sys.std.Core.Tuple.wrap

C<< function sys.std.Core.Tuple.wrap (Tuple <-- $topic : Tuple,
$outer : Name, $inner : set_of.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 a C<topic> attribute that isn't being wrapped.  Note that this
operation is also known as C<< %{%<-} >>.

=head2 sys.std.Core.Tuple.cmpl_wrap

C<< function sys.std.Core.Tuple.cmpl_wrap (Tuple <-- $topic : Tuple,
$outer : Name, $cmpl_inner : set_of.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>.  Note
that this operation is also known as C<< %{%<-!} >>.

=head2 sys.std.Core.Tuple.unwrap

C<< function sys.std.Core.Tuple.unwrap (Tuple <-- $topic : Tuple,
$inner : set_of.Name, $outer : 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}> has the same name as
another C<topic> attribute.  Now conceptually speaking, the C<inner>
parameter is completely superfluous for this C<Tuple> variant of C<unwrap>;
however, it is provided anyway so that this function has complete API
parity with the C<Relation> variant of C<unwrap>, where C<inner> I<is>
necessary in the general case, and so Muldis D code using this function is
also forced to be more self-documenting or strongly typed.  This function
will fail if C<inner> does not match the names of the attributes of
C<topic{outer}>.  Note that this operation is also known as C<< %{<-%} >>.

=head2 sys.std.Core.Tuple.product

C<< function sys.std.Core.Tuple.product (Tuple <-- $topic : 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.

=head2 sys.std.Core.Tuple.is_member

C<< function sys.std.Core.Tuple.is_member (Bool <--
$t : Tuple, $r : Relation) >>

This function is an alias for C<sys.std.Core.Relation.has_member>.  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.  Note that this operation is also known as C<∈>.

=head2 sys.std.Core.Tuple.is_not_member

C<< function sys.std.Core.Tuple.is_not_member (Bool <--
$t : Tuple, $r : Relation) >>

This function is an alias for C<sys.std.Core.Relation.has_not_member>.
This function is exactly the same as C<sys.std.Core.Tuple.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<∉>.

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

=head2 sys.std.Core.Relation.cardinality

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

This function results in the cardinality of its argument (that is, the
count of tuples its body has).  Note that this operation is also known as
I<count> or C<R#>.

=head2 sys.std.Core.Relation.count

C<< function sys.std.Core.Relation.count (NNInt <-- $topic : Relation) >>

This function is an alias for C<sys.std.Core.Relation.cardinality>.

=head2 sys.std.Core.Relation.has_member

C<< function sys.std.Core.Relation.has_member (Bool <-- $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 will warn if its 2
arguments' common-named attributes have declared types that are
incompatible as per C<is_identical>.  Note that this operation is also
known as C<∋>.

=head2 sys.std.Core.Relation.has_not_member

C<< function sys.std.Core.Relation.has_not_member (Bool <-- $r : Relation,
$t : Tuple) >>

This function is exactly the same as C<sys.std.Core.Relation.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<∌>.

=head2 sys.std.Core.Relation.Tuple_from_Relation

C<< function sys.std.Core.Relation.Tuple_from_Relation (Tuple <--
$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.  Note that this operation is also known as C<t>.

=head2 sys.std.Core.Relation.Relation_from_Tuple

C<< function sys.std.Core.Relation.Relation_from_Tuple (Relation <--
$topic : Tuple) >>

This function results in the C<Relation> value those body has just the one
C<Tuple> that is its argument.  Note that this operation is also known as
C<r>.

=head2 sys.std.Core.Relation.insertion

C<< function sys.std.Core.Relation.insertion (Relation <-- $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>.

=head2 sys.std.Core.Relation.disjoint_ins

C<< function sys.std.Core.Relation.disjoint_ins (Relation <--
$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>.

=head2 sys.std.Core.Relation.deletion

C<< function sys.std.Core.Relation.deletion (Relation <-- $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>.

=head2 sys.std.Core.Relation.rename

C<< function sys.std.Core.Relation.rename (Relation <-- $topic : Relation,
$map : 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>.  Note
that this operation is also known as C<< @{<-} >>.

=head2 sys.std.Core.Relation.projection

C<< function sys.std.Core.Relation.projection (Relation <--
$topic : Relation, $attr_names : set_of.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.
Note that this operation is also known as C<@{}>.

=head2 sys.std.Core.Relation.cmpl_proj

C<< function sys.std.Core.Relation.cmpl_proj (Relation <--
$topic : Relation, $attr_names : set_of.Name) >>

This function is the same as C<sys.std.Core.Tuple.cmpl_proj> but
that it operates on and results in a C<Relation> rather than a C<Tuple>.
Note that this operation is also known as C<@{!}>.

=head2 sys.std.Core.Relation.wrap

C<< function sys.std.Core.Relation.wrap (Relation <-- $topic : Relation,
$outer : Name, $inner : set_of.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>.  The result relation has the same cardinality
as C<topic>.  Note that this operation is also known as C<< @{%<-} >>.

=head2 sys.std.Core.Relation.cmpl_wrap

C<< function sys.std.Core.Relation.cmpl_wrap (Relation <--
$topic : Relation, $outer : Name, $cmpl_inner : set_of.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>.  Note that this operation is also known as
C<< @{%<-!} >>.

=head2 sys.std.Core.Relation.unwrap

C<< function sys.std.Core.Relation.unwrap (Relation <-- $topic : Relation,
$inner : set_of.Name, $outer : 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 simplest concept of a
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}>.
This function will fail with a non-C<DHRelation> valued C<topic> unless,
for every tuple of C<topic>, the attribute specified by C<outer> is valued
with a tuple of the same degree and heading (attribute names); this
failure is because there would be no consistent set of attribute names to
extend C<topic> with (a problem that would never happen by definition with
a deeply homogeneous relation C<topic>).  Note that this operation is also
known as C<< @{<-%} >>.

=head2 sys.std.Core.Relation.group

C<< function sys.std.Core.Relation.group (Relation <-- $topic : Relation,
$outer : Name, $inner : set_of.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> (except that the result has zero tuples when
C<topic> does).  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.
Note that this operation is also known as I<nest> or C<< @{@<-} >>.

=head2 sys.std.Core.Relation.cmpl_group

C<< function sys.std.Core.Relation.cmpl_group (Relation <--
$topic : Relation, $outer : Name, $group_per : set_of.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>.  Note
that this operation is also known as C<< @{@<-!} >>.

=head2 sys.std.Core.Relation.ungroup

C<< function sys.std.Core.Relation.ungroup (Relation <--
$topic : Relation, $inner : set_of.Name, $outer : 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}> has the same name as another C<topic> attribute.  This
function will fail with a non-C<DHRelation> valued C<topic> unless, for
every tuple of C<topic>, the attribute specified by C<outer> is valued with
a relation of the same degree and heading (attribute names); this failure
is because there would be no consistent set of attribute names to extend
C<topic> with (a problem that would never happen by definition with a
deeply homogeneous relation C<topic>).  Note that this operation is also
known as I<unnest> or C<< @{<-@} >>.

=head2 sys.std.Core.Relation.restriction

C<< function sys.std.Core.Relation.restriction (Relation <--
$topic : Relation, $func : ValFiltFuncRef) >>

This function results in the relational restriction of its C<topic>
argument as determined by applying the C<value-filter> function named in
its C<func>
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.  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 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.

=head2 sys.std.Core.Relation.restr_and_cmpl

C<< function sys.std.Core.Relation.restr_and_cmpl (Tuple <--
$topic : Relation, $func : ValFiltFuncRef) >>

This function performs a 2-way partitioning of all the tuples of C<topic>
and results in a binary tuple whose attribute values are each relations
that have the same heading as C<topic> and complementary subsets of its
tuples; the 2 result attributes have the names C<pass> and C<fail>, and
their values are what C<sys.std.Core.Relation.restriction> and
C<sys.std.Core.Relation.cmpl_restr>, respectively, would result in
when given the same arguments.

=head2 sys.std.Core.Relation.cmpl_restr

C<< function sys.std.Core.Relation.cmpl_restr (Relation <--
$topic : Relation, $func : ValFiltFuncRef) >>

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.semidiff> function.

=head2 sys.std.Core.Relation.extension

C<< function sys.std.Core.Relation.extension (Relation <--
$topic : Relation, $attr_names : set_of.Name, $func : ValMapFuncRef) >>

This function results in the relational extension of its C<topic> argument
as determined by applying the C<Tuple>-resulting C<value-map> function
named in its C<func>
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; 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>.  Now,
C<extension> requires the extra C<attr_names> argument to prevent ambiguity
in the general case where C<topic> might have zero tuples, because in
that situation, C<func> would never be invoked, and the names of the
attributes to add to C<topic> are not known (we don't generally assume that
C<extension> can reverse-engineer C<func> to see what attributes it would
have resulted in).  This function will fail if C<topic> has at least 1
tuple and the result of C<func> does not have matching attribute names to
those named by C<attr_names>.

=head2 sys.std.Core.Relation.static_exten

C<< function sys.std.Core.Relation.static_exten (Relation <--
$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.

=head2 sys.std.Core.Relation.summary

C<< function sys.std.Core.Relation.summary (Relation <--
$topic : Relation, $group_per : set_of.Name,
$summ_attr_names : set_of.Name, $summ_func : ValMapFuncRef) >>

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
binary tuple in the main relation, this function applies the
C<Tuple>-resulting C<value-map> function named in its C<summ_func>
argument; for each post-group main relation
tuple, the function named in C<summ_func> results in a second tuple when
the first tuple is its C<topic> argument; the C<topic> argument has the 2
attribute names C<summarize> and C<per>, which are valued with the
relation-valued attribute and
tuple-valued attribute, respectively.  As per a function that
C<extension> applies, the function named by C<summ_func> effectively takes
a whole post-grouping input tuple and results in a partial tuple that
would be joined by C<summary> with the C<per> tuple to get the result
tuple; the applied
function would directly invoke any N-adic/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<summ_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.
Now, C<summary> requires the extra C<summ_attr_names> argument to prevent
ambiguity in the general case where C<topic> might have zero tuples,
because in that situation, C<summ_func> would never be invoked, and the
names of the attributes to add to C<per> are not known (we don't generally
assume that C<summary> can reverse-engineer C<summ_func> to see what
attributes it would have resulted in).  This function will fail if C<topic>
has at least 1 tuple and the result of C<summ_func> does not have
matching attribute names to those named by C<summ_attr_names>.

=head2 sys.std.Core.Relation.cardinality_per_group

C<< function sys.std.Core.Relation.cardinality_per_group (Relation <--
$topic : Relation, $count_attr_name : Name, $group_per : set_of.Name) >>

This function is a convenient shorthand for the common use of C<summary>
that is just counting the tuples of each group.  This function is like
C<cmpl_group> but that the single added attribute, rather than an RVA of
the grouped C<topic> attributes, has the cardinality that said RVA would
have had.  The result's heading consists of the attributes named in
C<group_per> plus the attribute named in C<count_attr_name> (a C<PInt>).
Note that this operation is also known as C<< @{#@<-!} >>.

=head2 sys.std.Core.Relation.count_per_group

C<< function sys.std.Core.Relation.count_per_group (Relation <--
$topic : Relation, $count_attr_name : Name, $group_per : set_of.Name) >>

This function is an alias for
C<sys.std.Core.Relation.cardinality_per_group>.

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

=head2 sys.std.Core.Relation.is_subset

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

This function results in C<Bool:true> iff the set of tuples comprising
C<topic> is a subset of the set of tuples comprising C<other>, and
C<Bool:false> otherwise.  This function will warn if the input relations
common-named attributes have declared types that are incompatible as per
C<is_identical>.  Note that this operation is also known as C<⊆>.

=head2 sys.std.Core.Relation.is_not_subset

C<< function sys.std.Core.Relation.is_not_subset (Bool <--
$topic : Relation, $other : 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.  Note that this operation is also known as C<⊈>.

=head2 sys.std.Core.Relation.is_superset

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

This function is an alias for C<sys.std.Core.Relation.is_subset> except
that it transposes the C<topic> and C<other> arguments.  This function
results in C<Bool:true> iff the set of tuples comprising C<topic> is a
superset of the set of tuples comprising C<other>, and C<Bool:false>
otherwise.  Note that this operation is also known as C<⊇>.

=head2 sys.std.Core.Relation.is_not_superset

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

This function is an alias for C<sys.std.Core.Relation.is_not_subset>
except that it transposes the C<topic> and C<other> arguments.  This
function is exactly the same as C<sys.std.Core.Relation.is_superset>
except that it results in the opposite boolean value when given the same
arguments.  Note that this operation is also known as C<⊉>.

=head2 sys.std.Core.Relation.union

C<< function sys.std.Core.Relation.union (Relation <--
$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 commutative,
associative, and idempotent) 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.  Note that this operation is
also known as C<∪>.

=head2 sys.std.Core.Relation.disjoint_union

C<< function sys.std.Core.Relation.disjoint_union (Relation <--
$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.

=head2 sys.std.Core.Relation.intersection

C<< function sys.std.Core.Relation.intersection (Relation <--
$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
commutative, associative, and idempotent) 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.  Note that this
operation is also known as C<∩>.

=head2 sys.std.Core.Relation.diff

C<< function sys.std.Core.Relation.diff (Relation <--
$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 warn if the input relations common-named attributes have declared
types that are incompatible as per C<is_identical>.  Note that this
I<difference> operator is conceptually a special case of I<semidiff>,
applicable when the headings of the inputs are the same.  Note that this
operation is also known as I<minus> or I<except> or C<∖>.

=head2 sys.std.Core.Relation.semidiff

C<< function sys.std.Core.Relation.semidiff (Relation <--
$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 known as I<antijoin> or I<anti-semijoin>
or I<semiminus> or C<!matching> or C<not-matching> or C<⊿>.

=head2 sys.std.Core.Relation.antijoin

C<< function sys.std.Core.Relation.antijoin (Relation <--
$source : Relation, $filter : Relation) >>

This function is an alias for C<sys.std.Core.Relation.semidiff>.

=head2 sys.std.Core.Relation.semijoin_and_diff

C<< function sys.std.Core.Relation.semijoin_and_diff (Tuple <--
$source : Relation, $filter : Relation) >>

This function performs a 2-way partitioning of all the tuples of
C<source> and results in a binary tuple whose attribute values are each
relations that have the same heading as C<source> and complementary
subsets of its tuples; the 2 result attributes have the names C<pass> and
C<fail>, and their values are what C<sys.std.Core.Relation.semijoin> and
C<sys.std.Core.Relation.semidiff>, respectively, would result in
when given the same arguments.

=head2 sys.std.Core.Relation.semijoin

C<< function sys.std.Core.Relation.semijoin (Relation <--
$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.
Note that this operation is also known as C<matching> or C<⋉>.

=head2 sys.std.Core.Relation.join

C<< function sys.std.Core.Relation.join (Relation <--
$topic? : 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 commutative, associative, and
idempotent) 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 two is a semijoin with the
former filtering the latter.  This function will warn if any input
relations have attributes with common names where their declared types
are incompatible as per C<is_identical>.  Note that this operation is also
known as I<natural inner join> or C<⋈>.

=head2 sys.std.Core.Relation.product

C<< function sys.std.Core.Relation.product (Relation <--
$topic? : 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 known as I<cartesian join> or
C<cross-join> or C<×>.

=head2 sys.std.Core.Relation.quotient

C<< function sys.std.Core.Relation.quotient (Relation <--
$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} × $B) ∖ $A)@{X})>.  Note that this operation is also known as
I<divideby> or C<÷>.

=head1 SYSTEM-DEFINED GENERIC CONTROL FLOW FUNCTIONS

=head2 sys.std.Core.Control.func_invo

C<< function sys.std.Core.Control.func_invo (Universal <--
$function : FuncRef, $args? : Tuple) >>

This function results in the result of invoking the other function named in
its C<function> argument with arguments supplied by this function's 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 tuple if no
explicit argument is given to it.

=head2 sys.std.Core.Control.curried_func

C<< function sys.std.Core.Control.curried_func (FuncRef <--
$function : FuncRef, $args : Tuple) >>

This function results in a reference to a new anonymous function which is
the result of currying the other function named in its C<function> argument
with 0..N arguments supplied by this function's C<args> argument; each
attribute name of C<args> is mapped to a parameter name of the curried
function, and the corresponding attribute value is the corresponding
pre-bound parameter of the curried function.  This function will fail 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.  A curried function effectively does not have the
parameters of the original function that were pre-bound, and attempts to
supply arguments to those on the curried function will fail.  Note that the
result of a C<curried_func> invocation can be used as input to another one,
as there is effectively no difference in their kind.  The purpose of
C<curried_func> is to support the passing of functions as arguments to
invocations of other routines where the passed function wants to use
runtime-defined information in the context that invoked routine, without
having to pass that information separately as additional routine arguments.
Or the purpose of C<curried_func> is just to easily support defining
functions as simplified versions of others.

=head1 SYSTEM-DEFINED GENERIC UNIVERSAL UPDATERS

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

=head2 sys.std.Core.Universal.assign

C<updater sys.std.Core.Universal.assign (&$target : Universal,
$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>.

=head1 SYSTEM-DEFINED GENERIC TUPLE VARIABLE UPDATERS

=head1 Updaters That Rename Attributes

=head2 sys.std.Core.Tuple.assign_rename

C<updater sys.std.Core.Tuple.assign_rename (&$topic : Tuple,
$map : AttrRenameMap)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Tuple.rename> function with the same arguments, and then
assigning the result of that function to C<topic>.  This procedure is
analagous to the data-manipulation phase of a SQL RENAME TABLE|VIEW or
ALTER TABLE|VIEW RENAME TO statement iff C<topic> is C<Database>-typed;
each tuple of C<map> corresponds to a renamed SQL table.

=head1 Updaters That Add Attributes

=head2 sys.std.Core.Tuple.assign_static_exten

C<updater sys.std.Core.Tuple.assign_static_exten (&$topic : Tuple,
$attrs : Tuple)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Tuple.static_exten> function with the same arguments,
and then assigning the result of that function to C<topic>.  This procedure
is analagous to the data-manipulation phase of a SQL CREATE TABLE|VIEW
statement iff both arguments are C<Database>-typed; each relation-typed
attribute of C<attrs> corresponds to a created SQL table.

=head1 Updaters That Remove Attributes

=head2 sys.std.Core.Tuple.assign_projection

C<updater sys.std.Core.Tuple.assign_projection (&$topic : Tuple,
$attr_names : set_of.Name)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Tuple.projection> function with the same arguments, and
then assigning the result of that function to C<topic>.

=head2 sys.std.Core.Tuple.assign_cmpl_proj

C<updater sys.std.Core.Tuple.assign_cmpl_proj (&$topic : Tuple,
$attr_names : set_of.Name)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Tuple.cmpl_proj> function with the same arguments,
and then assigning the result of that function to C<topic>.  This procedure
is analagous to the data-manipulation phase of a SQL DROP TABLE|VIEW
statement iff C<topic> is C<Database>-typed; each relation-typed
attribute named by C<attr_names> corresponds to a dropped SQL table.

=head1 SYSTEM-DEFINED GENERIC RELATION VARIABLE UPDATERS

=head1 Updaters That Add Tuples

=head2 sys.std.Core.Relation.assign_insertion

C<updater sys.std.Core.Relation.assign_insertion (&$r : Relation,
$t : Tuple)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Relation.insertion> function with the same arguments, and
then assigning the result of that function to C<r>.  This updater is
analagous to the general case of the single-row SQL "INSERT" statement.

=head2 sys.std.Core.Relation.assign_disjoint_ins

C<updater sys.std.Core.Relation.assign_disjoint_ins (&$r : Relation,
$t : Tuple)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Relation.disjoint_ins> function with the same
arguments, and then assigning the result of that function to C<r>.

=head2 sys.std.Core.Relation.assign_union

C<updater sys.std.Core.Relation.assign_union (&$topic : Relation,
$other : Relation)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Relation.union> function such that it has 2 input
relations from C<assign_union>'s 2 arguments, and then assigning the
result of that function to C<topic>.  This updater is analagous to the
general case of the multiple-row SQL "INSERT" statement.

=head2 sys.std.Core.Relation.assign_disjoint_union

C<updater sys.std.Core.Relation.assign_disjoint_union (&$topic : Relation,
$other : Relation)>

This update operator is to C<sys.std.Core.Relation.disjoint_union> what
the function C<sys.std.Core.Relation.assign_union> is to
C<sys.std.Core.Relation.union>.

=head1 Updaters That Remove Tuples

=head2 sys.std.Core.Relation.assign_deletion

C<updater sys.std.Core.Relation.assign_deletion (&$r : Relation,
$t : Tuple)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Relation.deletion> function with the same arguments, and
then assigning the result of that function to C<r>.

=head2 sys.std.Core.Relation.assign_restriction

C<updater sys.std.Core.Relation.assign_restriction (&$topic : Relation,
$func : ValFiltFuncRef)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Relation.restriction> function with the same arguments, and
then assigning the result of that function to C<topic>.

=head2 sys.std.Core.Relation.assign_cmpl_restr

C<updater sys.std.Core.Relation.assign_cmpl_restr
(&$topic : Relation, $func : ValFiltFuncRef)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Relation.cmpl_restr> function with the same arguments, and
then assigning the result of that function to C<topic>. This updater is
analagous to the general case of the SQL "DELETE" statement.

=head2 sys.std.Core.Relation.assign_intersection

C<updater sys.std.Core.Relation.assign_intersection (&$topic : Relation,
$other : Relation)>

This update operator is to C<sys.std.Core.Relation.intersection> what the
function C<sys.std.Core.Relation.assign_union> is to
C<sys.std.Core.Relation.union>.

=head2 sys.std.Core.Relation.assign_diff

C<updater sys.std.Core.Relation.assign_diff (&$source : Relation,
$filter : Relation)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Relation.diff> function with the same arguments, and
then assigning the result of that function to C<source>.

=head2 sys.std.Core.Relation.assign_semidiff

C<updater sys.std.Core.Relation.assign_semidiff (&$source : Relation,
$filter : Relation)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Relation.semidiff> function with the same arguments,
and then assigning the result of that function to C<source>.  This updater
is analagous to the common case of the SQL "DELETE" statement where the
criteria is simply a set of and-ed and or-ed value equality tests.

=head2 sys.std.Core.Relation.assign_antijoin

C<updater sys.std.Core.Relation.assign_antijoin (&$source : Relation,
$filter : Relation)>

This update operator is an alias for
C<sys.std.Core.Relation.assign_semidiff>.

=head2 sys.std.Core.Relation.assign_semijoin

C<updater sys.std.Core.Relation.assign_semijoin (&$source : Relation,
$filter : Relation)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Relation.semijoin> function with the same arguments, and
then assigning the result of that function to C<source>.

=head1 Updaters That Rename Attributes

=head2 sys.std.Core.Relation.assign_rename

C<updater sys.std.Core.Relation.assign_rename (&$topic : Relation,
$map : AttrRenameMap)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Relation.rename> function with the same arguments, and then
assigning the result of that function to C<topic>.  This procedure is
analagous to the data-manipulation phase of a SQL ALTER TABLE|VIEW RENAME
COLUMN statement; each tuple of C<map> corresponds to a renamed SQL table
column.

=head1 Updaters That Add Attributes

=head2 sys.std.Core.Relation.assign_extension

C<updater sys.std.Core.Relation.assign_extension (&$topic : Relation,
$attr_names : set_of.Name, $func : ValMapFuncRef)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Relation.extension> function with the same arguments, and
then assigning the result of that function to C<topic>.

=head2 sys.std.Core.Relation.assign_static_exten

C<updater sys.std.Core.Relation.assign_static_exten
(&$topic : Relation, $attrs : Tuple)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Relation.static_exten> function with the same
arguments, and then assigning the result of that function to C<topic>.
This procedure is analagous to the data-manipulation phase of a SQL ALTER
TABLE|VIEW ADD COLUMN statement; each attribute of C<attrs> corresponds to
an added SQL table column.

=head1 Updaters That Remove Attributes

=head2 sys.std.Core.Relation.assign_projection

C<updater sys.std.Core.Relation.assign_projection (&$topic : Relation,
$attr_names : set_of.Name)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Relation.projection> function with the same arguments, and
then assigning the result of that function to C<topic>.

=head2 sys.std.Core.Relation.assign_cmpl_proj

C<updater sys.std.Core.Relation.assign_cmpl_proj (&$topic : Relation,
$attr_names : set_of.Name)>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Relation.cmpl_proj> function with the same arguments,
and then assigning the result of that function to C<topic>.  This procedure
is analagous to the data-manipulation phase of a SQL ALTER TABLE|VIEW DROP
COLUMN statement; each attribute named by C<attr_names> corresponds to an
dropped SQL table column.

=head1 SYSTEM-DEFINED GENERIC CONTROL FLOW UPDATERS

=head2 sys.std.Core.Control.upd_invo

C<updater sys.std.Core.Control.upd_invo ($updater : UpdRef,
&$upd_args : Tuple, $ro_args? : Tuple)>

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<ro_args>
parameter is optional and defaults as per the C<args> parameter of
C<func_invo>; the C<upd_args> parameter is non-optional because an updater
must always be invoked with at least one subject-to-update argument.

=head1 SYSTEM-DEFINED GENERIC SYSTEM SERVICES FOR STANDARD I/O

These system services are provided so Muldis D can do basic user
input/output by itself, using standard input and standard output, like any
general purpose programming language, and help satisfy its need to be
computationally complete.  For now they just work with plain (Unicode) text
data, so one can implement a basic command-line program interface, or do
basic invoker-setup file piping, as well as display diagnostics to standard
error.  These routines are not exhaustive, and their details are subject to
future revision.

=head2 sys.std.Core.STDIO.read_Text

C<system-service sys.std.Core.STDIO.read_Text (&$target : Text,
$len_in_graphs : NNInt)>

This system service routine will attempt to read C<len_in_graphs>
characters from standard input as a single C<Text> value, blocking the
current in-DBMS process until it finishes, and then update the variable
supplied as its C<target> argument so that it holds the read value.  The
routine will only fetch fewer than the requested number of characters if
the input stream is closed first.  This routine will throw an exception if
any system errors occur.

=head2 sys.std.Core.STDIO.read_Text_line

C<system-service sys.std.Core.STDIO.read_Text_line (&$target : Text,
$ignore_empty_lines? : Bool)>

This system service routine is the same as C<sys.std.Core.STDIO.read_Text>
except that it will read from standard input until an
implementation-defined end-of-line character is read, rather than reading a
fixed number of characters; this end-of-line character will not be included
in the read C<Text> value.  If the C<ignore_empty_lines> argument is
C<Bool:true>, then this routine will keep reading lines from standard input
until it reads a non-empty line, and then C<target> is only updated to hold
that last non-empty line; otherwise, this routine will end as soon as one
line is read, even if it is empty.

=head2 sys.std.Core.STDIO.write_Text

C<system-service sys.std.Core.STDIO.write_Text ($v : Text)>

This system service routine will attempt to write the characters of its
C<v> argument to standard output, blocking the current in-DBMS process
until it finishes.  This routine will throw an exception if any system
errors occur.

=head2 sys.std.Core.STDIO.write_Text_line

C<system-service sys.std.Core.STDIO.write_Text_line ($v : Text)>

This system service routine is the same as C<sys.std.Core.STDIO.write_Text>
except that it will additionally write an implementation-defined
end-of-line character after writing C<v>.

=head2 sys.std.Core.STDIO.prompt_Text_line

C<system-service sys.std.Core.STDIO.prompt_Text_line (&$target : Text,
$prompt : Text, $ignore_empty_lines? : Bool )>

This system service routine is a wrapper over first invoking
C<sys.std.Core.STDIO.write_Text> with its C<prompt> argument and then
invoking C<sys.std.Core.STDIO.read_Text_line> with its C<target> argument.
A true C<ignore_empty_lines> argument will result in I<both> of the wrapped
routines being invoked repeatedly, not just C<read_text_line>.

=head2 sys.std.Core.STDIO.error_Text

C<system-service sys.std.Core.STDIO.error_Text ($v : Text)>

This system service routine is the same as C<sys.std.Core.STDIO.write_Text>
except that it will write to standard error rather than standard output.

=head2 sys.std.Core.STDIO.error_Text_line

C<system-service sys.std.Core.STDIO.error_Text_line ($v : Text)>

This system service routine is the same as
C<sys.std.Core.STDIO.write_Text_line> except that it will write to standard
error rather than standard output.

=head1 SYSTEM-DEFINED GENERIC CONTROL FLOW PROCEDURES

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

=head2 sys.std.Core.Control.proc_invo

C<procedure sys.std.Core.Control.proc_invo ($procedure : ProcRef,
&$upd_args? : Tuple, $ro_args? : Tuple)>

This procedure is the same as C<sys.std.Core.Control.upd_invo> but that it
invokes a procedure (or system-service) rather than an updater, and
that C<upd_args> is optional.

=head2 sys.std.Core.Control.fail

C<procedure sys.std.Core.Control.fail ($topic : 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.

=head2 sys.std.Core.Control.try_catch

C<procedure sys.std.Core.Control.try_catch
($try : ProcRef, &$try_upd_args? : Tuple, $try_ro_args? : Tuple,
$catch? : ProcRef, &$catch_upd_args? : Tuple, $catch_ro_args? : Tuple)>

This procedure invokes the procedure (or system-service)
named in its C<try> argument
with arguments supplied by this procedure's C<try_upd_args> and
C<try_ro_args> arguments; each attribute name of C<try_[upd|ro]_args> is
mapped to a parameter name of the invoked procedure, and the corresponding
attribute value is the corresponding argument for the procedure
invocation.  If the C<try> routine
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 an C<Exception>; if the C<catch> routine
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> routine succeeds (doesn't throw an exception), then the C<catch>
routine is not called.  Each of the C<[try|catch]_[upd|ro]_args>
parameters is optional and defaults to the zero-attribute tuple if no
explicit argument is given to it.

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