Component bdlb_nullopt [Package bdlb]

Provide a tag type and constant indicating an empty nullable value. More...

Namespaces
namespace	bdlb

---

Detailed Description

Outline

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

Purpose:

Provide a tag type and constant indicating an empty nullable value.

Classes:

NullOptType	tag type representing an empty nullable value
nullOpt	literal value of type NullOptType

See also:

Component bdlb_nullablevalue

Description:

This component provides a class, bdlb::NullOptType, that defines a vocabulary to be used in functions that want to indicate an empty nullable value.

In addition to the NullOptType class type, this component defines a constant, bdlb::nullOpt, of type NullOptType, to act as a literal of this type, much as nullptr is a (built in) literal for null pointers.

Usage:

In this section we show intended use of this component.

Example 1: ...:

Suppose we are implementing a type that has an optional null (empty) state, such as NullableValue. First we declare the class template.

  namespace xyza {
  template <class TYPE>
  class NullableValue {
      // This class can hold a value of (the template parameter) 'TYPE' or be
      // in an empty "null" state.

Then, we privide a buffer than can be uninitialized or hold a valid object, and a bool variable to indicate whether an object is stored in the buffer.

      bsls::ObjectBuffer<TYPE> d_value;
      bool                     d_isNull;

Next, we provide a constructor that makes a copy of an argument of the given TYPE.

    public:
      // CREATORS
      explicit NullableValue(const TYPE& value);
          // Create an object having the specified 'value'.

Then, we provide an implicit constructor using bdlb::NullOptType to allow our users to explicitly create a nullable object in the null state.

      NullableValue(bdlb::NullOptType);                           // IMPLICIT
          // Create a null object.  Note that the passed argument is used
          // only to select this constructor overload, the actual value is
          // not used.

Next we provide accessors to indicate whether the object is in the null state, and to return the wrapped value if one is avaialble.

      // ACCESSORS
      const TYPE& getValue() const;
          // Return a reference to the non-modifiable object held by this
          // 'NullableValue'.  The behavior is undefined if this object is
          // null.

      bool isNull() const;
          // Return 'false' if this object holds a value, and 'true'
          // otherwise.  Note that a 'NullableValue' that does not hold an
          // object is said to be "null".
  };

  }  // close namespace xyza

Now, we can write a function that consumes a nullable value.

  namespace xyzb {

  struct Utility {
      static int unwrap(const xyza::NullableValue<int>& optionalValue);
          // Return the value of the specified 'optionalValue' if it holds a
          // value; otherwise, return 0.
  };

  int Utility::unwrap(const xyza::NullableValue<int>& optionalValue) {
      if (optionalValue.isNull()) {
          return 0;                                                 // RETURN
      }

      return optionalValue.getValue();
  }

  }  // close namespace xyzb

Finally, our clients can call xyza::Utility::unwrap with either a nullable value of their own, or with bdlb::nullOpt to indicate a null object.

  int xyz_main() {
      return xyzb::Utility::unwrap(bdlb::nullOpt);
  }