Skip to content

std::float

Operations on the IEEE 754 double-precision Float type: the special values (nan, ±infinity), the constants pi and e, classification predicates, rounding, powers, roots, logarithms, trigonometry, and conversion to Int. Its Equatable, Hashable and Comparable impls give Float a total order and hashing that agrees with == (NaN equals NaN, and -0.0 equals 0.0).

Float.format and Float.format_percent write a float as a reader of a locale writes it, and Float.parse_in and Float.parse_percent_in read it back, by the rules std::int’s page gives for formatting and parsing numbers.

Import with import std::float.

type Float

64-bit floating point number.

fn nan() -> Float

type function on Float

Returns IEEE 754 NaN (“not a number”). Produced by indeterminate operations like 0.0 / 0.0. NaN propagates through arithmetic and comparisons; use Float.is_nan to test for it.

assert Float.is_nan(Float.nan())
fn positive_infinity() -> Float

type function on Float

Returns IEEE 754 positive infinity. Produced by overflow and by dividing a positive Float by 0.0. Use Float.is_infinite to test for it.

assert Float.is_infinite(Float.positive_infinity())
fn negative_infinity() -> Float

type function on Float

Returns IEEE 754 negative infinity. Produced by overflow and by dividing a negative Float by 0.0. Use Float.is_infinite to test for it.

assert Float.is_infinite(Float.negative_infinity())
once pi: PositiveFloat = 3.141592653589793

The Float nearest π, the ratio of a circle’s circumference to its diameter: 3.141592653589793.

assert Float.pi == 3.141592653589793
assert Float.cos(Float.pi) == -1.0
once e: PositiveFloat = 2.718281828459045

The Float nearest e, the base of the natural logarithm: 2.718281828459045.

assert Float.e == 2.718281828459045
assert Float.log(Float.e) == 1.0
fn is_nan(x: Float) -> Bool

type function on Float

True if x is NaN.

assert Float.is_nan(Float.nan())
refute Float.is_nan(1.0)
fn is_infinite(x: Float) -> Bool

type function on Float

True if x is +Infinity or -Infinity.

assert Float.is_infinite(Float.positive_infinity())
refute Float.is_infinite(42.0)
fn is_finite(x: Float) -> Bool

type function on Float

True if x is a finite number: not NaN and not ±Infinity.

assert Float.is_finite(42.0)
refute Float.is_finite(Float.nan())
refute Float.is_finite(Float.negative_infinity())
fn to_int(x: Float) -> Maybe<Int>

type function on Float

Converts a Float to an Int by truncating toward zero, exactly at any magnitude. Returns None for NaN and ±Infinity. Use Float.round/floor/ceil first if a different rounding rule is needed.

assert Float.to_int(3.7) == Maybe.Some(3)
assert Float.to_int(-3.7) == Maybe.Some(-3)
assert Float.to_int(42.0) == Maybe.Some(42)
assert Float.to_int(1.0e20) == Maybe.Some(100_000_000_000_000_000_000)
assert Float.to_int(Float.nan()) == Maybe.None
fn to_decimal(x: Float, scale: Int, mode: RoundingMode) -> Maybe<Decimal>

type function on Float

Converts a Float to a Decimal at exactly scale fractional digits, rounding the Float’s exact binary value with mode. The scale and mode are required so it never hands back 0.1000…0055 silently. Returns None for NaN and ±Infinity. A scale past Decimal’s, -2147483648 to 2147483647, traps.

assert Float.to_decimal(0.1, 2, RoundingMode.HalfEven) == Maybe.Some(0.10d)
assert Float.to_decimal(3.14159, 2, RoundingMode.Floor) == Maybe.Some(3.14d)
fn round(x: Float, scale: Int = 0, mode: RoundingMode = RoundingMode.HalfEven) -> Float

type function on Float

Rounds x to scale digits after the decimal point by mode: Float.round(x) is the nearest integer-valued Float, half to even (banker’s rounding), and a negative scale rounds to tens, hundreds and so on. The modes are Decimal.round’s. NaN and ±Infinity pass through unchanged, and a result of zero keeps x’s sign.

A Float is binary, so most decimal fractions are not exactly one: 2.675 is 2.67499999999999982236431605997495353221893310546875, which rounds to 2.67 at scale 2 even under HalfUp. The rounding is of that exact value, and the result is the Float nearest the rounded decimal, so Float.round(0.125, 2) prints 0.12 but is not exactly 0.12 either. Round a Decimal when the decimal digits must be exact.

