=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.74.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<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 2 parameters named C<func> and
C<assuming> is a wrapper over the C<order_determination> function named in
its C<func> argument when the latter function is curried by its C<assuming>
argument plus a calling-function-specific C<is_reverse_order> argument
value.  For any q/scalar root type's type-default order function, the
argument for C<func> is C<sys.std.Core.QScalar.order>.  Each C<func> and
C<assuming> parameter 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.

=head2 sys.std.Ordered.is_before

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

This function results in C<Bool:true> iff the wrapped function would result
in C<Order:increase> when given the same corresponding 3 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 <-- Universal $topic,
Universal $other, OrdDetFuncRef $func?, QTuple $assuming?) >>

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 3 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 <-- Universal $topic,
Universal $other, OrdDetFuncRef $func?, QTuple $assuming?) >>

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 <-- Universal $topic,
Universal $other, OrdDetFuncRef $func?, QTuple $assuming?) >>

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_inside_range

C<< function sys.std.Ordered.is_inside_range (Bool <-- Universal $topic,
Universal $min, Universal $max, Bool $min_is_outside?,
Bool $max_is_outside?, OrdDetFuncRef $func?, QTuple $assuming?) >>

This function results in C<Bool:true> iff its C<topic> argument is within
the range whose bounds are defined by its C<min> and C<max> arguments.  If
C<min_is_outside> or C<max_is_outside> are C<Bool:true>, then C<topic> I<is
not> considered to be within the range if it is equal to C<min> or C<max>,
respectively; otherwise, C<topic> I<is> considered to be within the range
if it is equal to C<min> or C<max>.  This function's C<min> and C<max>
arguments must be of compatible declared types with C<topic> and C<order>
as per the wrapped function; otherwise this function will fail|warn when
the wrapped function would.  This function will fail if C<max> is before
C<min>.  Each of the C<m[in|ax]_is_outside> parameters is optional and
defaults to C<Bool:false> if no explicit argument is given to it. Note that
this operation is also known as I<between>.

=head2 sys.std.Ordered.is_outside_range

C<< function sys.std.Ordered.is_outside_range (Bool <-- Universal $topic,
Universal $min, Universal $max, Bool $min_is_outside?,
Bool $max_is_outside?, OrdDetFuncRef $func?, QTuple $assuming?) >>

This function is exactly the same as C<sys.std.Ordered.is_inside_range>
except that it results in the opposite boolean value when given the same
arguments.  Note that this operation is also known as I<not between>.

=head2 sys.std.Ordered.min

C<< function sys.std.Ordered.min (Universal <-- QSet $topic,
OrdDetFuncRef $func?, QTuple $assuming?) >>

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 <-- QSet $topic,
OrdDetFuncRef $func?, QTuple $assuming?) >>

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 (QTuple <-- QSet $topic,
OrdDetFuncRef $func?, QTuple $assuming?) >>

This function results in a binary q/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 (QMaybe <-- QSet $topic,
OrdDetFuncRef $func?, QTuple $assuming?) >>

This function is exactly the same as C<sys.std.Ordered.min> except that it
results in a C<QMaybe> 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 (QMaybe <-- QSet $topic,
OrdDetFuncRef $func?, QTuple $assuming?) >>

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 (QRelation <-- QSet $topic,
OrdDetFuncRef $func?, QTuple $assuming?) >>

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