std::to_chars, std::to_chars_result

 

C++

Compiler support

Freestanding and hosted

Language

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Technical specifications

Symbols index

External libraries

 

Utilities library

Language support Type support (basic types, RTTI) Library feature-test macros (C++20) Dynamic memory management Program utilities Coroutine support (C++20) Variadic functions is_constant_evaluated (C++20) launder (C++17) initializer_list (C++11) source_location (C++20) Three-way comparison (C++20) three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)    is_eqis_neqis_ltis_lteqis_gtis_gteq (C++20)(C++20)(C++20)(C++20)(C++20)(C++20)

General utilities Date and time Function objects Formatting library (C++20) bitset hash (C++11) Relational operators (deprecated in C++20) rel_ops::operator!=rel_ops::operator> rel_ops::operator<=rel_ops::operator>= Integer comparison functions cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)    cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) Swap and type operations swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) Common vocabulary types pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23) Elementary string conversions to_chars (C++17) from_chars (C++17) chars_format (C++17)

 

Defined in header <charconv>
	(1)
std::to_chars_result to_chars( char* first, char* last,                                /*see below*/ value, int base = 10 );			(since C++17) (until C++23)
constexpr std::to_chars_result to_chars( char* first, char* last,                                /*see below*/ value, int base = 10 );			(since C++23)
std::to_chars_result to_chars( char*, char*, bool, int = 10 ) = delete;		(2)	(since C++17)
std::to_chars_result to_chars( char* first, char* last, float       value ); std::to_chars_result to_chars( char* first, char* last, double      value ); std::to_chars_result to_chars( char* first, char* last, long double value );		(3)	(since C++17)
std::to_chars_result to_chars( char* first, char* last, float       value,                                std::chars_format fmt ); std::to_chars_result to_chars( char* first, char* last, double      value,                                std::chars_format fmt ); std::to_chars_result to_chars( char* first, char* last, long double value,                                std::chars_format fmt );		(4)	(since C++17)
std::to_chars_result to_chars( char* first, char* last, float       value,                                std::chars_format fmt, int precision ); std::to_chars_result to_chars( char* first, char* last, double      value,                                std::chars_format fmt, int precision ); std::to_chars_result to_chars( char* first, char* last, long double value,                                std::chars_format fmt, int precision );		(5)	(since C++17)
Helper types
struct to_chars_result {     char* ptr;     std::errc ec; };		(6)	(since C++17)

Converts value into a character string by successively filling the range [first, last), where [first, last) is required to be a valid range.

1) Integer formatters: 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 a minus sign. The library provides overloads for all signed and unsigned integer types and for the type char as the type of the parameter value.

2) Overload for bool is deleted. to_chars rejects argument of type bool because the result would be "0"/"1" but not "false"/"true" if it is permitted.

3) value is converted to a string as if by std::printf in the default ("C") locale. The conversion specifier is f or e (resolving in favor of f in case of a tie), chosen according to the requirement for a shortest representation: 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 std::from_chars function recovers value exactly. If there are several such representations, one with the smallest difference to value is chosen, resolving any remaining ties using rounding according to std::round_to_nearest

4) same as (3), but the conversion specified for the as-if printf is f if fmt is std::chars_format::fixed, e if fmt is std::chars_format::scientific, a (but without leading "0x" in the result) if fmt is std::chars_format::hex, and g if fmt is chars_format::general.

5) same as (4), except the precision is specified by the parameter precision rather than by the shortest representation requirement.

6) The return type (see Return value below). std::to_chars_result has no base classes, or members other than ptr, ec and implicitly declared special member functions.

Parameters

first, last	-	character range to write to
value	-	the value to convert to its string representation
base	-	integer base to use: a value between 2 and 36 (inclusive).
fmt	-	floating-point formatting to use, a bitmask of type std::chars_format
precision	-	floating-point precision to use

Return value

On success, returns a value of type to_chars_result such that ec equals value-initialized std::errc and ptr is the one-past-the-end pointer of the characters written. Note that the string is not NUL-terminated.

On error, returns a value of type to_chars_result holding std::errc::value_too_large in ec, a copy of the value last in ptr, and leaves the contents of the range [first, last) in unspecified state.

operator==(std::to_chars_result)

friend bool operator==( const to_chars_result&, const to_chars_result& ) = default;		(since C++20)

Checks if ptr and ec of both arguments are equal respectively.

This function is not visible to ordinary unqualified or qualified lookup, and can only be found by argument-dependent lookup when std::to_chars_result is an associated class of the arguments.

The != operator is synthesized from operator==.

Exceptions

Throws nothing.

Notes

Unlike other formatting functions in C++ and C libraries, std::to_chars is locale-independent, non-allocating, and non-throwing. Only a small subset of formatting policies used by other libraries (such as std::sprintf) is provided. This is intended to allow the fastest possible implementation that is useful in common high-throughput contexts such as text-based interchange (JSON or XML).

The guarantee that std::from_chars can recover every floating-point value formatted by to_chars exactly is only provided if both functions are from the same implementation.

It is required to explicitly cast a bool value to another integer type if it is wanted to format the value as "0"/"1".

Feature-test macro:

__cpp_lib_to_chars

Feature-test macro:

__cpp_lib_constexpr_charconv

Example

Run this code

#include <array>
#include <charconv>
#include <iostream>
#include <string_view>
#include <system_error>
 
void show_to_chars(auto... format_args)
{
    std::array<char, 10> str;
 
    if(auto [ptr, ec] = std::to_chars(str.data(), str.data() + str.size(), format_args...);
       ec == std::errc())
    {
        std::cout << std::string_view
            (str.data(), ptr) << '\n';
        //  (str.data(), ptr - str.data()) // C++17 alt, using string_view(ptr, length)
    }
    else
    {
        std::cout << std::make_error_code(ec).message() << '\n';
    }
}
 
int main()
{
    show_to_chars(42);
    show_to_chars(+3.14159F);
    show_to_chars(-3.14159, std::chars_format::fixed);
    show_to_chars(-3.14159, std::chars_format::scientific, 3);
    show_to_chars(3.1415926535, std::chars_format::fixed, 10);
}

Output:

42
3.14159
-3.14159
-3.142e+00
Value too large for defined data type

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 2955	C++17	this function was in <utility> and used std::error_code	moved to <charconv> and uses std::errc
LWG 3266	C++17	bool argument was accepted and promoted to int	rejected by a deleted overload
LWG 3373	C++17	to_chars_result might have additional members	additional members are disallowed

See also

from_chars (C++17)	converts a character sequence to an integer or floating-point value (function)
to_string (C++11)	converts an integral or floating point value to string (function)
printffprintfsprintfsnprintf (C++11)	prints formatted output to stdout, a file stream or a buffer (function)
operator<<	inserts formatted data (public member function of std::basic_ostream<CharT,Traits>)