cppdraft_translate/cppdraft/charconv.md

[charconv]

# 28 Text processing library [[text]](./#text)

## 28.2 Primitive numeric conversions [charconv]

### [28.2.1](#syn) Header <charconv> synopsis [[charconv.syn]](charconv.syn)

[1](#syn-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L24)

When a function is specified
with a type placeholder of *integer-type*,
the implementation provides overloads
for char and all cv-unqualified signed and unsigned integer types
in lieu of *integer-type*[.](#syn-1.sentence-1)

When a function is specified
with a type placeholder of *floating-point-type*,
the implementation provides overloads
for all cv-unqualified floating-point types ([[basic.fundamental]](basic.fundamental "6.9.2 Fundamental types"))
in lieu of *floating-point-type*[.](#syn-1.sentence-2)

[🔗](#header:%3ccharconv%3e)

namespace std {// floating-point format for primitive numerical conversionenum class [chars_format](#lib:chars_format "28.2.1 Header <charconv> synopsis [charconv.syn]") {[scientific](#lib:chars_format,scientific "28.2.1 Header <charconv> synopsis [charconv.syn]") = *unspecified*, [fixed](#lib:chars_format,fixed "28.2.1 Header <charconv> synopsis [charconv.syn]") = *unspecified*, [hex](#lib:chars_format,hex "28.2.1 Header <charconv> synopsis [charconv.syn]") = *unspecified*, [general](#lib:chars_format,general "28.2.1 Header <charconv> synopsis [charconv.syn]") = fixed | scientific }; // [[charconv.to.chars]](#to.chars "28.2.2 Primitive numeric output conversion"), primitive numerical output conversionstruct [to_chars_result](#lib:to_chars_result "28.2.1 Header <charconv> synopsis [charconv.syn]") { // freestandingchar* [ptr](#lib:to_chars_result,ptr "28.2.1 Header <charconv> synopsis [charconv.syn]");
 errc [ec](#lib:to_chars_result,ec "28.2.1 Header <charconv> synopsis [charconv.syn]"); friend bool operator==(const to_chars_result&, const to_chars_result&) = default; constexpr explicit operator bool() const noexcept { return ec == errc{}; }}; constexpr to_chars_result to_chars(char* first, char* last, // freestanding*integer-type* value, int base = 10);
 to_chars_result to_chars(char* first, char* last, // freestandingbool value, int base = 10) = delete;

 to_chars_result to_chars(char* first, char* last, // freestanding-deleted*floating-point-type* value);
 to_chars_result to_chars(char* first, char* last, // freestanding-deleted*floating-point-type* value, chars_format fmt);
 to_chars_result to_chars(char* first, char* last, // freestanding-deleted*floating-point-type* value, chars_format fmt, int precision); // [[charconv.from.chars]](#from.chars "28.2.3 Primitive numeric input conversion"), primitive numerical input conversionstruct [from_chars_result](#lib:from_chars_result "28.2.1 Header <charconv> synopsis [charconv.syn]") { // freestandingconst char* [ptr](#lib:from_chars_result,ptr "28.2.1 Header <charconv> synopsis [charconv.syn]");
 errc [ec](#lib:from_chars_result,ec "28.2.1 Header <charconv> synopsis [charconv.syn]"); friend bool operator==(const from_chars_result&, const from_chars_result&) = default; constexpr explicit operator bool() const noexcept { return ec == errc{}; }}; constexpr from_chars_result from_chars(const char* first, const char* last, // freestanding*integer-type*& value, int base = 10);

 from_chars_result from_chars(const char* first, const char* last, // freestanding-deleted*floating-point-type*& value,
 chars_format fmt = chars_format::general);}

[2](#syn-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L84)

The type chars_format is a bitmask type ([[bitmask.types]](bitmask.types "16.3.3.3.3 Bitmask types"))
with elements scientific, fixed, and hex[.](#syn-2.sentence-1)

[3](#syn-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L88)

The types to_chars_result and from_chars_result have the data members and special members specified above[.](#syn-3.sentence-1)

They have no base classes or members other than those specified[.](#syn-3.sentence-2)

### [28.2.2](#to.chars) Primitive numeric output conversion [[charconv.to.chars]](charconv.to.chars)

[1](#to.chars-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L95)

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[.](#to.chars-1.sentence-1)

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[.](#to.chars-1.sentence-2)

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[.](#to.chars-1.sentence-3)

[2](#to.chars-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L113)

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[.](#to.chars-2.sentence-1)

[*Note [1](#to.chars-note-1)*:

This guarantee applies only ifto_chars and from_chars are executed on the same implementation[.](#to.chars-2.sentence-2)

— *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 toround_to_nearest ([[round.style]](round.style "17.3.4 Enum float_­round_­style"))[.](#to.chars-2.sentence-3)

[3](#to.chars-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L133)

The functions taking a chars_format parameter
determine the conversion specifier for printf as follows:
The conversion specifier isf 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,
andg if fmt is chars_format​::​general[.](#to.chars-3.sentence-1)

[🔗](#lib:to_chars)

`constexpr to_chars_result to_chars(char* first, char* last, integer-type value, int base = 10);
`

[4](#to.chars-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L150)

*Preconditions*: base has a value between 2 and 36 (inclusive)[.](#to.chars-4.sentence-1)

[5](#to.chars-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L154)

*Effects*: The value of value is converted
to a string of digits in the given base
(with no redundant leading zeroes)[.](#to.chars-5.sentence-1)

Digits in the range 10..35 (inclusive)
are represented as lowercase characters a..z[.](#to.chars-5.sentence-2)

If value is less than zero,
the representation starts with '-'[.](#to.chars-5.sentence-3)

[6](#to.chars-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L164)

*Throws*: Nothing[.](#to.chars-6.sentence-1)

[🔗](#lib:to_chars_)

`to_chars_result to_chars(char* first, char* last, floating-point-type value);
`

[7](#to.chars-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L175)

*Effects*: value is converted to a string
in the style of printf in the "C" locale[.](#to.chars-7.sentence-1)

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[.](#to.chars-7.sentence-2)

[8](#to.chars-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L185)

*Throws*: Nothing[.](#to.chars-8.sentence-1)

[🔗](#lib:to_chars__)

`to_chars_result to_chars(char* first, char* last, floating-point-type value, chars_format fmt);
`

[9](#to.chars-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L196)

*Preconditions*: fmt has the value of
one of the enumerators of chars_format[.](#to.chars-9.sentence-1)

[10](#to.chars-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L201)

*Effects*: value is converted to a string
in the style of printf in the "C" locale[.](#to.chars-10.sentence-1)

[11](#to.chars-11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L207)

*Throws*: Nothing[.](#to.chars-11.sentence-1)

[🔗](#lib:to_chars___)

`to_chars_result to_chars(char* first, char* last, floating-point-type value,
                         chars_format fmt, int precision);
`

[12](#to.chars-12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L219)

*Preconditions*: fmt has the value of
one of the enumerators of chars_format[.](#to.chars-12.sentence-1)

[13](#to.chars-13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L224)

*Effects*: value is converted to a string
in the style of printf in the "C" locale
with the given precision[.](#to.chars-13.sentence-1)

[14](#to.chars-14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L231)

*Throws*: Nothing[.](#to.chars-14.sentence-1)

See also: ISO/IEC 9899:2024, 7.21.6.1

### [28.2.3](#from.chars) Primitive numeric input conversion [[charconv.from.chars]](charconv.from.chars)

[1](#from.chars-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L240)

All functions named from_chars analyze the string [first, last)
for a pattern,
where [first, last) is required to be a valid range[.](#from.chars-1.sentence-1)

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[.](#from.chars-1.sentence-2)

[*Note [1](#from.chars-note-1)*:

If the pattern allows for an optional sign,
but the string has no digit characters following the sign,
no characters match the pattern[.](#from.chars-1.sentence-3)

— *end note*]

Otherwise,
the characters matching the pattern
are interpreted as a representation
of a value of the type of value[.](#from.chars-1.sentence-4)

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[.](#from.chars-1.sentence-5)

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[.](#from.chars-1.sentence-6)

Otherwise,value is set to the parsed value,
after rounding according to round_to_nearest ([[round.style]](round.style "17.3.4 Enum float_­round_­style")), and
the member ec is value-initialized[.](#from.chars-1.sentence-7)

[🔗](#lib:from_chars)

`constexpr from_chars_result from_chars(const char* first, const char* last,
                                       integer-type& value, int base = 10);
`

[2](#from.chars-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L282)

*Preconditions*: base has a value between 2 and 36 (inclusive)[.](#from.chars-2.sentence-1)

[3](#from.chars-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L286)

*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[.](#from.chars-3.sentence-1)

[4](#from.chars-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L298)

*Throws*: Nothing[.](#from.chars-4.sentence-1)

[🔗](#lib:from_chars_)

`from_chars_result from_chars(const char* first, const char* last, floating-point-type& value,
                             chars_format fmt = chars_format::general);
`

[5](#from.chars-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L310)

*Preconditions*: fmt has the value of
one of the enumerators of chars_format[.](#from.chars-5.sentence-1)

[6](#from.chars-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L315)

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

- [(6.1)](#from.chars-6.1)

the sign '+' may only appear in the exponent part;

- [(6.2)](#from.chars-6.2)

if fmt has chars_format​::​scientific set
but not chars_format​::​fixed,
the otherwise optional exponent part shall appear;

- [(6.3)](#from.chars-6.3)

if fmt has chars_format​::​fixed set
but not chars_format​::​scientific,
the optional exponent part shall not appear; and

- [(6.4)](#from.chars-6.4)

if fmt is chars_format​::​hex,
the prefix "0x" or "0X" is assumed[.](#from.chars-6.sentence-1)
  [*Example [1](#from.chars-example-1)*:
  The string 0x123 is parsed to have the value0 with remaining characters x123[.](#from.chars-6.4.sentence-2)
 — *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[.](#from.chars-6.sentence-2)

[7](#from.chars-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L346)

*Throws*: Nothing[.](#from.chars-7.sentence-1)

See also: ISO/IEC 9899:2024, 7.22.1.3, 7.22.1.4