/ 
Muldis-D-0.57.0
River stage zero No dependents
/ Muldis::D::Ext::Ordered

NAME

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

VERSION

This document is Muldis::D::Ext::Ordered version 0.57.0.

PREFACE

This document is part of the Muldis D language specification, whose root document is Muldis::D; you should read that root document before you read this one, which provides subservient details.

DESCRIPTION

Muldis D has a mandatory core set of system-defined (eternally available) entities, which is referred to as the Muldis D core or the 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 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 Ordered document describes the system-defined 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) 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 Muldis::D::Core.

This documentation is pending.

SYSTEM-DEFINED ORDER-CONCERNING FUNCTIONS

Each of these functions which has the 2 parameters named func and assuming is a wrapper over the order_determination function named in its func argument when the latter function is curried by its assuming argument. For any q/scalar root type's type-default order function, the argument for func is sys.std.Core.QScalar.order. Each func and assuming parameter is optional and defaults to sys.std.Core.QScalar.order or the zero-attribute tuple, respectively, if no explicit argument is given to it.

function sys.std.Ordered.reverse_order result Order params { topic(Universal), other(Universal), func(OrdDetFuncRef)?, assuming(QTuple)? }

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

function sys.std.Ordered.is_before result Bool params { topic(Universal), other(Universal), func(OrdDetFuncRef)?, assuming(QTuple)? }

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

function sys.std.Ordered.is_not_before result Bool params { topic(Universal), other(Universal), func(OrdDetFuncRef)?, assuming(QTuple)? }

This function is exactly the same as 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".)

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(OrdDetFuncRef)?, assuming(QTuple)? }

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

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(OrdDetFuncRef)?, assuming(QTuple)? }

This function is exactly the same as sys.std.Ordered.is_inside_range except that it results in the opposite boolean value when given the same arguments.

function sys.std.Ordered.min result Universal params { topic(QSet), func(OrdDetFuncRef)?, assuming(QTuple)? }

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 topic has zero values, then this function will fail. Note that, conceptually min does have an identity value which could be this function's result when topic has zero values, which is the result type's concept of positive infinity; however, in practice there is little benefit to min supporting this identity value, since the wrapped 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 Text type.

function sys.std.Ordered.max result Universal params { topic(QSet), func(OrdDetFuncRef)?, assuming(QTuple)? }

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

function sys.std.Ordered.maybe_min result QMaybe params { topic(QSet), func(OrdDetFuncRef)?, assuming(QTuple)? }

This function is exactly the same as sys.std.Ordered.min except that it results in a 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.

function sys.std.Ordered.maybe_max result QMaybe params { topic(QSet), func(OrdDetFuncRef)?, assuming(QTuple)? }

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

SEE ALSO

Go to Muldis::D for the majority of distribution-internal references, and Muldis::D::SeeAlso for the majority of distribution-external references.

AUTHOR

Darren Duncan (perl@DarrenDuncan.net)

LICENSE AND COPYRIGHT

This file is part of the formal specification of the Muldis D language.

Muldis D is Copyright © 2002-2009, Darren Duncan.

See the LICENSE AND COPYRIGHT of Muldis::D for details.

TRADEMARK POLICY

The TRADEMARK POLICY in Muldis::D applies to this file too.

ACKNOWLEDGEMENTS

The ACKNOWLEDGEMENTS in Muldis::D apply to this file too.