OpenEuphoria

8.24 Math

8.24.1 Sign and comparisons

8.24.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.24.1.2 sign

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

Return -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.24.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.

Examples:

? 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

Comments:

Introduced in v4.0.3

See Also:

max, compare, smaller_of

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

Examples:

? 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

Comments:

Introduced in v4.0.3

See Also:

min, compare, larger_of

8.24.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.24.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.24.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.24.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.24.2 Roundings and remainders

8.24.2.1 remainder

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

Compute 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.24.2.2 mod

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

Compute 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.24.2.3 trunc

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

Return 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.24.2.4 frac

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

Return 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.24.2.5 intdiv

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

Return 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.24.2.6 floor

<built-in> function floor(object value)

Rounds value down to the next integer less than or equal to value. It does not simply truncate the fractional part, but actually rounds towards negative infinity.

Parameters:

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

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.24.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.24.2.8 round

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

Return 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.24.3 Trigonometry

8.24.3.1 arctan

<built-in> function arctan(object tangent)

Return 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.24.3.2 tan

<built-in> function tan(object angle)

Return 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.24.3.3 cos

<built-in> function cos(object angle)

Return 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({0.5, 0.6, 0.7})
-- x is {0.8775826, 0.8253356, 0.7648422}

See Also:

sin, tan, arccos, PI, deg2rad

8.24.3.4 sin

<built-in> function sin(object angle)

Return 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({0.5, 0.9, 0.11})
-- sin_x is {.479, .783, .110}

See Also:

cos, arcsin, PI, deg2rad

8.24.3.5 arccos

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

Return 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.24.3.6 arcsin

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

Return 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.24.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.24.3.8 rad2deg

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

Convert 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.24.3.9 deg2rad

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

Convert 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.24.4 Logarithms and powers.

8.24.4.1 log

<built-in> function log(object value)

Return 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.24.4.2 log10

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

Return 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.24.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.24.4.4 power

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

Raise a base value to some power.

Parameters:

1. base : an object, the value(s) to raise to some power.
2. exponent : an object, the exponent(s) 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 don't 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.24.4.5 sqrt

<built-in> function sqrt(object value)

Calculate 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.24.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.24.5 Hyperbolic trigonometry

8.24.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.24.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.24.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.24.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.24.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.24.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.24.6 Accumulation

8.24.6.1 sum

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

Compute 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.24.6.2 product

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

Compute 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.24.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 or'ing 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 = sum({10, 7, 35})
-- a is 47

See Also:

sum, product, or_bits

8.24.7 Bitwise operations

8.24.7.1 and_bits

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

Perform 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 signed numbers. They will be negative when the highest-order bit is 1.

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 -1
-- Note that #FFFFFFFF is a positive number,
-- but the result of a bitwise operation is interpreted
-- as a signed 32-bit number, so it's negative.

See Also:

or_bits, xor_bits, not_bits, int_to_bits

8.24.7.2 xor_bits

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

Perform 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 signed numbers. They will be negative when the highest-order bit is 1.

Example 1:

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

See Also:

and_bits, or_bits, not_bits, int_to_bits

8.24.7.3 or_bits

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

Perform 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 signed numbers. They will be negative when the highest-order bit is 1.

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.24.7.4 not_bits

<built-in> function not_bits(object a)

Perform 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 signed numbers. They will be negative when the highest-order bit is 1.

A simple equality holds for an atom a: a + not_bits(a) = -1.

Example 1:

a = not_bits(#000000F7)
-- a is -248 (i.e. FFFFFF08 interpreted as a negative number)

See Also:

and_bits, or_bits, xor_bits, int_to_bits

8.24.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(s) 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(s) 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(s) 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) --> 56
? shift_bits((0, -9) --> 0
? shift_bits((4, -7) --> 512
? shift_bits((8, -4) --> 128
? shift_bits((0xFE427AAC, -7) --> 0x213D5600
? shift_bits((-7, -3) --> -56  which is 0xFFFFFFC8 
? shift_bits((131, 0) --> 131
? shift_bits((184.464, 0) --> 184
? shift_bits((999_999_999_999_999, 0) --> -1530494977 which is 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
? shift_bits({48, 121}, 2) --> {12, 30}

See Also:

rotate_bits

8.24.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(s) 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(s) 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) --> -49  which is 0xFFFFFFCF 
? rotate_bits(131, 0) --> 131
? rotate_bits(184.464, 0) --> 184
? rotate_bits(999_999_999_999_999, 0) --> -1530494977 which is 0xA4C67FFF
? rotate_bits(184, 3) -- 23
? rotate_bits(48, 2) --> 12
? rotate_bits(121, 3) --> 536870927
? rotate_bits(0xFE427AAC, 7) -->  0x59FC84F5
? rotate_bits(-7, 3) --> 0x3FFFFFFF
? rotate_bits({48, 121}, 2) --> {12, 1073741854}

See Also:

shift_bits

Arithmetics

8.24.7.7 gcd

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

Returns the greater common divisor of to 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.24.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.24.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, eg. 2,4,8,16,32, ...
• 0 for each item in p that is not a power of two, eg. 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.24.7.10 is_even

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

Test 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.24.7.11 is_even_obj

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

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