标准库标头 <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++23) |
pair 和 tuple 的格式化支持 (类模板特化) |
(C++23) |
范围的格式化支持 (类模板特化) |
函数 | |
(C++20) |
在新字符串中存储参数的格式化表示 (函数模板) |
(C++20) |
通过输出迭代器写入其实参的格式化表示 (函数模板) |
(C++20) |
通过输出迭代器写入其实参的格式化表示,不超出指定的大小 (函数模板) |
(C++20) |
确定存储其参数的格式化表示所需的字符数 (函数模板) |
(C++26) |
创建能直接用于面向用户的格式化函数的运行时格式串 (函数) |
(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_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; // 变量模板 enable_nonlocking_formatter_optimization 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 = // 仅用于阐述 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_; // 仅用于阐述 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); 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(const 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(const 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); }; }