Component balxml_typesprintutil [Package balxml]

Provide a utility for printing types using XML formatting. More...

Namespaces
namespace	balxml

---

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                                DEFAULT, DEC, TEXT
      char                                DEFAULT, DEC, TEXT
      unsigned char                       DEFAULT, DEC
      [unsigned] short                    DEFAULT, DEC
      [unsigned] int                      DEFAULT, DEC
      [unsigned] long                     DEFAULT, DEC
      bsls::Types::[Uint64|Int64]         DEFAULT, DEC
      float                               DEFAULT, DEC
      double                              DEFAULT, DEC
      bdldfp::Decimal64                   DEFAULT, DEC
      bsl::string                         DEFAULT, TEXT, BASE64, HEX
      bdlt::Date                          DEFAULT
      bdlt::DateTz                        DEFAULT
      bdlt::Datetime                      DEFAULT
      bdlt::DateTimeTz                    DEFAULT
      bdlt::Time                          DEFAULT
      bdlt::TimeTz                        DEFAULT
      bdlb::Variant2<DateTz, Date>        DEFAULT
      bdlb::Variant2<TimeTz, Time>        DEFAULT
      Variant2<DatetimeTz, Datetime>      DEFAULT
      bsl::vector<char>                   DEFAULT, BASE64, HEX, TEXT, IS_LIST

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

      'bdlat' Type Category               Formatting Mode
      ---------------------               ---------------
      Enumeration                         DEFAULT, TEXT, DECIMAL
      CustomizedType                      Base type's formatting modes
      Array                               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                                DEC or TEXT
      [unsigned] char                     DEC
      [unsigned] short                    DEC
      [unsigned] int                      DEC
      [unsigned] long                     DEC
      bsls::Types::[Uint64|Int64]         DEC
      bsl::string                         TEXT
      bsl::vector<char>                   BASE64

      'bdlat' Type Category               Default Formatting Mode
      ---------------------               -----------------------
      Enumeration                         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 (") will be printed as &, <, &gt, ' and " respectively. Hence the expected output for the above string VALID_STR is:

      const char EXPECTED_RESULT[] = "Hello \t 'World'";

We can test that printText will successfully print the string:

      balxml::TypesPrintUtil::printText(ss, VALID_STR);
      assert(ss.good());
      assert(EXPECTED_RESULT == ss.str());

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:

      ss.str("");
      const char INVALID_STR[]  = "Hello \300\t 'World'";
      balxml::TypesPrintUtil::printText(ss, INVALID_STR);
      assert(ss.fail());
      assert("Hello " == ss.str());
  }