Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/utility/format/basic format arg/handle"

From cppreference.com
(→‎Notes)
m (fix)
 
Line 9: Line 9:
 
A type-erased wrapper that allows formatting an object of a user-defined type.
 
A type-erased wrapper that allows formatting an object of a user-defined type.
  
−
{{tt|handle}} objects are typically created by {{lc|std::make_format_args}} and accessed through {{lc|std::visit_format_arg}}{{rev inl|since=c++26| or the {{tt|visit}} member functions of {{lc|std::basic_format_args}}}}.
+
{{tt|handle}} objects are typically created by {{lc|std::make_format_args}} and accessed through {{lc|std::visit_format_arg}}{{rev inl|since=c++26| or the {{tt|visit}} member functions of {{lc|std::}}}}.
  
 
===Data members===
 
===Data members===

Latest revision as of 07:32, 7 September 2023

 
C++
 
Text processing library
 
Formatting library
Standard format specification
Formatting functions
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
Format strings
(C++20)(C++20)(C++20)
(C++26)
Formatting concepts
(C++23)
Formatter
(C++20)
(C++23)
(C++23)
(C++23)
(C++23)
(C++20)(C++20)(C++20)
(C++20)(C++20)(C++20)
(C++23)
(C++23)
Formatting arguments
(C++20)
basic_format_arg::handle
(C++20)
(C++20)(C++20)(C++20)
(C++20) (deprecated in C++26)
(C++20)(C++20)
Format error
(C++20)
 
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).

Contents

[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

format
(C++20)
 formats the referenced object with the given contexts
(public member function)

std::basic_format_arg<Context>::handle::format

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

Let

  • 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;
parse_ctx.advance_to(f.parse(parse_ctx));
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

(C++20)
 class template that provides access to a formatting argument for user-defined formatters
(class template) [edit]
(C++20)(C++20)
 creates a type-erased object referencing all formatting arguments, convertible to format_args
(function template) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/utility/format/basic_format_arg/handle&oldid=158164"