The transcendentals Module#

The transcendentals module, exported from the common-dylan library, provides a set of generic functions for ANSI C-like behavior over real numbers. The restrictions and error cases described in this document are intended to be the same as they are in ANSI C.

Because implementation of these functions might be by a standard library for transcendentals accessed by a foreign function interface, the exact precision and algorithms (and hence, the exact results) for all of these functions is explicitly unspecified.

Note, however, that a program may expect the following, even in libraries that are implemented by calling foreign libraries:

Domain and range errors should be signalled as Dylan errors.
Floating point precision contagion must obey Dylan rules. That is, functions called on single precision values return single precision results, and functions on double precision values return double precision results. When a function (e.g., ^, atan2, etc.) accepts two arguments, if either argument is a double precision value then the result is also double precision.

As a rule this module does not automatically convert integer values to floating point values. Callers should do so explicitly, so as to choose the appropriate floating point type for their needs.

Complex numbers are not implemented. If the result of calling any transcendentals function would be a complex number <error> is signalled.

Reference#

This section contains a reference entry for each item exported from the transcendentals module.

Constants#

$single-e Constant#

The value of e, the base of natural logarithms, as a single precision floating point number.

Type:: <single-float>

$double-e Constant#

The value of e, the base of natural logarithms, as a double precision floating point number.

Type:: <double-float>

$single-pi Constant#

The value of π as a single precision floating point number.

Type:: <single-float>

$double-pi Constant#

The value of π as a double precision floating point number.

Type:: <double-float>

Functions#

^(<single-float>, <single-float>) Method#

Single precision floating point implementation of ^.

Signature:: base ^ exponent => y

Returns base raised to the power exponent as a <single-float>. If base is 0 and exponent is not positive, an error is signalled. If base is negative and exponent is not an integer, an error is signalled.

^(<double-float>, <double-float>) Method#

Double precision floating point implementation of ^.

Signature:: base ^ exponent => y

Returns base raised to the power exponent as a <double-float>. If base is 0 and exponent is not positive, an error is signalled. If base is negative and exponent is not an integer, an error is signalled.

^(<single-float>, <double-float>) Method#: Converts the first argument to <double-float> and calls ^(<double-float>, <double-float>).

^(<double-float>, <single-float>) Method#: Converts the second argument to <double-float> and calls ^(<double-float>, <double-float>).

acos Open Generic function#

Signature:

acos(x) => y

Parameters:

x – An instance of type <number>. The angle, in radians. If x is not in the range [-1,1], an error is signalled.

Values:

y – An instance of type <number>.

Returns the arc cosine of its argument. The floating point precision of the result is given by the precision of x.

See also:: asin, atan

acos(<single-float>) Method#: Single precision floating point implementation of acos. Returns a <single-float>.

acos(<double-float>) Method#: Double precision floating point implementation of acos. Returns a <double-float>.

acosh Open Generic function#

Signature:

acosh(x) => y

Parameters:

x – An instance of type <number>. The angle, in radians.

Values:

y – An instance of type <number>.

Returns the hyperbolic arc cosine of its argument. The floating point precision of the result is given by the precision of x.

See also:: asinh, atanh

acosh(<single-float>) Method#: Single precision floating point implementation of acosh. Returns a <single-float>.

acosh(<double-float>) Method#: Double precision floating point implementation of acosh. Returns a <double-float>.

asin Generic function#

Signature:

asin(x) => y

Parameters:

x – An instance of type <number>. The angle, in radians. If x is not in the range [-1,+1], an error is signalled.

Values:

y – An instance of type <number>.

Returns the arc sine of its argument. The floating point precision of the result is given by the precision of x.

See also:: acos, atan

asin(<single-float>) Sealed Method#: Single precision floating point implementation of asin. Returns a <single-float>.

asin(<double-float>) Sealed Method#: Double precision floating point implementation of asin. Returns a <double-float>.

asinh Generic function#

Signature:

asinh(x) => y

Parameters:

x – An instance of type <number>. The angle, in radians.

Values:

y – An instance of type <number>.

Returns the hyperbolic arc sine of its argument. The floating point precision of the result is given by the precision of x.

See also:: acosh, atanh

asinh(<single-float>) Sealed Method#: Single precision floating point implementation of asinh. Returns a <single-float>.

asinh(<double-float>) Sealed Method#: Double precision floating point implementation of asinh. Returns a <double-float>.

atan Generic function#

Signature:

atan(x) => y

Parameters:

x – An instance of type <number>. The angle, in radians. If x is not in the range [-1,+1], an error is signalled.

