.. zsh-module-meta::
   :name: zsh/mathfunc
   :summary: Standard scientific functions for use in mathematical evaluations.

.. index:: single: functions, mathematical; Command

.. index:: single: mathematical functions; Command

The ``zsh/mathfunc`` module provides standard
mathematical functions for use when
evaluating mathematical formulae.  The syntax agrees with normal C and
FORTRAN conventions, for example,

.. code-block:: zsh
   :class: example

    (( f = sin(0.3) ))

assigns the sine of 0.3 to the parameter f.

Most functions take floating point arguments and return a floating point
value.  However, any necessary conversions from or to integer type will be
performed automatically by the shell.  Apart from ``atan`` with a second
argument and the ``abs``, ``int`` and ``float`` functions, all functions
behave as noted in the manual page for the corresponding C function,
except that any arguments out of range for the function in question will be
detected by the shell and an error reported.

The following functions take a single floating point argument: ``acos``,
``acosh``, ``asin``, ``asinh``, ``atan``, ``atanh``, ``cbrt``, ``ceil``,
``cos``, ``cosh``, ``erf``, ``erfc``, ``exp``, ``expm1``, ``fabs``,
``floor``, ``gamma``, ``j0``, ``j1``, ``lgamma``, ``log``, ``log10``,
``log1p``, ``log2``, ``logb``, ``sin``, ``sinh``, ``sqrt``, ``tan``,
``tanh``, ``y0``, ``y1``.  The ``atan`` function can optionally take a
second argument, in which case it behaves like the C function ``atan2``.
The ``ilogb``, ``isinf``, and ``isnan`` functions take a single floating
point argument, but return an integer.

The function ``signgam`` takes no arguments, and returns an integer, which
is the C variable of the same name, as described in :manpage:`gamma(3)`.  Note
that it is therefore only useful immediately after a call to ``gamma`` or
``lgamma``.  Note also that ``signgam()`` and ``signgam`` are
distinct expressions.

The functions ``min``, ``max``, and ``sum`` are defined not in this module
but in the ``zmathfunc`` autoloadable function, described in
:zshsectref:`Mathematical Functions <zshcontrib>`.

The following functions take two floating point arguments: ``copysign``,
``fmod``, ``hypot``, ``nextafter``.

The following take an integer first argument and a floating point second
argument: ``jn``, ``yn``.

The following take a floating point first argument and an integer second
argument: ``ldexp``, ``scalb``.

The function ``abs`` does not convert the type of its single argument; it
returns the absolute value of either a floating point number or an
integer.  The functions ``float`` and ``int`` convert their arguments into
a floating point or integer value (by truncation) respectively.

Note that the C ``pow`` function is available in ordinary math evaluation
as the ``**`` operator and is not provided here.

The function ``rand48`` is available if your system's mathematical library
has the function ``erand48(3)``.  It returns a pseudo-random floating point
number between 0 and 1.  It takes a single string optional argument.

If the argument is not present, the random number seed is initialised by
three calls to the ``rand(3)`` function --- this produces the
same random
numbers as the next three values of ``$RANDOM``.

If the argument is present, it gives the name of a scalar parameter where
the current random number seed will be stored.  On the first call, the
value must contain at least twelve hexadecimal digits (the remainder of the
string is ignored), or the seed will be initialised in the same manner as
for a call to ``rand48`` with no argument.  Subsequent calls to
``rand48``\(:var:`param`) will then maintain the seed in the
parameter :var:`param` as a string of twelve hexadecimal digits, with no base
signifier.  The random number sequences for different parameters are
completely independent, and are also independent from that used by calls to
``rand48`` with no argument.

For example, consider

.. code-block:: zsh
   :class: example

    print $(( rand48(seed) ))
    print $(( rand48() ))
    print $(( rand48(seed) ))

Assuming ``$seed`` does not exist, it will be initialised by the first
call.  In the second call, the default seed is initialised; note, however,
that because of the properties of ``rand()`` there is a
correlation between
the seeds used for the two initialisations, so for more secure uses, you
should generate your own 12-byte seed.  The third call returns to the same
sequence of random numbers used in the first call, unaffected by the
intervening ``rand48()``.