import std::decimal.RoundingMode

assert Float.round(3.5) == 4.0
assert Float.round(2.5) == 2.0
assert Float.round(3.7) == 4.0
assert Float.round(3.14159, 2) == 3.14
assert Float.round(1234.5, -2) == 1200.0
assert Float.round(2.5, 0, RoundingMode.HalfUp) == 3.0
assert Float.round(2.675, 2, RoundingMode.HalfUp) == 2.67
assert Float.round(-0.4) == 0.0
fn floor(x: Float) -> Float

type function on Float

Rounds a Float toward -∞. NaN and ±Infinity pass through unchanged.

assert Float.floor(3.7) == 3.0
assert Float.floor(-3.2) == -4.0
fn ceil(x: Float) -> Float

type function on Float

Rounds a Float toward +∞. NaN and ±Infinity pass through unchanged.

assert Float.ceil(3.2) == 4.0
assert Float.ceil(-3.7) == -3.0
fn trunc(x: Float) -> Float

type function on Float

Rounds a Float toward zero. NaN and ±Infinity pass through unchanged.

assert Float.trunc(3.7) == 3.0
assert Float.trunc(-3.7) == -3.0
fn abs(x: Float) -> Float

type function on Float

Returns |x|, with the sign bit cleared: -0.0 gives 0.0, either infinity gives +Infinity, and NaN gives NaN.

assert Float.abs(-1.5) == 1.5
assert Float.to_string(Float.abs(-0.0)) == "0.0"
assert Float.abs(Float.negative_infinity()) == Float.positive_infinity()
assert Float.is_nan(Float.abs(Float.nan()))
fn equal_within(a: Float, b: Float, tolerance: NonNegativeFloat) -> Bool

type function on Float

Whether a and b differ by at most tolerance: a == b, or Float.abs(a - b) <= tolerance. Use it where a computed Float should equal a known one, since == compares every bit and most results carry rounding error (Float.pow(8.0, 4.0 / 3.0) is 15.999999999999998, not 16.0). The tolerance is absolute and the caller picks it. Two equal infinities are equal; a NaN is equal within no tolerance to anything, itself included, though Float.nan() == Float.nan() holds. The tolerance is a NonNegativeFloat, so it is never negative or NaN.

assert Float.equal_within(Float.pow(8.0, 4.0 / 3.0), 16.0, 1e-12)
refute Float.pow(8.0, 4.0 / 3.0) == 16.0
assert Float.equal_within(1.5, 1.5, 0.0)
refute Float.equal_within(1.0, 1.1, 0.05)
assert Float.equal_within(Float.positive_infinity(), Float.positive_infinity(), 0.0)
refute Float.equal_within(Float.positive_infinity(), Float.negative_infinity(), 1e300)
refute Float.equal_within(Float.nan(), Float.nan(), 1.0)
fn sign(x: Float) -> Int

type function on Float

Returns the sign of x as -1, 0, or +1. Both zeros give 0, and so does NaN, which is neither less than nor greater than zero; test for it with Float.is_nan first when it must be told apart from zero.

assert Float.sign(-1.5) == -1
assert Float.sign(-0.0) == 0
assert Float.sign(Float.positive_infinity()) == 1
assert Float.sign(Float.nan()) == 0
fn pow(x: Float, y: Float) -> Float

type function on Float

x raised to the power y, with IEEE 754’s results at the edges: Float.pow(x, 0.0) and Float.pow(1.0, y) are 1.0 for every x and y, NaN included; a negative x to a y that is not a whole number is NaN; 0.0 to a negative y is +Infinity; and a result past the Float range is ±Infinity. Int.pow is the exact power of two Ints.

assert Float.pow(2.0, 10.0) == 1024.0
assert Float.pow(4.0, 0.5) == 2.0
assert Float.pow(Float.nan(), 0.0) == 1.0
assert Float.is_nan(Float.pow(-8.0, 1.0 / 3.0))
assert Float.pow(0.0, -1.0) == Float.positive_infinity()
fn sqrt(x: Float) -> Float

type function on Float

The square root of x: NaN for a negative x, -0.0 for -0.0, and +Infinity for +Infinity.

assert Float.sqrt(2.25) == 1.5
assert Float.is_nan(Float.sqrt(-1.0))
assert Float.to_string(Float.sqrt(-0.0)) == "-0.0"
fn exp(x: Float) -> Float

type function on Float

e raised to the power x: +Infinity past the Float range, 0.0 below it, and 0.0 for -Infinity.

