Standard library header <format> (C++20)
From cppreference.com
C++
Feature test macros (C++20)
Concepts library (C++20)
Metaprogramming library (C++11)
Ranges library (C++20)
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
Standard library headers
<compare> (C++20)
<contracts> (C++26)
<coroutine> (C++20)
<cstdint> (C++11)
<source_location> (C++20)
<stdfloat> (C++23)
<version> (C++20)
<concepts> (C++20)
<debugging> (C++26)
<stacktrace> (C++23)
<system_error> (C++11)
<memory_resource> (C++17)
<scoped_allocator> (C++11)
<type_traits> (C++11)
<ratio> (C++11)
<any> (C++17)
<bit> (C++20)
<charconv> (C++17)
<expected> (C++23)
<format> (C++20)
<optional> (C++17)
<stdbit.h> (C++26)
<tuple> (C++11)
<typeindex> (C++11)
<variant> (C++17)
<array> (C++11)
<flat_map> (C++23)
<flat_set> (C++23)
<forward_list> (C++11)
<hive> (C++26)
<mdspan> (C++23)
<span> (C++20)
<unordered_map> (C++11)
<unordered_set> (C++11)
<generator> (C++23)
<ranges> (C++20)
<cuchar> (C++11)
<string_view> (C++17)
<codecvt> (C++11/17/26*)
<regex> (C++11)
<cfenv> (C++11)
<linalg> (C++26)
<numbers> (C++20)
<random> (C++11)
<simd> (C++26)
<stdckdint.h> (C++26)
<chrono> (C++11)
<ccomplex> (C++11/17/20*)
<ciso646> (until C++20)
<cstdalign> (C++11/17/20*)
<cstdbool> (C++11/17/20*)
<ctgmath> (C++11/17/20*)
<cinttypes> (C++11)
<filesystem> (C++17)
<print> (C++23)
<spanstream> (C++23)
<strstream> (C++98/26*)
<syncstream> (C++20)
<atomic> (C++11)
<barrier> (C++20)
<condition_variable> (C++11)
<future> (C++11)
<hazard_pointer> (C++26)
<latch> (C++20)
<mutex> (C++11)
<rcu> (C++26)
<semaphore> (C++20)
<shared_mutex> (C++14)
<stdatomic.h> (C++23)
<stop_token> (C++20)
<thread> (C++11)
<execution> (C++17)
This header is part of the text processing library.
Contents
- 1 Concepts
- 2 Enumerations
- 3 Classes
- 4 Functions
- 5 Helpers
- 6 Synopsis
- 6.1 Class template std::basic_format_string
- 6.2 Concept std::formattable
- 6.3 Class template std::basic_format_parse_context
- 6.4 Class template std::basic_format_context
- 6.5 Variable template std::format_kind
- 6.6 Class template std::range_formatter
- 6.7 Class template __range_default_formatter
- 6.8 Specialization of __range_default_formatter for maps
- 6.9 Specialization of __range_default_formatter for sets
- 6.10 Specialization of __range_default_formatter for strings
- 6.11 Class template std::basic_format_arg
- 6.12 Class std::basic_format_arg::handle
- 6.13 Class template __format_arg_store
- 6.14 Class template std::basic_format_args
- 6.15 Tuple formatter
- 6.16 Class std::format_error
Concepts
(C++23)
parse
and format
(concept) [edit]
Enumerations
Classes
(C++23)
(class template) [edit]
(C++20)(C++20)(C++20)
(class template) [edit]
(C++20)
(class template) [edit]
(C++20)(C++20)(C++20)
(class template) [edit]
(C++20)(C++20)(C++20)
(class template) [edit]
Formatter specializations
Functions
(C++20)
(function template) [edit]
(C++20)
(function template) [edit]
(C++20)
(function template) [edit]
(C++26)
(function) [edit]
(C++20)
(function) [edit]
(C++20)
(function template) [edit]
(C++20) (deprecated in C++26)
(function template) [edit]
(C++20)(C++20)
format_args
(function template) [edit]
Helpers
[edit] Synopsis
namespace std { // class template basic_format_context template<class Out, class CharT> class basic_format_context; using format_context = basic_format_context</* unspecified */, char>; using wformat_context = basic_format_context</* unspecified */, wchar_t>; // class template 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>; // class template basic_format_string template<class CharT, class... Args> struct basic_format_string; template<class CharT> struct /*runtime-format-string*/ { // exposition-only private: basic_string_view<CharT> /*str*/; // exposition-only public: /*runtime-format-string*/(basic_string_view<CharT> s) noexcept : /*str*/(s) { } /*runtime-format-string*/(const /*runtime-format-string*/&) = delete; /*runtime-format-string*/& operator=(const /*runtime-format-string*/&) = delete; }; /*runtime-format-string*/<char> runtime_format(string_view fmt) noexcept { return fmt; } /*runtime-format-string*/<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>...>; // formatting functions 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); // formatter template<class T, class CharT = char> struct formatter; // formatter locking template<class T> constexpr bool enable_nonlocking_formatter_optimization = false; // concept formattable template<class T, class CharT> concept formattable = /* see description */; 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>; // class template 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>; // formatting of ranges // variable template format_kind enum class range_format { disabled, map, set, sequence, string, debug_string }; template<class R> constexpr /* unspecified */ format_kind = /* unspecified */; template<ranges::input_range R> requires same_as<R, remove_cvref_t<R>> constexpr range_format format_kind<R> = /* see description */; // class template range_formatter template<class T, class CharT = char> requires same_as<remove_cvref_t<T>, T> && formattable<T, CharT> class range_formatter; // class template range-default-formatter template<range_format K, ranges::input_range R, class CharT> struct /*range-default-formatter*/; // exposition-only // specializations for maps, sets, and strings 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> {}; template<ranges::input_range R> requires(format_kind<R> != range_format::disabled) constexpr bool enable_nonlocking_formatter_optimization<R> = false; // arguments // class template basic_format_arg template<class Context> class basic_format_arg; // class template 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; }
[edit] Class template std::basic_format_string
namespace std { template<class CharT, class... Args> struct basic_format_string { private: basic_string_view<CharT> /*str*/; // exposition-only 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*/; } }; }
This section is incomplete
Reason: create page:
Reason: create page:
concept formattable
[edit] Concept 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>>; };
[edit] Class template 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_; // exposition-only iterator end_; // exposition-only enum indexing { unknown, manual, automatic }; // exposition-only indexing indexing_; // exposition-only size_t next_arg_id_; // exposition-only size_t num_args_; // exposition-only 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; }; }
[edit] Class template std::basic_format_context
namespace std { template<class Out, class CharT> class basic_format_context { basic_format_args<basic_format_context> args_; // exposition-only Out out_; // exposition-only 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); }; }
[edit] Variable template std::format_kind
template<ranges::input_range R> requires same_as<R, remove_cvref_t<R>> constexpr range_format format_kind<R> = /* see description */;
[edit] Class template 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_*/; // exposition-only basic_string_view<CharT> /*separator_*/ = /*STATICALLY-WIDEN*/<CharT>(", "); // exposition-only basic_string_view<CharT> /*opening-bracket_*/ = /*STATICALLY-WIDEN*/<CharT>("["); // exposition-only basic_string_view<CharT> /*closing-bracket_*/ = /*STATICALLY-WIDEN*/<CharT>("]"); // exposition-only 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; }; }
[edit] Class template __range_default_formatter
namespace std { template<ranges::input_range R, class CharT> struct /*range-default-formatter*/<range_format::sequence, R, CharT> { // exposition-only private: using /*maybe-const-r*/ = /*fmt-maybe-const*/<R, CharT>; // exposition-only range_formatter<remove_cvref_t<ranges::range_reference_t </*maybe-const-r*/>>, CharT> /*underlying_*/; // exposition-only 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; }; }
[edit] Specialization of __range_default_formatter for 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>; // exposition-only using /*element-type*/ = // exposition-only remove_cvref_t<ranges::range_reference_t </*maybe-const-map*/>>; range_formatter</*element-type*/, CharT> /*underlying_*/; // exposition-only 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; }; }
[edit] Specialization of __range_default_formatter for sets
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>; // exposition-only range_formatter<remove_cvref_t<ranges::range_reference_t </*maybe-const-set*/>>, CharT> /*underlying_*/; // exposition-only 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; }; }
[edit] Specialization of __range_default_formatter for strings
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_*/; // exposition-only public: template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx); template<class FormatContext> typename FormatContext::iterator format(/* see description */ &str, FormatContext& ctx) const; }; }
[edit] Class template std::basic_format_arg
namespace std { template<class Context> class basic_format_arg { public: class handle; private: using char_type = typename Context::char_type; // exposition-only 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; // exposition-only template<class T> explicit basic_format_arg(T& v) noexcept; // exposition-only 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); }; }
[edit] Class std::basic_format_arg::handle
namespace std { template<class Context> class basic_format_arg<Context>::handle { const void* ptr_; // exposition-only void (*format_)(basic_format_parse_context<char_type>&, Context&, const void*); // exposition-only template<class T> explicit handle(T& val) noexcept; // exposition-only public: void format(basic_format_parse_context<char_type>&, Context& ctx) const; }; }
[edit] Class template __format_arg_store
namespace std { template<class Context, class... Args> class /*format-arg-store*/ { // exposition-only array<basic_format_arg<Context>, sizeof...(Args)> /*args*/; // exposition-only }; }
[edit] Class template std::basic_format_args
namespace std { template<class Context> class basic_format_args { size_t size_; // exposition-only const basic_format_arg<Context>* data_; // exposition-only 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>; }
[edit] Tuple formatter
namespace std { template<class CharT, formattable<CharT>... Ts> struct formatter</*pair-or-tuple*/<Ts...>, CharT> { private: tuple<formatter<remove_cvref_t<Ts>, CharT>...> /*underlying_*/; // exposition-only basic_string_view<CharT> /*separator_*/ = /*STATICALLY-WIDEN*/<CharT>(", "); // exposition-only basic_string_view<CharT> /*opening-bracket_*/ = /*STATICALLY-WIDEN*/<CharT>("("); // exposition-only basic_string_view<CharT> /*closing-bracket_*/ = /*STATICALLY-WIDEN*/<CharT>(")"); // exposition-only 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(/* see description */ &elems, FormatContext& ctx) const; }; template<class... Ts> constexpr bool enable_nonlocking_formatter_optimization</*pair-or-tuple*/<Ts...>> = (enable_nonlocking_formatter_optimization<Ts> && ...); }
[edit] Class 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); }; }