=pod

=encoding utf8

=head1 NAME

Muldis::D::Core::Relation -
Muldis D generic relational operators

=head1 VERSION

This document is Muldis::D::Core::Relation version 0.148.0.

=head1 PREFACE

This document is part of the Muldis D language specification, whose root
document is L<Muldis::D>; you should read that root document before
you read this one, which provides subservient details.  Moreover, you
should read the L<Muldis::D::Core> document before this current
document, as that forms its own tree beneath a root document branch.

=head1 DESCRIPTION

This document describes essentially all of the core Muldis D generic
relational operators (for generic relations).

I<This documentation is pending.>

=head1 FUNCTIONS IMPLEMENTING VIRTUAL ATTRIBUTIVE FUNCTIONS

=head2 sys.std.Core.Relation.degree

C<< function degree (NNInt <-- topic : Relation)
implements sys.std.Core.Attributive.degree {...} >>

This function results in the degree of its argument (that is, the count of
attributes it has).

=head2 sys.std.Core.Relation.is_nullary

C<< function is_nullary (Bool <-- topic : Relation)
implements sys.std.Core.Attributive.is_nullary {...} >>

This function results in C<Bool:True> iff its argument has a degree of zero
(that is, it has zero attributes), and C<Bool:False> otherwise.  By
definition, the only 2 relation values for which this function would
result in C<Bool:True> are the values C<Relation:D0C[0|1]>.

=head2 sys.std.Core.Relation.is_not_nullary

C<< function is_not_nullary (Bool <-- topic : Relation)
implements sys.std.Core.Attributive.is_not_nullary {...} >>

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

=head2 sys.std.Core.Relation.has_attrs

C<< function has_attrs (Bool <-- topic : Relation,
attr_names : set_of.Name)
implements sys.std.Core.Attributive.has_attrs {...} >>

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 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.Relation.attr_names

C<< function attr_names (set_of.Name <-- topic : Relation)
implements sys.std.Core.Attributive.attr_names {...} >>

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

=head2 sys.std.Core.Relation.rename

C<< function rename (Relation <-- topic : Relation, map : AttrRenameMap)
implements sys.std.Core.Attributive.rename {...} >>

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

=head2 sys.std.Core.Relation.projection

C<< function projection (Relation <--
topic : Relation, attr_names : set_of.Name)
implements sys.std.Core.Attributive.projection {...} >>

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.

=head2 sys.std.Core.Relation.cmpl_proj

C<< function cmpl_proj (Relation <--
topic : Relation, attr_names : set_of.Name)
implements sys.std.Core.Attributive.cmpl_proj {...} >>

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

=head2 sys.std.Core.Relation.static_exten

C<< function static_exten (Relation <-- topic : Relation, attrs : Tuple)
implements sys.std.Core.Attributive.static_exten {...} >>

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

C<< function wrap (Relation <-- topic : Relation, outer : Name,
inner : set_of.Name) implements sys.std.Core.Attributive.wrap {...} >>

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

=head2 sys.std.Core.Relation.cmpl_wrap

C<< function cmpl_wrap (Relation <--
topic : Relation, outer : Name, cmpl_inner : set_of.Name)
implements sys.std.Core.Attributive.cmpl_wrap {...} >>

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

=head2 sys.std.Core.Relation.unwrap

C<< function unwrap (Relation <-- topic : Relation, inner : set_of.Name,
outer : Name) implements sys.std.Core.Attributive.unwrap {...} >>

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

=head1 GENERIC RELATIONAL FUNCTIONS WITH SINGLE INPUT RELATION

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

C<< function D0C0 (Relation <--) {...} >>

This C<named-value> selector function results in the only zero-attribute,
zero-tuple Relation value, which is known by the special name
C<Relation:D0C0>, aka C<D0C0>.  Note that I<The Third Manifesto> also
refers to this value by the special shorthand name I<TABLE_DUM>.

=head2 sys.std.Core.Relation.D0C1

C<< function D0C1 (Relation <--) {...} >>

This C<named-value> selector function results in the only zero-attribute,
single-tuple Relation value, which is known by the special name
C<Relation:D0C1>, aka C<D0C1>.  Note that I<The Third Manifesto> also
refers to this value by the special shorthand name I<TABLE_DEE>.

