=pod

=encoding utf8

=head1 NAME

Muldis::D::Core::Array -
Muldis D Array specific operators

=head1 VERSION

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

=head1 PREFACE

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

=head1 DESCRIPTION

This document describes generic operators that are specific to the
C<Array> parameterized relation type, and said operators
are short-hands for more generic relational operators.

I<This documentation is pending.>

=head1 FUNCTIONS IMPLEMENTING VIRTUAL STRINGY FUNCTIONS

=head2 sys.std.Core.Array.catenation

C<< function catenation (Array <-- topic? : array_of.Array)
implements sys.std.Core.Stringy.catenation {...} >>

This function results in the catenation of the N element values of its
argument; it is a reduction operator that recursively takes each
consecutive pair of input values and catenates (which is associative) them
together until just one is left, which is the result.  To catenate 2
C<Array> means to union their tuples after first increasing all the
C<index> values of the second one by the cardinality of the first one.  If
C<topic> has zero values, then C<catenation> results in the empty sequence
value, which is the identity value for catenation.

=head2 sys.std.Core.Array.replication

C<< function replication (Array <-- topic : Array,
count : NNInt) implements sys.std.Core.Stringy.replication {...} >>

This function results in the catenation of C<count> instances of C<topic>.

=head1 FUNCTIONS IMPLEMENTING VIRTUAL COLLECTIVE FUNCTIONS

=head2 sys.std.Core.Array.has_elem

C<< function has_elem (Bool <-- coll : Array, value : Universal)
implements sys.std.Core.Collective.has_member {...} >>

This function results in C<Bool:True> iff its C<value> argument matches the
C<value> attribute of at least one tuple of its C<coll> argument (that
is, iff conceptually C<value> is an element of C<coll>), and C<Bool:False>
otherwise.  This function will warn if C<coll.value> and C<value> are
incompatible as per C<update_value>.

=head2 sys.std.Core.Array.has_not_elem

C<< function has_not_elem (Bool <-- coll : Array, value : Universal)
implements sys.std.Core.Collective.has_not_member {...} >>

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

=head2 sys.std.Core.Array.value_is_elem

C<< function value_is_elem (Bool <-- value : Universal, coll : Array)
implements sys.std.Core.Collective.value_is_member {...} >>

This function is an alias for C<sys.std.Core.Array.has_elem>.  This
function results in C<Bool:True> iff its C<value> argument matches the
C<value> attribute of at least one tuple of its C<coll> argument (that is,
iff conceptually C<value> is an element of C<coll>), and C<Bool:False>
otherwise.

=head2 sys.std.Core.Array.value_is_not_elem

C<< function value_is_not_elem (Bool <-- value : Universal, coll : Array)
implements sys.std.Core.Collective.value_is_not_member {...} >>

This function is an alias for C<sys.std.Core.Array.has_elem>.  This
function is exactly the same as C<sys.std.Core.Array.value_is_elem> except
that it results in the opposite boolean value when given the same
arguments.

=head1 GENERIC RELATIONAL FUNCTIONS FOR ARRAYS

=head2 sys.std.Core.Array.value

C<< function value (Universal <-- topic : Array, index : NNInt) {...} >>

This function results in the scalar or nonscalar C<value> attribute of the
tuple of C<topic> whose C<index> attribute is C<index>.  This function will
fail if no tuple exists in C<topic> with the specified index.  Note that
this operation is also known as C<.[]>.

=head2 sys.std.Core.Array.update_value

C<< function update_value (Array <-- topic : Array,
index : NNInt, value : Universal) {...} >>

This function results in its C<topic> argument but that the C<value>
attribute of the tuple of C<topic> whose C<index> attribute is C<index>
has been updated with a new scalar or nonscalar value given by
C<value>.  This function will fail if no tuple exists in C<topic> with
the specified index.  This function will warn if the most specific types of
the C<value> argument and the C<value> attribute of C<topic> are
incompatible as per C<is_same>, or otherwise if the declared type of
C<value> isn't a subtype of the declared type of the C<value> attribute.

=head2 sys.std.Core.Array.insertion

