bdlat_nullablevalueutil

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Primitive and Derived Functions of Nullable Values
  • Usage
    • Example 1: Accessing the Held Value And Its Category

Purpose

Provide utilities for operating on bdlat "nullable value" types.

Classes

• bdlat::NullableValueUtil: namespace for utility functions on nullables

See also

bdlat_nullablevaluefunctions, bdlat_typecategory

Description

This component provides a utility struct, bdlat::NullableValueUtil, which serves as a namespace for a collection of function templates providing derived operations for "nullable value" types. See bdlat_nullablevaluefunctions for the set of requirements of "nullable value" types in the bdlat framework. See bdlat_typecategory for more general information about this framework.

Primitive and Derived Functions of Nullable Values

In order to be "plugged in" to the bdlat framework as a "nullable value", a type must meet a set of requirements including providing certain function overloads (customization points) and specifying certain type traits, as specified by the bdlat_nullablevaluefunctions component. We call the required function overloads the "primitive" operations of "nullable value" types. This component provides "derived" operations, which are operations that are exclusively defined in terms of primitive operations, and as such can be used with any "nullable value" type.

Usage

In this section we show intended usage of this component.

Example 1: Accessing the Held Value And Its Category

Suppose we would like to define a function that detects whether the value held by a nullable value is an array.

First, we need to define an accessor functor per {bdlat_typecategory |ACCESSOR Functors} that will be used to detect whether the held value is an array:

class MyArrayDetector {
    // DATA
    bool d_didVisitArray;
 
  public:
    // CREATORS
    MyArrayDetector()
    : d_didVisitArray(false)
    {
    }
 
    // MANIPULATORS
    template <class TYPE>
    int operator()(const TYPE& object, bdlat_TypeCategory::Array)
    {
        d_didVisitArray = true;
        return 0;
    }
 
    template <class TYPE, class OTHER_CATEGORY>
    int operator()(const TYPE&, OTHER_CATEGORY)
    {
        d_didVisitArray = false;
        return 0;
    }
 
    // ACCESSORS
    bool didVisitArray()
    {
        return d_didVisitArray;
    }
};

Then, we can define a utility struct, MyNullableValueUtil, that provides a function for detecting whether or not the held value of a nullable value is an array:

struct MyNullableValueUtil {
 
    // CLASS METHODS
    template <class TYPE>
    static int isValueAnArray(bool *isArray, const TYPE& object)
        // Load the value 'true' to the specified 'isArray' if the value
        // stored in the specified 'object' has the "array" type category,
        // and load the value 'false' otherwise.  Return 0 on success,
        // and a non-zero value otherwise.  If a non-zero value is
        // returned, the value loaded to 'isArray' is unspecified.  The
        // behavior is undefined if 'object' contains a null value.
    {
        BSLS_ASSERT(bdlat_TypeCategoryFunctions::select(object) ==
                    bdlat_TypeCategory::e_NULLABLE_VALUE_CATEGORY);
        BSLS_ASSERT(!bdlat_NullableValueFunctions::isNull(object));
 
        MyArrayDetector detector;
        int rc = bdlat::NullableValueUtil::accessValueByCategory(object,
                                                                 detector);
        if (0 != rc) {
            return -1;                                            // RETURN
        }
 
        *isArray = detector.didVisitArray();
        return 0;
    }
};

Finally, we can use this utility to detect whether nullable values are arrays:

void example()
{
    bdlb::NullableValue<int> valueA(42);
 
    bool isArray = false;
    int rc = MyNullableValueUtil::isValueAnArray(&isArray, valueA);
 
    assert(0 == rc);
    assert(! isArray);
 
    bdlb::NullableValue<bsl::vector<int> > valueB;
    valueB.makeValue(bsl::vector<int>());
 
    rc = MyNullableValueUtil::isValueAnArray(&isArray, valueB);
 
    assert(0 == rc);
    assert(isArray);
}