LEVIATHAN v962456e · 962456eee1

Standard Library

namespace math

Mathematical constants and functions on float.

since 0.1.0-alpha.1linuxwindowswasm

Overview

Call them with the namespace in front, as in math::sin(x), or add uses math; to use the bare names. Angles are in radians. min and max are available for both int and float; the other functions take and return float.

Description

math is a top-level namespace that is always available, like the rest of the prelude. Reach a member with a qualified path, math::pi or math::log(x), or bring the whole namespace into scope with uses math; and write pi and log(x) bare.

Its members fall into three families.

  • Constants. math::pi and math::e are float constants.
  • Transcendental functions. log (natural logarithm), log2, exp, sin, cos, tan (angles in radians) and atan2(y, x) all take and return float. They call the platform's math library; compare computed floats with a tolerance rather than with ==.
  • min and max. Each has two overloads in the same namespace, one for a pair of ints and one for a pair of floats. The overload is chosen from the argument types, so math::max(3, 9) is an int and math::max(3.5, 9.25) is a float. They are written in Leviathan and are not tied to any floating-point library.

The namespace also holds the bit-pattern factories floatFromBits, float8FromBits, float16FromBits and float32FromBits, which build a float from its bit pattern.

The functions here are plain free functions in a namespace. The unrelated aggregate functions std::min and std::max work on arrays, see the Array entry.

Rules

  • math is spelled with one segment. Write math::pi, never std::math::pi: the qualified path through std is not supported.
  • uses math; makes the bare names pi, e, log, min and the rest available in the current scope.
  • min and max do not mix: both arguments are int or both are float.
  • The angle unit of sin, cos, tan and the result unit of atan2 is the radian.

Examples

Area of a circle and the overloads of max

float r = 2.0;
float area = math::pi * r * r;
console.writeln(area);
console.writeln(math::max(3, 9));
console.writeln(math::max(3.5, 9.25));
console.writeln(math::log(1.0));
Run it ▶
12.566371
9
9.250000
0.000000

Bare names after uses

uses math;
console.writeln(log2(1024.0));
console.writeln(sin(pi / 2.0));
console.writeln(min(1.5, 2.5));
Run it ▶
10.000000
1.000000
1.500000

Notes

A float prints with six decimals, so console.writeln(math::pi) shows 3.141593; the stored value keeps full double precision.

Examples

float radius = 2.0;
float area = math::pi * radius * radius;
console.writeln(area);
console.writeln(math::max(3, 8));
console.writeln(math::sin(math::pi / 6.0));
Run it ▶
12.566371
8
0.500000

Constants and globals

e

const float e = 2.718281828459045

Euler's number, the base of the natural logarithm, 2.718281828459045.

pi

const float pi = 3.141592653589793

The ratio of a circle's circumference to its diameter, 3.141592653589793.

Functions

atan2

atan2(float y, float x) -> float

The angle, in radians, of the point (x, y) measured from the positive x axis.

Unlike a plain arctangent of y / x, this uses the signs of both arguments to place the angle in the right quadrant, so the result lies between -pi and pi.

Parameters

y
The vertical coordinate.
x
The horizontal coordinate.

Returns

The angle of the point from the positive x axis.

Examples

console.writeln(math::atan2(1.0, 1.0) * 4.0);
console.writeln(math::atan2(1.0, 0.0));
console.writeln(math::atan2(-1.0, -1.0));
Run it ▶
3.141593
1.570796
-2.356194

See also: tan

cos

cos(float x) -> float

The cosine of an angle given in radians.

Parameters

x
The angle in radians.

Returns

The cosine of x, between -1 and 1.

Examples

console.writeln(math::cos(0.0));
console.writeln(math::cos(math::pi / 3.0));
console.writeln(math::cos(math::pi));
Run it ▶
1.000000
0.500000
-1.000000

See also: sin

exp

exp(float x) -> float

The number math::e raised to the power x.

Parameters

x
The exponent.

Returns

e to the power x.

Examples

console.writeln(math::exp(0.0));
console.writeln(math::exp(1.0));
console.writeln(math::exp(2.0));
Run it ▶
1.000000
2.718282
7.389056

See also: log

float16FromBits

float16FromBits(int bits) -> float16

Build a float16 from its 16-bit IEEE 754 binary16 encoding.

This is the function behind float16::fromBits(bits). Every NaN encoding becomes the format's single NaN.

Parameters

bits
The encoding, from 0 to 65535.

Returns

The float16 with that encoding.

Throws

RuntimeException
when bits is outside 0..65535.

Examples

console.writeln(math::float16FromBits(15360));
console.writeln(math::float16FromBits(16384));
try {
    console.writeln(math::float16FromBits(0 - 1));
} catch (RuntimeException e) {
    console.writeln(e.message);
}
Run it ▶
1.000000
2.000000
float16FromBits: bits -1 out of range (0..65535)

