OpenEuphoria: Euphoria v4.1

# OpenEuphoria Manual

## Euphoria v4.1

routine or constant name search

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.24 Base 64 Encoding and Decoding | Up: 8 API Reference | 8.26 Math Constants > | 9 Release Notes >>

## 8.25 Math

### 8.25.1 Sign and Comparisons

#### 8.25.1.1 abs

    include std/math.e
    namespace math
    public function abs(object a)

returns the absolute value of numbers.

##### Parameters:

1. `value` : an object, each atom is processed, no matter how deeply nested.

##### Returns:

An object, the same shape as `value`. When `value` is an atom, the result is the same if not less than zero, and the opposite value otherwise.

##### Comments:

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

##### Example 1:

    x = abs({10.5, -12, 3})
    -- x is {10.5, 12, 3}

    i = abs(-4)
    -- i is 4

##### See Also:

sign

#### 8.25.1.2 sign

    include std/math.e
    namespace math
    public function sign(object a)

returns -1, 0 or 1 for each element according to it being negative, zero or positive.

##### Parameters:

1. `value` : an object, each atom of which will be acted upon, no matter how deeply nested.

##### Returns:

An object, the same shape as `value`. When `value` is an atom, the result is -1 if `value` is less than zero, 1 if greater and 0 if equal.

##### Comments:

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

For an atom, `sign(x)` is the same as compare(x,0).

##### Example 1:

    i = sign(5)
    i is 1

    i = sign(0)
    -- i is 0

    i = sign(-2)
    -- i is -1

##### See Also:

compare

#### 8.25.1.3 larger_of

    include std/math.e
    namespace math
    public function larger_of(object objA, object objB)

returns the larger of two objects.

##### Parameters:

1. `objA` : an object.
2. `objB` : an object.

##### Returns:

Whichever of `objA` and `objB` is the larger one.

##### Comments:

Introduced in v4.0.3

##### Example 1:

    ? larger_of(10, 15.4) -- returns 15.4
    ? larger_of("cat", "dog") -- returns "dog"
    ? larger_of("apple", "apes") -- returns "apple"
    ? larger_of(10, 10) -- returns 10

##### See Also:

max, compare, smaller_of

#### 8.25.1.4 smaller_of

    include std/math.e
    namespace math
    public function smaller_of(object objA, object objB)

returns the smaller of two objects.

##### Parameters:

1. `objA` : an object.
2. `objB` : an object.

##### Returns:

Whichever of `objA` and `objB` is the smaller one.

##### Comments:

Introduced in v4.0.3

##### Example 1:

    ? smaller_of(10, 15.4) -- returns 10
    ? smaller_of("cat", "dog") -- returns "cat"
    ? smaller_of("apple", "apes") -- returns "apes"
    ? smaller_of(10, 10) -- returns 10

##### See Also:

min, compare, larger_of

#### 8.25.1.5 max

    include std/math.e
    namespace math
    public function max(object a)

computes the maximum value among all the argument's elements.

##### Parameters:

1. `values` : an object, all atoms of which will be inspected, no matter how deeply nested.

##### Returns:

An atom, the maximum of all atoms in flatten(`values`).

##### Comments:

This function may be applied to an atom or to a sequence of any shape.

##### Example 1:

    a = max({10,15.4,3})
    -- a is 15.4

##### See Also:

min, compare, flatten

#### 8.25.1.6 min

    include std/math.e
    namespace math
    public function min(object a)

computes the minimum value among all the argument's elements.

##### Parameters:

1. `values` : an object, all atoms of which will be inspected, no matter how deeply nested.

##### Returns:

An atom, the minimum of all atoms in flatten(`values`).

##### Comments:

This function may be applied to an atom or to a sequence of any shape.

##### Example 1:

    a = min({10,15.4,3})
    -- a is 3

#### 8.25.1.7 ensure_in_range

    include std/math.e
    namespace math
    public function ensure_in_range(object item, sequence range_limits)

ensures that the `item` is in a range of values supplied by inclusive `range_limits`.

##### Parameters:

1. `item` : The object to test for.
2. `range_limits` : A sequence of two or more elements. The first is assumed to be the smallest value and the last is assumed to be the highest value.

##### Returns:

A object, If `item` is lower than the first item in the `range_limits` it returns the first item. If `item` is higher than the last element in the `range_limits` it returns the last item. Otherwise it returns `item`.

##### Example 1:

    object valid_data = ensure_in_range(user_data, {2, 75})
    if not equal(valid_data, user_data) then
        errmsg("Invalid input supplied. Using %d instead.", valid_data)
    end if
    procA(valid_data)

#### 8.25.1.8 ensure_in_list

    include std/math.e
    namespace math
    public function ensure_in_list(object item, sequence list, integer default = 1)

ensures that the `item` is in a list of values supplied by `list`.

##### Parameters:

1. `item` : The object to test for.
2. `list` : A sequence of elements that `item` should be a member of.
3. `default` : an integer, the index of the list item to return if `item` is not found. Defaults to 1.

##### Returns:

An object, if `item` is not in the list, it returns the list item of index `default`, otherwise it returns `item`.

##### Comments:

If `default` is set to an invalid index, the first item on the list is returned instead when `item` is not on the list.

