Home / Docs / Specification / 29. Numerics
29.18 F32 and the finite kinds
(ADR 0120 rules 5 to 11 and V1.) F32, IEEE 754 binary32, under the rules of F64 with the substitutions below, and the refined kinds Finite64 and Finite32. This section applies only to packages of edition 0.5; in earlier editions F32, Finite64 and Finite32 are ordinary names, to_f32 resolves as any function name does, and the prelude has none of the names of rule 9.
-
The type.
F32is a built-in type: every binary32 value that is not a NaN, and one NaN, the canonical NaN ofF32, whose bits are0x7FC00000. Every rule of §1 to §14 applies toF32with these substitutions, and no other: the format binary32;to_bits()gives aU32; the bounds of rule 3; rendering and parsing at binary32 (rule 8); the SMT sortFloat32(rule 10).F32satisfiesEqandOrd, and neverInteger. A user kind, variant, capability or unit namedF32,Complex,Array,Matrix,TensororLuis U1002, as one namedDecimalis (§16 rule 1). -
Literals. A float literal takes the type
F32where its context expectsF32, by the rule of expected types of spec/18 §2 rule 1: a binding or a result of typeF32, an argument, an element of aList[F32], and the other operand of an operator or a comparison, on either side, so that inx + 0.1,0.1 + xandx < 0.5withx: F32the literal is anF32. Elsewhere it is anF64(§2 rule 6). AnF32literal is rounded once, from its exact decimal value to the nearest binary32 value, ties to even, never through binary64:0.1as anF32is0x3DCCCCCD, and1.000000059604644776327862400740697910706is 1 + 2^-23, where rounding through binary64 would give1.0. An integer literal never takes the typeF32: whereF32is expected,1is U2001, with an edit to1.0. -
Range. An
F32literal is U2031 when it rounds to an infinity or is not zero and rounds to zero:- Overflow: a literal whose value is at least 2^128 - 2^103, the midpoint between the largest finite value and 2^128, rounds to an infinity (the midpoint itself is a tie that rounds to even, 2^128).
3.4028235677973366e38lies just below the midpoint and is accepted as the largest finite value,3.4028235e38;3.4028235677973367e38and340282356779733661637539395458142568448.0, the midpoint, are U2031. - Underflow: a literal whose value is not zero and at most 2^-150, half the smallest subnormal, rounds to zero (2^-150 itself is a tie that rounds to even, zero), so it is U2031.
1.0e-45is accepted: it is the smallest subnormal, 2^-149.
- Overflow: a literal whose value is at least 2^128 - 2^103, the midpoint between the largest finite value and 2^128, rounds to an infinity (the midpoint itself is a tie that rounds to even, 2^128).
-
Distinct.
F32is distinct fromF64and from every integer type. An operator or a comparison with anF32and anF64operand is U2001, with a repair that converts the second operand to the first one's type byto_f32()orto_f64(); with an integer operand, a repair that converts it byto_f32(). -
Operations. The operators and the methods of §3 rule 3 apply to
F32, withF32arguments and results,to_bits()excepted, and run in binary32: no engine computes anF32operation in binary64 and rounds afterwards.x.fma(times: y, plus: z)is rounded once in binary32, never through binary64, where it would round twice.modis U2001, with a repair torem. The comparisons with a literal zero are U2033, and float literal patterns U2032, as in §5 rules 5 and 6.nan()andinfinity()stayF64: the NaN and the infinities ofF32arenan().to_f32(),infinity().to_f32()and-infinity().to_f32(). -
Conversions.
x.to_f64()on anF32is exact.y.to_f32()on anF64is IEEEconvertFormatin roundTiesToEven: a value beyond the range gives an infinity, never a failure, and a NaN the canonical NaN ofF32.n.to_f32()onIntor a fixed-width integer is IEEEconvertFromInt: the nearest binary32 value, ties to even, decided on every bit of the integer, so16777217gives16777216.0. AnIntof magnitude 2^128 - 2^103 or more gives an infinity of its sign.x.to_int_exact()is §4 rule 2's.- The conversions resolve ahead of a function of their name. A package function
to_f32whose first parameter has an integer type,F64, or is a type parameter, and a package functionto_decimalwhose first parameter is anF32, are U1002 at their names, and so is an import of one (ADR 0120 rule 4).
-
Equality, order and determinism are those of §5 and §6 on the canonical bits of
F32:==is identity,<is IEEE totalOrder, NaN is canonical outside registers, and no engine contracts or reassociates. The self-test of the environment (§6 rule 4) of a command that reads a package of edition0.5runs the same probes in binary32 too, in the CLI and in a native executable, and a failed one is U6006. -
Text.
to_text, interpolation and the Una form write anF32as §7 rule 1 writes anF64, with the shortest digits thatparse_f32reads back to the same bits:0.1renders0.1, the largest finite value3.4028235e38, and the smallest subnormal1.0e-45.parse_f32(t)givesF32 fails ParseError: it reads the texts of §7 rule 2, with the failures of §7 rule 3, and rounds once, from the exact decimal value to the nearest binary32 value, ties to even.parse_f32(to_text(x)) == xfor everyF32. -
The prelude of edition
0.5gainsf32_from_bits(bits: U32) -> F32, where any NaN gives the canonical NaN,parse_f32(t: Text) -> F32 fails ParseError, and the refined kinds:unapub kind Finite64 = F64 where it.is_finite() pub kind Finite32 = F32 where it.is_finite()They are ordinary refined kinds: a value enters one through a branch, as in
if x.is_finite() then use(x) else fallback. An operation on finite values is not finite in general (the largest finite value plus itself is an infinity), so its result is anF64or anF32, and flows back into a finite kind with an obligation that the verifier decides by §8. A package declaration of one of these four names is the package's own and keeps its meaning (spec/10 §11 rule 5). -
Verification. An
F32is the SMT-LIB sort(_ FloatingPoint 8 24),Float32, with every row of §8 rule 1 at that format: a literal is(fp ...)of its exact bits, the order is the defined functionsi!lt!F32andi!le!F32, andn.to_f32()is the form ofn.to_f64()with(_ to_fp 8 24)and(_ to_fp_unsigned 8 24), and the uninterpretedi!to_f32!Intbeyond 64 bits, pinned as §8 rule 8 pinsi!to_f64!Int. The conversions between the formats are((_ to_fp 11 53) RNE x)forx.to_f64()and((_ to_fp 8 24) RNE y)fory.to_f32(); both are in the refinement language. The rules of §8 rules 3 to 7 that name "anF64term" apply to a float term of either sort: the logic, the step budget, the cone, the Boolean abstraction and the weighted bound of 4, in which a conversion between the formats of a value that is not a literal weighs 4. A counterexample shows anF32by its rendering. -
Representation. The representation is not observable (spec/16 §4). The interpreter holds an
F32inline in its value. Native code holds anF32as the tagged word of its totalOrder key, never behind a handle, so it never allocates: the key is the canonical bits as a signed 32-bit integer, with every bit but the sign flipped when the sign is set. The key determines the bits, and integer order on keys is totalOrder, so equality stays identity andsortand map keys compare words. Every operation is the runtime's, computed by the same routines ofuna-coreas the interpreter's. A type descriptor (spec/20 §7) has a kind forF32: equality by its bits, and totalOrder. The raw cells and packed lists of 4 bytes per element of ADR 0120 rule 10 wait for those of ADR 0107, as §9 says forF64. -
Information flow is §11's: an
F32carries labels asIntdoes, every result joins the labels of its operands, andparse_f32andf32_from_bitslabel their results with their arguments' labels. -
Cost. Every operator, method and conversion between the formats is O(1); rendering is O(1), at most 9 significant digits; parsing is O(b) in the text's length;
n.to_f32()of anIntof m limbs is O(m). The binary32 probes add O(1) to the self-test. -
Diagnostics. U1002 for the names of rule 1 and the functions of rule 6; U2001 for mixed operands and an integer literal where an
F32is expected; U2031 at the bounds of rule 3; U2032 and U2033 as forF64; U5001 and U5002 for refinements intoFinite64andFinite32; U6006 for a failed binary32 probe. -
Not yet.
x.to_f32()of aDecimal[s]andx.to_decimal(scale:, rounding:)of anF32(ADR 0120 rule 15) wait for a later step: on anF32receiver,to_decimalresolves as a function of the package. Range sugar with float bounds is a syntax error, as in §1. -
Units.
F32 ofa unit follows the rules ofF64 ofa unit (§12, ADR 0120 rule 62), with the ratio k of aconvert()at most 2^24, the integers anF32holds exactly (spec/25 §9).