🗐 MATH for Euphoria 3.1.1


                 Version 1.10, January/22/2018, by Shian Lee.


                             1. Introduction


 This library provides math routines for any platform.

 Most of this library routines can be applied to individual atoms or to
 sequences of values. For more details see Euphoria 3.1.1 REFMAN.DOC, Part I -
 Core Language - Operations on Sequences.

 The accuracy of any calculation in this library is limited to 15 decimal
 digits. Euphoria atoms can have any integer or double-precision floating
 point value. They can range from approximately -1e300 (minus one times 10 to
 the power 300) to +1e300 with 15 decimal digits of accuracy.

 What's new in version 1.10:

 - Function math_eval() for evaluating a math expression (from matheval.e).


 Disclaimer
 ==========

 Use this library at your own risk. The author will not be responsible for
 any damage or data loss.

 This library is tested on FreeDOS 1.1 operating system. The code or the
 documentation might still contain errors or mistakes.


 In the descriptions below, to indicate what kind of object may be passed in
 and returned, the following prefixes are used:

 x     - a general object (atom or sequence)

 s     - a sequence

 a     - an atom

 i     - an integer

 fn    - an integer used as a file number

 st    - a string sequence, or single-character atom




                      2. Routines by Application Area


 Some of the routines which are listed below are not included in math.e, these
 are either builtin routines or routines which are included in misc.e or
 machine2.e.

 Details about routines which are labeled with <builtin> or <include misc.e>
 see in Euphoria 3.1.1 - LIBRARY.DOC. Details about routines which are labeled
 with <include machine2.e> see in MACHINE2.DOC.


 2.1 Math Constants
 ==================

 The following math constants are not documented in this manual, but here is
 their short description:

 MINF            - the negative infinity value -inf (-1E308 * 1000)

 PINF            - the positive infinity value inf (1E308 * 1000)

 E               - the base of the natural logarithm Euler (e) (2.71828...)

 PHI             - the golden ratio phi (1+sqrt(5))/2 (1.61803...)

 EULER_GAMMA     - the value Euler Gamma (0.57721...)

 HALFSQRT2       - the value sqrt(2)/2 (0.70710...)

 SQRT2           - the value sqrt(2) (1.41421...)

 SQRT3           - the value sqrt(3) (1.73205...)

 SQRT5           - the value sqrt(5) (2.23606...)

 SQRTE           - the value sqrt(E) (1.64872...)

 LN2             - the value ln(2) (log(2)) (0.69314...)

 LN10            - the value ln(10) (log(10)) (2.30258...)

 INVLN2          - the value 1/ln(2) (1/log(2)) (1.44269...)

 INVLN10         - the value 1/ln(10) (1/log(10)) (0.43429...)

 PI              - the value PI (3.14159...) <include misc.e>

 QUARTPI         - the value PI/4 (0.78539...)

 HALFPI          - the value PI/2 (1.57079...)

 TWOPI           - the value PI*2 (6.28318...)

 PISQR           - the value power(PI,2) (9.86960...)

 INVSQ2PI        - the value 1/sqrt(PI*2) (0.39894...)

 DEG_TO_RAD      - conversion factor degrees to radians PI/180 (0.01745...)

 RAD_TO_DEG      - conversion factor radians to degrees 180/PI (57.2957...)



 2.2 Comparisons
 ===============

 These routines can be applied to individual atoms or to sequences of values.

 sign            - return a value indicating the sign of a number, 0 is 0
                   <include machine2.e>

 psign           - return a value indicating the sign of a number, 0 is 1
                   <include machine2.e>

 nsign           - return a value indicating the sign of a number, 0 is -1
                   <include machine2.e>

 zsign           - return a value indicating the sign of a number, 0 is TRUE
                   <include machine2.e>

 comp            - return a value indicating equality of numbers

 comp_approx     - return a value indicating approximate equality of numbers

 is_int          - return true if a number is an integer

 is_even         - return true if a number is an even integer

 is_odd          - return true if a number is an odd integer

 is_prime        - return true if a number is a prime integer

 gcd             - return the greatest common divisor of two numbers

 lcm             - return the least common multiple of two numbers



 2.3 Accumulation
 ================

 These routines can only be applied to sequences of values.

 min             - return the minimum value in a sequence

 max             - return the maximum value in a sequence

 sum             - calculate the sum of a sequence <include machine2.e>

 product         - calculate the product of a sequence

 average         - calculate the average of a sequence



 2.4 Rounding and Remainders
 ===========================

 These routines can be applied to individual atoms or to sequences of values.

 floor           - round down to the nearest integer <builtin>

 ceil            - round up to the nearest integer

 round           - round down or up to the nearest integer

 round_to        - round down or up to some precision

 fix             - truncate the fractional part of a number <include machine2.e>
                   (round towards zero to the nearest integer)

 fixup           - round towards infinity to the nearest integer

 even            - round towards infinity to the next even integer

 odd             - round towards infinity to the next odd integer

 remainder       - calculate the remainder when a number is divided by another
                   <builtin>

 mod             - calculate the remainder when a number is divided by another,
                   using floored division (modulus division)

 frac            - return the fractional part of a number

 abs             - return the absolute value of a number <include machine2.e>



 2.5 Logarithms and Powers
 =========================

 These routines can be applied to individual atoms or to sequences of values.

 sqrt            - calculate the square root of an object <builtin>

 log             - calculate the natural logarithm <builtin>

 log10           - calculate the base 10 logarithm

 power           - calculate a number raised to a power <builtin>

 exp             - calculate E (Euler (e)) raised to a specified power

 fib             - calculate the nth Fibonacci Number



 2.6 Random Numbers
 ==================

 These routines can be applied to individual atoms or to sequences of values.

 rand            - generate random numbers <builtin>

 rand_range      - generate random integer from a specified inclusive range

 rnd             - generate random floating point number (> 0 and <= 1)



 2.7 Trigonometry
 ================

 These routines can be applied to individual atoms or to sequences of values.

 sin             - calculate the sine of an angle <builtin>

 cos             - calculate the cosine of an angle <builtin>

 tan             - calculate the tangent of an angle <builtin>

 csc             - calculate the cosecant of an angle

 sec             - calculate the secant of an angle

 cot             - calculate the cotangent of an angle

 arcsin          - calculate the angle with a given sine <include misc.e>

 arccos          - calculate the angle with a given cosine <include misc.e>

 arctan          - calculate the arctangent of a number <builtin>

 atan2           - calculate the arctangent of a ratio

 arccsc          - calculate the angle with a given cosecant

 arcsec          - calculate the angle with a given secant

 arccot          - calculate the angle with a given cotangent

 deg_to_rad      - convert an angle measured in degrees to an angle measured
                   in radians

 rad_to_deg      - convert an angle measured in radians to an angle measured
                   in degrees



 2.8 Hyperbolic Trigonometry
 ===========================

 These routines can be applied to individual atoms or to sequences of values.

 sinh            - calculate the hyperbolic sine of a number

 cosh            - calculate the hyperbolic cosine of a number

 tanh            - calculate the hyperbolic tangent of a number

 csch            - calculate the hyperbolic cosecant of a number

 sech            - calculate the hyperbolic secant of a number

 coth            - calculate the hyperbolic cotangent of a number

 arcsinh         - calculate the inverse hyperbolic sine of a number

 arccosh         - calculate the inverse hyperbolic cosine of a number

 arctanh         - calculate the inverse hyperbolic tangent of a number

 arccsch         - calculate the inverse hyperbolic cosecant of a number

 arcsech         - calculate the inverse hyperbolic secant of a number

 arccoth         - calculate the inverse hyperbolic cotangent of a number



 2.9 Misc
 ========

 math_eval       - evaluate a math expression

 serial_numbers  - return a sequence of serial numbers

 prime_range     - return a sequence of prime numbers by specified range

 prime_list      - return a list of prime numbers




                   3. Alphabetical Listing of all Routines



 --------------------------------<arccosh>-----------------------------------

 Syntax:      include math.e
              x2 = arccosh(x1)

 Description: Return the inverse hyperbolic cosine of x1.

 Comments:    The argument, x1, must be greater than or equal to 1.

              This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              s = arccosh({1, 1.5, 2})
              -- s is {0, 0.9624236501, 1.316957897}


 See Also:    cosh, arcsinh, arctanh, arcsech, Euphoria 3.1.1: arccos, cos


 ---------------------------------<arccot>-----------------------------------

 Syntax:      include math.e
              x2 = arccot(x1)

 Description: Return an angle with cotangent (cot) equal to x1.

 Comments:    The argument, x1, may have any value except 0.

              A value (radians) between 0 and +PI, excluded, will be returned.

              This function may be applied to an atom or to all elements of a
              sequence.

              arccot() is not as fast as arctan().

 Example:

              s = arccot({-1, 0.5, 0.9})
              -- s is {-0.7853981634, 1.107148718, 0.837981225}


 See Also:    cot, arcsec, arccsc, Euphoria 3.1.1: arcsin, arctan, tan


 --------------------------------<arccoth>-----------------------------------

 Syntax:      include math.e
              x2 = arccoth(x1)

 Description: Return the inverse hyperbolic cotangent of x1.

 Comments:    The argument, x1, must be less than -1 or greater than +1.

              This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              s = arccoth({1.1, -1.4, 1.9})
              -- s is {1.522261219, -0.8958797346, 0.5850356263}


 See Also:    coth, arccsch, arcsech, arcsinh, cot, Euphoria 3.1.1: arctan


 ---------------------------------<arccsc>-----------------------------------

 Syntax:      include math.e
              x2 = arccsc(x1)

 Description: Return an angle with cosecant (csc) equal to x1.

 Comments:    The argument, x1, must be less than or equal to -1, or greater
              than or equal to +1.

              A value (radians) between -PI/2 and +PI/2, but not zero, will be
              returned.

              This function may be applied to an atom or to all elements of a
              sequence.

              arccsc() is not as fast as arccot() or arctan().

 Example:

              s = arccsc({-1, 1, 1.2})
              -- s is {-1.570796327, 1.570796327, 0.9851107833}


 See Also:    csc, arcsec, arccot, Euphoria 3.1.1: arcsin, sin


 --------------------------------<arccsch>-----------------------------------

 Syntax:      include math.e
              x2 = arccsch(x1)

 Description: Return the inverse hyperbolic cosecant of x1.

 Comments:    The argument, x1, may have any value except 0.

              This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              s = arccsch({-1, 0.5, 1})
              -- s is {-0.881373587, 1.443635475, 0.881373587}


 See Also:    csch, arcsech, arccoth, csc, arcsinh, Euphoria 3.1.1: arcsin


 ---------------------------------<arcsec>-----------------------------------

 Syntax:      include math.e
              x2 = arcsec(x1)

 Description: Return an angle with secant (sec) equal to x1.

 Comments:    The argument, x1, must be less than or equal to -1, or greater
              than or equal to +1.

              A value between 0 and +PI (radians) will be returned.

              This function may be applied to an atom or to all elements of a
              sequence.

              arcsec() is not as fast as arccot() or arctan().

 Example:

              s = arcsec({-1, 1, 1.2})
              -- s is {{3.141592654, 0, 0.5856855435}}


 See Also:    sec, arccsc, arccot, Euphoria 3.1.1: cos, arccos


 --------------------------------<arcsech>-----------------------------------

 Syntax:      include math.e
              x2 = arcsech(x1)

 Description: Return the inverse hyperbolic secant of x1.

 Comments:    The argument, x1, must be greater than 0 and less than or equal
              to +1.

              This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              s = arcsech({0.1, 0.4, 1})
              -- s is {2.993222846, 1.566799237, 0}


 See Also:    sech, arccsch, arccoth, arccosh, sec, Euphoria 3.1.1: arccos


 ---------------------------------<arcsinh>----------------------------------

 Syntax:      include math.e
              x2 = arcsinh(x1)

 Description: Return the inverse hyperbolic sine of x1.

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              s = arcsinh({-1, 0, 1})
              -- s is {-0.881373587, 0, 0.881373587}


 See Also:    sinh, arccosh, arctanh, arccsch, Euphoria 3.1.1: arcsin, sin


 ---------------------------------<arctanh>----------------------------------

 Syntax:      include math.e
              x2 = arctanh(x1)

 Description: Return the inverse hyperbolic tangent of x1.

 Comments:    The argument, x1, must be in the range -1 to +1 excluded.

              This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              s = arctanh({-0.5, 0, 0.5})
              -- s is {-0.5493061443, 0, 0.5493061443}


 See Also:    tanh, arcsinh, arccosh, arccoth, Euphoria 3.1.1: arctan, tan


 ---------------------------------<atan2>------------------------------------

 Syntax:      include math.e
              x3 = atan2(x1, x2)

 Description: Return the arctangent after dividing x1 by x2.

 Comments:    A value (radians) between -PI and PI inclusive will be returned.

              atan2(x1, x2) is equal to arctan(x1 / x2) but it can handle zero
              denominator and is more accurate.

              The arguments to this function may be atoms or sequences. The
              rules for operations on sequences apply.

 Example 1:

              a = atan2(10.5, 3.1)
              -- a is 1.283713958


 Example 2:

              s = atan2(5, {0, 5, 0.9, -0.11})
              -- s is {1.570796327, 0.7853981634, 1.392703389, 1.592792778}


 See Also:    arccot, cot, rad_to_deg, arctanh, Euphoria 3.1.1: arctan, tan


 --------------------------------<average>-----------------------------------

 Syntax:      include math.e
              s2 = average(s1)

 Description: Return the average value of s1. s1 must be a sequence. An error
              will occur if s1 is an atom. s2 is a sequence of the form:

              {sum, count, average}

 Example 1:

              s = average({{1,2}, {3.5,4}, {5,6,{}}, 0})
              -- s is {21.5, 7, 3.071428571}
              -- i.e. {1 + 2 + 3.5 + 4 + 5 + 6 + 0, 7-numbers, 21.5 / 7}


 Example 2:

              s = average({})   -- s is {0, 0, 0}

              s = average({{0, {0}}})   -- s is {0, 2, 0}


 Example 3:

              s = average("12")
              -- s is {99, 2, 49.5}
              -- i.e. {ASCII-49 + ASCII-50, 2-numbers, 99 / 2}


 See Also:    product, sum, max


 ----------------------------------<ceil>------------------------------------

 Syntax:      include math.e
              x2 = ceil(x1)

 Description: Return the greatest integer more than or equal to x1. (Round up
              to an integer.)

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

              ceil() is the opposite of floor().

 Example:

              y = ceil({0.5, -0.5, 9.99, -9.7, 0})
              -- y is {1, 0, 10, -9, 0}


 See Also:    fixup, round, even, abs, frac, Euphoria 3.1.1: floor, remainder


 ----------------------------------<comp>------------------------------------

 Syntax:      include math.e
              x3 = comp(x1, x2)

 Description: Return 0 if x1 and x2 are equal, 1 if x1 is greater than x2, -1
              if x1 is less than x2. (i.e. compare between two numbers).

 Comments:    The arguments to this function may be atoms or sequences. The
              rules for operations on sequences apply.

 Example:

              x = comp({4.2, {-8.5}, 3}, {4, -8.5, 11})
              -- x is {1, {0}, -1}


 See Also:    comp_approx, is_int, sign, Euphoria 3.1.1: compare, equal


 ------------------------------<comp_approx>---------------------------------

 Syntax:      include math.e
              x4 = comp_approx(x1, x2, x3)

 Description: Return 0 if x1 and x2 are approximately equal, 1 if x1 is greater
              than x2, -1 if x1 is less than x2. x3 defines the amount of
              inequality allowed, it must be a positive number or 0. (i.e.
              compare approximately between two numbers).

 Comments:    The arguments to this function may be atoms or sequences. The
              rules for operations on sequences apply.

 Example 1:

              x = comp_approx(11, 10.995, 0.005)
              -- x is 0 -- i.e. 11 - 10.995 is 0.005 (approximately equal)


 Example 2:

              x = comp_approx({4, {-9.1}, 3}, {4.2, -8.5, 3.6}, 0.5)
              -- x is {0, {-1}, -1}
              -- i.e. {4, {-9.1}, 3} - {4.2, -8.5, 3.6} is {-0.2,{-0.6},-0.6}


 Example 3:

              x = comp_approx({4.6, {-9.1}}, {4, -8.5}, {0.5, 0.6})
              -- x is {1, {0}}
              -- i.e. {4.6, {-9.1}} - {4, -8.5} is {0.6,{-0.6}}


 See Also:    comp, Euphoria 3.1.1: compare, equal, relational operators


 -----------------------------------<cosh>-----------------------------------

 Syntax:      include math.e
              x2 = cosh(x1)

 Description: Return the hyperbolic cosine of x1.

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              s = cosh({.5, .6, .7})
              -- s is {1.127625965, 1.185465218, 1.255169006}


 See Also:    arccosh, sinh, tanh, sech, Euphoria 3.1.1: cos, arccos


 -----------------------------------<cot>------------------------------------

 Syntax:      include math.e
              x2 = cot(x1)

 Description: Return the cotangent of x1, where x1 is in radians.

 Comments:    The argument, x1, may have any value except 0 or a multiple of
              PI.

              This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              x = cot({.5, .9, .11})
              -- x is {1.830487722, 0.7935511478, 9.054212812}


 See Also:    csc, sec, arccot, coth, Euphoria 3.1.1: sin, cos, tan


 -----------------------------------<coth>-----------------------------------

 Syntax:      include math.e
              x2 = coth(x1)

 Description: Return the hyperbolic cotangent of x1.

 Comments:    The argument, x1, may have any value except 0.

              This function may be applied to an atom or to all elements of a
              sequence.

              coth(x) is the ratio (cosh(x) / sinh(x)).

 Example:

              s = coth({.5, .6, .7})
              -- s is {2.163953414, 1.862025521, 1.654621636}


 See Also:    arccoth, csch, sech, tanh, Euphoria 3.1.1: tan, arctan


 -----------------------------------<csc>------------------------------------

 Syntax:      include math.e
              x2 = csc(x1)

 Description: Return the cosecant of x1, where x1 is in radians.

 Comments:    The argument, x1, may have any value except 0 or a multiple of
              PI.

              This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              x = csc({.5, .9, .11})
              -- x is {2.085829643, 1.276606213, 9.109268338}


 See Also:    sec, cot, arccsc, deg_to_rad, Euphoria 3.1.1: sin, cos, tan


 ----------------------------------<csch>------------------------------------

 Syntax:      include math.e
              x2 = csch(x1)

 Description: Return the hyperbolic cosecant of x1.

 Comments:    The argument, x1, may have any value except 0.

              This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              s = csch({.5, .6, .7})
              -- s is {1.919034751, 1.570712909, 1.318246091}


 See Also:    arccsch, sech, coth, sinh, csc, Euphoria 3.1.1: sin, arcsin


 -------------------------------<deg_to_rad>---------------------------------

 Syntax:      include math.e
              x2 = deg_to_rad(x1)

 Description: Convert an angle x1 measured in degrees, to an angle measured in
              radians.

 Comments:    A value of x1 multiplied by (PI / 180) will be returned. (i.e.
              x1 * DEG_TO_RAD).

              This function may be applied to an atom or to all elements of a
              sequence.

              A flat angle is PI radians and 180 degrees.

              sin(), cos(), tan(), csc(), sec() and cot() expect angles in
              radians.

 Example 1:

              a = deg_to_rad(194)
              -- a is 3.385938749


 Example 2:

              s = deg_to_rad({180, 45, 90, 360})
              -- s is {3.141592654, 0.7853981634, 1.570796327, 6.283185307}
              -- i.e. s is {PI, QUARTPI, HALFPI, TWOPI}


 See Also:    rad_to_deg, csc, sec, cot, arccot, Euphoria 3.1.1: sin, cos, tan


 ----------------------------------<even>------------------------------------

 Syntax:      include math.e
              x2 = even(x1)

 Description: Round x1 towards infinity to the next even integer.

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              x = even({2.3, 2, 1, 0, -0.5, -1, -2.3})
              -- x is {4, 2, 2, 0, -2, -2, -4}


 See Also:    odd, fixup, ceil, round, abs, Euphoria 3.1.1: floor, remainder


 -----------------------------------<exp>------------------------------------

 Syntax:      include math.e
              x2 = exp(x1)

 Description: Return E raised to power x1. (x2 is the exponential of x1).

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

              The constant E is Euler (e). The base of the natural logarithm.

 Example:

              a = exp(5.4)
              -- a is 221.4064162


 See Also:    log10, Euphoria 3.1.1: log, power, sqrt, sin, cos, tan


 -----------------------------------<fib>------------------------------------

 Syntax:      include math.e
              x2 = fib(x1)

 Description: Return the Fibonacci Number specified by x1. x1 is an integer to
              compute a Fibonacci Number from.

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              a = fib(6)   -- a is 8

              s = fib({4, 9})   -- s is {3, 34}


 See Also:    gcd, prime_range, serial_numbers, Euphoria 3.1.1: sqrt, power


 ---------------------------------<fixup>------------------------------------

 Syntax:      include math.e
              x2 = fixup(x1)

 Description: Round x1 towards infinity to the nearest integer.

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

              fixup() is the opposite of fix() which rounds towards zero (see
              machine2.doc).

 Example:

              y = fixup({0.2, -0.2, 9.5, -7.5, 100, 0})
              -- y is {1, -1, 10, -8, 100, 0}


 See Also:    fix, even, ceil, round, frac, Euphoria 3.1.1: floor, remainder


 ----------------------------------<frac>------------------------------------

 Syntax:      include math.e
              x2 = frac(x1)

 Description: Return the fractional portion of x1. (Truncate the integer part).

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

              frac() does not round the number. i.e. x = fix(x) + frac(x).

 Example:

              y = frac({0.15, -1.675, 9.99, 100, 0})
              -- y is {0.15, -0.675, 0.99, 0, 0}


 See Also:    fix, mod, round_to, is_int, Euphoria 3.1.1: remainder, floor


 -----------------------------------<gcd>------------------------------------

 Syntax:      include math.e
              x3 = gcd(x1, x2)

 Description: Return the greatest common divisor (gcd) of x1 and x2. x3 will
              be a positive integer (greater than 0), the largest value that
              evenly divides x1 and x2.

 Comments:    The arguments to this function may be atoms or sequences. The
              rules for operations on sequences apply.

 Example:

              x = gcd({-3, 15, -18.5, 0, 16}, 9)
              -- x is {3, 3, 9, 9, 1}

              x = gcd(0, {-3, 15, -18.5, 0, 16})
              -- x is {3, 15, 18, 1, 16}

              x = gcd({{-9, 0}, {24}, -21.9}, {24, -10.5, {9, 0}})
              -- x is {{3, 24}, {2}, {3, 21}}


 See Also:    lcm, is_even, is_prime, sign, abs


 ---------------------------------<is_even>----------------------------------

 Syntax:      include math.e
              x2 = is_even(x1)

 Description: Return 1 (true) if x1 is an even integer number, else return 0
              (false).

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              y = is_even({-100, {-1.5, 9}, 0, 12, 28.2, 9991073741824})
              -- y is {1, {0, 0}, 1, 1, 0, 1}


 See Also:    is_odd, is_int, is_prime, comp, sign, serial_numbers


 ----------------------------------<is_int>----------------------------------

 Syntax:      include math.e
              x2 = is_int(x1)

 Description: Return 1 (true) if x1 is an integer number, return 0 (false) if
              x1 contains a fractional part.

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              y = is_int({-100, {-1.5, 9}, 0, 11.02, 4.2, 9991073741823})
              -- y is {1, {0, 1}, 1, 0, 0, 1}


 See Also:    is_even, is_odd, is_prime, comp, sign, gcd


 ----------------------------------<is_odd>----------------------------------

 Syntax:      include math.e
              x2 = is_odd(x1)

 Description: Return 1 (true) if x1 is an odd integer number, else return 0
              (false).

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              y = is_odd({-103, {-1.5, 9}, 0, 15, 27.2, 9991073741821})
              -- y is {1, {0, 1}, 0, 1, 0, 1}


 See Also:    is_even, is_int, is_prime, comp, sign, serial_numbers


 ---------------------------------<is_prime>---------------------------------

 Syntax:      include math.e
              x2 = is_prime(x1)

 Description: Return 1 (true) if x1 is a prime integer number, else return 0
              (false). x1 must be less than or equal to +999,999,999,999,999
              (which is 15 decimal digits of accuracy).

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

              Prime numbers are positive integers. Searching for prime numbers
              is normally slower then other math functions.

 Example:

              x = is_prime({2, 3, 1907377, 9, 11, {1621, 908491}, 17, {18}, 19})
              -- x is {1, 1, 1, 0, 1, {1, 1}, 1, {0}, 1}


 See Also:    is_int, is_odd, is_even, comp, prime_list, prime_range


 -----------------------------------<lcm>------------------------------------

 Syntax:      include math.e
              x3 = lcm(x1, x2)

 Description: Return the least common multiple (lcm) of x1 and x2. x3 will
              be a positive integer (greater than or equal to 0), the smallest
              value that is a common multiple of x1 and x2.

 Comments:    The arguments to this function may be atoms or sequences. The
              rules for operations on sequences apply.

 Example:

              x = lcm({-3, 15, -18.5, 0, 16}, 9)
              -- x is {9, 45, 18, 0, 144}

              x = lcm(0, {-3, 15, -18.5, 0, 16})
              -- x is {0, 0, 0, 0, 0}

              x = lcm({{-9, 0}, {24}, -21.9}, {24, -10.5, {9, 0}})
              -- x is {{72, 0}, {120}, {63, 0}}


 See Also:    gcd, is_even, is_int, product, serial_numbers


 ----------------------------------<log10>-----------------------------------

 Syntax:      include math.e
              x2 = log10(x1)

 Description: Return the base 10 logarithm of x1.

 Comments:    This function may be applied to an atom or to all elements of a
              sequence. Note that log10 is only defined for positive numbers.
              Your program will abort with a message if you try to take the
              log10 of a negative number or zero.

              log10() is proportional to log() by a factor of 1 / log(10),
              i.e. the constant INVLN10.

              Raising 10 to x1 yields x1 back, i.e. x = power(10, log10(x)).

 Example:

              s = log10({12, 100})
              -- s is {1.079181246, 2}


 See Also:    exp, arcsinh, Euphoria 3.1.1: log, sqrt, power, sin, cos, tan


 --------------------------------<math_eval>---------------------------------

 Syntax:      include matheval.e
              x = math_eval(st)

 Description: Evaluate the string representation of a Euphoria math expression
              and return the result. math_eval() will return a short error-
              message string if the syntax of the math expression is wrong or
              if an illegal argument is passed to a function.

 Comments:    Because either an atom (result) or a string-sequence (error-
              message) might be returned, you should probably assign the result
              to a variable declared as object.

              Euphoria 3.1 syntax is fully supported. All relational, logical
              and arithmetic operators are supported. Operations on sequences
              are *not* supported.

              In addition to Euphoria decimal and hexadecimal (#) numbers, you
              can also use binary, octal and hexadecimal numbers with the
              following prefixes (see also int() function for details):

                0b - binary number (base 2, digits 0-1), e.g. 0b00110
                0o - octal number (base 8, digits 0-7), e.g. 0o315
                0x - hexadecimal number (base 16, digits 0-9, A-F), e.g. 0xFF1

              The following functions are supported:

                floor, ceil, fix, frac, round, abs, sign, sqrt, log, power, exp,
                remainder, mod, rand, sin, cos, tan, sinh, cosh, tanh, arcsin,
                arccos, arctan, arcsinh, arccosh, arctanh, deg_to_rad,
                rad_to_deg.

              The following constants are supported:

                PI, E, PHI

 Example:

              x = math_eval("143.5")
              -- x is 143.5

              x = math_eval("19 / 0")
              -- x is "division by zero"

              x = math_eval("remainder(PI*9, 2)")
              -- x is 0.2743338823

              x = math_eval("31.5e-4 / 7 + sin(0.5)")
              -- x is 0.4798755386

              x = math_eval("3+2*(#A + 20)")
              -- x is 63

              x = math_eval("10/-floor(0b1111/2)+ (9 and 2)")
              -- x is -0.4285714286
              -- in Euphoria you can write it like this:
              -- 10/-floor(int("0b1111")/2)+ (9 and 2)


 Example Program: demo\meval.ex

 See Also:    Euphoria 3.1.1: value


 -----------------------------------<max>------------------------------------

 Syntax:      include math.e
              a = max(s)

 Description: Return the maximum value in s. s must be a sequence. An error
              will occur if s is an atom.

 Example 1:

              a = max({{1, 2}, {9.5, {4}}, {5, 6}})   -- a is 9.5


 Example 2:

              a = max({})   -- a is -inf (negative infinity)


 Example 3:

              a = max("12")   -- a is 50 -- i.e. '2' is ASCII-50


 See Also:    min, average, product, sum, serial_numbers, comp


 -----------------------------------<min>------------------------------------

 Syntax:      include math.e
              a = min(s)

 Description: Return the minimum value in s. s must be a sequence. An error
              will occur if s is an atom.

 Example 1:

              a = min({{1, 2}, {-9.5, {4}}, {5, 6}})   -- a is -9.5


 Example 2:

              a = min({})   -- a is inf (positive infinity)


 Example 3:

              a = min("12")   -- a is 49 -- i.e. '1' is ASCII-49


 See Also:    max, average, product, sum, serial_numbers, comp


 ----------------------------------<mod>-------------------------------------

 Syntax:      include math.e
              x3 = mod(x1, x2)

 Description: Compute the remainder after dividing x1 by x2, using floored
              division (modulus division). The result will have the same sign
              as x2.

 Comments:    The arguments to this function may be atoms or sequences. The
              rules for operations on sequences apply.

              Note that the mod function (modulo) is implemented differently
              among programming languages and calculators. To understand how
              mod() is calculated see the following example:

              floor( 9 /  4) =  2, remainder is  1; since  9 =  4 * 2 + 1
              floor(-9 /  4) = -3, remainder is  3; since -9 =  4 * (-3) + 3
              floor( 9 / -4) = -3, remainder is -3; since  9 = -4 * (-3) + (-3)
              floor(-9 / -4) =  2, remainder is -1; since -9 = -4 * 2 + (-1)

 Example 1:

              a = mod(9, 4)    -- a is 1

              a = mod(-9, 4)   -- a is 3

              a = mod(9, -4)   -- a is -3

              a = mod(-9, -4)  -- a is -1


 Example 2:

              s = mod({81, -3.5, -9, 5.5}, {8, -1.7, 2, -4})
              -- s is {1, -0.1, 1, -2.5}


 Example 3:

              s = mod({17, 12, 34}, 16)  -- s is {1, 12, 2}

              s = mod(16, {2, 3, 5})     -- s is {0, 1, 1}


 See Also:    frac, fixup, ceil, round, abs, Euphoria 3.1.1: remainder, floor


 -----------------------------------<odd>------------------------------------

 Syntax:      include math.e
              x2 = odd(x1)

 Description: Round x1 towards infinity to the next odd integer.

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              x = odd({3.3, 3, 2, 0, -2, -3, -3.3})
              -- x is {5, 3, 3, 1, -3, -3, -5}


 See Also:    even, fixup, ceil, round, Euphoria 3.1.1: floor, remainder


 -------------------------------<prime_list>---------------------------------

 Syntax:      include math.e
              s = prime_list(i)

 Description: Return a list (a string-sequence) of prime numbers from 0 to i.

 Comments:    prime_list() is useful for creating a list of prime numbers
              very fast. Yet if i is very large (e.g. above 1,000,000) your
              program may run out of memory and crash. For creating a list of
              large prime numbers you should use prime_range() instead.

              Searching for prime numbers is normally slower then other math
              functions.

 Example:

              s = prime_list(40)
              -- s is {2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37}

              s = prime_list(200000)
              -- s is {2, 3, 5, ..., 199931, 199933, 199961, 199967, 199999}


 See Also:    prime_range, is_prime, is_int, serial_numbers


 -------------------------------<prime_range>--------------------------------

 Syntax:      include math.e
              s = prime_range(x1, x2)

 Description: Return a sequence of prime numbers in the range x1 to x2. x2
              must be less than or equal to 999,999,999,999,999.

 Comments:    The arguments to this function may be atoms or sequences. The
              rules for operations on sequences apply.

              Searching for prime numbers is normally slower then other math
              functions, therefore it's not recommended to specify a very wide
              range for search.

 Example 1:

             s = prime_range(1, 50)
             -- s is {2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47}

             s = prime_range(5000, 5080)
             -- s is {5003, 5009, 5011, 5021, 5023, 5039, 5051, 5059, 5077}

             s = prime_range(999999900, 999999999)
             -- s is {999999929, 999999937}


 Example 2:

             s = prime_range({1, 100, 1000}, {10, 110, 1010})
             -- s is {{2, 3, 5, 7}, {101, 103, 107, 109}, {1009}}


 See Also:    prime_list, is_prime, serial_numbers


 --------------------------------<product>-----------------------------------

 Syntax:      include math.e
              a = product(s)

 Description: Return the product of s. s must be a sequence. An error will
              occur if s is an atom.

 Example 1:

              a = product({{1,2}, {3.5,4}, {5,6,{}}, {}})
              -- a is 840 -- i.e. 1 * 2 * 3.5 * 4 * 5 * 6


              a = product({{1,2}, {3.5,4}, {5,6,{}}, 0})
              -- a is 0 -- i.e. 1 * 2 * 3.5 * 4 * 5 * 6 * 0


 Example 2:

              a = product({})   -- a is 0


 Example 3:

              a = product("12")   -- a is 2450 -- i.e. ASCII-49 * ASCII-50


 See Also:    average, sum, max, min, lcm


 -------------------------------<rad_to_deg>---------------------------------

 Syntax:      include math.e
              x2 = rad_to_deg(x1)

 Description: Convert an angle x1 measured in radians, to an angle measured in
              degrees.

 Comments:    A value of x1 multiplied by (180 / PI) will be returned. (i.e.
              x1 * RAD_TO_DEG).

              This function may be applied to an atom or to all elements of a
              sequence.

              A flat angle is PI radians and 180 degrees.

              arcsin(), arccos(), arctan(), arccsc(), arcsec() and arccot()
              return angles in radians.

 Example 1:

              a = rad_to_deg(3.385938749)
              -- a is 194


 Example 2:

              s = rad_to_deg({PI, QUARTPI, HALFPI, TWOPI})
              -- s is {180, 45, 90, 360}


 See Also:    deg_to_rad, arccsc, arcsec, arccot, Euphoria 3.1.1: arctan


 -------------------------------<rand_range>---------------------------------

 Syntax:      include math.e
              x3 = rand_range(x1, x2)

 Description: Return a random integer from x1 to x2 inclusive, where x1 and x2
              may be from 1 to the largest positive value of type integer
              (1073741823).

 Comments:    The arguments to this function may be atoms or sequences. The
              rules for operations on sequences apply.

              rand_range() is not as fast as rand().

 Example:

              i = rand_range(1000, 2000)
              -- i might be: 1383, 1552, or 1797 etc.

              s = rand_range({50, 100, 400}, {60, 200, 410})
              -- s might be: {55, 156, 404} or {57, 162, 408} etc.


 See Also:    rnd, serial_numbers, Euphoria 3.1.1: rand, set_rand


 -----------------------------------<rnd>------------------------------------

 Syntax:      include math.e
              x2 = rnd(x1)

 Description: Return a random floating point number greater then 0 and less
              than or equal to 1, where x1 may be from 1 to the largest
              positive value of type integer (1073741823). A larger x1 result
              in higher resolution.

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

              rnd() is not as fast as rand().

 Example:

              x = rnd(2)
              -- x may only be 0.5 or 1


              x = rnd({10, 100, 10000})
              -- x may be {1, 0.01724137931, 0.0004140786749} or
              --          {0.125, 0.02777777778, 0.025} or
              --          {0.1111111111, 0.02941176471, 0.00119047619}, etc


 See Also:    rand_range, serial_numbers, Euphoria 3.1.1: rand, set_rand


 ----------------------------------<round>-----------------------------------

 Syntax:      include math.e
              x2 = round(x1)

 Description: Round x1 down or up to the nearest integer.

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

              When the fractional part of x1 is .5 this function rounds up,
              i.e. round(0.5) is 1 and round(-0.5) is 0.

              round(x1) is equivalent to round_to(x1, 0), but round() is
              faster.

 Example:

              y = round({0.5, -1.5, 3.1, -5.1, 4.7, -9.7, 100, 0})
              -- y is {1, -1, 3, -5, 5, -10, 100, 0}


 See Also:    round_to, ceil, fixup, even, odd, is_even, Euphoria 3.1.1: floor


 ---------------------------------<round_to>---------------------------------

 Syntax:      include math.e
              x3 = round_to(x1, x2)

 Description: Round x1 down or up to x2 decimal digits. x2 must be a positive
              value or 0 (i.e. 0, 1, 2, 3,...).

 Comments:    The arguments to this function may be atoms or sequences. The
              rules for operations on sequences apply.

              When the fractional part of x1 is .5 this function rounds up,
              i.e. round_to(0.5, 0) is 1 and round_to(-0.5, 0) is 0.

              When x2 is 0, i.e. round_to(x1, 0), this function is equivalent
              to round(x1), but round() is faster.

 Example:

              y = round_to({1.55, -1.55}, 1)
              -- y is {1.6, -1.5} -- i.e. round to 1 digit precision

              y = round_to(9.12645, {0, 1, 2, 3, 4})
              -- y is {9, 9.1, 9.13, 9.126, 9.1265}

              y = round_to(-9.12645, {0, 1, 2, 3, 4})
              -- y is {-9, -9.1, -9.13, -9.126, -9.1264}


 See Also:    round, fix, fixup, ceil, frac, Euphoria 3.1.1: floor, remainder


 -----------------------------------<sec>------------------------------------

 Syntax:      include math.e
              x2 = sec(x1)

 Description: Return the secant of x1, where x1 is in radians.

 Comments:    The argument, x1, may have any value except an odd multiple of
              PI/2 (i.e. PI/2, PI/2*3, PI/2*5, etc).

              This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              x = sec({.5, .9, .11})
              -- x is {1.139493927, 1.60872581, 1.006080653}


 See Also:    arcsec, csc, cot, sech, deg_to_rad, Euphoria 3.1.1: cos, tan


 ----------------------------------<sech>------------------------------------

 Syntax:      include math.e
              x2 = sech(x1)

 Description: Return the hyperbolic secant of x1.

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              s = sech({.5, .6, .7})
              -- s is {0.886818884, 0.8435506876, 0.79670546}


 See Also:    arcsech, csch, coth, cosh, sec, Euphoria 3.1.1: sin, cos, tan


 ------------------------------<serial_numbers>------------------------------

 Syntax:      include math.e
              s = serial_numbers(x1, x2, x3)

 Description: Return a sequence of serial numbers of length x2, start from
              number x1, using increment of x3.

 Comments:    The arguments to this function may be atoms or sequences. The
              rules for operations on sequences apply.

 Example 1:

              s = serial_numbers(0, 6, 1)
              -- s is {0, 1, 2, 3, 4, 5}


              s = serial_numbers(-5, 6, 2)
              -- s is {-5, -3, -1, 1, 3, 5}


              s = serial_numbers(-PI, 5, PI/2)
              -- s is {-3.141592654, -1.570796327, 0, 1.570796327, 3.141592654}


 Example 2:

              s = serial_numbers(1, 3, {0.2, 0.4, 0.6})
              -- s is {{1, 1.2, 1.4}, {1, 1.4, 1.8}, {1, 1.6, 2.2}}


              s = serial_numbers({0, 10, 100}, 3, -2)
              -- s is {{0, -2, -4}, {10, 8, 6}, {100, 98, 96}}


 See Also:    prime_range, prime_list, is_int, Euphoria 3.1.1: repeat


 ----------------------------------<sinh>------------------------------------

 Syntax:      include math.e
              x2 = sinh(x1)

 Description: Return the hyperbolic sine of x1.

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

 Example:

              s = sinh({.5, .6, .7})
              -- s is {0.5210953055, 0.6366535821, 0.7585837018}


 See Also:    arcsinh, cosh, tanh, csch, exp, Euphoria 3.1.1: sin, power


 ----------------------------------<tanh>------------------------------------

 Syntax:      include math.e
              x2 = tanh(x1)

 Description: Return the hyperbolic tangent of x1.

 Comments:    This function may be applied to an atom or to all elements of a
              sequence.

              tanh(x) is the ratio (sinh(x) / cosh(x)).

 Example:

              s = tanh({.5, .6, .7})
              -- s is {0.4621171573, 0.537049567, 0.6043677771}


 See Also:    arctanh, sinh, cosh, coth, exp, Euphoria 3.1.1: tan, power