20 General utilities library [utilities]

20.19 Primitive numeric conversions [charconv]

20.19.1 Header <charconv> synopsis [charconv.syn]

namespace std {
  // floating-point format for primitive numerical conversion
  enum class chars_­format {
    scientific = unspecified,
    fixed = unspecified,
    hex = unspecified,
    general = fixed | scientific
  };


  // [charconv.to.chars], primitive numerical output conversion
  struct to_chars_result {
    char* ptr;
    errc ec;
    friend bool operator==(const to_chars_result&, const to_chars_result&) = default;
  };

  to_chars_result to_chars(char* first, char* last, see below value, int base = 10);
  to_chars_result to_chars(char* first, char* last, bool value, int base = 10) = delete;

  to_chars_result to_chars(char* first, char* last, float value);
  to_chars_result to_chars(char* first, char* last, double value);
  to_chars_result to_chars(char* first, char* last, long double value);

  to_chars_result to_chars(char* first, char* last, float value, chars_format fmt);
  to_chars_result to_chars(char* first, char* last, double value, chars_format fmt);
  to_chars_result to_chars(char* first, char* last, long double value, chars_format fmt);

  to_chars_result to_chars(char* first, char* last, float value,
                           chars_format fmt, int precision);
  to_chars_result to_chars(char* first, char* last, double value,
                           chars_format fmt, int precision);
  to_chars_result to_chars(char* first, char* last, long double value,
                           chars_format fmt, int precision);


  // [charconv.from.chars], primitive numerical input conversion
  struct from_chars_result {
    const char* ptr;
    errc ec;
    friend bool operator==(const from_chars_result&, const from_chars_result&) = default;
  };

  from_chars_result from_chars(const char* first, const char* last,
                               see below& value, int base = 10);

  from_chars_result from_chars(const char* first, const char* last, float& value,
                               chars_format fmt = chars_format::general);
  from_chars_result from_chars(const char* first, const char* last, double& value,
                               chars_format fmt = chars_format::general);
  from_chars_result from_chars(const char* first, const char* last, long double& value,
                               chars_format fmt = chars_format::general);
}
1
#
The type chars_­format is a bitmask type ([bitmask.types]) with elements scientific, fixed, and hex.
2
#
The types to_­chars_­result and from_­chars_­result have the data members and special members specified above.
They have no base classes or members other than those specified.

20.19.2 Primitive numeric output conversion [charconv.to.chars]

1
#
All functions named to_­chars convert value into a character string by successively filling the range [first, last), where [first, last) is required to be a valid range.
If the member ec of the return value is such that the value is equal to the value of a value-initialized errc, the conversion was successful and the member ptr is the one-past-the-end pointer of the characters written.
Otherwise, the member ec has the value errc​::​value_­too_­large, the member ptr has the value last, and the contents of the range [first, last) are unspecified.
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.
[ Note
:
This guarantee applies only if to_­chars and from_­chars are executed on the same implementation.
— end note
 ]
If there are several such representations, the representation with the smallest difference from the floating-point argument value is chosen, resolving any remaining ties using rounding according to round_­to_­nearest.
3
#
The functions taking a chars_­format parameter determine the conversion specifier for printf as follows: The conversion specifier is f if fmt is chars_­format​::​fixed, e if fmt is chars_­format​::​scientific, a (without leading "0x" in the result) if fmt is chars_­format​::​hex, and g if fmt is chars_­format​::​general.
🔗
to_chars_result to_chars(char* first, char* last, see below value, int base = 10);
4
#
Preconditions: base has a value between 2 and 36 (inclusive).
5
#
Effects: The value of value is converted to a string of digits in the given base (with no redundant leading zeroes).
Digits in the range 10.
35 (inclusive) are represented as lowercase characters a.
z.
If value is less than zero, the representation starts with '-'.
6
#
Throws: Nothing.
7
#
Remarks: The implementation shall provide overloads for all signed and unsigned integer types and char as the type of the parameter value.
🔗
to_chars_result to_chars(char* first, char* last, float value); to_chars_result to_chars(char* first, char* last, double value); to_chars_result to_chars(char* first, char* last, long double value);
8
#
Effects: value is converted to a string in the style of printf in the "C" locale.
The conversion specifier is f or e, chosen according to the requirement for a shortest representation (see above); a tie is resolved in favor of f.
9
#
Throws: Nothing.
🔗
to_chars_result to_chars(char* first, char* last, float value, chars_format fmt); to_chars_result to_chars(char* first, char* last, double value, chars_format fmt); to_chars_result to_chars(char* first, char* last, long double value, chars_format fmt);
10
#
Preconditions: fmt has the value of one of the enumerators of chars_­format.
11
#
Effects: value is converted to a string in the style of printf in the "C" locale.
12
#
Throws: Nothing.
🔗
to_chars_result to_chars(char* first, char* last, float value, chars_format fmt, int precision); to_chars_result to_chars(char* first, char* last, double value, chars_format fmt, int precision); to_chars_result to_chars(char* first, char* last, long double value, chars_format fmt, int precision);
13
#
Preconditions: fmt has the value of one of the enumerators of chars_­format.
14
#
Effects: value is converted to a string in the style of printf in the "C" locale with the given precision.
15
#
Throws: Nothing.
See also: ISO C 7.21.6.1

20.19.3 Primitive numeric input conversion [charconv.from.chars]

1
#
All functions named from_­chars analyze the string [first, last) for a pattern, where [first, last) is required to be a valid range.
If no characters match the pattern, value is unmodified, the member ptr of the return value is first and the member ec is equal to errc​::​invalid_­argument.
[ Note
:
If the pattern allows for an optional sign, but the string has no digit characters following the sign, no characters match the pattern.
— end note
 ]
Otherwise, the characters matching the pattern are interpreted as a representation of a value of the type of value.
The member ptr of the return value points to the first character not matching the pattern, or has the value last if all characters match.
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, and the member ec is value-initialized.
🔗
from_chars_result from_chars(const char* first, const char* last, see below& value, int base = 10);
2
#
Preconditions: base has a value between 2 and 36 (inclusive).
3
#
Effects: The pattern is the expected form of the subject sequence in the "C" locale for the given nonzero base, as described for strtol, except that no "0x" or "0X" prefix shall appear if the value of base is 16, and except that '-' is the only sign that may appear, and only if value has a signed type.
4
#
Throws: Nothing.
5
#
Remarks: The implementation shall provide overloads for all signed and unsigned integer types and char as the referenced type of the parameter value.
🔗
from_chars_result from_chars(const char* first, const char* last, float& value, chars_format fmt = chars_format::general); from_chars_result from_chars(const char* first, const char* last, double& value, chars_format fmt = chars_format::general); from_chars_result from_chars(const char* first, const char* last, long double& value, chars_format fmt = chars_format::general);
6
#
Preconditions: fmt has the value of one of the enumerators of chars_­format.
7
#
Effects: The pattern is the expected form of the subject sequence in the "C" locale, as described for strtod, except that
  • (7.1)
    the sign '+' may only appear in the exponent part;
  • (7.2)
    if fmt has chars_­format​::​scientific set but not chars_­format​::​fixed, the otherwise optional exponent part shall appear;
  • (7.3)
    if fmt has chars_­format​::​fixed set but not chars_­format​::​scientific, the optional exponent part shall not appear; and
  • (7.4)
    if fmt is chars_­format​::​hex, the prefix "0x" or "0X" is assumed.
    [ Example
    : The string 0x123 is parsed to have the value 0 with remaining characters x123. — end example
     ]
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.
8
#
Throws: Nothing.
See also: ISO C 7.22.1.3, 7.22.1.4