# 标准库头文件 <format>

< cpp‎ | header

此头文件是格式化库的一部分。

### 类
formatter (C++20) | 定义给定类型的格式化规则的类模板 (类模板)
basic_format_parse_context format_parse_context wformat_parse_context (C++20)(C++20)(C++20) | 格式化字符串分析器状态 (类模板)
basic_format_context format_context wformat_context (C++20)(C++20)(C++20) | 格式化状态，包括所有格式化参数和输出迭代器 (类模板)
basic_format_arg (C++20) | 提供对用户定义格式化器的格式化参数的访问的类模板 (类模板)
basic_format_args format_args wformat_args (C++20)(C++20)(C++20) | 提供对所有格式化参数的访问的类 (类模板)
format_error (C++20) | 格式化错误时抛出的异常类型 (类)
### 函数
format (C++20) | 在新 string 中存储参数的格式化表示 (函数模板)
format_to (C++20) | 通过输出迭代器写其参数的格式化表示 (函数模板)
format_to_n (C++20) | 通过输出迭代器写其参数的格式化表示，不超出指定的大小 (函数模板)
formatted_size (C++20) | 确定存储其参数的格式化表示所需的字符数 (函数模板)
vformat (C++20) | std::format 的使用类型擦除的参数表示的非模板变体 (函数)
vformat_to (C++20) | std::format_to 的使用类型擦除的参数表示的非模板变体 (函数模板)
visit_format_arg (C++20) | 用户定义格式化器的参数观览接口 (函数模板)
make_format_args make_wformat_args (C++20)(C++20) | 创建引用所有格式化参数的类型擦除对象，可转换到 format_args (函数模板)

### 概要

    namespace std {
      // 格式化函数
      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<type_identity_t<Out>, char> args);
      template<class Out>
        Out vformat_to(Out out, wstring_view fmt,
                       format_args_t<type_identity_t<Out>, wchar_t> args);
      template<class Out>
        Out vformat_to(Out out, const locale& loc, string_view fmt,
                       format_args_t<type_identity_t<Out>, char> args);
      template<class Out>
        Out vformat_to(Out out, const locale& loc, wstring_view fmt,
                       format_args_t<type_identity_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);

      // 格式化器
      template<class T, class charT = char> struct formatter;

      // 类模板 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>;

      // 实参
      // 类模板 basic_format_arg
      template<class Context> class basic_format_arg;

      template<class Visitor, class Context>
        /* 见描述 */ visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);

      // class template format-arg-store
      template<class Context, class... Args> struct /*format-arg-store*/;  // 仅为阐释

      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);

      // 类模板 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>>;

      // 类 format_error
      class format_error;
    }

#### 类模板 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);
      };
    }

#### 类模板 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) const;
        std::locale locale();

        iterator out();
        void advance_to(iterator it);
      };
    }

#### 类模板 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(const T* p) noexcept;                  // 仅为阐释

      public:
        basic_format_arg() noexcept;

        explicit operator bool() const noexcept;
      };
    }

#### 类 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>
      struct /*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;
      };
    }

#### 类 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);
      };
    }