The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Muldis-D-0.97.0
River stage zero No dependents
/ Muldis::D::Ext::Rational

NAME

Muldis::D::Ext::Rational - Muldis D extension for rational data types and operators

VERSION

This document is Muldis::D::Ext::Rational version 0.97.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 Rational document describes the system-defined Muldis D Rational Extension, which consists of rational 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.Scalar
            sys.std.Core.Type.DHScalar

                # The following are all regular ordered scalar types.

                sys.std.Core.Type.Rat
                    sys.std.Rational.Type.BRat
                    sys.std.Rational.Type.DRat

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

                            # These are all finite integer types.

                            sys.std.Rational.Type.PInt2_36

This documentation is pending.

SYSTEM-DEFINED RATIONAL-CONCERNING DATA TYPES

sys.std.Rational.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.

sys.std.Rational.Type.BRat

This is an enumeration data type. BRat (binary rational) is a proper subtype of Rat where the radix is 2; it is the best option to exactly represent rational numbers that are conceptually binary or octal or hexadecimal, such as most IEEE-754 floating point numbers.

sys.std.Rational.Type.DRat

This is an enumeration data type. DRat (decimal rational) is a proper subtype of Rat where the radix is 10 (or if it could be without the float possrep normalization constraint); it is the best option to exactly represent rational numbers that are conceptually the decimal numbers that humans typically work with.

FUNCTIONS FOR RATIONAL MATH

These functions implement commonly used rational numeric operations.

sys.std.Rational.abs

function sys.std.Rational.abs (NNRat <-- $topic : Rat)

This function results in the absolute value of its argument. Note that this operation is also known as N||.

sys.std.Rational.sum

function sys.std.Rational.sum (Rat <-- $topic? : bag_of.Rat)

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 topic has zero values, then sum results in the rational zero, which is the identity value for addition. Note that this operation is also known as addition or plus or N+.

sys.std.Rational.diff

function sys.std.Rational.diff (Rat <-- $minuend : Rat, $subtrahend : Rat)

This function results in the difference when its subtrahend argument is subtracted from its minuend argument. Note that this operation is also known as subtraction or minus or N-.

sys.std.Rational.abs_diff

function sys.std.Rational.abs_diff (Rat <-- $topic : Rat, $other : Rat)

This symmetric function results in the absolute difference between its 2 arguments. Note that this operation is also known as N|-|.

sys.std.Rational.product

function sys.std.Rational.product (Rat <-- $topic? : bag_of.Rat)

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 topic has zero values, then product results in the rational 1, which is the identity value for multiplication. Note that this operation is also known as multiply or times or N*.

sys.std.Rational.quotient

function sys.std.Rational.quotient (Rat <-- $dividend : Rat, $divisor : Rat)

This function results in the quotient when its dividend argument is divided by its divisor argument using rational division. This function will fail if divisor is zero. Note that this operation is also known as divide or N/.

sys.std.Rational.maybe_quotient

function sys.std.Rational.maybe_quotient (maybe_of.Rat <-- $dividend : Rat, $divisor : Rat)

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

sys.std.Rational.range

function sys.std.Rational.range (Rat <-- $topic : set_of.Rat)

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 rational zero.

sys.std.Rational.mean

function sys.std.Rational.mean (Rat <-- $topic : bag_of.Rat)

This function results in the mean or arithmetic average of the N element values of its argument. It is equivalent to first taking the sum of the input values, and dividing that sum by the count of the input values. If topic has zero values, then this function will fail.

sys.std.Rational.maybe_mean

function sys.std.Rational.maybe_mean (maybe_of.Rat <-- $topic : bag_of.Rat)

This function is exactly the same as sys.std.Rational.mean except that it results in a Maybe of what is otherwise the result, and that result has zero elements if topic has zero values.

sys.std.Rational.median

function sys.std.Rational.median (set_of.Rat <-- $topic : bag_of.Rat)

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.

sys.std.Rational.mean_of_median

function sys.std.Rational.mean_of_median (Rat <-- $topic : bag_of.Rat)

This function is a wrapper over sys.std.Rational.median that will result in the mean of its result elements; it will fail if there are zero elements.

sys.std.Rational.mode

function sys.std.Rational.mode (set_of.Rat <-- $topic : bag_of.Rat)

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.

sys.std.Rational.round

function sys.std.Rational.round (Rat <-- $topic : Rat, $round_rule : RatRoundRule)

This function results in the rational that is equal to or otherwise nearest to its topic argument, where the nearest is determined by the rational rounding rule specified by the round_rule argument.

sys.std.Rational.power

function sys.std.Rational.power (PRat <-- $radix : PRat, $exponent : Rat, $round_rule : RatRoundRule)

This function results in its (positive rational) radix argument taken to the power of its exponent argument. Since the result would be an irrational number in the general case, the round_rule argument specifies how to coerce the conceptual result into a rational number that is the actual result. Note that, while this function might conceptually have multiple real number results for some fractional exponent, it will always only result in the one that is positive. Note that this operation is also known as exponentiation or N^.

sys.std.Rational.log

function sys.std.Rational.log (Rat <-- $topic : PRat, $radix : PRat, $round_rule : RatRoundRule)

This function results in the logarithm of its topic argument to the base given in its (positive rational) radix argument. The round_rule parameter is as per power.

sys.std.Rational.natural_power

function sys.std.Rational.natural_power (PRat <-- $exponent : Rat, $round_rule : RatRoundRule)

This function results in the special mathematical constant e (which is the base of the natural logarithm) taken to the power of its exponent argument. The round_rule parameter is as per power. Note that this operation is also known as e^.

sys.std.Rational.natural_log

function sys.std.Rational.natural_log (Rat <-- $topic : PRat, $round_rule : RatRoundRule)

This function results in the natural logarithm of its topic argument. The round_rule parameter is as per power. Note that this operation is also known as log-e.

FUNCTIONS FOR RATIONAL CONVERSION WITH TEXT

These functions convert between Rat values and canonically formatted representations of rationals as character strings.

sys.std.Rational.Rat_from_Text

function sys.std.Rational.Rat_from_Text (Rat <-- $text : Text, $radix : PInt2_36)

This selector function results in the Rat value that its (not-empty) text argument maps to when the whole character string is evaluated as a base-radix rational. 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.

sys.std.Rational.Text_from_Rat

function sys.std.Rational.Text_from_Rat (Text <-- $rat : Rat, $radix : PInt2_36)

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

FUNCTIONS FOR RATIONAL CONVERSION WITH INTEGER

These functions convert between Rat values and equal or nearly equal Int values.

sys.std.Rational.Rat_from_Int

function sys.std.Rational.Rat_from_Int (Rat <-- $int : Int)

This selector function results in the Rat value that is conceptually equal to its Int argument.

sys.std.Rational.Int_from_Rat

function sys.std.Rational.Int_from_Rat (Int <-- $rat : Rat, $round_meth : RatRoundMeth)

This selector function results in the Int value that is conceptually equal to or otherwise nearest to its rat argument, where the nearest is determined by the rounding method specified by the round_meth argument.

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.

sys.std.Rational.fetch_random

system-service sys.std.Rational.fetch_random (&$target : Rat, $radix : PInt2_N, $max_denom : PInt, $interval : interval_of.Rat)

This system service routine will update the variable supplied as its target argument so that it holds a randomly generated rational value that is included within the interval defined by its interval argument. The denominator attribute of the generated value will be a non-negative power of radix that is not larger than max_denom. This function will fail if interval represents an empty interval.

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, Muldis Data Systems, Inc.

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.