[#bsl-optional-072]
= xref:bsl.adoc[bsl]::optional
:relfileprefix: ../
:mrdocs:

== Synopsis

Declared in `<bslstl_optional.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<class t_TYPE>
class optional
    : public xref:BloombergLP/bslstl/Optional_Base-05.adoc[BloombergLP::bslstl::Optional_Base<t_TYPE>]
----

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bslstl/Optional_Base-05.adoc[BloombergLP::bslstl::Optional_Base<t_TYPE>]`
| This component‐private class template implements the functionality of `bsl::optional`. The primary template is instantiated when `TYPE` is allocator‐aware, and holds the allocator that is used to create the stored object.
|===

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslstl/Optional_Base-05/allocator_type.adoc[`allocator_type`] 
| This `typedef` is an alias to `bsl::allocator<char>`.
| xref:BloombergLP/bslstl/Optional_Base-05/value_type.adoc[`value_type`] 
| `value_type` is an alias for the underlying `TYPE` upon which this template class is instantiated, and represents the type of the managed object. The name is chosen so it is compatible with the `std::optional` implementation.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/optional-072/2constructor-043.adoc[`optional`]         [.small]#[constructor]#
| Constructors
| xref:bsl/optional-072/operator_assign-01.adoc[`operator=`] 
| Assignment operators
| xref:bsl/optional-072/and_then-08d.adoc[`and_then`] 
| `and_then` overloads
| xref:BloombergLP/bslstl/Optional_Base-05/emplace-02.adoc[`emplace`] 
| `emplace` overloads
| xref:BloombergLP/bslstl/Optional_Base-05/get_allocator.adoc[`get_allocator`] 
| Return allocator used for construction of `value_type`.
| xref:BloombergLP/bslstl/Optional_Base-05/has_value.adoc[`has_value`] 
| Return `false` if this object is disengaged, and `true` otherwise.
| xref:BloombergLP/bslstl/Optional_Base-05/operator_star-0b.adoc[`operator*`] 
| Dereference operators
| xref:BloombergLP/bslstl/Optional_Base-05/operator_ptr-0a.adoc[`operator‐>`] 
| Member access operators
| xref:bsl/optional-072/or_else-09.adoc[`or_else`] 
| `or_else` overloads
| xref:BloombergLP/bslstl/Optional_Base-05/reset.adoc[`reset`] 
| Reset this object to the default constructed state (i.e., to a disengaged state).
| xref:BloombergLP/bslstl/Optional_Base-05/swap.adoc[`swap`] 
| Efficiently exchange the value of this object with the value of the specified `other` object. This method provides the no‐throw exception‐safety guarantee if the template parameter `t_TYPE` provides that guarantee and the result of the `hasValue` method for the two objects being swapped is the same. The behavior is undefined unless this object was created with the same allocator as `other`.
| xref:bsl/optional-072/transform-09d.adoc[`transform`] 
| `transform` overloads
| xref:BloombergLP/bslstl/Optional_Base-05/value-07a.adoc[`value`] 
| `value` overloads
| xref:BloombergLP/bslstl/Optional_Base-05/value_or-07.adoc[`value_or`] 
| `value_or` overloads
| xref:BloombergLP/bslstl/Optional_Base-05/2conversion-076.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<Optional_Base, IsBitwiseCopyable, BloombergLP::bslmf::IsBitwiseCopyable<t_TYPE>::value>`] 
| Nested trait declaration for `bslmf::IsBitwiseCopyable`.
| xref:BloombergLP/bslstl/Optional_Base-05/2conversion-04.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<Optional_Base, IsBitwiseMoveable, BloombergLP::bslmf::IsBitwiseMoveable<t_TYPE>::value>`] 
| Nested trait declaration for `bslmf::IsBitwiseMoveable`.
| xref:BloombergLP/bslstl/Optional_Base-05/2conversion-0a.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<Optional_Base, UsesAllocatorArgT>`] 
| Nested trait declaration for `bslmf::UsesAllocatorArgT`.
| xref:BloombergLP/bslstl/Optional_Base-05/2conversion-0b.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<Optional_Base, UsesBslmaAllocator>`] 
| Nested trait declaration for `bslma::UsesBslmaAllocator`.
| xref:bsl/optional-072/2conversion-0af.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<optional, IsBitwiseCopyable, BloombergLP::bslmf::IsBitwiseCopyable<t_TYPE>::value>`] 
| Nested trait declaration for `bslmf::IsBitwiseCopyable`.
| xref:bsl/optional-072/2conversion-0a1.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<optional, IsBitwiseMoveable, BloombergLP::bslmf::IsBitwiseMoveable<t_TYPE>::value>`] 
| Nested trait declaration for `bslmf::IsBitwiseMoveable`.
| xref:bsl/optional-072/2conversion-0d.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<optional, UsesAllocatorArgT, BloombergLP::bslma::UsesBslmaAllocator<t_TYPE>::value>`] 
| Nested trait declaration for `bslmf::UsesAllocatorArgT`.
| xref:bsl/optional-072/2conversion-05.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<optional, UsesBslmaAllocator, BloombergLP::bslma::UsesBslmaAllocator<t_TYPE>::value>`] 
| Nested trait declaration for `bslma::UsesBslmaAllocator`.
| xref:BloombergLP/bslstl/Optional_Base-05/2conversion-071.adoc[`operator bool`] 
| Return `false` if this object is disengaged, and `true` otherwise.
|===


