Заголовочный файл стандартной библиотеки <format> (C++20)

 

C++

Поддержка компилятором

Автономные и размещённые реализации

Язык

Стандартная библиотека

Заголовки стандартной библиотеки

Требования к именованию

Макросы тестирования функциональности (C++20)

Поддержка языка

Библиотека концептов (C++20)

Библиотека метапрограммирования (C++11)

Библиотека диагностики

Библиотека общих утилит

Библиотека строк

Библиотека контейнеров

Библиотека итераторов

Библиотека диапазонов (C++20)

Библиотека алгоритмов

Библиотека численных данных

Библиотека ввода/вывода

Библиотека локализаций

Регулярные выражения (C++11)

Атомарные операции (C++11)

Библиотека поддержки конкуренции (C++11)

Библиотека файловой системы (C++17)

Технические спецификации

Указатель символов

Внешние библиотеки

 

Заголовочные файлы стандартной библиотеки

Языковая поддержка
<cstddef> <cstdlib> <version> (C++20) <limits> <climits>	<cfloat> <cstdint> (C++11) <stdfloat> (C++23) <new> <typeinfo>	<source_location> (C++20) <exception> <initializer_list> (C++11) <compare> (C++20)	<coroutine> (C++20) <csignal> <csetjmp> <cstdarg>
Концепты
<concepts> (C++20)
Диагностика
<stdexcept> <stacktrace> (C++23)	<cassert>	<cerrno>	<system_error> (C++11)
Управление памятью
<memory>	<memory_resource> (C++17)	<scoped_allocator> (C++11)
Метапрограммирование
<type_traits> (C++11)	<ratio> (C++11)
Общие утилиты
<utility> <tuple> (C++11) <optional> (C++17) <variant> (C++17)	<any> (C++17) <expected> (C++23) <bitset>	<functional> <typeindex> (C++11) <execution> (C++17)	<charconv> (C++17) <format> (C++20) <bit> (C++20)
Строки
<string_view> (C++17) <string>	<cctype> <cwctype>	<cstring> <cwchar>	<cuchar> (C++11)
Контейнеры
<array> (C++11) <deque> <forward_list> (C++11) <list>	<vector> <map> <set> <unordered_map> (C++11)	<unordered_set> (C++11) <queue> <stack> <flat_map> (C++23)	<flat_set> (C++23) <span> (C++20) <mdspan> (C++23)
Итераторы
<iterator>
Диапазоны
<ranges> (C++20)	<generator> (C++23)
Алгоритмы
<algorithm>	<numeric>
Числа
<cfenv> (C++11) <complex>	<random> (C++11) <valarray>	<cmath>	<numbers> (C++20)
Время
<chrono> (C++11)	<ctime>
Локализация
<locale>	<clocale>	<codecvt> (C++11/17*)
Ввод/вывод
<iosfwd> <iostream> <ios> <streambuf>	<istream> <ostream> <iomanip> <print> (C++23)	<sstream> <spanstream> (C++23) <fstream> <syncstream> (C++20)	<filesystem> (C++17) <cstdio> <cinttypes> (C++11) <strstream> (C++98*)
Регулярные выражения
<regex> (C++11)
Поддержка конкуренции
<stop_token> (C++20) <thread> (C++11) <atomic> (C++11)	<stdatomic.h> (C++23) <mutex> (C++11) <shared_mutex> (C++14)	<condition_variable> (C++11)   <semaphore> (C++20) <latch> (C++20)	<barrier> (C++20) <future> (C++11)
Совместимость с C
<cstdbool> (C++11/17/20*)   <ccomplex> (C++11/17/20*)	<ctgmath> (C++11/17/20*)	<cstdalign> (C++11/17/20*)	<ciso646> (до C++20)

 

Этот заголовок является частью библиотеки форматирования.

