Tracking Issue for float_format_parse_hex #160626

Feature gates: #![feature(float_format_parse_hex)]

This is a tracking issue for formatting and parsing floats in the hex format, e.g. "-0x1.921fb6p+1".

Public API

// Feature gate: float_format_hex
impl LowerHex for {f16, f32, f64, f128} { /* ... */ }
impl UpperHex for {f16, f32, f64, f128} { /* ... */ }

// Feature gate: float_from_hex
impl {f16, f32, f64, f128} {
    // Accepts anything from the IEEE specification, even if it does not exactly match what we produce
    fn from_hex<S: AsRef<[u8]>>(src: &S) -> Result<Self, ParseFloatError>;
}

Format details:

IEEE specifies the following:

sign [+ −]
digit [0123456789]
hexDigit [0123456789abcdefABCDEF]
hexExpIndicator [Pp]
hexIndicator "0" [Xx]
hexSignificand ( {hexDigit} * "." {hexDigit}+ | {hexDigit}+ "." | {hexDigit}+ )
decExponent {hexExpIndicator} {sign}? {digit}+
hexSequence {sign}? {hexIndicator} {hexSignificand} {decExponent}

We should parse everything it allows. What we emit is slightly more constrained:

HEX_OUTPUT ->
    SIGN? `0x` (`1` | `0`) (`.` HEX_SEQUENCE)? HEX_INDICATOR SIGN DEC_SEQUENCE
SIGN -> `+` | `-`
HEX_EXP_INDICATOR -> `p` | `P`
HEX_SEQUENCE -> [`0`-`9` `a`-`f` `A`-`F`]+
DEC_SEQUENCE -> [`0`-`9`]+

• The + formatting flag makes the + always present for nonnegative numbers (same as other number formatting).
• The 0x is always printed, # makes no difference (unlike integers). 0x is always lowercase.
• Precision specifiers like {:.4} will zero-pad or truncate the hex digits.
• The hex sequence and "p" are lowercase for LowerHex, uppercase for UpperHex.
• If the value is nonzero, the result always starts with 0x1. (0 always prints as 0x0p+0 or -0x0p+0)
• The . and hex sequence are omitted if there are no digits other than the leading 1.

Steps / History

(Remember to update the S-tracking-* label when checking boxes.)

• ACP: ACP: hex formatting and parsing for floats libs-team#536
• Implementation: #...
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• Should subnormal numbers start with a 1 (normalized) or 0 and remain shifted to match the repr?
• Is it worth having an error type independent of ParseFloatError?
• Should we have a way to indicate whether or not parsed values are exact? (Alternative method?)
• Should we allow omitting the 0x/0X indicator when parsing, for some consistency with from_str_radix?
• This is gated behind no_fp_fmt_parse, does this make sense? The code is significantly smaller than decimal formatting/parsing.