##### Example 1:

    object valid_data = ensure_in_list(user_data, {100, 45, 2, 75, 121})
    if not equal(valid_data, user_data) then
        errmsg("Invalid input supplied. Using %d instead.", valid_data)
    end if
    procA(valid_data)

### 8.25.2 Roundings and Remainders

#### 8.25.2.1 remainder

    <built-in> function remainder(object dividend, object divisor)

computes the remainder of the division of two objects using truncated division.

##### Parameters:

1. `dividend` : any Euphoria object.
2. `divisor` : any Euphoria object.

##### Returns:

An object, the shape of which depends on `dividend`'s and `divisor`'s. For two atoms, this is the remainder of dividing `dividend` by `divisor`, with `dividend`'s sign.

##### Errors:

1. If any atom in `divisor` is 0, this is an error condition as it amounts to an attempt to divide by zero.
2. If both `dividend` and `divisor` are sequences, they must be the same length as each other.

##### Comments:

- There is a integer `N` such that `dividend` = `N` * `divisor` + result.
- The result has the sign of `dividend` and lesser magnitude than `divisor`.
- The result has the same sign as the dividend.
- This differs from mod in that when the operands' signs are different this function rounds `dividend/divisior` towards zero whereas `mod` rounds away from zero.

The arguments to this function may be atoms or sequences. The rules for operations on sequences apply, and determine the shape of the returned object.

##### Example 1:

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

##### Example 2:

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

##### Example 3:

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

##### Example 4:

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

##### See Also:

mod, Relational operators, Operations on sequences

#### 8.25.2.2 mod

    include std/math.e
    namespace math
    public function mod(object x, object y)

computes the remainder of the division of two objects using floored division.

##### Parameters:

1. `dividend` : any Euphoria object.
2. `divisor` : any Euphoria object.

##### Returns:

An object, the shape of which depends on `dividend`'s and `divisor`'s. For two atoms, this is the remainder of dividing `dividend` by `divisor`, with `divisor`'s sign.

##### Comments:

- There is a integer `N` such that `dividend` = N * `divisor` + result.
- The result is non-negative and has lesser magnitude than `divisor`. n needs not fit in an Euphoria integer.
- The result has the same sign as the dividend.
- The arguments to this function may be atoms or sequences. The rules for operations on sequences apply, and determine the shape of the returned object.
- When both arguments have the same sign, mod() and remainder return the same result.
- This differs from remainder in that when the operands' signs are different this function rounds `dividend/divisior` away from zero whereas `remainder` rounds towards zero.

##### Example 1:

    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}

##### Example 4:

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

##### See Also:

remainder, Relational operators, Operations on sequences

#### 8.25.2.3 trunc

    include std/math.e
    namespace math
    public function trunc(object x)

returns the integer portion of a number.

##### Parameters:

1. `value` : any Euphoria object.

##### Returns:

An object, the shape of which depends on `values`'s. Each item in the returned object will be an integer. These are the same corresponding items in `value` except with any fractional portion removed.

##### Comments:

- This is essentially done by always rounding towards zero. The floor function rounds towards negative infinity, which means it rounds towards zero for positive values and away from zero for negative values.
- Note that `trunc(x) + frac(x) = x`

##### Example 1:

    a = trunc(9.4)
    -- a is 9

##### Example 2:

    s = trunc({81, -3.5, -9.999, 5.5})
    -- s is {81,-3, -9, 5}

##### See Also:

floor frac

#### 8.25.2.4 frac

    include std/math.e
    namespace math
    public function frac(object x)

returns the fractional portion of a number.

##### Parameters:

1. `value` : any Euphoria object.

##### Returns:

An object, the shape of which depends on `values`'s. Each item in the returned object will be the same corresponding items in `value` except with the integer portion removed.

##### Comments:

Note that `trunc(x) + frac(x) = x`

##### Example 1:

    a = frac(9.4)
    -- a is 0.4

##### Example 2:

    s = frac({81, -3.5, -9.999, 5.5})
    -- s is {0, -0.5, -0.999, 0.5}

##### See Also:

trunc

#### 8.25.2.5 intdiv

    include std/math.e
    namespace math
    public function intdiv(object a, object b)

returns an integral division of two objects.

##### Parameters:

1. `divided` : any Euphoria object.
2. `divisor` : any Euphoria object.

##### Returns:

An object, which will be a sequence if either `dividend` or `divisor` is a sequence.

##### Comments:

- This calculates how many non-empty sets when `dividend` is divided by `divisor`.
- The result's sign is the same as the `dividend`'s sign.

##### Example 1:

    object Tokens = 101
    object MaxPerEnvelope = 5
    integer Envelopes = intdiv( Tokens, MaxPerEnvelope) --> 21

#### 8.25.2.6 floor

    <built-in> function floor(object value)

Rounds `value` down to the next integer less than or equal to `value`.

##### Parameters:

1. `value` : any Euphoria object; each atom in `value` will be acted upon.

##### Comments:

It does not simply truncate the fractional part, but actually rounds towards negative infinity.

##### Returns:

An object, the same shape as `value` but with each item guarenteed to be an integer less than or equal to the corresponding item in `value`.

##### Example 1:

    y = floor({0.5, -1.6, 9.99, 100})
    -- y is {0, -2, 9, 100}

##### See Also:

ceil, round

