bslfmt_format_args

Detailed Description

Provide a container of arguments for use by bsl::format.

Outline

• Purpose
• Classes
• Canonical Header
• Description
  • Usage
    • Example: 1 Non-default construction and value verification

Purpose

Provide a container of arguments for use by bsl::format

Classes

• bslfmt::basic_format_args: standard-compliant argument store

Canonical Header

bsl_format.h

Description

This component provides an implementation of the C++20 Standard Library's std::basic_format_args, providing access to an array of basic_format_arg types. It also provides implementations of the standard library free functions make_format_args and make_wformat_args .

As also specified by the standard, the provided free functions return an exposition-only type that holds references to the arguments passed in. A basic_format_args constructed from an instance of this type holds a reference to it. This means it is the users responsibility to ensure that the lifetime of the returned type does not end before the lifetime of the constructed basic_format_args type. This means that, for example, the following code results in Undefined Behavior, in both the standard library and the bslfmt versions:

    int value = 5;
    format_args args = make_format_args(value);
    // args now holds a reference to a temporary whose lifetime has ended.
    do_something_with(args);

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

Usage

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

Example: 1 Non-default construction and value verification

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 want to construct a int-containing basic_format_args and verify that it contains that int. Note the use of a function to workaround the lifetime issues specified above. Format_ArgsStore passed to the basic_format_args constructor must outlive the constructed object. bslfmt::make_format_args returns temporary Format_ArgsStore object so to avoid its destruction we have to do all the useful work within the execution of one function.

  struct UsageExampleVisitor {
 
    void operator()(bsl::monostate) const
    {
      assert(false); // contains no value
    }
 
    template <class t_TYPE>
    typename bsl::enable_if<bsl::is_integral<t_TYPE>::value>::type
                                          operator()(t_TYPE x) const
    {
      assert(static_cast<t_TYPE>(99) == x);
    }
 
    template <class t_TYPE>
    typename bsl::enable_if<!bsl::is_integral<t_TYPE>::value>::type
                                          operator()(t_TYPE) const
    {
      assert(false); // contains non-integral value
    }
  };
 
  struct UsageExampleChecker {
    static void checkValue(bslfmt::format_args args)
    {
      UsageExampleVisitor visitor;
      visit_format_arg(visitor, args.get(0));
      asssert(args.get(1));
    }
  };
 
  int value = 99;
  UsageExampleChecker::checkValue(bslfmt::make_format_args(value));