=pod

=encoding utf8

=head1 NAME

Muldis::D::Ext::Sequence -
Muldis D extension for Seq specific operators

=head1 VERSION

This document is Muldis::D::Ext::Sequence version 0.23.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<Sequence> document describes the system-defined I<Muldis D
Sequence Extension>, which consists of generic operators that are specific
to the C<Seq> 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.Sequence.value result ScaTupRel params {
topic(Seq), 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.Sequence.update_value result Seq params {
topic(Seq), 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.Sequence.insertion result Seq params { topic(Seq),
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.Sequence.deletion result Seq params { topic(Seq),
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.Sequence.is_element result Bool params {
topic(Seq), 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.Sequence.is_not_element result Bool params {
topic(Seq), value(ScaTupRel) }>

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

=item C<function sys.std.Sequence.reduction result ScaTupRel params {
topic(Seq), 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 a C<Seq> 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.Sequence.maybe_reduction result Maybe params {
topic(Seq), func(Cat.NameChain), assuming(Tuple) }>

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

=item C<function sys.std.Sequence.catenation result Seq params {
topic(seq_of.Seq) }>

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<Seq>
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.Sequence.repeat result Seq params { topic(Seq),
count(UInt) }>

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

=item C<function sys.std.Sequence.reverse result Seq params { topic(Seq) }>

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.Sequence.is_subseq result Bool params {
look_in(Seq), look_for(Seq) }>

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.Sequence.is_not_subseq result Bool params {
look_in(Seq), look_for(Seq) }>

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

=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