-- (c) Copyright - See License.txt

--

--****

-- == Math

--

-- <>

--

namespace math

public include std/rand.e

public include std/mathcons.e

include std/error.e

-- values passed to arccos and arcsin must be [-1,+1]

else

end if

end if

end type

--****

-- === Sign and comparisons

--

--**

-- Returns the absolute value of numbers.

--

-- Parameters:

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

object t

else

end if

end if

end if

else

end if

end function

--**

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

--

-- Parameters:

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

-- small so normally it will be inlined

end function

--**

-- Computes the maximum value among all the argument's elements

--

-- Parameters:

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

atom b, c

end if

end if

end function

--**

-- Computes the minimum value among all the argument's elements

--

-- Parameters:

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

--

atom b, c

end if

end if

end function

--**

-- Ensures that the ##item## is in a range of values supplied by inclusive ##range_limits##

--

-- Parameters:

-- # ##item## : The object to test for.

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

--

end if

end if

end if

end function

--**

-- Ensures that the ##item## is in a list of values supplied by ##list##

--

-- Parameters:

-- # ##item## : The object to test for.

-- # ##list## : A sequence of elements that ##item## should be a member of.

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

--

end if

else

end if

end if

end function

--****

-- === Roundings and remainders

--

--****

-- Signature:

-- function remainder(object dividend, object divisor)

--

-- Description:

-- Compute the remainder of the division of two objects using truncated division.

--

-- Parameters:

-- # ##dividend## : any Euphoria object.

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

-- # If any atom in ##divisor## is 0, this is an error condition as it

-- amounts to an attempt to divide by zero.

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

--**

-- Compute the remainder of the division of two objects using floored division.

--

-- Parameters:

-- # ##dividend## : any Euphoria object.

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

end if

end function

--**

-- Return the integer portion of a number.

--

-- Parameters:

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

end function

--**

-- Return the fractional portion of a number.

--

-- Parameters:

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

end function

--**

-- Return an integral division of two objects.

--

-- Parameters:

-- # ##divided## : any Euphoria object.

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

--

--

end function

--****

-- Signature:

-- function floor(object value)

--

-- Description:

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

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

--**

-- Computes the next integer equal or greater than the argument.

--

-- Parameters:

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

end function

--**

-- Return the argument's elements rounded to some precision

--

-- Parameters:

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

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

integer len

sequence s

object t, u

end if

else

end if

else

end if

end if

end if

else

end if

else

end if

end function

--****

-- === Trigonometry

--****

-- Signature:

-- function arctan(object tangent)

--

-- Description:

-- Return an angle with given tangent.

--

-- Parameters:

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

--****

-- Signature:

-- function tan(object angle)

--

-- Description:

-- Return the tangent of an angle, or a sequence of angles.

--

-- Parameters:

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

--****

-- Signature:

-- function cos(object angle)

--

-- Description:

-- Return the cosine of an angle expressed in radians

--

-- Parameters:

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

--****

-- Signature:

-- function sin(object angle)

--

-- Description:

-- Return the sine of an angle expressed in radians

--

-- Parameters:

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

--**

-- Return an angle given its cosine.

--

-- Parameters:

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

-- returns angle in radians

end function

--**

-- Return an angle given its sine.

--

-- Parameters:

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

-- returns angle in radians

end function

--**

-- Calculate the arctangent of a ratio.

--

-- Parameters:

-- # ##y## : an atom, the numerator of the ratio

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

else

end if

else

end if

end function

--**

-- Convert an angle measured in radians to an angle measured in degrees

--

-- Parameters:

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

end function

--**

-- Convert an angle measured in degrees to an angle measured in radians

--

-- Parameters:

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

end function

--****

-- === Logarithms and powers.

--

--****

-- Signature:

-- function log(object value)

--

-- Description:

-- Return the natural logarithm of a positive number.

--

-- Parameters:

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

--

--**

-- Return the base 10 logarithm of a number.

--

-- Parameters:

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

end function

--**

-- Computes some power of E.

--

-- Parameters:

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

end function

--****

-- Signature:

-- function power(object base, object exponent)

--

-- Description:

-- Raise a base value to some power.

--

-- Parameters:

-- # ##base## : an object, the value(s) to raise to some power.

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

--****

-- Signature:

-- function sqrt(object value)

--

-- Description:

-- Calculate the square root of a number.

--

-- Parameters:

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

--

--****

-- === Hyperbolic trigonometry

--

--**

-- Computes the hyperbolic cosine of an object.

--

-- Parameters:

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

end function

--**

-- Computes the hyperbolic sine of an object.

--

-- Parameters:

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

end function

--**

-- Computes the hyperbolic tangent of an object.

--

-- Parameters:

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

end function

--**

-- Computes the reverse hyperbolic sine of an object.

--

-- Parameters:

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

end function

end if

end if

end type

--**

-- Computes the reverse hyperbolic cosine of an object.

--

-- Parameters:

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

end function

end if

end if

end type

--**

-- Computes the reverse hyperbolic tangent of an object.

--

-- Parameters:

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

end function

--****

-- === Accumulation

--

--**

-- Compute the sum of all atoms in the argument, no matter how deeply nested

--

-- Parameters:

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

-- [[:can_add]], [[:product]], [[:or_all]]

atom b

end if

else

end if

end function

--**

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

--

-- Parameters:

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

-- [[:can_add]], [[:sum]], [[:or_all]]

atom b

end if

else

end if

end function

--**

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

--

-- Parameters:

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

-- [[:can_add]], [[:sum]], [[:product]], [[:or_bits]]

atom b

end if

else

end if

end function

--****

-- === Bitwise operations

--

--****

-- Signature:

-- function and_bits(object a, object b)

--

-- Description:

-- Perform the logical 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:

-- # ##a## : one of the objects involved

-- # ##b## : the second object

--

-- Returns:

-- An **object**, whose shape depends on the shape of both arguments. Each atom in this object

-- is obtained by logical 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 logical operation is interpreted

-- -- as a signed 32-bit number, so it's negative.

--

--

-- See Also:

-- [[:or_bits]], [[:xor_bits]], [[:not_bits]], [[:int_to_bits]]

--

--****

-- Signature:

-- function xor_bits(object a, object b)

--

-- Description:

-- Perform the logical 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:

-- # ##a## : one of the objects involved

-- # ##b## : the second object

--

-- Returns:

-- An **object**, whose shape depends on the shape of both arguments. Each atom in this object

-- is obtained by logical 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]]

--****

-- Signature:

-- function or_bits(object a, object b)

--

-- Description:

-- Perform the logical 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:

-- # ##a## : one of the objects involved

-- # ##b## : the second object

--

-- Returns:

-- An **object**, whose shape depends on the shape of both arguments. Each atom in this object

-- is obtained by logical 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 = 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]]

--****

-- Signature:

-- function not_bits(object a)

--

-- Description:

-- Perform the logical 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.