Floating point¶
float64 is a 64-bit IEEE 754 binary floating-point number, the type of
every JSON number that is not a whole number.
Literals¶
A float literal has digits on both sides of a point, an exponent, or both:
1. and .5 are not literals: a point needs a digit after it, so that
1.to_str() still calls a method on the integer 1. Nothing else turns an
integer into a float; 2 is an int64 and 2.0 is a float64.
Operators¶
| Operator | Operands | Result |
|---|---|---|
+ - * / |
two float64 |
float64 |
-x |
a float64 |
float64 |
< <= > >= == != |
two float64 |
bool |
Nothing converts implicitly: 1.5 + 1 and n * 0.5 with n: int64 are
errors, and so is % on a float. Arithmetic follows IEEE 754 exactly, so
1.0 / 0.0 is infinity, 0.0 / 0.0 is not a number, and a not-a-number
value is unequal to everything, itself included (x != x is how to
test for one, or x.is_nan()). There is no trap on overflow or division by
zero.
A float64 is an ordinary value: it can be a variable, parameter, field,
array element ([float64]), optional (float64?) or a type argument
(Box[float64]). It cannot be a Map key or a Set member, because its
== is not an equivalence, and it has no literal pattern in a match.
Conversions and methods¶
| Method | Result |
|---|---|
n.to_float64() on an int64 |
the nearest float64 |
x.to_int64() |
x truncated toward zero; a not-a-number is 0 and an out-of-range value saturates to the int64 limits |
x.to_str() |
the shortest text that reads back as x (below) |
s.parse_float() on a str |
a float64?: none unless all of s is a decimal number, with an optional sign, a point and an exponent; inf, nan and hex are not accepted |
x.abs() x.floor() x.ceil() x.round() x.sqrt() |
the float64 they name; round rounds halves away from zero |
x.is_nan() x.is_inf() |
bool |
to_str gives the fewest digits that parse back to exactly x (rounded half
to even from its exact value, when more than one such text has that many
digits), and always shows it is a float: 2.0, not 2. Magnitudes from 1e-6 up to 1e21 are
written without an exponent (0.000001, 123456789.5); outside that range as
1e+21 and 1.5e-7. The special values are inf, -inf and nan. An
f-string uses to_str; print takes a str, so write print(x.to_str()).
parse_float gives the float64 nearest the decimal value, however many
digits it has; a value exactly halfway between two floats goes to the one whose
last bit is 0. A value beyond the largest float is infinity, and one below half
the smallest is zero, with the sign kept. Both directions are Kod, in
stdlib/primitives/float_text.kod, with exact arithmetic on integers wider
than 64 bits where a float can't be trusted.
print((0.1 + 0.2).to_str()) // 0.30000000000000004
print((1.0).to_str()) // 1.0
print((must "2.5e3".parse_float()).to_str()) // 2500.0
JSON¶
A JSON number that is not a whole int64 keeps its text in a
Decimal, so reading one as a float is parse_float on that text,
and writing one is to_str:
let text = must item.get("price").as_number_text()
let price = must text.parse_float()
let out = json.Value.Decimal(text: (price * 1.2).to_str())
to_str gives text that is a valid JSON number for every finite value. Infinity
and not-a-number have no JSON form: emit writes a Decimal whose text is not a
number as null, so inf and nan come out as null.
Representation¶
A float64 is the 8 bytes of its bit pattern, held in an ordinary register or
slot; the compiler moves it to a floating-point register only for the
operation. That is why it needs no new calling convention and an array of
them is an array of 8-byte words.