Utilities library
Language support
Type support (basic types, RTTI)
Library feature-test macros (C++20)
Dynamic memory management
Program utilities
Coroutine support (C++20)
Variadic functions
Debugging support
Three-way comparison
General utilities
Date and time
Function objects
Formatting library (C++20)
Relational operators (deprecated in C++20)
Integer comparison functions
Swap and type operations
Common vocabulary types
Elementary string conversions

Defined in header <format>
template< class Context >
class basic_format_arg<Context>::handle;
(since C++20)

A type-erased wrapper that allows formatting an object of a user-defined type.

handle objects are typically created by std::make_format_args and accessed through std::visit_format_arg or the visit member functions of std::basic_format_arg(since C++26).


[edit] Data members

A typical implementation of handle is TriviallyCopyable and only stores two non-static data members:

  • a const void* pointer to the object to be formatted, and
  • a void (*)(std::basic_format_parse_context<Context::char_type>&, Context&, const void*) function pointer to the function performing needed operations in the format member function (see below).

[edit] Member functions

formats the referenced object with the given contexts
(public member function)


void format( std::basic_format_parse_context<Context::char_type>& parse_ctx,
             Context& format_ctx ) const;
(since C++20)


  • T be the type of the formatting argument,
  • TD be std::remove_const_t<T>,
  • TQ be const TD if const TD satisfies __formattable_with<Context> or TD otherwise, and
  • ref be a reference to the formatting argument.

Equivalent to: typename Context::template formatter_type<TD> f;
format_ctx.advance_to(f.format(const_cast<TQ&>(static_cast<const TD&>(ref)), format_ctx));

[edit] Notes

A handle has reference semantics for the formatted argument and does not extend its lifetime. It is the programmer's responsibility to ensure that the argument outlives the handle. Usually, a handle is only used within formatting functions.

[edit] See also

class template that provides access to a formatting argument for user-defined formatters
(class template) [edit]
creates a type-erased object referencing all formatting arguments, convertible to format_args
(function template) [edit]