bslfmt_formattable

Provide a concept to check for the presence of a bsl::formatter.

Outline

• Purpose
• Classes
• Macros
• Description
  • When is a Type Formattable?
  • Usage
    • Example: Verify the Presence of a bsl::formatter

Purpose

Provide a concept to check for the presence of a bsl::formatter.

Classes

• bsl::formattable<t_TYPE, t_CHAR>: bsl::formatter presence concept

Macros

• BSL_FORMATTABLE_DEFINED: bsl::formatter is available

Description

This component conditionally provides bsl::formattable, a concept that determines if a type has a formatter enabled for a given character type (i.e. char or wchar_t). The concept is defined only if concepts are available on the current platform. The macro BSL_FORMATTABLE_DEFINED may be used to determine if the concept is present or not.

Because this component requires concepts support it is not available portably on all platforms, therefore any portable use of this concept should make use of the appropriate preprocessor guards.

When is a Type Formattable?

A type is formattable if it can be used as a formatted argument of the bsl::format family of functions:

bsl::string fmtd = bsl::format("{}", MyType(42));

That in turn works if there is a matching bsl::formatter specialization for that type, such as:

namespace bsl {
template <class t_CHAR>
class formatter<MyType, t_CHAR> ...
}

Usage

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

Example: Verify the Presence of a bsl::formatter

Suppose we want to write different code depending on if a type has a formatter enabled, and fall back to using standard streaming if it does not.

First we create a type that supports streaming but not formatting with bsl::format:

 struct Streamable {};
 std::ostream& operator<<(std::ostream& os, const Streamable&) {
     return os << "Streamable";
 }

Then we demonstrate that this type is not formattable, but an int is. Since the concept may not exists (older compilers/standards) we need to protect the code with the preprocessor:

#ifdef BSL_FORMATTABLE_DEFINED
  assert(false == (bsl::formattable<Streamable, char>));
  assert(true  == (bsl::formattable<int,        char>));
#endif

Next we create a generic function to convert a value to string, center-aligned, and we provide two implementations, the first one for types that are formattable in case the concept exists, and just the stream-based variation if it does not.

template <class t_TYPE>
bsl::string
centeredIn(const t_TYPE& obj, size_t width)
#ifdef BSL_FORMATTABLE_DEFINED
  requires (!bsl::formattable<t_TYPE, char>)
#endif
{
    bsl::ostringstream os;
    os << obj;
    bsl::string s = os.str();
 
    width = bsl::max(width, s.length());
 
    const size_t allPadding = width - s.length();
    s.insert(s.begin(), allPadding / 2, ' ');
    s.append(allPadding - allPadding / 2, ' ');
 
    return s;
}

Then, if the concept is present, we define the format-based overload:

#ifdef BSL_FORMATTABLE_DEFINED
template <class t_TYPE>
bsl::string
centeredIn(const t_TYPE& obj, size_t width)
requires (bsl::formattable<t_TYPE, char>)
{
    return bsl::format("{:^{}}", obj, width);
}
#endif

Finally, we can call the centeredIn function and let concepts select the right variation (if concepts are available):

bsl::string s = centeredIn(Streamable(), 14);
assert(s == "  Streamable  ");
 
s = centeredIn(42, 8);
assert(s == "   42   ");