=pod

=encoding utf8

=head1 NAME

Muldis::D::Ext::Array -
Muldis D extension for Array specific operators

=head1 VERSION

This document is Muldis::D::Ext::Array version 0.79.1.

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

=head1 DESCRIPTION

Muldis D has a mandatory core set of system-defined (eternally available)
entities, which is referred to as the I<Muldis D core> or the I<core>; they
are the minimal entities that all Muldis D implementations need to provide;
they are mutually self-describing and are used to bootstrap the language;
any entities outside the core, called I<Muldis D extensions>, are
non-mandatory and are defined in terms of the core or each other, but the
reverse isn't true.

This current C<Array> document describes the system-defined I<Muldis D
Array Extension>, which consists of generic operators that are specific
to the C<Array> parameterized relation type, and said operators are
short-hands for generic relational operators in the language core.

This current document does not describe the polymorphic operators that all
types, or some types including core types, have defined over them; said
operators are defined once for all types in L<Muldis::D::Core>.

I<This documentation is pending.>

=head1 SYSTEM-DEFINED ARRAY-CONCERNING FUNCTIONS

Each C<\w*assuming> parameter is optional and defaults to the
zero-attribute tuple if no explicit argument is given to it.

=head2 sys.std.Array.value

C<< function sys.std.Array.value (Universal <-- Array $topic,
NNInt $index) >>

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.

=head2 sys.std.Array.update_value

C<< function sys.std.Array.update_value (Array <-- Array $topic,
NNInt $index, Universal $value) >>

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_identical>, 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.Array.insertion

C<< function sys.std.Array.insertion (Array <-- Array $topic,
NNInt $index, Universal $value) >>

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

C<< function sys.std.Array.deletion (Array <-- Array $topic,
NNInt $index) >>

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

C<< function sys.std.Array.has_elem (Bool <-- Array $topic,
Universal $value) >>

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<topic> argument (that
is, iff conceptually C<value> is an element of C<topic>), and C<Bool:false>
otherwise.  This function will warn if C<topic.value> and C<value> are
incompatible as per C<update_value>.

=head2 sys.std.Array.has_not_elem

C<< function sys.std.Array.has_not_elem (Bool <-- Array $topic,
Universal $value) >>

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

=head2 sys.std.Array.reduction

C<< function sys.std.Array.reduction (Universal <-- Array $topic,
ValRedFuncRef $func, Tuple $assuming?, Universal $identity) >>

This function is the same as C<sys.std.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.Array.maybe_reduction

C<< function sys.std.Array.maybe_reduction (Maybe <-- Array $topic,
ValRedFuncRef $func, Tuple $assuming?) >>

This function is to C<sys.std.Set.maybe_reduction> as
C<sys.std.Array.reduction> is to C<sys.std.Set.reduction>.

=head2 sys.std.Array.slice

C<< function sys.std.Array.slice (Array <-- Array $topic,
NNInt $first_index, NNInt $last_index) >>

This function results in the sub-sequence of its C<topic> argument that is
specified by its C<first_index> and C<last_index> arguments, which specify
the inclusive source-C<index> range of the elements of the result.  This
function will fail if C<last_index> is before C<first_index>.  It is valid
for C<first_index> or C<last_index> 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 C<first_index>.  If
C<topic> has any elements and C<first_index> matches the index of a source
element, then the result will always have at least 1 element.

=head2 sys.std.Array.catenation

C<< function sys.std.Array.catenation (Array <-- array_of.Array $topic?) >>

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<catenate> results in the empty sequence
value, which is the identity value for catenate.  Note that this operation
is also known as C<A~>.

=head2 sys.std.Array.replication

C<< function sys.std.Array.replication (Array <-- Array $topic,
NNInt $count) >>

This function results in the catenation of C<count> instances of C<topic>.
Note that this operation is also known as C<Ax>.

=head2 sys.std.Array.reverse

C<< function sys.std.Array.reverse (Array <-- Array $topic) >>

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

C<< function sys.std.Array.has_subarray (Bool <-- Array $look_in,
Array $look_for) >>

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

C<< function sys.std.Array.has_not_subarray (Bool <-- Array $look_in,
Array $look_for) >>

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

=head2 sys.std.Array.Array_from_wrap

C<< function sys.std.Array.Array_from_wrap (array_of.Tuple <--
Relation $topic, OrdDetFuncRef $ord_func, Tuple $ord_assuming?,
Bool $is_reverse_order?) >>

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<ord_assuming> and C<is_reverse_order>
arguments; 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.Relation.rank> function, which is the
same as C<sys.std.Array.Array_from_wrap> but that it just adds an attribute
to the source tuples and does not wrap them.

=head2 sys.std.Array.Array_from_wrap_by_attr_names

C<< function sys.std.Array.Array_from_wrap_by_attr_names
(array_of.Tuple <-- Relation $topic,
array_of.OrderByName $order_by, Bool $is_reverse_order?) >>

This function is to C<Array_from_wrap> what
C<sys.std.Relation.rank_by_attr_names> is to C<sys.std.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.Array.limit_of_Array_from_wrap

C<< function sys.std.Array.limit_of_Array_from_wrap (array_of.Tuple <--
Relation $topic, OrdDetFuncRef $ord_func, Tuple $ord_assuming?,
Bool $is_reverse_order?, NNInt $first_index, NNInt $last_index) >>

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

=head2 sys.std.Array.limit_of_Array_from_wrap_by_attr_names

C<< function sys.std.Array.limit_of_Array_from_wrap_by_attr_names
(array_of.Tuple <-- Relation $topic, array_of.OrderByName $order_by,
Bool $is_reverse_order?, NNInt $first_index, NNInt $last_index) >>

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

C<< function sys.std.Array.Array_from_attr (Array <-- Relation $topic,
Name $name, OrdDetFuncRef $ord_func?, Tuple $ord_assuming?,
Bool $is_reverse_order?) >>

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.Array.Array_from_wrap>.  Each of the C<ord_func> and
C<ord_assuming> and C<is_reverse_order> parameters is optional and defaults
to C<sys.std.Core.Scalar.order> or the zero-attribute tuple or
C<Bool:false>, respectively, 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<perl@DarrenDuncan.net>)

=head1 LICENSE AND COPYRIGHT

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

Muldis D is Copyright © 2002-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