Namespaces
Variants
Views
Actions

Standard library header <format>

From cppreference.com
< cpp‎ | header
 
 
 

This header is part of the format library.

Contents

Classes

(C++20)
class template that defines formatting rules for a given type
(class template) [edit]
formatting string parser state
(class template) [edit]
formatting state, including all formatting arguments and the output iterator
(class template) [edit]
class 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]
exception type thrown on formatting errors
(class) [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]
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]
(C++20)
non-template variant of std::format using type-erased argument representation
(function) [edit]
non-template variant of std::format_to using type-erased argument representation
(function) [edit]
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]

[edit] Synopsis

namespace std {
  // formatting functions
  template<class... Args>
    string format(string_view fmt, const Args&... args);
  template<class... Args>
    wstring format(wstring_view fmt, const Args&... args);
  template<class... Args>
    string format(const locale& loc, string_view fmt, const Args&... args);
  template<class... Args>
    wstring format(const locale& loc, wstring_view fmt, const 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, string_view fmt, const Args&... args);
  template<class Out, class... Args>
    Out format_to(Out out, wstring_view fmt, const Args&... args);
  template<class Out, class... Args>
    Out format_to(Out out, const locale& loc, string_view fmt, const Args&... args);
  template<class Out, class... Args>
    Out format_to(Out out, const locale& loc, wstring_view fmt, const Args&... args);
 
  template<class Out>
    Out vformat_to(Out out, string_view fmt, format_args_t<Out, char> args);
  template<class Out>
    Out vformat_to(Out out, wstring_view fmt, format_args_t<Out, wchar_t> args);
  template<class Out>
    Out vformat_to(Out out, const locale& loc, string_view fmt,
                   format_args_t<Out, char> args);
  template<class Out>
    Out vformat_to(Out out, const locale& loc, wstring_view fmt,
                   format_args_t<Out, wchar_t> 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,
                                        string_view fmt, const Args&... args);
  template<class Out, class... Args>
    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                        wstring_view fmt, const 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, string_view fmt,
                                        const 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, wstring_view fmt,
                                        const Args&... args);
 
  template<class... Args>
    size_t formatted_size(string_view fmt, const Args&... args);
  template<class... Args>
    size_t formatted_size(wstring_view fmt, const Args&... args);
  template<class... Args>
    size_t formatted_size(const locale& loc, string_view fmt, const Args&... args);
  template<class... Args>
    size_t formatted_size(const locale& loc, wstring_view fmt, const Args&... args);
 
  // formatter
  template<class T, class charT = char> struct formatter;
 
  // 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>;
 
  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>;
 
  // arguments
  // class template basic_format_arg
  template<class Context> class basic_format_arg;
 
  template<class Visitor, class Context>
    /* see description */ visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
 
  // class template format-arg-store
  template<class Context, class... Args> struct /*format-arg-store*/;  // exposition only
 
  template<class Context = format_context, class... Args>
    /*format-arg-store*/<Context, Args...>
      make_format_args(const Args&... args);
  template<class... Args>
    /*format-arg-store*/<wformat_context, Args...>
      make_wformat_args(const Args&... args);
 
  // 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>;
 
  template<class Out, class charT>
    using format_args_t = basic_format_args<basic_format_context<Out, charT>>;
 
  // class format_error
  class format_error;
}

[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,
                                                  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);
  };
}

[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
 
  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;
    std::locale locale();
 
    iterator out();
    void advance_to(iterator it);
  };
}

[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(const T& v) noexcept;  // exposition only
    explicit basic_format_arg(float n) noexcept;                       // exposition only
    explicit basic_format_arg(double n) noexcept;                      // exposition only
    explicit basic_format_arg(long double n) noexcept;                 // exposition only
    explicit basic_format_arg(const char_type* s);                     // exposition only
 
    template<class traits>
      explicit basic_format_arg(
        basic_string_view<char_type, traits> s) noexcept;              // exposition only
 
    template<class traits, class Allocator>
      explicit basic_format_arg(
        const basic_string<char_type, traits, Allocator>& s) noexcept; // exposition only
 
    explicit basic_format_arg(nullptr_t) noexcept;                     // exposition only
 
    template<class T>
      explicit basic_format_arg(const T* p) noexcept;                  // exposition only
 
    template<class Visitor, class Ctx>
      friend auto visit_format_arg(Visitor&& vis,
                                   basic_format_arg<Ctx> arg);         // exposition only
 
    template<class Ctx, class... Args>
      friend /*format-arg-store*/<Ctx, Args...>
        make_format_args(const Args&... args);                         // exposition only
 
  public:
    basic_format_arg() noexcept;
 
    explicit operator bool() const noexcept;
  };
}

[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(const T& val) noexcept;   // exposition only
 
    friend class basic_format_arg<Context>;                     // 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>
  struct /*format-arg-store*/ {      // exposition only
    array<basic_format_arg<Context>, sizeof...(Args)> args;
  };
}

[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:
    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;
  };
}

[edit] Class 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);
  };
}