Component bdlat_typename [Package bdlat]

Provide string representations for data type names. More...

Classes
struct	bdlat_TypeName
	namespace for type-name functions More...
struct	bdlat_TypeName_Imp
Namespaces
namespace	bdlat_TypeName_Overloadable

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Class Name Information
  • Overloable Class Name Functions For User Defined Classes
  • Generic Type Name Information
  • XSD Type Name Information
  • Usage

Purpose:

Provide string representations for data type names.

Classes:

bdlat_TypeName

namespace for type-name functions

See also:

http://www.w3.org/TR/xmlschema-2/#built-in-datatypes

Description:

This component defines a structure bdlat_TypeName which provides a namespace for functions returning information about the object types. Functions in this namespace allow users to get access to three categories of information:

• class name from the metadata associated with the object type
• generic type name
• XML/XSD type name, based on object type and formatting mode.

Class Name Information:

The template function className returns the object class name from the metadata associated with given object type. Metadata is available for the C++ types that have one the following traits:

  'bdlat_TypeTraitBasicChoice'
  'bdlat_TypeTraitBasicSequence'
  'bdlat_TypeTraitBasicCustomizedType'
  'bdlat_TypeTraitBasicEnumeration'

If metadata is not available for the object type, the function className returns 0 unless the function bdlat_TypeName_className is overloaded by developer.

Overloable Class Name Functions For User Defined Classes:

To provide the custom name for the given user-defined C++ class, the developer should overload the template function bdlat_TypeName_className for this type in the namespace where the type is defined.

WARNING! Do not extend bdlat_TypeName_Overloadable namespace.

Generic Type Name Information:

The template functions name returns the generic type name for the given object. The generic type name is one of the following:

  o predefined name for fundamental types
  o class name from 'bdlat_TypeName_className', if such function returns a
    non-null value
  o name obtained from 'type_info' object provided by C++ runtime, if no
    class name is available

XSD Type Name Information:

The template functions xsdName returns the XML/XSD type name, based on the object type and formatting mode. The returned value is one of the following:

   o predefined name for built-in XSD types
   o class name from 'bdlat_TypeName_className', if such function returns
     a non-null value
   o the "anyType" string, if no class name is available

This component also defines the XSD names for the following C++ types and formatting modes:

  C++ Type                      Formatting Mode             XML Name
  --------                      ---------------             --------
  bool                          DEFAULT/DEC/TEXT            boolean
  char                          DEFAULT/DEC                 byte
  char                          TEXT                        string
  unsigned char                 DEFAULT/DEC                 unsignedByte
  short                         DEFAULT/DEC                 short
  short                         TEXT                        string
  unsigned short                DEFAULT/DEC                 unsignedShort
  int                           DEFAULT/DEC                 int
  unsigned int                  DEFAULT/DEC                 unsignedInt
  bsls::Types::Int64            DEFAULT/DEC                 long
  bsls::Types::Uint64           DEFAULT/DEC                 unsignedLong
  float                         DEFAULT                     float
  float                         DEC                         decimal
  double                        DEFAULT                     double
  double                        DEC                         decimal
  bdldflp::Decimal64            DEFAULT                     Decimal64
  bsl::string                   DEFAULT/TEXT                string
  bsl::string                   BASE64                      base64Binary
  bsl::string                   HEX                         hexBinary
  bdlt::Date                     DEFAULT                     date
  bdlt::DateTz                   DEFAULT                     date
  bdlt::Datetime                 DEFAULT                     dateTime
  bdlt::DatetimeTz               DEFAULT                     dateTime
  bdlt::Time                     DEFAULT                     time
  bdlt::TimeTz                   DEFAULT                     time
  bsl::vector<char>             DEFAULT/BASE64              base64Binary
  bsl::vector<char>             HEX                         hexBinary
  bsl::vector<char>             TEXT                        string
  bsl::vector<short>            TEXT                        string

Usage:

