home | help 
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) (constexpr
     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 (inclu-
     sive) 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
	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 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 rep-
     resentation
	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. The library provides overloads for all cv-unqual-
     ified
	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-unqual-
     ified
	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  pre-
     cision rather
	than  by  the  shortest representation requirement. The library provides
     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 (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 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 sub-
     set 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  conver-
     sions
	__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	integral
     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(), for-
     mat_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		 Correct
     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  rejected by
     a deleted
			    to int				     overload
	LWG 3373 C++17	    std::to_chars_result might have	      additional
     members are
			    additional members			     disallowed

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)
home | help