Пользовательские типы и std::format в C++20

std::format — очень полезное (и серьезное) нововведение C++20, позволяющее нам форматировать текст в строки удобным и эффективным образом. Оно привносит в язык форматирование в стиле Python в сочетании с безопасностью и простотой использования.

В этой статье я расскажу, как реализовать пользовательские средства форматирования (форматтеры) в соответствии с новой std::format архитектурой.

Краткое введение в std::format    

Давайте взглянем на этот Hello World:

#include <format> #include <iostream> #include <chrono>  int main() {     auto ym = std::chrono::year { 2022 } / std::chrono::July;     std::string msg = std::format("{:*^10}\n{:*>10}\nin{}!", "hello", "world", ym);     std::cout << msg; }

Вы можете посмотреть этот код в Compiler Explorer.

Вывод:

**hello*** *****world in2022/Jul!

Мы здесь видим местозаполнители для аргументов, которые разворачиваются и форматируются в объект std::string. Кроме того, у нас есть различные спецификаторы для управления выводом (тип, длина, точность, заполняющие символы и т. д.). Мы также можем использовать пустой местозаполнитель {}, который даст нам дефолтный вывод конкретного типа (к слову, поддерживается даже std::chrono!). Позже мы можем вывести эту строку в объект-поток.

Подробнее о архитектуре и фичах вы можете узнать в этой статье. 

Существующие форматтеры    

По умолчанию std::format поддерживает следующие типы:

• char, wchar_t;

• строковые типы, включая std::basic_string, std::basic_string_view, массивы символов и строковые литералы;

• арифметические типы;

• указатели: void*, const void* и nullptr_t.

Это определено в стандарте formatter, вы можете увидеть это в спецификации [format.formatter.spec]:

Давайте вызовем:

std::cout << std::format("10 = {}, 42 = {:10}\n", 10, 42);

Вызов создаст два форматтера, по одному для каждого аргумента. На них лежит задача распарсить спецификатор формата и отформатировать значение в вывод.

Специализации форматтеров:

template<> struct formatter<char, char>; template<> struct formatter<char, wchar_t>; template<> struct formatter<wchar_t, wchar_t>;

Все специализации для строковых типов и charT:

template<> struct formatter<charT*, charT>; template<> struct formatter<const charT*, charT>; template<size_t N> struct formatter<const charT[N], charT>; template<class traits, class Allocator>   struct formatter<basic_string<charT, traits, Allocator>, charT>; template<class traits>   struct formatter<basic_string_view<charT, traits>, charT>;

Для каждого charT, а также для каждого cv-неквалифицированного арифметического типа ArithmeticT, не являющегося char, wchar_t, char8_t, char16_t или char32_t, есть специализация:

template<> struct formatter<ArithmeticT, charT>;

Специализации для типов указателей и charT:

template<> struct formatter<nullptr_t, charT>; template<> struct formatter<void*, charT>; template<> struct formatter<const void*, charT>;

Например, если вы хотите вывести указатель:

int val = 10; std::cout << std::format("val = {}, &val = {}\n", val, &val);

Этот код не будет работать, и вы получите ошибку компилятора (не самую лаконичную, но зато понятную):

auto std::make_format_args<std::format_context,int,int*>(const int &,int *const &)'   was being compiled and failed to find the required specializations (в процессе компиляции не смог найти нужных специализаций)...

Это потому, что мы пытались вывести int*, но библиотека поддерживает только void*. Мы можем это обойти, написав:

int val = 10; std::cout << std::format("val = {}, &val = {}\n", val, static_cast<void*>(&val)); 

И тогда вывод будет (MSVC, x64, Debug):

val = 10, &val = 0xf5e64ff2c4

В библиотеке {fmt} даже реализована такая вспомогательная функция, но в Стандарте, увы, нет.

template<typename T> auto fmt::ptr(T p) -> const void*

Хорошо, а что насчет пользовательских типов?

Для потоков мы можем переопределить оператор <<, и такой код будет работать. Но так же ли это просто для std::format?

Давайте разберемся.

Пользовательские форматтеры    

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

Чтобы создать форматтер, можно использовать следующий код:

template <> struct std::formatter<MyType> {     constexpr auto parse(std::format_parse_context& ctx) {         return /* */;     }      auto format(const MyType& obj, std::format_context& ctx) {         return std::format_to(ctx.out(), /* */);     } };

Вот основные требования к такому типу функций (из Стандарта):

Тут больше кода, чем нам нужно было написать для оператора <<, и все это звучит чуть более сложно, так что давайте попробуем разобраться с тем, что от нас требует Стандарт.

Одно значение     

Для начала возьмем простой тип-обертку с одним значением:

struct Index {     unsigned int id_{ 0 }; };

И для него мы можем написать следующий форматтер:

template <> struct std::formatter<Index> {     // только для дебагга     formatter() { std::cout << "formatter<Index>()\n"; }      constexpr auto parse(std::format_parse_context& ctx) {         return ctx.begin();     }      auto format(const Index& id, std::format_context& ctx) {         return std::format_to(ctx.out(), "{}", id.id_);     } };

Пример использования:

Index id{ 100 }; std::cout << std::format("id {}\n", id); std::cout << std::format("id duplicated {0} {0}\n", id);

Мы получим следующий вывод:

formatter<Index>() id 100 formatter<Index>() formatter<Index>() id duplicated 100 100

Как видите, даже для дублируемого аргумента {0} создаются два форматтера, а не один.

Функция parse() принимает контекст и получает спецификатор формата для данного аргумента.

Например:

"{0}"      // ctx.begin() указывает на `}` "{0:d}"    // ctx.begin() указывает на `d`, а begin-end — "d}" "{:hello}" // ctx.begin() указывает на 'h', а begin-end — "hello}"

Функция parse() должна вернуть итератор на закрывающую скобку, поэтому нам нужно найти ее или предположить, что она находится в позиции ctx.begin().

В случае {:hello} возврат begin() не будет указывать на } и, таким образом, мы получите ошибку времени выполнения — будет сгенерировано исключение. Так что будьте внимательны!

