[Перевод] Пользовательские типы и std::format в C++2007.09.2022 14:02

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

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

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

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

#include 
#include 
#include 

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;
template<> struct formatter;
template<> struct formatter;

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

template<> struct formatter;
template<> struct formatter;
template struct formatter;
template
  struct formatter, charT>;
template
  struct formatter, charT>;

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

template<> struct formatter;

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

template<> struct formatter;
template<> struct formatter;
template<> struct formatter;

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

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

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

auto std::make_format_args(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(&val)); 

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

val = 10, &val = 0xf5e64ff2c4

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

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

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

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

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

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

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

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

emplate <>
struct std::formatter {
    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 {
    // только для дебагга
    formatter() { std::cout << "formatter()\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()
id 100
formatter()
formatter()
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 : std::formatter {
    auto format(const Index& id, std::format_context& ctx) {
        return std::formatter::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 {
    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 : std::formatter {
    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::format(temp, ctx);
    }
};

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

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

template <>
struct std::formatter : std::formatter {
    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::format(temp, ctx);
    }
};

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

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

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

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

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

emplate <>
struct std::formatter {
    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 имеет экспериментальную внутреннюю реализацию, но она еще не раскрыта.

Ссылки

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

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

© Habrahabr.ru