Outline
Purpose
Tech preview for non-owning reference to nullable objects.
Classes
- NullableValueRef: template for modifiable reference to nullable object
- ConstNullableValueRef: template for const reference to nullable object
- See also
- NullableAllocatedValue, bsl::optional, NullableValue
Description
This component is a technology preview and subject to change. It is provided for evaluation purposes only and should not be used in a production setting. It provides two template classes, bdlb::NullableValueRef<TYPE> and bdlb::ConstNullableValueRef<TYPE>, that hold a reference to a either a bdlb::NullableValue or a bdlb::NullableAllocatedValue, and provide a common interface for dealing with the referenced object. Once constructed, the "ref" object is not re-targetable, i. e, it cannot be changed to refer to a different nullable object (the target). However, in the case of NullableValueRef, the value that is contained by the target can be changed, cleared, created and so on.
Neither a NullableValueRef nor a ConstNullableValueRef owns the target that it refers to. They do not allocate the value upon construction; they store a pointer to an already existing nullable value.
Ownership and Lifetime
Since the NullableValueRef does not own the value that it refers to, the user must ensure that the value's lifetime does not end before the NullableValueRef.
Usage
The following snippets of code illustrate use of this component.
Example 1: Migrating from NullableValue to NullableAllocatedValue
Suppose we have a data structure that contains optional data members that are implemented with NullableValue, and client code that uses them. Now we want to change the data structure to use NullableAllocatedValue, but without requiring simultaneous changes to the client code. If the client code uses NullableValueRef to access the optional values, the change will not require any source changes in the clients; a recompile is sufficient.
Given the following functions:
{
return nv;
}
{
return nav;
}
Definition bdlb_nullableallocatedvalue.h:174
Definition bdlb_nullablevalue.h:257
Definition bslstl_optional.h:1861
We can wrap both of these types into a wrapper, and then treat them identically.
assert(23 == r1.
value());
assert(34 == r2.
value());
Definition bdlb_nullablevalueref.h:163
const value_type & value() const
Definition bdlb_nullablevalueref.h:1183
◆ ConstNullableValueRef() [1/4]
Create a nullable object wrapper that refers to the specified opt object. Note that the created wrapper does not own a copy of the underlying nullable value, but instead refers to it, and so the lifetime of opt must exceed the lifetime of the created wrapper.
◆ ConstNullableValueRef() [2/4]
Create a nullable object wrapper that refers to the target object of the specified original wrapper. Note that the created wrapper does not own a copy of the underlying nullable value, but instead refers to it, and so the lifetime of the target must exceed the lifetime of the created wrapper.
◆ ConstNullableValueRef() [3/4]
Create a nullable object wrapper that refers to the specified opt object. Note that the created wrapper does not own a copy of the underlying nullable value, but instead refers to it, and so the lifetime of opt must exceed the lifetime of the created wrapper.
◆ ConstNullableValueRef() [4/4]
Create a nullable object wrapper that refers to the target object of the specified ref wrapper. Note that the created wrapper does not own a copy of the underlying nullable value, but instead refers to to it, and so the lifetime of the target must exceed the lifetime of the created wrapper.
◆ emplace()
template<class TYPE >
template<class... ARGS>
◆ has_value() [1/2]
◆ has_value() [2/2]
◆ isNull() [1/2]
Return false if the target contains a value, and true otherwise. Note that this accessor is provided purely for compatibility with NullableValue and NullableAllocatedValue, and its use is discouraged in favor of has_value .
◆ isNull() [2/2]
Return false if the target contains a value, and true otherwise. Note that this accessor is provided purely for compatibility with NullableValue and NullableAllocatedValue, and its use is discouraged in favor of has_value .
◆ NullableValueRef() [1/3]
Create a nullable object wrapper that refers to the specified opt object. Note that the created wrapper does not own a copy of the underlying nullable value, but instead refers to it, and so the lifetime of opt must exceed the lifetime of the created wrapper.
◆ NullableValueRef() [2/3]
Create a nullable object wrapper that refers to the target object of the specified original wrapper. Note that the created wrapper does not own a copy of the underlying nullable value, but instead refers to it, and so the lifetime of the target must exceed the lifetime of the created wrapper.
◆ NullableValueRef() [3/3]
Create a nullable object wrapper that refers to the specified opt object. Note that the created wrapper does not own a copy of the underlying nullable value, but instead refers to it, and so the lifetime of opt must exceed the lifetime of the created wrapper.
◆ operator*() [1/3]
Return a reference providing modifiable access to the underlying TYPE object. The behavior is undefined if the target has no value.
◆ operator*() [2/3]
Return a reference providing non-modifiable access to the underlying TYPE object. The behavior is undefined if the target has no value.
◆ operator*() [3/3]
Return a reference providing non-modifiable access to the underlying TYPE object. The behavior is undefined if the target has no value.
◆ operator->() [1/3]
Return a pointer providing modifiable access to the underlying TYPE object. The behavior is undefined if the target has no value.
◆ operator->() [2/3]
Return a pointer providing non-modifiable access to the underlying TYPE object. The behavior is undefined if the target has no value.
◆ operator->() [3/3]
Return a pointer providing non-modifiable access to the underlying TYPE object. The behavior is undefined if the target has no value.
◆ operator=() [1/5]
Reset the target to the default constructed state (i.e., to have the null value).
◆ operator=() [2/5]
Assign to the target the value of the specified rhs, and return a reference providing modifiable access to this object.
◆ operator=() [3/5]
Assign to the target the value of the specified rhs, and return a reference providing modifiable access to this object.
◆ operator=() [4/5]
Assign to the target the value of the specified rhs, and return a reference providing modifiable access to this object.
◆ operator=() [5/5]
Assign to the target the value of the specified rhs, and return a reference providing modifiable access to this object.
◆ reset()
Reset the target to the default constructed state (i.e., to have the null value).
◆ value() [1/3]
Return a reference providing modifiable access to the underlying TYPE object. The behavior is undefined unless this object is non-null.
◆ value() [2/3]
Return a reference providing non-modifiable access to the underlying object of a (template parameter) TYPE. The behavior is undefined if the target has no value.
◆ value() [3/3]
Return a reference providing non-modifiable access to the underlying object of a (template parameter) TYPE. The behavior is undefined if the target has no value.
◆ value_or() [1/2]
template<class TYPE >
template<class ANY_TYPE >
Return the value of the underlying object of a (template parameter) TYPE if the target is non-null, and the specified default_value otherwise. Note that this method returns by value, so may be inefficient in some contexts.
◆ value_or() [2/2]
template<class TYPE >
template<class ANY_TYPE >
Return the value of the underlying object of a (template parameter) TYPE if the target is non-null, and the specified default_value otherwise. Note that this method returns by value, so may be inefficient in some contexts.
1.9.8