#### 8.25.2.7 ceil

    include std/math.e
    namespace math
    public function ceil(object a)

computes the next integer equal or greater than the argument.

##### Parameters:

1. `value` : an object, each atom of which processed, no matter how deeply nested.

##### Returns:

An object, the same shape as `value`. Each atom in `value` is returned as an integer that is the smallest integer equal to or greater than the corresponding atom in `value`.

##### Comments:

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

`ceil(X)` is 1 more than `floor(X)` for non-integers. For integers, `X = floor(X) = ceil(X)`.

##### Example 1:

    sequence nums
    nums = {8, -5, 3.14, 4.89, -7.62, -4.3}
    nums = ceil(nums) -- {8, -5, 4, 5, -7, -4}

##### See Also:

floor, round

#### 8.25.2.8 round

    include std/math.e
    namespace math
    public function round(object a, object precision = 1)

returns the argument's elements rounded to some precision.

##### Parameters:

1. `value` : an object, each atom of which will be acted upon, no matter how deeply nested.
2. `precision` : an object, the rounding precision(s). If not passed, this defaults to 1.

##### Returns:

An object, the same shape as `value`. When `value` is an atom, the result is that atom rounded to the nearest integer multiple of 1/`precision`.

##### Comments:

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

##### Example 1:

    round(5.2) -- 5
    round({4.12, 4.67, -5.8, -5.21}, 10) -- {4.1, 4.7, -5.8, -5.2}
    round(12.2512, 100) -- 12.25

##### See Also:

floor, ceil

### 8.25.3 Trigonometry

#### 8.25.3.1 arctan

    <built-in> function arctan(object tangent)

returns an angle with given tangent.

##### Parameters:

1. `tangent` : an object, each atom of which will be converted, no matter how deeply nested.

##### Returns:

An object, of the same shape as `tangent`. For each atom in `flatten(tangent)`, the angle with smallest magnitude that has this atom as tangent is computed.

##### Comments:

All atoms in the returned value lie between `-PI/2` and `PI/2`, exclusive.

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

`arctan` is faster than `arcsin` or `arccos`.

##### Example 1:

    s = arctan({1,2,3})
    -- s is {0.785398, 1.10715, 1.24905}

##### See Also:

arcsin, arccos, tan, flatten

#### 8.25.3.2 tan

    <built-in> function tan(object angle)

returns the tangent of an angle, or a sequence of angles.

##### Parameters:

1. `angle` : an object, each atom of which will be converted, no matter how deeply nested.

##### Returns:

An object, of the same shape as `angle`. Each atom in the flattened `angle` is replaced by its tangent.

##### Errors:

If any atom in `angle` is an odd multiple of PI/2, an error occurs, as its tangent would be infinite.

##### Comments:

This function may be applied to an atom or to all elements of a sequence of arbitrary shape, recursively.

##### Example 1:

    t = tan(1.0)
    -- t is 1.55741

##### See Also:

sin, cos, arctan

#### 8.25.3.3 cos

    <built-in> function cos(object angle)

returns the cosine of an angle expressed in radians.

##### Parameters:

1. `angle` : an object, each atom of which will be converted, no matter how deeply nested.

##### Returns:

An object, the same shape as `angle`. Each atom in `angle` is turned into its cosine.

##### Comments:

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

The cosine of an angle is an atom between -1 and 1 inclusive. 0.0 is hit by odd multiples of `PI/2` only.

##### Example 1:

    x = cos({.5, .6, .7})
    -- x is {0.8775826, 0.8253356, 0.7648422}

##### See Also:

sin, tan, arccos, PI, deg2rad

#### 8.25.3.4 sin

    <built-in> function sin(object angle)

returns the sine of an angle expressed in radians.

##### Parameters:

1. `angle` : an object, each atom in which will be acted upon.

##### Returns:

An object, the same shape as `angle`. When `angle` is an atom, the result is the sine of `angle`.

##### Comments:

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

The sine of an angle is an atom between -1 and 1 inclusive. 0.0 is hit by integer multiples of `PI` only.

##### Example 1:

    sin_x = sin({.5, .9, .11})
    -- sin_x is {.479, .783, .110}

##### See Also:

cos, arcsin, PI, deg2rad

#### 8.25.3.5 arccos

    include std/math.e
    namespace math
    public function arccos(trig_range x)

returns an angle given its cosine.

##### Parameters:

1. `value` : an object, each atom in which will be acted upon.

##### Returns:

An object, the same shape as `value`. When `value` is an atom, the result is an atom, an angle whose cosine is `value`.

##### Errors:

If any atom in `value` is not in the -1..1 range, it cannot be the cosine of a real number, and an error occurs.

##### Comments:

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.

`arccos` is not as fast as arctan.

##### Example 1:

    s = arccos({-1,0,1})
    -- s is {3.141592654, 1.570796327, 0}

##### See Also:

cos, PI, arctan

#### 8.25.3.6 arcsin

    include std/math.e
    namespace math
    public function arcsin(trig_range x)

returns an angle given its sine.

##### Parameters:

1. `value` : an object, each atom in which will be acted upon.

##### Returns:

An object, the same shape as `value`. When `value` is an atom, the result is an atom, an angle whose sine is `value`.

##### Errors:

If any atom in `value` is not in the -1..1 range, it cannot be the sine of a real number, and an error occurs.

