StormByte 3.0.0
C++26 foundation of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Safe::Optional< T > Class Template Referencefinal

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.

Detailed Description

template<Type::SafeComponent T>
class StormByte::Safe::Optional< T >

std::optional stored on Base's heap.

Template Parameters
TSafe 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.

Member Typedef Documentation

◆ const_iterator

template<Type::SafeComponent T>
using StormByte::Safe::Optional< T >::const_iterator = const T*

Read-only iterator over the single value, or end when empty.

◆ const_reference

template<Type::SafeComponent T>
using StormByte::Safe::Optional< T >::const_reference = const T&

Read-only contained value.

◆ iterator

template<Type::SafeComponent T>
using StormByte::Safe::Optional< T >::iterator = T*

Mutable iterator over the single value, or end when empty.

◆ reference

template<Type::SafeComponent T>
using StormByte::Safe::Optional< T >::reference = T&

Mutable contained value.

◆ value_type

template<Type::SafeComponent T>
using StormByte::Safe::Optional< T >::value_type = T

Contained type.

Constructor & Destructor Documentation

◆ Optional() [1/13]

template<Type::SafeComponent T>
StormByte::Safe::Optional< T >::Optional ( )
noexcept

Construct an empty optional.

◆ Optional() [2/13]

template<Type::SafeComponent T>
StormByte::Safe::Optional< T >::Optional ( std::nullopt_t value)
noexcept

Construct an empty optional.

Parameters
valueEmpty-state tag.

◆ Optional() [3/13]

template<Type::SafeComponent T>
template<class... Args>
requires Type::ConstructibleFrom<T, Args...>
StormByte::Safe::Optional< T >::Optional ( std::in_place_t tag,
Args &&... args )
inlineexplicit

Construct the contained value in Base storage.

Template Parameters
ArgsConstructor argument types.
Parameters
tagIn-place construction tag.
argsArguments forwarded to T.
Exceptions
AllocationErrorThe block could not be allocated.

◆ Optional() [4/13]

template<Type::SafeComponent T>
template<class U, class... Args>
requires Type::ConstructibleFrom<T, std::initializer_list<U>&, Args...>
StormByte::Safe::Optional< T >::Optional ( std::in_place_t tag,
std::initializer_list< U > values,
Args &&... args )
inlineexplicit

Construct T from an initializer list and trailing arguments.

Template Parameters
UInitializer-list element type.
ArgsTrailing constructor argument types.
Parameters
tagIn-place construction tag.
valuesInitializer-list elements.
argsTrailing arguments forwarded to T.
Exceptions
AllocationErrorThe block could not be allocated.

◆ Optional() [5/13]

template<Type::SafeComponent T>
StormByte::Safe::Optional< T >::Optional ( const T & value)

Copy a value into Base storage.

Parameters
valueValue to store.
Exceptions
AllocationErrorThe block could not be allocated.

◆ Optional() [6/13]

template<Type::SafeComponent T>
StormByte::Safe::Optional< T >::Optional ( T && value)

Move a value into Base storage.

Parameters
valueValue to store.
Exceptions
AllocationErrorThe block could not be allocated.

◆ Optional() [7/13]

template<Type::SafeComponent T>
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>
StormByte::Safe::Optional< T >::Optional ( U && value)
inline

Construct T from a value that can construct it.

Template Parameters
USource type.
Parameters
valueSource value.
Exceptions
AllocationErrorThe block could not be allocated.

◆ Optional() [8/13]

template<Type::SafeComponent T>
StormByte::Safe::Optional< T >::Optional ( const std::optional< T > & value)

Copy a caller-owned STL optional into Base storage.

Parameters
valueSource. Its state is unchanged.
Exceptions
AllocationErrorThe block could not be allocated.

◆ Optional() [9/13]

template<Type::SafeComponent T>
StormByte::Safe::Optional< T >::Optional ( std::optional< T > && value)

