Fix defects in floating-point std::from_chars
(LWG3081, LWG3082, LWG3456)

Contents

1. Introduction

In 2018, [LWG3081] pointed out that the from_chars API does not give the user a means of distinguishing floating-point overflow and underflow. The perceived defect is a loss of functionality compared to std::strtod. This issue remains open to this day despite having Priority 2.

In 2023, [P2827R1] attempted to solve this issue, but died in LEWG eventually. Lack of motivation within the paper was among the feedback given. Perplexingly, [P2827R1] does not mention the implementation divergence between libstdc++ and MSVC STL, which already existed at the time; mentioning it surely would have added motivation.

The issue is much more severe than the LWG issue and paper make it out to be. The wording is defective, implementations diverge, and users suffer from it to the point where boost::from_chars_erange ([BoostCharConv]) should arguably be recommended to users over the standard feature; at least it is portable and well-specified.

1.1. Implementation divergence

There are three cases of interest where typical implementations likely diverge:

• Treatment of floating-point overflow (always resulting in infinity), such as when parsing "1e+1000" as std::float32_t.
• Treatment of floating-point underflow that results in an inexact zero, such as when parsing "1e-10000" as std::float32_t.
• Treatment of floating-point underflow that results in an inexact subnormal, such as when parsing "1e-45" as std::float32_t.

At the time of writing, implementations behave as shown in the table below when parsing a string as float (binary32). Each cell shows what value the given float& is set to, as well as the returned std::errc value.

1.2. Defective wording

1.2.1. Range of representable values

Out of the implementations above, none comply with the existing wording. [charconv.from.chars] states:

[…] If the parsed value is not in the range representable by the type of value, value is unmodified and the member ec of the return value is equal to errc::result_out_of_range. Otherwise, value is set to the parsed value, after rounding according to round_to_nearest ([round.style]), and the member ec is value-initialized.

