/ 
Muldis-D-0.55.0
River stage zero No dependents
/ Muldis::D::Ext::Integer

NAME

Muldis::D::Ext::Integer - Muldis D extension for integer data types and operators

VERSION

This document is Muldis::D::Ext::Integer version 0.55.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 Integer document describes the system-defined Muldis D Integer Extension, which consists of integer data types and operators, essentially all the generic ones that a typical programming language should have, but for the bare minimum needed for bootstrapping Muldis D, which are defined in the language core instead.

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.

TYPE SUMMARY

Following are all the data types described in this document, arranged in a type graph according to their proper sub|supertype relationships (but that a few of them just reappear from the core set to provide a similar context, and aren't re-described here):

sys.std.Core.Type.Universal

    sys.std.Core.Type.Empty

    sys.std.Core.Type.QScalar
        sys.std.Core.Type.Scalar
            sys.std.Core.Type.Int
                sys.std.Core.Type.NNInt
                    sys.std.Core.Type.PInt

                        # These are all finite integer types.

                        sys.std.Integer.Type.PInt2_36

This documentation is pending.

SYSTEM-DEFINED INTEGER-CONCERNING DATA TYPES

sys.std.Integer.Type.PInt2_36

This is an enumeration data type. PInt2_36 is a proper subtype of PInt where all member values are between 2 and 36. (The significance of the number 36 is 10 digits plus 26 letters.) Its default and minimum value is 2. Its maximum value is 36. The cardinality of this type is 35.

FUNCTIONS FOR INTEGER MATH

These functions implement commonly used integer numeric operations.

function sys.std.Integer.increment result Int params { topic(Int) }

This function results in its argument incremented by 1.

function sys.std.Integer.decrement result Int params { topic(Int) }

This function results in its argument decremented by 1.

function sys.std.Integer.abs result NNInt params { topic(Int) }

This function results in the absolute value of its argument.

function sys.std.Integer.sum result Int params { addends(bag_of.Int) }

This function results in the sum of the N element values of its argument; it is a reduction operator that recursively takes each pair of input values and adds (which is both commutative and associative) them together until just one is left, which is the result. If addends has zero values, then sum results in the integer zero, which is the identity value for addition.

function sys.std.Integer.difference result Int params { minuend(Int), subtrahend(Int) }

This function results in the difference when its subtrahend argument is subtracted from its minuend argument.

function sys.std.Integer.abs_difference result Int params { topic(Int), other(Int) }

This function results in the absolute difference between its 2 arguments.

function sys.std.Integer.product result Int params { factors(bag_of.Int) }

This function results in the product of the N element values of its argument; it is a reduction operator that recursively takes each pair of input values and multiplies (which is both commutative and associative) them together until just one is left, which is the result. If factors has zero values, then product results in the integer 1, which is the identity value for multiplication.

function sys.std.Integer.quotient result Int params { dividend(Int), divisor(Int) }

This function results in the quotient when its dividend argument is divided by its divisor argument using integer division. This function will fail if divisor is zero.

function sys.std.Integer.remainder result NNInt params { dividend(Int), divisor(Int) }

This function results in the remainder when its dividend argument is divided by its divisor argument using integer division. This function will fail if divisor is zero.

function sys.std.Integer.maybe_quotient result maybe_of.Int params { dividend(Int), divisor(Int) }

This function is exactly the same as sys.std.Integer.quotient except that it results in a Maybe of what is otherwise the result, and that result has zero elements if divisor is zero.

function sys.std.Integer.maybe_remainder result maybe_of.NNInt params { dividend(Int), divisor(Int) }

This function is exactly the same as sys.std.Integer.remainder except that it results in a Maybe of what is otherwise the result, and that result has zero elements if divisor is zero.

function sys.std.Integer.range result Int params { topic(set_of.Int) }

This function results in the difference between the lowest and highest element values of its argument. If topic has zero values, then range results in the integer zero.

function sys.std.Integer.median result set_of.Int params { topic(bag_of.Int) }

This function results in the 1 or 2 median values of the N element values of its argument; they are returned as a set. It is equivalent to first arranging the input values from least to greatest, and then taking the single middle value, if the count of input values is odd, or taking the 2 middle values, if the count of input values is even (but if the 2 middle values are the same value, the output has one element). If topic has zero values, then the result set is empty.

function sys.std.Integer.mode result set_of.Int params { topic(bag_of.Int) }

This function results in the mode of the N element values of its argument; it is the set of values that appear the most often as input elements, and all have the same count of occurrances. As a trivial case, if all input elements have the same count of occurrances, then they will all be in the output. If topic has zero values, then the result set is empty.

function sys.std.Integer.power result Int params { radix(Int), exponent(NNInt) }

This function results in its radix argument taken to the power of its (non-negative integer) exponent argument. This function will fail if radix and exponent are both zero.

function sys.std.Integer.factorial result PInt params { topic(NNInt) }

This function results in the factorial of its argument (it is defined for an argument of zero to result in 1, as per the identity value for multiplication of an empty set).

FUNCTIONS FOR INTEGER CONVERSION WITH TEXT

These functions convert between Int values and canonically formatted representations of integers as character strings.

function sys.std.Integer.Int_from_Text result Int params { text(Text), radix(PInt2_36) }

This selector function results in the Int value that its (not-empty) text argument maps to when the whole character string is evaluated as a base-radix integer. Extending the typical formats of [base-2, base-8, base-10, base-16], this function supports base-2 through base-36; to get the latter, the characters 0-9 and A-Z represent values in 0-35. This function will fail if text can't be mapped as specified.

function sys.std.Integer.Text_from_Int result Text params { int(Int), radix(PInt2_36) }

This selector function results in the (not-empty) Text value where its int argument is formatted as a base-radix integer.

FUNCTIONS FOR INTEGER CONVERSION WITH BLOB

These functions convert between Int values and canonically formatted representations of integers as binary strings. Conjecture: These may not actually be useful, and perhaps only operators that take an argument specifying a fixed-length field size, with big and little endian versions, would be appropriate instead. Or maybe both kinds are necessary.

function sys.std.Integer.Int_from_Blob_S_VBE result Int params { blob(Blob) }

This selector function results in the Int value that its blob argument maps to when the whole bit string is treated literally as a variable-length binary (two's complement) signed integer of 1 or more bits in length. The first bit is taken as the sign bit, and any other bits provide greater precision than the -1 thru 0 range. The bit string is assumed to be big-endian, since it may not be possible to use little-endian in situations where the bit length isn't a multiple of 8.

function sys.std.Integer.Blob_S_VBE_from_Int result Blob params { int(Int) }

This selector function results in the Blob value where its int argument is formatted as a variable-length binary (two's complement) signed integer of 1 or more bits in length; the smallest number of bits necessary to store int is used.

function sys.std.Integer.Int_from_Blob_U_VBE result NNInt params { blob(Blob) }

This function is the same as sys.std.Integer.Int_from_Blob_S_VBE but that it does unsigned integers.

function sys.std.Integer.Blob_U_VBE_from_Int result NNInt params { blob(Blob) }

This function is the same as sys.std.Integer.Blob_S_VBE_from_Int but that it does unsigned integers.

SYSTEM SERVICES FOR RANDOM NUMBER GENERATORS

These system service routines provide ways to get random numbers from the system. Where the results are in the range between truly random and pseudo-random is, for the moment, an implementation detail, but the details of these functions is subject to become more formalized later.

system_service sys.std.Integer.fetch_random update { target(Int) } read { min(Int), max(Int), exclude_min(Bool)?, exclude_max(Bool)? }

This system service routine will update the variable supplied as its target argument so that it holds a randomly generated integer value in the range whose bounds are defined by its min and max arguments. If exclude_min or exclude_max are Bool:true, then the randomly generated value will not be equal to min or max, respectively; otherwise, the generated value might be equal to min or max. This function will fail if max is before min. Each of the exclude_m(in|ax) parameters is optional and defaults to Bool:false if no explicit argument is given to it.

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-2008, 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.