C<< function insertion (Array <-- topic : Array,
index : NNInt, value : Universal) {...} >>

This function results in its C<topic> argument but that a new tuple has
been inserted whose C<index> is C<index> and whose C<value> is C<value>;
any existing tuples with C<index> values greater than or equal to
C<index> had theirs incremented by 1.  As a trivial case, if C<index> is
equal to zero or is equal to the cardinality of C<topic>, then C<value> has
become the new first or last (or only) element, respectively.  This
function will fail if C<index> is greater than the cardinality of C<topic>,
or it will warn if C<topic.value> and C<value> are incompatible as per
C<update_value>.

=head2 sys.std.Core.Array.deletion

C<< function deletion (Array <-- topic : Array, index : NNInt) {...} >>

This function results in its C<topic> argument but that a tuple has been
deleted whose C<index> is C<index>; any existing tuples with C<index>
values greater than or equal to C<index> had theirs decremented by 1.  This
function will fail if no tuple exists in C<topic> with the specified index.

=head2 sys.std.Core.Array.reduction

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

This function is the same as C<sys.std.Core.Set.reduction>, including that
input values for the reduction come from the C<value> attribute of
C<topic>, except that it works with an C<Array> rather than a C<Set>.
Also, the C<value-reduction> function named in C<func> is only associative,
and I<not> commutative; the arguments to C<v1> and C<v2> of C<func> are
guaranteed to be consecutive input elements, with the result returning to
their place in sequence beween the other input elements.

=head2 sys.std.Core.Array.slice

C<< function slice (Array <-- topic : Array,
index_interval : sp_interval_of.NNInt) {...} >>

This function results in the sub-sequence of its C<topic> argument that is
specified by its C<index_interval> argument, which specifies the
source-C<index> interval of the elements of the result.  It is valid for
the lowest and highest source-C<index> specified by C<index_interval> to be
greater than the last index of C<topic>; in the first case, the result has
zero elements; in the second case, the result has all remaining elements
starting at the lowest source-C<index>, if any.  Note that this operation
is also known as C<[]>.

=head2 sys.std.Core.Array.reverse

C<< function reverse (Array <-- topic : Array) {...} >>

This function results in its argument but that the order of its elements
has been reversed.  For example, the input C<< { 0=>'a', 1=>'b', 2=>'c',
3=>'d'} >> results in C<< { 0=>'d', 1=>'c', 2=>'b', 3=>'a' } >>.

=head2 sys.std.Core.Array.has_subarray

C<< function has_subarray (Bool <-- look_in : Array,
look_for : Array) {...} >>

This function results in C<Bool:True> iff the sequence of values comprising
C<look_for> is a sub-sequence of the sequence of values C<look_in>, and
C<Bool:False> otherwise.  This function will fail|warn if the 2 arguments
don't have a compatible or same heading.

=head2 sys.std.Core.Array.has_not_subarray

C<< function has_not_subarray (Bool <--
look_in : Array, look_for : Array) {...} >>

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

=head2 sys.std.Core.Array.order

C<< function order (Order <-- topic : Array,
other : Array, elem_ord_func? : OrdDetCFuncNC,
elem_is_reverse_order? : Bool, is_reverse_order? : Bool) {...} >>

This function is a generic (total) C<order-determination> function for
C<Array> values, especially for homogeneous ones.  Iff
both of its C<topic> and C<other> arguments are identical, this function
results in C<Order:Same>.  Otherwise, iff one of those 2 arguments is a
subarray of the other where the latter is matched by its leading elements,
meaning that the former's tuples are a proper subset of the latter's, then
the shorter argument is ordered before the longer one.  Otherwise, the
order of the C<topic> and C<other> arguments is determined by the
comparison of the lowest-index distinct element values of those arguments,
as follows:  The result of this function is the result of applying to those
2 elements the (total) C<order-determination> function given in its
C<elem_ord_func> argument, as curried by its C<elem_is_reverse_order>
argument.  Iff C<topic> is ordered before C<other>, this function results
in C<Order:Increase>; otherwise, iff C<other> is ordered before C<topic>,
this function results in C<Order:Decrease>.  The C<is_reverse_order>
argument is applied to the result of this function I<after> all of the
other arguments are applied; if it is C<Bool:False>, it does not change the
result; if it is C<Bool:True>, then it reverses the result.

