std::optional stored on Base's heap. More...
#include <StormByte/safe/optional.hxx>
Public Types | |
| using | value_type = T |
| Contained type. | |
| using | iterator = T* |
| Mutable iterator over the single value, or end when empty. | |
| using | const_iterator = const T* |
| Read-only iterator over the single value, or end when empty. | |
| using | reference = T& |
| Mutable contained value. | |
| using | const_reference = const T& |
| Read-only contained value. | |
Public Member Functions | |
| Optional () noexcept | |
| Construct an empty optional. | |
| Optional (std::nullopt_t value) noexcept | |
| Construct an empty optional. | |
| template<class... Args> requires Type::ConstructibleFrom<T, Args...> | |
| Optional (std::in_place_t tag, Args &&... args) | |
| Construct the contained value in Base storage. | |
| template<class U, class... Args> requires Type::ConstructibleFrom<T, std::initializer_list<U>&, Args...> | |
| Optional (std::in_place_t tag, std::initializer_list< U > values, Args &&... args) | |
| Construct T from an initializer list and trailing arguments. | |
| Optional (const T &value) | |
| Copy a value into Base storage. | |
| Optional (T &&value) | |
| Move a value into Base storage. | |
| template<class U> requires (!Type::SameAs<U, Optional>) && (!Type::SameAs<U, std::nullopt_t>) && (!Type::SameAs<U, std::in_place_t>) && Type::ConstructibleFrom<T, U> | |
| Optional (U &&value) | |
| Construct T from a value that can construct it. | |
| Optional (const std::optional< T > &value) | |
| Copy a caller-owned STL optional into Base storage. | |
| Optional (std::optional< T > &&value) | |
| Move a caller-owned STL optional into Base storage. | |
| template<class U> requires (!Type::SameAs<U, T>) && Type::ConstructibleFrom<T, const U&> | |
| Optional (const std::optional< U > &value) | |
| Copy a caller-owned STL optional of a convertible value. | |
| template<class U> requires (!Type::SameAs<U, T>) && Type::ConstructibleFrom<T, U> | |
| Optional (std::optional< U > &&value) | |
| Move a caller-owned STL optional of a convertible value. | |
| Optional (const Optional &other) | |
| Copy the contained value into a new Base block. | |
| Optional (Optional &&other) noexcept | |
| Take the contained block. | |
| ~Optional () noexcept | |
| Destroy a held value and release its Base block. | |
| Optional & | operator= (const Optional &other) |
| Copy-assign. | |
| Optional & | operator= (Optional &&other) noexcept |
| Move-assign. | |
| Optional & | operator= (const T &value) |
| Copy-assign a value. | |
| Optional & | operator= (T &&value) |
| Move-assign a value. | |
| template<class U> requires (!Type::SameAs<U, Optional>) && (!Type::SameAs<U, std::nullopt_t>) && Type::ConstructibleFrom<T, U> | |
| Optional & | operator= (U &&value) |
| Assign a value that can construct T. | |
| Optional & | operator= (std::nullopt_t value) noexcept |
| Reset this optional. | |
| Optional & | operator= (const std::optional< T > &value) |
| Copy-assign a caller-owned STL optional. | |
| Optional & | operator= (std::optional< T > &&value) |
| Move-assign a caller-owned STL optional. | |
| void | swap (Optional &other) noexcept |
| Exchange contained blocks. | |
| bool | has_value () const noexcept |
| Test whether a value is held. | |
| operator bool () const noexcept | |
| Test whether a value is held. | |
| iterator | begin () noexcept |
| Return the mutable iterator, or end when empty. | |
| iterator | end () noexcept |
| Return the end mutable iterator. | |
| const_iterator | begin () const noexcept |
| Return the read-only iterator, or end when empty. | |
| const_iterator | end () const noexcept |
| Return the end read-only iterator. | |
| const_iterator | cbegin () const noexcept |
| Return the read-only iterator. | |
| const_iterator | cend () const noexcept |
| Return the end read-only iterator. | |
| T & | value () & |
| Return the contained value. | |
| const T & | value () const & |
| Return the contained value. | |
| T && | value () && |
| Return the contained value from an rvalue. | |
| const T && | value () const && |
| Return the contained value from a const rvalue. | |
| template<class U> requires Type::ConvertibleTo<U, T> | |
| T | value_or (U &&fallback) const & |
| Return the contained value or a fallback. | |
| template<class U> requires Type::ConvertibleTo<U, T> | |
| T | value_or (U &&fallback) && |
| Return the contained value or a fallback from an rvalue. | |
| T & | operator* () & |
| Access the contained value. | |
| const T & | operator* () const & |
| Access the contained value. | |
| T && | operator* () && |
| Access the contained value from an rvalue. | |
| const T && | operator* () const && |
| Access the contained value from a const rvalue. | |
| T * | operator-> () |
| Access a member of the contained value. | |
| const T * | operator-> () const |
| Access a member of the contained value. | |
| bool | operator== (const Optional &other) const |
| Compare states and, when present, values. | |
| bool | operator!= (const Optional &other) const |
| Compare states and, when present, values. | |
| bool | operator== (std::nullopt_t) const noexcept |
| Compare with the empty tag. | |
| STORMBYTE_FORCE_INLINE std::strong_ordering | operator<=> (std::nullopt_t) const noexcept |
| Order empty before engaged. | |
| template<class U> requires Type::SafeComponent<std::remove_cvref_t<U>> && (!Type::SameAs<std::remove_cvref_t<U>, Optional>) && requires(const T& left, const U& right) { { left == right } -> Type::ConvertibleTo<bool>; } | |
| bool | operator== (const U &value) const |
| Compare the contained value with a Safe component. | |
| template<class U> requires Type::SafeComponent<std::remove_cvref_t<U>> && (!Type::SameAs<std::remove_cvref_t<U>, Optional>) && requires(const T& left, const U& right) { left <=> right; } | |
| STORMBYTE_FORCE_INLINE auto | operator<=> (const U &value) const |
| Order against a Safe component. | |
| STORMBYTE_FORCE_INLINE auto | operator<=> (const Optional &other) const |
| Order empty before engaged, then order the values. | |
| template<class U> requires requires(const T& left, const U& right) { { left == right } -> Type::ConvertibleTo<bool>; } | |
| bool | operator== (const std::optional< U > &other) const |
| Compare with a caller-owned STL optional. | |
| template<class U> requires requires(const T& left, const U& right) { left <=> right; } | |
| STORMBYTE_FORCE_INLINE auto | operator<=> (const std::optional< U > &other) const |
| Order against a caller-owned STL optional. | |
| template<class F> requires Type::Invocable<F, T&> && Detail::SafeOptionalResult<std::remove_cvref_t<std::invoke_result_t<F, T&>>> | |
| auto | and_then (F &&function) & |
| Invoke a function on the value and return its optional result. | |
| template<class F> requires Type::Invocable<F, const T&> && Detail::SafeOptionalResult<std::remove_cvref_t<std::invoke_result_t<F, const T&>>> | |
| auto | and_then (F &&function) const & |
| Invoke a function on the value and return its optional result. | |
| template<class F> requires Type::Invocable<F, T&&> && Detail::SafeOptionalResult<std::remove_cvref_t<std::invoke_result_t<F, T&&>>> | |
| auto | and_then (F &&function) && |
| Invoke a function on an rvalue value and return its optional result. | |
| template<class F> requires Type::Invocable<F, T&> && Type::SafeComponent<std::remove_cvref_t<std::invoke_result_t<F, T&>>> | |
| auto | transform (F &&function) & |
| Map the contained value to another Safe component. | |
| template<class F> requires Type::Invocable<F, const T&> && Type::SafeComponent<std::remove_cvref_t<std::invoke_result_t<F, const T&>>> | |
| auto | transform (F &&function) const & |
| Map the contained value to another Safe component. | |
| template<class F> requires Type::Invocable<F, T&&> && Type::SafeComponent<std::remove_cvref_t<std::invoke_result_t<F, T&&>>> | |
| auto | transform (F &&function) && |
| Map an rvalue contained value to another Safe component. | |
| template<class F> requires Type::Invocable<F> && Type::SameAs<std::invoke_result_t<F>, Optional> | |
| Optional | or_else (F &&function) const & |
| Return this optional when engaged, otherwise invoke a fallback. | |
| template<class F> requires Type::Invocable<F> && Type::SameAs<std::invoke_result_t<F>, Optional> | |
| Optional | or_else (F &&function) && |
| Return this rvalue optional, or invoke a fallback. | |
| template<class... Args> | |
| T & | emplace (Args &&... args) |
| Construct or replace the contained value. | |
| template<class U, class... Args> | |
| T & | emplace (std::initializer_list< U > values, Args &&... args) |
| Construct or replace T from an initializer list. | |
| void | reset () noexcept |
| Destroy a held value and release its block. | |
| STORMBYTE_FORCE_INLINE | operator std::optional< T > () const |
| Copy the value into caller-owned STL storage. | |
Friends | |
| void | swap (Optional &left, Optional &right) noexcept |
| Exchange two optionals. | |
| bool | operator== (std::nullopt_t, const Optional &self) noexcept |
| Compare the empty tag with this optional. | |
| template<class U> requires Type::SafeComponent<std::remove_cvref_t<U>> && (!Type::SameAs<std::remove_cvref_t<U>, Optional>) && requires(const U& left, const T& right) { { left == right } -> Type::ConvertibleTo<bool>; } | |
| bool | operator== (const U &value, const Optional &self) |
| Compare a Safe component with this optional. | |
| template<class U> requires requires(const U& left, const T& right) { { left == right } -> Type::ConvertibleTo<bool>; } | |
| bool | operator== (const std::optional< U > &other, const Optional &self) |
| Compare a caller-owned STL optional with this optional. | |
std::optional stored on Base's heap.
| T | Safe component. |
The observable contract matches std::optional. The contained value is constructed in a block from Heap::Allocate and released with Heap::Free. A move of this optional leaves the source empty. A move from std::optional does not change its has_value(). value() throws BadOptionalAccess when empty. operator* and operator-> require a contained value and do not check.
| using StormByte::Safe::Optional< T >::const_iterator = const T* |
Read-only iterator over the single value, or end when empty.
| using StormByte::Safe::Optional< T >::const_reference = const T& |
Read-only contained value.
| using StormByte::Safe::Optional< T >::iterator = T* |
Mutable iterator over the single value, or end when empty.
| using StormByte::Safe::Optional< T >::reference = T& |
Mutable contained value.
| using StormByte::Safe::Optional< T >::value_type = T |
Contained type.
|
noexcept |
Construct an empty optional.
|
noexcept |
Construct an empty optional.
| value | Empty-state tag. |
|
inlineexplicit |
Construct the contained value in Base storage.
| Args | Constructor argument types. |
| tag | In-place construction tag. |
| args | Arguments forwarded to T. |
| AllocationError | The block could not be allocated. |
|
inlineexplicit |
Construct T from an initializer list and trailing arguments.
| U | Initializer-list element type. |
| Args | Trailing constructor argument types. |
| tag | In-place construction tag. |
| values | Initializer-list elements. |
| args | Trailing arguments forwarded to T. |
| AllocationError | The block could not be allocated. |
| StormByte::Safe::Optional< T >::Optional | ( | const T & | value | ) |
Copy a value into Base storage.
| value | Value to store. |
| AllocationError | The block could not be allocated. |
| StormByte::Safe::Optional< T >::Optional | ( | T && | value | ) |
Move a value into Base storage.
| value | Value to store. |
| AllocationError | The block could not be allocated. |
|
inline |
Construct T from a value that can construct it.
| U | Source type. |
| value | Source value. |
| AllocationError | The block could not be allocated. |
| StormByte::Safe::Optional< T >::Optional | ( | const std::optional< T > & | value | ) |
Copy a caller-owned STL optional into Base storage.
| value | Source. Its state is unchanged. |
| AllocationError | The block could not be allocated. |
| StormByte::Safe::Optional< T >::Optional | ( | std::optional< T > && | value | ) |
Move a caller-owned STL optional into Base storage.
| value | Source. has_value() is unchanged; a held value is moved-from. |
| AllocationError | The block could not be allocated. |
|
inline |
Copy a caller-owned STL optional of a convertible value.
| U | Source value type. |
| value | Source. Its state is unchanged. |
| AllocationError | The block could not be allocated. |
|
inline |
Move a caller-owned STL optional of a convertible value.
| U | Source value type. |
| value | Source. has_value() is unchanged; a held value is moved-from. |
| AllocationError | The block could not be allocated. |
| StormByte::Safe::Optional< T >::Optional | ( | const Optional< T > & | other | ) |
Copy the contained value into a new Base block.
| other | Source. |
| AllocationError | The block could not be allocated. |
|
noexcept |
Take the contained block.
other is left empty.
| other | Source. |
|
noexcept |
Destroy a held value and release its Base block.
|
inline |
|
inline |
|
inline |
|
inlinenoexcept |
Return the read-only iterator, or end when empty.
|
inlinenoexcept |
Return the mutable iterator, or end when empty.
|
inlinenoexcept |
Return the read-only iterator.
|
inlinenoexcept |
Return the end read-only iterator.
|
inline |
Construct or replace the contained value.
| Args | Constructor argument types. |
| args | Arguments forwarded to T. |
| AllocationError | The block could not be allocated. The previous value is kept. |
|
inline |
Construct or replace T from an initializer list.
| U | Initializer-list element type. |
| Args | Trailing constructor argument types. |
| values | Initializer-list elements. |
| args | Trailing arguments forwarded to T. |
| AllocationError | The block could not be allocated. The previous value is kept. |
|
inlinenoexcept |
Return the end read-only iterator.
|
inlinenoexcept |
Return the end mutable iterator.
|
inlinenoexcept |
Test whether a value is held.
|
inlineexplicitnoexcept |
Test whether a value is held.
|
inlineexplicit |
Copy the value into caller-owned STL storage.
|
inline |
Compare states and, when present, values.
| other | Optional to compare. |
| T & StormByte::Safe::Optional< T >::operator* | ( | ) | & |
Access the contained value.
| T && StormByte::Safe::Optional< T >::operator* | ( | ) | && |
Access the contained value from an rvalue.
| const T & StormByte::Safe::Optional< T >::operator* | ( | ) | const & |
Access the contained value.
| const T && StormByte::Safe::Optional< T >::operator* | ( | ) | const && |
Access the contained value from a const rvalue.
| T * StormByte::Safe::Optional< T >::operator-> | ( | ) |
Access a member of the contained value.
| const T * StormByte::Safe::Optional< T >::operator-> | ( | ) | const |
Access a member of the contained value.
|
inline |
Order empty before engaged, then order the values.
| other | Optional to compare. |
|
inline |
Order against a caller-owned STL optional.
Empty is less than engaged.
| U | Other value type. |
| other | Optional to compare. |
|
inline |
|
inlinenoexcept |
Order empty before engaged.
| Optional & StormByte::Safe::Optional< T >::operator= | ( | const Optional< T > & | other | ) |
Copy-assign.
The previous value is released only after the copy exists.
| other | Source. |
| AllocationError | The replacement block could not be allocated. |
| Optional & StormByte::Safe::Optional< T >::operator= | ( | const std::optional< T > & | value | ) |
Copy-assign a caller-owned STL optional.
Its state is unchanged.
| value | Source. |
| AllocationError | The replacement block could not be allocated. |
| Optional & StormByte::Safe::Optional< T >::operator= | ( | const T & | value | ) |
Copy-assign a value.
| value | Value to store. |
| AllocationError | The replacement block could not be allocated. |
|
noexcept |
Move-assign.
other is left empty.
| other | Source. |
|
noexcept |
Reset this optional.
| value | Empty-state tag. |
| Optional & StormByte::Safe::Optional< T >::operator= | ( | std::optional< T > && | value | ) |
Move-assign a caller-owned STL optional.
has_value() is unchanged.
| value | Source. |
| AllocationError | The replacement block could not be allocated. |
| Optional & StormByte::Safe::Optional< T >::operator= | ( | T && | value | ) |
Move-assign a value.
| value | Value to store. |
| AllocationError | The replacement block could not be allocated. |
|
inline |
Assign a value that can construct T.
| U | Source type. |
| value | Source value. |
| AllocationError | The replacement block could not be allocated. |
|
inline |
Compare states and, when present, values.
| other | Optional to compare. |
|
inline |
Compare with a caller-owned STL optional.
| U | Other value type. |
| other | Optional to compare. |
|
inline |
|
inlinenoexcept |
Compare with the empty tag.
|
inline |
Return this rvalue optional, or invoke a fallback.
| F | Callable returning Optional. |
| function | Fallback callable. |
|
inline |
Return this optional when engaged, otherwise invoke a fallback.
| F | Callable returning Optional. |
| function | Fallback callable. |
|
noexcept |
Destroy a held value and release its block.
|
noexcept |
|
inline |
|
inline |
|
inline |
| T & StormByte::Safe::Optional< T >::value | ( | ) | & |
Return the contained value.
| BadOptionalAccess | The optional is empty. |
| T && StormByte::Safe::Optional< T >::value | ( | ) | && |
Return the contained value from an rvalue.
| BadOptionalAccess | The optional is empty. |
| const T & StormByte::Safe::Optional< T >::value | ( | ) | const & |
Return the contained value.
| BadOptionalAccess | The optional is empty. |
| const T && StormByte::Safe::Optional< T >::value | ( | ) | const && |
Return the contained value from a const rvalue.
| BadOptionalAccess | The optional is empty. |
|
inline |
Return the contained value or a fallback from an rvalue.
| U | Fallback type convertible to T. |
| fallback | Value returned when empty. |
|
inline |
Return the contained value or a fallback.
| U | Fallback type convertible to T. |
| fallback | Value returned when empty. |
|
friend |
Compare a caller-owned STL optional with this optional.
| U | Other value type. |
| other | STL optional. |
| self | Optional to compare. |
|
friend |
|
friend |
Compare the empty tag with this optional.
| self | Optional to compare. |
Exchange two optionals.
| left | First optional. |
| right | Second optional. |