assert Float.exp(0.0) == 1.0
assert Float.exp(1000.0) == Float.positive_infinity()
assert Float.exp(Float.negative_infinity()) == 0.0
fn log(x: Float) -> Float

type function on Float

The natural logarithm of x, to base e: -Infinity for 0.0, NaN for a negative x, and +Infinity for +Infinity.

assert Float.log(1.0) == 0.0
assert Float.log(Float.exp(2.0)) == 2.0
assert Float.log(0.0) == Float.negative_infinity()
assert Float.is_nan(Float.log(-1.0))
fn log2(x: Float) -> Float

type function on Float

The base-2 logarithm of x, exact at a power of two, with Float.log’s results at 0.0, a negative x and the infinities.

assert Float.log2(8.0) == 3.0
assert Float.log2(0.5) == -1.0
fn log10(x: Float) -> Float

type function on Float

The base-10 logarithm of x, with Float.log’s results at 0.0, a negative x and the infinities.

assert Float.log10(1000.0) == 3.0
assert Float.log10(0.0) == Float.negative_infinity()
fn sin(x: Float) -> Float

type function on Float

The sine of the angle x in radians. NaN for an infinity or NaN.

assert Float.sin(0.0) == 0.0
assert Float.sin(Float.atan2(1.0, 0.0)) == 1.0
assert Float.is_nan(Float.sin(Float.positive_infinity()))
fn cos(x: Float) -> Float

type function on Float

The cosine of the angle x in radians. NaN for an infinity or NaN.

assert Float.cos(0.0) == 1.0
assert Float.cos(Float.atan2(0.0, -1.0)) == -1.0
fn tan(x: Float) -> Float

type function on Float

The tangent of the angle x in radians. NaN for an infinity or NaN.

assert Float.tan(0.0) == 0.0
assert Float.is_nan(Float.tan(Float.negative_infinity()))
fn atan2(y: Float, x: Float) -> Float

type function on Float

The angle in radians, from -π to π, between the positive x axis and the point (x, y). The y argument comes first, as in C, Go and Python. The quadrant comes from both signs, so Float.atan2(0.0, -1.0) is π, and the signed zeros follow IEEE 754: Float.atan2(-0.0, -1.0) is -π. NaN when either is NaN.

assert Float.atan2(0.0, 1.0) == 0.0
assert Float.atan2(1.0, 1.0) * 4.0 == Float.atan2(0.0, -1.0)
assert Float.atan2(-0.0, -1.0) == -Float.atan2(0.0, -1.0)
fn format(f: Float, locale: Locale, fraction: ClosedRange<NonNegativeInt> = 0..=3, grouping: Bool = True) -> String

type function on Float

f as a reader of locale writes it, with the digits after the decimal point held within fraction: rounded half to even to its end and padded with zeros to its start. fraction is one ClosedRange<NonNegativeInt>, so a negative count or a backwards range is a compile error. Rounding works on the shortest decimal that reads back as f, so 1.015 rounds to 1.02. Infinity and NaN are the locale’s symbols.

assert Float.format(1234567.891, Locale"en") == "1,234,567.891"
assert Float.format(1234567.89, Locale"de") == "1.234.567,89"
assert Float.format(1.5, Locale"fr", 2..=3) == "1,50"
assert Float.format(2.5, Locale"en", 0..=0) == "2"
assert Float.format(-1234.5, Locale"en", 0..=3, False) == "-1234.5"
assert Float.format(1234.5, Locale"fr", fraction: 2..=2) == "1\u{202f}234,50"
assert Float.format(1.015, Locale"en", fraction: 0..=2) == "1.02"
fn format_percent(f: Float, locale: Locale, max_fraction: NonNegativeInt = 0) -> String

type function on Float

f as a percentage in locale: f times 100, with the locale’s percent sign where the locale puts it, rounded half to even to at most max_fraction digits, a NonNegativeInt.

assert Float.format_percent(0.256, Locale"en") == "26%"
assert Float.format_percent(0.256, Locale"fr") == "26\u{a0}%"
assert Float.format_percent(0.256, Locale"de") == "26\u{a0}%"
assert Float.format_percent(0.256, Locale"tr") == "%26"
assert Float.format_percent(0.1234, Locale"en", 1) == "12.3%"
fn parse_in(text: String, locale: Locale, lenient: Bool = False) -> Result<Float, NumberParseError>

type function on Float

Read text a reader of locale wrote as a Float, strictly unless lenient: True, as Int.parse_in reads an Int. The locale’s infinity and NaN symbols read as infinity and NaN; digits that overflow to infinity are OutOfRange.