=head2 sys.std.Core.Array.Array_from_wrap

C<< function Array_from_wrap (array_of.Tuple <-- topic : Relation,
ord_func : OrdDetCFuncNC, is_reverse_order? : Bool) {...} >>

This function results in an C<Array> whose C<value> attribute is
tuple-typed and that attribute's values are all the tuples of C<topic>;
is a short-hand for a relational wrap of all attributes of C<topic> such
that the new tuple-valued attribute is named C<value>, and then that
result is extended with an C<index> attribute whose values result from a
rank of the tuples, where the ranked-first tuple has an C<index> of
zero, and so on.  This function is a wrapper over the (total)
C<order-determination> function named in its C<ord_func> argument when the
latter function is curried by its C<is_reverse_order>
argument; this wrapped function is used to rank the tuples, with each
invocation getting a C<topic> tuple as each its C<topic> and C<other>
arguments.  See also the C<sys.std.Core.Relation.rank> function, which is
the same as C<sys.std.Core.Array.Array_from_wrap> but that it just adds an
attribute to the source tuples and does not wrap them.

=head2 sys.std.Core.Array.Array_from_wrap_by_attr_names

C<< function Array_from_wrap_by_attr_names
(array_of.Tuple <-- topic : Relation,
order_by : array_of.OrderByName, is_reverse_order? : Bool) {...} >>

This function is to C<Array_from_wrap> what
C<sys.std.Core.Relation.rank_by_attr_names> is to
C<sys.std.Core.Relation.rank>.
Note that this function is the most direct analogy to the common case of
SQL's "ORDER BY" where a simple list of attribute names is given to sort on
(and the tuples remain sorted), which is in contrast with
C<Array_from_wrap> that is the analogy to the general case of "ORDER BY"
that may contain any arbitrary value expression.

=head2 sys.std.Core.Array.limit_of_Array_from_wrap

C<< function limit_of_Array_from_wrap
(array_of.Tuple <-- topic : Relation, ord_func : OrdDetCFuncNC,
is_reverse_order? : Bool, index_interval : sp_interval_of.NNInt) {...} >>

This function is a short-hand for invoking first
C<sys.std.Core.Array.Array_from_wrap> and then C<sys.std.Core.Array.slice>
on its result.  This function is to C<sys.std.Core.Array.Array_from_wrap>
what the C<sys.std.Core.Relation.limit> function is to
C<sys.std.Core.Relation.rank>.

=head2 sys.std.Core.Array.limit_of_Array_from_wrap_by_attr_names

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

This function is to C<limit_of_Array_from_wrap> what
C<Array_from_wrap_by_attr_names> is to C<Array_from_wrap>.

=head2 sys.std.Core.Array.Array_from_attr

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

This function results in an C<Array> consisting of all the values of the
attribute of C<topic> named by C<name>.  It is a short-hand for a unary
projection of just the named attribute plus its renaming to C<value>, and
then that result is extended with an C<index> attribute whose values result
from a rank of the source attribute values, where the ranked-first source
value has an C<index> of zero, and so on.  This function is otherwise the
same as C<sys.std.Core.Array.Array_from_wrap>.  Each of the C<ord_func> and
C<is_reverse_order> parameters is optional and defaults
to C<sys.std.Core.Ordered.order> or
C<Bool:False>, respectively, if no explicit argument is given to it.

=head2 sys.std.Core.Array.Array_from_Set

C<< function Array_from_Set (Array <-- topic : Set,
ord_func? : OrdDetCFuncNC, is_reverse_order? : Bool) {...} >>

This function results in an C<Array> consisting of all the values of
C<topic>.  It is a short-hand for a C<sys.std.Core.Array.Array_from_attr>
invocation with a C<name> argument of C<value>, and C<topic> is a C<Set>.

=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