=pod

=encoding utf8

=head1 NAME

Muldis::D::Ext::Integer -
Muldis D extension for integer data types and operators

=head1 VERSION

This document is Muldis::D::Ext::Integer version 0.26.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.

=head1 DESCRIPTION

Muldis D has a mandatory core set of system-defined (eternally available)
entities, which is referred to as the I<Muldis D core> or the I<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 I<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 C<Integer> document describes the system-defined I<Muldis D
Integer Extension>, which consists of integer 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 L<Muldis::D::Core>.

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 (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.Int
                sys.std.Core.Type.UInt
                    sys.std.Core.Type.PInt

                        # These are all finite integer types.

                        sys.std.Integer.Type.PInt2_36

I<This documentation is pending.>

=head1 SYSTEM-DEFINED INTEGER-CONCERNING DATA TYPES

=head2 sys.std.Integer.Type.PInt2_36

A C<PInt2_36> is a proper subtype of C<PInt2_N> where all member
values are between 2 and 36.  (The significance of the number 36 is 10
digits plus 26 letters.)  Its maximum value is 36.  The cardinality of this
type is 35.

=head1 FUNCTIONS FOR INTEGER MATH

These functions implement commonly used integer numeric operations.

=over

=item C<function sys.std.Integer.increment result Int params { topic(Int)
}>

This function results in its argument incremented by 1.

=item C<function sys.std.Integer.decrement result Int params { topic(Int)
}>

This function results in its argument decremented by 1.

=item C<function sys.std.Integer.abs result UInt params { topic(Int) }>

This function results in the absolute value of its argument.

=item C<function sys.std.Integer.sum result Int params {
addends(bag_of.Int) }>

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<addends> has zero values, then
C<sum> results in the integer zero, which is the identity value for
addition.

=item C<function sys.std.Integer.difference result Int params {
minuend(Int), subtrahend(Int) }>

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

=item C<function sys.std.Integer.product result Int params {
factors(bag_of.Int) }>

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<factors>
has zero values, then C<product> results in the integer 1, which is the
identity value for multiplication.

=item C<function sys.std.Integer.quotient result Int params {
dividend(Int), divisor(Int) }>

This function results in the quotient when its C<dividend> argument is
divided by its C<divisor> argument using integer division.  This function
will fail if C<divisor> is zero.

=item C<function sys.std.Integer.remainder result UInt params {
dividend(Int), divisor(Int) }>

This function results in the remainder when its C<dividend> argument is
divided by its C<divisor> argument using integer division.  This function
will fail if C<divisor> is zero.

=item C<function sys.std.Integer.maybe_quotient result maybe_of.Int params
{ dividend(Int), divisor(Int) }>

This function is exactly the same as C<sys.std.Integer.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.

=item C<function sys.std.Integer.maybe_remainder result maybe_of.UInt
params { dividend(Int), divisor(Int) }>

This function is exactly the same as C<sys.std.Integer.remainder> 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.

=item C<function sys.std.Integer.range result Int params {
topic(set_of.Int) }>

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

=item C<function sys.std.Integer.median result set_of.Int params {
topic(bag_of.Int) }>

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.

=item C<function sys.std.Integer.mode result set_of.Int params {
topic(bag_of.Int) }>

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.

=item C<function sys.std.Integer.power result Int params { radix(Int),
exponent(UInt) }>

This function results in its C<radix> argument taken to the power of its
(unsigned integer) C<exponent> argument.  This function will fail if
C<radix> and C<exponent> are both zero.

=item C<function sys.std.Integer.factorial result PInt params { topic(UInt)
}>

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

=back

=head1 FUNCTIONS FOR INTEGER CONVERSION WITH TEXT

These functions convert between C<Int> values and canonically formatted
representations of integers as character strings.

=over

=item C<function sys.std.Integer.Int_from_Text result Int params {
text(Text), radix(PInt2_36) }>

This selector function results in the C<Int> value that its (not-empty)
C<text> argument maps to when the whole character string is evaluated as a
base-C<radix> integer.  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 C<text> can't be mapped as specified.

=item C<function sys.std.Integer.Text_from_Int result Text params {
int(Int), radix(PInt2_36) }>

This selector function results in the (not-empty) C<Text> value where its
C<int> argument is formatted as a base-C<radix> integer.

=back

=head1 FUNCTIONS FOR INTEGER CONVERSION WITH BLOB

These functions convert between C<Int> values and canonically formatted
representations of integers as binary strings.  I<Conjecture: These may not
actually be useful, and perhaps only operators that take an argument
specifying a fixed-length field size, with big and little endian versions,
would be appropriate instead.  Or maybe both kinds are necessary.>

=over

=item C<function sys.std.Integer.Int_from_Blob_S_VBE result Int params {
blob(Blob) }>

This selector function results in the C<Int> value that its C<blob>
argument maps to when the whole bit string is treated literally as a
variable-length binary (two's complement) signed integer of 1 or more bits
in length.  The first bit is taken as the sign bit, and any other bits
provide greater precision than the -1 thru 0 range.  The bit string is
assumed to be big-endian, since it may not be possible to use little-endian
in situations where the bit length isn't a multiple of 8.

=item C<function sys.std.Integer.Blob_S_VBE_from_Int result Blob params {
int(Int) }>

This selector function results in the C<Blob> value where its C<int>
argument is formatted as a variable-length binary (two's complement) signed
integer of 1 or more bits in length; the smallest number of bits necessary
to store C<int> is used.

=item C<function sys.std.Integer.Int_from_Blob_U_VBE result UInt params {
blob(Blob) }>

This function is the same as C<sys.std.Integer.Int_from_Blob_S_VBE> but
that it does unsigned integers.

=item C<function sys.std.Integer.Blob_U_VBE_from_Int result UInt params {
blob(Blob) }>

This function is the same as C<sys.std.Integer.Blob_S_VBE_from_Int> but
that it does unsigned integers.

=back

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

=over

=item C<system_service sys.std.Integer.fetch_random update { target(Int) }
read { min(Int), max(Int), exclude_min(Bool)?, exclude_max(Bool)? }>

This system service routine will update the variable supplied as its
C<target> argument so that it holds a randomly generated integer value in
the range whose bounds are defined by its C<min> and C<max> arguments.  If
C<exclude_min> or C<exclude_max> are C<Bool:true>, then the randomly
generated value will not be equal to C<min> or C<max>, respectively;
otherwise, the generated value might be equal to C<min> or C<max>.  This
function will fail if C<max> is before C<min>.  Each of the
C<exclude_m(in|ax)> parameters is optional and defaults to C<Bool:false> if
no explicit argument is given to it.

=back

=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<perl@DarrenDuncan.net>)

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