assert Float.parse_in("1.234,5", Locale"de") == Ok(1234.5)
assert Float.parse_in("1.234,5", Locale"en") == Err(NumberParseError.Unexpected{at: 5, text: ","})
assert Float.parse_in("∞", Locale"en") == Ok(Float.positive_infinity())
assert Float.parse_in("-∞", Locale"en") == Ok(Float.negative_infinity())
assert Float.parse_in("1" + String.repeat("0", 400), Locale"en") == Err(NumberParseError.OutOfRange)
fn parse_percent_in(text: String, locale: Locale, lenient: Bool = False) -> Result<Float, NumberParseError>

type function on Float

Read a percentage a reader of locale wrote, as a fraction: 12,5 % is 0.125. The percent sign is required, where the locale puts it unless lenient: True, as Decimal.parse_percent_in reads one.

assert Float.parse_percent_in("12,5\u{a0}%", Locale"de") == Ok(0.125)
assert Float.parse_percent_in("%50", Locale"tr") == Ok(0.5)

assert Float.parse_percent_in("12.5", Locale"en")
    == Err(NumberParseError.Unexpected{at: 4, text: ""})

impl Display for Float

fn to_string(x: Float) -> String

impl Display.to_string

Returns x as text, what io.print and string interpolation write: a whole number keeps its .0, NaN is NaN, and the infinities are +Inf and -Inf.

assert Float.to_string(3.14) == "3.14"
assert Float.to_string(1e20) == "100000000000000000000.0"

impl Add<Float, Float> for Float

fn add(lhs: Float, rhs: Float) -> Float

impl Add.add

impl Summable for Float

fn empty_sum() -> Float

impl Summable.empty_sum

The sum of no Floats: 0.0. x + 0.0 is x for every Float but -0.0, which it turns into 0.0 (equal under ==).

assert Float.empty_sum() == 0.0
assert 2.5 + Float.empty_sum() == 2.5

impl Subtract<Float, Float> for Float

fn subtract(lhs: Float, rhs: Float) -> Float

impl Subtract.subtract

impl Multiply<Float, Float> for Float

fn multiply(lhs: Float, rhs: Float) -> Float

impl Multiply.multiply

impl Productable for Float

fn empty_product() -> Float

impl Productable.empty_product

The product of no Floats: 1.0. x * 1.0 is x for every Float, NaN and the infinities included.

assert Float.empty_product() == 1.0
assert 2.5 * Float.empty_product() == 2.5

impl Divide<Float, Float> for Float

fn divide(lhs: Float, rhs: Float) -> Float

impl Divide.divide

lhs / rhs by IEEE 754. The divisor may be zero: a nonzero lhs over 0.0 is an infinity and 0.0 / 0.0 is NaN, so it never traps.

assert 1.0 / 4.0 == 0.25
assert 1.0 / 0.0 == Float.positive_infinity()
assert Float.is_nan(0.0 / 0.0)

impl Remainder<Float, Float> for Float

fn remainder(lhs: Float, rhs: Float) -> Float

impl Remainder.remainder

lhs % rhs: IEEE 754’s fmod, lhs - rhs * trunc(lhs / rhs) computed exactly, so it takes the sign of lhs and never traps. A zero rhs or an infinite lhs gives NaN, and an infinite rhs gives lhs.

assert 7.5 % 2.0 == 1.5
assert -7.5 % 2.0 == -1.5
assert 7.5 % -2.0 == 1.5
assert Float.is_nan(1.0 % 0.0)
assert Float.is_nan(Float.positive_infinity() % 2.0)
assert 3.0 % Float.positive_infinity() == 3.0

impl Debug for Float

fn inspect(x: Float) -> String

impl Debug.inspect

The same text as Display (3.14): a Float’s literal is its user-facing form.

assert Debug.inspect(3.14) == Display.to_string(3.14)

impl Equatable for Float

fn equal(a: Float, b: Float) -> Bool

impl Equatable.equal

impl Hashable for Float

fn hash(x: Float) -> Int

impl Hashable.hash

impl Comparable for Float

fn compare(a: Float, b: Float) -> Ordering

impl Comparable.compare

impl Comparable for Float

fn min(a: Float, b: Float) -> Float

impl Comparable.min

The lesser of a and b: NaN if either is NaN, and -0.0 as the lesser of the two zeros (IEEE 754-2019 minimum). Other ties return a. It overrides Comparable.min, which by compare would put NaN above every number.

