=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.26.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.  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> and
C<assuming> parameter is optional and defaults to
C<sys.std.Core.Scalar.order> or the zero-attribute tuple, respectively, if
no explicit argument is given to it.

=over

=item C<function sys.std.Ordered.reverse_order result Cat.Order params {
topic(Universal), other(Universal), func(Cat.OrdDetFuncRef)?,
assuming(QuasiTuple)? }>

This function is exactly the same as the C<order_determination> function it
wraps except that it results in the reverse value when given the same
non-C<func> arguments.  It is a short-hand for applying
C<sys.std.Core.Cat.Order_reverse> to the result of the wrapped function
with the same non-C<func> arguments.

=item C<function sys.std.Ordered.is_before result Bool params {
topic(Universal), other(Universal), func(Cat.OrdDetFuncRef)?,
assuming(QuasiTuple)? }>

This function results in C<Bool:true> iff the wrapped function would result
in C<Cat.Order:increase> when given the same arguments, and C<Bool:false>
otherwise.

=item C<function sys.std.Ordered.is_not_before result Bool params {
topic(Universal), other(Universal), func(Cat.OrdDetFuncRef)?,
assuming(QuasiTuple)? }>

This function is exactly the same as C<sys.std.Ordered.is_before> except
that it results in the opposite boolean value when given the same
arguments.  (It could alternately be called "is after or is identical".)

=item C<function sys.std.Ordered.is_inside_range result Bool params {
topic(Universal), min(Universal), max(Universal), min_is_outside(Bool)?,
max_is_outside(Bool)?, func(Cat.OrdDetFuncRef)?, assuming(QuasiTuple)? }>

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.

=item C<function sys.std.Ordered.is_outside_range result Bool params {
topic(Universal), min(Universal), max(Universal), min_is_outside(Bool)?,
max_is_outside(Bool)?, func(Cat.OrdDetFuncRef)?, assuming(QuasiTuple)? }>

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.

=item C<function sys.std.Ordered.min result Universal params { topic(Set),
func(Cat.OrdDetFuncRef)?, assuming(QuasiTuple)? }>

This function is a reduction operator that recursively takes each pair of
its N input element values and picks the minimum of the 2 (a process which
is both commutative and associative) 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.

=item C<function sys.std.Ordered.max result Universal params { topic(Set),
func(Cat.OrdDetFuncRef)?, assuming(QuasiTuple)? }>

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

=item C<function sys.std.Ordered.maybe_min result Maybe params {
topic(Set), func(Cat.OrdDetFuncRef)?, assuming(QuasiTuple)? }>

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.

=item C<function sys.std.Ordered.maybe_max result Maybe params {
topic(Set), func(Cat.OrdDetFuncRef)?, assuming(QuasiTuple)? }>

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

=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