Move a caller-owned STL optional into Base storage.

Parameters
valueSource. has_value() is unchanged; a held value is moved-from.
Exceptions
AllocationErrorThe block could not be allocated.

◆ Optional() [10/13]

template<Type::SafeComponent T>
template<class U>
requires (!Type::SameAs<U, T>) && Type::ConstructibleFrom<T, const U&>
StormByte::Safe::Optional< T >::Optional ( const std::optional< U > & value)
inline

Copy a caller-owned STL optional of a convertible value.

Template Parameters
USource value type.
Parameters
valueSource. Its state is unchanged.
Exceptions
AllocationErrorThe block could not be allocated.

◆ Optional() [11/13]

template<Type::SafeComponent T>
template<class U>
requires (!Type::SameAs<U, T>) && Type::ConstructibleFrom<T, U>
StormByte::Safe::Optional< T >::Optional ( std::optional< U > && value)
inline

Move a caller-owned STL optional of a convertible value.

Template Parameters
USource value type.
Parameters
valueSource. has_value() is unchanged; a held value is moved-from.
Exceptions
AllocationErrorThe block could not be allocated.

◆ Optional() [12/13]

template<Type::SafeComponent T>
StormByte::Safe::Optional< T >::Optional ( const Optional< T > & other)

Copy the contained value into a new Base block.

Parameters
otherSource.
Exceptions
AllocationErrorThe block could not be allocated.

◆ Optional() [13/13]

template<Type::SafeComponent T>
StormByte::Safe::Optional< T >::Optional ( Optional< T > && other)
noexcept

Take the contained block.

other is left empty.

Parameters
otherSource.

◆ ~Optional()

template<Type::SafeComponent T>
StormByte::Safe::Optional< T >::~Optional ( )
noexcept

Destroy a held value and release its Base block.

Member Function Documentation

◆ and_then() [1/3]

template<Type::SafeComponent T>
template<class F>
requires Type::Invocable<F, T&> && Detail::SafeOptionalResult<std::remove_cvref_t<std::invoke_result_t<F, T&>>>
auto StormByte::Safe::Optional< T >::and_then ( F && function) &
inline

Invoke a function on the value and return its optional result.

Template Parameters
FCallable returning a Safe optional.
Parameters
functionFunction invoked with the contained value.
Returns
An empty optional of the result type, or the function result.

◆ and_then() [2/3]

template<Type::SafeComponent T>
template<class F>
requires Type::Invocable<F, T&&> && Detail::SafeOptionalResult<std::remove_cvref_t<std::invoke_result_t<F, T&&>>>
auto StormByte::Safe::Optional< T >::and_then ( F && function) &&
inline

Invoke a function on an rvalue value and return its optional result.

Template Parameters
FCallable returning a Safe optional.
Parameters
functionFunction invoked with the contained value.
Returns
An empty optional of the result type, or the function result.

◆ and_then() [3/3]

template<Type::SafeComponent T>
template<class F>
requires Type::Invocable<F, const T&> && Detail::SafeOptionalResult<std::remove_cvref_t<std::invoke_result_t<F, const T&>>>
auto StormByte::Safe::Optional< T >::and_then ( F && function) const &
inline

Invoke a function on the value and return its optional result.

Template Parameters
FCallable returning a Safe optional.
Parameters
functionFunction invoked with the contained value.
Returns
An empty optional of the result type, or the function result.

◆ begin() [1/2]

template<Type::SafeComponent T>
const_iterator StormByte::Safe::Optional< T >::begin ( ) const
inlinenoexcept

Return the read-only iterator, or end when empty.

Returns
Read-only iterator.

◆ begin() [2/2]

template<Type::SafeComponent T>
iterator StormByte::Safe::Optional< T >::begin ( )
inlinenoexcept

Return the mutable iterator, or end when empty.

Returns
Mutable iterator.

◆ cbegin()