assert Float.min(1.5, -2.0) == -2.0
assert Float.to_string(Float.min(0.0, -0.0)) == "-0.0"
assert Float.is_nan(Float.min(Float.nan(), 1.0))
assert Float.is_nan(Comparable.min(1.0, Float.nan()))

impl Comparable for Float

fn max(a: Float, b: Float) -> Float

impl Comparable.max

The greater of a and b: NaN if either is NaN, and 0.0 as the greater of the two zeros (IEEE 754-2019 maximum). Other ties return a. It overrides Comparable.max.

assert Float.max(1.5, -2.0) == 1.5
assert Float.to_string(Float.max(-0.0, 0.0)) == "0.0"
assert Float.is_nan(Float.max(1.0, Float.nan()))

impl Comparable for Float

fn clamp(value: Float, range: ClosedRange<Float>) -> Float

impl Comparable.clamp

value held to range, both ends included. A NaN value stays NaN, as every IEEE operation on one does; compare would put it above the end and return the end, a number nobody asked for. A range with a NaN end holds no value, so it is no ClosedRange and ClosedRange.try_from answers None for it; no literal is NaN. Within the range the value comes back as it is, so -0.0 held to 0.0..=1.0 stays -0.0.

assert Float.clamp(1.5, 0.0..=1.0) == 1.0
assert Float.clamp(-0.5, 0.0..=1.0) == 0.0
assert Float.clamp(0.25, 0.0..=1.0) == 0.25
assert Float.is_nan(Float.clamp(Float.nan(), 0.0..=1.0))
assert Float.clamp(Float.positive_infinity(), 0.0..=1.0) == 1.0
assert ClosedRange.try_from(0.0..=Float.nan()) == Maybe.None
subtype NonZeroFloat Float when fn x -> x != 0.0 and not Float.is_nan(x)

A Float that is not zero and not NaN, so dividing by one gives a number or an infinity, never NaN from 0.0 / 0.0. A literal is checked when the program is compiled; NonZeroFloat.try_from(x) checks a value at run time. It is in the prelude.

subtype: NonZeroFloat is a subtype of Float. A literal where a NonZeroFloat is expected is checked when the program is compiled; NonZeroFloat.try_from(...) checks a value when it runs.

d: NonZeroFloat = -2.0
assert 3.0 / d == -1.5
assert NonZeroFloat.try_from(0.0) == Maybe.None
assert NonZeroFloat.try_from(Float.nan()) == Maybe.None
fn try_from(value: Float) -> Maybe<NonZeroFloat>

type function on NonZeroFloat

Some of the value when it satisfies NonZeroFloat’s rules, None when it does not.

subtype NonNegativeFloat Float when fn x -> x >= 0.0

A Float that is zero or more: never negative, and never NaN, which compares as neither. A literal is checked when the program is compiled; NonNegativeFloat.try_from(x) checks a value at run time. A NonNegativeFloat is a Float, and passes wherever one is expected. It is in the prelude.

subtype: NonNegativeFloat is a subtype of Float. A literal where a NonNegativeFloat is expected is checked when the program is compiled; NonNegativeFloat.try_from(...) checks a value when it runs.

t: NonNegativeFloat = 0.5
assert t + 1.0 == 1.5
assert NonNegativeFloat.try_from(0.0) == Maybe.Some(0.0)
assert NonNegativeFloat.try_from(-0.5) == Maybe.None
assert NonNegativeFloat.try_from(Float.nan()) == Maybe.None
fn try_from(value: Float) -> Maybe<NonNegativeFloat>

type function on NonNegativeFloat

Some of the value when it satisfies NonNegativeFloat’s rules, None when it does not.

subtype PositiveFloat NonNegativeFloat and NonZeroFloat when fn x -> x > 0.0

A Float greater than zero. It refines both NonNegativeFloat and NonZeroFloat, so a PositiveFloat passes wherever either, or a Float, is expected. It is in the prelude.

subtype: PositiveFloat is a subtype of NonNegativeFloat and NonZeroFloat, and through them Float. A literal where a PositiveFloat is expected is checked when the program is compiled; PositiveFloat.try_from(...) checks a value when it runs.

assert PositiveFloat.try_from(2.5) == Maybe.Some(2.5)
assert PositiveFloat.try_from(0.0) == Maybe.None
fn try_from(value: Float) -> Maybe<PositiveFloat>

type function on PositiveFloat

Some of the value when it satisfies PositiveFloat’s rules, None when it does not.