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

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 `NullableAllocatedValue<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. Attempts to copy construct, copy assign, or compare incompatible values types will fail to compile. The `NullableAllocatedValue` template can be instantiated on an incomplete type, but it cannot be instantiated on a type that overloads `operator&`.

== Synopsis

Declared in `<bdlb_nullableallocatedvalue.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<class TYPE>
class NullableAllocatedValue;
----

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlb/NullableAllocatedValue/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.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlb/NullableAllocatedValue/2constructor-0bd.adoc[`NullableAllocatedValue`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bdlb/NullableAllocatedValue/2destructor.adoc[`~NullableAllocatedValue`] [.small]#[destructor]#
| Destroy this object.
| xref:BloombergLP/bdlb/NullableAllocatedValue/operator_assign-0b.adoc[`operator=`] 
| Assignment operators
| xref:BloombergLP/bdlb/NullableAllocatedValue/addressOr.adoc[`addressOr`] 
| Return an address providing non‐modifiable access to the underlying object of a (template parameter) `TYPE` if this object is non‐null, and the specified `address` otherwise.
| xref:BloombergLP/bdlb/NullableAllocatedValue/allocator.adoc[`allocator`] 
| Return the allocator used by this object to supply memory.
| xref:BloombergLP/bdlb/NullableAllocatedValue/bdexStreamIn.adoc[`bdexStreamIn`] 
| Assign to this object the value read from the specified input `stream` using the specified `version` format, and return a reference to `stream`. If `stream` is initially invalid, this operation has no effect. If `version` is not supported, this object is unaltered and `stream` is invalidated, but otherwise unmodified. If `version` is supported but `stream` becomes invalid during this operation, this object has an undefined, but valid, state. Note that no version is read from `stream`. See the `bslx` package‐level documentation for more information on BDEX streaming of value‐semantic types and containers.
| xref:BloombergLP/bdlb/NullableAllocatedValue/bdexStreamOut.adoc[`bdexStreamOut`] 
| Write the value of this object, using the specified `version` format, to the specified output `stream`, and return a reference to `stream`. If `stream` is initially invalid, this operation has no effect. If `version` is not supported, `stream` is invalidated, but otherwise unmodified. Note that `version` is not written to `stream`. See the `bslx` package‐level documentation for more information on BDEX streaming of value‐semantic types and containers.
| xref:BloombergLP/bdlb/NullableAllocatedValue/emplace-01.adoc[`emplace`] 
| `emplace` overloads
| xref:BloombergLP/bdlb/NullableAllocatedValue/get_allocator.adoc[`get_allocator`] 
| Return a `bsl::allocator` constructed from the `bslma::Allocator` used by this object to supply memory. Note that if no allocator was supplied at construction the default allocator in effect at construction is used.
| xref:BloombergLP/bdlb/NullableAllocatedValue/has_value.adoc[`has_value`] 
| Return `true` if this object contains a value, and `false` otherwise.
| xref:BloombergLP/bdlb/NullableAllocatedValue/isNull.adoc[`isNull`] 
| Return `false` if this object contains a value, and `true` otherwise. Note that this is the opposite of `has_value`.
| xref:BloombergLP/bdlb/NullableAllocatedValue/makeValue-08.adoc[`makeValue`] 
| `makeValue` overloads
| xref:BloombergLP/bdlb/NullableAllocatedValue/makeValueInplace.adoc[`makeValueInplace`] 
| Assign to this nullable object the value of the (template parameter) `TYPE` created in place using the specified `args`. Return a reference providing modifiable access to the created (value) object. The object is also accessible via the `value` method. If this nullable object already contains an object (`false == isNull()`), that object is destroyed before the new object is created. If `TYPE` has the trait `bslma::UsesBslmaAllocator` (`TYPE` is allocator‐enabled) the allocator specified at the construction of this nullable object is used to supply memory to the value object. Attempts to explicitly specify via `args` another allocator to supply memory to the created (value) object are disallowed by the compiler. Note that if the constructor of `TYPE` throws an exception this object is left in the null state.
| xref:BloombergLP/bdlb/NullableAllocatedValue/maxSupportedBdexVersion-03.adoc[`maxSupportedBdexVersion`] 
| `maxSupportedBdexVersion` overloads
| xref:BloombergLP/bdlb/NullableAllocatedValue/operator_star-0d.adoc[`operator*`] 
| Dereference operators
| xref:BloombergLP/bdlb/NullableAllocatedValue/operator_ptr-0f.adoc[`operator‐>`] 
| Member access operators
| xref:BloombergLP/bdlb/NullableAllocatedValue/print.adoc[`print`] 
| Format this object to the specified output `stream` at the (absolute value of) the optionally specified indentation `level` and return a reference to `stream`. If `level` is specified, optionally specify `spacesPerLevel`, the number of spaces per indentation level for this and all of its nested objects. If `level` is negative, suppress indentation of the first line. If `spacesPerLevel` is negative, format the entire output on one line, suppressing all but the initial indentation (as governed by `level`). If `stream` is not valid on entry, this operation has no effect.
| xref:BloombergLP/bdlb/NullableAllocatedValue/reset.adoc[`reset`] 
| Reset this object to the default constructed state (i.e., to have the null value).
| xref:BloombergLP/bdlb/NullableAllocatedValue/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. The behavior is undefined unless this object was created with the same allocator as `other`.
| xref:BloombergLP/bdlb/NullableAllocatedValue/value-00.adoc[`value`] 
| `value` overloads
| xref:BloombergLP/bdlb/NullableAllocatedValue/valueOr.adoc[`valueOr`] 
| Return the value of the underlying object of a (template parameter) `TYPE` if this object is non‐null, and the specified `otherValue` otherwise. Note that this method returns _by_ _value_, so may be inefficient in some contexts.
| xref:BloombergLP/bdlb/NullableAllocatedValue/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/bdlb/NullableAllocatedValue/value_or.adoc[`value_or`] 
| Return the value of the underlying object of a (template parameter) `TYPE` if this object is non‐null, and the specified `default_value` otherwise. Note that this method returns _by_ _value_, so may be inefficient in some contexts.
| xref:BloombergLP/bdlb/NullableAllocatedValue/2conversion-06.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<NullableAllocatedValue, HasPrintMethod>`] 
| Declare that `NullableAllocatedValue` provides a `print` method.
| xref:BloombergLP/bdlb/NullableAllocatedValue/2conversion-07.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<NullableAllocatedValue, IsBitwiseMoveable>`] 
| Declare `NullableAllocatedValue` as bitwise moveable when `TYPE` is.
| xref:BloombergLP/bdlb/NullableAllocatedValue/2conversion-0e.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<NullableAllocatedValue, UsesBslmaAllocator>`] 
| Declare that `NullableAllocatedValue` uses a `bslma` allocator.
| xref:BloombergLP/bdlb/NullableAllocatedValue/2conversion-02.adoc[`operator bool`] 
| Return `true` if this object is contains a value, and `true` otherwise.
|===


== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlb/operator_not_eq-005.adoc[`operator!=`]
| Return `true` if the specified `lhs` and `rhs` objects do not have the same value, and `false` otherwise. A nullable object and a value of some type do not have the same value if either the nullable object is null, or its underlying value does not compare equal to the other value. Note that this function will fail to compile if `LHS_TYPE` and `RHS_TYPE` are not compatible.
| xref:BloombergLP/bdlb/operator_not_eq-011.adoc[`operator!=`]
| Return `true` if the specified `lhs` and `rhs` nullable objects do not have the same value, and `false` otherwise. Two nullable objects do not have the same value if one is null and the other is non‐null, or if both are non‐null and the values of their underlying objects do not compare equal. Note that this function will fail to compile if `LHS_TYPE` and `RHS_TYPE` are not compatible.
| xref:BloombergLP/bdlb/operator_not_eq-052.adoc[`operator!=`]
| Return `true` if the specified `lhs` is not null, and `false` otherwise.
| xref:BloombergLP/bdlb/operator_not_eq-0f.adoc[`operator!=`]
| If neither of the specified `lhs` and `rhs` contain a value, return `false`. If one contains a value, and the other does not, return `true`. Otherwise, return `lhs.value != rhs.value()`.
| xref:BloombergLP/bdlb/operator_lt-015.adoc[`operator<`]
| Return `false`. Note that `bsl::nullopt` never orders after a `NullableAllocatedValue`.
| xref:BloombergLP/bdlb/operator_lt-02d.adoc[`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_lt-057.adoc[`operator<`]
| Return `true` if the specified `lhs` nullable object is ordered before the specified `rhs`, and `false` otherwise. `lhs` is ordered before `rhs` if `lhs` is null or `lhs.value()` is ordered before `rhs`.
| xref:BloombergLP/bdlb/operator_lt-094.adoc[`operator<`]
| Return `true` if the specified `lhs` nullable object is ordered before the specified `rhs` nullable object, and `false` otherwise. `lhs` is ordered before `rhs` if `lhs` is null and `rhs` is non‐null or if both are non‐null and `lhs.value()` is ordered before `rhs.value()`. Note that this function will fail to compile if `LHS_TYPE` and `RHS_TYPE` are not compatible.
| xref:BloombergLP/bdlb/operator_le-00.adoc[`operator<=`]
| Return `true` if the specified `lhs` is null, and `false` otherwise.
| xref:BloombergLP/bdlb/operator_le-081.adoc[`operator<=`]
| Return `true` if the specified `lhs` nullable object is ordered before the specified `rhs` nullable object or `lhs` and `rhs` have the same value, and `false` otherwise. (See `operator<` and `operator==`.) Note that this operator returns `!(rhs < lhs)` when both operands are of `NullableValue` type. Also note that this function will fail to compile if `LHS_TYPE` and `RHS_TYPE` are not compatible.
| xref:BloombergLP/bdlb/operator_le-08f.adoc[`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-0c1.adoc[`operator<=`]
| Return `true` if the specified `lhs` nullable object is ordered before the specified `rhs` or `lhs` and `rhs` have the same value, and `false` otherwise. (See `operator<` and `operator==`.) Note that this operator returns `!(rhs < lhs)`.
| xref:BloombergLP/bdlb/operator_eq-03c1.adoc[`operator==`]
| If neither of the specified `lhs` and `rhs` contain a value, return `true`. If one contains a value, and the other does not, return `false`. Otherwise, return `lhs.value == rhs.value()`.
| xref:BloombergLP/bdlb/operator_eq-056.adoc[`operator==`]
| Return `true` if the specified `lhs` is null, and `false` otherwise.
| xref:BloombergLP/bdlb/operator_eq-078.adoc[`operator==`]
| Return `true` if the specified `lhs` and `rhs` objects have the same value, and `false` otherwise. A nullable object and a value of some type have the same value if the nullable object is non‐null and its underlying value compares equal to the other value. Note that this function will fail to compile if `LHS_TYPE` and `RHS_TYPE` are not compatible.
| xref:BloombergLP/bdlb/operator_eq-0c3.adoc[`operator==`]
| Return `true` if the specified `lhs` and `rhs` nullable objects have the same value, and `false` otherwise. Two nullable objects have the same value if both are null, or if both are non‐null and the values of their underlying objects compare equal. Note that this function will fail to compile if `LHS_TYPE` and `RHS_TYPE` are not compatible.
| xref:BloombergLP/bdlb/operator_gt-051.adoc[`operator>`]
| Return `true` if the specified `lhs` nullable object is ordered after the specified `rhs`, and `false` otherwise. `lhs` is ordered after `rhs` if `lhs` is not null and `lhs.value()` is ordered after `rhs`. Note that this operator returns `rhs < lhs`.
| xref:BloombergLP/bdlb/operator_gt-054.adoc[`operator>`]
| Return `true` if the specified `lhs` nullable object is ordered after the specified `rhs` nullable object, and `false` otherwise. `lhs` is ordered after `rhs` if `lhs` is non‐null and `rhs` is null or if both are non‐null and `lhs.value()` is ordered after `rhs.value()`. Note that this operator returns `rhs < lhs` when both operands are of `NullableValue` type. Also note that this function will fail to compile if `LHS_TYPE` and `RHS_TYPE` are not compatible.
| xref:BloombergLP/bdlb/operator_gt-07b.adoc[`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_gt-07e.adoc[`operator>`]
| Return `true` if the specified `lhs` is not null, and `false` otherwise.
| xref:BloombergLP/bdlb/operator_ge-003.adoc[`operator>=`]
| Return `true`.
| xref:BloombergLP/bdlb/operator_ge-04.adoc[`operator>=`]
| Return `true` if the specified `lhs` nullable object is ordered after the specified `rhs` nullable object or `lhs` and `rhs` have the same value, and `false` otherwise. (See `operator>` and `operator==`.) Note that this operator returns `!(lhs < rhs)` when both operands are of `NullableValue` type. Also note that this function will fail to compile if `LHS_TYPE` and `RHS_TYPE` are not compatible.
| xref:BloombergLP/bdlb/operator_ge-060.adoc[`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-0cf2.adoc[`operator>=`]
| Return `true` if the specified `lhs` nullable object is ordered after the specified `rhs` or `lhs` and `rhs` have the same value, and `false` otherwise. (See `operator>` and `operator==`.) Note that this operator returns `!(lhs < rhs)`.
| xref:BloombergLP/bdlb/swap-07.adoc[`swap`]
| Exchange the values of the specified `a` and `b` objects. This function provides the no‐throw exception‐safety guarantee if the two objects were created with the same allocator and the basic guarantee otherwise.
| xref:BloombergLP/bdlat_NullableValueFunctions/bdlat_nullableValueAccessValue-00.adoc[`::BloombergLP::bdlat_NullableValueFunctions::bdlat_nullableValueAccessValue`]
| Default customization‐point implementation of `accessValue` for `bdlb::NullableAllocatedValue`.
| xref:BloombergLP/bdlat_NullableValueFunctions/bdlat_nullableValueIsNull-06.adoc[`::BloombergLP::bdlat_NullableValueFunctions::bdlat_nullableValueIsNull`]
| Default customization‐point implementation of `isNull` for `bdlb::NullableAllocatedValue`.
| xref:BloombergLP/bdlat_NullableValueFunctions/bdlat_nullableValueMakeValue-05.adoc[`::BloombergLP::bdlat_NullableValueFunctions::bdlat_nullableValueMakeValue`]
| Default customization‐point implementation of `makeValue` for `bdlb::NullableAllocatedValue`.
| xref:BloombergLP/bdlat_NullableValueFunctions/bdlat_nullableValueManipulateValue-04f.adoc[`::BloombergLP::bdlat_NullableValueFunctions::bdlat_nullableValueManipulateValue`]
| Default customization‐point implementation of `manipulateValue` for `bdlb::NullableAllocatedValue`.
|===


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