template<Type::SafeComponent T>
const_iterator StormByte::Safe::Optional< T >::cbegin ( ) const
inlinenoexcept

Return the read-only iterator.

Returns
Read-only iterator.

◆ cend()

template<Type::SafeComponent T>
const_iterator StormByte::Safe::Optional< T >::cend ( ) const
inlinenoexcept

Return the end read-only iterator.

Returns
Read-only iterator.

◆ emplace() [1/2]

template<Type::SafeComponent T>
template<class... Args>
T & StormByte::Safe::Optional< T >::emplace ( Args &&... args)
inline

Construct or replace the contained value.

Template Parameters
ArgsConstructor argument types.
Parameters
argsArguments forwarded to T.
Returns
Contained value. Valid until reset or a move.
Exceptions
AllocationErrorThe block could not be allocated. The previous value is kept.

◆ emplace() [2/2]

template<Type::SafeComponent T>
template<class U, class... Args>
T & StormByte::Safe::Optional< T >::emplace ( std::initializer_list< U > values,
Args &&... args )
inline

Construct or replace T from an initializer list.

Template Parameters
UInitializer-list element type.
ArgsTrailing constructor argument types.
Parameters
valuesInitializer-list elements.
argsTrailing arguments forwarded to T.
Returns
Contained value. Valid until reset or a move.
Exceptions
AllocationErrorThe block could not be allocated. The previous value is kept.

◆ end() [1/2]

template<Type::SafeComponent T>
const_iterator StormByte::Safe::Optional< T >::end ( ) const
inlinenoexcept

Return the end read-only iterator.

Returns
One past the value, or equal to begin when empty.

◆ end() [2/2]

template<Type::SafeComponent T>
iterator StormByte::Safe::Optional< T >::end ( )
inlinenoexcept

Return the end mutable iterator.

Returns
One past the value, or equal to begin when empty.

◆ has_value()

template<Type::SafeComponent T>
bool StormByte::Safe::Optional< T >::has_value ( ) const
inlinenoexcept

Test whether a value is held.

Returns
Whether the optional contains a value.

◆ operator bool()

template<Type::SafeComponent T>
StormByte::Safe::Optional< T >::operator bool ( ) const
inlineexplicitnoexcept

Test whether a value is held.

Returns
Whether the optional contains a value.

◆ operator std::optional< T >()

template<Type::SafeComponent T>
STORMBYTE_FORCE_INLINE StormByte::Safe::Optional< T >::operator std::optional< T > ( ) const
inlineexplicit

Copy the value into caller-owned STL storage.

Returns
A std::optional owned by the caller.

◆ operator!=()

template<Type::SafeComponent T>
bool StormByte::Safe::Optional< T >::operator!= ( const Optional< T > & other) const
inline

Compare states and, when present, values.

Parameters
otherOptional to compare.
Returns
Whether the optionals differ.

◆ operator*() [1/4]

template<Type::SafeComponent T>
T & StormByte::Safe::Optional< T >::operator* ( ) &

Access the contained value.

Returns
Contained value. Valid until reset or a move.
Precondition
The optional contains a value.

◆ operator*() [2/4]

template<Type::SafeComponent T>
T && StormByte::Safe::Optional< T >::operator* ( ) &&

Access the contained value from an rvalue.

Returns
Contained value.
Precondition
The optional contains a value.

◆ operator*() [3/4]

template<Type::SafeComponent T>
const T & StormByte::Safe::Optional< T >::operator* ( ) const &

Access the contained value.

Returns
Contained value. Valid until reset or a move.
Precondition
The optional contains a value.

◆ operator*() [4/4]

template<Type::SafeComponent T>
const T && StormByte::Safe::Optional< T >::operator* ( ) const &&

Access the contained value from a const rvalue.

Returns
Contained value.
Precondition
The optional contains a value.

◆ operator->() [1/2]

