=pod

=encoding utf8

=head1 NAME

Muldis::D::Core::Integer -
Muldis D integer numeric operators

=head1 VERSION

This document is Muldis::D::Core::Integer version 0.148.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<Int>, essentially all the generic ones
that a typical programming language should have.

I<This documentation is pending.>

=head1 FUNCTIONS IMPLEMENTING VIRTUAL ORDERED FUNCTIONS

=head2 sys.std.Core.Integer.order

C<< function order (Order <-- topic : Int,
other : Int, misc_args? : Tuple, is_reverse_order? : Bool)
implements sys.std.Core.Ordered.order {...} >>

This is a (total) C<order-determination> function specific to C<Int>.  Its
only valid C<misc_args> argument is C<Tuple:D0>.

=head1 FUNCTIONS IMPLEMENTING VIRTUAL ORDINAL FUNCTIONS

=head2 sys.std.Core.Integer.pred

C<< function pred (Int <-- topic : Int)
implements sys.std.Core.Ordered.Ordinal.pred {...} >>

This function results in the value that precedes its argument.  It is a
shorthand for adding 1 to its argument.

=head2 sys.std.Core.Integer.succ

C<< function succ (Int <-- topic : Int)
implements sys.std.Core.Ordered.Ordinal.succ {...} >>

This function results in the value that succeeds its argument.  It is a
shorthand for subtracting 1 from its argument.

=head1 FUNCTIONS IMPLEMENTING VIRTUAL NUMERIC FUNCTIONS

=head2 sys.std.Core.Integer.abs

C<< function abs (NNInt <-- topic : Int)
implements sys.std.Core.Numeric.abs {...} >>

This function results in the absolute value of its argument.

=head2 sys.std.Core.Integer.sum

C<< function sum (Int <-- topic? : bag_of.Int)
implements sys.std.Core.Numeric.sum {...} >>

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

=head2 sys.std.Core.Integer.diff

C<< function diff (Int <-- minuend : Int, subtrahend : Int)
implements sys.std.Core.Numeric.diff {...} >>

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

=head2 sys.std.Core.Integer.abs_diff

C<< function abs_diff (Int <-- topic : Int, other : Int)
implements sys.std.Core.Numeric.abs_diff {...} >>

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

=head2 sys.std.Core.Integer.product

C<< function product (Int <-- topic? : bag_of.Int)
implements sys.std.Core.Numeric.product {...} >>

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

=head2 sys.std.Core.Integer.frac_quotient

C<< function frac_quotient (Rat <-- dividend : Int, divisor : Int)
implements sys.std.Core.Numeric.frac_quotient {...} >>

This function results in the rational quotient when its C<dividend>
argument is divided by its C<divisor> argument using the semantics of real
number division.  This function will fail if C<divisor> is zero.  It is an
alternate way to construct a C<Rat> literal at runtime in terms of 2 C<Int>
that are its C<numerator> and C<denominator> possrep attributes.

=head2 sys.std.Core.Integer.whole_quotient

C<< function whole_quotient (Int <--
dividend : Int, divisor : Int, round_meth : RoundMeth)
implements sys.std.Core.Numeric.whole_quotient {...} >>

This function results in the integer quotient when its C<dividend> argument
is divided by its C<divisor> argument using the semantics of real number
division, and then the latter's result is rounded to the same or nearest
integer, where the nearest is determined by the rounding method specified
by the C<round_meth> argument.  This function will fail if C<divisor> is
zero.

=head2 sys.std.Core.Integer.remainder

C<< function remainder (Int <--
dividend : Int, divisor : Int, round_meth : RoundMeth)
implements sys.std.Core.Numeric.remainder {...} >>

This function results in the integer remainder when its C<dividend>
argument is divided by its C<divisor> argument using the semantics of real
number division, and then the latter's result is rounded to the same or
nearest integer.  The semantics of this function preserve the identity
C<x mod y = x - y * (x div y)> (read C<x> as C<dividend> and C<y>
as C<divisor>) where the division has the same semantics as
C<sys.std.Core.Integer.whole_quotient> (rounding guided by C<round_meth>);
the sign of this function's result always matches the sign of the dividend
or the divisor if C<round_meth> is C<ToZero> (aka I<truncate>) or C<Down>
(aka I<floor>), respectively.  This function will fail if C<divisor> is
zero.

=head2 sys.std.Core.Integer.quot_and_rem

