NAME
Muldis::D::Core::Rational - Muldis D rational numeric operators
VERSION
This document is Muldis::D::Core::Rational version 0.103.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. Moreover, you should read the Muldis::D::Core document before this current document, as that forms its own tree beneath a root document branch.
DESCRIPTION
This document describes essentially all of the core Muldis D operators that are specific to the core data type Rat
, essentially all the generic ones that a typical programming language should have.
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:
sys.std.Core.Type.Universal
sys.std.Core.Type.Empty
sys.std.Core.Type.Scalar
sys.std.Core.Type.DHScalar
sys.std.Core.Type.Cat.OVLScalar
# The following are all regular ordered scalar types.
sys.std.Core.Type.Rat
sys.std.Core.Type.Rational.BRat
sys.std.Core.Type.Rational.DRat
This documentation is pending.
DATA TYPES THAT SUBTYPE RATIONALS
sys.std.Core.Type.Rational.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.Core.Type.Rational.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.Core.Rational.abs
function sys.std.Core.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.Core.Rational.sum
function sys.std.Core.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.Core.Rational.diff
function sys.std.Core.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.Core.Rational.abs_diff
function sys.std.Core.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.Core.Rational.product
function sys.std.Core.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.Core.Rational.quotient
function sys.std.Core.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.Core.Rational.maybe_quotient
function sys.std.Core.Rational.maybe_quotient (maybe_of.Rat <-- $dividend : Rat, $divisor : Rat)
This function is exactly the same as sys.std.Core.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.Core.Rational.range
function sys.std.Core.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.Core.Rational.mean
function sys.std.Core.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.Core.Rational.maybe_mean
function sys.std.Core.Rational.maybe_mean (maybe_of.Rat <-- $topic : bag_of.Rat)
This function is exactly the same as sys.std.Core.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.Core.Rational.median
function sys.std.Core.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.Core.Rational.mean_of_median
function sys.std.Core.Rational.mean_of_median (Rat <-- $topic : bag_of.Rat)
This function is a wrapper over sys.std.Core.Rational.median
that will result in the mean of its result elements; it will fail if there are zero elements.
sys.std.Core.Rational.mode
function sys.std.Core.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.Core.Rational.round
function sys.std.Core.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.Core.Rational.power
function sys.std.Core.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.Core.Rational.log
function sys.std.Core.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.Core.Rational.natural_power
function sys.std.Core.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.Core.Rational.natural_log
function sys.std.Core.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
.
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.Core.Rational.fetch_random
system-service sys.std.Core.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 (darren@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.