=pod

=encoding utf8

=head1 NAME

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

=head1 VERSION

This document is Muldis::D::Ext::QArray version 0.60.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<QArray> document describes the system-defined I<Muldis D
QArray Extension>, which consists of generic operators that are specific
to the C<QArray> parameterized q/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 QUASI-/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.QArray.value

C<function sys.std.QArray.value result Universal params {
topic(QArray), index(NNInt) }>

This function results in the q/scalar or q/nonscalar C<value> attribute of
the q/tuple of C<topic> whose C<index> attribute is C<index>.  This
function will fail if no q/tuple exists in C<topic> with the specified
index.

=head2 sys.std.QArray.update_value

C<function sys.std.QArray.update_value result QArray params {
topic(QArray), index(NNInt), value(Universal) }>

This function results in its C<topic> argument but that the C<value>
attribute of the q/tuple of C<topic> whose C<index> attribute is C<index>
has been updated with a new q/scalar or q/nonscalar value given by
C<value>.  This function will fail if no q/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.QArray.insertion

C<function sys.std.QArray.insertion result QArray params {
topic(QArray), index(NNInt), value(Universal) }>

This function results in its C<topic> argument but that a new q/tuple has
been inserted whose C<index> is C<index> and whose C<value> is C<value>;
any existing q/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.QArray.deletion

C<function sys.std.QArray.deletion result QArray params {
topic(QArray), index(NNInt) }>

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

=head2 sys.std.QArray.is_element

C<function sys.std.QArray.is_element result Bool params {
topic(QArray), value(Universal) }>

This function results in C<Bool:true> iff its C<value> argument matches the
C<value> attribute of at least one q/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.QArray.is_not_element

C<function sys.std.QArray.is_not_element result Bool params {
topic(QArray), value(Universal) }>

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

=head2 sys.std.QArray.reduction

C<function sys.std.QArray.reduction result Universal params {
topic(QArray), func(FuncRef), assuming(QTuple)?, identity(Universal) }>

This function is the same as C<sys.std.QSet.reduction>, including that
input values for the reduction come from the C<value> attribute of
C<topic>, except that it works with an C<QArray> rather than a C<QSet>.
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.

=head2 sys.std.QArray.maybe_reduction

C<function sys.std.QArray.maybe_reduction result QMaybe params {
topic(QArray), func(FuncRef), assuming(QTuple)? }>

This function is to C<sys.std.QSet.maybe_reduction> as
C<sys.std.QArray.reduction> is to C<sys.std.QSet.reduction>.

=head2 sys.std.QArray.slice

C<function sys.std.QArray.slice result QArray params { topic(QArray),
first_index(NNInt), last_index(NNInt) }>

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

C<function sys.std.QArray.catenation result QArray params {
topic(quasi_array_of.QArray) }>

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<QArray> means to union their q/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.

=head2 sys.std.QArray.repeat

C<function sys.std.QArray.repeat result QArray params {
topic(QArray), count(NNInt) }>

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

=head2 sys.std.QArray.reverse

C<function sys.std.QArray.reverse result QArray params { topic(QArray) }>

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

C<function sys.std.QArray.is_subarray result Bool params {
look_in(QArray), look_for(QArray) }>

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

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

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

=head2 sys.std.QArray.QArray_from_wrap

C<function sys.std.QArray.QArray_from_wrap result quasi_array_of.QTuple
params { topic(QRelation), ord_func(FuncRef), ord_assuming(QTuple)? }>

This function results in an C<QArray> whose C<value> attribute is
q/tuple-typed and that attribute's values are all the q/tuples of C<topic>;
is a short-hand for a relational wrap of all attributes of C<topic> such
that the new q/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 q/tuples, where the ranked-first q/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 q/tuples, with each invocation getting a
C<topic> q/tuple as each its C<topic> and C<other> arguments.  See also the
C<sys.std.QRelation.rank> function, which is the same as
C<sys.std.QArray.QArray_from_wrap> but that it just adds an attribute to
the source q/tuples and does not wrap them.

=head2 sys.std.QArray.limit_of_QArray_from_wrap

C<function sys.std.QArray.limit_of_QArray_from_wrap result
quasi_array_of.QTuple params { topic(QRelation), ord_func(FuncRef),
ord_assuming(QTuple)?, first_index(NNInt), last_index(NNInt) }>

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

=head2 sys.std.QArray.QArray_from_attr

C<function sys.std.QArray.QArray_from_attr result QArray params {
topic(QRelation), name(Name), ord_func(OrdDetFuncRef)?,
ord_assuming(QTuple)? }>

This function results in an C<QArray> 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.QArray.QArray_from_wrap>.  Each of the C<ord_func> and
C<ord_assuming> parameters is optional and defaults to
C<sys.std.Core.QScalar.order> or the zero-attribute tuple, 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
