NAME

math.ops - Mathematical Opcodes

DESCRIPTION

Parrot's library of mathematical ops.

To use this library of ops, add this directive to your PIR:

 .loadlib 'math_ops'

General Math

cmod(out INT, in INT, in INT)

cmod(invar PMC, invar PMC, in INT)

cmod(invar PMC, invar PMC, invar PMC)

NOTE: This "uncorrected mod" algorithm uses the C language's built-in mod operator (x % y), which is

    ... the remainder when x is divided by y, and thus is zero
    when y divides x exactly.
    ...
    The direction of truncation for / and the sign of the result
    for % are machine-dependent for negative operands, as is the
    action taken on overflow or underflow.
                                                     -- [1], page 41

Also:

    ... if the second operand is 0, the result is undefined.
    Otherwise, it is always true that (a/b)*b + a%b is equal to z. If
    both operands are non-negative, then the remainder is non-
    negative and smaller than the divisor; if not, it is guaranteed
    only that the absolute value of the remainder is smaller than
    the absolute value of the divisor.
                                                     -- [1], page 205

This op is provided for those who need it (such as speed-sensitive applications with heavy use of mod, but using it only with positive arguments), but a more mathematically useful mod based on ** floor(x/y) and defined with y == 0 is provided by the mod op.

  [1] Brian W. Kernighan and Dennis M. Ritchie, *The C Programming
      Language*, Second Edition. Prentice Hall, 1988.

If the denominator is zero, a 'Divide by zero' exception is thrown.If the denominator is inf or nan, a wrong integer will be returned.

cmod(out NUM, in NUM, in NUM)

cmod(invar PMC, invar PMC, in NUM)

NOTE: This "uncorrected mod" algorithm uses the built-in C math library's fmod() function, which computes

    ... the remainder of dividing x by y. The return value is
    x - n * y, where n is the quotient of x / y, rounded towards
    zero to an integer.
                                -- fmod() manpage on RedHat Linux 7.0

In addition, fmod() returns

    the remainder, unless y is zero, when the function fails and
    errno is set.

According to page 251 of [1], the result when y is zero is implementation- defined.This op is provided for those who need it, but a more mathematically useful numeric mod based on floor(x/y) instead of truncate(x/y) and defined with y == 0 is provided by the mod op.

  [1] Brian W. Kernighan and Dennis M. Ritchie, *The C Programming
      Language*, Second Edition. Prentice Hall, 1988.

If the denominator is zero, a 'Divide by zero' exception is thrown.If the denominator is inf or nan, the denominator will be returned as String.

Pseudorandom number operations

These operations perform various pseudorandom number operations.

rand(out NUM)

Set $1 to a random floating point number between 0 and 1, inclusive.

rand(out INT)

Set $1 to a random integer between [-2^31, 2^31) .

rand(out NUM, in NUM)

Set $1 to a random floating point number between 0 and $2, inclusive.

rand(out INT, in INT)

Set $1 to a integer between 0 and $2, inclusive.

rand(out NUM, in NUM, in NUM)

Set $1 to a random floating point number between $2 and $3, inclusive.

srand(in NUM)

Set the random number seed to $1. $1 is casted to an INTVAL.

srand(in INT)

Set the random number seed to $1.

rand(out INT, in INT, in INT)

Set $1 to a integer between $2 and $3, inclusive.

COPYRIGHT

Copyright (C) 2001-2014, Parrot Foundation.

LICENSE

This program is free software. It is subject to the same license as the Parrot interpreter itself.