home | help 
std::formatted_size(3)	       C++ Standard Libary	  std::formatted_size(3)

NAME
     std::formatted_size - std::formatted_size

Synopsis
	Defined in header <format>
	template< class... Args >
	std::size_t  formatted_size(  std::format_string<Args...> fmt,	     (1)
     (since C++20)
	Args&&... args );
	template< class... Args >
	std::size_t formatted_size( std::wformat_string<Args...>  fmt,	     (2)
     (since C++20)
	Args&&... args );
	template< class... Args >

	std::size_t  formatted_size(  const std::locale& loc,		     (3)
     (since C++20)

				    std::format_string<Args...> fmt,
	Args&&... args );
	template< class... Args >

	std::size_t formatted_size( const std::locale&	loc,		     (4)
     (since C++20)

				    std::wformat_string<Args...> fmt,
	Args&&... args );

	Determine the total number of characters in the formatted string by for-
     matting args
	according  to the format string fmt. If present, loc is used for locale-
     specific
	formatting.

	The behavior  is  undefined  if  std::formatter<std::remove_cvref_t<Ti>,
     CharT> does not
	meet the BasicFormatter requirements for any Ti in Args.

Parameters
		  an object that represents the format string. The format string
     consists of
		    * ordinary characters (except { and }), which are copied un-
     changed to
		      the output,
		    *  escape sequences {{ and }}, which are replaced with { and
     }
		      respectively in the output, and
		    * replacement fields.

		  Each replacement field has the following format:

		  { arg-id (optional) } 	      (1)
		  { arg-id (optional) : format-spec } (2)

		  1) replacement field without a format specification
		  2) replacement field with a format specification

				specifies the index  of  the  argument	in  args
     whose value is
				to be used for formatting; if it is omitted, the
     arguments
				are used in order.
		  arg-id      -
				The  arg-idas  in  a  format  string must all be
     present or all
				be omitted. Mixing manual and automatic indexing
     is an
				error.
	fmt	 -		  the  format  specification  defined	by   the
     std::formatter
		  format-spec  -  specialization for the corresponding argument.
     Cannot start
				with }.

		    * For basic types and  standard  string  types,  the  format
     specification is
		      interpreted as standard format specification.
		    *  For chrono types, the format specification is interpreted
     as chrono
		      format specification.

		    * For range types, the format specification is interpreted
		      as range format specification.
		    * For std::pair and std::tuple, the format specification
		      is interpreted as tuple format specification.
		    *  For  std::thread::id   and   std::stacktrace_entry,   see
     (since C++23)
		      thread id format specification and stacktrace entry
		      format specification.
		    * For std::basic_stacktrace, no format specifier is
		      allowed.

		    *	  For	 std::filesystem::path,    see	  path	  format
     (since C++26)
		      specification.

		    * For other formattable types, the format  specification  is
     determined by
		      user-defined formatter specializations.
	args... - arguments to be formatted
	loc	- std::locale used for locale-specific formatting

Return value
	The total number of characters in the formatted string.

Exceptions
	Propagates any exception thrown by formatter.

Example
     // Run this code

      #include <format>
      #include <iostream>
      #include <vector>
      #include <string_view>

      int main()
      {
	  using namespace std::literals::string_view_literals;

	  constexpr  auto fmt_str { "Hubble's H{0} {1} {2:*^4} miles/sec/mpc."sv
     };
	  constexpr auto sub_zero { "a"sv };  // { "\u2080"sv } => { 0xe2, 0x82,
     0x80 };
	  constexpr auto aprox_equ { "a"sv }; // { "\u2245"sv } => { 0xe2, 0x89,
     0x85 };
	  constexpr int Ho { 42 }; // Ha

	  const auto min_buffer_size  =  std::formatted_size(fmt_str,  sub_zero,
     aprox_equ, Ho);

	  std::cout << "Min buffer size = " << min_buffer_size << '\n';

	  //  Use  std::vector	as dynamic buffer. Note: buffer does not include
     the trailing '\0'.
	  std::vector<char> buffer(min_buffer_size);

	  std::format_to_n(buffer.data(),  buffer.size(),   fmt_str,   sub_zero,
     aprox_equ, Ho);

	  std::cout   <<   "Buffer:   \""   <<	 std::string_view{buffer.data(),
     min_buffer_size} << "\"\n";

	  // Or we can print the buffer directly by adding the trailing '\0'.
	  buffer.push_back('\0');
	  std::cout << "Buffer: \"" << buffer.data() << "\"\n";
      }

Output:
      Min buffer size = 37
      Buffer: "Hubble's Ha a *42* miles/sec/mpc."
      Buffer: "Hubble's Ha a *42* miles/sec/mpc."

	Defect reports

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

	  DR	 Applied to	 Behavior as published		     Correct be-
     havior
	P2216R3  C++20	     throws  std::format_error	for	 invalid  format
     string results in
			   invalid format string	    compile-time error
			   objects that are neither
	P2418R2  C++20	     const-usable  nor	copyable	allow formatting
     these objects
			   (such as generator-like objects)
			   are not formattable
	P2508R1 C++20	   there's no user-visible name for the name  basic_for-
     mat_string is
			   this facility		    exposed

See also
	format_to   writes out formatted representation of its arguments through
     an output
	(C++20)     iterator
		    (function template)
	format_to_n writes out formatted representation of its arguments through
     an output
	(C++20)     iterator, not exceeding specified size
		    (function template)

http://cppreference.com 	   2024.06.10		  std::formatted_size(3)
home | help