Standard library header <format> (C++20)

From cppreference.net

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

Содержание

Концепты

(C++23)

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


          parse


          format

(концепт)

Перечисления

range_format

(C++23)

определяет, как должен форматироваться диапазон
(перечисление)

Классы

formatter

(C++20)

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

range_formatter

(C++23)

шаблон класса, который помогает реализовать std::formatter специализации для типов диапазонов
(шаблон класса)

basic_format_parse_context format_parse_context wformat_parse_context

(C++20) (C++20) (C++20)

состояние парсера форматирующей строки
(шаблон класса)

basic_format_context format_context wformat_context

(C++20) (C++20) (C++20)

состояние форматирования, включая все аргументы форматирования и выходной итератор
(шаблон класса)

basic_format_arg

(C++20)

шаблон класса, предоставляющий доступ к аргументу форматирования для пользовательских форматтеров
(class template)

basic_format_args format_args wformat_args

(C++20) (C++20) (C++20)

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

basic_format_string format_string wformat_string

(C++20) (C++20) (C++20)

шаблон класса, выполняющий проверки строки форматирования во время компиляции при создании объекта
(шаблон класса)

format_error

(C++20)

тип исключения, выбрасываемого при ошибках форматирования
(класс)

Специализации Formatter

std::formatter < pair-or-tuple >

(C++23)

поддержка форматирования для


          pair


          tuple

(специализация шаблона класса)

std::formatter < range >

(C++23)

поддержка форматирования для диапазонов
(специализация шаблона класса)

Функции

format

(C++20)

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

format_to

(C++20)

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

format_to_n

(C++20)

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

formatted_size

(C++20)

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

runtime_format

(C++26)

создает строки форматирования времени выполнения, непосредственно используемые в пользовательских функциях форматирования
(функция)

vformat

(C++20)

нетемплейтный вариант std::format с использованием стирания типов для представления аргументов
(функция)

vformat_to

(C++20)

нетемплейтный вариант std::format_to с использованием type-erased представления аргументов
(шаблон функции)

visit_format_arg

(C++20) (deprecated in C++26)

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

make_format_args make_wformat_args

(C++20) (C++20)

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


          format_args

(шаблон функции)

Вспомогательные средства

format_kind

(C++23)

выбирает подходящий std::range_format для диапазона
(шаблон переменной)

enable_nonlocking_formatter_optimization

(C++23)

указывает, что тип аргумента может быть эффективно выведен
(шаблон переменной)

Синопсис

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 CharT> struct /*строка формата времени выполнения*/
  {                                   // exposition-only
  private:
    basic_string_view<CharT> /*строка*/; // exposition-only
  public:
    /*строка-формата-времени-выполнения*/(basic_string_view<CharT> s) noexcept
      : /*строка*/(s)
    {
    }
    /*строка-формата-времени-выполнения*/(const /*строка-формата-времени-выполнения*/&) = delete;
    /*строка-формата-времени-выполнения*/& operator=(const /*строка-формата-времени-выполнения*/&) = delete;
  };
  /*строка-формата-времени-выполнения*/<char> runtime_format(string_view fmt) noexcept { return fmt; }
  /*строка-формата-времени-выполнения*/<wchar_t> runtime_format(wstring_view fmt) noexcept
  {
    return fmt;
  }
  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> constexpr bool enable_nonlocking_formatter_optimization = false;
  // концепция formattable
  template<class T, class CharT>
  concept formattable = /* см. описание */;
  template<class R, class CharT>
  concept /*const-formattable-range*/ = // exposition-only
    ranges::input_range<const R> &&
    formattable<ranges::range_reference_t<const R>, CharT>;
  template<class R, class CharT>
  using /*fmt-maybe-const*/ =           // exposition-only
    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>;
  // форматирование диапазонов
  // variable template 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 /*форматер диапазона по умолчанию*/; // exposition-only
  // специализации для map, set и string
  template<ranges::input_range R, class CharT>
    requires(format_kind<R> != range_format::отключено) &&
            formattable<ranges::range_reference_t<R>, CharT>
  struct formatter<R, CharT> : /*форматер диапазона по умолчанию*/<format_kind<R>, R, CharT>
  {};
  template<ranges::input_range R>
    requires(format_kind<R> != range_format::отключено)
  constexpr bool enable_nonlocking_formatter_optimization<R> = false;
  // аргументы
  // шаблон класса basic_format_arg
  template<class Context> class basic_format_arg;
  // шаблон класса format-arg-store
  template<class Context, class... Args> class /*format-arg-store*/; // exposition-only
  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);
  // class 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);
    basic_format_string(/*runtime-format-string*/<CharT> s) noexcept
      : str(s./*str*/)
    {
    }
    constexpr basic_string_view<CharT> get() const noexcept { return /*str*/; }
  };
}

