bslfmt_format_context

Detailed Description

Provides access to formatting state.

Outline

• Purpose
• Classes
• Canonical Header
• Description
  • Usage
    • Example: 1 Testing a user defined formatter's format method.

Purpose

Provides access to formatting state.

Classes

• bslfmt::basic_format_context: standard-compliant output context

Canonical Header

bsl_format.h

Description

This component provides an implementation of the C++20 Standard Library's std::basic_format_context, which provides access to formatting state consisting of the formatting arguments and the output iterator.

This type is designed to be constructed from within bslfmt::format and cannot be constructed directly from user code.

As this type contains a basic_format_args type therefore all of the warnings around lifetime documented in bslfmt_formatargs.h also apply here.

This header is not intended to be included directly. Please include <bsl_format.h> to be able to use bsl::basic_format_context.

Usage

In this section we show the intended use of this component.

Example: 1 Testing a user defined formatter's format method.

We do not expect most users of bsl::format to interact with this type directly and instead use bsl::format or bsl::vformat. In addition, there are only a very limited number of public methods so this example is necessarily unrealistic.

Suppose we have a user-defined formatter and want to test its format method:

 struct MyCharFormatter {
     template <class t_FORMAT_CONTEXT>
     typename t_FORMAT_CONTEXT::iterator format(
         char              v,
         t_FORMAT_CONTEXT& fc) const
     {
         typename t_FORMAT_CONTEXT::iterator out = fc.out();
 
         *out++ = v;
 
         return out;
     }
 };

We can then write a test function. Note that it is not possible for users to construct a context directly, so we are forced to abuse the internal-use-only types Format_ContextOutputIteratorRef and Format_ContextFactory in order to write this usage example.

 struct MyCharFormatterTestVisitor {
     char value;
 
     void operator()(char v) { value = v; }
 
     template <class t_TYPE>
     void operator()(const t_TYPE &) const
     {
         assert(false);  // Wrong Type
     }
 };
 
 void testFormatter(bslfmt::format_args args)
 {
     MyCharFormatter                        f;
     bsl::string                            result;
     bsl::back_insert_iterator<bsl::string> backiter(result);
     bslfmt::Format_ContextOutputIteratorImpl<
         char, bsl::back_insert_iterator<bsl::string> >
                                            iter(backiter);
     bslfmt::format_context fc =
         bslfmt::Format_ContextFactory::construct(
                      bslfmt::Format_ContextOutputIteratorRef<char>(&iter),
                      args);
     MyCharFormatterTestVisitor visitor;
     bslfmt::visit_format_arg(visitor, fc.arg(0));
     f.format(visitor.value, fc);
     assert(result.size() == 1);
     assert(result.front() == `x`);
 }

Then we perform the test itself:

  char value = `x`;
  testFormatter(bslfmt::make_format_args(value));