std::vprint_unicode, std::vprint_unicode_buffered
<print>
std::string_view fmt, std::format_args args );
std::string_view fmt, std::format_args args );
Format args according to the format string fmt, and writes the result to the output stream.
- Locks stream.
- Let out denote the character representation of formatting arguments provided by args formatted according to specifications given in fmt.
- Writes out to stream:
- If stream refers to a terminal that is only capable of displaying Unicode via a native Unicode API, flushes stream and writes out to the terminal using the native Unicode API.
- Otherwise, writes unmodified out to the stream.
- stream is not a valid pointer to an output C stream.
- out contains invalid Unicode code units when the native Unicode API is used.
std::vprint_unicode(stream, "{}", std::make_format_args (out));.
After writing characters to the output stream, establishes an observable checkpoint.
(since C++26)[edit] Parameters
- ordinary characters (except { and }), which are copied unchanged 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)
args
whose value is to be used for formatting; if it is omitted, the arguments are used in order.
The arg-id s in a format string must all be present or all be omitted. Mixing manual and automatic indexing is an error.
- 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 thread id format specification and stacktrace entry format specification.
- For std::basic_stacktrace, no format specifier is allowed.
- For other formattable types, the format specification is determined by user-defined
formatter
specializations.
[edit] 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::format_error .
[edit] Notes
The C++ standard encourages the implementers to produce a diagnostic message if out contains invalid Unicode code units.
On POSIX, writing to a terminal is done using the usual standard I/O functions, so there is no need to treat a terminal differently to any other file stream.
On Windows, the stream refers to a terminal if GetConsoleMode(_get_osfhandle(_fileno(stream))) returns nonzero (see Windows documentation for GetConsoleMode
, _get_osfhandle
, and _fileno
). The native Unicode API on Windows is WriteConsoleW
.
If invoking the native Unicode API requires transcoding, the invalid code units are substituted with U+FFFD
REPLACEMENT CHARACTER (see "The Unicode Standard - Core Specification", Chapter 3.9).
Feature-test macro | Value | Std | Feature |
---|---|---|---|
__cpp_lib_print |
202207L |
(C++23) | Formatted output |
202403L |
(C++26) (DR23) |
Unbuffered formatted output | |
202406L |
(C++26) (DR23) |
Enabling unbuffered formatted output for more formattable types | |
__cpp_lib_format |
202207L |
(C++23) | Exposing std::basic_format_string |
[edit] Example
Reason: no example
[edit] 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 4044 | C++23 | the native Unicode API was always used if the terminal referred to by stream can display Unicode |
only used if the terminal can only use the native Unicode API to display Unicode |
P3107R5 | C++23 | printing operations were always buffered | provides unbuffered printing operations |
P3235R3 | C++23 | the names of the functions added by P3107R5 were misleading |
changed the function names |
[edit] See also
(function template) [edit]