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

NAME
     std::print - std::print

Synopsis
	Defined in header <print>
	template<   class...   Args  >					     (1)
     (since C++23)
	void print( std::format_string<Args...> fmt, Args&&... args );
	template< class... Args >

	void  print(  std::FILE*   stream,				     (2)
     (since C++23)

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

	Format	args according to the format string fmt, and print the result to
     an output
	stream.

	1) Equivalent to std::print(stdout, fmt, std::forward<Args>(args)...).
	2) If the ordinary literal encoding is UTF-8, equivalent to
	(std::enable_nonlocking_formatter_optimization<std::re-
     move_cvref_t<Args>> && ...)
	    ?	  std::vprint_unicode_locking(stream,	  fmt.str,     make_for-
     mat_args(args...))
	    : std::vprint_unicode(stream, fmt.str, make_format_args(args...));.
	Otherwise, equivalent to
	(std::enable_nonlocking_formatter_optimization<std::re-
     move_cvref_t<Args>> && ...)
	    ?	 std::vprint_nonunicode_locking(stream,    fmt.str,    make_for-
     mat_args(args...))
	    :	   std::vprint_nonunicode(stream,	fmt.str,       make_for-
     mat_args(args...));.

	The behavior is undefined if std::formatter<Ti, char> does not meet the
	BasicFormatter requirements for any Ti in Args (as required by
	std::make_format_args).

Parameters
	stream	- output file stream to write to

		  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

Exceptions
	  * std::bad_alloc on allocation failure.
	  * std::system_error, if writing to the stream fails.
	  *  Propagates  any exception thrown by used formatters, e.g. std::for-
     mat_error.

Notes
	Feature-test macro  Value    Std		 Feature
			   202207L (C++23) Formatted output
	__cpp_lib_print    202403L (C++26) Formatted output with stream locking
				   (DR23)
	__cpp_lib_format   202207L (C++23) Exposing std::basic_format_string

Example
     // Run this code

      #include <cstdio>
      #include <filesystem>
      #include <print>

      int main()
      {
	  std::print("{0} {2}{1}!\n", "Hello", 23, "C++"); // overload (2)

	  const auto tmp {std::filesystem::temp_directory_path() / "test.txt"};

	  if (std::FILE* stream{std::fopen(tmp.c_str(), "w")})
	  {
	      std::print(stream, "File: {}", tmp.string()); // overload (1)
	      std::fclose(stream);
	  }
      }

Output:
      Hello C++23!

See also
	println 	    same as std::print except that each print is  termi-
     nated by
	(C++23) 	    additional new line
			    (function template)
	print(std::ostream) outputs formatted representation of the arguments
	(C++23) 	    (function template)
	format		     stores formatted representation of the arguments in
     a new string
	(C++20) 	    (function template)
	format_to	    writes out formatted representation of its arguments
     through an
	(C++20) 	    output iterator
			    (function template)
	printf
	fprintf 	    prints formatted output to stdout, a file stream  or
     a buffer
	sprintf 	    (function)
	snprintf
	(C++11)

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