float32FromBits

float32FromBits(int bits) -> float32

Build a float32 from its 32-bit IEEE 754 binary32 encoding.

This is the function behind float32::fromBits(bits). Every NaN encoding becomes the format's single NaN.

Parameters

bits
The encoding, from 0 to 4294967295.

Returns

The float32 with that encoding.

Throws

RuntimeException
when bits is outside 0..4294967295.

Examples

console.writeln(math::float32FromBits(1073741824));
console.writeln(math::float32FromBits(1078530011));
Run it ▶
2.000000
3.141593

float8FromBits

float8FromBits(int bits) -> float8

Build a float8 from its 8-bit encoding.

This is the function behind float8::fromBits(bits). The format is the E4M3 layout with one sign bit, four exponent bits and three fraction bits. Every NaN encoding becomes the format's single NaN.

Parameters

bits
The encoding, from 0 to 255.

Returns

The float8 with that encoding.

Throws

RuntimeException
when bits is outside 0..255.

Examples

console.writeln(math::float8FromBits(56));
console.writeln(math::float8FromBits(72));
try {
    console.writeln(math::float8FromBits(256));
} catch (RuntimeException e) {
    console.writeln(e.message);
}
Run it ▶
1.000000
4.000000
float8FromBits: bits 256 out of range (0..255)

floatFromBits

floatFromBits(int bits) -> float

Build a float from its 64-bit IEEE 754 representation.

This is the function behind float::fromBits(bits). The integer's 64 bits are read as the sign, exponent and fraction of a double-precision number.

Parameters

bits
The bit pattern of the value.

Returns

The float with that bit pattern.

Examples

console.writeln(math::floatFromBits(4607182418800017408));
console.writeln(math::floatFromBits(4611686018427387904));
console.writeln(math::floatFromBits(0));
Run it ▶
1.000000
2.000000
0.000000

log

log(float x) -> float

The natural logarithm of x.

The logarithm of zero is negative infinity, and the logarithm of a negative number is NaN.

Parameters

x
The value to take the logarithm of.

Returns

The power to which math::e must be raised to get x.

Examples

console.writeln(math::log(1.0));
console.writeln(math::log(math::e));
console.writeln(math::log(100.0) / math::log(10.0));
Run it ▶
0.000000
1.000000
2.000000

See also: exp

log2

log2(float x) -> float

The base-2 logarithm of x.

Parameters

x
The value to take the logarithm of.

Returns

The power to which 2 must be raised to get x.

Examples

console.writeln(math::log2(8.0));
console.writeln(math::log2(1024.0));
Run it ▶
3.000000
10.000000

See also: log

max

max(int a, int b) -> int

The larger of two integers.

Parameters

a
The first integer.
b
The second integer.

Returns

a if it is greater than b, otherwise b.

Examples

console.writeln(math::max(3, 8));
console.writeln(math::max(0 - 5, 0 - 9));
console.writeln(math::max(-1.0, -4.0));
Run it ▶
8
-5
-1.000000

max(float a, float b) -> float

The larger of two floats.

Same as max(a, b) for integers, chosen when both arguments are floats.

Parameters

a
The first float.
b
The second float.

Returns

a if it is greater than b, otherwise b.

See also: min

min

min(int a, int b) -> int

The smaller of two integers.

Parameters

a
The first integer.
b
The second integer.

Returns

a if it is less than b, otherwise b.

Examples

console.writeln(math::min(3, 8));
console.writeln(math::min(7, 7));
console.writeln(math::min(2.5, 1.5));
Run it ▶
3
7
1.500000

min(float a, float b) -> float

The smaller of two floats.

Same as min(a, b) for integers, chosen when both arguments are floats.

Parameters

a
The first float.
b
The second float.

Returns

a if it is less than b, otherwise b.

See also: max

sin

sin(float x) -> float

The sine of an angle given in radians.

Parameters

x
The angle in radians.

Returns

The sine of x, between -1 and 1.

Examples

console.writeln(math::sin(0.0));
console.writeln(math::sin(math::pi / 6.0));
console.writeln(math::sin(math::pi / 2.0));
Run it ▶
0.000000
0.500000
1.000000

See also: cos

tan

tan(float x) -> float

The tangent of an angle given in radians.

Parameters

x
The angle in radians.

Returns

The tangent of x.

Examples

console.writeln(math::tan(0.0));
console.writeln(math::tan(math::pi / 4.0));
Run it ▶
0.000000
1.000000

See also: atan2

See also

  • min — Find the smallest element of an integer array.
  • max — Find the largest element of an integer array.