=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.22.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 is either inherently ordered or or has an order-determination
operator defined for them.

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

These functions are applicable to values of potentially any data type,
those which have a C<comparison> or such function defined for them.  They
provide a common syntax for sort-related functionality, though technically
every type having these functions is re-implementing its own version.  If
values of an ordered data type can conceivably be sorted using multiple
criteria (such as different text collations), then these functions just
represent the default criteria; any additional criteria are represented by
additional functions declared for just the types they apply to.

=over

=item C<function sys.std.Ordered.is_before result Bool params {
topic(Universal), other(Universal) }>

This function results in C<Bool:true> iff its 2 arguments are non-identical
and the value of the C<topic> argument is considered to come before the
value of the C<other> argument when the 2 values are arranged in order (as
defined by the type); it results in C<Bool:false> otherwise.  This
function's arguments must be of compatible declared types; in this case, 2
declared types are compatible iff they are both subtypes of a common scalar
type that declares a C<comparison> function for itself.  Note that
C<is_before> is considered the only fundamental ordered-specific operator,
and all others are defined over it plus C<is_identical>.

=item C<function sys.std.Ordered.is_not_before result Bool params {
topic(Universal), other(Universal) }>

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_inside(Bool),
max_is_inside(Bool) }>

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_inside> or C<max_is_inside> are C<Bool:true>, then C<topic> is
considered to be within the range if it is equal to C<min> or C<max>,
respectively; otherwise, C<topic> is not considered to be within the range
if it is equal to C<min> or C<max>.  This function's arguments must be of
compatible declared types as per C<sys.std.Ordered.is_before>.  This
function will fail if C<max> is before C<min>.

=item C<function sys.std.Ordered.is_outside_range result Bool params {
topic(Universal), min(Universal), max(Universal), min_is_inside(Bool),
max_is_inside(Bool) }>

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

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 C<min> results in the
result type's concept of positive infinity, which is the identity value for
I<min>.  This function will fail on a C<topic> of zero values if the result
type's 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)
}>

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, and
its identity value is the result type's concept of negative infinity.

=item C<function sys.std.Ordered.maybe_min result Maybe params { topic(Set)
}>

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.

=item C<function sys.std.Ordered.maybe_max result Maybe params { topic(Set)
}>

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