= Math

== Numbers

The three numeric types in Nickle--int, rational, and real--have a hierarchical relationship.
Specifically, int is a subset of rational, which is a subset of real.
Ints and rationals are stored internally in infinite precision, and printed as precisely as possible (rationals with repeating portions are represented with curly braces to allow more precision in printing; see the section on Expressions for a discussion of rational constants). Reals are stored in finite, floating-point representations.
The mantissa defaults to 256 bits long, but this number can be changed. 

Whenever performing calculations, Nickle will keep numbers in their most specific format.
For example, the result of '4/2' is an int, because although the result (2) is a rational, it is also an int, and int is more specific.
Similarly, reals are not always in imprecise floating representation; if they are known exactly, they will be represented as rationals or ints.
Nickle will only produce imprecise reals when it has to, as in square roots and logarithms. 

== Operators

In order to do the Right Thing for a desk calculator, Nickle provides
several operators that are not present in C; these are extremely
useful.  To force division to produce an integer, even if the result
would be a rational, use the `//` integer divide operator, which
always rounds its results to ints.  Nickle also has an exponentiation
operator `+**+`, which behaves correctly for all exponents, including
negative and fractional.  Therefore, `sqrt(x)` is the same as `+x**.5+`, and
`1/x` is the same as `+x**-1+`.  Finally, it provides a factorial operator
`!`.

== The Math namespace

Nickle provides the builtin namespace Math for useful functions such as trigonometric functions, logarithms, as well as useful constants such as `pi` and ``e``. 

=== Logarithms

`real log ( real a )` +
`real log10 ( real a )` +
`real log2 ( real a )`

The logarithm of `a` in base e, ten, and two, respectively. 

----
> log ( Math::e )
1.000000000000000
> log10 ( 16 ) / log10 ( 4 )    /* change of base formula, log_4 16 */
1.999999999999999
> log2 ( 16 )
3.999999999999999
>
----

=== Trigonometric functions

`real sin ( real a )` +
`real cos ( real a )` +
`real tan ( real a )` +
`real asin ( real a )` +
`real acos ( real a )` +
`real atan ( real a )`

The sine, cosine, and tangent of `a`, and the inverse functions. 

----
> sin ( pi ) ** 2 + cos ( pi ) **2
1
> atan ( 1 ) * 4
3.141592653589793
>
----

=== Constants

`protected real e` +
`real pi`

`pi` and `e` define the usual constants (3.14..., 2.72...). `e` is
protected and must be called `Math::e` to allow ordinary use of the
name `e`.