4 releases
0.1.3 | Dec 2, 2023 |
---|---|
0.1.2 | Nov 30, 2023 |
0.1.1 | Nov 30, 2023 |
0.1.0 | Nov 30, 2023 |
#997 in Parser implementations
35 downloads per month
Used in 4 crates
(3 directly)
29KB
503 lines
hexfloat2
supports hexadecimal f32/64 syntax.
IEEE754 defines a syntax for "hexadecimal-significand character sequences" that lets you write a precise representation of a floating point number.
For example:
0x1.0p0
is just 1.00x8.8p1
is 8.5 * 2^1, or 17.0x3.0p-12
is 3 * 2^-12, or 0.000732421875 in decimal.
Unlike decimal representations, "hexfloat" representations don't involve any rounding, so a format-then-parse round trip will always return exactly the same original value.
A formatted hexfloat will always appear in its "canonical" format,
copying the exact bit representation as closely as possible. For example,
the value 2^-20 will always be rendered as 0x1.0p-19
.
The parser attempts to handle "non-canonical" representations. For example, these values will all be parsed as 2^-20:
0x1.0p-20
0x2.0p-21
0x0.0008p-7
Some inputs won't parse: values with too
many hex digits (e.g. 0x10000000000000000p20
) will fail to parse
because the parser is only willing to parse up to 16 hex digits.
Values that are outside the range that can be represented in the
underlying type (f32 or f64) will also fail to parse.
Values with excessive precision will have the trailing bits dropped.
For example, 0x1.0000000000001p0
will be truncated to 1.0
when
parsed into a HexFloat<f32>
(but would fit in an f64).
"Subnormal" values can be successfully formatted and parsed;
0x0.000002p-127
can be parsed as an f32; anything smaller will
be truncated to 0.
Examples
use hexfloat2::HexFloat32;
const EXPECTED: f32 = 1.0 / 1048576.0;
let x = "0x1.0p-20";
let fx: HexFloat32 = x.parse().unwrap();
assert_eq!(*fx, EXPECTED);
let y = "0x2.0p-21";
let fy: HexFloat32 = y.parse().unwrap();
assert_eq!(*fy, EXPECTED);
let z = "0x0.0008p-7";
let fz: HexFloat32 = z.parse().unwrap();
assert_eq!(*fz, EXPECTED);
let sz = format!("{fz}");
assert_eq!(sz, "0x1.000000p-20");
This crate provides newtype wrappers HexFloat<T>
, aka HexFloat32
or
HexFloat64
, that implement Display
and FromStr
.
If you don't want to deal with the wrapper structs, you can also call
hexfloat::parse::<T>()
or hexfloat::format::<T>()
instead.