Концепты
formattable (C++23)	указывает, что тип является форматируемым, то есть он специализирует std::formatter и предоставляет функции-элементы parse и format (концепт)
Перечисления
range_format (C++23)	указывает, как должен быть отформатирован диапазон (перечисление)
Клыссы
formatter (C++20)	шаблонный класс, который определяет правила форматирования для данного типа (шаблон класса)
range_formatter (C++23)	шаблонный класс, который помогает реализовать специализации std::formatter для диапазонных типов (шаблон класса)
basic_format_parse_contextformat_parse_contextwformat_parse_context (C++20)(C++20)(C++20)	состояние парсера строки форматирования (шаблон класса)
basic_format_contextformat_contextwformat_context (C++20)(C++20)(C++20)	состояние форматирования, включая все аргументы форматирования и итератор вывода (шаблон класса)
basic_format_arg (C++20)	шаблонный класс, который предоставляет доступ к аргументу форматирования для определяемых пользователем средств форматирования (шаблон класса)
basic_format_argsformat_argswformat_args (C++20)(C++20)(C++20)	класс, который обеспечивает доступ ко всем аргументам форматирования (шаблон класса)
basic_format_stringformat_stringwformat_string (C++20)(C++20)(C++20)	шаблон класса, который выполняет проверку строки формата во время компиляции во время построения (шаблон класса)
format_error (C++20)	тип исключения, возникающий при ошибках форматирования (класс)
Функции
format (C++20)	сохраняет форматированное представление аргументов в новой строке (шаблон функции)
format_to (C++20)	записывает форматированное представление своих аргументов через итератор вывода (шаблон функции)
format_to_n (C++20)	записывает форматированное представление своих аргументов через итератор вывода, не превышая заданного размера (шаблон функции)
formatted_size (C++20)	определяет количество символов, необходимых для хранения форматированного представления его аргументов (шаблон функции)
vformat (C++20)	нешаблонный вариант std::format с использованием представления аргументов с удалением типа (функция)
vformat_to (C++20)	нешаблонный вариант std::format_to с использованием представления аргументов с удалением типа (шаблон функции)
visit_format_arg (C++20) (устарело в C++26)	интерфейс посещения аргументов для определяемых пользователем средств форматирования (шаблон функции)
make_format_argsmake_wformat_args (C++20)(C++20)	создаёт объект с удалением типа, ссылающийся на все аргументы форматирования, конвертируемый в format_args (шаблон функции)
Помощники
format_kind (C++23)	выбирает подходящий std::range_format для диапазона (шаблонная переменная)

Резюме

namespace std {
  // шаблонный класс basic_format_context
  template<class Out, class CharT> class basic_format_context;
  using format_context = basic_format_context</* неуказано */, char>;
  using wformat_context = basic_format_context</* неуказано */, wchar_t>;

  // шаблонный класс basic_format_args
  template<class Context> class basic_format_args;
  using format_args = basic_format_args<format_context>;
  using wformat_args = basic_format_args<wformat_context>;

  // шаблонный класс basic_format_string
  template<class CharT, class... Args>
    struct basic_format_string;

  template<class... Args>
    using format_string = basic_format_string<char, type_identity_t<Args>...>;
  template<class... Args>
    using wformat_string = basic_format_string<wchar_t, type_identity_t<Args>...>;

  // функции форматирования
  template<class... Args>
    string format(format_string<Args...> fmt, Args&&... args);
  template<class... Args>
    wstring format(wformat_string<Args...> fmt, Args&&... args);
  template<class... Args>
    string format(const locale& loc, format_string<Args...> fmt, Args&&... args);
  template<class... Args>
    wstring format(const locale& loc, wformat_string<Args...> fmt, Args&&... args);

  string vformat(string_view fmt, format_args args);
  wstring vformat(wstring_view fmt, wformat_args args);
  string vformat(const locale& loc, string_view fmt, format_args args);
  wstring vformat(const locale& loc, wstring_view fmt, wformat_args args);

