bdlat_enumfunctions

Detailed Description

Provide a namespace defining enumeration functions.

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Basic Usage

Purpose

Provide a namespace defining enumeration functions.

Classes

• bdlat_EnumFunctions: namespace for calling enumeration functions

See also

Description

The bdlat_EnumFunctions namespace provided in this component defines parameterized functions that expose "enumeration" behavior for "enumeration" types. See the package-level documentation for a brief description of "enumeration" types.

The functions in this namespace allow users to:

• load an enumeration value from an integer value (fromInt).
• load an enumeration value from a string value (fromString).
• load an integer value from an enumeration value (toInt).
• load a string value from an enumeration value (toString).
• set an enumeration to its fallback value (makeFallback).
• check whether an enumeration supports a fallback value (hasFallback).
• test whether an enumeration is equal to the fallback value (isFallback).

The meta-functions IsEnumeration and HasFallbackEnumerator indicate whether a type supports the above functions. If the compile-time constant IsEnumeration<TYPE>::value is declared to be nonzero, the type must support the first four functions listed above. If the compile-time constant HasFallbackEnumerator<TYPE>::value is declared to be nonzero, the type must also support the last three functions listed above.

This component provides default implementations of the above listed functions and meta-functions for types that have the bdlat_TypeTraitBasicEnumeration trait. For other types, one may specialize the meta-functions and provide implementations for the functions by declaring overloads of the corresponding customization points. An example of this is provided in the Usage section of this document.

Usage

This section illustrates intended use of this component.

Example 1: Basic Usage

Suppose you have a C++ enum type called ImageType whose enumerators represent supported formats for image files:

#include <bdlat_enumfunctions.h>
#include <bdlb_string.h>
#include <bsl_iostream.h>
#include <bsl_sstream.h>
#include <bsl_string.h>
 
namespace BloombergLP {
 
namespace mine {
 
enum ImageType {
    JPG     = 0,
    PNG     = 1,
    GIF     = 2,
    UNKNOWN = 100
};

We can now make ImageType expose "enumeration" behavior by implementing all the necessary bdlat_enum* functions for ImageType inside the mine namespace (not by attempting to declare specializations or overloads in the bdlat_EnumFunctions namespace). First we should forward declare all the functions that we will implement inside the mine namespace:

// MANIPULATORS
 
/// Load into the specified `result` the enumerator matching the
/// specified `number`.  Return 0 on success, and a non-zero value
/// with no effect on `result` if `number` does not match any
/// enumerator.
int bdlat_enumFromInt(ImageType* result, int number);
 
/// Load into the specified `result` the enumerator matching the
/// specified `string` of the specified `stringLength`.  Return 0 on
/// success, and a non-zero value with no effect on `result` if
/// `string` and `stringLength` do not match any enumerator.
int bdlat_enumFromString(ImageType  *result,
                         const char *string,
                         int         stringLength);
 
/// Load into the specified `result` the fallback enumerator value and
/// return 0 to indicate success.
int bdlat_enumMakeFallback(ImageType *result);
 
// ACCESSORS
 
/// Load into the specified `result` the integer representation of the
/// enumerator value held by the specified `value`.
void bdlat_enumToInt(int *result, const ImageType& value);
 
/// Load into the specified `result` the string representation of the
/// enumerator value held by the specified `value`.
void bdlat_enumToString(bsl::string *result, const ImageType& value);
 
/// Return `true` to indicate that this type supports a fallback
/// enumerator.
bool bdlat_enumHasFallback(const ImageType&);
 
/// Return `true` if the specified `value` equals the fallback
/// enumerator, and `false` otherwise.
bool bdlat_enumIsFallback(const ImageType& value);
 
}  // close namespace mine

Next, we provide the definitions for each of these functions:

// MANIPULATORS
 
inline
int mine::bdlat_enumFromInt(ImageType *result, int number)
{
    enum { SUCCESS = 0, NOT_FOUND = -1 };
 
    switch (number) {
      case JPG: {
        *result = JPG;
        return SUCCESS;
      }
      case PNG: {
        *result = PNG;
        return SUCCESS;
      }
      case GIF: {
        *result = GIF;
        return SUCCESS;
      }
      case UNKNOWN: {
        *result = UNKNOWN;
        return SUCCESS;
      }
      default: {
        return NOT_FOUND;
      }
    }
}
 
inline
int mine::bdlat_enumFromString(ImageType  *result,
                               const char *string,
                               int         stringLength)
{
    enum { SUCCESS = 0, NOT_FOUND = -1 };
 
    if (bdlb::String::areEqualCaseless("jpg",
                                       string,
                                       stringLength)) {
        *result = JPG;
        return SUCCESS;
    }
 
    if (bdlb::String::areEqualCaseless("png",
                                       string,
                                       stringLength)) {
        *result = PNG;
        return SUCCESS;
    }
 
    if (bdlb::String::areEqualCaseless("gif",
                                       string,
                                       stringLength)) {
        *result = GIF;
        return SUCCESS;
    }
 
    if (bdlb::String::areEqualCaseless("unknown",
                                       string,
                                       stringLength)) {
        *result = UNKNOWN;
        return SUCCESS;
    }
 
    return NOT_FOUND;
}
 
inline
int mine::bdlat_enumMakeFallback(ImageType *result)
{
    *result = UNKNOWN;
    return 0;
}
 
// ACCESSORS
 
inline
void mine::bdlat_enumToInt(int *result, const ImageType& value)
{
    *result = static_cast<int>(value);
}
 
inline
void mine::bdlat_enumToString(bsl::string *result, const ImageType& value)
{
    switch (value) {
      case JPG: {
        *result = "JPG";
      } break;
      case PNG: {
        *result = "PNG";
      } break;
      case GIF: {
        *result = "GIF";
      } break;
      case UNKNOWN: {
        *result = "UNKNOWN";
      } break;
      default: {
        *result = "INVALID";
      } break;
    }
}
 
inline
bool mine::bdlat_enumHasFallback(const ImageType&)
{
    return true;
}
 
inline
bool mine::bdlat_enumIsFallback(const ImageType& value)
{
    return value == UNKNOWN;
}

Finally, we need to specialize the IsEnumeration and HasFallbackEnumerator meta-functions in the bdlat_EnumFunctions namespace for the mine::ImageType type. This makes the bdlat infrastructure recognize ImageType as an enumeration abstraction with a fallback enumerator:

namespace bdlat_EnumFunctions {
template <>
struct IsEnumeration<mine::ImageType> : public bsl::true_type {
};
template <>
struct HasFallbackEnumerator<mine::ImageType> : public bsl::true_type {
};
}  // close namespace bdlat_EnumFunctions
}  // close namespace BloombergLP

