bslfmt_formattercharutil

Detailed Description

Character conversion utilities for bsl::format.

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example: Outputting A Hexadecimal In Upper Case

Purpose

Character conversion utilities for bsl::format.

Classes

• bslfmt::FormatterCharUtil: utilities to perform character conversions

Description

This component provides a FormatterCharUtil struct template that is a namespace for utility functions that convert characters (e.g. from char to wchar_t or lowercase characters to uppercase).

Usage

This section illustrates intended use of this component.

Example: Outputting A Hexadecimal In Upper Case

Suppose we need to output a hexadecimal number to some object (e.g. some character buffer) represented by the output iterator. Additionally, we are required to have the number displayed in uppercase.

 char         number[]     = "0x12cd";
 const size_t sourceLength = sizeof(number) - 1;

First, we convert the number to uppercase in place and verify the result:

 bslfmt::FormatterCharUtil<char>::toUpper(number, number + sourceLength);
 const char *expectedUppercaseNumber = "0X12CD";
 assert(0 == strcmp(number, expectedUppercaseNumber));

Next, we output this uppercase number to the destination, using outputFromChar function. OutputIterator in this example is just a primitive class that minimally satisfies the requirements of the output iterator.

 char destination[8];
 memset(destination, 0, sizeof(destination));
 OutputIterator<char> charIt(destination);
 
 charIt = bslfmt::FormatterCharUtil<char>::outputFromChar(
                                                      number,
                                                      number + sourceLength,
                                                      charIt);
 
 assert(destination + sourceLength == charIt.ptr());
 assert(0 == strcmp(number, destination));

Finally, we demonstrate the main purpose of these functions - to unify the output of values to character strings and wide character strings. All we need to do is just change the template parameter:

 wchar_t wDestination[8];
 memset(wDestination, 0, sizeof(wchar_t) * 8);
 
 wchar_t wcharExpected[] = L"0X12CD";
 
 OutputIterator<wchar_t> wcharIt(wDestination);
 wcharIt = bslfmt::FormatterCharUtil<wchar_t>::outputFromChar(
                                                      number,
                                                      number + sourceLength,
                                                      wcharIt);
 assert(wDestination + sourceLength == wcharIt.ptr());
 assert(0 == wcscmp(wcharExpected, wDestination));