## The math package

The math package piggybacks on libc for basic mathematical operations with standard integer and floating point types.

## math

By simply importing `math`

, a most of the math functions from libc will get
imported.

Often, math operations are available both in function form and in method form. The function form would be similar to C, e.g.:

`sin(2 * PI)`

Whereas the method form would be more.. object-oriented-ish:

`2 pow(16)`

### Powers and roots

`pow`

elevates the first argument to the power of the second:

`2 pow(8) // 256`

`exp`

returns the value of e (the base of natural logarithms) raised to the
power of x:

`exp(2) // approx. 7.389`

`sqrt`

returns the square root of a number:

`144 sqrt() // 12`

`cbrt`

returns the cube root of a number:

`8 cbrt() // 2`

### Trigonometry

`PI`

is a constant defined in math as:

`PI := 3.14159_26535_89793_23846_26433_83279`

`sin`

, `cos`

, and `tan`

, are available, both in method and function form:

```
sin(2 * PI) // 0
cos(- (3 / 4) * PI) // -0.707, etc.
tan(PI / 4) // 1
```

As are their arc equivalents, `asin`

, `acos`

, `atan`

, their hyperbolic
variants, `sinh`

, `cosh`

, `tanh`

, and their arc hyperbolic tandems,
`asinh`

, `acosh`

, `atanh`

.

As for `atan2`

, straight from Wikipedia:

```
In a variety of computer languages, the function atan2 is the arctangent
function with two arguments. The purpose of using two arguments instead of
one, is to gather information of the signs of the inputs in order to return
the appropriate quadrant of the computed angle, which is not possible for
the single-argument arctangent function.
For any real number (e.g., floating point) arguments x and y not both equal
to zero, atan2(y, x) is the angle in radians between the positive x-axis of
a plane and the point given by the coordinates (x, y) on it. The angle is
positive for counter-clockwise angles (upper half-plane, y > 0), and
negative for clockwise angles (lower half-plane, y < 0).
```

Source: http://en.wikipedia.org/wiki/Atan2

### Logarithms

The `log`

function returns the natural logarithm of x:

`log(2) // about 0.69`

The `log10`

function returns the base 10 logarithm of x:

`log10(4000) // about 3.6`

### Rounding and truncation

The `round`

, `roundLong`

and `roundLLong`

are methods that will round to the
nearest integer:

```
3.14 round() // 3.00
4.78 roundLong() // 5
0.92 roundLLong() // 1
```

The `ceil`

and `floor`

methods will round to the nearest upper and lower
integer, respectively:

```
3.14 ceil() // 4.00
8.92 floor() // 8.00
```

### Floating-point remainder

The `mod`

function computes the floating-point remainder of dividing x by y.
The return value is x - n * y, where n is the quotient of x / y, rounded toward
zero to an integer.

```
12 mod(5) // 2
```

### Various

To get the absolute value of a number, use `abs()`

:

`(-4) abs() // 4`

## Random

By importing `math/Random`

, one can generate random numbers.

**Disclaimer: neither the libc random number generator or the fast prng
exposed by math/Random are suitable for cryptographic usage. Find a library
that does it right, this was not planned for it.**

When the module is loaded (probably at program start-up), the libc random number generator will be seeded with the current time in microseconds.

Then, various functions can be used to get random numbers.

### libc generator

To get any number between `INT_MIN`

and `INT_MAX`

, call:

`number := Random random()`

To get any number within a range, use either:

```
// gives a number between 0 (included) and 10 (included)
number := Random randInt(0, 10)
// gives a number between 0 (included) and 9 (included)
number = Random randRange(0, 10)
```

Those both have variants to get a number in a range, excluding any number already contained in a list:

```
// get 10 unique numbers between 0 and 100
list := ArrayList<Int> new()
10 times(||
list add(Random randInt(0, 100, list))
)
```

To pick out a random element ouf ot a list, use `choice`

:

```
// get one of those 10 unique numbers we just generated:
num := Random choice(list)
```

Note that `choice`

is generic, so it will work with lists of any
type of element.

### fast prng

Most of the methods above have a `fast`

variant, working from a PRNG (pseudorandom
number generator) coded directly into the Random class.

```
// all these are documented above, they work in a similar fashion
Random fastRandom()
Random fastRandInt(0, 10)
Random fastRandRange(0, 10)
Random fastRandInt(0, 10, list)
Random fastRandRange(0, 10, list)
Random fastChoice(list)
```

The `fast`

variants are meant to be faster, as the name implies, but they’re even
less guaranteed to have good random qualities - the numbers it generates might be
less even / repeat more easily.