- Generated by
1.9.8
|
BDE 4.39.x Production Release
|
Basic Standard Library Format Implementation (bslfmt)
Provide implementation mechanisms for bsl::format.
Basic Standard Library Format Implementation (bslfmt)
The 'bslfmt' package provides implementation mechanisms for bsl::format and associated types.
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.
bslfmt_enablestreamedformatter : Provide a trait to enable stream based formatting of a type.
bslfmt_format : Provide a standard compliant format implementation.
bslfmt_format_arg : !PRIVATE! Provide a proxy for an argument for use by bsl::format
bslfmt_format_arg_cpp03 : !PRIVATE! Provide C++03 implementation for bslfmt_format_arg.h
bslfmt_format_args : !PRIVATE! Provide a container of arguments for use by bsl::format
bslfmt_format_args_cpp03 : !PRIVATE! Provide C++03 implementation for bslfmt_format_args.h
bslfmt_format_context : !PRIVATE! Provides access to formatting state.
bslfmt_format_imp : !PRIVATE! Provide a standard compliant format implementation
bslfmt_format_imp_cpp03 : !PRIVATE! Provide C++03 implementation for bslfmt_format_imp.h
bslfmt_format_string : !PRIVATE! Provide a string_view wrapper for formatting library usage
bslfmt_formaterror : Provide an exception type for format library errors.
bslfmt_formatparsecontext : Provides access to formatting parsing string and parsing state.
bslfmt_formatspecificationparser : Tokenization utility for use within BSL format spec parsers
bslfmt_formattable : Provide a concept to check for the presence of a bsl::formatter.
bslfmt_formatterbase : Provide a base template for formatter specializations.
bslfmt_formatterbool : Provide a formatter customization for bool type
bslfmt_formattercharacter : Provide a formatter customization for character types
bslfmt_formattercharutil : Character conversion utilities for bsl::format.
bslfmt_formatterfloating : Provide a formatter customization for floating point types
bslfmt_formatterintegral : Provide a formatter customization for integer types
bslfmt_formatterintegralbase : Provide a formatter customization for integer types
bslfmt_formatterpointer : Provide a formatter customization for pointer types
bslfmt_formatterspecificationnumericvalue : Integer value for use within bsl::format specification parsers
bslfmt_formatterstring : Provide a string formatter for use by bsl::format
bslfmt_formattertestutil : Provide utilities for testing custom formatters
bslfmt_formatterunicodedata : Private unicode data tables for use by bsl::format.
bslfmt_mockformatcontext : Provide mock context to test formatter specializations
bslfmt_mockparsecontext : Provide mock context to test formatter specializations
bslfmt_padutil : Provide padding utilities for the bslfmt package and clients.
bslfmt_print : Provide a standard compliant print(FILE) implementation.
bslfmt_print_imp : !PRIVATE! Provide a standard compliant print(FILE) implementation.
bslfmt_print_imp_cpp03 : !PRIVATE! Provide C++03 implementation for bslfmt_print_imp.h
bslfmt_print_ostream : !PRIVATE! Provide a standard compliant print(ostream) implementation.
bslfmt_print_ostream_imp : !PRIVATE! Provide a standard compliant print(ostream) implementation.
bslfmt_print_ostream_imp_cpp03 : !PRIVATE! Provide C++03 implementation for bslfmt_print_ostream_imp.h
bslfmt_standardformatspecification : Private utility for use within BSL format standard spec parsers
bslfmt_streamed : Provide a wrapper to format using an ostream operator<<
bslfmt_streamedformatter : Provide a formatter that uses the ostream insert operator<<.
bslfmt_testspecificationgenerator : Provide a generator for test format specifications
bslfmt_unicodecodepoint : Provide a Unicode code point representation
This package contains two components that facilitate adoption of bsl::format for user-defined types that provide an ostream insert operator<<.
This package has two different ways to support formatting types that have an ostream insert operator<< defined but don't have bsl::formating 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).
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:
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:
May be Useful in the Following Circumstances:
formatter for it without creating a possible collision with a formatter introduced by the owner.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.
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:
Consequences
May be Useful in the Following Circumstances:
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.
The format specification string for a bsl::streamed wrapped object matches that for a string. Specifically, it supports:
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:
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**" |
1.9.8