Outline
Purpose
Provide a namespace defining enumeration functions.
Classes
- 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 full description of "enumeration" types. The functions in this namespace allow users to:
o load an enumeration value from an integer value ('fromInt').
o load an enumeration value from a string value ('fromString').
o load an integer value from an enumeration value ('toInt').
o load a string value from an enumeration value ('toString').
o set an enumeration to its fallback value ('makeFallback').
o check whether an enumeration supports a fallback value
('hasFallback').
o 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 <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:
int bdlat_enumFromInt(ImageType* result, int number);
int bdlat_enumFromString(ImageType *result,
const char *string,
int stringLength);
int bdlat_enumMakeFallback(ImageType *result);
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);
}
Definition bslstl_string.h:1281
Next, we provide the definitions for each of these functions:
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 };
string,
stringLength)) {
*result = JPG;
return SUCCESS;
}
string,
stringLength)) {
*result = PNG;
return SUCCESS;
}
string,
stringLength)) {
*result = GIF;
return SUCCESS;
}
string,
stringLength)) {
*result = UNKNOWN;
return SUCCESS;
}
return NOT_FOUND;
}
inline
int mine::bdlat_enumMakeFallback(ImageType *result)
{
*result = UNKNOWN;
return 0;
}
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;
}
static bool areEqualCaseless(const char *lhsString, const char *rhsString)
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:
template <>
};
template <>
struct HasFallbackEnumerator<mine::ImageType> :
public bsl::true_type {
};
}
}
Definition bdlat_enumfunctions.h:389
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:
void decodeImageTypeFromXML(bsl::istream& inputData)
{
using namespace BloombergLP;
ImageType object = 0;
int result = decoder.decode(inputData, &object);
assert(0 == result);
assert(PNG == object);
}
Definition balxml_decoderoptions.h:72
Definition balxml_decoder.h:402
Definition balxml_errorinfo.h:353
Definition balxml_minireader.h:343
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)
{
stream >> value;
}
template <class TYPE>
int readEnumOrFallback(bsl::istream& stream, TYPE *object)
{
const int rc = readEnum(stream, object);
}
size_type length() const BSLS_KEYWORD_NOEXCEPT
Definition bslstl_string.h:6601
const CHAR_TYPE * c_str() const BSLS_KEYWORD_NOEXCEPT
Definition bslstl_string.h:6705
int fromString(TYPE *result, const char *string, int stringLength)
int makeFallback(TYPE *result)
We can use these generic functions with mine::ImageType as follows:
void usageExample()
{
using namespace BloombergLP;
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);
}
Definition bslstl_stringstream.h:184
◆ 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 |
1.9.8