template<Type::SafeComponent T>
T * StormByte::Safe::Optional< T >::operator-> ( )

Access a member of the contained value.

Returns
Pointer to the contained value.
Precondition
The optional contains a value.

◆ operator->() [2/2]

template<Type::SafeComponent T>
const T * StormByte::Safe::Optional< T >::operator-> ( ) const

Access a member of the contained value.

Returns
Pointer to the contained value.
Precondition
The optional contains a value.

◆ operator<=>() [1/4]

template<Type::SafeComponent T>
STORMBYTE_FORCE_INLINE auto StormByte::Safe::Optional< T >::operator<=> ( const Optional< T > & other) const
inline

Order empty before engaged, then order the values.

Parameters
otherOptional to compare.
Returns
Three-way comparison result.

◆ operator<=>() [2/4]

template<Type::SafeComponent T>
template<class U>
requires requires(const T& left, const U& right) { left <=> right; }
STORMBYTE_FORCE_INLINE auto StormByte::Safe::Optional< T >::operator<=> ( const std::optional< U > & other) const
inline

Order against a caller-owned STL optional.

Empty is less than engaged.

Template Parameters
UOther value type.
Parameters
otherOptional to compare.
Returns
Three-way comparison result.

◆ operator<=>() [3/4]

template<Type::SafeComponent T>
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 StormByte::Safe::Optional< T >::operator<=> ( const U & value) const
inline

Order against a Safe component.

Empty is less than any value.

Template Parameters
USafe component orderable against T. An iterator is not a candidate.
Parameters
valueValue to compare.
Returns
Three-way comparison result.

◆ operator<=>() [4/4]

template<Type::SafeComponent T>
STORMBYTE_FORCE_INLINE std::strong_ordering StormByte::Safe::Optional< T >::operator<=> ( std::nullopt_t ) const
inlinenoexcept

Order empty before engaged.

Returns
Equivalent when empty, greater when engaged.

◆ operator=() [1/8]

template<Type::SafeComponent T>
Optional & StormByte::Safe::Optional< T >::operator= ( const Optional< T > & other)

Copy-assign.

The previous value is released only after the copy exists.

Parameters
otherSource.
Returns
This optional.
Exceptions
AllocationErrorThe replacement block could not be allocated.

◆ operator=() [2/8]

template<Type::SafeComponent T>
Optional & StormByte::Safe::Optional< T >::operator= ( const std::optional< T > & value)

Copy-assign a caller-owned STL optional.

Its state is unchanged.

Parameters
valueSource.
Returns
This optional.
Exceptions
AllocationErrorThe replacement block could not be allocated.

◆ operator=() [3/8]

template<Type::SafeComponent T>
Optional & StormByte::Safe::Optional< T >::operator= ( const T & value)

Copy-assign a value.

Parameters
valueValue to store.
Returns
This optional.
Exceptions
AllocationErrorThe replacement block could not be allocated.

◆ operator=() [4/8]

template<Type::SafeComponent T>
Optional & StormByte::Safe::Optional< T >::operator= ( Optional< T > && other)
noexcept

Move-assign.

other is left empty.

Parameters
otherSource.
Returns
This optional.

◆ operator=() [5/8]

template<Type::SafeComponent T>
Optional & StormByte::Safe::Optional< T >::operator= ( std::nullopt_t value)
noexcept

Reset this optional.

Parameters
valueEmpty-state tag.
Returns
This optional.

◆ operator=() [6/8]

template<Type::SafeComponent T>
Optional & StormByte::Safe::Optional< T >::operator= ( std::optional< T > && value)

Move-assign a caller-owned STL optional.

has_value() is unchanged.

Parameters
valueSource.
Returns
This optional.
Exceptions
AllocationErrorThe replacement block could not be allocated.

◆ operator=() [7/8]

template<Type::SafeComponent T>
Optional & StormByte::Safe::Optional< T >::operator= ( T && value)

Move-assign a value.

