balxml_typesprintutil

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Behavior of printText on Non-Valid Strings
  • Usage

Purpose

Provide a utility for printing types using XML formatting.

Classes

• balxml::TypesPrintUtil: utility for printing using XML formatting

See also

http://www.w3.org/TR/xmlschema-2/

Description

The balxml::TypesPrintUtil struct provided by this component contains the following functions:

print: Print an object using the supplied formatting mode.

printBase64: Print an object using bdlat_FormattingMode::e_BASE64.

printDecimal: Print an object using bdlat_FormattingMode::e_DEC.

printDefault: Print an object using bdlat_FormattingMode::e_DEFAULT.

printHex: Print an object using bdlat_FormattingMode::e_HEX.

printList: Print an object using bdlat_FormattingMode::e_IS_LIST.

printText: Print an object using bdlat_FormattingMode::e_TEXT.

The output is generated according to each type's lexical representation as described in the XML Schema Specification, which is available at http://www.w3.org/TR/xmlschema-2/. The text input is parsed and output according to the XML-1.0 with UTF-8 encoding, which prevents control characters (accepted by UTF-8) but otherwise accepts valid characters as described in the Unicode Standard 4.0, which is available at http://www.unicode.org/versions/Unicode4.0.0/ (well-formed UTF-8 byte sequences are described in Chapter 3, Section 3.9 and Table 3.5).

The following C++ Type / Formatting Mode combinations are supported by this component:

    C++ Type                            Formatting Mode
    --------                            ---------------
    bool                                e_DEFAULT, e_DEC, e_TEXT
    char                                e_DEFAULT, e_DEC, e_TEXT
    unsigned char                       e_DEFAULT, e_DEC
    [unsigned] short                    e_DEFAULT, e_DEC
    [unsigned] int                      e_DEFAULT, e_DEC
    [unsigned] long                     e_DEFAULT, e_DEC
    bsls::Types::[Uint64|Int64]         e_DEFAULT, e_DEC
    float                               e_DEFAULT, e_DEC
    double                              e_DEFAULT, e_DEC
    bdldfp::Decimal64                   e_DEFAULT, e_DEC
    bsl::string                         e_DEFAULT, e_TEXT, e_BASE64, e_HEX
    bdlt::Date                          e_DEFAULT
    bdlt::DateTz                        e_DEFAULT
    bdlt::Datetime                      e_DEFAULT
    bdlt::DateTimeTz                    e_DEFAULT
    bdlt::Time                          e_DEFAULT
    bdlt::TimeTz                        e_DEFAULT
    bdlb::Variant2<DateTz, Date>        e_DEFAULT
    bdlb::Variant2<TimeTz, Time>        e_DEFAULT
    Variant2<DatetimeTz, Datetime>      e_DEFAULT
    bsl::vector<char>                   e_DEFAULT, e_BASE64, e_HEX, e_TEXT,
                                        e_IS_LIST

In addition to the types listed above, this component also recognizes the following bdlat type categories:

    'bdlat' Type Category               Formatting Mode
    ---------------------               ---------------
    Enumeration                         e_DEFAULT, e_TEXT, e_DECIMAL
    CustomizedType                      Base type's formatting modes
    Array                               e_IS_LIST

When bdlat_FormattingMode::e_DEFAULT is used, the actual formatting mode selected is based on the following mapping:

    C++ Type                            Default Formatting Mode
    --------                            -----------------------
    bool                                e_DEC or e_TEXT
    [unsigned] char                     e_DEC
    [unsigned] short                    e_DEC
    [unsigned] int                      e_DEC
    [unsigned] long                     e_DEC
    bsls::Types::[Uint64|Int64]         e_DEC
    bsl::string                         e_TEXT
    bsl::vector<char>                   e_BASE64
 
    'bdlat' Type Category               Default Formatting Mode
    ---------------------               -----------------------
    Enumeration                         e_TEXT

Behavior of printText on Non-Valid Strings

The output of printText will always be valid XML 1.0 with UTF-8 encoding. When attempting to print text data that contains non-valid UTF-8 characters or non-printable control characters using printText, this component prints the valid characters up to and excluding the first invalid character. See the second example in the Usage section for an illustration.

Usage

The following snippets of code illustrates how to print an bsl::vector<char> object in Base64 format:

#include <balxml_typesprintutil.h>
 
#include <cassert>
#include <sstream>
#include <vector>
 
using namespace BloombergLP;
 
void usageExample1()
{
    bsl::ostringstream ss;
 
    bsl::vector<char> vec;
    vec.push_back('a');
    vec.push_back('b');
    vec.push_back('c');
    vec.push_back('d');
 
    const char EXPECTED_RESULT[] = "YWJjZA==";
 
    balxml::TypesPrintUtil::printBase64(ss, vec);
    assert(EXPECTED_RESULT == ss.str());
}

The following snippet of shows what can be expected when printing valid or invalid data via printText:

void usageExample2()
{
    bsl::ostringstream ss;
 
    const char VALID_STR[] = "Hello \t 'World'";

Note that all characters in the range 0x01 to 0x7F are valid first bytes (including printable ASCII, TAB 0x09, or LF 0x0a, but excluding control characters other than TAB and LF) and that ampersand (& or 0x26), less-than (< or 0x3c), greater-than (> or 0x3e), apostrophe (0x27), and quote ("</tt>) will be printed as <tt>\&amp;</tt>, <tt>\&lt;</tt>, <tt>\&gt</tt>, <tt>\&apos;</tt> and <tt>\&quot;</tt> respectively. Hence the expected output for the above string <tt>VALID_STR</tt> is: @code const char EXPECTED_RESULT[] = "Hello \t 'World'"; @endcode We can test that <tt>printText</tt> will successfully print the string: @code balxml::TypesPrintUtil::printText(ss, VALID_STR); assert(ss.good()); assert(EXPECTED_RESULT == ss.str()); @endcode In addition, when invalid data is printed, the stream is set to a bad state which is the proper means for the user to detect an error, as shown in the following code snippet: @code ss.str(""); const char INVALID_STR[] = "Hello \300\t 'World'"; balxml::TypesPrintUtil::printText(ss, INVALID_STR); assert(ss.fail()); assert("Hello " == ss.str()); }