Для простого случая с одним значением мы можем положиться на стандартную реализацию и попросту задействуем этот код:

template <> struct std::formatter<Index> : std::formatter<int> {     auto format(const Index& id, std::format_context& ctx) {         return std::formatter<int>::format(id.id_, ctx);     } };

Теперь наш код будет работать, распаршивая стандартные спецификаторы:

Index id{ 100 }; std::cout << std::format("id {:*<11d}\n", id); std::cout << std::format("id {:*^11d}\n", id);

Вывод:

id 100******** id ****100****

Несколько значений   

А что насчет случаев, когда мы хотели бы показать несколько значений:

struct Color {     uint8_t r{ 0 };     uint8_t g{ 0 };     uint8_t b{ 0 }; };

Чтобы создать создать форматтер, мы можем написать что-то вроде этого:

template <> struct std::formatter<Color> {     constexpr auto parse(std::format_parse_context& ctx) {         return ctx.begin();     }      auto format(const Color& col, std::format_context& ctx) {         return std::format_to(ctx.out(), "({}, {}, {})", col.r, col.g, col.b);     } };

Этот код поддерживает только фиксированный формат вывода и никаких дополнительных спецификаторов формата.

Однако мы можем задействовать уже готовый форматтер string_view:

template <> struct std::formatter<Color> : std::formatter<string_view> {     auto format(const Color& col, std::format_context& ctx) {         std::string temp;         std::format_to(std::back_inserter(temp), "({}, {}, {})",                         col.r, col.g, col.b);         return std::formatter<string_view>::format(temp, ctx);     } };

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

Точно так же, если ваш объект содержит контейнер значений, вы можете написать следующий код:

template <> struct std::formatter<YourType> : std::formatter<string_view> {     auto format(const YourType& obj, std::format_context& ctx) {         std::string temp;         std::format_to(std::back_inserter(temp), "{} - ", obj.GetName());          for (const auto& elem : obj.GetValues())             std::format_to(std::back_inserter(temp), "{}, ", elem);          return std::formatter<string_view>::format(temp, ctx);     } };

Приведенный выше форматтер выведет obj.GetName(), а затем элементы из obj.GetValues(). Поскольку мы наследуемся от класса string_view форматтера, здесь также применимы стандартные спецификаторы формата.

Расширение форматтера с помощью функции parse()    

Но как насчет пользовательской функции для парсинга?

Основная идея заключается в том, что мы можем распарсить строку формата, а затем сохранить некоторое состояние в *this, после чего мы можем использовать информацию в вызове format.

Давайте попробуем:

template <> struct std::formatter<Color> {     constexpr auto parse(std::format_parse_context& ctx){         auto pos = ctx.begin();         while (pos != ctx.end() && *pos != '}') {             if (*pos == 'h' || *pos == 'H')                 isHex_ = true;             ++pos;         }         return pos;  // В этой позиции ожидается `}`, иначе                       // это ошибка! Генерируется исключение!     }      auto format(const Color& col, std::format_context& ctx) {         if (isHex_) {             uint32_t val = col.r << 16 | col.g << 8 | col.b;             return std::format_to(ctx.out(), "#{:x}", val);         }                  return std::format_to(ctx.out(), "({}, {}, {})", col.r, col.g, col.b);     }      bool isHex_{ false }; };

И тест:

std::cout << std::format("col {}\n", Color{ 100, 200, 255 }); std::cout << std::format("col {:h}\n", Color{ 100, 200, 255 });

Вывод:

col (100, 200, 255) col #64c8ff

Резюме

Чтобы обеспечить поддержку пользовательских типов в std::format, мы должны реализовать специализацию для std::formatter. Этот класс должен предоставлять функции parse() и format(). Первая отвечает за парсинг спецификатора формата и сохранение дополнительных данных в *this, если это необходимо, а вторая выводит значения в выходной буфер out, предоставленный контекстом форматирования.

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

Вы можете изучить код, используемый в этой статье в Compiler Explorer.

В Visual Studio 2022 версии 17.2 и Visual Studio 2019 версии 16.11.14 вы можете использовать std:c++20, но в более ранних версиях используйте /std:latest (поскольку он все еще находился в разработке). По состоянию на июль 2022 года GCC еще не реализовал эту фичу. Clang 14 имеет экспериментальную внутреннюю реализацию, но она еще не раскрыта.

Ссылки

• Справочное руководство по API — документация fmt 8.1.0

• Форматирование определяемых пользователем типов с помощью библиотеки {fmt} — во многих случаях мы можем просто заменить fmt:: на std::, поэтому ознакомление с документацией по fmt не будет лишним.

• Внеземное руководство по форматированию текста в C++20 — C++ Stories

• C++20 — Полное руководство от Nicolai M. Josuttis — трюки с наследованием существующих типов и повторным использованием их функционала форматирования.

• MSVC’s STL Completes /std:c++20 — Блог команды разработчиков C++

---

Хоть и модно критиковать ООП-подход к разработке кода, он остаётся самым популярным во многих и многих сферах. Поэтому не знать и не уметь использовать данную парадигму разработки для настоящего профессионала просто не вежливо. Приглашаем всех желающих на открытое занятие «ООП глазами C++», на котором поговорим и посмотрим на примерах, как термины ООП реализуются в синтаксисе языка C++.

Регистрация на занятие.