=encoding utf8

=head1 Title

Math::Basic API reference

=head1 Typical Usage

use Math::Basic

=head2 Tags

The following export tags are available:

 :UNI
 :compat
 :constants

=head2 Constants

To export the constants provided by C<Math::Basic> use the C<:constants>
tag when importing:

 use Math::Basic :constants;

=over

=item e

 constant Num Math::Basic::e

The constant C<e>, roughly equal to C<2.71828182845905>.

=item euler_constant

 constant Num Math::Basic::γ
 constant Num Math::Basic::euler_constant

The Euler constant (or Euler-Mascheroni constant or simply γ), roughly
equal to C<0.57721566490153286>. This constant should not be confused
with C<e>.

=item golden_ratio

 constant Num Math::Basic::φ
 constant Num Math::Basic::phi
 constant Num Math::Basic::golden_ratio

The golden ratio, roughly equal to C<1.6180339887498948>.

=item i

 constant Complex Math::Basic::i

The constant C<i>, which is defined as the square root of C<-1>.

=item one

 constant Complex Math::Basic::one

The constant value C<1>.

=item pi

 constant Num Math::Basic::π
 constant Num Math::Basic::pi

The constant C<pi>, roughly equal to C<3.14159265358979>.

=item zero

 constant Complex Math::Basic::zero

The constant value C<0>.

=back

=head2 Exported functions

The following functions are exported by default:

=over

=item abs

 our Num multi Math::Basic::abs ( Num $x )
 our Int multi Math::Basic::abs ( Int $x )
 our Complex multi Math::Basic::abs ( Complex $x )

The absolute value or modulus of C<$x>, as denoted in mathematics
by C<|x|>.

The absolute value of a complex number is a generalization of this
basic operation.

=item ceil

=item ceiling

 our Int multi Math::Basic::ceiling ( Num $x )
 our Complex multi Math::Basic::ceiling ( Complex $x )
 our Int multi Math::Basic::ceil ( Num $x )
 our Complex multi Math::Basic::ceil ( Complex $x )

The ceiling of a real number, C<$x>, is defined as the smallest
integer which is not less than C<$x>.

In the case of complex numbers, TODO.

=item floor

 our Int multi Math::Basic::floor ( Num $x )
 our Complex multi Math::Basic::floor ( Complex $x )

The floor of a real number, C<$x>, is defined as the largest
integer which is not greater than C<$x>.

In the case of complex numbers, TODO.

=item round

 our int enum Math::Basic::Dir <<RoundUp RoundDown RoundPositive RoundNegative RoundEven RoundOdd RoundRandom>>;
 our Int multi Math::Basic::round ( Num $x, Math::Basic::Dir :$dir = RoundUp )
 our Complex multi Math::Basic::round ( Complex $x, Math::Basic::Dir :$dir = RoundUp)

A number, when rounded, is equal to the nearest whole number. If the number
falls exactly between two whole numbers, then the one which matches
the direction described by C<:dir> is returned (by default the number with the larger
absolute value is returned). The rounding modes that C<:dir> can describe are:

 RoundUp       - The default. Toward the larger absolute value.
 RoundUown     - Toward the smaller absolute value.
 RoundPositive - Toward positive infinity.
 RoundNegative - Toward negative infinity.
 RoundEven     - Toward the even of the two nearest.
 RoundOdd      - Toward the odd of the two nearest.
 RoundRandom   - Select one of the nearest randomly.

Here is an example of the usage:

 my $n = 0.5;
 my $n_rounded = round :dir(RoundEven), $n;

For complex numbers, round has the following behavior: TODO

=item int

=item truncate

 our Int multi Math::Basic::int ( Num $x )
 our Int multi Math::Basic::int ( Num $x )
 our Complex multi Math::Basic::truncate ( Complex $x )
 our Complex multi Math::Basic::truncate ( Complex $x )

Truncation returns the whole-number portion of a real number. Another
way to define this operation is that, of the whole numbers closest to
C<$x>, the one closest to zero is returned.

For complex numbers, C<truncate> has the following behavior: TODO

=item exp

 our Num multi Math::Basic::exp ( Num $exponent, Num :$base = Num::e )

=item log

=item log10

 our Num multi Math::Basic::log ( Num $x, Num :$base )
 our Num multi Math::Basic::log10 (Num $x);

=item rand

 our Num multi Math::Basic::rand ( Num $x = 1 )

=item sign

 our Int multi Math::Basic::sign ( Num $x )

=item srand

 our multi Math::Basic::srand ( Num $seed = default_seed_algorithm())

=item sqrt

=item √

 our Num multi Math::Basic::sqrt ( Num $x )
 our Num multi prefix:Math::Basic::<√> ( Num $x )

√ is only exported with the C<:UNI> tag.

=head2 Methods

These functions are also provided as methods, which you can
call on the basic numeric types:

=over

=item Num

Provides: abs, floor, ceiling, ceil, round, truncate, int, exp, log, log10,
rand, sign, and sqrt.

Example:

 my Num $n = 3.141;
 say "Square root of $n is {$n.sqrt}";

=item Int

Provides: abs, exp, log, log10, rand, sign, and sqrt.

Example:

 my Int $i = 2;
 say "log base 10 of $i = {$i.log10}";

=item Complex

Provides: abs, floor, ceiling, ceil, round, truncate, int, exp, log, log10,
rand, sign, and sqrt.

Exmple:

 my Complex $c = (2,10.3);
 say "Floor of complex number $c is: {$c.floor}";

=back

=cut