Заголовочный файл стандартной библиотеки <format> (C++20)
Материал из cppreference.com
Этот заголовок является частью библиотеки форматирования.
Концепты | |
(C++23) | указывает, что тип является форматируемым, то есть он специализирует std::formatter и предоставляет функции-элементы parse и format(концепт) |
Перечисления | |
(C++23) | указывает, как должен быть отформатирован диапазон (перечисление) |
Клыссы | |
(C++20) | шаблонный класс, который определяет правила форматирования для данного типа (шаблон класса) |
(C++23) | шаблонный класс, который помогает реализовать специализации std::formatter для диапазонных типов (шаблон класса) |
(C++20)(C++20)(C++20) | состояние парсера строки форматирования (шаблон класса) |
(C++20)(C++20)(C++20) | состояние форматирования, включая все аргументы форматирования и итератор вывода (шаблон класса) |
(C++20) | шаблонный класс, который предоставляет доступ к аргументу форматирования для определяемых пользователем средств форматирования (шаблон класса) |
(C++20)(C++20)(C++20) | класс, который обеспечивает доступ ко всем аргументам форматирования (шаблон класса) |
(C++20)(C++20)(C++20) | шаблон класса, который выполняет проверку строки формата во время компиляции во время построения (шаблон класса) |
(C++20) | тип исключения, возникающий при ошибках форматирования (класс) |
Функции | |
(C++20) | сохраняет форматированное представление аргументов в новой строке (шаблон функции) |
(C++20) | записывает форматированное представление своих аргументов через итератор вывода (шаблон функции) |
(C++20) | записывает форматированное представление своих аргументов через итератор вывода, не превышая заданного размера (шаблон функции) |
(C++20) | определяет количество символов, необходимых для хранения форматированного представления его аргументов (шаблон функции) |
(C++20) | нешаблонный вариант std::format с использованием представления аргументов с удалением типа (функция) |
(C++20) | нешаблонный вариант std::format_to с использованием представления аргументов с удалением типа (шаблон функции) |
(C++20)(устарело в C++26) | интерфейс посещения аргументов для определяемых пользователем средств форматирования (шаблон функции) |
(C++20)(C++20) | создаёт объект с удалением типа, ссылающийся на все аргументы форматирования, конвертируемый в format_args (шаблон функции) |
Помощники | |
(C++23) | выбирает подходящий std::range_format для диапазона (шаблонная переменная) |
[править]Резюме
namespace std {// шаблонный класс basic_format_contexttemplate<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_argstemplate<class Context>class basic_format_args;using format_args = basic_format_args<format_context>;using wformat_args = basic_format_args<wformat_context>; // шаблонный класс basic_format_stringtemplate<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_contexttemplate<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_kindenumclass 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_formattertemplate<class T, class CharT =char> requires same_as<remove_cvref_t<T>, T>&& formattable<T, CharT>class range_formatter; // шаблонный класс __range_default_formattertemplate<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_argtemplate<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_storetemplate<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_errorclass 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()constnoexcept{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:constexprexplicit 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()constnoexcept;constexpr const_iterator end()constnoexcept;constexprvoid advance_to(const_iterator it); constexpr size_t next_arg_id();constexprvoid check_arg_id(size_t id); template<class... Ts>constexprvoid check_dynamic_spec(size_t id)noexcept;constexprvoid check_dynamic_spec_integral(size_t id)noexcept;constexprvoid 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)constnoexcept;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:constexprvoid set_separator(basic_string_view<CharT> sep);constexprvoid set_brackets(basic_string_view<CharT> opening, basic_string_view<CharT> closing);constexpr formatter<T, CharT>& underlying(){return underlying_;}constexprconst formatter<T, CharT>& underlying()const{return underlying_;} template<class ParseContext>constexprtypename 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:constexprvoid set_separator(basic_string_view<CharT> sep);constexprvoid set_brackets(basic_string_view<CharT> opening, basic_string_view<CharT> closing); template<class ParseContext>constexprtypename 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>constexprtypename 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>constexprtypename 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>constexprtypename 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, unsignedint, longlongint, unsignedlonglongint, float, double, longdouble, const char_type*, basic_string_view<char_type>, constvoid*, 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(longdouble 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()constnoexcept; 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{constvoid* ptr_;// только для описанияvoid(*format_)(basic_format_parse_context<char_type>&, Context&, constvoid*);// только для описания template<class T>explicit handle(T&& val)noexcept;// только для описания friendclass 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)constnoexcept;};}
[править]Средство форматирования кортежей
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:constexprvoid set_separator(basic_string_view<CharT> sep);constexprvoid set_brackets(basic_string_view<CharT> opening, basic_string_view<CharT> closing); template<class ParseContext>constexprtypename 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(constchar* what_arg);};}