Values:

y – An instance of type <number>.

Returns the arc tangent of its argument. The floating point precision of the result is given by the precision of x.

See also:: acos, asin

atan(<single-float>) Sealed Method#: Single precision floating point implementation of atan. Returns a <single-float>.

atan(<double-float>) Sealed Method#: Double precision floating point implementation of atan. Returns a <double-float>.

atan2 Generic function#

Signature:

atan2(x, y) => z

Parameters:

x – An instance of type <number>. The first angle, in radians.
y – An instance of type <number>. The second angle, in radians.

Values:

z – An instance of type <number>.

Returns the arc tangent of x divided by y. x may be zero if y is not zero. The signs of x and y are used to derive what quadrant the angle falls in.

atan2(<single-float>, <single-float>) Sealed Method#: Single precision floating point implementation of atan2. Returns a <single-float>.

atan2(<double-float>, <double-float>) Sealed Method#: Double precision floating point implementation of atan2. Returns a <double-float>.

atan2(<single-float>, <double-float>) Sealed Method#: Converts the first argument to <double-float> and calls atan2(<double-float>, <double-float>).

atan2(<double-float>, <single-float>) Sealed Method#: Converts the second argument to <double-float> and calls atan2(<double-float>, <double-float>).

atanh Generic function#

Signature:

atanh(x) => y

Parameters:

x – An instance of type <number>. The angle, in radians.

Values:

y – An instance of type <number>.

Returns the hyperbolic arc tangent of its argument. The floating point precision of the result is given by the precision of x.

See also:: acosh, asinh

atanh(<single-float>) Sealed Method#: Single precision floating point implementation of atanh. Returns a <single-float>.

atanh(<double-float>) Sealed Method#: Double precision floating point implementation of atanh. Returns a <double-float>.

cos Generic function#

Signature:

cos(x) => y

Parameters:

x – An instance of type <number>. The angle, in radians.

Values:

y – An instance of type <number>.

Returns the cosine of its argument. The floating point precision of the result is given by the precision of x.

See also:: sin, sincos, tan

cos(<single-float>) Sealed Method#: Single precision floating point implementation of cos. Returns a <single-float>.

cos(<double-float>) Sealed Method#: Double precision floating point implementation of cos. Returns a <double-float>.

cosh Generic function#

Signature:

cosh(x) => y

Parameters:

x – An instance of type <number>. The angle, in radians.

Values:

y – An instance of type <number>.

Returns the hyperbolic cosine of its argument. The floating point precision of the result is given by the precision of x.

See also:: sinh, tanh

cosh(<single-float>) Sealed Method#: Single precision floating point implementation of cosh. Returns a <single-float>.

cosh(<double-float>) Sealed Method#: Double precision floating point implementation of cosh. Returns a <double-float>.

exp Generic function#

Signature:

exp(x) => y

Parameters:

x – An instance of type <number>.

Values:

y – An instance of type <number>.

Returns e, the base of natural logarithms, raised to the power x. The floating point precision is given by the precision of x.

See also:: ^, ilog2, log, logn

exp(<single-float>) Sealed Method#: Single precision floating point implementation of exp. Returns a <single-float>.

exp(<double-float>) Sealed Method#: Double precision floating point implementation of exp. Returns a <double-float>.

hypot Generic function#

Signature:

hypot(x, y) => z

Parameters:

x – An instance of type <number>.
y – An instance of type <number>.

Values:

z – An instance of type <number>.

Returns the Euclidian distance without unnecessary overflow or underflow.

hypot(<single-float>, <single-float>) Method#: Returns the Euclidian distance as a <single-float> without unnecessary overflow or underflow.

hypot(<double-float>, <double-float>) Method#: Returns the Euclidian distance as a <double-float> without unnecessary overflow or underflow.

hypot(<single-float>, <double-float>) Method#: Converts the first argument to <double-float> and calls hypot(<double-float>, <double-float>).

hypot(<double-float>, <single-float>) Method#: Converts the second argument to <double-float> and calls hypot(<double-float>, <double-float>).

isqrt Function#

Signature:

isqrt(x) => y

Parameters:

x – An instance of type <integer>.

Values:

y – An instance of type <integer>.

Returns the integer square root of x, that is the greatest integer less than or equal to the exact positive square root of x. If x < 0, an error is signalled.

See also:: sqrt

log Generic function#

Returns the natural logarithm of its argument.

Signature:

log(x) => y

Parameters:

x – An instance of type <number>.

Values:

y – An instance of type <number>.

