/ 
Language-MuldisD-0.22.1
/ Language::MuldisD::Core::Routines

NAME

Language::MuldisD::Core::Routines - Muldis D general purpose routines

VERSION

This document is Language::MuldisD::Core::Routines version 0.19.1.

PREFACE

This document is part of the Muldis D language specification, whose root document is Language::MuldisD; you should read that root document before you read this one, which provides subservient details. Moreover, you should read the Language::MuldisD::Core document before this current document, as that forms its own tree beneath a root document branch.

DESCRIPTION

This document contains one or more sections that were moved here from Language::MuldisD::Core so that that other document would not be too large.

SYSTEM-DEFINED GENERIC UNIVERSAL FUNCTIONS

These functions are applicable to values of any data type at all.

function sys.Core.Universal.is_identical result Bool params { topic(Universal), other(Universal) }

This function results in Bool:true iff its 2 arguments are exactly the same value, and Bool:false otherwise. This function's arguments must be of compatible declared types; in this case, 2 declared types are compatible iff at least one of the following is true: 1. they are both subtypes of a common scalar root type; 2. they are both subtypes of a common non-incomplete tuple or relation type, that is they essentially have the same headings; 3. at least one type is a generic (eg-Universal) or incomplete (eg-Seq) type, and it is a supertype of the other. This function's 2 parameters are mutually commutative.

function sys.Core.Universal.is_not_identical result Bool params { topic(Universal), other(Universal) }

This function is exactly the same as sys.Core.Universal.is_identical except that it results in the opposite boolean value when given the same arguments.

function sys.Core.Universal.is_value_of_type result Bool params { topic(Universal), type(Cat.NameChain) }

This function results in Bool:true iff the value of its topic argument is a member of the data type whose name is given in the type argument, and Bool:false otherwise. As trivial cases, this function always results in Bool:true if the named type is Universal, and Bool:false if it is Empty. This function will fail if the named type doesn't exist in the virtual machine.

function sys.Core.Universal.treated result Universal params { topic(Universal), as(Cat.NameChain) }

This function results in the value of its topic argument, but that the declared type of the result is the not-Empty data type whose name is given in the as argument. This function will fail if the named type doesn't exist in the virtual machine, or if topic isn't a member of the named type. The purpose of treated is to permit taking values from a context having a more generic declared type, and using them in a context having a more specific declared type; such an action would otherwise be blocked at compile time due to a type-mismatch error; treated causes the type-mismatch validation, and possible failure, to happen at runtime instead, on the actual value rather than declared value. For example, if you are storing an Int value in a Scalar-typed variable, using treated will cause the compiler to let you use that variable as an argument to Int.sum, which it otherwise wouldn't.

function sys.Core.Universal.default result Universal params { of(Cat.NameChain) }

This function results in the default value of the not-Empty data type whose name is given in the of argument, and the declared type of the result is that same type. This function will fail if the named type doesn't exist in the virtual machine, either at compile or runtime depending whether the type is in the system or user namespace. This function is conceptually implicitly used to provide default values for variables, so they always hold valid values of their declared type.

SYSTEM-DEFINED GENERIC ORDERED FUNCTIONS

These functions are applicable to values of any data type which is a subtype of Ordered. 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.

function sys.Core.Ordered.is_before result Bool params { topic(Ordered), other(Ordered) }

This function results in Bool:true iff its 2 arguments are non-identical and the value of the topic argument is considered to come before the value of the other argument when the 2 values are arranged in order (as defined by the type); it results in 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 itself an Ordered subtype. Note that is_before is considered the only fundamental ordered-specific operator, and all others are defined over it plus is_identical.

function sys.Core.Ordered.is_not_before result Bool params { topic(Ordered), other(Ordered) }

This function is exactly the same as sys.Core.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.Core.Ordered.is_inside_range result Bool params { topic(Ordered), min(Ordered), max(Ordered), min_is_inside(Bool), max_is_inside(Bool) }

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

function sys.Core.Ordered.is_outside_range result Bool params { topic(Ordered), min(Ordered), max(Ordered), min_is_inside(Bool), max_is_inside(Bool) }

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

function sys.Core.Ordered.min result Ordered params { topic(SetOfOrdered) }

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 min results in the result type's concept of positive infinity, which is the identity value for min. This function will fail on a 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 Text type.

function sys.Core.Ordered.max result Ordered params { topic(SetOfOrdered) }

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

function sys.Core.Ordered.maybe_min result MaybeOfOrdered params { topic(SetOfOrdered) }

This function is exactly the same as sys.Core.Ordered.min except that it results in a Maybe of what is otherwise the result type, and that result has zero elements if the argument has zero elements.

function sys.Core.Ordered.maybe_max result MaybeOfOrdered params { topic(SetOfOrdered) }

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

SYSTEM-DEFINED CORE GENERIC QUASI- FUNCTIONS

This documentation is pending.

SYSTEM-DEFINED CORE CATALOG FUNCTIONS

This documentation is pending.

SYSTEM-DEFINED CORE UPDATERS

Generic Universal

These update operators are applicable to values of any data type at all.

updater sys.Core.Universal.assign update { target(Universal) } read { v(Universal) }

This update operator will update the variable supplied as its target argument so that it holds the value supplied as its v argument. This update operator's arguments must be of compatible declared types; in this case, v must be a subtype of target.

SYSTEM-DEFINED CORE SYSTEM SERVICES

These system services are applicable to just one or more specific system-defined core scalar data type.

This documentation is pending.

SYSTEM-DEFINED CORE PROCEDURES

Generic Control-Flow Procedures

These procedures are applicable to use in all kinds of procedures.

procedure sys.Core.Control.fail update {} read { topic(Cat.Exception) }

This procedure will throw the exception given as its argument; this results in the call stack unwinding, and transaction rollbacks, until it is caught.

procedure sys.Core.Control.try_catch update { try_updating(Tuple), catch_updating(Tuple) } read { try(Cat.NameChain), catch(Cat.NameChain), try_assuming(Tuple), catch_assuming(Tuple) }

This procedure invokes the procedure named in its try argument, giving it the arguments try_updating and try_assuming as its updating and assuming arguments, respectively. If the try procedure throws an exception, then any state changes it made roll back (but changes made before that don't), and the call stack unwinds to the try_catch itself; then the procedure named by catch is invoked similarly to try was, with corresponding arguments, but with the extra read-only argument topic whose value is a Cat.Exception; if the catch procedure also throws an exception (such as to say its not handling the thrown one), then that one is not caught and the call stack unwinding plus applicable transaction rollback carries on to the caller of the try_catch. If the try procedure succeeds (doesn't throw an exception), then the catch procedure is not called.

SEE ALSO

Go to Language::MuldisD for the majority of distribution-internal references, and Language::MuldisD::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-2008, Darren Duncan.

See the LICENSE AND COPYRIGHT of Language::MuldisD for details.

ACKNOWLEDGEMENTS

The ACKNOWLEDGEMENTS in Language::MuldisD apply to this file too.