The problem is that for several years while std::from_chars existed, there was no definition of range of representable values (marked above) in the standard. That definition was only added recently in 2023 via [CWG2723]; the definition in [basic.fundamental] paragraph 13 includes all real numbers in that range, meaning that every standard library is incorrect for returning errc::result_out_of_range on overflow and underflow. Ergo, not only is underflow indistinguishable from overflow via error code, overflow, underflow, and exact rounding are all indistinguishable if the wording is implemented (which it isn't).

1.2.2. No handling of non-ISO/IEC 60559 types

Another problem with the wording is that it does not account for types that do not have a representation of infinity or NaN. The string pattern accepted by std::from_chars is always permitted to be "INFINITY", but what should happen when returning a floating-point type without infinity representations?

1.2.3. No specification of parsing

Last but most severe, the entire mechanism of mapping the matched pattern onto a floating-point value is described as:

Otherwise, value is set to the parsed value, after rounding according to round_to_nearest ([round.style]), and the member ec is value-initialized.

The fact that a string such as "INF" results in infinity or that "1" results in 1.0 is handwaved as the single word parsed, which is not explained anywhere. While most such cases are obvious, std::to_chars in libc++ represents signaling NaNs as "nan(snan)", and it is unclear whether std::from_chars can recover a signaling NaN from such a string because there exists no wording for parsed.

The intent is presumably to handle these cases like std::strtod, but this is not stated anywhere; only the syntax of the matched pattern is specified, not the interpretation of the pattern. The description of the matched pattern is also deemed underspecified, as explained in [LWG3456].

1.2.4. Signaling NaNs make std::from_chars unimplementable

Yet another problem is that std::from_chars cannot be implemented for types that can represent signaling NaNs; the problem lies in [charconv.to.chars] paragraph 2:

The functions that take a floating-point value but not a precision parameter ensure that the string representation consists of the smallest number of characters such that there is at least one digit before the radix point (if present) and parsing the representation using the corresponding from_chars function recovers value exactly.

It is not entirely clear whether this requirement was intended to apply to non-finite inputs, but it technically could be read in such a way. If so, it would additionally mandate that "inf" instead of "infinity" is emitted when the value is $+\infty$, which implementations do.

The problem is that the pattern accepted by std::from_chars is that of std::strtod, which supports "INFINITY", "NAN", and "NAN(d-char-sequence)" but no "SNAN" as inputs. std::strtod interprets every NaN input as a quiet NaN, which is presumably the intent for std::from_chars, even if the wording does not explicitly say so; in fact, the wording does not say anything about how these text representations of infinity or NaN are interpreted as a floating-point value by std::from_chars.

As things stand, the requirement to recover the value exactly cannot be implemented for signaling NaNs in any reasonable way. Therefore, it is necessary to exempt signaling NaNs from being recovered. std::strtod has this exemption, as does ISO/IEC 60559; see §5.12.1 External character sequences representing zeros, infinities, and NaNs:

Conversion of a signaling NaN in a supported format to an external character sequence should produce a language-defined one of "snan" or "nan" or a sequence that is equivalent except for case, with an optional preceding sign.

2. Design

In short, the MSVC STL and libc++ behavior is proposed, with additional wording clarifications.

2.1. Limited design options

At this stage, the available design options are extremely limited because floating-point implementations of std::from_chars have already existed for years (MSVC STL since 2018, libstdc++ since 2021, libc++ since 2025). Changing the behavior of std::from_chars can break substantial amounts of existing code.

There seem to be only two plausible options with sufficiently low impact:

• Standardize the libstdc++ behavior, which is to leave the given float& unmodified on overflow/underflow.
• Standardize the MSVC STL and libc++ behavior, which is to overwrite the given float& with either zero or infinity.

I argue that the libc++ behavior is strictly better because

• the behavior resolves [LWG3081] by making underflow distinguishable from overflow,
• users may actually want to ignore result_out_of_range and simply take the 0 resulting from underflow and $\infty$ resulting from overflow, which the libc++ behavior makes possible, and
• the behavior is consistent with std::strtod.

To provide the maximum amount of information to the user, it is also important that the user obtains a correctly signed zero on underflow and a correctly signed $\infty$ on overflow. That is, the sign of the result value should always be the sign of the parsed mathematical value, even if rounded to zero or infinity. Both MSVC STL and libc++ provide correctly signed values.

2.2. Note on ISO/IEC 60559 conformance

The choice of (correctly signed) zeros and infinities to signal underflow and overflow is far from arbitrary; strtod has that design, and correctly implements the ISO/IEC 60559 (or IEEE-754) operation convertFromDecimalCharacter for floating-point types (see C23 §F.3).

std::from_chars should have that same behavior to increase ISO/IEC 60559 conformance. [charconv.from.chars] even uses the round_to_nearest rounding mode corresponding to roundTiesToEven already, which makes it extremely similar to the ISO/IEC 60559 operation.

As mentioned in §1.2.4. Signaling NaNs make std::from_chars unimplementable, it is also necessary to handle signaling NaNs in some way, as part of the convertFromDecimalCharacter operation. The easiest way to do so would be to double down on the practice of always producing "NAN" for both quiet and signaling NaNs; the wording merely needs to relax the exact recoverability requirement for that case.

2.3. Impact on existing code

Furthermore, we must consider how the change in behavior affects existing users, if we standardize the behavior of the other implementation:

• Users of libstdc++ likely ignore the written value on result_out_of_range because it is unmodified. Now modifying the value does not cause any problem if they were ignoring it already.
• Users of MSVC STL and libc++ may rely on infinity or zero being written on result_out_of_range, and suddenly leaving the value unmodified would result in use of erroneous or even indeterminate values for these users.

When considering these two options, standardizing the GCC behavior appears more risky.

2.4. Alternatives considered

Neither [LWG3081] nor [P2827R1] fully resolve the defects in the wording. Each proposes a different value that should be written for overflow; the LWG issue proposes numeric_limits<T>::max(), and the paper proposes 1.

Neither of these behaviors standardizes existing practice in standard libraries, is particularly well-motivated, or matches the behavior of other functions such as std::strtod. Both alternatives make it difficult to simply ignore the result_out_of_range error and use the value.

2.5. Further edge cases

As explained in §1.2.2. No handling of non-ISO/IEC 60559 types, there are various edge cases such as parsing the string "INFINITY" and attempting to store it in a floating-point type that does not have a representation of infinity. These edge cases are currently not handled in any explicit way by major standard library implementations. To my knowledge, all major standard libraries assume ISO/IEC-60559-like types, meaning that negative and positive infinity and NaN are also supported.

The proposed solution is to handle these cases as closely as possible to std::strtod, as specified in C23 §7.24.1.5. For example, this means that when "inf" is parsed but not representable in the type, the greatest finite value is returned instead, and the error code is errc::result_out_of_range.

3. Implementation experience

The proposed behavior has been released in MSVC STL and libc++, except that the behavior in §2.5. Further edge cases does not need to be implemented and only exists on paper for these implementations.

The proposed behavior has also been implemented as boost::from_chars_erange ([BoostCharConv]).

4. Editorial problems

Beyond the normative issues, there are also significant editorial problems with [charconv.from.chars] which make it difficult to understand what pattern it actually accepts. Namely, the wording is currently:

Effects: The pattern is the expected form of the subject sequence in the "C" locale, as described for strtod, except that

• the sign '+' may only appear in the exponent part;
• if fmt has chars_format​::​scientific set but not chars_format​::​fixed, the otherwise optional exponent part shall appear;
• if fmt has chars_format​::​fixed set but not chars_format​::​scientific, the optional exponent part shall not appear; and
• if fmt is chars_format​::​hex, the prefix "0x" or "0X" is assumed.

In any case, the resulting value is one of at most two floating-point values closest to the value of the string matching the pattern.

We don't actually get to understand what the pattern is here, just that we should look at strtod and make mental changes relative to that. C23 §7.24.1.5 paragraph 3 then describes the sequence partially using a mixture of prose and grammar, containing descriptions such as

[…] a nonempty sequence of decimal digits optionally containing a decimal-point character, then an optional exponent part as defined in 6.4.4.3, excluding any digit separators (6.4.4.2);

Even the C wording doesn't directly describe the pattern but refers to various other definitions such as exponent part and digit separators that must be looked up elsewhere. Anyone trying to understand what std::from_chars actually accepts needs to go through a multi-standard scavenger hunt and keep track of two layers of excluding and except that.

This is an ineffective way to communicate the behavior of std::from_chars and should be rewritten so that the accepted pattern can be understood solely through [charconv.from.chars]. [LWG3456] performs such a rewrite, but does not fully decouple std::from_chars from the C wording.

A proper rewrite can also fix the lack of clarity pointed out in [LWG3082].

5. Wording

The changes are relative to [N5032].

[version.syn]

Bump the feature-test macro in [version.syn] as follows:

[charconv.to.chars]

Change [charconv.to.chars] paragraph 2 as follows:

[charconv.from.chars]

Change [charconv.from.chars] as follows:

6. References