Standard Library

class float16

A 16-bit floating-point number in the IEEE 754 binary16 format: 1 sign bit, 5 exponent bits and 10 mantissa bits.

since 0.1.0-alpha.1linuxwindowswasm

Overview

A float16 has about three significant decimal digits. The largest finite value is 65504 and the smallest positive normal value is about 0.000061. An operation whose result is above 65504 gives infinity, and operations with no defined result, such as 0.0 / 0.0, give NaN. Every arithmetic result is rounded to the nearest float16 (ties to even) after each operation, so 2000.0 + 49.0 is 2048. 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 float16 is rounded to the nearest value and a literal above 65504 is a compile error. float.toFloat16() converts a float and throws when the value is out of range. toFloat() converts back exactly.

Examples

Rounding, range and NaN

float16 h = 0.1;
console.writeln(h);
console.writeln(h.toFloat() == 0.1);
float16 a = 2000.0;
float16 b = 49.0;
console.writeln(a + b);
float16 big = 65504.0;
float16 two = 2.0;
console.writeln((big * two).isInfinite());
float tooBig = 70000.0;
try {
    console.writeln(tooBig.toFloat16());
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}

0.099976
false
2048.000000
true
caught: toFloat16: value out of range (max finite 65504)

Methods

abs

abs() -> float16

Return the absolute value.

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

Returns

this with its sign removed, as a float16.

Examples

float16 neg = -2.5;
console.writeln(neg.abs());
float16 negZero = float16::fromBits(32768);
console.writeln(negZero.abs().bits());

2.500000
0

bits

bits() -> int

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

The result is the raw interchange bits of the format (1 sign bit, then 5 exponent bits, then 10 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.float16FromBits turns bits back into a float16 and is also written float16::fromBits.

Returns

The bit pattern of this.

Examples

float16 one = 1.0;
console.writeln(one.bits());
float16 big = 65504.0;
console.writeln(big.bits());
float16 h = 0.1;
console.writeln(h.bits());
console.writeln(float16::fromBits(15360) == one);

See also: float16FromBits

canonEq

canonEq(float16 other) -> bool

Compare two float16 values by their canonical form.

This is the relation used when a float16 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

float16 nan = float16::fromBits(32256);
console.writeln(nan == nan);
console.writeln(nan.canonEq(nan));
float16 zero = 0.0;
float16 negZero = float16::fromBits(32768);
console.writeln(zero == negZero);
console.writeln(zero.canonEq(negZero));
console.writeln(zero.bits());
console.writeln(negZero.bits());

false
true
true
true
0
32768

ceil

ceil() -> float16

Round up to a whole number.

Returns

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

Examples

float16 pos = 2.5;
float16 neg = -2.5;
console.writeln(pos.ceil());
console.writeln(neg.ceil());

3.000000
-2.000000

See also: floor

floor

floor() -> float16

Round down to a whole number.

Returns

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

Examples

float16 pos = 2.5;
float16 neg = -2.5;
console.writeln(pos.floor());
console.writeln(neg.floor());

2.000000
-3.000000

See also: ceil

isInfinite

isInfinite() -> bool

Test whether the value is positive or negative infinity.

A float16 becomes infinite when an operation produces a magnitude above the largest finite value, 65504. NaN is not infinite.

Returns

true when this is infinity or negative infinity.

Examples

float16 big = 65504.0;
float16 two = 2.0;
console.writeln(big.isInfinite());
console.writeln((big * two).isInfinite());
console.writeln((-(big * two)).isInfinite());
float16 zero = 0.0;
console.writeln((zero / zero).isInfinite());

false
true
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

float16 one = 1.0;
console.writeln(one.isNaN());
float16 zero = 0.0;
console.writeln((zero / zero).isNaN());
console.writeln(float16::fromBits(32256).isNaN());

false
true
true

pow

pow(float16 e) -> float16

Raise the value to a power.

The result is computed in higher precision and rounded to the nearest float16. A result above 65504 is infinity.

Parameters

e: The exponent.

Returns

this to the power e, rounded to a float16.

Examples

float16 two = 2.0;
console.writeln(two.pow(two));
float16 ten = 10.0;
float16 three = 3.0;
console.writeln(ten.pow(three));
float16 big = 65504.0;
console.writeln(big.pow(two));

4.000000
1000.000000
inf

round

round() -> float16

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

Examples

float16 pos = 2.5;
float16 neg = -2.5;
console.writeln(pos.round());
console.writeln(neg.round());

3.000000
-3.000000

See also: trunc

sqrt

sqrt() -> float16

Compute the square root.

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

Returns

The square root of this, as a float16.

Examples

float16 nine = 9.0;
console.writeln(nine.sqrt());
float16 two = 2.0;
console.writeln(two.sqrt());
float16 minusOne = -1.0;
console.writeln(minusOne.sqrt());

3.000000
1.414062
nan

toFloat

toFloat() -> float

Convert the float16 to a float.

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

Returns

The value as a float.

Examples

float16 h = 0.1;
console.writeln(h.toFloat());
console.writeln(h.toFloat() == 0.1);

0.099976
false

See also: toFloat16

toInt

toInt() -> int

Convert the float16 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

float16 v = -2.5;
console.writeln(v.toInt());
float16 big = 65504.0;
console.writeln(big.toInt());
float16 inf = float16::fromBits(31744);
try {
    console.writeln(inf.toInt());
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}

-2
65504
caught: float is not finite or out of int64 range for toInt()

toString

toString() -> string

Format the float16 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

float16 h = 0.1;
console.writeln(h.toString());
float16 y = 3.5;
console.writeln("y = " + y.toString());

0.099976
y = 3.500000

trunc

trunc() -> float16

Discard the fraction.

Returns

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

Examples

float16 pos = 2.5;
float16 neg = -2.5;
console.writeln(pos.trunc());
console.writeln(neg.trunc());

2.000000
-2.000000

See also: floor