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.

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
```

#### 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.

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
```

#### 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.

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
```

#### 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.

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
```

#### 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).

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
```

#### 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).

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.

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.
• 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}
```

#### 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.

• 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}
```

#### 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.

• 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}
```

#### 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.

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}
```

#### 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.

• 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.

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}
```

#### 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.

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}
```

#### 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.

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
```

### 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.

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}
```

#### 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.

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
```

#### 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.

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}
```

#### 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.

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}
```

#### 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.

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}
```

#### 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.

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}
```

#### 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
```

```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.

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
```

```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.

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
```

### 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.

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
```

#### 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.

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
```

#### 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.

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
```

#### 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.

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}
```

#### 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.

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

##### Example 1:
```r = sqrt(16)
-- r is 4
```

#### 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.
• 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.

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
```

#### 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.

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
```

#### 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.

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
```

#### 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.

The hyperbolic sine grows like the logarithm function.

##### Example 1:
```? arcsinh(1) -- prints out 0,4812118250596034
```

#### 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.

The hyperbolic cosine grows like the logarithm function.

##### Example 1:
```? arccosh(1) -- prints out 0
```

#### 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.

The hyperbolic cosine grows like the logarithm function.

##### Example 1:
```? arctanh(1/2) -- prints out 0,5493061443340548456976
```

### 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).

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
```

#### 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).

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
```

#### 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).

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
```

### 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.

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
```

#### 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.

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
```

#### 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.

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}
```

#### 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.

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)
```

#### 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.
• 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}
```

#### 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.
• 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}
```

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.

• 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.

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 >>