=pod

=encoding utf8

=head1 NAME

Muldis::D::Core::Rational -
Muldis D rational numeric operators

=head1 VERSION

This document is Muldis::D::Core::Rational version 0.111.0.

=head1 PREFACE

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

=head1 DESCRIPTION

This document describes essentially all of the core Muldis D operators that
are specific to the core data type C<Rat>, essentially all the generic ones
that a typical programming language should have.

I<This documentation is pending.>

=head1 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

I<This documentation is pending.>

=head1 DATA TYPES THAT SUBTYPE RATIONALS

=head2 sys.std.Core.Type.Rational.BRat

This is an enumeration data type.  C<BRat> (binary rational) is a proper
subtype of C<Rat> where the C<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.

=head2 sys.std.Core.Type.Rational.DRat

This is an enumeration data type.  C<DRat> (decimal rational) is a proper
subtype of C<Rat> where the C<radix> is 10 (or if it could be without the
C<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.

=head1 FUNCTIONS FOR RATIONAL MATH

These functions implement commonly used rational numeric operations.

=head2 sys.std.Core.Rational.abs

C<< 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 C<N||>.

=head2 sys.std.Core.Rational.sum

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

=head2 sys.std.Core.Rational.diff

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

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

=head2 sys.std.Core.Rational.abs_diff

C<< 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 C<N|-|>.

=head2 sys.std.Core.Rational.product

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

=head2 sys.std.Core.Rational.quotient

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

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

=head2 sys.std.Core.Rational.maybe_quotient

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

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

=head2 sys.std.Core.Rational.range

C<< 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 C<topic> has zero values, then C<range>
results in the rational zero.

=head2 sys.std.Core.Rational.mean

C<< 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
C<topic> has zero values, then this function will fail.

=head2 sys.std.Core.Rational.maybe_mean

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

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

=head2 sys.std.Core.Rational.median

C<< 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 C<topic> has
zero values, then the result set is empty.

=head2 sys.std.Core.Rational.mean_of_median

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

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

=head2 sys.std.Core.Rational.mode

C<< 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 C<topic> has zero values, then the result set is empty.

=head2 sys.std.Core.Rational.round

C<< 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 C<topic> argument, where the nearest is determined by the rational
rounding rule specified by the C<round_rule> argument.

=head2 sys.std.Core.Rational.power

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

This function results in its (positive rational) C<radix> argument taken to
the power of its C<exponent> argument.  Since the result would be an
irrational number in the general case, the C<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 C<exponent>, it will
always only result in the one that is positive.  Note that this operation
is also known as I<exponentiation> or C<N^>.

=head2 sys.std.Core.Rational.log

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

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

=head2 sys.std.Core.Rational.natural_power

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

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

=head2 sys.std.Core.Rational.natural_log

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

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

=head1 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.

=head2 sys.std.Core.Rational.fetch_random

C<system-service sys.std.Core.Rational.fetch_random (&$target : Rat,
$radix : PInt2_N, $max_denom : PInt, $interval : sp_interval_of.Rat)>

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

=head1 SEE ALSO

Go to L<Muldis::D> for the majority of distribution-internal
references, and L<Muldis::D::SeeAlso> for the majority of
distribution-external references.

=head1 AUTHOR

Darren Duncan (C<darren@DarrenDuncan.net>)

=head1 LICENSE AND COPYRIGHT

This file is part of the formal specification of the Muldis D language.

Muldis D is Copyright © 2002-2010, Muldis Data Systems, Inc.

See the LICENSE AND COPYRIGHT of L<Muldis::D> for details.

=head1 TRADEMARK POLICY

The TRADEMARK POLICY in L<Muldis::D> applies to this file too.

=head1 ACKNOWLEDGEMENTS

The ACKNOWLEDGEMENTS in L<Muldis::D> apply to this file too.

=cut