=head2 sys.std.Core.Relation.cardinality

C<< function 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<#>.

=head2 sys.std.Core.Relation.count

C<< function count (NNInt <-- topic : Relation) {...} >>

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

=head2 sys.std.Core.Relation.is_empty

C<< function is_empty (Bool <-- topic : Relation) {...} >>

This function results in C<Bool:True> iff its argument has a cardinality of
zero (that is, it has zero tuples), and C<Bool:False> otherwise.  Note
that if you are using a C<Maybe> to represent a sparse data item,
analogously to a SQL nullable context, then testing the C<Maybe> with
C<is_empty> is analogous to testing a SQL nullable with C<is null>.

=head2 sys.std.Core.Relation.is_not_empty

C<< function is_not_empty (Bool <-- topic : Relation) {...} >>

This function is exactly the same as C<sys.std.Core.Relation.is_empty>
except that it results in the opposite boolean value when given the same
argument.  And following the analogy with C<is_empty>, C<is_not_empty> is
analogous to SQL's C<is not null>.

=head2 sys.std.Core.Relation.has_member

C<< function 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_same>.  Note that this operation is also
known as C<@∋> or C<holds>.

=head2 sys.std.Core.Relation.has_not_member

C<< function 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<@∌> or C<!holds> or
C<not-holds>.

=head2 sys.std.Core.Relation.tuple_is_member

C<< function 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<∈@>
or C<inside>.

=head2 sys.std.Core.Relation.tuple_is_not_member

C<< function 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.Relation.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<∉@> or C<!inside> or C<not-inside>.

=head2 sys.std.Core.Relation.has_key

C<< function has_key (Bool <-- topic : Relation,
attr_names : set_of.Name) {...} >>

This function results in C<Bool:True> iff its C<topic> argument has a
(unique) key over the subset of its attributes whose names are specified by
its C<attr_names> argument; otherwise it results in C<Bool:False>.  This
function will fail if C<topic> does not have all of the attributes named by
C<attr_names>.  As a trivial case, this function's result is C<Bool:True>
if C<topic> is empty.

=head2 sys.std.Core.Relation.empty

C<< function empty (Relation <-- topic : Relation) {...} >>

This function results in the empty relation of the same heading of its
argument, that is having the same degree and attribute names; it has zero
tuples.

=head2 sys.std.Core.Relation.insertion

C<< function 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 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 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.group

C<< function 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 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 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.power_set

C<< function power_set (set_of.Relation <-- topic : Relation) {...} >>

This function results in the power set of its argument.  The result is a
C<Set> whose sole attribute is C<Relation>-typed (its type is nominally
the same as that of the argument) and which has a tuple for every
distinct subset of tuples in the argument.  The cardinality of the result
is equal to 2 raised to the power of the cardinality of the argument (which
may easily lead to a very large result, so use this function with care).
Note that the N-adic relational union of the power set of some relation
is that relation; the N-adic intersection of any power set is the empty
relation.

=head2 sys.std.Core.Relation.tclose

C<< function tclose (Relation <-- topic : Relation) {...} >>

This function results in the transitive closure of its argument.  The
argument must be a binary relation whose attributes are both of the same
type, and the result is a relation having the same heading and a body
which is a superset of the argument's tuples.  Assuming that the argument
represents all of the node pairs in a directed graph that have an arc
between them, and so each argument tuple represents an arc, C<tclose>
will determine all of the node pairs in that graph which have a path
between them (a recursive operation), so each tuple of the result
represents a path.  The result is a superset since all arcs are also
complete paths.  The C<tclose> function is intended to support recursive
queries, such as in connection with the "part explosion problem" (the
problem of finding all components, at all levels, of some specified part).

=head2 sys.std.Core.Relation.restriction

C<< function restriction (Relation <--
topic : Relation, func : ValFiltCFuncNC) {...} >>

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 C<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 restr_and_cmpl (Tuple <--
topic : Relation, func : ValFiltCFuncNC) {...} >>

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 cmpl_restr (Relation <--
topic : Relation, func : ValFiltCFuncNC) {...} >>

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.  Note that this
operation is also known as C<!where> or C<not-where>.