##### Comments:

A value between `-PI/2` and `+PI/2` (radians) inclusive will be returned.

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

`arcsin` is not as fast as arctan.

##### Example 1:

    s = arcsin({-1,0,1})
    s is {-1.570796327, 0, 1.570796327}

##### See Also:

arccos, arccos, sin

#### 8.25.3.7 atan2

    include std/math.e
    namespace math
    public function atan2(atom y, atom x)

calculate the arctangent of a ratio.

##### Parameters:

1. `y` : an atom, the numerator of the ratio
2. `x` : an atom, the denominator of the ratio

##### Returns:

An atom, which is equal to arctan(`y`/`x`), except that it can handle zero denominator and is more accurate.

##### Example 1:

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

##### See Also:

arctan

#### 8.25.3.8 rad2deg

    include std/math.e
    namespace math
    public function rad2deg(object x)

converts an angle measured in radians to an angle measured in degrees.

##### Parameters:

1. `angle` : an object, all atoms of which will be converted, no matter how deeply nested.

##### Returns:

An object, the same shape as `angle`, all atoms of which were multiplied by `180/PI`.

##### Comments:

This function may be applied to an atom or sequence. A flat angle is `PI` radians and 180 degrees.

arcsin, arccos and arctan return angles in radians.

##### Example 1:

    x = rad2deg(3.385938749)
    -- x is 194

##### See Also:

deg2rad

#### 8.25.3.9 deg2rad

    include std/math.e
    namespace math
    public function deg2rad(object x)

converts an angle measured in degrees to an angle measured in radians.

##### Parameters:

1. `angle` : an object, all atoms of which will be converted, no matter how deeply nested.

##### Returns:

An object, the same shape as `angle`, all atoms of which were multiplied by `PI/180`.

##### Comments:

This function may be applied to an atom or sequence. A flat angle is `PI` radians and 180 degrees. sin, cos and tan expect angles in radians.

##### Example 1:

    x = deg2rad(194)
    -- x is 3.385938749

##### See Also:

rad2deg

### 8.25.4 Logarithms and Powers

#### 8.25.4.1 log

    <built-in> function log(object value)

returns the natural logarithm of a positive number.

##### Parameters:

1. `value` : an object, any atom of which `log` acts upon.

##### Returns:

An object, the same shape as `value`. For an atom, the returned atom is its logarithm of base E.

##### Errors:

If any atom in `value` is not greater than zero, an error occurs as its logarithm is not defined.

##### Comments:

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

To compute the inverse, you can use `power(E, x)` where E is 2.7182818284590452, or equivalently exp(x). Beware that the logarithm grows very slowly with x, so that exp grows very fast.

##### Example 1:

    a = log(100)
    -- a is 4.60517

##### See Also:

E, exp, log10

#### 8.25.4.2 log10

    include std/math.e
    namespace math
    public function log10(object x1)

returns the base 10 logarithm of a number.

##### Parameters:

1. `value` : an object, each atom of which will be converted, no matter how deeply nested.

##### Returns:

An object, the same shape as `value`. When `value` is an atom, raising 10 to the returned atom yields `value` back.

##### Errors:

If any atom in `value` is not greater than zero, its logarithm is not a real number and an error occurs.

##### Comments:

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

`log10` is proportional to `log` by a factor of `1/log(10)`, which is about `0.435` .

##### Example 1:

    a = log10(12)
    -- a is 2.48490665

##### See Also:

log

#### 8.25.4.3 exp

    include std/math.e
    namespace math
    public function exp(atom x)

computes some power of E.

##### Parameters:

1. `value` : an object, all atoms of which will be acted upon, no matter how deeply nested.

##### Returns:

An object, the same shape as `value`. When `value` is an atom, its exponential is being returned.

##### Comments:

This function can be applied to a single atom or to a sequence of any shape.

Due to its rapid growth, the returned values start losing accuracy as soon as values are greater than 10. Values above 710 will cause an overflow in hardware.

##### Example 1:

    x = exp(5.4)
    -- x is 221.4064162

##### See Also:

log

#### 8.25.4.4 power

    <built-in> function power(object base, object exponent)

raises a base value to some power.

##### Parameters:

1. `base` : an object, the value or values to raise to some power.
2. `exponent` : an object, the exponent or exponents to apply to `base`.

##### Returns:

An object, the shape of which depends on `base`'s and `exponent`'s. For two atoms, this will be `base` raised to the power `exponent`.

##### Errors:

If some atom in `base` is negative and is raised to a non integer exponent, an error will occur, as the result is undefined.

If 0 is raised to any negative power, this is the same as a zero divide and causes an error.

`power(0,0)` is illegal, because there is not an unique value that can be assigned to that quantity.

##### Comments:

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

Powers of 2 are calculated very efficiently.

Other languages have a `**` or `^` operator to perform the same action. But they do not have sequences.

##### Example 1:

    ? power(5, 2)
    -- 25 is printed

##### Example 2:

    ? power({5, 4, 3.5}, {2, 1, -0.5})
    -- {25, 4, 0.534522} is printed

##### Example 3:

    ? power(2, {1, 2, 3, 4})
    -- {2, 4, 8, 16}

##### Example 4:

    ? power({1, 2, 3, 4}, 2)
    -- {1, 4, 9, 16}

