bdlb_nullablevalue

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Conversion to bool: Explicit with C++11 but Implicit with C++03
  • Usage
    • Example 1: Basic Usage

Purpose

Provide a template for nullable (in-place) objects.

Classes

• bdlb::NullableValue: template for nullable (in-place) objects

See also

bdlb_nullableallocatedvalue, bslstl_optional

Description

This component provides a template class, bdlb::NullableValue<TYPE>, that can be used to augment an arbitrary value-semantic TYPE, such as int or bsl::string, so that it also supports the notion of a "null" value. That is, the set of values representable by the template parameter TYPE is extended to include null. If the underlying TYPE is fully value-semantic, then so will the augmented type bdlb::NullableValue<TYPE>. Two homogeneous nullable objects have the same value if their underlying (non-null) TYPE values are the same, or both are null.

Note that the object of template parameter TYPE that is managed by a bdlb::NullableValue<TYPE> object is created in-*place*. Consequently, the template parameter TYPE must be a complete type when the class is instantiated. In contrast, bdlb::NullableAllocatedValue<TYPE> (see bdlb_nullableallocatedvalue ) does not require that TYPE be complete when that class is instantiated, with the trade-off that the managed TYPE object is always allocated out-of-place in that case.

In addition to the standard homogeneous, value-semantic, operations such as copy construction, copy assignment, equality comparison, and BDEX streaming, bdlb::NullableValue also supports conversion between augmented types for which the underlying types are convertible, i.e., for heterogeneous copy construction, copy assignment, and equality comparison (e.g., between int and double); attempts at conversion between incompatible types, such as int and bsl::string, will fail to compile. Note that these operational semantics are similar to those found in bsl::shared_ptr.

Furthermore, a move constructor (taking an optional allocator) and a move-assignment operator are also provided. Note that move semantics are emulated with C++03 compilers.

Conversion to bool: Explicit with C++11 but Implicit with C++03

bdlb::NullableValue<TYPE> provides a standard-compliant allocator-aware implementation of std::optional<TYPE>. Hence, bdlb::NullableValue<TYPE> converts to bool, where the resulting Boolean value indicates whether the bdlb::NullableValue<TYPE> object is "engaged" (see bslstl_optional ). With C++11 and later, this conversion is explicit (per the C++ Standard) but the conversion is implicit with C++03 because explicit conversion operators were not available until C++11. Note that this implicit conversion on C++03 platforms is implemented using the "unspecified Boolean type" idiom.

For example, consider the following code snippet where we assert behavior that holds with C++11 (and later), i.e., that there is not an implicit conversion from bdlb::NullableValue<double> to bool:

typedef bdlb::NullableValue<double> AnyNullableValue;
 
assert(!(bsl::is_convertible<AnyNullableValue, bool>::value));

However, as explained above, the assertion fails with C++03. The result is the same when double is substituted with any other type.

Usage

This section illustrates intended use of this component.

Example 1: Basic Usage

First, create a nullable int object:

bdlb::NullableValue<int> nullableInt;
assert( nullableInt.isNull());

Next, give the int object the value 123 (making it non-null):

nullableInt.makeValue(123);
assert(!nullableInt.isNull());
assert(123 == nullableInt.value());

Finally, reset the object to its default constructed state (i.e., null):

nullableInt.reset();
assert( nullableInt.isNull());