=head2 sys.std.Core.Relation.classification

C<< function classification (Relation <--
topic : Relation, func : ValMapCFuncNC, class_attr_name : Name,
group_attr_name : Name) {...} >>

This function conceptually is to C<sys.std.Core.Relation.restriction> what
C<sys.std.Core.Relation.group> is to C<sys.std.Core.Relation.semijoin>.
It classifies the tuples of C<topic> into N groups using the C<value-map>
function named by C<func>, such that any distinct tuples are in a common
group if the function named by C<func> results in the same value when given
either of those tuples as its C<topic>
argument.  This function conceptually is a short-hand for first
extending C<topic> with a new attribute whose name is given in
C<class_attr_name>, whose value per tuple is determined from C<topic> using
C<func>, and then grouping that result relation on all of
its original attributes, with the post-group RVA having the name given in
C<group_attr_name>; the result of C<classification> is a binary relation
whose 2 attributes have the names given in C<class_attr_name> and
C<group_attr_name>.  This function is intended for use when you want to
partition a relation's tuples into an arbitrary number of groups using
arbitrary criteria, in contrast with C<restriction> where you are dividing
into exactly 2 groups (and returning one) using arbitrary criteria.

=head2 sys.std.Core.Relation.extension

C<< function extension (Relation <--
topic : Relation, attr_names : set_of.Name, func : ValMapCFuncNC) {...} >>

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

C<< function map (Relation <-- topic : Relation,
result_attr_names : set_of.Name, func : ValMapCFuncNC) {...} >>

