[#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&hyphen;semantic `TYPE` parameter to include the notion of a &quot;null&quot; value&period; If `TYPE` is fully value&hyphen;semantic, then the augmented type `NullableAllocatedValue&lt;TYPE&gt;` will be as well&period; In addition to supporting all homogeneous value&hyphen;semantic operations, conversions between comparable underlying value types is also supported&period; 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&hyphen;null values compare equal&period; Attempts to copy construct, copy assign, or compare incompatible values types will fail to compile&period; The `NullableAllocatedValue` template can be instantiated on an incomplete type, but it cannot be instantiated on a type that overloads `operator&amp;`&period;

== Synopsis

Declared in `&lt;bdlb&lowbar;nullableallocatedvalue&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;class TYPE&gt;
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&period;
|===


== Member Functions

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


== Non-Member Functions

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


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