bslfmt_formatterbase

Detailed Description

Provide a base template for formatter specializations.

Outline

• Purpose
• Classes
• Canonical Header
• Description
  • User-provided Formatters
  • Usage
    • Example 1: Creating Custom Formatter For User Type

Purpose

Provide a base template for formatter specializations.

Classes

• bsl::formatter: standard-compliant formatter base template

Canonical Header

bsl_format.h

Description

This component provides a base template of the C++20 Standard Library's formatter, which is a customization point for user defined types seeking to use the formatting library.

It also provides a mechanism, when the standard library <format> header is available, to forward those partial specializations to the std namespace to enable use of std::format as well as bsl::format.

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

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:

• The formatter for a user defined type T, should be declared in the same component header in which this type is declared to avoid issues due to users forgetting to include the header for the formatter.
• Formatter must be defined in the namespace bsl, not std.
• Template arguments must be used for the format and parse context parameters. This is essential as the parameter type passed in might 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.

Usage

This section illustrates intended use of this component.

Example 1: Creating Custom Formatter For User Type

Suppose we have a custom type representing a date. And we want to output it to the stream in different formats depending on the circumstances using bsl::format function. The following example shows how this can be done.

First, we define our Date class:

 /// This class implements a complex-constrained, value-semantic type for
 /// representing dates.  Each object of this class *always* represents a
 /// *valid* date value in the range `[0001JAN01 .. 9999DEC31]` inclusive.
 class Date {
   private:
     // DATA
     int d_year;   // year
     int d_month;  // month
     int d_day;    // day
 
   public:
     // CREATORS
 
     /// Create an object having the value represented by the specified
     /// `year`, `month`, and `day`.
     Date(int year, int month, int day);
 
     // ACCESSORS
 
     /// Return the year of this date.
     int year() const;
 
     /// Return the month of this date.
     int month() const;
 
     /// Return the day of this date.
     int day() const;
 };

Now, we define formatter specialization for the Date and in particular parse() and format() functions which will be called by bsl::format. Note that specialization must be defined in the namespace bsl.

 namespace bsl {
 
 template <class t_CHAR>
 struct formatter<Date, t_CHAR> {
     // MANIPULATORS
 
     /// Parse the specified `parseContext` and return an iterator, pointing
     /// to the beginning of the format string.
     template <class t_PARSE_CONTEXT>
     BSLS_KEYWORD_CONSTEXPR_CPP20 typename t_PARSE_CONTEXT::iterator parse(
                                             t_PARSE_CONTEXT& parseContext);
 
     // ACCESSORS
 
     /// Create string representation of the specified `value`, customized
     /// in accordance with the requested format and the specified
     /// `formatContext`, and copy it to the output that the output iterator
     /// of the `formatContext` points to.
     template <class t_FORMAT_CONTEXT>
     typename t_FORMAT_CONTEXT::iterator format(
                                     Date              value,
                                     t_FORMAT_CONTEXT& formatContext) const;
 };
 
 }  // close namespace bsl

Unfortunately, due to the position of this component in the class hierarchy, a full-fledged example would require duplicating a huge amount of code. A complete example of a custom formatter implementation can be found in the bslfmt_format component.