std/number/lib

Zero of this type: what a sum starts from, and what a generic body compares against. Scalar.zero reads it through a type parameter, Int.zero and Float.zero through the type.

One of this type: what a product starts from, and the unit of an identity matrix or a homogeneous coordinate.

The value without its sign.

Half a turn in radians - the ratio of a circle's circumference to its diameter - in this scalar's type: Scalar.pi in a body that is generic over it, whose literals could not write the digits.

A whole turn in radians, twice Real.pi, rounded once in this scalar's type rather than doubled.

The base of the natural logarithm, in this scalar's type: Scalar.e, named like Real.pi.

The gap between one and the next value this scalar can hold: the resolution a tolerance cannot go below. It is the machine epsilon of a float and the one part of a fixed-point number.

The non-negative square root. Negative input answers a value the implementor documents.

The sine of an angle in radians.

The cosine of an angle in radians.

The tangent of an angle in radians.

The angle in radians whose sine is this value, in [-pi/2, pi/2].

Outside [-1, 1], where no angle has this sine. The precondition is an ordinary expression, value.absolute() <= Scalar.one, so a value outside is a broken promise of the program and every implementor stops there rather than answering a number (docs/design/PANICS.md, 5.1). value.clamp(-Scalar.one, Scalar.one) first is the total form, for a ratio that rounding pushed a hair past one.

The angle in radians whose cosine is this value, in [0, pi].

Outside [-1, 1], as Real.arcSine says.

The angle in radians whose tangent is this value, in (-pi/2, pi/2).

The angle in radians of the point (by, self), in (-pi, pi]: the arc tangent of self / by that uses the sign of both to pick the quadrant. This is what turns a vector into a direction, and it is why it takes a label - y.arcTangentDivided(by: x) says which of the two is which, where a bare pair of arguments does not.

Real.e raised to this value: Scalar.e ** value, without a logarithm of e in between.

The logarithm to the base Real.e. Zero and a negative value answer what the implementor documents.

The logarithm to another base: (8.0).logarithm(base: 2.0) is 3.0. It is the natural logarithm of the value over the one of the base, so an implementor that has a faster way overrides it.

Rounded towards negative infinity.

Rounded towards positive infinity.

Rounded to the nearest whole value, halves away from zero.

Half the value. It is a member and not value / 2 at the call, because a body that is generic over the scalar cannot write the literal 2 at all: a literal has a type, and inside such a body that type is the parameter. Halving is what a midpoint, a radius and an average are made of, so the trait carries it.

Twice the value.

The angle in radians that this many degrees is.

Degrees are a member of the scalar and not a function of std/linear, because the conversion needs the value of pi in this scalar's type - and a body that is generic over the scalar can write neither pi nor 180. Each implementor carries its own exact factor.

The angle in degrees that this many radians is.

Bit-for-bit and. This is &.

Bit-for-bit or. This is |.

Bit-for-bit exclusive or. This is ^.

Every bit flipped. This is the prefix ~.

Shifted towards the high bits. This is <<.

Shifted towards the low bits: arithmetic for a signed type, logical for an unsigned one. This is >>.

The smallest value of the type.

The largest value of the type.

self + other, or None where the sum does not fit the type.

self - other, or None where the difference does not fit the type.

self * other, or None where the product does not fit the type.

self / other, or None for a zero divisor and for the smallest value of a signed type divided by -1.

self % other, or None where self / other would be None as well.

The text that does not describe a number. Every conversion that fails with it names its parameter text, which is what lets a back end build the failure without knowing anything about this type (docs/BACKEND.md, "the parameter of the same name").

What went out of range.

Zero, the Numeric.zero of an Int8.

One, the Numeric.one of an Int8.

The smallest Int8.

The largest Int8.

Zero, the Numeric.zero of an Int16.

One, the Numeric.one of an Int16.

The smallest Int16.

The largest Int16.

Zero, the Numeric.zero of an Int32.

One, the Numeric.one of an Int32.

The smallest Int32.

The largest Int32.

Zero, the Numeric.zero of a UInt8.

One, the Numeric.one of a UInt8.

Always 0.

The largest UInt8.

Zero, the Numeric.zero of a UInt16.

One, the Numeric.one of a UInt16.

Always 0.

The largest UInt16.

Zero, the Numeric.zero of a UInt32.

One, the Numeric.one of a UInt32.

Always 0.

The largest UInt32.