Returns the natural logarithm of x to the base e. If x <= 0, an error is signalled. The floating point precision of the result is given by the precision of x.

See also:: exp, ilog2, logn

log(<single-float>) Method#

Signature:

log(x) => y

Parameters:

x – An instance of type <single-float>.

Values:

y – An instance of type <single-float>.

Returns the natural logarithm of x to the base e as a <single-float>.

log(<double-float>) Method#

Signature:

log(x) => y

Parameters:

x – An instance of type <double-float>.

Values:

y – An instance of type <double-float>.

Returns the natural logarithm of x to the base e as a <single-float>.

logn Function#

Returns the logarithm of its argument to the given base.

Signature:

logn(x, base) => y

Parameters:

x – An instance of <number>
base – The base. An instance of <number>.

Values:

y – An instance of <number>.

Returns the logarithm of x to the base base. If x <= 0 or base <= 1, an error is signalled. The floating point precision of the result is given by the precision of x.

Note

In practice both x and base must be instances of <float> since they are passed directly to log, which only has methods on <float>.

See also:: exp, log, ilog2

ilog2 Function#

Signature:

ilog2(x) => y

Parameters:

x – An instance of <integer>.

Values:

y – An instance of <integer>.

Returns the integer base 2 logarithm of x, truncated to an <integer>. That is, it returns the greatest integer less than or equal to the exact base 2 logarithm of x.

See also:: exp, logn, log

sin Generic function#

Signature:

sin(x) => y

Parameters:

x – An instance of type <number>. The angle, in radians.

Values:

y – An instance of type <number>.

Returns the sine of its argument. The floating point precision of the result is given by the precision of x.

See also:: cos, sincos, tan

sin(<single-float>) Sealed Method#: Single precision floating point implementation of sin. Returns a <single-float>.

sin(<double-float>) Sealed Method#: Double precision floating point implementation of sin. Returns a <double-float>.

sincos Generic function#

Signature:

sincos(x) => (sin, cos)

Parameters:

x – An instance of type <number>. The angle, in radians.

Values:

sin – An instance of type <number>. The result of sin(x).
cos – An instance of type <number>. The result of cos(x).

Returns both the sine and the cosine of its argument. The floating point precision of the results is given by the precision of x. In some implementations sincos may have better performance than calling sin(x) and cos(x) separately.

See also:: cos, sin

sincos(<single-float>) Sealed Method#: Single precision floating point implementation of sincos. Returns a <single-float>.

sincos(<double-float>) Sealed Method#: Double precision floating point implementation of sincos. Returns a <double-float>.

sinh Generic function#

Signature:

sinh(x) => y

Parameters:

x – An instance of type <number>. The angle, in radians.

Values:

y – An instance of type <number>.

Returns the hyperbolic sine of its argument. The floating point precision of the result is given by the precision of x.

See also:: cosh, tanh

sinh(<single-float>) Sealed Method#: Single precision floating point implementation of sinh. Returns a <single-float>.

sinh(<double-float>) Sealed Method#: Double precision floating point implementation of sinh. Returns a <double-float>.

sqrt Generic function#

Signature:

sqrt(x) => y

Parameters:

x – An instance of type <number>.

Values:

y – An instance of type <number>.

Returns the square root of x. If x is less than zero an error is signalled. The floating point precision of the result is given by the precision of x.

See also:: isqrt

sqrt(<single-float>) Sealed Method#: Single precision floating point implementation of sqrt. Returns a <single-float>.

sqrt(<double-float>) Sealed Method#: Double precision floating point implementation of sqrt. Returns a <double-float>.

tan Generic function#

Signature:

tan(x) => y

Parameters:

x – An instance of type <number>. The angle, in radians.

Values:

y – An instance of type <number>.

Returns the tangent of x. The floating point precision of the result is given by the precision of x.

See also:: cos, sin

tan(<single-float>) Sealed Method#: Single precision floating point implementation of tan. Returns a <single-float>.

tan(<double-float>) Sealed Method#: Double precision floating point implementation of tan. Returns a <double-float>.

tanh Generic function#

Signature:

tanh(x) => y

Parameters:

x – An instance of type <number>. The angle, in radians.

Values:

y – An instance of type <number>.

Returns the hyperbolic tangent of x. The floating point precision of the result is given by the precision of x.

See also:: cosh, sinh

tanh(<single-float>) Sealed Method#: Single precision floating point implementation of tanh. Returns a <single-float>.

tanh(<double-float>) Sealed Method#: Double precision floating point implementation of tanh. Returns a <double-float>.