LEVIATHAN v962456e · 962456eee1

Standard Library

class float32

A 32-bit floating-point number in the IEEE 754 binary32 format: 1 sign bit, 8 exponent bits and 23 mantissa bits.

since 0.1.0-alpha.1linuxwindowswasm

Overview

A float32 has about seven significant decimal digits. The largest finite value is about 3.4 times 10 to the 38th power. An operation whose result is larger gives infinity, and operations with no defined result, such as 0.0 / 0.0, give NaN. Every arithmetic result is rounded to the nearest float32 (ties to even) after each operation, so adding 1 to 16777216 leaves 16777216. Mixing two float formats computes in the wider one, and mixing with an int or a float computes as float.

A literal assigned to a float32 is rounded to the nearest value. float.toFloat32() converts a float and throws when the value is out of range. toFloat() converts back exactly.

Examples

Rounding, range and NaN

float32 p = 0.1;
console.writeln(p);
console.writeln(p.toFloat() == 0.1);
float32 big = 16777216.0;
float32 one = 1.0;
console.writeln(big + one);
float tooBig = 1000000.0 * 1000000.0 * 1000000.0 * 1000000.0 * 1000000.0 * 1000000.0 * 1000000.0;
try {
    console.writeln(tooBig.toFloat32());
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}
Run it ▶
0.100000
false
16777216.000000
caught: toFloat32: value out of range (max finite 3.4028235e+38)

Methods

abs

abs() -> float32

Return the absolute value.

The sign bit is cleared, so -0.0 becomes 0.0.

Returns

this with its sign removed, as a float32.

Examples

float32 neg = -2.5;
console.writeln(neg.abs());
float32 negZero = float32::fromBits(2147483648);
console.writeln(negZero.abs().bits());
Run it ▶
2.500000
0

bits

bits() -> int

Return the 32-bit encoding of the value as an int.

The result is the raw interchange bits of the format (1 sign bit, then 8 exponent bits, then 23 mantissa bits), as a non-negative int. Two values that print the same can have different bits, for example 0.0 and -0.0. std.math.float32FromBits turns bits back into a float32 and is also written float32::fromBits.

Returns

The bit pattern of this.

Examples

float32 one = 1.0;
console.writeln(one.bits());
float32 p = 0.1;
console.writeln(p.bits());
float32 negOne = -1.0;
console.writeln(negOne.bits());
console.writeln(float32::fromBits(1065353216) == one);
Run it ▶
1065353216
1036831949
3212836864
true

See also: float32FromBits

canonEq

canonEq(float32 other) -> bool

Compare two float32 values by their canonical form.

This is the relation used when a float32 is a map key or a field of a struct compared with == on the struct. It differs from the == operator in two cases: every NaN equals every other NaN, and 0.0 equals -0.0. The == operator follows the IEEE rule that NaN is not equal to anything, itself included.

Parameters

other
The value to compare with.

Returns

true when both are NaN or both denote the same number.

Examples

float32 nan = float32::fromBits(2143289344);
console.writeln(nan == nan);
console.writeln(nan.canonEq(nan));
float32 zero = 0.0;
float32 negZero = float32::fromBits(2147483648);
console.writeln(zero == negZero);
console.writeln(zero.canonEq(negZero));
console.writeln(zero.bits());
console.writeln(negZero.bits());
Run it ▶
false
true
true
true
0
2147483648

ceil

ceil() -> float32

Round up to a whole number.

Returns

The smallest whole number not less than this, as a float32.

Examples

float32 pos = 2.5;
float32 neg = -2.5;
console.writeln(pos.ceil());
console.writeln(neg.ceil());
Run it ▶
3.000000
-2.000000

See also: floor

floor

floor() -> float32

Round down to a whole number.

Returns

The largest whole number not greater than this, as a float32.

Examples

float32 pos = 2.5;
float32 neg = -2.5;
console.writeln(pos.floor());
console.writeln(neg.floor());
Run it ▶
2.000000
-3.000000

See also: ceil

isInfinite

isInfinite() -> bool

Test whether the value is positive or negative infinity.