Zero, the Numeric.zero of an Float32.

One, the Numeric.one of an Float32.

"Not a number" - the one value for which == is never true, not even with itself. See Float64.nan.

Larger than every finite Float32. Float32.negativeInfinity is smaller than every finite one.

Smaller than every finite Float32, the one value below every finite one.

Whether the value is Float32.infinity or Float32.negativeInfinity.

Whether the value is neither nan nor infinite.

The IEEE-754 binary32 pattern of the value: the sign in the top bit, then eight bits of exponent and 23 of mantissa. Nothing is converted, so -0.0, a subnormal and a nan with a payload keep every bit, and Float32.ofBits gives the same value back: 1.0 is 0x3f800000.

The Float32 whose IEEE-754 binary32 pattern is bits, the inverse of Float32.bits. Every pattern is a Float32, a signalling nan included, and keeps its bits on the way back.

Zero, the Numeric.zero of an Decimal.

One, the Numeric.one of an Decimal.

To the nearest, a tie to the neighbour with an even last digit. The mode of /, banker's rounding.

To the nearest, a tie away from zero: 2.5 is 3 and -2.5 is -3. What a person at a till does.

Towards zero: the digits are cut off.

Away from zero: any dropped non-zero digit raises the magnitude.

Towards negative infinity.

Towards positive infinity.

The value with exactly scale digits after the point. A larger scale than the current one adds zeros and rounds nothing (2.5 at 3 is 2.500); a smaller one drops digits by rounding; a negative one rounds to tens or hundreds (1250 at -2 with Rounding.HalfEven is 1200).

The exact quotient rounded once to scale: 1 / 3 at scale 2 with Rounding.Up is 0.34, where rounding the 34 digits of / again would give 0.33.

When by is zero, like /.

How many digits are after the point: 2 for 19.90, 0 for 42, and negative for 1e3.

The same value without the trailing zeros of its unscaled number, the scale lowered to match: 19.90 is 19.9, 1200 is 12 at scale -2. Equal values have one normalised form, which is what Hash is computed from.

When the lowered scale leaves Int32.

The unscaled whole number as text, with its sign: 1990 for 19.90, -5 for -0.05.

The value unscaled / 10^scale, the way back from Decimal.unscaledText and Decimal.scale. unscaled is an optional sign and decimal digits, nothing else; anything more fails with a NumberParseError.

Zero, the Numeric.zero of an Int64.

One, the Numeric.one of an Int64.

The smallest Int64 cannot be written as a positive literal negated (9223372036854775808 alone does not fit any integer type), so it is spelled the way C spells INT64_MIN: one more than the smallest literal there is.

The largest Int64.

Digits in another base: Int.parseDigits("ff", radix: 16). No sign, no prefix, _ is allowed between digits.

Zero, the Numeric.zero of a UInt64.

One, the Numeric.one of a UInt64.

Always 0.

18446744073709551615: all ones, which is the largest UInt64 there is.

Addition that wraps around instead of panicking. Together with UInt64.multipliedWrapping this is the only arithmetic in the language that does not panic on overflow, and it exists for one reason: a hash function mixes bits and needs the wrap. Everywhere else, overflow is a bug and + says so.

An integer literal is read in the type it is expected as, so the offset basis of FNV-1a, which is above the largest Int64, is written as it is:

const bytes: List<UInt64> = [104, 105]
var hash: UInt64 = 14695981039346656037
for byte in bytes {
  hash = (hash ^ byte).multipliedWrapping(1099511628211)
}
print hash

Multiplication that wraps around instead of panicking. See UInt64.addedWrapping.

Zero, the Numeric.zero of an Float64.

One, the Numeric.one of an Float64.

The ratio of a circle's circumference to its diameter: the Real.pi of a Float64.

A whole turn in radians, twice Float64.pi: the Real.tau of a Float64.

The gap between 1.0 and the next Float64, which is two to the power of minus 52: its Real.epsilon.

The base of the natural logarithm.

"Not a number" - the one value for which == is never true, not even with itself (Float64.isNaN). Named the way Real.pi is: the compile-time constant evaluator (ir/constant.trb) only allows this one declaration and Float32.nan to fold to it, because an ordinary expression that produces nan is a mistake and stays an error (docs/language/modules-and-packages/top-level-code.md, rule 6).

Larger than every finite Float64. Float64.negativeInfinity is smaller than every finite one.