  template<class Out, class... Args>
    Out format_to(Out out, format_string<Args...> fmt, Args&&... args);
  template<class Out, class... Args>
    Out format_to(Out out, wformat_string<Args...> fmt, Args&&... args);
  template<class Out, class... Args>
    Out format_to(Out out, const locale& loc, format_string<Args...> fmt, Args&&... args);
  template<class Out, class... Args>
    Out format_to(Out out, const locale& loc, wformat_string<Args...> fmt, Args&&... args);

  template<class Out>
    Out vformat_to(Out out, string_view fmt, format_args args);
  template<class Out>
    Out vformat_to(Out out, wstring_view fmt, wformat_args args);
  template<class Out>
    Out vformat_to(Out out, const locale& loc, string_view fmt, format_args args);
  template<class Out>
    Out vformat_to(Out out, const locale& loc, wstring_view fmt, wformat_args args);

  template<class Out> struct format_to_n_result {
    Out out;
    iter_difference_t<Out> size;
  };
  template<class Out, class... Args>
    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                        format_string<Args...> fmt, Args&&... args);
  template<class Out, class... Args>
    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                        wformat_string<Args...> fmt, Args&&... args);
  template<class Out, class... Args>
    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                        const locale& loc, format_string<Args...> fmt,
                                        Args&&... args);
  template<class Out, class... Args>
    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                        const locale& loc, wformat_string<Args...> fmt,
                                        Args&&... args);

  template<class... Args>
    size_t formatted_size(format_string<Args...> fmt, Args&&... args);
  template<class... Args>
    size_t formatted_size(wformat_string<Args...> fmt, Args&&... args);
  template<class... Args>
    size_t formatted_size(const locale& loc, format_string<Args...> fmt, Args&&... args);
  template<class... Args>
    size_t formatted_size(const locale& loc, wformat_string<Args...> fmt, Args&&... args);

  // форматтер
  template<class T, class CharT = char> struct formatter;

  // концепт форматирования
  template<class T, class CharT>
    concept formattable = /* смотрите описание */;

  template<class R, class CharT>
    concept __const_formattable_range =                            // только для описания
      ranges::input_range<const R> &&
      formattable<ranges::range_reference_t<const R>, CharT>;

  template<class R, class CharT>
    using __fmt_maybe_const =                                      // только для описания
      conditional_t<__const_formattable_range<R, CharT>, const R, R>;

  // шаблонный класс basic_format_parse_context
  template<class CharT> class basic_format_parse_context;
  using format_parse_context = basic_format_parse_context<char>;
  using wformat_parse_context = basic_format_parse_context<wchar_t>;

  // форматирование диапазонов
  // переменный шаблон format_kind
  enum class range_format {
    disabled,
    map,
    set,
    sequence,
    string,
    debug_string
  };

  template<class R>
    constexpr /* неуказано */ format_kind = /* неуказано */;

  template<ranges::input_range R>
      requires same_as<R, remove_cvref_t<R>>
    constexpr range_format format_kind<R> = /* смотрите описание */;

  // шаблонный класс range_formatter
  template<class T, class CharT = char>
    requires same_as<remove_cvref_t<T>, T> && formattable<T, CharT>
  class range_formatter;

  // шаблонный класс __range_default_formatter
  template<range_format K, ranges::input_range R, class CharT>
    struct __range_default_formatter;                              // только для описания

  // специализации для карт, наборов и строк
  template<ranges::input_range R, class CharT>
    requires (format_kind<R> != range_format::disabled) &&
             formattable<ranges::range_reference_t<R>, CharT>
  struct formatter<R, CharT> : __range_default_formatter<format_kind<R>, R, CharT> { };

  // аргументы
  // шаблонный класс basic_format_arg
  template<class Context> class basic_format_arg;

  template<class Visitor, class Context>
    decltype(auto) visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);

  // шаблонный класс __format_arg_store
  template<class Context, class... Args> class __format_arg_store; // только для описания

  template<class Context = format_context, class... Args>
    __format_arg_store<Context, Args...>
      make_format_args(Args&&... fmt_args);
  template<class... Args>
    __format_arg_store<wformat_context, Args...>
      make_wformat_args(Args&&... args);

  // класс format_error
  class format_error;
}