##### See Also:

log, Operations on sequences

#### 8.25.4.5 sqrt

    <built-in> function sqrt(object value)

calculates the square root of a number.

##### Parameters:

1. `value` : an object, each atom in which will be acted upon.

##### Returns:

An object, the same shape as `value`. When `value` is an atom, the result is the positive atom whose square is `value`.

##### Errors:

If any atom in `value` is less than zero, an error will occur, as no squared real can be less than zero.

##### Comments:

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

##### Example 1:

    r = sqrt(16)
    -- r is 4

##### See Also:

power, Operations on sequences

#### 8.25.4.6 fib

    include std/math.e
    namespace math
    public function fib(integer i)

computes the nth Fibonacci Number.

##### Parameters:

1. `value` : an integer. The starting value to compute a Fibonacci Number from.

##### Returns:

An atom,

- The Fibonacci Number specified by value.

##### Comments:

- Note that due to the limitations of the floating point implementation, only 'i' values less than 76 are accurate on Windows platforms, and 69 on other platforms (due to rounding differences in the native C runtime libraries).

##### Example 1:

    ? fib(6)
    -- output ...
    -- 8

### 8.25.5 Hyperbolic Trigonometry

#### 8.25.5.1 cosh

    include std/math.e
    namespace math
    public function cosh(object a)

computes the hyperbolic cosine of an object.

##### Parameters:

1. `x` : the object to process.

##### Returns:

An object, the same shape as `x`, each atom of which was acted upon.

##### Comments:

The hyperbolic cosine grows like the exponential function.

For all reals, `power(cosh(x), 2) - power(sinh(x), 2) = 1`. Compare with ordinary trigonometry.

##### Example 1:

    ? cosh(LN2) -- prints out 1.25

##### See Also:

cos, sinh, arccosh

#### 8.25.5.2 sinh

    include std/math.e
    namespace math
    public function sinh(object a)

computes the hyperbolic sine of an object.

##### Parameters:

1. `x` : the object to process.

##### Returns:

An object, the same shape as `x`, each atom of which was acted upon.

##### Comments:

The hyperbolic sine grows like the exponential function.

For all reals, `power(cosh(x), 2) - power(sinh(x), 2) = 1`. Compare with ordinary trigonometry.

##### Example 1:

    ? sinh(LN2) -- prints out 0.75

##### See Also:

cosh, sin, arcsinh

#### 8.25.5.3 tanh

    include std/math.e
    namespace math
    public function tanh(object a)

computes the hyperbolic tangent of an object.

##### Parameters:

1. `x` : the object to process.

##### Returns:

An object, the same shape as `x`, each atom of which was acted upon.

##### Comments:

The hyperbolic tangent takes values from -1 to +1.

`tanh` is the ratio `sinh / cosh`. Compare with ordinary trigonometry.

##### Example 1:

    ? tanh(LN2) -- prints out 0.6

##### See Also:

cosh, sinh, tan, arctanh

#### 8.25.5.4 arcsinh

    include std/math.e
    namespace math
    public function arcsinh(object a)

computes the reverse hyperbolic sine of an object.

##### Parameters:

1. `x` : the object to process.

##### Returns:

An object, the same shape as `x`, each atom of which was acted upon.

##### Comments:

The hyperbolic sine grows like the logarithm function.

##### Example 1:

    ? arcsinh(1) -- prints out 0,4812118250596034

##### See Also:

arccosh, arcsin, sinh

#### 8.25.5.5 arccosh

    include std/math.e
    namespace math
    public function arccosh(not_below_1 a)

computes the reverse hyperbolic cosine of an object.

##### Parameters:

1. `x` : the object to process.

##### Returns:

An object, the same shape as `x`, each atom of which was acted upon.

##### Errors:

Since cosh only takes values not below 1, an argument below 1 causes an error.

##### Comments:

The hyperbolic cosine grows like the logarithm function.

##### Example 1:

    ? arccosh(1) -- prints out 0

##### See Also:

arccos, arcsinh, cosh

#### 8.25.5.6 arctanh

    include std/math.e
    namespace math
    public function arctanh(abs_below_1 a)

computes the reverse hyperbolic tangent of an object.

##### Parameters:

1. `x` : the object to process.

##### Returns:

An object, the same shape as `x`, each atom of which was acted upon.

##### Errors:

Since tanh only takes values between -1 and +1 excluded, an out of range argument causes an error.

##### Comments:

The hyperbolic cosine grows like the logarithm function.

##### Example 1:

    ? arctanh(1/2) -- prints out 0,5493061443340548456976

##### See Also:

arccos, arcsinh, cosh

### 8.25.6 Accumulation

#### 8.25.6.1 sum

    include std/math.e
    namespace math
    public function sum(object a)

computes the sum of all atoms in the argument, no matter how deeply nested.

##### Parameters:

1. `values` : an object, all atoms of which will be added up, no matter how nested.

##### Returns:

An atom, the sum of all atoms in flatten(`values`).

##### Comments:

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

##### Example 1:

    a = sum({10, 20, 30})
    -- a is 60

    a = sum({10.5, {11.2} , 8.1})
    -- a is 29.8

##### See Also:

product, or_all

#### 8.25.6.2 product

    include std/math.e
    namespace math
    public function product(object a)

