std::formatter<std::chrono::duration>

Определён в заголовочном файле `<chrono>`
template< class Rep, class Period, class CharT > struct formatter<std::chrono::duration<Rep, Period>, CharT>;

Специализация std::formatter, определяющая правила форматирования для std::chrono::duration. duration интерпретируется как время суток, прошедшее с полуночи.

Специализация std::formatter обычно не используется напрямую, а применяется через функции форматирования.

Спецификация формата

Спецификация формата имеет следующий вид

fill-and-align (необязательно) width (необязательно) precision (необязательно) L(необязательно) chrono-spec (необязательно)

fill-and-align, width и precision имеют то же значение, что и в стандартной спецификации формата. precision допустим только для типов std::chrono::duration, у которых тип представления Rep является типом с плавающей точкой; в противном случае выбрасывается std::format_error.

Локаль, используемая для форматирования, определяется следующим образом:

локаль "C" по умолчанию, если в спецификации формата отсутствует L,
в противном случае — локаль, заданная объектом std::locale, переданным функции форматирования, если он передан,
в противном случае (если L присутствует, но функции форматирования не передан std::locale) используется глобальная локаль.

Если кодировка (обычных или широких) строковых литералов является формой кодирования Unicode, а локаль входит в определённый реализацией набор локалей, каждая зависящая от локали замена выполняется так, как если бы заменяющая последовательность символов была преобразована в кодировку литерала.

chrono-spec состоит из одного или нескольких спецификаторов преобразования и обычных символов (кроме {, } и %). chrono-spec должен начинаться со спецификатора преобразования. Все обычные символы выводятся без изменений. Каждый неизменённый спецификатор преобразования начинается с символа %, за которым следует символ, определяющий поведение спецификатора. Некоторые спецификаторы преобразования имеют модифицированную форму, в которой после символа % вставляется символ-модификатор E или O. Каждый спецификатор преобразования заменяется в выходных данных соответствующими символами, как описано ниже.

Если не указано иное, при пустом значении chrono-spec объект chrono форматируется так, как если бы он был передан в потоковый оператор вывода объекта os типа std::basic_ostringstream<CharT> с локалью форматирования (одной из std::locale::classic(), переданного объекта std::locale и std::locale::global()), установленной с помощью imbue, а os.str() скопирован в выходной буфер с дополнительным дополнением и корректировками в соответствии со спецификаторами формата.

Доступны следующие спецификаторы формата:

Спецификатор преобразования	Описание
`%%`	Записывает буквальный символ `%`.
`%n`	Записывает символ новой строки.
`%t`	Записывает символ горизонтальной табуляции.
Время суток
`%H` `%OH`	Записывает час (в 24-часовом формате) в виде десятичного числа. Если результат состоит из одной цифры, перед ней добавляется 0. Модифицированная команда `%OH` записывает альтернативное представление, используемое в локали.
`%I` `%OI`	Записывает час (в 12-часовом формате) в виде десятичного числа. Если результат состоит из одной цифры, перед ней добавляется 0. Модифицированная команда `%OI` записывает альтернативное представление, используемое в локали.
`%M` `%OM`	Записывает минуту в виде десятичного числа. Если результат состоит из одной цифры, перед ней добавляется 0. Модифицированная команда `%OM` записывает альтернативное представление, используемое в локали.
`%S` `%OS`	Записывает секунду в виде десятичного числа. Если количество секунд меньше 10, перед результатом добавляется 0. Если точность входного значения нельзя точно представить в секундах, результатом будет десятичное число с фиксированной точкой и точностью, соответствующей точности входного значения (или с точностью до микросекунд, если преобразование в десятичное число секунд с плавающей точкой невозможно выполнить с количеством дробных цифр не более 18). Символ десятичного разделителя определяется локалью. Модифицированная команда `%OS` записывает альтернативное представление, используемое в локали.
`%p`	Записывает эквивалентные обозначения AM/PM, используемые в локали для 12-часового формата времени.
`%R`	Эквивалентно `"%H:%M"`.
`%T`	Эквивалентно `"%H:%M:%S"`.
`%r`	Записывает представление времени в 12-часовом формате, используемое в локали.
`%X` `%EX`	Записывает представление времени, используемое в локали. Модифицированная команда `%EX` записывает альтернативное представление времени, используемое в локали.
Счётчик длительности
`%Q`	Записывает количество тиков длительности, то есть значение, полученное с помощью `count()`.
`%q`	Записывает суффикс единицы измерения длительности, указанный в `operator<<()`.

Распознаются следующие спецификаторы, но они приводят к выбрасыванию std::format_error:

Спецификатор преобразования	Описание
Год
`%C` `%EC`	Записывает год, делённый на 100 с округлением вниз. Если результат состоит из одной десятичной цифры, перед ней добавляется 0. Модифицированная команда `%EC` записывает альтернативное представление века, используемое в локали.
`%y` `%Oy` `%Ey`	Записывает последние две десятичные цифры года. Если результат состоит из одной цифры, перед ней добавляется 0. Модифицированная команда `%Oy` записывает альтернативное представление, используемое в локали. Модифицированная команда `%Ey` записывает альтернативное представление смещения от `%EC` (только год), используемое в локали.
`%Y` `%EY`	Записывает год в виде десятичного числа. Если результат содержит меньше четырёх цифр, слева добавляются нули до четырёх цифр. Модифицированная команда `%EY` записывает альтернативное полное представление года, используемое в локали.
Месяц
`%b` `%h`	Записывает сокращённое название месяца, используемое в локали.
`%B`	Записывает полное название месяца, используемое в локали.
`%m` `%Om`	Записывает месяц в виде десятичного числа (январь — `01`). Если результат состоит из одной цифры, перед ней добавляется 0. Модифицированная команда `%Om` записывает альтернативное представление, используемое в локали.
День
`%d` `%Od`	Записывает день месяца в виде десятичного числа. Если результат состоит из одной десятичной цифры, перед ней добавляется 0. Модифицированная команда `%Od` записывает альтернативное представление, используемое в локали.
`%e` `%Oe`	Записывает день месяца в виде десятичного числа. Если результат состоит из одной десятичной цифры, перед ней добавляется пробел. Модифицированная команда `%Oe` записывает альтернативное представление, используемое в локали.
День недели
`%a`	Записывает сокращённое название дня недели, используемое в локали.
`%A`	Записывает полное название дня недели, используемое в локали.
`%u` `%Ou`	Записывает день недели ISO в виде десятичного числа (1–7), где понедельник — `1`. Модифицированная команда `%Ou` записывает альтернативное представление, используемое в локали.
`%w` `%Ow`	Записывает день недели в виде десятичного числа (0–6), где воскресенье — `0`. Модифицированная команда `%Ow` записывает альтернативное представление, используемое в локали.
Неделя ISO 8601 и соответствующий ей год
В ISO 8601 неделя начинается в понедельник, а первая неделя года должна соответствовать следующим требованиям: Включает 4 января Включает первый четверг года
`%g`	Записывает последние две десятичные цифры года, соответствующего неделе ISO 8601. Если результат состоит из одной цифры, перед ней добавляется 0.
`%G`	Записывает год, соответствующий неделе ISO 8601, в виде десятичного числа. Если результат содержит меньше четырёх цифр, слева добавляются нули до четырёх цифр.
`%V` `%OV`	Записывает номер недели ISO 8601 в году в виде десятичного числа. Если результат состоит из одной цифры, перед ней добавляется 0. Модифицированная команда `%OV` записывает альтернативное представление, используемое в локали.
Неделя/день года
`%j`	Записывает день года в виде десятичного числа (1 января — `001`). Если результат содержит меньше трёх цифр, слева добавляются нули до трёх цифр.
`%U` `%OU`	Записывает номер недели года в виде десятичного числа. Первое воскресенье года является первым днём недели 01. Дни того же года, предшествующие этому воскресенью, относятся к неделе 00. Если результат состоит из одной цифры, перед ней добавляется 0. Модифицированная команда `%OU` записывает альтернативное представление, используемое в локали.
`%W` `%OW`	Записывает номер недели года в виде десятичного числа. Первый понедельник года является первым днём недели 01. Дни того же года, предшествующие этому понедельнику, относятся к неделе 00. Если результат состоит из одной цифры, перед ней добавляется 0. Модифицированная команда `%OW` записывает альтернативное представление, используемое в локали.
Дата
`%D`	Эквивалентно `"%m/%d/%y"`.
`%F`	Эквивалентно `"%Y-%m-%d"`.
`%x` `%Ex`	Записывает представление даты, используемое в локали. Модифицированная команда `%Ex` формирует альтернативное представление даты, используемое в локали.
Часовой пояс
`%z` `%Ez` `%Oz`	Записывает смещение от UTC в формате ISO 8601. Например, `-0430` означает, что время отстаёт от UTC на 4 часа 30 минут. Если смещение равно нулю, используется `+0000`. Модифицированные команды `%Ez` и `%Oz` вставляют `:` между часами и минутами (например, `-04:30`).
`%Z`	Записывает сокращённое название часового пояса.
Разное
`%c` `%Ec`	Записывает представление даты и времени, используемое в локали. Модифицированная команда `%Ec` записывает альтернативное представление даты и времени, используемое в локали.

Пример

#include <chrono>
#include <print>
using namespace std::chrono_literals;

int main()
{
    auto du{3h + 2min + 1s};

    std::print(
        "Duration is:\n"
        "{}\n"
        "{:%T}\n"
        "{:%H:%M:%S}\n"
        "{:%H hours %M minutes %S seconds}\n",
        du, du, du, du);
}

Возможный вывод:

Duration is:
10921s
03:02:01
03:02:01
03 hours 02 minutes 01 seconds

См. также

format

(C++20)

сохраняет отформатированное представление аргументов в новой строке
(шаблон функции)

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