This function provides a convenient one-place generalization of per-tuple
transformations that otherwise might require the chaining of up to a
half-dozen other operators like projection, extension, and rename.  This
function results in a relation each of whose tuples is the result of
applying, to each of the tuples of its C<topic> argument, the
C<Tuple>-resulting C<value-map> function named in its C<func>
argument.  There is no restriction
on what attributes the result tuple of C<func> may have (except that all
tuples from C<func> must have compatible headings); this tuple from
C<func> would completely replace the original tuple from C<topic>.  The
result relation has a cardinality that is the same as that of C<topic>,
unless the result of C<func> was redundant tuples, in which case the
result has appropriately fewer tuples.  As a trivial case, if C<func> is
defined to unconditionally result in the same tuple as its own C<topic>
argument, then this function results simply in C<topic>; or, if C<func> is
defined to have a static result, then this function's result will have just
0..1 tuples.  Now, C<map> requires the extra C<result_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 of the result are not known (we don't
generally assume that C<map> 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<result_attr_names>.

=head2 sys.std.Core.Relation.summary

C<< function summary (Relation <--
topic : Relation, group_per : set_of.Name,
summ_attr_names : set_of.Name, summ_func : ValMapCFuncNC) {...} >>

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

=head2 sys.std.Core.Relation.reduction

C<< function reduction (Tuple <-- topic : Relation,
func : ValRedCFuncNC, identity : Tuple) {...} >>

This function is a generic reduction operator that recursively takes each
pair of tuples in C<topic> and applies an argument-specified tuple
value-resulting C<value-reduction> function (which is both commutative and
associative) to the pair until just one input tuple is left, which is the
result.  The C<value-reduction> function to apply is named in the C<func>
argument, and that function must have 2 parameters named C<v1> and C<v2>,
which take the 2 input tuples for an invocation.  If C<topic> has zero
tuples, then C<reduction> results in the tuple given in C<identity>.
I<Note that C<identity> may be changed to take a function name rather than
a value, for consistency with C<func>.>  This function will fail|warn if
the |declared headings of C<identity> and C<topic> aren't compatible.

=head1 GENERIC RELATIONAL FUNCTIONS WITH MULTIPLE INPUT RELATIONS

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 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_same>.  Note that this operation is also known as C<⊆> or C<< {<=} >>.

=head2 sys.std.Core.Relation.is_not_subset

C<< function 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<⊈> or C<< {!<=} >>.

=head2 sys.std.Core.Relation.is_superset

C<< function 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<⊇> or C<< {>=} >>.

=head2 sys.std.Core.Relation.is_not_superset

C<< function 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<⊉> or C<< {!>=} >>.

=head2 sys.std.Core.Relation.is_proper_subset

C<< function is_proper_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 C<Bool:False> if its 2 arguments are identical.
Note that this operation is also known as C<⊂> or C<< {<} >>.

=head2 sys.std.Core.Relation.is_not_proper_subset

C<< function is_not_proper_subset (Bool <--
topic : Relation, other : Relation) {...} >>

This function is exactly the same as
C<sys.std.Core.Relation.is_proper_subset>
except that it results in the opposite boolean value when given the same
arguments.  Note that this operation is also known as C<⊄> or C<< {!<} >>.

=head2 sys.std.Core.Relation.is_proper_superset

C<< function is_proper_superset (Bool <--
topic : Relation, other : Relation) {...} >>

This function is an alias for C<sys.std.Core.Relation.is_proper_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 C<Bool:False> if its 2 arguments are identical.  Note that this
operation is also known as C<⊃> or C<< {>} >>.

=head2 sys.std.Core.Relation.is_not_proper_superset

C<< function is_not_proper_superset (Bool <--
topic : Relation, other : Relation) {...} >>

This function is an alias for C<sys.std.Core.Relation.is_not_proper_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_proper_superset>
except that it results in the opposite boolean value when given the same
arguments.  Note that this operation is also known as C<⊅> or C<< {!>} >>.

=head2 sys.std.Core.Relation.is_disjoint

C<< function is_disjoint (Bool <-- topic : Relation,
other : Relation) {...} >>

This symmetric function results in C<Bool:True> iff the set of tuples
comprising each of its 2 arguments are mutually disjoint, that is, iff the
intersection of the 2 arguments is empty; it results in C<Bool:False>
otherwise.

=head2 sys.std.Core.Relation.is_not_disjoint

C<< function is_not_disjoint (Bool <--
topic : Relation, other : Relation) {...} >>

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

=head2 sys.std.Core.Relation.union

C<< function 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 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.exclusion

C<< function exclusion (Relation <-- topic : bag_of.Relation) {...} >>

This function results in the relational exclusion/exclusive-or of the N
element values of its argument; it is a reduction operator that recursively
takes each pair of input values and relationally excludes (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 just an odd number
of the input relations.  Matters concerning a C<topic> with zero values
are as per C<sys.std.Core.Relation.union>; this function will fail when
given such, and the per-distinct-heading identity value for relational
exclusion is the same as for relational union.  Note that this operation is
also known as I<symmetric difference> or C<∆>.

=head2 sys.std.Core.Relation.symmetric_diff

C<< function symmetric_diff (Relation <-- topic : bag_of.Relation) {...} >>

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

=head2 sys.std.Core.Relation.intersection

C<< function 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 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_same>.  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 C<minus> or C<except> or C<∖>.

=head2 sys.std.Core.Relation.semidiff

C<< function 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 C<antijoin> or I<anti-semijoin>
or C<semiminus> or C<!matching> or C<not-matching> or C<⊿>.

=head2 sys.std.Core.Relation.antijoin

C<< function 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 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 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 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_same>.  Note that this operation is also
known as I<natural inner join> or C<⋈>.

=head2 sys.std.Core.Relation.product

C<< function 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 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<÷>.

=head2 sys.std.Core.Relation.composition

C<< function composition (Relation <--
topic : Relation, other : Relation) {...} >>

This symmetric function results in the relational composition of its
2 arguments.  It 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 only one of the
arguments has; that is, the result has all of and just the attributes that
were not involved in matching the tuples of the 2 arguments.  This
function will fail|warn any time that C<join> would fail|warn on the same 2
input relations.

=head2 sys.std.Core.Relation.join_with_group

C<< function join_with_group (Relation <--
primary : Relation, secondary : Relation, group_attr : Name) {...} >>

This function is a short-hand for first taking a (natural inner) C<join> of
its C<primary> and C<secondary> arguments, and then taking a C<group> on
all of the attributes that only the C<secondary> argument had, such that
the attribute resulting from the group has the name C<group_attr>.  The
result has 1 tuple for every tuple of C<primary> where at least 1
matching tuple exists in C<secondary>.  This function will fail if
C<group_attr> is the same name as any source attribute that wasn't grouped.
This function is a convenient tool for gathering both parent and child
records from a database using a single query while avoiding duplication of
the parent record values.

=head1 FUNCTIONS FOR RELATIONAL RANKING AND QUOTAS

These additional functions are specific to supporting ranking and quotas.

=head2 sys.std.Core.Relation.rank

C<< function rank (Relation <-- topic : Relation,
name : Name, ord_func : OrdDetCFuncNC, is_reverse_order? : Bool,
first_rank? : NNInt) {...} >>

This function results in the relational extension of its C<topic> argument
by a single C<NNInt>-typed attribute whose name is provided by the C<name>
argument, where the value of the new attribute for each tuple is the rank
of that tuple as determined by the (total) C<order-determination>
function named in the C<ord_func> argument when the latter function is
curried by the C<is_reverse_order> argument.  The C<order-determination>
function compares tuples, with each invocation of it getting a C<topic>
tuple as each its C<topic> and C<other> arguments.  The new attribute of
C<rank>'s result has the value of the C<first_rank> argument (that defaults
to zero if not explicitly given) for its ranked-first tuple, and each
further consecutive ranked tuple has the next larger integer value.  Note
that C<rank> provides the functionality of SQL's "RANK" feature but that
the result of C<rank> is always a total ordering (as per a (total)
C<order-determination> function) and so there is no "dense" / "not dense"
distinction (however a partial ordering can be implemented over it).  See
also the C<sys.std.Core.Array.Array_from_wrap> function, which is the same
as C<sys.std.Core.Relation.rank> but that it wraps the source tuples rather
than just adding an attribute to them.  The main purpose of the
C<first_rank> parameter is to support C<rank> being used as a sequence
generator to attach non-descriptive id attributes to a set of tuples that
are about to be added to a database, where we want to start the sequence
larger than the largest id value already in use there; granted, for that
purpose the new ids don't have to be ordered, just distinct, but ordering
is necessary for this setwise operation to remain deterministic.

=head2 sys.std.Core.Relation.rank_by_attr_names

C<< function rank_by_attr_names (Relation <--
topic : Relation, name : Name, order_by : array_of.OrderByName,
is_reverse_order? : Bool, first_rank? : NNInt) {...} >>

This function is a short-hand for invoking C<rank> with the function
C<sys.std.Core.Tuple.order_by_attr_names> as its C<ord_func> argument after
the latter is curried with this function's C<order_by> argument.

=head2 sys.std.Core.Relation.limit

C<< function limit (Relation <-- topic : Relation,
ord_func : OrdDetCFuncNC, is_reverse_order? : Bool,
rank_interval : sp_interval_of.NNInt) {...} >>

This function results in the relational restriction of its C<topic>
argument as determined by first ranking its tuples as per the C<rank>
function (using C<ord_func> and C<is_reverse_order>) and then keeping just
those tuples whose rank is included within the interval specified by the
C<rank_interval> argument (C<rank>'s extra attribute is not kept).  The
C<limit> function implements a certain kind of quota query where all the
result tuples are consecutive in their ranks.  It is valid for the lowest
and highest rank specified by C<rank_interval> to be greater than the
maximum rank of the source tuples; in the first case, the result has zero
tuples; in the second case, the result has all remaining tuples starting at
the lowest rank, if any.  Note that C<limit> provides the functionality of
SQL's "LIMIT/OFFSET" feature in combination with "ORDER BY" but that the
result tuples of C<limit> do not remain ordered (but see
C<sys.std.Core.Array.limit_of_Array_from_wrap> for an alternative).

=head2 sys.std.Core.Relation.limit_by_attr_names

C<< function limit_by_attr_names (Relation <--
topic : Relation, order_by : array_of.OrderByName,
is_reverse_order? : Bool, rank_interval : sp_interval_of.NNInt) {...} >>

This function is to C<limit> what C<rank_by_attr_names> is to C<rank>.

=head1 FUNCTIONS FOR RELATIONAL ATTRIBUTE VALUE SUBSTITUTIONS

These additional functions are specific to supporting substitutions.

=head2 sys.std.Core.Relation.substitution

C<< function substitution (Relation <--
topic : Relation, attr_names : set_of.Name, func : ValMapCFuncNC) {...} >>

This function is similar to C<extension> except that it substitutes values
of existing relation attributes rather than adding new attributes.  The
result relation has the same heading as C<topic>.  The result tuple of
the C<value-map> function named in C<func> must have a heading that is a
subset of the
heading of C<topic>; corresponding values resulting from the function named
in C<func> will replace the values of the tuples of C<topic>.  The result
relation has a cardinality that is the same as that of C<topic>, unless
the result of any substitutions was redundant tuples, in which case the
result has appropriately fewer tuples.  As a trivial case, if C<func> is
defined to unconditionally result in either the degree-zero tuple or in the
same tuple as its own C<topic> argument, then this function results
simply in C<topic>; or, if C<func> is defined to have a static result and
it replaces all attributes, then this function's result will have just 0..1
tuples.  Now, strictly speaking, C<substitution> could conceivably be
implemented such that each result from C<func> is allowed to specify
replacement values for different subsets of C<topic> attributes; however,
to improve the function's predictability and ease of implementation over
disparate foundations, C<substitution> requires the extra C<attr_names>
argument so that users can specify a consistent subset that C<func> will
update (possibly to itself).  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_subst

C<< function static_subst (Relation <--
topic : Relation, attrs : Tuple) {...} >>

This function is a simpler-syntax alternative to
C<sys.std.Core.Relation.substitution> in the typical scenario where every
tuple of a relation, given in the C<topic> argument, is updated with
identical values for the same attributes; the new attribute values are
given in the C<attrs> argument.

=head2 sys.std.Core.Relation.subst_in_restr

C<< function subst_in_restr (Relation <--
topic : Relation, restr_func : ValFiltCFuncNC,
subst_attr_names : set_of.Name, subst_func : ValMapCFuncNC) {...} >>

This function is like C<substitution> except that it only transforms a
subset of the tuples of C<topic> rather than all of them.  It is a
short-hand for first separating the tuples of C<topic> into 2 groups
where those passed by a relational restriction (defined by C<restr_func>)
are then transformed (defined by
C<subst_attr_names> and C<subst_func>), then the result
of the substitution is unioned with the un-transformed group.  See also the
C<subst_in_semijoin> function, which is a simpler-syntax alternative for
C<subst_in_restr> in its typical usage where restrictions are composed
simply of anded or ored tests for attribute value equality.

=head2 sys.std.Core.Relation.static_subst_in_restr

C<< function static_subst_in_restr (Relation <--
topic : Relation, restr_func : ValFiltCFuncNC, subst : Tuple) {...} >>

This function is to C<sys.std.Core.Relation.subst_in_restr> what
C<sys.std.Core.Relation.static_subst> is to
C<sys.std.Core.Relation.substitution>.  See also the
C<static_subst_in_semijoin> function.

=head2 sys.std.Core.Relation.subst_in_semijoin

C<< function subst_in_semijoin (Relation <--
topic : Relation, restr : Relation, subst_attr_names : set_of.Name,
subst_func : ValMapCFuncNC) {...} >>

This function is like C<subst_in_restr> except that the subset of the
tuples of C<topic> to be transformed is determined by those matched by a
semijoin with C<restr> rather than those that pass a generic relational
restriction.

=head2 sys.std.Core.Relation.static_subst_in_semijoin

C<< function static_subst_in_semijoin (Relation <--
topic : Relation, restr : Relation, subst : Tuple) {...} >>

This function is to C<sys.std.Core.Relation.subst_in_semijoin> what
C<sys.std.Core.Relation.static_subst> is to
C<sys.std.Core.Relation.substitution>.

=head1 FUNCTIONS FOR RELATIONAL OUTER-JOINS

These additional functions are specific to supporting outer-joins.

=head2 sys.std.Core.Relation.outer_join_with_group

C<< function outer_join_with_group (Relation <--
primary : Relation, secondary : Relation, group_attr : Name) {...} >>

This function is the same as C<sys.std.Core.Relation.join_with_group>
except that it results in a half-outer natural join rather than an inner
natural join; every tuple of C<primary> has exactly 1 corresponding tuple
in the result, but where there were no matching C<secondary> tuples, the
result attribute named by C<group_attr> contains zero tuples rather than
1+.

=head2 sys.std.Core.Relation.outer_join_with_maybes

C<< function outer_join_with_maybes (Relation <--
primary : Relation, secondary : Relation) {...} >>

This function results in a plain half-outer natural join of its C<primary>
and C<secondary> arguments where all the result attributes that come from
just C<secondary> are C<Maybe>-typed; for result tuples from matched
source tuples, each C<secondary> attribute value is a C<Just>; for
result tuples from non-matched C<primary> tuples, each C<secondary>
attribute value is C<Nothing>.  The C<outer_join_with_maybes> function is
Muldis D's answer to the SQL LEFT OUTER JOIN where SQL NULL is implicitly
used in result rows that were a non-match.

=head2 sys.std.Core.Relation.outer_join_with_defaults

C<< function outer_join_with_defaults (Relation <--
primary : Relation, secondary : Relation, filler : APTypeNC) {...} >>

This function is the same as
C<sys.std.Core.Relation.outer_join_with_static_exten> but that the filler
tuple is the default value of the tuple data type whose name is given
in the C<filler> argument.  This function is a short-hand for invoking
C<outer_join_with_static_exten> with the result from invoking
C<sys.std.Core.Universal.default>.

=head2 sys.std.Core.Relation.outer_join_with_static_exten

C<< function outer_join_with_static_exten (Relation <-- primary : Relation,
secondary : Relation, filler : Tuple) {...} >>

This function is the same as
C<sys.std.Core.Relation.outer_join_with_maybes>
but that C<secondary>-sourced result attributes are not converted to
C<Maybe>; rather, for result tuples from non-matches, the missing values
are provided explicitly from the C<filler> argument, which is a tuple
whose heading matches the projection of C<secondary>'s attributes that
aren't in common with C<primary>, and whose body is the specific values to
use for those missing attribute values.

=head2 sys.std.Core.Relation.outer_join_with_exten

C<< function outer_join_with_exten (Relation <-- primary : Relation,
secondary : Relation, exten_func : ValMapCFuncNC) {...} >>

This function is the same as
C<sys.std.Core.Relation.outer_join_with_static_exten> but that the result
tuples from non-matches are the result of performing a relational
extension on the un-matched C<primary> tuples such that each said result
tuple is determined by applying the function named in C<exten_func> to
each said C<primary> tuple.

=head1 UPDATERS IMPLEMENTING VIRTUAL ATTRIBUTIVE UPDATERS

=head1 Updaters That Rename Attributes

=head2 sys.std.Core.Relation.assign_rename

C<updater assign_rename (&topic : Relation, map : AttrRenameMap)
implements sys.std.Core.Attributive.assign_rename {...}>

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
analogous 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_static_exten

C<updater assign_static_exten (&topic : Relation, attrs : Tuple)
implements sys.std.Core.Attributive.assign_static_exten {...}>

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 analogous 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 assign_projection (&topic : Relation, attr_names : set_of.Name)
implements sys.std.Core.Attributive.assign_projection {...}>

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 assign_cmpl_proj (&topic : Relation, attr_names : set_of.Name)
implements sys.std.Core.Attributive.assign_cmpl_proj {...}>

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 analogous to the data-manipulation phase of a SQL ALTER TABLE|VIEW DROP
COLUMN statement; each attribute named by C<attr_names> corresponds to a
dropped SQL table column.

=head1 GENERIC UPDATERS FOR RELATION VARIABLES

=head1 More Updaters That Add Attributes

=head2 sys.std.Core.Relation.assign_extension

C<updater assign_extension (&topic : Relation,
attr_names : set_of.Name, func : ValMapCFuncNC) {...}>

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

=head1 Updaters That Add Tuples

=head2 sys.std.Core.Relation.assign_insertion

C<updater 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
analogous to the general case of the single-row SQL "INSERT" statement.

=head2 sys.std.Core.Relation.assign_disjoint_ins

C<updater 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 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>.  Note that this operation is
also known as C<:=union> or C<:=∪>.  This updater is analogous to the
general case of the multiple-row SQL "INSERT" statement.

=head2 sys.std.Core.Relation.assign_disjoint_union

C<updater 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_empty

C<updater assign_empty (&topic : Relation) {...}>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Relation.empty> function with the same argument, and then
assigning the result of that function to C<topic>.  This updater is
analogous to the SQL "TRUNCATE" statement.

=head2 sys.std.Core.Relation.assign_deletion

C<updater 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 assign_restriction (&topic : Relation,
func : ValFiltCFuncNC) {...}>

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>.  Note that
this operation is also known as C<:=where>.

=head2 sys.std.Core.Relation.assign_cmpl_restr

C<updater assign_cmpl_restr
(&topic : Relation, func : ValFiltCFuncNC) {...}>

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>.  Note that this
operation is also known as C<:=!where> or C<:=not-where>.  This updater is
analogous to the general case of the SQL "DELETE" statement.

=head2 sys.std.Core.Relation.assign_intersection

C<updater 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>.  Note that this operation is
also known as C<:=intersect> or C<:=∩>.

=head2 sys.std.Core.Relation.assign_diff

C<updater 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>.  Note that this
operation is also known as C<:=minus> or C<:=except> or C<:=∖>.

=head2 sys.std.Core.Relation.assign_semidiff

C<updater 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>.  Note that
this operation is also known as C<:=antijoin> or C<:=semiminus> or
C<:=!matching> or C<:=not-matching> or C<:=⊿>.  This updater
is analogous 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 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 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>.  Note that this
operation is also known as C<:=semijoin> or C<:=matching> or C<:=⋉>.

=head1 Updaters That Add and Remove Tuples

=head2 sys.std.Core.Relation.assign_exclusion

C<updater assign_exclusion (&topic : Relation, other : Relation) {...}>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Relation.exclusion> function such that it has 2 input
relations from C<assign_exclusion>'s 2 arguments, and then assigning the
result of that function to C<topic>.  Note that this operation is
also known as C<:=exclude> or C<:=symdiff> or C<:=∆>.

=head1 Updaters That Substitute Tuple Attribute Values

=head2 sys.std.Core.Relation.assign_substitution

C<updater assign_substitution (&topic : Relation,
attr_names : set_of.Name, func : ValMapCFuncNC) {...}>

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

=head2 sys.std.Core.Relation.assign_static_subst

C<updater assign_static_subst (&topic : Relation, attrs : Tuple) {...}>

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

=head2 sys.std.Core.Relation.assign_subst_in_restr

C<updater assign_subst_in_restr (&topic : Relation,
restr_func : ValFiltCFuncNC, subst_attr_names : set_of.Name,
subst_func : ValMapCFuncNC) {...}>

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

=head2 sys.std.Core.Relation.assign_static_subst_in_restr

C<updater assign_static_subst_in_restr
(&topic : Relation, restr_func : ValFiltCFuncNC, subst : Tuple) {...}>

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

=head2 sys.std.Core.Relation.assign_subst_in_semijoin

C<updater assign_subst_in_semijoin (&topic : Relation, restr : Relation,
subst_attr_names : set_of.Name, subst_func : ValMapCFuncNC) {...}>

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

=head2 sys.std.Core.Relation.assign_static_subst_in_semijoin

C<updater assign_static_subst_in_semijoin
(&topic : Relation, restr : Relation, subst : Tuple) {...}>

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

=head1 SEE ALSO

Go to L<Muldis::D> for the majority of distribution-internal
references, and L<Muldis::D::SeeAlso> for the majority of
distribution-external references.

=head1 AUTHOR

Darren Duncan (C<darren@DarrenDuncan.net>)

=head1 LICENSE AND COPYRIGHT

This file is part of the formal specification of the Muldis D language.

Muldis D is Copyright © 2002-2011, Muldis Data Systems, Inc.

See the LICENSE AND COPYRIGHT of L<Muldis::D> for details.

=head1 TRADEMARK POLICY

The TRADEMARK POLICY in L<Muldis::D> applies to this file too.

=head1 ACKNOWLEDGEMENTS

The ACKNOWLEDGEMENTS in L<Muldis::D> apply to this file too.

=cut