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

=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 SEQUENCE-CONCERNING FUNCTIONS

=over

=item C<function sys.std.Array.value result ScaTupRel params {
topic(Array), index(UInt) }>

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.

=item C<function sys.std.Array.update_value result Array params {
topic(Array), index(UInt), value(ScaTupRel) }>

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,
or if the declared type of C<value> isn't a subtype of the declared type of
the C<value> attribute.

=item C<function sys.std.Array.insertion result Array params {
topic(Array), index(UInt), value(ScaTupRel) }>

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 if the
declared type of C<value> isn't a subtype of the declared type of the
C<value> attribute.

=item C<function sys.std.Array.deletion result Array params { topic(Array),
index(UInt) }>

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.

=item C<function sys.std.Array.is_element result Bool params {
topic(Array), value(ScaTupRel) }>

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 fail if the declared type of C<value> isn't
a subtype of the declared type of that attribute.

=item C<function sys.std.Array.is_not_element result Bool params {
topic(Array), value(ScaTupRel) }>

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

=item C<function sys.std.Array.reduction result ScaTupRel params {
topic(Array), func(Cat.NameChain), assuming(Tuple), identity(ScaTupRel) }>

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

=item C<function sys.std.Array.maybe_reduction result Maybe params {
topic(Array), func(Cat.NameChain), assuming(Tuple) }>

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

=item C<function sys.std.Array.slice result Array params {
topic(Array), first_index(UInt), last_index(UInt) }>

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.

=item C<function sys.std.Array.catenation result Array params {
topic(array_of.Array) }>

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.

=item C<function sys.std.Array.repeat result Array params { topic(Array),
count(UInt) }>

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

=item C<function sys.std.Array.reverse result Array params { 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' } >>.

=item C<function sys.std.Array.is_subarray result Bool params {
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 if the 2 arguments don't
have the same heading.

=item C<function sys.std.Array.is_not_subarray result Bool params {
look_in(Array), look_for(Array) }>

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

=item C<function sys.std.Array.Array_from_wrap result array_of.Tuple params
{ topic(Relation), ord_func(Cat.NameChain), ord_assuming(Tuple) }>

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

=item C<function sys.std.Array.limit_of_Array_from_wrap result
array_of.Tuple params { topic(Relation), func(Cat.NameChain),
assuming(Tuple), first_index(UInt), last_index(UInt) }>

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

=item C<function sys.std.Array.Array_from_attr result Array params {
topic(Relation), name(Cat.Name), ord_func(Cat.NameChain),
ord_assuming(Tuple) }>

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

=back

=head1 SEE ALSO

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

=head1 AUTHOR

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

=head1 LICENSE AND COPYRIGHT

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

Muldis D is Copyright © 2002-2008, Darren Duncan.

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

=head1 TRADEMARK POLICY

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

=head1 ACKNOWLEDGEMENTS

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

=cut