The bdlat infrastructure (and any component that uses this infrastructure) will now recognize ImageType as an "enumeration" type with a fallback enumerator. For example, suppose we have the following XML data:

<?xml version='1.0' encoding='UTF-8' ?>
<ImageType>PNG</ImageType>

Using the balxml_decoder component, we can load this XML data into a ImageType object:

#include <balxml_decoder.h>
 
void decodeImageTypeFromXML(bsl::istream& inputData)
{
    ImageType object = 0;
 
    balxml::DecoderOptions options;
    balxml::MiniReader     reader;
    balxml::ErrorInfo      errInfo;
 
    balxml::Decoder decoder(&options, &reader, &errInfo);
    int result = decoder.decode(inputData, &object);
 
    assert(0   == result);
    assert(PNG == object);
}

Note that the bdlat framework can be used for functionality other than encoding/decoding into XML. When mine::ImageType is plugged into the framework, then it will be automatically usable within the framework. For example, consider the following generic functions that read a string from a stream and decode its value into a bdlat "enumeration" object:

template <class TYPE>
int readEnum(bsl::istream& stream, TYPE *object)
{
    bsl::string value;
    stream >> value;
 
    return bdlat_EnumFunctions::fromString(
                                          object,
                                          value.c_str(),
                                          static_cast<int>(value.length()));
}
 
template <class TYPE>
int readEnumOrFallback(bsl::istream& stream, TYPE *object)
{
    const int rc = readEnum(stream, object);
    return (0 == rc) ? rc : bdlat_EnumFunctions::makeFallback(object);
}

We can use these generic functions with mine::ImageType as follows:

void usageExample()
{
    bsl::stringstream ss;
    mine::ImageType   object;
 
    ss << "JPG\nWEBP\nWEBP\n";
 
    assert(0             == readEnum(ss, &object));
    assert(mine::JPG     == object);
 
    assert(0             != readEnum(ss, &object));
    assert(mine::JPG     == object);
 
    assert(0             == readEnumOrFallback(ss, &object));
    assert(mine::UNKNOWN == object);
}

Classes
struct	bdlat_EnumFunctions_ImplUtil

Functions
template<class TYPE >
static int	bdlat_EnumFunctions_ImplUtil::makeFallback (TYPE *result, bsl::true_type)
template<class TYPE >
static int	bdlat_EnumFunctions_ImplUtil::makeFallback (TYPE *result, bsl::false_type)
template<class TYPE >
static bool	bdlat_EnumFunctions_ImplUtil::hasFallback (const TYPE &value, bsl::true_type)
template<class TYPE >
static bool	bdlat_EnumFunctions_ImplUtil::hasFallback (const TYPE &value, bsl::false_type)
template<class TYPE >
static bool	bdlat_EnumFunctions_ImplUtil::isFallback (const TYPE &value, bsl::true_type)
template<class TYPE >
static bool	bdlat_EnumFunctions_ImplUtil::isFallback (const TYPE &value, bsl::false_type)

Function Documentation

hasFallback() [1/2]

template<class TYPE >

bool bdlat_EnumFunctions_ImplUtil::hasFallback ( const TYPE &  value, bsl::false_type    )

static

hasFallback() [2/2]

template<class TYPE >

bool bdlat_EnumFunctions_ImplUtil::hasFallback ( const TYPE &  value, bsl::true_type    )

static

isFallback() [1/2]

template<class TYPE >

bool bdlat_EnumFunctions_ImplUtil::isFallback ( const TYPE &  value, bsl::false_type    )

static

isFallback() [2/2]

template<class TYPE >

bool bdlat_EnumFunctions_ImplUtil::isFallback ( const TYPE &  value, bsl::true_type    )

static

makeFallback() [1/2]

template<class TYPE >

int bdlat_EnumFunctions_ImplUtil::makeFallback ( TYPE *  result, bsl::false_type    )

static

makeFallback() [2/2]

template<class TYPE >

int bdlat_EnumFunctions_ImplUtil::makeFallback ( TYPE *  result, bsl::true_type    )

static