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.
Exports
Section titled “Exports”type Float
Section titled “type Float”type Float
64-bit floating point number.
Float.nan
Section titled “Float.nan”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())
Float.positive_infinity
Section titled “Float.positive_infinity”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())
Float.negative_infinity
Section titled “Float.negative_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())
Float.pi
Section titled “Float.pi”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
Float.e
Section titled “Float.e”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
Float.is_nan
Section titled “Float.is_nan”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)
Float.is_infinite
Section titled “Float.is_infinite”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)
Float.is_finite
Section titled “Float.is_finite”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())
Float.to_int
Section titled “Float.to_int”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
Float.to_decimal
Section titled “Float.to_decimal”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)
Float.round
Section titled “Float.round”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
Float.floor
Section titled “Float.floor”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
Float.ceil
Section titled “Float.ceil”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
Float.trunc
Section titled “Float.trunc”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
Float.abs
Section titled “Float.abs”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()))
Float.equal_within
Section titled “Float.equal_within”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)
Float.sign
Section titled “Float.sign”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
Float.pow
Section titled “Float.pow”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()
Float.sqrt
Section titled “Float.sqrt”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"
Float.exp
Section titled “Float.exp”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
Float.log
Section titled “Float.log”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))
Float.log2
Section titled “Float.log2”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
Float.log10
Section titled “Float.log10”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()
Float.sin
Section titled “Float.sin”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()))
Float.cos
Section titled “Float.cos”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
Float.tan
Section titled “Float.tan”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()))
Float.atan2
Section titled “Float.atan2”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)
Float.format
Section titled “Float.format”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"
Float.format_percent
Section titled “Float.format_percent”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%"
Float.parse_in
Section titled “Float.parse_in”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)
Float.parse_percent_in
Section titled “Float.parse_percent_in”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: ""})
Float.to_string
Section titled “Float.to_string”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"
Float.add
Section titled “Float.add”impl Add<Float, Float> for Float
fn add(lhs: Float, rhs: Float) -> Float
impl Add.add
Float.empty_sum
Section titled “Float.empty_sum”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
Float.subtract
Section titled “Float.subtract”impl Subtract<Float, Float> for Float
fn subtract(lhs: Float, rhs: Float) -> Float
impl Subtract.subtract
Float.multiply
Section titled “Float.multiply”impl Multiply<Float, Float> for Float
fn multiply(lhs: Float, rhs: Float) -> Float
impl Multiply.multiply
Float.empty_product
Section titled “Float.empty_product”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
Float.divide
Section titled “Float.divide”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)
Float.remainder
Section titled “Float.remainder”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
Float.inspect
Section titled “Float.inspect”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)
Float.equal
Section titled “Float.equal”impl Equatable for Float
fn equal(a: Float, b: Float) -> Bool
impl Equatable.equal
Float.hash
Section titled “Float.hash”impl Hashable for Float
fn hash(x: Float) -> Int
impl Hashable.hash
Float.compare
Section titled “Float.compare”impl Comparable for Float
fn compare(a: Float, b: Float) -> Ordering
impl Comparable.compare
Float.min
Section titled “Float.min”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()))
Float.max
Section titled “Float.max”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()))
Float.clamp
Section titled “Float.clamp”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
type NonZeroFloat
Section titled “type NonZeroFloat”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
NonZeroFloat.try_from
Section titled “NonZeroFloat.try_from”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.
type NonNegativeFloat
Section titled “type NonNegativeFloat”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
NonNegativeFloat.try_from
Section titled “NonNegativeFloat.try_from”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.
type PositiveFloat
Section titled “type PositiveFloat”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
PositiveFloat.try_from
Section titled “PositiveFloat.try_from”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.