Component balcl_optiontype [Package balcl]

Enumerate the types supported for command-line-option values. More...

Namespaces
namespace	balcl

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Enumerators
  • Usage
    • Example 1: Basic Syntax
    • Example 2: Utility Methods

Purpose:

Enumerate the types supported for command-line-option values.

Classes:

balcl::OptionType

command-line option types enum and utilities

See also:

Component balcl_optionvalue, Component balcl_commandline

Description:

This component provides a struct, balcl::OptionType, that is a namespace for:

• A typedef for each of the types allowed for command-line-option values.
• An enumerator that represents each of those types.
• A statically-initialized null pointer for each of those types.
• Utility functions.

The enumerator values are used to control type-dependent operations where the type is not known until runtime.

The names of related symbols are similar to each other. For example, the supported option-value type bsl::vector<bdtl::Datetime> has:

  Symbol                               Description
  ------------------------------------ --------------------------------
  balcl::OptionType::DatetimeArray     alias ('typedef')
  balcl::OptionType::e_DATETIME_ARRAY  enumerator
  balcl::OptionType::k_DATETIME_ARRAY  statically-initialized null pointer

The null pointer symbols are typically used with the constructor of balcl::TypeInfo. They provide a clearly named way to select the constructor to create an object having the desired type attribute. See balcl_typeinfo and balcl_commandline.

In addition to the conventional enumeration methods, this component also provides some utility functions that categorize the represented types. For example, given an enumerator representing a scalar type, the balcl::OptionType::toArrayType method returns the enumerator representing an array of that scalar type.

Enumerators:

  Enumerator       Type Alias    Type
  ---------------- ------------- -------------------------------
  e_VOID           n/a           void
  e_BOOL           Bool          bool
  e_CHAR           Char          char
  e_INT            Int           int
  e_INT64          Int64         bsls::Types::Int64
  e_DOUBLE         Double        double
  e_STRING         String        bsl::string
  e_DATETIME       Datetime      bdlt::Datetime
  e_DATE           Date          bdlt::Date
  e_TIME           Time          bdlt::Time
  e_CHAR_ARRAY     CharArray     bsl::vector<char>
  e_INT_ARRAY      IntArray      bsl::vector<int>
  e_INT64_ARRAY    Int64Array    bsl::vector<bsls::Types::Int64>
  e_DOUBLE_ARRAY   DoubleArray   bsl::vector<double>
  e_STRING_ARRAY   StringArray   bsl::vector<bsl::string>
  e_DATETIME_ARRAY DatetimeArray bsl::vector<bdlt::Datetime>
  e_DATE_ARRAY     DateArray     bsl::vector<bdlt::Date>
  e_TIME_ARRAY     TimeArray     bsl::vector<bdlt::Time>

Usage:

This section illustrates intended use of this component.

Example 1: Basic Syntax:

The following snippets of code provide a simple illustration of balcl::OptionType usage.

First, we create a variable value of type balcl::OptionType::Enum and initialize it to the value balcl::OptionType::e_STRING:

  balcl::OptionType::Enum value = balcl::OptionType::e_STRING;

Next, we store a pointer to its ASCII representation in a variable asciiValue of type const char *:

  const char *asciiValue = balcl::OptionType::toAscii(value);
  assert(0 == bsl::strcmp(asciiValue, "STRING"));

Finally, we print the value to bsl::cout:

  bsl::cout << value << bsl::endl;

This statement produces the following output on stdout:

  STRING

Example 2: Utility Methods:

In a software system devoted to assembling option values of various types, the code is often governed in terms of the enumerated values (balcl::OptionType::Enum) corresponding to the various types. In particular, in order to assemble an option value of one of the array types (e.g., balcl::OptionType::e_STRING_ARRAY), one must first construct the constitute elements.

Suppose we have a class, MyMultitypeValue, that can, at runtime, be set to contain a value of one of the types named by balcl::OptionType. We may want to initialize a MyMultitypeValue object from an input stream using a utility function MyMultitypeValueUtil::parse:

  int MyMultitypeValueUtil::parse(MyMultitypeValue        *result,
                                  bsl::ostream&            input,
                                  balcl::OptionType::Enum  type)
  {
      BSLS_ASSERT(result);

      result->setType(type);

If type is not one of the array types, as determined by the balcl::OptionType::isArrayType method, one calls MyMultitypeValueUtil::parseScalar:

      if (!balcl::OptionType::isArrayType(type)) {
          return MyMultitypeValueUtil::parseScalar(result, input, type);
                                                                    // RETURN
      } else {

Otherwise, we have an array type. In this case, we must call parseScalar repeatedly and build a vector of those scalar values. The scalar type can be calculated from the given array type by the balcl::OptionType::fromArrayType method:

          balcl::OptionType::Enum scalarType =
                                      balcl::OptionType::fromArrayType(type);

          MyMultitypeValue element(scalarType);

          int rc;
          while (0 == (rc = MyMultitypeValueUtil::parseScalar(&element,
                                                              input,
                                                              scalarType))) {
              result->append(element);
          }
          return rc;                                                // RETURN
      }
  }