Parameters
valueValue to store.
Returns
This optional.
Exceptions
AllocationErrorThe replacement block could not be allocated.

◆ operator=() [8/8]

template<Type::SafeComponent T>
template<class U>
requires (!Type::SameAs<U, Optional>) && (!Type::SameAs<U, std::nullopt_t>) && Type::ConstructibleFrom<T, U>
Optional & StormByte::Safe::Optional< T >::operator= ( U && value)
inline

Assign a value that can construct T.

Template Parameters
USource type.
Parameters
valueSource value.
Returns
This optional.
Exceptions
AllocationErrorThe replacement block could not be allocated.

◆ operator==() [1/4]

template<Type::SafeComponent T>
bool StormByte::Safe::Optional< T >::operator== ( const Optional< T > & other) const
inline

Compare states and, when present, values.

Parameters
otherOptional to compare.
Returns
Whether both are empty or contain equal values.

◆ operator==() [2/4]

template<Type::SafeComponent T>
template<class U>
requires requires(const T& left, const U& right) { { left == right } -> Type::ConvertibleTo<bool>; }
bool StormByte::Safe::Optional< T >::operator== ( const std::optional< U > & other) const
inline

Compare with a caller-owned STL optional.

Template Parameters
UOther value type.
Parameters
otherOptional to compare.
Returns
Whether both are empty or their values compare equal.

◆ operator==() [3/4]

template<Type::SafeComponent T>
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 StormByte::Safe::Optional< T >::operator== ( const U & value) const
inline

Compare the contained value with a Safe component.

Empty is not equal.

Template Parameters
USafe component comparable with T. An iterator is not a candidate: checking U == T would re-enter this operator.
Parameters
valueValue to compare.
Returns
Whether a value is held and compares equal.

◆ operator==() [4/4]

template<Type::SafeComponent T>
bool StormByte::Safe::Optional< T >::operator== ( std::nullopt_t ) const
inlinenoexcept

Compare with the empty tag.

Returns
Whether this optional is empty.

◆ or_else() [1/2]

template<Type::SafeComponent T>
template<class F>
requires Type::Invocable<F> && Type::SameAs<std::invoke_result_t<F>, Optional>
Optional StormByte::Safe::Optional< T >::or_else ( F && function) &&
inline

Return this rvalue optional, or invoke a fallback.

Template Parameters
FCallable returning Optional.
Parameters
functionFallback callable.
Returns
This optional moved, or the callable result.

◆ or_else() [2/2]

template<Type::SafeComponent T>
template<class F>
requires Type::Invocable<F> && Type::SameAs<std::invoke_result_t<F>, Optional>
Optional StormByte::Safe::Optional< T >::or_else ( F && function) const &
inline

Return this optional when engaged, otherwise invoke a fallback.

Template Parameters
FCallable returning Optional.
Parameters
functionFallback callable.
Returns
A copy of this optional, or the callable result.

◆ reset()

template<Type::SafeComponent T>
void StormByte::Safe::Optional< T >::reset ( )
noexcept

Destroy a held value and release its block.

◆ swap()

template<Type::SafeComponent T>
void StormByte::Safe::Optional< T >::swap ( Optional< T > & other)
noexcept

Exchange contained blocks.

Does not allocate.

Parameters
otherOptional to exchange with.

◆ transform() [1/3]

template<Type::SafeComponent T>
template<class F>
requires Type::Invocable<F, T&> && Type::SafeComponent<std::remove_cvref_t<std::invoke_result_t<F, T&>>>
auto StormByte::Safe::Optional< T >::transform ( F && function) &
inline

Map the contained value to another Safe component.

Template Parameters
FCallable returning a Safe component.
Parameters
functionFunction invoked with the contained value.
Returns
An empty optional, or an optional holding the mapped value.

◆ transform() [2/3]

