Component bslstl_optional [Package bslstl]

Provide a standard-compliant allocator aware optional type. More...

Outline

• Purpose
• Classes
• Description
  • Sections
  • Usage
  • Known limitations

Purpose:

Provide a standard-compliant allocator aware optional type.

Classes:

bsl::optional

template class for optional objects

Canonical Header:

bsl_optional.h

Description:

This component provides a template class, bsl::optional<TYPE>, that implements a notion of object that may or may not contain a TYPE value. This template class also provides an interface to check if the optional object contains a value or not, as well as a contextual conversion to bool. If an optional object is engaged, i.e. contains a value, it will evaluate to true when converted to bool; otherwise, it will evaluate to false when converted to bool.

An optional object is engaged if it has been initialized with, or assigned from an object of TYPE or another engaged optional object, or if the value was created using the emplace method. Other types of assignment and initialization (including default initialization), as well as calling reset method will result in the optional object being disengaged.

If the underlying TYPE has value-semantics, then so will the type bsl::optional<TYPE>. Two homogeneous optional 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 bsl::optional<TYPE> object is created in-*place*. Consequently, the template parameter TYPE must be a complete type when the class is instantiated.

In addition to the standard homogeneous, value-semantic, operations such as copy/move construction, copy/move assignment, equality comparison, and relational operators, bsl::optional also supports conversion between optional 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.

For allocator-aware types, bsl::optional uses the same allocator for all value_type objects it manages during its lifetime.

Sections:

This file is very complex, a navigation map of this file can be obtained by: $ grep -n Section: bslstl_optional.h

Usage:

The following snippets of code illustrate use of this component:

First, create a optional int object:

  bsl::optional<int> optionalInt;
  assert(!optionalInt.has_value());

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

  optionalInt.emplace(123);
  assert( optionalInt.has_value());
  assert(123 == optionalInt.value());

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

  optionalInt.reset();
  assert(!optionalInt.has_value());

Known limitations:

• For assignment/construction constraints, we use is_constructible but the exact creation will be done using allocation construction that will invoke an allocator-extended constructor for allocator-aware types. If the value_type is constructible from the assignment/constructor argument, but doesn't have a corresponding allocator-extended constructor, the overload selection may not be be correct.
• optional<const TYPE> is fully supported in C++11 and onwards. However, due to limitations of MovableRef<const TYPE>, C++03 support for const value_types is limited and move semantics of such an optional in C++03 will not work.