computes the product of all the atom in the argument, no matter how deeply nested.

##### Parameters:

1. `values` : an object, all atoms of which will be multiplied up, no matter how nested.

##### Returns:

An atom, the product of all atoms in flatten(`values`).

##### Comments:

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

##### Example 1:

    a = product({10, 20, 30})
    -- a is 6000

    a = product({10.5, {11.2} , 8.1})
    -- a is 952.56

##### See Also:

sum, or_all

#### 8.25.6.3 or_all

    include std/math.e
    namespace math
    public function or_all(object a)

or's together all atoms in the argument, no matter how deeply nested.

##### Parameters:

1. `values` : an object, all atoms of which will be added up, no matter how nested.

##### Returns:

An atom, the result of bitwise or of all atoms in flatten(`values`).

##### Comments:

This function may be applied to an atom or to all elements of a sequence. It performs or_bits operations repeatedly.

##### Example 1:

    a = or_all({10, 7, 35})
    -- a is 47
    -- To see why notice:
    -- 10=0b1010, 7=0b111 and 35=0b100011.
    -- combining these gives:
    --               0b001010
    --      (or_bits)0b000111
    --               0b100011
    --               --------
    --               0b101111 = 47

##### See Also:

sum, product, or_bits

### 8.25.7 Bitwise Operations

Arguments passed to bitwise operations are interpreted as sequences of bits and these sequences are operated on and the result is returned, which is another sequence of bits, is returned as a number. The numbers passed when using ix86 and ARM archetecture must use no more than 32-bits and have no fraction part. Numbers that use no more than 32-bits are numbers between -2_147_483_648 to 4_294_967_295. Numbers that have a fraction part or are outside this range will not yield the results that a calculator that uses more bits would get.

#### 8.25.7.1 and_bits

    <built-in> function and_bits(object a, object b)

performs the bitwise AND operation on corresponding bits in two objects. A bit in the result will be 1 only if the corresponding bits in both arguments are 1.

##### Parameters:

1. `a` : one of the objects involved
2. `b` : the second object

##### Returns:

An object, whose shape depends on the shape of both arguments. Each atom in this object is obtained by bitwise AND between atoms on both objects.

##### Comments:

The arguments to this function may be atoms or sequences. The rules for operations on sequences apply. The atoms in the arguments must be representable as 32-bit numbers, either signed or unsigned.

If you intend to manipulate full 32-bit values, you should declare your variables as atom, rather than integer. Euphoria's integer type is limited to 31-bits.

Results are treated as unsigned numbers. They will never be negative.

To understand the binary representation of a number you should display it in hexadecimal notation. Use the %x format of printf. Using int_to_bits is an even more direct approach.