Шаблонный класс std::basic_format_string

namespace std {
  template<class CharT, class... Args>
  struct basic_format_string {
  private:
    basic_string_view<CharT> str;         // только для описания

  public:
    template<class T> consteval basic_format_string(const T& s);

    constexpr basic_string_view<CharT> get() const noexcept { return str; }
  };
}

Концепт std::formattable

template<class T, class CharT>
  concept formattable =
    semiregular<formatter<remove_cvref_t<T>, CharT>> &&
    requires(formatter<remove_cvref_t<T>, CharT> f,
             const formatter<remove_cvref_t<T>, CharT> cf,
             T t,
             basic_format_context<__fmt_iter_for<CharT>, CharT> fc,
             basic_format_parse_context<CharT> pc) {
        { f.parse(pc) } -> same_as<basic_format_parse_context<CharT>::iterator>;
        { cf.format(t, fc) } -> same_as<__fmt_iter_for<CharT>>;
    };

Шаблонный класс std::basic_format_parse_context

namespace std {
  template<class CharT>
  class basic_format_parse_context {
  public:
    using char_type = CharT;
    using const_iterator = typename basic_string_view<CharT>::const_iterator;
    using iterator = const_iterator;

  private:
    iterator begin_;                                    // только для описания
    iterator end_;                                      // только для описания
    enum indexing { unknown, manual, automatic };       // только для описания
    indexing indexing_;                                 // только для описания
    size_t next_arg_id_;                                // только для описания
    size_t num_args_;                                   // только для описания

  public:
    constexpr explicit basic_format_parse_context(basic_string_view<CharT> fmt,
                                                  size_t num_args = 0) noexcept;
    basic_format_parse_context(const basic_format_parse_context&) = delete;
    basic_format_parse_context& operator=(const basic_format_parse_context&) = delete;

    constexpr const_iterator begin() const noexcept;
    constexpr const_iterator end() const noexcept;
    constexpr void advance_to(const_iterator it);

    constexpr size_t next_arg_id();
    constexpr void check_arg_id(size_t id);

    template<class... Ts>
    constexpr void check_dynamic_spec(size_t id) noexcept;
    constexpr void check_dynamic_spec_integral(size_t id) noexcept;
    constexpr void check_dynamic_spec_string(size_t id) noexcept;
  };
}

Шаблонный класс std::basic_format_context

namespace std {
  template<class Out, class CharT>
  class basic_format_context {
    basic_format_args<basic_format_context> args_;      // только для описания
    Out out_;                                           // только для описания

  public:
    using iterator = Out;
    using char_type = CharT;
    template<class T> using formatter_type = formatter<T, CharT>;

    basic_format_arg<basic_format_context> arg(size_t id) const noexcept;
    std::locale locale();

    iterator out();
    void advance_to(iterator it);
  };
}

Переменный шаблон std::format_kind

template<ranges::input_range R>
    requires same_as<R, remove_cvref_t<R>>
  constexpr range_format format_kind<R> = /* смотрите описание */;

Шаблонный класс std::range_formatter

namespace std {
  template<class T, class CharT = char>
    requires same_as<remove_cvref_t<T>, T> && formattable<T, CharT>
  class range_formatter {
    formatter<T, CharT> underlying_;                        // только для описания
    basic_string_view<CharT> separator_ =                   // только для описания
      __STATICALLY_WIDEN<CharT>(", ");
    basic_string_view<CharT> __opening_bracket_ =           // только для описания
      __STATICALLY_WIDEN<CharT>("[");
    basic_string_view<CharT> __closing_bracket_ =           // только для описания
      __STATICALLY_WIDEN<CharT>("]");

