Namespaces
Variants
Actions

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

From cppreference.com
< cpp‎ | header
 
 
Standard library headers
<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)
<hive> (C++26)
<inplace_vector> (C++26)   
<mdspan> (C++23)
<span> (C++20)
<generator> (C++23)
<ranges> (C++20)
 

This header is part of the text processing library.

(C++23)
specifies that a type is formattable, that is, it specializes std::formatter and provides member functions parse and format
(concept) [edit]

Enumerations

specifies how a range should be formatted
(enum) [edit]

Classes

(C++20)
defines formatting rules for a given type
(class template) [edit]
class template that helps implementing std::formatter specializations for range types
(class template) [edit]
formatting string parser state
(class template) [edit]
formatting state, including all formatting arguments and the output iterator
(class template) [edit]
class template that provides access to a formatting argument for user-defined formatters
(class template) [edit]
class that provides access to all formatting arguments
(class template) [edit]
class template that performs compile-time format string checks at construction time
(class template) [edit]
exception type thrown on formatting errors
(class) [edit]
Formatter specializations
formatting support for pair and tuple
(class template specialization) [edit]
formatting support for ranges
(class template specialization) [edit]

Functions

(C++20)
stores formatted representation of the arguments in a new string
(function template) [edit]
(C++20)
writes out formatted representation of its arguments through an output iterator
(function template) [edit]
(C++20)
writes out formatted representation of its arguments through an output iterator, not exceeding specified size
(function template) [edit]
determines the number of characters necessary to store the formatted representation of its arguments
(function template) [edit]
creates runtime format strings directly usable in user-oriented formatting functions
(function) [edit]
(C++20)
non-template variant of std::format using type-erased argument representation
(function) [edit]
(C++20)
non-template variant of std::format_to using type-erased argument representation
(function template) [edit]
(C++20) (deprecated in C++26)
argument visitation interface for user-defined formatters
(function template) [edit]
creates a type-erased object referencing all formatting arguments, convertible to format_args
(function template) [edit]

Helpers

(C++23)
selects a suited std::range_format for a range
(variable template)[edit]
indicates the argument type can be efficiently printed
(variable template)[edit]

[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: 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);
 };
}
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/header/format&oldid=179094"

AltStyle によって変換されたページ (->オリジナル) /