C<< function quot_and_rem (Tuple <--
dividend : Int, divisor : Int, round_meth : RoundMeth)
implements sys.std.Core.Numeric.quot_and_rem {...} >>

This function results in a binary tuple whose attribute names are
C<quotient> and C<remainder> and whose respective attribute values are what
C<sys.std.Core.Integer.whole_quotient> and
C<sys.std.Core.Integer.remainder> would result in when given the same
arguments.  This function will fail if C<divisor> is zero.

=head2 sys.std.Core.Integer.range

C<< function range (Int <-- topic : set_of.Int)
implements sys.std.Core.Numeric.range {...} >>

This function results in the difference between the lowest and highest
element values of its argument.  If C<topic> has zero values, then
this function will fail.

=head2 sys.std.Core.Integer.frac_mean

C<< function frac_mean (Rat <-- topic : bag_of.Int)
implements sys.std.Core.Numeric.frac_mean {...} >>

This function results in the rational 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
using the semantics of real number division.  If C<topic> has zero values,
then this function will fail.

=head2 sys.std.Core.Integer.median

C<< function median (set_of.Int <-- topic : bag_of.Int)
implements sys.std.Core.Numeric.median {...} >>

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.Integer.frac_mean_of_median

C<< function frac_mean_of_median (Rat <-- topic : bag_of.Int)
implements sys.std.Core.Numeric.frac_mean_of_median {...} >>

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

=head2 sys.std.Core.Integer.mode

C<< function mode (set_of.Int <-- topic : bag_of.Int)
implements sys.std.Core.Numeric.mode {...} >>

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.Integer.power_with_whole_exp

C<< function power_with_whole_exp (Rat <--
radix : Int, exponent : Int)
implements sys.std.Core.Numeric.power_with_whole_exp {...} >>

This function results in a rational number that is the result of its
C<radix> argument taken to the power of its integer C<exponent> argument.
This function will result in 1 if C<radix> and C<exponent> are both zero
(rather than failing).

=head1 FUNCTIONS FOR INTEGER MATH

These functions implement commonly used integer numeric operations.

=head2 sys.std.Core.Integer.whole_mean

C<< function whole_mean (Int <-- topic : bag_of.Int,
round_meth : RoundMeth) {...} >>

This function results in the integer 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, where the semantics of the division are the same as those of
C<sys.std.Core.Integer.whole_quotient> (rounding the result of a real
number division as per C<round_meth>).  If C<topic> has zero values, then
this function will fail.

=head2 sys.std.Core.Integer.whole_mean_of_median

C<< function whole_mean_of_median (Int <--
topic : bag_of.Int, round_meth : RoundMeth) {...} >>

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

=head2 sys.std.Core.Integer.power

C<< function power (Int <-- radix : Int, exponent : NNInt) {...} >>

This function results in its C<radix> argument taken to the power of its
(non-negative integer) C<exponent> argument.  This function will result in
1 if C<radix> and C<exponent> are both zero (rather than failing), which
seems reasonable given that the C<Integer.power> function strictly has no
numeric continuity (unlike C<Rational.power>) and that this is by far the
most common practice in both pure integer math contexts and computer
languages, including SQL.  Note that this operation is also known as
I<exponentiation> or C<exp>.

=head2 sys.std.Core.Integer.factorial

C<< function factorial (PInt <-- 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).  Note that this operation is also known as
(postfix) C<!>.

=head1 UPDATERS IMPLEMENTING VIRTUAL ORDINAL FUNCTIONS

=head2 sys.std.Core.Integer.assign_pred

C<updater assign_pred (&topic : Int)
implements sys.std.Core.Ordered.Ordinal.assign_pred {...}>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Integer.pred> function with the same argument, and
then assigning the result of that function to its argument.

=head2 sys.std.Core.Integer.assign_succ

C<updater assign_succ (&topic : Int)
implements sys.std.Core.Ordered.Ordinal.assign_succ {...}>

This update operator is a short-hand for first invoking the
C<sys.std.Core.Integer.succ> function with the same argument, and
then assigning the result of that function to its argument.

=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.Integer.fetch_random

C<system-service fetch_random (&target : Int,
interval : sp_interval_of.Int) [...]>

This system-service routine will update the variable supplied as its
C<target> argument so that it holds a randomly generated integer value that
is included within the interval defined by its C<interval> argument.  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-2011, 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