NAME

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

VERSION

This document is Language::MuldisD::Ext::Rational version 0.20.0.

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.

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 in general, and not just integers such as the language core has.

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 Language::MuldisD::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.Core.Universal.Universal

    sys.Core.Universal.Empty

    sys.Core.Scalar.Scalar

        # The following are all regular ordered scalar types.

        sys.Rational.Rat.Rat
            sys.Rational.Rat.URat
                sys.Rational.Rat.PRat
            sys.Rational.Rat.BRat
            sys.Rational.Rat.DRat

        sys.Core.Scalar.Int
            sys.Core.Scalar.UInt
                sys.Core.Scalar.PInt

                    # These are all integer types.

                    sys.Rational.Cat.PInt_2_N

        # The following are all regular non-ordered scalar types.

        sys.Rational.Cat.E_RM

    sys.Core.Tuple.Tuple

        # The following are all regular tuple types.

        sys.Rational.Cat.RatRoundRule

Also for convenience are the regular set|maybe|seq|bag types sys.Rational.Spec.(Set|Maybe|Seq|Bag)OfRat.

This documentation is pending.

SYSTEM-DEFINED RATIONAL-CONCERNING DATA TYPES

sys.Rational.Cat.PInt_2_N

A Cat.PInt2_N is a proper subtype of PInt where all member values are greater than 1. Its default and minimum value is 2.

sys.Rational.Rat.Rat

A Rat (scalar) is a single exact rational number of any magnitude and precision. It is conceptually a composite type with 2 main system-defined possreps, called ratio and float, both of which are defined over several Int.

The ratio possrep consists of 2 attributes: numerator (an Int), denominator (a PInt); the conceptual value of a Rat is the result of rational-dividing its numerator by its denominator. Because in the general case there are an infinite set of [numerator,denominator] integer pairs that denote the same rational value, the ratio possrep carries the normalization constraint that numerator and denominator must be coprime, that is, they have no common integer factors other than 1.

The float possrep consists of 3 attributes: mantissa (an Int), radix (a Cat.PInt2_N), exponent (an Int); the conceptual value of a Rat is the result of multiplying its mantissa by the result of taking its radix to the power of its exponent. The float possrep carries the normalization constraint that among all the [mantissa,radix,exponent] triples which would denote the same rational value, the only allowed triple is the one having both the radix with the lowest value (that is closest to or equal to 2) and the exponent with the highest value (that is closest to positive infinity). Note: this constraint could stand to be rephrased for simplification or correction, eg if somehow the sets of candidate triples sharing the lowest radix and sharing the highest exponent have an empty intersection.

The default value of Rat is zero; its minimum and maximum values are conceptually infinities and practically impossible. The cardinality of this type is infinity; to define a most-generalized finite Rat subtype, you must specify the greatest magnitude value denominator, plus the the 2 integer end-points of the inclusive range of the value numerator; or alternately you must specify the greatest magnitude value mantissa (the maximum precision of the number), and specify the greatest magnitude value radix, plus the the 2 integer end-points of the inclusive range of the value exponent (the maximum scale of the number). Common subtypes specify that the normalized radixes of all their values are either 2 or 10; types such as these will easily map exactly to common human or physical numeric representations, so they tend to perform better.

sys.Rational.Rat.URat

A URat (unsigned / non-negative rational) is a proper subtype of Rat where all member values are greater than or equal to zero (that is, the numerator|mantissa is greater than or equal to zero). Its minimum value is zero.

sys.Rational.Rat.PRat

A PRat (positive rational) is a proper subtype of URat where all member values are greater than zero (that is, the numerator|mantissa is greater than zero). Its default value is 1.

sys.Rational.Rat.BRat

A 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.

sys.Rational.Rat.DRat

A 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.

sys.Rational.Cat.E_RM

A Cat.E_RM (rounding method) is a scalar enumeration consisting of the 7 values Cat.E_RM:half_down, Cat.E_RM:half_up, Cat.E_RM:half_even, Cat.E_RM:to_floor, Cat.E_RM:to_ceiling, Cat.E_RM:to_zero, Cat.E_RM:to_inf. When a value of some ordered type needs to be mapped into a proper subtype that doesn't contain that value, such as when mapping an arbitrary number to one with less precision, some rounding method is applied to determine which value of the subtype is to be mapped to while most accurately reflecting the original value. The Cat.E_RM type enumerates the rounding methods that Muldis D operators can typically apply. With half_down, half_up, and half_even (aka unbiased rounding, convergent rounding, statistician's rounding, or bankers' rounding), the original value will be mapped to the single target value that it is closest to, if there is one; otherwise, if it is exactly half-way between 2 adjacent target values, then half_down will round towards negative infinity, half_up will round towards positive infinity, and half_even will round towards the nearest "even" target. With to_floor, to_ceiling, to_zero (aka truncate), to_inf, the original value will always be mapped to the single adjacent value that is lower than it, or higher than it, or towards "zero" from it, or towards the nearer infinity from it, respectively. The default value of Cat.E_RM is Cat.E_RM:half_up, since that is the most commonly used method of rounding.

sys.Rational.Cat.RatRoundRule