  public:
    constexpr void set_separator(basic_string_view<CharT> sep);
    constexpr void set_brackets(basic_string_view<CharT> opening,
                                basic_string_view<CharT> closing);
    constexpr formatter<T, CharT>& underlying() { return underlying_; }
    constexpr const formatter<T, CharT>& underlying() const { return underlying_; }

    template<class ParseContext>
      constexpr typename ParseContext::iterator
        parse(ParseContext& ctx);

    template<ranges::input_range R, class FormatContext>
        requires formattable<ranges::range_reference_t<R>, CharT> &&
                 same_as<remove_cvref_t<ranges::range_reference_t<R>>, T>
      typename FormatContext::iterator
        format(R&& r, FormatContext& ctx) const;
  };
}

Шаблонный класс __range_default_formatter

namespace std {
  template<ranges::input_range R, class CharT>
  struct __range_default_formatter<range_format::sequence, R, CharT> {
  private:
    using __maybe_const_r = __fmt_maybe_const<R, CharT>;
    range_formatter<remove_cvref_t<ranges::range_reference_t<__maybe_const_r>>,
                    CharT> underlying_;       // только для описания

  public:
    constexpr void set_separator(basic_string_view<CharT> sep);
    constexpr void set_brackets(basic_string_view<CharT> opening,
                                basic_string_view<CharT> closing);

    template<class ParseContext>
      constexpr typename ParseContext::iterator
        parse(ParseContext& ctx);

    template<class FormatContext>
      typename FormatContext::iterator
        format(__maybe_const_r& elems, FormatContext& ctx) const;
  };
}

Специализация __range_default_formatter для карт

namespace std {
  template<ranges::input_range R, class CharT>
  struct __range_default_formatter<range_format::map, R, CharT> {
  private:
    using __maybe_const_map = __fmt_maybe_const<R, CharT>;          // только для описания
    using __element_type =                                          // только для описания
      remove_cvref_t<ranges::range_reference_t<__maybe_const_map>>;
    range_formatter<__element_type, CharT> underlying_;             // только для описания
  public:
    constexpr __range_default_formatter();

    template<class ParseContext>
      constexpr typename ParseContext::iterator
        parse(ParseContext& ctx);

    template<class FormatContext>
      typename FormatContext::iterator
        format(__maybe_const_map& r, FormatContext& ctx) const;
  };
}

Специализация __range_default_formatter для наборов

namespace std {
  template<ranges::input_range R, class CharT>
  struct __range_default_formatter<range_format::set, R, CharT> {
  private:
    using __maybe_const_set = __fmt_maybe_const<R, CharT>;          // только для описания
    range_formatter<remove_cvref_t<ranges::range_reference_t<__maybe_const_set>>,
                    CharT> underlying_;                             // только для описания
  public:
    constexpr __range_default_formatter();

    template<class ParseContext>
      constexpr typename ParseContext::iterator
        parse(ParseContext& ctx);

    template<class FormatContext>
      typename FormatContext::iterator
        format(__maybe_const_set& r, FormatContext& ctx) const;
  };
}

Специализация __range_default_formatter для строк

namespace std {
  template<range_format K, ranges::input_range R, class CharT>
    requires (K == range_format::string || K == range_format::debug_string)
  struct __range_default_formatter<K, R, CharT> {
  private:
    formatter<basic_string<CharT>, CharT> underlying_;              // только для описания

  public:
    template<class ParseContext>
      constexpr typename ParseContext::iterator
        parse(ParseContext& ctx);

    template<class FormatContext>
      typename FormatContext::iterator
        format(/* смотрите описание */& str, FormatContext& ctx) const;
  };
}

Шаблонный класс std::basic_format_arg

namespace std {
  template<class Context>
  class basic_format_arg {
  public:
    class handle;