##### Example 1:

    a = and_bits(#0F0F0000, #12345678)
    -- a is #02040000

##### Example 2:

    a = and_bits(#FF, {#123456, #876543, #2211})
    -- a is {#56, #43, #11}

##### Example 3:

    a = and_bits(#FFFFFFFF, #FFFFFFFF)
     -- a is #FFFFFFFF

##### See Also:

or_bits, xor_bits, not_bits, int_to_bits

#### 8.25.7.2 xor_bits

    <built-in> function xor_bits(object a, object b)

performs the bitwise XOR operation on corresponding bits in two objects. A bit in the result will be 1 only if the corresponding bits in both arguments are different.

##### Parameters:

1. `a` : one of the objects involved
2. `b` : the second object

##### Returns:

An object, whose shape depends on the shape of both arguments. Each atom in this object is obtained by bitwisel XOR between atoms on both objects.

##### Comments:

The arguments must be representable as 32-bit numbers, either signed or unsigned.

If you intend to manipulate full 32-bit values, you should declare your variables as atom, rather than integer. Euphoria's integer type is limited to 31-bits.

Results are treated as unsigned numbers. They will never be negative.

##### Example 1:

    a = xor_bits(#0110, #1010)
    -- a is #1100

##### See Also:

and_bits, or_bits, not_bits, int_to_bits

#### 8.25.7.3 or_bits

    <built-in> function or_bits(object a, object b)

performs the bitwise OR operation on corresponding bits in two objects. A bit in the result will be 1 only if the corresponding bits in both arguments are both 0.

##### Parameters:

1. `a` : one of the objects involved
2. `b` : the second object

##### Returns:

An object, whose shape depends on the shape of both arguments. Each atom in this object is obtained by bitwise OR between atoms on both objects.

##### Comments:

The arguments must be representable as 32-bit numbers, either signed or unsigned.

If you intend to manipulate full 32-bit values, you should declare your variables as atom, rather than integer. Euphoria's integer type is limited to 31-bits.

Results are treated as unsigned numbers. They will never be negative.

##### Example 1:

    a = or_bits(#0F0F0000, #12345678)
    -- a is #1F3F5678

##### Example 2:

    a = or_bits(#FF, {#123456, #876543, #2211})
    -- a is {#1234FF, #8765FF, #22FF}

##### See Also:

and_bits, xor_bits, not_bits, int_to_bits

#### 8.25.7.4 not_bits

    <built-in> function not_bits(object a)

performs the bitwise NOT operation on each bit in an object. A bit in the result will be 1 when the corresponding bit in x1 is 0, and will be 0 when the corresponding bit in x1 is 1.

##### Parameters:

1. `a` : the object to invert the bits of.

##### Returns:

An object, the same shape as `a`. Each bit in an atom of the result is the reverse of the corresponding bit inside `a`.

##### Comments:

The argument to this function may be an atom or a sequence.

The argument must be representable as a 32-bit number, either signed or unsigned.

If you intend to manipulate full 32-bit values, you should declare your variables as atom, rather than integer. Euphoria's integer type is limited to 31-bits.

Results are treated as unsigned numbers. They will never be negative.

A simple equality holds for an atom `a`: `a + not_bits(a) + 1 = power(2,32)`.

##### Example 1:

    a = not_bits(#000000F7)
    -- a is #FFFFFF08 (interpreted as a positive number)

##### See Also:

and_bits, or_bits, xor_bits, int_to_bits

#### 8.25.7.5 shift_bits

    include std/math.e
    namespace math
    public function shift_bits(object source_number, integer shift_distance)

moves the bits in the input value by the specified distance.

##### Parameters:

1. `source_number` : object: The value or values whose bits will be be moved.
2. `shift_distance` : integer: number of bits to be moved by.

##### Comments:

- If `source_number` is a sequence, each element is shifted.
- The value or values in `source_number` are first truncated to a 32-bit integer.
- The output is truncated to a 32-bit integer.
- Vacated bits are replaced with zero.
- If `shift_distance` is negative, the bits in `source_number` are moved left.
- If `shift_distance` is positive, the bits in `source_number` are moved right.
- If `shift_distance` is zero, the bits in `source_number` are not moved.

##### Returns:

Atom or atoms containing a 32-bit integer. A single atom in `source_number` is an atom, or a sequence in the same form as `source_number` containing 32-bit integers.

##### Example 1:

    ? shift_bits(7, -3) --> shift_bits(0b111, -3) -> 0b111000 (which is 56)
    ? shift_bits(0, -9) --> shift_bits(0b0, -9) -> 0b0000000000 -> 0
    ? shift_bits(4, -7) --> shift_bits(0b100, -7) -> 0b1000000000 (which is 512)
    ? shift_bits(8, -4) --> shift_bits(0b1000, -4) -> 0b1000_0000 (which is 128)
    ? shift_bits(0xFE427AAC, -7) --> shift_bits(0b11111110010000100111101010101100, -7)
                                 -->            0b00100001001111010101011000000000
                                 --             (which is 557_667_840)
    ? shift_bits(-7, -3) -->
     -->  shift_bits(0b11111111111111111111111111111001, -3)
                -->  0b11111111111111111111111111001000 ( which is 4_294_967_240)
    ? shift_bits(131, 0) --> 131
    ? shift_bits(184.464, 0) --> 184
    ? shift_bits(999_999_999_999_999, 0) --> 0xA4C67FFF
    ? shift_bits(184, 3) -- 23
    ? shift_bits(48, 2) --> 12
    ? shift_bits(121, 3) --> 15
    ? shift_bits(0xFE427AAC, 7) -->  0x01FC84F5
    ? shift_bits(-7, 3) --> 0x1FFFFFFF (which is 536_870_911)
    -->  shift_bits(0b11111111111111111111111111111001, 3)
               -->  0b00011111111111111111111111111111 ( which is 536_870_911)
    ? shift_bits({48, 121}, 2) --> {12, 30}

##### See Also:

rotate_bits

#### 8.25.7.6 rotate_bits

    include std/math.e
    namespace math
    public function rotate_bits(object source_number, integer shift_distance)

rotates the bits in the input value by the specified distance.

##### Parameters:

1. `source_number` : object: value or values whose bits will be be rotated.
2. `shift_distance` : integer: number of bits to be moved by.

##### Comments:

- If `source_number` is a sequence, each element is rotated.
- The value(s) in `source_number` are first truncated to a 32-bit integer.
- The output is truncated to a 32-bit integer.
- If `shift_distance` is negative, the bits in `source_number` are rotated left.
- If `shift_distance` is positive, the bits in `source_number` are rotated right.
- If `shift_distance` is zero, the bits in `source_number` are not rotated.

##### Returns:

Atom or atoms containing a 32-bit integer. A single atom in `source_number` is an atom, or a sequence in the same form as `source_number` containing 32-bit integers.

##### Example 1:

    ? rotate_bits(7, -3) --> 56
    ? rotate_bits(0, -9) --> 0
    ? rotate_bits(4, -7) --> 512
    ? rotate_bits(8, -4) --> 128
    ? rotate_bits(0xFE427AAC, -7) --> 0x213D567F
    ? rotate_bits(-7, -3) --> 4_294_967_247  which is 0xFFFFFFCF
    ? rotate_bits(131, 0) --> 131
    ? rotate_bits(184.464, 0) --> 184
    ? rotate_bits(999_999_999_999_999, 0) --> 2_764_472_319 which is 0xA4C67FFF
    ? rotate_bits(184, 3) -- 23
    ? rotate_bits(48, 2) --> 12
    ? rotate_bits(121, 3) --> 536_870_927
    ? rotate_bits(0xFE427AAC, 7) -->  0x59FC84F5
    ? rotate_bits(-7, 3) --> 0x3FFFFFFF
    ? rotate_bits({48, 121}, 2) --> {12, 1073741854}

##### See Also:

shift_bits

Arithmetic

#### 8.25.7.7 gcd

    include std/math.e
    namespace math
    public function gcd(atom p, atom q)

Returns the greater common divisor of two atoms

##### Parameters:

1. `p` : one of the atoms to consider
2. `q` : the other atom.

##### Returns:

A positive integer, which is the largest value that evenly divides into both parameters.

##### Comments:

- Signs are ignored. Atoms are rounded down to integers.
- If both parameters are zero, 0 is returned.
- If one parameter is zero, the other parameter is returned.

Parameters and return value are atoms so as to take mathematical integers up to `power(2,53)`.

##### Example 1:

    ? gcd(76.3, -114) --> 38
    ? gcd(0, -114) --> 114
    ? gcd(0, 0) --> 0 (This is often regarded as an error condition)

Floating Point

#### 8.25.7.8 approx

    include std/math.e
    namespace math
    public function approx(object p, object q, atom epsilon = 0.005)

compares two (sets of) numbers based on approximate equality.

##### Parameters:

1. `p` : an object, one of the sets to consider
2. `q` : an object, the other set.
3. `epsilon` : an atom used to define the amount of inequality allowed. This must be a positive value. Default is 0.005

##### Returns:

An integer,

- 1 when p > (q + epsilon) : P is definitely greater than q.
- -1 when p < (q - epsilon) : P is definitely less than q.
- 0 when p >= (q - epsilon) and p <= (q + epsilon) : p and q are approximately equal.

##### Comments:

This can be used to see if two numbers are near enough to each other.

Also, because of the way floating point numbers are stored, it not always possible express every real number exactly, especially after a series of arithmetic operations. You can use `approx` to see if two floating point numbers are almost the same value.

If `p` and `q` are both sequences, they must be the same length as each other.

If `p` or `q` is a sequence, but the other is not, then the result is a sequence of results whose length is the same as the sequence argument.

##### Example 1:

    ? approx(10, 33.33 * 30.01 / 100)
              --> 0 because 10 and 10.002333 are within 0.005 of each other
    ? approx(10, 10.001)
              --> 0 because 10 and 10.001 are within 0.005 of each other
    ? approx(10, {10.001,9.999, 9.98, 10.04})
              --> {0,0,1,-1}
    ? approx({10.001,9.999, 9.98, 10.04}, 10)
              --> {0,0,-1,1}
    ? approx({10.001,{9.999, 10.01}, 9.98, 10.04}, {10.01,9.99, 9.8, 10.4})
              --> {-1,{1,1},1,-1}
    ? approx(23,32, 10)
              --> 0 because 23 and 32 are within 10 of each other.

#### 8.25.7.9 powof2

    include std/math.e
    namespace math
    public function powof2(object p)

tests for power of 2.

##### Parameters:

1. `p` : an object. The item to test. This can be an integer, atom or sequence.

##### Returns:

An integer,

- 1 for each item in `p` that is a power of two (like `2,4,8,16,32, ...`)
- 0 for each item in `p` that is not a power of two (like `3, 54.322, -2`)

##### Example 1:

    for i = 1 to 10 do
      ? {i, powof2(i)}
    end for
    -- output ...
    -- {1,1}
    -- {2,1}
    -- {3,0}
    -- {4,1}
    -- {5,0}
    -- {6,0}
    -- {7,0}
    -- {8,1}
    -- {9,0}
    -- {10,0}

#### 8.25.7.10 is_even

    include std/math.e
    namespace math
    public function is_even(integer test_integer)

tests if the supplied integer is a even or odd number.

##### Parameters:

1. `test_integer` : an integer. The item to test.

##### Returns:

An integer,

- 1 if its even.
- 0 if its odd.

##### Example 1:

    for i = 1 to 10 do
      ? {i, is_even(i)}
    end for
    -- output ...
    -- {1,0}
    -- {2,1}
    -- {3,0}
    -- {4,1}
    -- {5,0}
    -- {6,1}
    -- {7,0}
    -- {8,1}
    -- {9,0}
    -- {10,1}

#### 8.25.7.11 is_even_obj

    include std/math.e
    namespace math
    public function is_even_obj(object test_object)

tests if the supplied Euphoria object is even or odd.

##### Parameters:

1. `test_object` : any Euphoria object. The item to test.

##### Returns:

An object,

- If `test_object` is an integer...
  - 1 if its even.
  - 0 if its odd.
- Otherwise if `test_object` is an atom this always returns 0
- otherwise if `test_object` is an sequence it tests each element recursively, returning a sequence of the same structure containing ones and zeros for each element. A 1 means that the element at this position was even otherwise it was odd.

##### Example 1:

    for i = 1 to 5 do
      ? {i, is_even_obj(i)}
    end for
    -- output ...
    -- {1,0}
    -- {2,1}
    -- {3,0}
    -- {4,1}
    -- {5,0}

##### Example 2:

    ? is_even_obj(3.4) --> 0

##### Example 3:

    ? is_even_obj({{1,2,3}, {{4,5},6,{7,8}},9}) --> {{0,1,0},{{1,0},1,{0,1}},0}

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.24 Base 64 Encoding and Decoding | Up: 8 API Reference | 8.26 Math Constants > | 9 Release Notes >>