[#BloombergLP-bdlb-NullableValue]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlb.adoc[bdlb]::NullableValue
:relfileprefix: ../../
:mrdocs:

Value‐semantic wrapper that adds a null state to `TYPE`.

== Synopsis

Declared in `<bdlb_nullablevalue.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<class TYPE>
class NullableValue
    : public xref:bsl/optional-072.adoc[bsl::optional<TYPE>]
----

== Description

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`.

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `xref:bsl/optional-072.adoc[bsl::optional<TYPE>]`
| Allocator‐aware nullable wrapper for an object of type `t_TYPE`.
|===

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlb/NullableValue/Base.adoc[`Base`] 
| Base class of this type.
| xref:BloombergLP/bdlb/NullableValue/ValueType.adoc[`ValueType`] 
| `ValueType` is an alias for the underlying `TYPE` upon which this template class is instantiated, and represents the type of the managed object.
| xref:BloombergLP/bdlb/NullableValue/allocator_type.adoc[`allocator_type`] 
| Allocator type used by this object.
| xref:BloombergLP/bslstl/Optional_Base-05/value_type.adoc[`value_type`] 
| Alias for the managed object type of this optional.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlb/NullableValue/2constructor-093.adoc[`NullableValue`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bdlb/NullableValue/operator_assign-087.adoc[`operator=`] 
| Assignment operators
| xref:BloombergLP/bdlb/NullableValue/addressOr.adoc[`addressOr`] 
| Return the address of the contained object, or `address` if null.
| xref:bsl/optional-072/and_then-08d.adoc[`and_then`] 
| `and_then` overloads
| xref:BloombergLP/bdlb/NullableValue/bdexStreamIn.adoc[`bdexStreamIn`] 
| Assign to this object the value read from the specified `stream`.
| xref:BloombergLP/bdlb/NullableValue/bdexStreamOut.adoc[`bdexStreamOut`] 
| Write this object to the specified output `stream`.
| xref:BloombergLP/bslstl/Optional_Base-05/emplace-02.adoc[`emplace`] 
| Destroy any contained value and construct a new one in place.
| 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/bdlb/NullableValue/isNull.adoc[`isNull`] 
| Return `true` if this object is null, and `false` otherwise.
| xref:BloombergLP/bdlb/NullableValue/makeValue-0b.adoc[`makeValue`] 
| `makeValue` overloads
| xref:BloombergLP/bdlb/NullableValue/makeValueInplace.adoc[`makeValueInplace`] 
| Construct a `TYPE` object in place from the specified `args`.
| xref:BloombergLP/bdlb/NullableValue/maxSupportedBdexVersion-0c.adoc[`maxSupportedBdexVersion`] 
| `maxSupportedBdexVersion` overloads
| 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`] 
| Return this optional if engaged; otherwise invoke `func`.
| xref:BloombergLP/bdlb/NullableValue/print.adoc[`print`] 
| Format this object to the specified output `stream`.
| 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`] 
| Exchange the values of two optionals.
| xref:bsl/optional-072/transform-09d.adoc[`transform`] 
| `transform` overloads
| xref:BloombergLP/bdlb/NullableValue/value-03.adoc[`value`] 
| `value` overloads
| xref:BloombergLP/bdlb/NullableValue/valueOr-03.adoc[`valueOr`] 
| `valueOr` overloads
| xref:BloombergLP/bdlb/NullableValue/valueOrNull.adoc[`valueOrNull`] 
| Return an address providing non‐modifiable access to the underlying object of a (template parameter) `TYPE` if this object is non‐null, and 0 otherwise.
| xref:BloombergLP/bslstl/Optional_Base-05/value_or-07.adoc[`value_or`] 
| Return the contained value, or a converted fallback if disengaged.
| xref:BloombergLP/bdlb/NullableValue/2conversion-00.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<NullableValue, HasPrintMethod>`] 
| `NullableValue` always provides a `print` method.
| xref:BloombergLP/bdlb/NullableValue/2conversion-03.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<NullableValue, IsBitwiseCopyable, bslmf::IsBitwiseCopyable<TYPE>::value>`] 
| `NullableValue` is bitwise copyable when `TYPE` is bitwise copyable.
| xref:BloombergLP/bdlb/NullableValue/2conversion-09.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<NullableValue, IsBitwiseMoveable, bslmf::IsBitwiseMoveable<TYPE>::value>`] 
| `NullableValue` is bitwise moveable when `TYPE` is bitwise moveable.
| xref:BloombergLP/bdlb/NullableValue/2conversion-07.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<NullableValue, UsesBslmaAllocator, bslma::UsesBslmaAllocator<TYPE>::value>`] 
| `NullableValue` uses a `bslma::Allocator` when `TYPE` does.
| 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`] 
| Assign or emplace a value into this optional.
| xref:BloombergLP/bslstl/Optional_Base-05/dereferenceRaw-049.adoc[`dereferenceRaw`] 
| Return a reference to the contained value without checking engagement.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `BloombergLP::bdlb::NullableValue`
| Value‐semantic wrapper that adds a null state to `TYPE`.
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlb/nullableValue_acceptsBslOptional.adoc[`nullableValue_acceptsBslOptional`]
| Component‐private constraint helper for `bsl::optional` conversion.
| xref:BloombergLP/bdlb/operator_not_eq-03.adoc[`operator!=`]
| Return `true` if the specified nullable objects do not have the same value.
| xref:BloombergLP/bdlb/operator_not_eq-044.adoc[`operator!=`]
| Return whether the specified `lhs` and `rhs` do not have the same value.
| xref:BloombergLP/bdlb/operator_not_eq-0476.adoc[`operator!=`]
| Return `true` if the specified nullable object and `std::optional` do not have the same value.
| xref:BloombergLP/bdlb/operator_not_eq-060.adoc[`operator!=`]
| Return whether the specified `lhs` and `rhs` do not have the same value.
| xref:BloombergLP/bdlb/operator_not_eq-07b.adoc[`operator!=`]
| Return `true` if the specified nullable objects do not have the same value.
| xref:BloombergLP/bdlb/operator_not_eq-0a1.adoc[`operator!=`]
| Return `true` if the specified nullable objects do not have the same value.
| xref:BloombergLP/bdlb/operator_lt-00.adoc[`operator<`]
| Return whether the specified `lhs` is ordered before the specified `rhs`.
| xref:BloombergLP/bdlb/operator_lt-032.adoc[`operator<`]
| Return `true` if `lhs` is ordered before `rhs`, and `false` otherwise.
| xref:BloombergLP/bdlb/operator_lt-07.adoc[`operator<`]
| Return `true` if `lhs` is ordered before `rhs`, and `false` otherwise.
| xref:BloombergLP/bdlb/operator_lt-0a0.adoc[`operator<`]
| Return `true` if `lhs` is ordered before `rhs`, and `false` otherwise.
| xref:BloombergLP/bdlb/operator_lt-0a1.adoc[`operator<`]
| Return whether the specified `lhs` is ordered before the specified `rhs`.
| xref:BloombergLP/bdlb/operator_lt-0b.adoc[`operator<`]
| Return whether the left‐hand operand is ordered before the right.
| xref:BloombergLP/bdlb/operator_le-023.adoc[`operator<=`]
| Return whether the specified `lhs` is ordered before or equal to `rhs`.
| xref:BloombergLP/bdlb/operator_le-041.adoc[`operator<=`]
| Return whether the left‐hand operand is before or equal to the right.
| xref:BloombergLP/bdlb/operator_le-047.adoc[`operator<=`]
| Return `true` if `lhs` is ordered before `rhs` or they are equal.
| xref:BloombergLP/bdlb/operator_le-06b.adoc[`operator<=`]
| Return `true` if `lhs` is ordered before `rhs` or they are equal.
| xref:BloombergLP/bdlb/operator_le-086.adoc[`operator<=`]
| Return `true` if `lhs` is ordered before `rhs` or they are equal.
| xref:BloombergLP/bdlb/operator_le-08e.adoc[`operator<=`]
| Return whether the specified `lhs` is ordered before or equal to `rhs`.
| xref:BloombergLP/bdlb/operator_3way-03.adoc[`operator<=>`]
| Return a three‐way comparison of the specified `lhs` and `rhs`.
| xref:BloombergLP/bdlb/operator_3way-04.adoc[`operator<=>`]
| Perform a three‐way comparison of the specified nullable objects.
| xref:BloombergLP/bdlb/operator_3way-07.adoc[`operator<=>`]
| Perform a three‐way comparison of the specified `value` and one of type `bsl::nullopt_t`; return the result of that comparison.
| xref:BloombergLP/bdlb/operator_3way-0a.adoc[`operator<=>`]
| Perform a three‐way comparison of the specified nullable objects.
| xref:BloombergLP/bdlb/operator_3way-0b.adoc[`operator<=>`]
| Perform a three‐way comparison of the specified nullable object and value.
| xref:BloombergLP/bdlb/operator_eq-0108.adoc[`operator==`]
| Return `true` if the specified `value` is null, and `false` otherwise.
| xref:BloombergLP/bdlb/operator_eq-047.adoc[`operator==`]
| Return `true` if the specified nullable objects have the same value.
| xref:BloombergLP/bdlb/operator_eq-052.adoc[`operator==`]
| Return `true` if the specified nullable objects have the same value, and `false` otherwise.
| xref:BloombergLP/bdlb/operator_eq-070.adoc[`operator==`]
| Return `true` if the specified nullable objects have the same value.
| xref:BloombergLP/bdlb/operator_eq-0aa.adoc[`operator==`]
| Return whether the specified `lhs` and `rhs` have the same value.
| xref:BloombergLP/bdlb/operator_eq-0da.adoc[`operator==`]
| Return whether the specified `lhs` and `rhs` have the same value.
| xref:BloombergLP/bdlb/operator_eq-0f6c.adoc[`operator==`]
| Return `true` if the specified nullable objects have the same value, and `false` otherwise.
| xref:BloombergLP/bdlb/operator_gt-00.adoc[`operator>`]
| Return `true` if `lhs` is ordered after `rhs`, and `false` otherwise.
| xref:BloombergLP/bdlb/operator_gt-013.adoc[`operator>`]
| Return `true` if `lhs` is ordered after `rhs`, and `false` otherwise.
| xref:BloombergLP/bdlb/operator_gt-03.adoc[`operator>`]
| Return `true` if `lhs` is ordered after `rhs`, and `false` otherwise.
| xref:BloombergLP/bdlb/operator_gt-04b.adoc[`operator>`]
| Return whether the left‐hand operand is ordered after the right.
| xref:BloombergLP/bdlb/operator_gt-075.adoc[`operator>`]
| Return whether the specified `lhs` is ordered after the specified `rhs`.
| xref:BloombergLP/bdlb/operator_gt-0da.adoc[`operator>`]
| Return whether the specified `lhs` is ordered after the specified `rhs`.
| xref:BloombergLP/bdlb/operator_ge-01d1.adoc[`operator>=`]
| Return whether the left‐hand operand is after or equal to the right.
| xref:BloombergLP/bdlb/operator_ge-058.adoc[`operator>=`]
| Return whether the specified `lhs` is ordered after or equal to `rhs`.
| xref:BloombergLP/bdlb/operator_ge-07.adoc[`operator>=`]
| Return whether the specified `lhs` is ordered after or equal to `rhs`.
| xref:BloombergLP/bdlb/operator_ge-082.adoc[`operator>=`]
| Return `true` if `lhs` is ordered after `rhs` or they are equal.
| xref:BloombergLP/bdlb/operator_ge-087.adoc[`operator>=`]
| Return `true` if `lhs` is ordered after `rhs` or they are equal.
| xref:BloombergLP/bdlb/operator_ge-0d.adoc[`operator>=`]
| Return `true` if `lhs` is ordered after `rhs` or they are equal.
| xref:BloombergLP/bdlb/swap-02.adoc[`swap`]
| Exchange the values of the specified `lhs` and `rhs` objects when `TYPE` does not use a `bslma::Allocator`.
| xref:BloombergLP/bdlb/swap-03.adoc[`swap`]
| Exchange the values of the specified `lhs` and `rhs` objects.
| xref:bsl/PrintTo-0f.adoc[`::bsl::PrintTo`]
| Write the specified `value` to the specified `*stream`, surrounded by double quotes.
| xref:bsl/operator_not_eq-0c3.adoc[`::bsl::operator!=`]
| Return whether the operands do not have the same value.
| xref:bsl/operator_not_eq-0cf.adoc[`::bsl::operator!=`]
| Return whether the operands do not have the same value.
| xref:bsl/operator_not_eq-0e.adoc[`::bsl::operator!=`]
| Return whether the operands do not have the same value.
| xref:bsl/operator_lt-00.adoc[`::bsl::operator<`]
| Return whether the left‐hand operand is ordered before the right.
| xref:bsl/operator_lt-010.adoc[`::bsl::operator<`]
| Return whether the left‐hand operand is ordered before the right.
| xref:bsl/operator_lt-0b.adoc[`::bsl::operator<`]
| Return whether the left‐hand operand is ordered before the right.
| xref:bsl/operator_le-03.adoc[`::bsl::operator<=`]
| Return whether the left‐hand operand is before or equal to the right.
| xref:bsl/operator_le-04.adoc[`::bsl::operator<=`]
| Return whether the left‐hand operand is before or equal to the right.
| xref:bsl/operator_le-0c.adoc[`::bsl::operator<=`]
| Return whether the left‐hand operand is before or equal to the right.
| xref:bsl/operator_3way-00.adoc[`::bsl::operator<=>`]
| Perform a three‐way comparison of the operands.
| xref:bsl/operator_3way-070.adoc[`::bsl::operator<=>`]
| Perform a three‐way comparison of the operands.
| xref:bsl/operator_3way-0a.adoc[`::bsl::operator<=>`]
| Perform a three‐way comparison of the operands.
| xref:bsl/operator_3way-0d1.adoc[`::bsl::operator<=>`]
| Perform a three‐way comparison of the operands.
| xref:bsl/operator_eq-02a.adoc[`::bsl::operator==`]
| Return whether the operands have the same value.
| xref:bsl/operator_eq-097.adoc[`::bsl::operator==`]
| Return whether the operands have the same value.
| xref:bsl/operator_eq-09de.adoc[`::bsl::operator==`]
| Compare a `std::optional` with a `bsl::optional` for equality.
| xref:bsl/operator_eq-0db.adoc[`::bsl::operator==`]
| Return whether the operands have the same value.
| xref:bsl/operator_gt-04.adoc[`::bsl::operator>`]
| Return whether the left‐hand operand is ordered after the right.
| xref:bsl/operator_gt-07.adoc[`::bsl::operator>`]
| Return whether the left‐hand operand is ordered after the right.
| xref:bsl/operator_gt-0bc.adoc[`::bsl::operator>`]
| Return whether the left‐hand operand is ordered after the right.
| xref:bsl/operator_ge-05.adoc[`::bsl::operator>=`]
| Return whether the left‐hand operand is after or equal to the right.
| xref:bsl/operator_ge-06.adoc[`::bsl::operator>=`]
| Return whether the left‐hand operand is after or equal to the right.
| xref:bsl/operator_ge-088.adoc[`::bsl::operator>=`]
| Return whether the left‐hand operand is after or equal to the right.
| xref:bsl/swap-00c.adoc[`::bsl::swap`]
| Exchange the values of two optionals.
| xref:bsl/swap-04d.adoc[`::bsl::swap`]
| Exchange the values of two optionals.
| xref:bsl/swap-0f3.adoc[`::bsl::swap`]
| Exchange the values of two optionals.
| xref:BloombergLP/bdlat_NullableValueFunctions/bdlat_nullableValueAccessValue-0c3.adoc[`::BloombergLP::bdlat_NullableValueFunctions::bdlat_nullableValueAccessValue`]
| Default customization‐point implementation of `accessValue` for `bdlb::NullableValue`.
| xref:BloombergLP/bdlat_NullableValueFunctions/bdlat_nullableValueIsNull-05.adoc[`::BloombergLP::bdlat_NullableValueFunctions::bdlat_nullableValueIsNull`]
| Return whether the specified nullable `object` is null.
| xref:BloombergLP/bdlat_NullableValueFunctions/bdlat_nullableValueMakeValue-0b.adoc[`::BloombergLP::bdlat_NullableValueFunctions::bdlat_nullableValueMakeValue`]
| Default customization‐point implementation of `makeValue` for `bdlb::NullableValue`.
| xref:BloombergLP/bdlat_NullableValueFunctions/bdlat_nullableValueManipulateValue-041.adoc[`::BloombergLP::bdlat_NullableValueFunctions::bdlat_nullableValueManipulateValue`]
| Default customization‐point implementation of `manipulateValue` for `bdlb::NullableValue`.
| xref:BloombergLP/bslstl/optional_acceptsBslOptional.adoc[`::BloombergLP::bslstl::optional_acceptsBslOptional`]
| Component‐private constraint helper for `Optional_DerivedFromBslOptional`.
|===


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