template<Type::SafeComponent T>
template<class F>
requires Type::Invocable<F, T&&> && Type::SafeComponent<std::remove_cvref_t<std::invoke_result_t<F, T&&>>>
auto StormByte::Safe::Optional< T >::transform ( F && function) &&
inline

Map an rvalue contained value to another Safe component.

Template Parameters
FCallable returning a Safe component.
Parameters
functionFunction invoked with the contained value.
Returns
An empty optional, or an optional holding the mapped value.

◆ transform() [3/3]

template<Type::SafeComponent T>
template<class F>
requires Type::Invocable<F, const T&> && Type::SafeComponent<std::remove_cvref_t<std::invoke_result_t<F, const T&>>>
auto StormByte::Safe::Optional< T >::transform ( F && function) const &
inline

Map the contained value to another Safe component.

Template Parameters
FCallable returning a Safe component.
Parameters
functionFunction invoked with the contained value.
Returns
An empty optional, or an optional holding the mapped value.

◆ value() [1/4]

template<Type::SafeComponent T>
T & StormByte::Safe::Optional< T >::value ( ) &

Return the contained value.

Returns
Contained value. Valid until reset or a move.
Exceptions
BadOptionalAccessThe optional is empty.

◆ value() [2/4]

template<Type::SafeComponent T>
T && StormByte::Safe::Optional< T >::value ( ) &&

Return the contained value from an rvalue.

Returns
Contained value.
Exceptions
BadOptionalAccessThe optional is empty.

◆ value() [3/4]

template<Type::SafeComponent T>
const T & StormByte::Safe::Optional< T >::value ( ) const &

Return the contained value.

Returns
Contained value. Valid until reset or a move.
Exceptions
BadOptionalAccessThe optional is empty.

◆ value() [4/4]

template<Type::SafeComponent T>
const T && StormByte::Safe::Optional< T >::value ( ) const &&

Return the contained value from a const rvalue.

Returns
Contained value.
Exceptions
BadOptionalAccessThe optional is empty.

◆ value_or() [1/2]

template<Type::SafeComponent T>
template<class U>
requires Type::ConvertibleTo<U, T>
T StormByte::Safe::Optional< T >::value_or ( U && fallback) &&
inline

Return the contained value or a fallback from an rvalue.

Template Parameters
UFallback type convertible to T.
Parameters
fallbackValue returned when empty.
Returns
The moved contained value, or the forwarded fallback.

◆ value_or() [2/2]

template<Type::SafeComponent T>
template<class U>
requires Type::ConvertibleTo<U, T>
T StormByte::Safe::Optional< T >::value_or ( U && fallback) const &
inline

Return the contained value or a fallback.

Template Parameters
UFallback type convertible to T.
Parameters
fallbackValue returned when empty.
Returns
A copy of the contained value, or the forwarded fallback.

◆ operator== [1/3]

template<Type::SafeComponent T>
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< T > & self )
friend

Compare a caller-owned STL optional with this optional.

Template Parameters
UOther value type.
Parameters
otherSTL optional.
selfOptional to compare.
Returns
Whether both are empty or their values compare equal.

◆ operator== [2/3]

template<Type::SafeComponent T>
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< T > & self )
friend

Compare a Safe component with this optional.

Template Parameters
USafe component comparable with T. An iterator is not a candidate: checking U == T would re-enter this operator.
Parameters
valueValue to compare.
selfOptional to compare.
Returns
Whether a value is held and compares equal.

◆ operator== [3/3]

template<Type::SafeComponent T>
bool operator== ( std::nullopt_t ,
const Optional< T > & self )
friend

Compare the empty tag with this optional.

Parameters
selfOptional to compare.
Returns
Whether this optional is empty.

◆ swap

template<Type::SafeComponent T>
void swap ( Optional< T > & left,
Optional< T > & right )
friend

Exchange two optionals.

Parameters
leftFirst optional.
rightSecond optional.

The documentation for this class was generated from the following file: