std::vprint_unicode, std::vprint_unicode_buffered

Определено в заголовочном файле <print>

Определено в заголовочном файле `<print>`
void vprint_unicode( std::FILE* stream, std::string_view fmt, std::format_args args );	(1)	(начиная с C++23)
void vprint_unicode_buffered( std::FILE* stream, std::string_view fmt, std::format_args args );	(2)	(начиная с C++23)
void vprint_unicode_buffered( std::string_view fmt, std::format_args args );	(3)	(начиная с C++23)

void vprint_unicode( std::FILE* stream,
                     std::string_view fmt, std::format_args args );

(1)

(начиная с C++23)

void vprint_unicode_buffered( std::FILE* stream,
                              std::string_view fmt, std::format_args args );

(2)

(начиная с C++23)

void vprint_unicode_buffered( std::string_view fmt, std::format_args args );

(3)

(начиная с C++23)

Форматирует args в соответствии со строкой формата fmt и записывает результат в выходной поток.

1) Выполняет следующие операции по порядку:

Блокирует stream.
Пусть out обозначает символьное представление аргументов форматирования, предоставленных с помощью args и отформатированных согласно спецификациям, заданным в fmt.
Записывает out в stream:

Если stream ссылается на терминал, способный отображать Unicode только с помощью собственного API Unicode, сбрасывает буфер stream и записывает out в терминал с помощью собственного API Unicode.
В противном случае записывает неизменённое out в stream.

Безусловно разблокирует stream при выходе из функции.

Поведение не определено, если выполняется любое из следующих условий:

stream не является допустимым указателем на выходной поток C.
out содержит недопустимые кодовые единицы Unicode, когда используется собственный API Unicode.

2) Эквивалентно

std::string out = std::vformat(fmt, args);
std::vprint_unicode(stream, "{}", std::make_format_args(out));

3) Эквивалентно std::vprint_unicode_buffered(stdout, fmt, args).

После записи символов в выходной поток устанавливает наблюдаемую контрольную точку.

(начиная с C++26)

Параметры

stream - выходной файловый поток для записи

fmt

объект, представляющий строку формата. Строка формата состоит из

обычных символов (кроме { и }), которые без изменений копируются в выходные данные,
последовательностей экранирования {{ и }}, которые заменяются в выходных данных на { и } соответственно, а также
полей подстановки.

Каждое поле подстановки имеет следующий формат:

`{` arg-id (необязательно) `}`	(1)
`{` arg-id (необязательно) `:` format-spec `}`	(2)

1) поле подстановки без спецификации формата 2) поле подстановки со спецификацией формата

arg-id	-	задаёт индекс аргумента в `args`, значение которого используется для форматирования; если он опущен, аргументы используются по порядку. Все arg-id в строке формата должны быть либо указаны, либо опущены. Смешивание ручной и автоматической индексации является ошибкой.
format-spec	-	спецификация формата, определённая специализацией `std::formatter` для соответствующего аргумента. Не может начинаться с `}`.

Для базовых типов и стандартных строковых типов спецификация формата интерпретируется как стандартная спецификация формата.
Для типов chrono спецификация формата интерпретируется как спецификация формата chrono.

Для типов диапазонов спецификация формата интерпретируется как спецификация формата диапазона.
Для std::pair и std::tuple спецификация формата интерпретируется как спецификация формата кортежа.
Для std::thread::id и std::stacktrace_entry см. спецификацию формата идентификатора потока и спецификацию формата элемента трассировки стека.
Для std::basic_stacktrace спецификатор формата не допускается.

(начиная с C++23)

Для std::filesystem::path см. спецификацию формата пути.

(начиная с C++26)

Для других форматируемых типов спецификация формата определяется пользовательскими специализациями formatter.

args - аргументы для форматирования

Исключения

std::bad_alloc при сбое выделения памяти.
std::system_error, если запись в поток завершается неудачей.
Передаёт любое исключение, выброшенное используемыми форматтерами, например std::format_error.

Примечания

Стандарт C++ рекомендует разработчикам реализаций выдавать диагностическое сообщение, если out содержит недопустимые кодовые единицы Unicode.

В POSIX запись в терминал выполняется с помощью обычных функций стандартного ввода-вывода, поэтому нет необходимости обрабатывать терминал иначе, чем любой другой файловый поток.

В Windows поток считается связанным с терминалом, если GetConsoleMode(_get_osfhandle(_fileno(stream))) возвращает ненулевое значение (см. документацию Windows для GetConsoleMode, _get_osfhandle и _fileno). Собственным API Unicode в Windows является WriteConsoleW.

Если для вызова собственного API Unicode требуется транскодирование, недопустимые кодовые единицы заменяются на U+FFFD REPLACEMENT CHARACTER (см. «Стандарт Unicode — базовая спецификация», глава 3.9).

Макрос проверки возможностей	Значение	Стандарт	Возможность
`__cpp_lib_print`	`202207L`	(C++23)	Форматированный вывод
	`202403L`	(C++26) (DR23)	Небуферизованный форматированный вывод
	`202406L`	(C++26) (DR23)	Поддержка небуферизованного форматированного вывода для большего числа форматируемых типов
`__cpp_lib_format`	`202207L`	(C++23)	Предоставление `std::basic_format_string`

Пример

Отчёты об ошибках

Следующие отчёты об ошибках, изменяющие поведение, были применены задним числом к ранее опубликованным стандартам C++.

DR	Применяется к	Опубликованное поведение	Правильное поведение
LWG 4044	C++23	собственный API Unicode использовался всегда, если терминал, на который ссылается `stream`, может отображать Unicode	используется только в том случае, если терминал может отображать Unicode только с помощью собственного API Unicode
P3107R5	C++23	операции вывода всегда были буферизованными	предоставляет небуферизованные операции вывода
P3235R3	C++23	названия функций, добавленных в P3107R5, вводили в заблуждение	изменены названия функций

См. также

vprint_nonunicodevprint_nonunicode_buffered (C++23)	выводит данные в `stdout` или файловый поток, используя стираемое по типу представление аргументов (функция)
vprint_unicode(std::ostream) (C++23)	выполняет вывод с поддержкой Unicode, используя стираемое по типу представление аргументов (функция)
print (C++23)	выводит данные в `stdout` или файловый поток, используя форматированное представление аргументов (шаблон функции)
format (C++20)	сохраняет форматированное представление аргументов в новой строке (шаблон функции)

Внешние ссылки

1.	Unicode
2.	Стандарт Unicode, версия 14.0 — базовая спецификация

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/io/vprint_unicode