We begin by creating abbreviations for formatting modes and by declaring objects of a number of types:

  int main() {

      static const int DEFAULT = bdlat_FormattingMode::DEFAULT;
      static const int DEC     = bdlat_FormattingMode::DEC;
      static const int HEX     = bdlat_FormattingMode::HEX;
      static const int BASE64  = bdlat_FormattingMode::BASE64;
      static const int TEXT    = bdlat_FormattingMode::TEXT;

      short                    theShort;
      unsigned                 theUint;
      float                    theFloat;
      const char              *theCharPtr;
      bsl::string              theString;

      bdlt::Date                theDate;
      bdlt::DatetimeTz          theDatetime;
      bsl::vector<char>        theCharVector;
      bsl::vector<bsl::string> theStrVector;

None of these types are generated types with metadata, so className will return a null pointer for each of them:

      assert(0 == bdlat_TypeName::className(theShort));
      assert(0 == bdlat_TypeName::className(theUint));
      assert(0 == bdlat_TypeName::className(theFloat));
      assert(0 == bdlat_TypeName::className(theCharPtr));
      assert(0 == bdlat_TypeName::className(theString));

      assert(0 == bdlat_TypeName::className(theDate));
      assert(0 == bdlat_TypeName::className(theDatetime));
      assert(0 == bdlat_TypeName::className(theCharVector));
      assert(0 == bdlat_TypeName::className(theStrVector));

The name function will never return a null pointer. For each of the fundamental and vocabulary types, it returns the known type name. For vector types, it returns the appropriate "vector<X>" string:

      assert(0 == bsl::strcmp("short", bdlat_TypeName::name(theShort)));
      assert(0 == bsl::strcmp("unsigned int",
                              bdlat_TypeName::name(theUint)));
      assert(0 == bsl::strcmp("float", bdlat_TypeName::name(theFloat)));
      assert(0 == bsl::strcmp("const char*",
                              bdlat_TypeName::name(theCharPtr)));

      assert(0 == bsl::strcmp("string", bdlat_TypeName::name(theString)));
      assert(0 == bsl::strcmp("bdlt::Date", bdlat_TypeName::name(theDate)));
      assert(0 == bsl::strcmp("bdlt::DatetimeTz",
                              bdlat_TypeName::name(theDatetime)));
      assert(0 == bsl::strcmp("vector<char>",
                              bdlat_TypeName::name(theCharVector)));
      assert(0 == bsl::strcmp("vector<string>",
                              bdlat_TypeName::name(theStrVector)));

Each of the above types except vector<string> has one or more corresponding XSD types. The XSD type is affected by a formatting mode so that, for example, a vector<char> can be represented as a text string (formatting mode TEXT) or as a sequence of binary bytes (formatting mode HEX or BASE64).

      assert(0 == bsl::strcmp("short",
                              bdlat_TypeName::xsdName(theShort, DEFAULT)));
      assert(0 == bsl::strcmp("unsignedInt",
                              bdlat_TypeName::xsdName(theUint, DEFAULT)));
      assert(0 == bsl::strcmp("float",
                              bdlat_TypeName::xsdName(theFloat, DEFAULT)));
      assert(0 == bsl::strcmp("decimal",
                              bdlat_TypeName::xsdName(theFloat, DEC)));
      assert(0 == bsl::strcmp("base64Binary",
                           bdlat_TypeName::xsdName(theCharVector, DEFAULT)));
      assert(0 == bsl::strcmp("string",
                              bdlat_TypeName::xsdName(theCharVector, TEXT)));

For types that have not corresponding XSD type, xsdName returns "anyType", regardless of formatting mode:

      assert(0 == bsl::strcmp("anyType",
                            bdlat_TypeName::xsdName(theStrVector, DEFAULT)));

      return 0;
  }

If we create our own class:

  namespace MyNamespace {

      class MyClass {
          //...
      };

Then we can assign it a printable name by overloading the bdlat_TypeName_className function in the class's namespace:

      const char *bdlat_TypeName_className(const MyClass&) {
          return "MyClass";
      }

  } // Close MyNamespace

Note that bdlat_TypeName_className must return a string that is valid and does not change for remaining duration the program. The overloaded bdlat_TypeName_className function is automatically used for name and xsdName, as well as for className:

  int main()
  {
      static const int DEFAULT = bdlat_FormattingMode::DEFAULT;

      MyNamespace::MyClass myClassObj;

      assert(0 == bsl::strcmp("MyClass",
                              bdlat_TypeName::className(myClassObj)));
      assert(0 == bsl::strcmp("MyClass", bdlat_TypeName::name(myClassObj)));
      assert(0 == bsl::strcmp("MyClass",
                              bdlat_TypeName::xsdName(myClassObj, DEFAULT)));

      return 0;
  }