bdlat_enumutil

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage

Purpose

Provide functions for decoding enumerations with fallback values.

Classes

• bdlat::EnumUtil: namespace for utility functions for decoding enumerations

See also

bdlat_enumfunctions

Description

This component provides a struct, bdlat::EnumUtil, with two utility function templates, fromIntOrFallbackIfEnabled and fromStringOrFallbackIfEnabled, which respectively attempt to decode a bdlat "enumeration" type from the integral or string representation. However, unlike the decoding functions in the bdlat_EnumFunctions namespace, when the functions in this component are given values that do not correspond to any enumerator, they attempt to set the result to the "fallback" enumerator value, if possible, instead of failing.

Usage

This section illustrates intended use of this component.

Suppose you have a C++ enum type called ImageType whose enumerators represent supported formats for image files, and it exposes "enumeration" behavior as described in bdlat_enumfunctions :

#include <bdlat_enumfunctions.h>
#include <bdlb_string.h>
#include <bsl_string.h>
 
namespace BloombergLP {
namespace mine {
 
enum ImageType {
    JPG     = 0,
    PNG     = 1,
    GIF     = 2,
    UNKNOWN = 100
};
 
// MANIPULATORS
 
int bdlat_enumFromInt(ImageType* result, int number);
 
int bdlat_enumFromString(ImageType  *result,
                         const char *string,
                         int         stringLength);
 
int bdlat_enumMakeFallback(ImageType *result);
 
// ACCESSORS
 
void bdlat_enumToInt(int *result, const ImageType& value);
 
void bdlat_enumToString(bsl::string *result, const ImageType& value);
 
bool bdlat_enumHasFallback(const ImageType&);
 
bool bdlat_enumIsFallback(const ImageType& value);
 
}  // close namespace mine

Next, we provide definitions for the bdlat_enum* customization point function overloads:

// 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;
}

To complete the implementation of mine::ImageType as an "enumeration" type with fallback enumerator recognized by the bdlat framework, we specialize the necessary traits:

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

We can now use the methods in EnumUtil to decode integral and string values into mine::ImageType values, falling back to the mine::UNKNOWN enumerator value when the integral or string value does not correspond to any enumerator:

void usageExample()
{
    using namespace BloombergLP;
 
    mine::ImageType imageType;
    int rc;
 
    rc = bdlat::EnumUtil::fromIntOrFallbackIfEnabled(&imageType, 1);
    assert(0         == rc);
    assert(mine::PNG == imageType);
 
    rc = bdlat::EnumUtil::fromIntOrFallbackIfEnabled(&imageType, 4);
    assert(0             == rc);
    assert(mine::UNKNOWN == imageType);
 
    rc = bdlat::EnumUtil::fromStringOrFallbackIfEnabled(&imageType,
                                                        "GIF",
                                                        3);
    assert(0         == rc);
    assert(mine::GIF == imageType);
 
    rc = bdlat::EnumUtil::fromStringOrFallbackIfEnabled(&imageType,
                                                        "WEBP",
                                                        4);
    assert(0             == rc);
    assert(mine::UNKNOWN == imageType);
}

Note that the methods in EnumUtil may also be used with bdlat "enumeration" types that do not support a fallback enumerator. In such cases, they can fail by returning a non-zero error code.