Detailed Description

Provide a standard compliant format implementation.

Outline

Purpose
Classes
Canonical Header
Description
- User-provided formatters
- Usage
  - Example 1: Simple integer formatting

Purpose

Provide a standard compliant format implementation

Classes

bslfmt::format_to_n_result: result type for format_to_n.

Canonical Header

bsl_format.h

See also: ISO C++ Standard, <format>

Description

This component will provide, in the bslfmt namespace, compliant implementations of the following free functions exposed by the standard <format> header. These are available for C++03 and later.

format
format_to
format_to_n
formatted_size
vformat
vformat_to

Note 1: The overloads taking a locale parameter are not provided. Note 2: Compile-time format string checking is not performed.

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

User-provided formatters

User-provided formatters are supported by the BSL implementation, just as they are by the standard library implementation. However, in order for them to be compatible with both implementations, there are specific requirements, notably:

If you will define a formatter for your type T, do so in the same component header that defines T itself. This avoids issues due to users forgetting to include the header for the formatter.
Define bsl::formatter<T> - DO NOT define std::formatter<T> - Use template arguments for the format context and parse context parameters. This is essential as the parameter type passed in will depend upon underlying implementation.
The parse function should be constexpr in C++20, but this is not required (and may not be possible) for earlier C++ standards.

An example of a user defined formatter is as follows:

namespace bsl {
 
template <class t_CHAR> struct formatter<UserDefinedType, t_CHAR> {
    template <class t_PARSE_CONTEXT>
    BSLS_KEYWORD_CONSTEXPR_CPP20
    t_PARSE_CONTEXT::iterator parse(t_PARSE_CONTEXT& pc)
    {
        // implementation goes here
    }
 
    template <class t_FORMAT_CONTEXT>
    t_FORMAT_CONTEXT::iterator format(UserDefinedType   s,
                                      t_FORMAT_CONTEXT& ctx) const
    {
        // implementation goes here
    }
};
 
}  // close namespace bsl

Usage

This section illustrates the intended use of this component.

Example 1: Simple integer formatting

#include <bslfmt_format.h>
#include <bsl_iostring.h>
 
bsl::string doFormat(int value)
{
    bsl::string res = bslfmt::format("{}", value);
    return res;
}
 
int main()
{
    bsl::cout << doFormat(99) << bsl::endl;
    return 0;
}