  private:
    using char_type = typename Context::char_type;                  // только для описания

    variant<monostate, bool, char_type,
            int, unsigned int, long long int, unsigned long long int,
            float, double, long double,
            const char_type*, basic_string_view<char_type>,
            const void*, handle> value;                             // только для описания

    template<class T> explicit basic_format_arg(T&& v) noexcept;    // только для описания
    explicit basic_format_arg(float n) noexcept;                    // только для описания
    explicit basic_format_arg(double n) noexcept;                   // только для описания
    explicit basic_format_arg(long double n) noexcept;              // только для описания
    explicit basic_format_arg(const char_type* s);                  // только для описания

    template<class traits>
      explicit basic_format_arg(
        basic_string_view<char_type, traits> s) noexcept;           // только для описания

    template<class traits, class Allocator>
      explicit basic_format_arg(
        // только для описания
        const basic_string<char_type, traits, Allocator>& s) noexcept;

    explicit basic_format_arg(nullptr_t) noexcept;                  // только для описания

    template<class T>
      explicit basic_format_arg(T* p) noexcept;                     // только для описания

  public:
    basic_format_arg() noexcept;

    explicit operator bool() const noexcept;

    template<class Visitor>
      decltype(auto) visit(this basic_format_arg arg, Visitor&& vis);
    template<class R, class Visitor>
      R visit(this basic_format_arg arg, Visitor&& vis);
  };
}

Класс std::basic_format_arg::handle

namespace std {
  template<class Context>
  class basic_format_arg<Context>::handle {
    const void* ptr_;                                           // только для описания
    void (*format_)(basic_format_parse_context<char_type>&,
                    Context&, const void*);                     // только для описания

    template<class T> explicit handle(T&& val) noexcept;        // только для описания

    friend class basic_format_arg<Context>;                     // только для описания

  public:
    void format(basic_format_parse_context<char_type>&, Context& ctx) const;
  };
}

Шаблонный класс __format_arg_store

namespace std {
  template<class Context, class... Args>
  class __format_arg_store {                                    // только для описания
    array<basic_format_arg<Context>, sizeof...(Args)> args;     // только для описания
  };
}

Шаблонный класс std::basic_format_args

namespace std {
  template<class Context>
  class basic_format_args {
    size_t size_;                               // только для описания
    const basic_format_arg<Context>* data_;     // только для описания

  public:
    basic_format_args() noexcept;

    template<class... Args>
      basic_format_args(const __format_arg_store<Context, Args...>& store) noexcept;

    basic_format_arg<Context> get(size_t i) const noexcept;
  };
}

Средство форматирования кортежей

namespace std {
  template<class CharT, formattable<CharT>... Ts>
  struct formatter<__pair_or_tuple<Ts...>, CharT> {
  private:
    tuple<formatter<remove_cvref_t<Ts>, CharT>...> underlying_;     // только для описания
    basic_string_view<CharT> separator_ =                           // только для описания
      __STATICALLY_WIDEN<CharT>(", ");
    basic_string_view<CharT> opening_bracket_ =                     // только для описания
      __STATICALLY_WIDEN<CharT>("(");
    basic_string_view<CharT> closing_bracket_ =                     // только для описания
      __STATICALLY_WIDEN<CharT>(")");

  public:
    constexpr void set_separator(basic_string_view<CharT> sep);
    constexpr void set_brackets(basic_string_view<CharT> opening,
                                basic_string_view<CharT> closing);

    template<class ParseContext>
      constexpr typename ParseContext::iterator
        parse(ParseContext& ctx);

    template<class FormatContext>
      typename FormatContext::iterator
        format(/* смотрите описание */& elems, FormatContext& ctx) const;
  };
}

Класс std::format_error

namespace std {
  class format_error : public runtime_error {
  public:
    explicit format_error(const string& what_arg);
    explicit format_error(const char* what_arg);
  };
}