Этот раздел не завершён
Причина: создать страницу: concept formattable

Концепт `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>>;
    };

**Примечание:** Весь код C++ внутри тегов `

` и `` был сохранен без изменений, как и требовалось. HTML-теги и атрибуты также остались нетронутыми.

Шаблон класса 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) 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_;                                      // только для демонстрации
    basic_format_context(const basic_format_context&) = delete;
    basic_format_context& operator=(const basic_format_context&) = delete;
  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) noexcept;
    constexpr void set_brackets(basic_string_view<CharT> opening,
                                basic_string_view<CharT> closing) noexcept;
    constexpr formatter<T, CharT>& underlying() noexcept { return /*underlying_*/; }
    constexpr const formatter<T, CharT>& underlying() const noexcept
    {
      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) noexcept;
    constexpr void set_brackets(basic_string_view<CharT> opening,
                                basic_string_view<CharT> closing) noexcept;
    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 для отображений (maps)

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 /*форматтер по умолчанию для диапазонов*/<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; // только для демонстрации
  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; // только для демонстрации
  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:
    template<class... Args>
    basic_format_args(const /*format-arg-store*/<Context, Args...>& store) noexcept;
    basic_format_arg<Context> get(size_t i) const noexcept;
  };
  template<class Context, class... Args>
  basic_format_args(/*format-arg-store*/<Context, Args...>) -> basic_format_args<Context>;
}

Форматер кортежей

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) noexcept;
    constexpr void set_brackets(basic_string_view<CharT> opening,
                                basic_string_view<CharT> closing) noexcept;
    template<class ParseContext>
    constexpr typename ParseContext::iterator parse(ParseContext& ctx);
    template<class FormatContext>
    typename FormatContext::iterator format(/* см. описание */ &elems,
                                            FormatContext& ctx) const;
  };
  template<class... Ts>
  constexpr bool enable_nonlocking_formatter_optimization</*pair-or-tuple*/<Ts...>> =
    (enable_nonlocking_formatter_optimization<Ts> && ...);
}

Класс std::format_error

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

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Diagnostics library
Memory management library
Metaprogramming library (C++11)
General utilities library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Strings library
Text processing library
Numerics library
Date and time library
Input/output library
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
Technical specifications
Symbols index
External libraries

cppreference.net

Namespaces

Variants

Standard library header <format> (C++20)

Содержание

Концепты

Перечисления

Классы

Специализации Formatter

Функции

Вспомогательные средства

Синопсис

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

Концепт `std::formattable`

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

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

Шаблон переменной std::format_kind

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

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

Специализация __range_default_formatter для отображений (maps)

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

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

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

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

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

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

Форматер кортежей

Класс std::format_error

cppreference.net

Namespaces

Variants

Standard library header <format> (C++20)

Содержание

Концепты

Перечисления

Классы

Специализации Formatter

Функции

Вспомогательные средства

Синопсис

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

Концепт std::formattable

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

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

Шаблон переменной std::format_kind

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

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

Специализация __range_default_formatter для отображений (maps)

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

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

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

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

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

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

Форматер кортежей

Класс std::format_error

Концепт `std::formattable`