A float32 becomes infinite when an operation produces a magnitude above the largest finite value, about 3.4 times 10 to the 38th power. NaN is not infinite.

Returns

true when this is infinity or negative infinity.

Examples

float32 big = 1000000.0;
console.writeln(big.isInfinite());
console.writeln((big * big * big * big * big * big * big * big).isInfinite());
float32 zero = 0.0;
console.writeln((zero / zero).isInfinite());
Run it ▶
false
true
false

isNaN

isNaN() -> bool

Test whether the value is NaN.

NaN (not a number) is what an undefined operation produces, such as the square root of a negative number. NaN is the only value that is not equal to itself, so x.isNaN() is the reliable test.

Returns

true when this is NaN.

Examples

float32 one = 1.0;
console.writeln(one.isNaN());
float32 zero = 0.0;
console.writeln((zero / zero).isNaN());
console.writeln(float32::fromBits(2143289344).isNaN());
Run it ▶
false
true
true

pow

pow(float32 e) -> float32

Raise the value to a power.

The result is computed in higher precision and rounded to the nearest float32. A result beyond the largest finite value is infinity.

Parameters

e
The exponent.

Returns

this to the power e, rounded to a float32.

Examples

float32 two = 2.0;
float32 ten = 10.0;
console.writeln(two.pow(ten));
float32 big = 1000000.0;
console.writeln(big.pow(big));
Run it ▶
1024.000000
inf

round

round() -> float32

Round to the nearest whole number.

A value exactly halfway between two whole numbers rounds away from zero, so 2.5 becomes 3 and -2.5 becomes -3.

Returns

The nearest whole number, as a float32.

Examples

float32 pos = 2.5;
float32 neg = -2.5;
console.writeln(pos.round());
console.writeln(neg.round());
Run it ▶
3.000000
-3.000000

See also: trunc

sqrt

sqrt() -> float32

Compute the square root.

The result is rounded to the nearest float32. The square root of a negative number is NaN; it does not throw.

Returns

The square root of this, as a float32.

Examples

float32 nine = 9.0;
console.writeln(nine.sqrt());
float32 two = 2.0;
console.writeln(two.sqrt());
float32 minusOne = -1.0;
console.writeln(minusOne.sqrt());
Run it ▶
3.000000
1.414214
nan

toFloat

toFloat() -> float

Convert the float32 to a float.

The conversion is exact: every value of a float32 is representable as a float, so nothing is rounded. Converting a float back with float.toFloat32() rounds to the nearest float32 and throws when the value is out of range.

Returns

The value as a float.

Examples

float32 p = 0.1;
console.writeln(p.toFloat() == 0.1);
console.writeln(p.toFloat() > 0.1);
float32 half = 0.5;
console.writeln(half.toFloat() == 0.5);
Run it ▶
false
true
true

See also: toFloat32

toInt

toInt() -> int

Convert the float32 to an int, discarding the fraction.

The value is truncated toward zero, so -2.5 becomes -2.

Returns

The whole-number part of this as an int.

Throws

RuntimeException
when the value is NaN or infinite.

Examples

float32 v = -2.5;
console.writeln(v.toInt());
float32 big = 3000000000.5;
console.writeln(big.toInt());
float32 inf = float32::fromBits(2139095040);
try {
    console.writeln(inf.toInt());
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}
Run it ▶
-2
3000000000
caught: float is not finite or out of int64 range for toInt()

toString

toString() -> string

Format the float32 as decimal text.

The text is the six-decimal form that float prints, for example 3.500000, computed from the value actually stored, so a number that is not exactly representable shows its rounded value. NaN prints as nan and infinity as inf or -inf.

Returns

The decimal text of this.

Examples

float32 p = 0.1;
console.writeln(p.toString());
float32 y = 3.5;
console.writeln("y = " + y.toString());
Run it ▶
0.100000
y = 3.500000

trunc

trunc() -> float32

Discard the fraction.

Returns

The whole-number part of this, rounded toward zero, as a float32.

Examples

float32 pos = 2.5;
float32 neg = -2.5;
console.writeln(pos.trunc());
console.writeln(neg.trunc());
Run it ▶
2.000000
-2.000000

See also: floor