Home / Docs / Specification / 29. Numerics

29.7 Text

Release v0.4.0
  1. Rendering. to_text, interpolation, the Una form of spec/11 §5, traces and --json outputs write an F64 as follows:

    • NaN is nan, and the infinities are inf and -inf;
    • zero is 0.0, and negative zero -0.0;
    • another finite value starts with - when its sign bit is set; its digits are the shortest decimal digit string that parse_f64 reads back to the same bits, and of those, the one nearest the exact value;
    • with k the decimal exponent of its first digit, it is written positionally when -6 <= k <= 20, with at least one digit after the point (1.0, 0.1, 0.000001, 100000000000000000000.0), and otherwise in scientific form, one digit before the point, at least one after it, e, and the exponent with - when negative (1.0e21, 1.5e-7, 5.0e-324);
    • no _ and no +.

    Rendering is injective on F64, and every rendering of a finite value is a float literal after its sign. The Una form of a structure writes P(x: nan), P(x: inf), P(x: -inf).

  2. Parsing. parse_f64(t) reads exactly one of a number of the number production of RFC 8259 §6 (an optional -, an integer part without a leading zero, an optional fraction, an optional exponent with e or E and an optional sign), nan, inf or -inf. It returns the value nearest the exact decimal value, ties to even, with the sign of the text, so -0 gives -0.0. A number beyond the range rounds to an infinity, and one below it to a subnormal or a zero. It reads any number of digits and any exponent correctly. Space is not trimmed. Its failure is labeled as parse_int's is (spec/22 §5).

  3. Failures. parse_f64 fails with ParseError (spec/22 §4): Empty for an empty text, NoDigits for - alone, and otherwise NotADigit(at: i), with i the first position, in scalar values, at which no accepted text can continue; a text that ends where an accepted text could still continue fails at its length:

    Text Failure
    "" Empty
    "-" NoDigits
    "1.", "1e", "in" NotADigit(at: 2)
    "1.5e-", "-inf " NotADigit(at: 5), NotADigit(at: 4)
    "+1", ".5", " 1" NotADigit(at: 0)
    "01", "--1", "-nan" NotADigit(at: 1)
    "1.0x", "nan ", "1_0" NotADigit(at: 3), NotADigit(at: 3), NotADigit(at: 1)
    "Infinity", "NaN" NotADigit(at: 0)
  4. Round trip. parse_f64(to_text(x)) == x for every F64, the canonical NaN included.