FreeBSD Manual Pages
std::to_chars(3) C++ Standard Libary std::to_chars(3) NAME std::to_chars - std::to_chars Synopsis Defined in header <charconv> std::to_chars_result (since C++17) to_chars( char* first, char* last, (1) (const- expr since C++23) /* integer-type */ value, int base = 10 ); std::to_chars_result (2) (since C++17) to_chars( char*, char*, bool, int = 10 ) = delete; std::to_chars_result to_chars( char* first, char* last, /* (3) (since C++17) floating-point-type */ value ); std::to_chars_result to_chars( char* first, char* last, /* (4) (since C++17) floating-point-type */ value, std::chars_format fmt ); std::to_chars_result to_chars( char* first, char* last, /* (5) (since C++17) floating-point-type */ value, std::chars_format fmt, int precision ); 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 (in- clusive) are represented as lowercase characters a..z. If value is less than zero, the representation starts with a minus sign. The library provides over- loads for all cv-unqualified (since C++23) signed and unsigned integer types and for the type char as the type of the parameter value. 2) Overload for bool is deleted. std::to_chars rejects argument of type bool because the result would be "0"/"1" but not "false"/"true" if it is permit- ted. 3) value is converted to a string as if by std::printf in the de- fault ("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 ex- actly. 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. The library provides overloads for all cv-un- qualified standard (until C++23) floating-point types as the type of the parameter value. 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. The library provides overloads for all cv-un- qualified standard (until C++23) floating-point types as the type of the parameter value. 5) Same as (4), except the precision is specified by the parameter precision rather than by the shortest representation requirement. The library pro- vides overloads for all cv-unqualified standard (until C++23) floating-point types as the type of the parameter value. 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 (inclu- sive). 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 std::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 std::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. 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 std::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 Value Std Feature 201611L (C++17) Elementary string con- versions __cpp_lib_to_chars (std::to_chars, std::from_chars) 202306L (C++26) Testing for success or failure of <charconv> functions Add constexpr modifiers to __cpp_lib_constexpr_charconv 202207L (C++23) std::to_chars and std::from_chars overloads (1) for inte- gral types 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 __cpp_lib_to_chars >= 202306L // use C++26 operator bool() for error checking if (auto res = std::to_chars(str.data(), str.data() + str.size(), format_args...)) std::cout << std::string_view(str.data(), res.ptr) << '\n'; else std::cout << std::make_error_code(res.ec).message() << '\n'; #else if (auto [ptr, ec] = std::to_chars(str.data(), str.data() + str.size(), for- mat_args...); ec == std::errc()) std::cout << std::string_view(str.data(), ptr) << '\n'; else std::cout << std::make_error_code(ec).message() << '\n'; #endif } 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); } Possible 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 retroac- tively to previously published C++ standards. DR Applied to Behavior as published Cor- rect behavior LWG 2955 C++17 this function was in <utility> and used moved to <charconv> and std::error_code uses std::errc LWG 3266 C++17 bool argument was accepted and promoted re- jected by a deleted to int over- load LWG 3373 C++17 std::to_chars_result might have addi- tional members are additional members disal- lowed See also to_chars_result the return type of std::to_chars (C++17) (class) from_chars converts a character sequence to an integer or floating-point value (C++17) (function) to_string converts an integral or floating-point value to string (C++11) (function) printf fprintf prints formatted output to stdout, a file stream or a buffer sprintf (function) snprintf (C++11) operator<< inserts formatted data (public member function of std::basic_os- tream<CharT,Traits>) http://cppreference.com 2024.06.10 std::to_chars(3)
NAME | Synopsis | Parameters | Return value | Exceptions | Notes | Example | Possible output: | See also
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::to_chars&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>