A Cat.RatRoundRule is a Tuple. It specifies a controlled (and typically degrading) coercion of a real number into a rational number having a specific radix and precision. It is mainly used to deterministically massage an operation, whose conceptual result is generally an irrational number, so that its actual result is a best approximating rational number. It is also used to define a generic rounding operation on a rational number that derives a typically less precise rational. A Cat.RatRoundRule has these 3 attributes: radix (a Cat.PInt2_N), max_denom (a PInt), and round_meth (a Cat.E_RM). The rational resulting from the operation is as close as possible to the conceptual result but that its denominator is a non-negative power of radix and said denominator is not larger than max_denom; if rounding is needed, then round dictates the rounding method. The default value of Cat.RatRoundRule specifies a coersion to a whole number using the Cat.E_RM:half_up rounding method (its radix is 2 and its max denom is 1).

sys.Rational.Spec.(Set|Maybe|Seq|Bag)OfRat

A (Set|Maybe|Seq|Bag)OfRat is a completely defined proper subtype of (Set|Maybe|Seq|Bag) whose value attribute has a declared type of a Rat subtype.

SYSTEM-DEFINED RATIONAL-CONCERNING FUNCTIONS

These functions are essentially selectors and attribute extractors for the conceptual possrep of a rational in terms of an integral numerator plus denominator.

function sys.Rational.Rat.Rat_from_Int_pair result Rat params { numerator(Int), denominator(PInt) }

This selector function results in the Rat value that arguments collectively map to as the attributes of the result's ratio possrep; however, the arguments do not have to be the canonical/normalized attribute values, but constitute any other pair that denotes the same rational value.

function sys.Rational.Rat.Rat_from_Int_triple result Rat params { mantissa(Int), radix(Cat.PInt2_N), exponent(Int) }

This selector function results in the Rat value that arguments collectively map to as the attributes of the result's float possrep; however, the arguments do not have to be the canonical/normalized attribute values, but constitute any other triple that denotes the same rational.

function sys.Rational.Rat.(numerator|mantissa|exponent) result Int params { topic(Rat) }

This function results in the canonical numerator|mantissa|exponent of its argument.

function sys.Rational.Rat.denominator result PInt params { topic(Rat) }

This function results in the canonical denominator of its argument.

function sys.Rational.Rat.radix result Cat.PInt2_N params { topic(Rat) }

This function results in the canonical radix of its argument.

These functions implement commonly used rational numeric operations.

function sys.Rational.Rat.abs result URat params { topic(Rat) }

This function results in the absolute value of its argument.

function sys.Rational.Rat.sum result Rat params { addends(BagOfRat) }

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 rational zero, which is the identity value for addition.

function sys.Rational.Rat.difference result Rat params { minuend(Rat), subtrahend(Rat) }

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

function sys.Rational.Rat.product result Rat params { factors(BagOfRat) }

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 rational 1, which is the identity value for multiplication.

function sys.Rational.Rat.quotient result Rat params { 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.

function sys.Rational.Rat.maybe_quotient result MaybeOfRat params { dividend(Rat), divisor(Rat) }

This function is exactly the same as sys.Rational.Rat.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.Rational.Rat.range result Rat params { topic(SetOfRat) }

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.

function sys.Rational.Rat.mean result Rat params { topic(BagOfRat) }

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.

function sys.Rational.Rat.maybe_mean result MaybeOfRat params { topic(BagOfRat) }

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

function sys.Rational.Rat.median result SetOfRat params { topic(BagOfRat) }

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.Rational.Rat.mean_of_median result Rat params { topic(BagOfRat) }

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

function sys.Rational.Rat.mode result SetOfRat params { topic(BagOfRat) }

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.Rational.Rat.round result Rat params { topic(Rat), round_rule(Cat.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.

function sys.Rational.Rat.power result PRat params { radix(PRat), exponent(Rat) }

This function results in its (positive rational) radix argument taken to the power of its exponent argument. 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.

function sys.Rational.Rat.log result Rat params { topic(PRat), radix(PRat), round_rule(Cat.RatRoundRule) }

This function results in the logarithm of its topic argument to the base given in its (positive rational) radix 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.

function sys.Rational.Rat.natural_power result PRat params { exponent(Rat), round_rule(Cat.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 log.

function sys.Rational.Rat.natural_log result Rat params { topic(PRat), round_rule(Cat.RatRoundRule) }

This function results in the natural logarithm of its topic argument. The round_rule parameter is as per log.

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

function sys.Rational.Rat.Rat_from_NEText result Rat params { text(NEText), radix(Cat.PInt2_36) }

This selector function results in the Rat value that its 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.

function sys.Rational.Rat.NEText_from_Rat result NEText params { rat(Rat), radix(Cat.PInt2_36) }

This selector function results in the NEText value where its rat argument is formatted as a base-radix rational.

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

function sys.Rational.Rat.Rat_from_Int result Rat params { int(Int) }

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

function sys.Rational.Rat.Int_from_Rat result Int params { rat(Rat), round_meth(Cat.E_RM) }

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.

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.

cpanm Language::MuldisD

perl -MCPAN -e shell
install Language::MuldisD