bslfmt.h

Go to the documentation of this file.

/// @file bslfmt.h
///
///
/// @defgroup bslfmt Package bslfmt
/// @brief  Basic Standard Library Format Implementation (bslfmt)
/// @addtogroup bsl
/// @{
/// @addtogroup bslfmt
/// @{
/// * <a href="#bslfmt-purpose"> Purpose</a>
/// * <a href="#bslfmt-mnemonic"> Mnemonic </a>
/// * <a href="#bslfmt-description"> Description </a>
///   * <a href="#bslfmt-hierarchical-synopsis"> Hierarchical Synopsis </a>
///   * <a href="#bslfmt-component-synopsis"> Component Synopsis </a>
///   * <a href="#bslfmt-streaming-based-formatting"> Streaming-based Formatting </a>
///     * <a href="#bslfmt-design-choices"> Design Choices </a>
///     * <a href="#bslfmt-wrapper"> Wrapper </a>
///     * <a href="#bslfmt-trait-enabled-formatter"> Trait-enabled Formatter </a>
///     * <a href="#bslfmt-format-specification-strings-for-streamed-types"> Format Specification Strings for Streamed Types </a>
///
/// # Purpose {#bslfmt-purpose}
/// Provide implementation mechanisms for bsl::format.
///
/// # Mnemonic {#bslfmt-mnemonic}
/// Basic Standard Library Format Implementation (bslfmt)
///
/// # Description {#bslfmt-description}
/// The 'bslfmt' package provides implementation mechanisms for
///              bsl::format and associated types.
///
/// ## Hierarchical Synopsis {#bslfmt-hierarchical-synopsis}
///
/// The 'bslfmt' package currently has 40 components having 14 levels of physical
/// dependency.  The list below shows the hierarchical ordering of the components.
/// The order of components within each level is not architecturally significant,
/// just alphabetical.
/// @code
///  14. bslfmt_enablestreamedformatter
///      bslfmt_print
///      bslfmt_print_ostream                                            !PRIVATE!
///      bslfmt_streamed
///
///  13. bslfmt_formattable
///      bslfmt_print_imp                                                !PRIVATE!
///      bslfmt_print_ostream_imp                                        !PRIVATE!
///      bslfmt_streamedformatter
///
///  12. bslfmt_format
///
///  11. bslfmt_format_imp                                               !PRIVATE!
///
///  10. bslfmt_formatterbool
///      bslfmt_formattercharacter
///      bslfmt_formatterintegral
///      bslfmt_formatterpointer
///
///   9. bslfmt_formatterfloating
///      bslfmt_formatterintegralbase
///      bslfmt_formatterstring
///
///   8. bslfmt_padutil
///      bslfmt_standardformatspecification
///
///   7. bslfmt_formatspecificationparser
///      bslfmt_formattertestutil
///
///   6. bslfmt_mockformatcontext
///      bslfmt_mockparsecontext
///
///   5. bslfmt_format_context                                           !PRIVATE!
///      bslfmt_formatterspecificationnumericvalue
///
///   4. bslfmt_format_args                                              !PRIVATE!
///
///   3. bslfmt_format_arg                                               !PRIVATE!
///      bslfmt_formatparsecontext
///      bslfmt_unicodecodepoint
///
///   2. bslfmt_format_string                                            !PRIVATE!
///      bslfmt_formaterror
///      bslfmt_formatterbase
///      bslfmt_formattercharutil
///      bslfmt_formatterunicodedata
///      bslfmt_testspecificationgenerator
///
///   1. bslfmt_format_arg_cpp03                                         !PRIVATE!
///      bslfmt_format_args_cpp03                                        !PRIVATE!
///      bslfmt_format_imp_cpp03                                         !PRIVATE!
///      bslfmt_print_imp_cpp03                                          !PRIVATE!
///      bslfmt_print_ostream_imp_cpp03                                  !PRIVATE!
/// @endcode
///
/// ## Component Synopsis {#bslfmt-component-synopsis}
///
///  @ref bslfmt_enablestreamedformatter :
///       Provide a trait to enable stream based formatting of a type.
/// 
///  @ref bslfmt_format :
///       Provide a standard compliant `format` implementation.
/// 
///  @ref bslfmt_format_arg :                                                !PRIVATE!
///       Provide a proxy for an argument for use by bsl::format
/// 
///  @ref bslfmt_format_arg_cpp03 :                                          !PRIVATE!
///       Provide C++03 implementation for bslfmt_format_arg.h
/// 
///  @ref bslfmt_format_args :                                               !PRIVATE!
///       Provide a container of arguments for use by bsl::format
/// 
///  @ref bslfmt_format_args_cpp03 :                                         !PRIVATE!
///       Provide C++03 implementation for bslfmt_format_args.h
/// 
///  @ref bslfmt_format_context :                                            !PRIVATE!
///       Provides access to formatting state.
/// 
///  @ref bslfmt_format_imp :                                                !PRIVATE!
///       Provide a standard compliant `format` implementation
/// 
///  @ref bslfmt_format_imp_cpp03 :                                          !PRIVATE!
///       Provide C++03 implementation for bslfmt_format_imp.h
/// 
///  @ref bslfmt_format_string :                                             !PRIVATE!
///       Provide a string_view wrapper for formatting library usage
/// 
///  @ref bslfmt_formaterror :
///       Provide an exception type for format library errors.
/// 
///  @ref bslfmt_formatparsecontext :
///       Provides access to formatting parsing string and parsing state.
/// 
///  @ref bslfmt_formatspecificationparser :
///       Tokenization utility for use within BSL `format` spec parsers
/// 
///  @ref bslfmt_formattable :
///       Provide a concept to check for the presence of a `bsl::formatter`.
/// 
///  @ref bslfmt_formatterbase :
///       Provide a base template for formatter specializations.
/// 
///  @ref bslfmt_formatterbool :
///       Provide a formatter customization for bool type
/// 
///  @ref bslfmt_formattercharacter :
///       Provide a formatter customization for character types
/// 
///  @ref bslfmt_formattercharutil :
///       Character conversion utilities for `bsl::format`.
/// 
///  @ref bslfmt_formatterfloating :
///       Provide a formatter customization for floating point types
/// 
///  @ref bslfmt_formatterintegral :
///       Provide a formatter customization for integer types
/// 
///  @ref bslfmt_formatterintegralbase :
///       Provide a formatter customization for integer types
/// 
///  @ref bslfmt_formatterpointer :
///       Provide a formatter customization for pointer types
/// 
///  @ref bslfmt_formatterspecificationnumericvalue :
///       Integer value for use within `bsl::format` specification parsers
/// 
///  @ref bslfmt_formatterstring :
///       Provide a string formatter for use by bsl::format
/// 
///  @ref bslfmt_formattertestutil :
///       Provide utilities for testing custom formatters
/// 
///  @ref bslfmt_formatterunicodedata :
///       Private unicode data tables for use by `bsl::format`.
/// 
///  @ref bslfmt_mockformatcontext :
///       Provide mock context to test formatter specializations
/// 
///  @ref bslfmt_mockparsecontext :
///       Provide mock context to test formatter specializations
/// 
///  @ref bslfmt_padutil :
///       Provide padding utilities for the `bslfmt` package and clients.
/// 
///  @ref bslfmt_print :
///       Provide a standard compliant `print(FILE)` implementation.
/// 
///  @ref bslfmt_print_imp :                                                 !PRIVATE!
///       Provide a standard compliant `print(FILE)` implementation.
/// 
///  @ref bslfmt_print_imp_cpp03 :                                           !PRIVATE!
///       Provide C++03 implementation for bslfmt_print_imp.h
/// 
///  @ref bslfmt_print_ostream :                                             !PRIVATE!
///       Provide a standard compliant `print(ostream)` implementation.
/// 
///  @ref bslfmt_print_ostream_imp :                                         !PRIVATE!
///       Provide a standard compliant `print(ostream)` implementation.
/// 
///  @ref bslfmt_print_ostream_imp_cpp03 :                                   !PRIVATE!
///       Provide C++03 implementation for bslfmt_print_ostream_imp.h
/// 
///  @ref bslfmt_standardformatspecification :
///       Private utility for use within BSL `format` standard spec parsers
/// 
///  @ref bslfmt_streamed :
///       Provide a wrapper to format using an `ostream` `operator<<`
/// 
///  @ref bslfmt_streamedformatter :
///       Provide a formatter that uses the `ostream` insert `operator<<`.
/// 
///  @ref bslfmt_testspecificationgenerator :
///       Provide a generator for test format specifications
/// 
///  @ref bslfmt_unicodecodepoint :
///       Provide a Unicode code point representation
///
/// ## Streaming-based Formatting {#bslfmt-streaming-based-formatting}
///
/// This package contains two components that facilitate adoption of `bsl::format`
/// for user-defined types that provide an `ostream` insert `operator<<`.
///
/// ### Design Choices {#bslfmt-design-choices}
///
/// This package has two different ways to support formatting types that have an
/// `ostream` insert `operator<<` defined but don't have `bsl::format`ing enabled.
/// Choosing between the two solutions is a design decision and here we present
/// the circumstances and consequences of using either solution.
///
/// The choices are wrapping or enabling stream-based formatting using a trait.
/// Either option provides the same (limited) functionality: the type is converted
/// to a string using `ostream` insert `operator<<` and that string is then
/// formatted as if the string had been passed directly to `bsl::format` (see the
/// table below).
///
/// ### Wrapper {#bslfmt-wrapper}
///
/// The wrapper should be the first design choice as it does not lock in a design
/// decision (unlike creating a formatter).
///
/// The wrapper has a simple, (as) short (as possible) syntax:
///```
///  bsl::string bsl::format("{:-^12}", bslfmt::streamed(streamableType));
///```
///
/// The above code uses the `ostream` insert `operator<<` of `StreamableType` to
/// "convert" the object to string and formats the string according to the format
/// specification.
///
/// **Consequences**:
///   * The wrapper has to be used at every place where such an object is
///     formatted.
///
///   * The formatting support is simplistic.
///
/// May be Useful in the Following Circumstances:
///   * You do not own the type so you cannot create a `formatter` for it without
///     creating a possible collision with a formatter introduced by the owner.
///
///   * Your type really needs its own `formatter` but you need time to design and
///     implement that.  You do not want to lock yourself into forever supporting
///     the string-based simplistic formatting abilities in your future formatter
///     so you rather wrap the type where you need to `format` (e.g., log) it.
///
/// There may be many reasons why a type should have its own formatter.  One is
/// that it is not string-like but number-like.  Or it is complex where you may
/// want to show only parts of it, or in different format etc.  The type may also
/// be an identifier so that truncating it (which the string format supports) is a
/// mistake.
///
/// As the previous (non-exhaustive) list shows you probably want to use the
/// wrapper in **most** cases, because using the trait-enabled formatter may lock
/// you into supporting the string-based format string syntax.
///
/// ### Trait-enabled Formatter {#bslfmt-trait-enabled-formatter}
///
/// If the stream-capable type you are formatting is **your** type (so you can
/// safely define a formatter) you may opt for enabling string-like formatting.
///
/// Note that the **consequence** is that may be locked into supporting
/// string-like formatting for that type.  That means when you design your own
/// format-specification syntax has to be able tell the difference between the
/// string-like formatting specification and your new formatting specification.
///
/// Enabling the formatting is as simple as:
///```
///  public:
///    // TRAITS
///    BSLMF_NESTED_TRAIT_DECLARATION(NowFormattableType,
///                                   bslfmt::EnableStreamedFormatter);
///```
///
/// **Consequences**
///   * You may be locked into supporting the string-like format specification and
///     whatever the resulting streamed output looks like.
///
///   * You get the simplistic, string-based formatting.
///
///
/// May be Useful in the Following Circumstances:
///   * You do not care to implement a formatter for the type, and it is unlikely
///     to ever require a different or more complicated format specification.
///
///   * You own the type.
///
/// In other words, if you declare the trait for your type, users of your type
/// will start formatting your type with string options, and those users will
/// become broken later if you write your own formatter that either does not
/// support all string-formatting options, or repurposes any subset of the string
/// format specification with a different meaning.
///
/// ### Format Specification Strings for Streamed Types {#bslfmt-format-specification-strings-for-streamed-types}
///
/// The format specification string for a `bsl::streamed` wrapped object matches
/// that for a string. Specifically, it supports:
///   * alignment
///   * width
///   * precision (which is used to truncate)
///
/// For details see
/// [Standard format specification]
/// (http://www.en.cppreference.com/w/cpp/utility/format/spec.html)
///
/// Imagine we have a simple type that outputs "12345" when output to a stream:
///```
/// class Streamable {};
///
/// std::ostream& operator<<(std::ostream& os, const Streamable&)
/// {
///     return os << "012345";
/// }
///```
/// The following table describes the effect of different format specifications:
///
/// | Width | Alignment | Pad Char | Precision | Format Spec | Output Text  |
/// |-------|-----------|----------|-----------|-------------|--------------|
/// | N/A   | N/A       | N/A      | N/A       | "{}"        | "012345"     |
/// | N/A   | N/A       | N/A      | 3         | "{:.3}"     | "012"        |
/// | 8     | N/A       | N/A      | N/A       | "{:8}"      | "012345  "   |
/// | 8     | left      | N/A      | N/A       | "{:<8}"     | "012345  "   |
/// | 8     | center    | N/A      | N/A       | "{:^8}"     | " 012345 "   |
/// | 8     | right     | N/A      | N/A       | "{:>8}"     | "  012345"   |
/// | 8     | center    | =        | N/A       | "{:=^8}"    | "=012345="   |
/// | 6     | center    | *        | 2         | "{:*^6.2}"  | "**01**"     |
///
///
/// @}
/** @} */