== Protected Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslstl/Optional_Base-05/AllocType.adoc[`AllocType`] 
| This `typedef` is an alias to `allocator_type`.
|===


== Protected Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslstl/Optional_Base-05/assignOrEmplace.adoc[`assignOrEmplace`] 
| If `*this` holds an object, assign to that object the value of the specified `rhs`, converted to `t_TYPE`. Otherwise, construct a held object from `rhs`, converted to `t_TYPE`. The allocators of `*this` and `rhs` remain unchanged.
| xref:BloombergLP/bslstl/Optional_Base-05/dereferenceRaw-049.adoc[`dereferenceRaw`] 
| `dereferenceRaw` overloads
|===


== Deduction Guides

[cols="1,4"]
|===
| Name| Description
| xref:bsl/optional-0d.adoc[`optional<t_TYPE>`] 
| Deduce the specified type `t_TYPE` from the corresponding type supplied to the constructor of `optional`.
| xref:bsl/optional-0b.adoc[`optional<t_TYPE>`] 
| Deduce the specified type `t_TYPE` from the corresponding type supplied to the constructor of `optional`. This guide does not participate in deduction unless the deduced type `t_TYPE` supports the bslma allocator model, and the specified `t_ALLOC` can be implicitly converted to `bsl::allocator<char>`.
| xref:bsl/optional-07d.adoc[`optional<t_TYPE>`] 
| Deduce the specified type `t_TYPE` from the corresponding template parameter type supplied to the constructor of `optional`. This guide does not participate in deduction unless the deduced type `t_TYPE` supports the bslma allocator model, and the specified `t_ALLOC` can be implicitly converted to `bsl::allocator<char>`.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `bsl::optional`
| 
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/PrintTo-0f.adoc[`PrintTo`]
| Write the specified `value` to the specified `*stream`, surrounded by double quotes.
| xref:bsl/make_optional-00.adoc[`make_optional`]
| Return an `optional` object containing a `TYPE` object created by invoking a `bsl::optional` `in_place_t` constructor with the specified `arg` and `args` as the constructor arguments. If `t_TYPE` uses an allocator, the default allocator will be used for the `optional` object. This function can be called in constant expressions only if `t_TYPE` is not allocator‐aware.
| xref:bsl/make_optional-01.adoc[`make_optional`]
| Return an `optional` object containing a value‐initialized `t_TYPE` object. If `t_TYPE` uses an allocator, the default allocator will be used for the `optional` object. This function can be called in constant expressions only if `t_TYPE` is not allocator‐aware.
| xref:bsl/make_optional-03.adoc[`make_optional`]
| Return an `optional` object containing a `t_TYPE` object created by invoking a `bsl::optional` `in_place_t` constructor with the specified `il` and `args` as the constructor arguments. If `t_TYPE` uses an allocator, the default allocator will be used for the `optional` object. This function can be called in constant expressions only if `t_TYPE` is not allocator‐aware.
| xref:bsl/make_optional-04.adoc[`make_optional`]
| Return an `optional` object containing a `t_TYPE` object created by invoking a `bsl::optional` allocator‐extended `in_place_t` constructor with the specified `alloc` as the allocator argument, and specified `rhs` as the constructor argument. Note that this function will fail to compile if `t_TYPE` doesn't use allocators.
| xref:bsl/make_optional-06.adoc[`make_optional`]
| Return an `optional` object containing a `t_TYPE` object created by invoking a `bsl::optional` allocator‐extended `in_place_t` constructor with the specified `alloc` as the allocator argument, and specified `il` and `args` as the constructor arguments. Note that this function will fail to compile if `t_TYPE` doesn't use allocators.
| xref:bsl/make_optional-0a.adoc[`make_optional`]
| Return an `optional` object containing a `t_TYPE` object created by invoking a `bsl::optional` constructor with the specified `rhs` as the constructor argument. If `t_TYPE` uses an allocator, the default allocator will be used for the `optional` object. This function can be called in constant expressions only if `t_TYPE` is not allocator‐aware.
| xref:bsl/make_optional-0e.adoc[`make_optional`]
| Return an `optional` object containing a `t_TYPE` object created by invoking a `bsl::optional` allocator‐extended `in_place_t` constructor with the specified `alloc` as the allocator argument, and specified `args` as constructor arguments. Note that this function will fail to compile if `t_TYPE` doesn't use allocators.
| xref:bsl/operator_not_eq-0c3.adoc[`operator!=`]
| Return `true` if the specified `lhs` and `rhs` `optional` objects do not have the same value, and `false` otherwise. Two `optional` objects do not have the same value if one is disengaged and the other is engaged, or if both are engaged and the values of their underlying objects do not compare equal. This function can be called in constant expressions only if neither `t_LHS_TYPE` nor `t_RHS_TYPE` is allocator‐aware.
| xref:bsl/operator_not_eq-0cf.adoc[`operator!=`]
| Return `true` if the specified `lhs` and `rhs` optional objects do not have the same value, and `false` otherwise. Two optional objects do not have the same value if one is disengaged and the other is engaged, or if both are engaged and the values of their underlying objects do not compare equal. Note that this function will fail to compile if `t_LHS_TYPE` and `t_RHS_TYPE` are not compatible. These functions can be called in constant expressions only if the `bsl::optional`'s value type is not allocator‐aware.
| xref:bsl/operator_not_eq-0e.adoc[`operator!=`]
| Return `true` if the specified `lhs` and `rhs` objects do not have the same value, and `false` otherwise. An `optional` object and a value of some type do not have the same value if either the optional object is disengaged, or its underlying value does not compare equal to the other value. These function can be called in constant expressions only if the `optional`'s value type is not allocator‐aware.
| xref:bsl/operator_lt-00.adoc[`operator<`]
| Return `true` if the specified `lhs` `optional` object is ordered before the specified `rhs`, and `false` otherwise. `lhs` is ordered before `rhs` if `lhs` is disengaged or `lhs.value()` is ordered before `rhs`. This function can be called in constant expressions only if `t_LHS_TYPE` is not allocator‐aware.
| xref:bsl/operator_lt-010.adoc[`operator<`]
| Return `true` if the specified `lhs` optional object is ordered before the specified `rhs` optional object, and `false` otherwise. `lhs` is ordered before `rhs` if `lhs` is disengaged and `rhs` is engaged or if both are engaged and `lhs.value()` is ordered before `rhs.value()`. Note that this function will fail to compile if `t_LHS_TYPE` and `t_RHS_TYPE` are not compatible. These functions can be called in constant expressions only if the `bsl::optional`'s value type is not allocator‐aware.
| xref:bsl/operator_lt-0b.adoc[`operator<`]
| Return `true` if the specified `lhs` `optional` object is ordered before the specified `rhs` `optional` object, and `false` otherwise. `lhs` is ordered before `rhs` if `lhs` is disengaged and `rhs` is engaged or if both are engaged and `lhs.value()` is ordered before `rhs.value()`. This function can be called in constant expressions only if neither `t_LHS_TYPE` nor `t_RHS_TYPE` is allocator‐aware.
| xref:bsl/operator_le-03.adoc[`operator<=`]
| Return `true` if the specified `lhs` `optional` object is ordered before the specified `rhs` or `lhs` and `rhs` have the same value, and `false` otherwise. (See `operator<` and `operator==`.) This function can be called in constant expressions only if `t_LHS_TYPE` is not allocator‐aware.
| xref:bsl/operator_le-04.adoc[`operator<=`]
| Return `true` if the specified `lhs` is ordered before the specified `rhs` optional object or `lhs` and `rhs` have the same value, and `false` otherwise. (See `operator<` and `operator==`.) Note that this function will fail to compile if `t_LHS_TYPE` and `t_RHS_TYPE` are not compatible. These functions can be called in constant expressions only if the `bsl::optional`'s value type is not allocator‐aware.
| xref:bsl/operator_le-0c.adoc[`operator<=`]
| Return `true` if the specified `lhs` `optional` object is ordered before the specified `rhs` `optional` object or if `lhs` and `rhs` have the same value, and `false` otherwise. (See `operator<` and `operator==`.) This function can be called in constant expressions only if neither `t_LHS_TYPE` nor `t_RHS_TYPE` is allocator‐aware.
| xref:bsl/operator_3way-00.adoc[`operator<=>`]
| Perform a three‐way comparison of the specified `lhs` and the specified `rhs` objects by using the comparison operators of `t_LHS` and `t_RHS`; return the result of that comparison. This function can be called in constant expressions only if neither `t_LHS` nor `t_RHS` is allocator‐aware.
| xref:bsl/operator_3way-070.adoc[`operator<=>`]
| Perform a three‐way comparison of the specified `lhs` and the specified `rhs` objects by using the comparison operators of `t_LHS` and `t_RHS`; return the result of that comparison. This function can be called in constant expressions only if `t_LHS` is not allocator‐aware.
| xref:bsl/operator_3way-0a.adoc[`operator<=>`]
| Perform a three‐way comparison of the specified `lhs` and the specified `rhs` objects by using the comparison operators of `t_LHS` and `t_RHS`; return the result of that comparison. This function can be called in constant expressions only if `t_LHS` is not allocator‐aware.
| xref:bsl/operator_3way-0d1.adoc[`operator<=>`]
| Perform a three‐way comparison of the specified `value` and `nullopt`; return the result of that comparison. This function can be called in constant expressions only if `t_TYPE` is not allocator‐aware.
| xref:bsl/operator_eq-02a.adoc[`operator==`]
| Return `true` if the specified `lhs` and `rhs` objects have the same value, and `false` otherwise. An `optional` object and a value of some type have the same value if the optional object is engaged and its underlying value compares equal to the other value. These functions can be called in constant expressions only if the `optional`'s value type is not allocator‐aware.
| xref:bsl/operator_eq-097.adoc[`operator==`]
| Return `true` if the specified `lhs` and `rhs` `optional` objects have the same value, and `false` otherwise. Two `optional` objects have the same value if both are disengaged, or if both are engaged and the values of their underlying objects compare equal. This function can be called in constant expressions only if neither `t_LHS_TYPE` nor `t_RHS_TYPE` is allocator‐aware.
| xref:bsl/operator_eq-09de.adoc[`operator==`]
| Compare a `std::optional` with a `bsl::optional` for equality.
| xref:bsl/operator_eq-0db.adoc[`operator==`]
| Return `true` if the specified `value` is disengaged, and `false` otherwise. This function can be called in constant expressions only if `t_TYPE` is not allocator‐aware.
| xref:bsl/operator_gt-04.adoc[`operator>`]
| Return `true` if the specified `lhs` `optional` object is ordered after the specified `rhs`, and `false` otherwise. `lhs` is ordered after `rhs` if `lhs` is engaged and `lhs.value()` is ordered after `rhs`. This function can be called in constant expressions only if `t_LHS_TYPE` is not allocator‐aware.
| xref:bsl/operator_gt-07.adoc[`operator>`]
| Return `true` if the specified `lhs` optional object is ordered after the specified `rhs` optional object, and `false` otherwise. `lhs` is ordered after `rhs` if `lhs` is engaged and `rhs` is disengaged or if both are engaged and `lhs.value()` is ordered after `rhs.value()`. Note that this function will fail to compile if `t_LHS_TYPE` and `t_RHS_TYPE` are not compatible. These functions can be called in constant expressions only if the `bsl::optional`'s value type is not allocator‐aware.
| xref:bsl/operator_gt-0bc.adoc[`operator>`]
| Return `true` if the specified `lhs` `optional` object is ordered after the specified `rhs` `optional` object, and `false` otherwise. `lhs` is ordered after `rhs` if `lhs` is engaged and `rhs` is disengaged or if both are engaged and `lhs.value()` is ordered after `rhs.value()`. This function can be called in constant expressions only if neither `t_LHS_TYPE` nor `t_RHS_TYPE` is allocator‐aware.
| xref:bsl/operator_ge-05.adoc[`operator>=`]
| Return `true` if the specified `lhs` `optional` object is ordered after the specified `rhs` `optional` object or if `lhs` and `rhs` have the same value, and `false` otherwise. (See `operator>` and `operator==`.) This function can be called in constant expressions only if neither `t_LHS_TYPE` nor `t_RHS_TYPE` is allocator‐aware.
| xref:bsl/operator_ge-06.adoc[`operator>=`]
| Return `true` if the specified `lhs` `optional` object is ordered after the specified `rhs` or if `lhs` and `rhs` have the same value, and `false` otherwise. (See `operator>` and `operator==`.) This function can be called in constant expressions only if `t_LHS_TYPE` is not allocator‐aware.
| xref:bsl/operator_ge-088.adoc[`operator>=`]
| Return `true` if the specified `lhs` optional object is ordered after the specified `rhs` optional object or `lhs` and `rhs` have the same value, and `false` otherwise. (See `operator>` and `operator==`.) Note that this function will fail to compile if `t_LHS_TYPE` and `t_RHS_TYPE` are not compatible. These functions can be called in constant expressions only if the `bsl::optional`'s value type is not allocator‐aware.
| xref:bsl/swap-00c.adoc[`swap`]
| Efficiently exchange the values of the specified `lhs` and `rhs` objects. This method provides the no‐throw exception‐safety guarantee if the template parameter `t_TYPE` provides that guarantee and the result of the `hasValue` method for `lhs` and `rhs` is the same. This function can be called in constant expressions only if `t_TYPE` is not allocator‐aware.
| xref:bsl/swap-04d.adoc[`swap`]
| Efficiently exchange the values of the specified `lhs` and `rhs` objects. This method provides the no‐throw exception‐safety guarantee if the template parameter `t_TYPE` provides that guarantee, `lhs` and `rhs` have equal allocators, and `lhs.hasValue() == rhs.hasValue()`.
| xref:bsl/swap-0f3.adoc[`swap`]
| Efficiently exchange the values of the specified `lhs` and `rhs` objects. This method provides the no‐throw exception‐safety guarantee if the template parameter `t_TYPE` provides that guarantee and the result of the `hasValue` method for `lhs` and `rhs` is the same.
| xref:BloombergLP/bdlb/nullableValue_acceptsBslOptional.adoc[`::BloombergLP::bdlb::nullableValue_acceptsBslOptional`]
| Component‐private constraint helper for `bsl::optional` conversion.
| xref:BloombergLP/bdlb/operator_not_eq-07b.adoc[`::BloombergLP::bdlb::operator!=`]
| Return `true` if the specified nullable objects do not have the same value.
| xref:BloombergLP/bdlb/operator_not_eq-0a1.adoc[`::BloombergLP::bdlb::operator!=`]
| Return `true` if the specified nullable objects do not have the same value.
| xref:BloombergLP/bdlb/operator_lt-07.adoc[`::BloombergLP::bdlb::operator<`]
| Return `true` if `lhs` is ordered before `rhs`, and `false` otherwise.
| xref:BloombergLP/bdlb/operator_lt-0b.adoc[`::BloombergLP::bdlb::operator<`]
| If neither of the specified `lhs` and `rhs` contain a value, return `false`. If `lhs` contains a value, and `rhs` does not, return `false`. If `lhs` does not contains a value, `rhs` does, return `true`. Otherwise, return `lhs.value < rhs.value()`.
| xref:BloombergLP/bdlb/operator_le-041.adoc[`::BloombergLP::bdlb::operator<=`]
| If neither of the specified `lhs` and `rhs` contain a value, return `true`. If `lhs` contains a value, and `rhs` does not, return `false`. If `lhs` does not contains a value, `rhs` does, return `true`. Otherwise, return `lhs.value <= rhs.value()`.
| xref:BloombergLP/bdlb/operator_le-06b.adoc[`::BloombergLP::bdlb::operator<=`]
| Return `true` if `lhs` is ordered before `rhs` or they are equal.
| xref:BloombergLP/bdlb/operator_eq-047.adoc[`::BloombergLP::bdlb::operator==`]
| Return `true` if the specified nullable objects have the same value.
| xref:BloombergLP/bdlb/operator_eq-052.adoc[`::BloombergLP::bdlb::operator==`]
| Return `true` if the specified nullable objects have the same value, and `false` otherwise.
| xref:BloombergLP/bdlb/operator_gt-00.adoc[`::BloombergLP::bdlb::operator>`]
| Return `true` if `lhs` is ordered after `rhs`, and `false` otherwise.
| xref:BloombergLP/bdlb/operator_gt-04b.adoc[`::BloombergLP::bdlb::operator>`]
| If neither of the specified `lhs` and `rhs` contain a value, return `false`. If `lhs` contains a value, and `rhs` does not, return `true`. If `lhs` does not contains a value, `rhs` does, return `false`. Otherwise, return `lhs.value > rhs.value()`.
| xref:BloombergLP/bdlb/operator_ge-01d1.adoc[`::BloombergLP::bdlb::operator>=`]
| If neither of the specified `lhs` and `rhs` contain a value, return `true`. If `lhs` contains a value, and `rhs` does not, return `true`. If `lhs` does not contains a value, `rhs` does, return `false`. Otherwise, return `lhs.value >= rhs.value()`.
| xref:BloombergLP/bdlb/operator_ge-087.adoc[`::BloombergLP::bdlb::operator>=`]
| Return `true` if `lhs` is ordered after `rhs` or they are equal.
| xref:BloombergLP/bslstl/optional_acceptsBslOptional.adoc[`::BloombergLP::bslstl::optional_acceptsBslOptional`]
| Component‐private constraint helper for `Optional_DerivedFromBslOptional`.
|===

== Derived Classes

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlb/NullableValue.adoc[`NullableValue`] 
| This template class extends the set of values of its value‐semantic `TYPE` parameter to include the notion of a "null" value. If `TYPE` is fully value‐semantic, then the augmented type `NullableValue<TYPE>` will be as well. In addition to supporting all homogeneous value‐semantic operations, conversions between comparable underlying value types is also supported. Two nullable objects with different underlying types compare equal if their underlying types are comparable and either (1) both objects are null or (2) the non‐null values compare equal. A null nullable object is considered ordered before any non‐null nullable object. Attempts to copy construct, copy assign, or compare incompatible values types will fail to compile. The `NullableValue` template cannot be instantiated on an incomplete type, a type that overloads unary `operator&`, or `bsl::nullopt_t`.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#