Smaller than every finite Float64, the one value below every finite one.

The non-negative square root.

Rounded towards negative infinity.

Rounded towards positive infinity.

Rounded to the nearest integer.

Whether the value is "not a number" - the one value for which == is never true, not even with itself.

Whether the value is Float64.infinity or Float64.negativeInfinity.

Whether the value is neither nan nor infinite.

The IEEE-754 binary64 pattern of the value: the sign in the top bit, then eleven bits of exponent and 52 of mantissa. Nothing is converted, so -0.0, a subnormal and a nan with a payload keep every bit, and Float64.ofBits gives the same value back:

const value = 1.0
const pattern: UInt64 = 0x3ff0000000000000
assert(value.bits() == pattern)
assert(Float64.ofBits(pattern) == value)

The Float64 whose IEEE-754 binary64 pattern is bits, the inverse of Float64.bits. Every pattern is a Float64, a signalling nan included, and keeps its bits on the way back. A call is never folded into a constant: const x = Float64.ofBits(...) at the top level is an error, because what it makes may be a nan.

Floats are compared with a tolerance: assert(length.isCloseTo(1.0))

The exact comparisons a float has are deliberately different from each other, because IEEE-754 equality is not an equivalence relation and IEEE-754 ordering is not a total order:

• Every operator is IEEE-754: ==, <, <=, > and >=. nan != nan, every comparison with a nan on either side is false, and 0.0 == -0.0.
• compare is a total order: nan is above everything, and -0.0 compares equal to 0.0. So sorted terminates whatever pivot it picks, whatever is in the list.
• A float is therefore the one type where an operator and the member behind it disagree, which is why everything that orders values calls compare and never writes <=: an IEEE <= would leave a nan where it started.
• Float32 and Float64 are not Hash, so a float is never a Map key and the nan key does not exist.

The sine of an angle in radians.

The cosine of an angle in radians.

The tangent of an angle in radians.

In radians, in [-pi/2, pi/2]; nan answers nan.

Outside [-1, 1], where no angle has this sine, exactly as Fixed.arcSine of std/linear does: the two implementors of Real agree about every value both of them hold (docs/design/LINEAR.md, "Numeric policy"). A ratio that rounding pushed a hair past one is clamped at the call, ratio.clamp(-1.0, 1.0).arcSine(), which is the total form.

In radians, in [0, pi]; nan answers nan.

Outside [-1, 1], where no angle has this cosine, as Float64.arcSine says.

In radians, in (-pi/2, pi/2).

The angle of the point (by, self), which is C's atan2(self, by).

e raised to this value. An infinity where it does not fit, and never a panic.

The logarithm to the base e: -infinity at zero, nan below it, and never a panic.

As a whole number of bytes, which is exactly what it holds.

As a fraction of whole: memory.used().fraction(of: memory.total) is between 0 and 1. A whole of zero bytes answers what Float64 division by zero answers.

In kilobytes of 1000 bytes, as a disk is counted.

In megabytes of 1000 kilobytes.

In gigabytes of 1000 megabytes.

In terabytes of 1000 gigabytes.

In kibibytes of 1024 bytes, as a memory is counted.

In mebibytes of 1024 kibibytes.

In gibibytes of 1024 mebibytes.

In tebibytes of 1024 gibibytes.

Which of the two sizes is the smaller one.

The two sizes together. Panics where the sum does not fit, as every Int64 addition does.

How much larger this size is than other: negative where it is smaller.

The size other times over: 4.kibibytes() * 3. Panics where the product does not fit.

The largest binary unit with at least one of it, to one decimal: 512 B, 1.5 KiB, 15.9 GiB. Below 1024 bytes it is the whole number of bytes, and a negative size keeps its sign: -2.0 KiB.

A ByteSize of exactly this many bytes: 512.bytes().

A ByteSize of this many kilobytes of 1000 bytes: 4.kilobytes().

A ByteSize of this many megabytes of 1000 kilobytes: 64.megabytes(), the sandbox's default limit.

A ByteSize of this many gigabytes of 1000 megabytes.

A ByteSize of this many terabytes of 1000 gigabytes.

A ByteSize of this many kibibytes of 1024 bytes: 4.kibibytes(), a page of most systems.

A ByteSize of this many mebibytes of 1024 kibibytes.

A ByteSize of this many gibibytes of 1024 mebibytes.

A ByteSize of this many tebibytes of 1024 gibibytes.