=pod

=encoding utf8

=head1 NAME

Muldis::D::Ext::Ordered -
Muldis D extension for generic ordered-sensitive operators

=head1 VERSION

This document is Muldis::D::Ext::Ordered version 0.96.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<Ordered> document describes the system-defined I<Muldis D
Ordered Extension>, which consists of generic operators that are sensitive
to an ordering of a type's values, and are used for such things as list
sorting or quota queries or determining before/after/min/max/between/etc.
They can potentially be used with values of any data type as long as said
data type has a (total) C<order-determination> function defined for it,
and all system-defined conceptually-ordered Muldis D scalar root types do.

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 ORDER-CONCERNING FUNCTIONS

Each of these functions which has the parameter named C<func> is a wrapper
over the C<order-determination> function named in its C<func> argument when
the latter function is curried by a calling-function-specific
C<is_reverse_order> argument value.  For any scalar root type's
type-default order function, the argument for C<func> is
C<sys.std.Core.Scalar.order>.  Each C<func> parameter is optional and
defaults to C<sys.std.Core.Scalar.order> if no explicit argument is given
to it.

These functions' C<Interval>-typed arguments' C<min> and C<max> attribute
values must be of compatible declared types with the wrapped functions'
C<topic> and C<other> parameters; otherwise these functions will fail|warn
when the wrapped function would.  Likewise, any other argument values would
be compared to an interval's endpoints must be compatible with them.

=head2 sys.std.Ordered.is_before

C<< function sys.std.Ordered.is_before (Bool <-- $topic : Universal,
$other : Universal, $func? : OrdDetFuncRef) >>

This function results in C<Bool:true> iff the wrapped function would result
in C<Order:increase> when given the same corresponding 2 arguments plus a
C<is_reverse_order> argument of C<Bool:false>, and C<Bool:false> otherwise.
Note that this operation is also known as I<less than> or C<< < >>.

=head2 sys.std.Ordered.is_after

C<< function sys.std.Ordered.is_after (Bool <-- $topic : Universal,
$other : Universal, $func? : OrdDetFuncRef) >>

This function is an alias for C<sys.std.Ordered.is_before> except that it
transposes the C<topic> and C<other> arguments.  This function results in
C<Bool:true> iff the wrapped function would result in C<Order:decrease>
when given the same corresponding 2 arguments plus a C<is_reverse_order>
argument of C<Bool:false>, and C<Bool:false> otherwise.  Note that this
operation is also known as I<greater than> or C<< > >>.

=head2 sys.std.Ordered.is_before_or_same

C<< function sys.std.Ordered.is_before_or_same (Bool <--
$topic : Universal, $other : Universal, $func? : OrdDetFuncRef) >>

This function is exactly the same as C<sys.std.Ordered.is_before> except
that it results in C<Bool:true> if its 2 primary arguments are identical.
Note that this operation is also known as I<less than or equal to> or C<≤>.

=head2 sys.std.Ordered.is_after_or_same

C<< function sys.std.Ordered.is_after_or_same (Bool <-- $topic : Universal,
$other : Universal, $func? : OrdDetFuncRef) >>

This function is an alias for C<sys.std.Ordered.is_before_or_same> except
that it transposes the C<topic> and C<other> arguments.  This function is
exactly the same as C<sys.std.Ordered.is_after> except that it results in
C<Bool:true> if its 2 primary arguments are identical.  Note that this
operation is also known as I<greater than or equal to> or C<≥>.

=head2 sys.std.Ordered.is_member

C<< function sys.std.Ordered.is_member (Bool <-- $value : Universal,
$interval : Interval, $func? : OrdDetFuncRef) >>

This function is an alias for C<sys.std.Interval.has_member>.  This
function results in C<Bool:true> iff its C<value> argument is included
within the interval defined by its C<interval> argument, and C<Bool:false>
otherwise.  That is, if conceptually the interval represents a set of
values, this function tests if C<value> is a member of C<interval>.  Note
that this operation is also known as C<I∈> or I<between>, and depending on
the combination of C<excludes_[min|max]> attributes of its C<interval>
argument, it is alternately also known as one of [C<≤≤>, C<< ≤< >>, C<< <≤
>>, C<< << >>].

=head2 sys.std.Ordered.is_not_member

C<< function sys.std.Ordered.is_not_member (Bool <-- $value : Universal,
$interval : Interval, $func? : OrdDetFuncRef) >>

This function is an alias for C<sys.std.Interval.has_not_member>.  This
function is exactly the same as C<sys.std.Ordered.is_member> except that it
results in the opposite boolean value when given the same arguments.  Note
that this operation is also known as C<I∉> or I<not between>, and depending
on the combination of C<excludes_[min|max]> attributes of its C<interval>
argument, it is alternately also known as one of [C<!≤≤>, C<< !≤< >>, C<<
!<≤ >>, C<< !<< >>].

=head2 sys.std.Ordered.min

C<< function sys.std.Ordered.min (Universal <-- $topic : Set,
$func? : OrdDetFuncRef) >>

This function is a reduction operator that recursively takes each pair of
its N input element values and picks the minimum of the 2 (which is
commutative, associative, and idempotent) until just one is left, which is
the function's result.  If C<topic> has zero values, then this function
will fail.  Note that, conceptually C<min> I<does> have an identity value
which could be this function's result when C<topic> has zero values, which
is the result type's concept of positive infinity; however, in practice
there is little benefit to C<min> supporting this identity value, since the
wrapped C<order-determination> function can't supply the value, and also
many types' concept of positive infinity is impossible or impractically
large to represent, such as with the infinite C<Text> type.

=head2 sys.std.Ordered.max

C<< function sys.std.Ordered.max (Universal <-- $topic : Set,
$func? : OrdDetFuncRef) >>

This function is exactly the same as C<sys.std.Ordered.min> except that it
results in the maximum input element value rather than the minimum one.
(Note that, conceptually C<max> has an identity value which is the result
type's concept of negative infinity, but it is unsupported here).

=head2 sys.std.Ordered.minmax

C<< function sys.std.Ordered.minmax (Tuple <-- $topic : Set,
$func? : OrdDetFuncRef) >>

This function results in a binary tuple whose attribute names are C<min>
and C<max> and whose respective attribute values are what
C<sys.std.Ordered.min> and C<sys.std.Ordered.max> would result in when
given the same arguments.  If C<topic> has zero values, then this function
will fail.

=head2 sys.std.Ordered.maybe_min

C<< function sys.std.Ordered.maybe_min (Maybe <-- $topic : Set,
$func? : OrdDetFuncRef) >>

This function is exactly the same as C<sys.std.Ordered.min> except that it
results in a C<Maybe> of what is otherwise the result type, and that
result has zero elements if the argument has zero elements, rather than the
function failing.

=head2 sys.std.Ordered.maybe_max

C<< function sys.std.Ordered.maybe_max (Maybe <-- $topic : Set,
$func? : OrdDetFuncRef) >>

This function is to C<sys.std.Ordered.max> as C<sys.std.Ordered.maybe_min>
is to C<sys.std.Ordered.min>.

=head2 sys.std.Ordered.maybe_minmax

C<< function sys.std.Ordered.maybe_minmax (Relation <-- $topic : Set,
$func? : OrdDetFuncRef) >>

This function results in a binary relation whose attribute names are C<min>
and C<max>.  If C<topic> has zero values then the result has a single tuple
whose respective attribute values are what C<sys.std.Ordered.min> and
C<sys.std.Ordered.max> would result in when given the same arguments; if
C<topic> has zero values, then the result has zero tuples.

=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
