Class Subspace :: sus :: option :: Option
The Option type.
See the namespace level documentation for more.
Static Methods
Construct an option that is holding the given value.
Const References
For Option<const T&> it is possible to bind to
a temporary which would create a memory safety bug. The
[[clang::lifetimebound]] attribute is used to prevent this via Clang.
But additionally, the incoming type is required to match with
SafelyConstructibleFromReference
to prevent conversions that would construct a temporary.
To force accepting a const reference anyway in cases where a type can
convert to a reference without constructing a temporary, use an unsafe
static_cast<const T&>() at the callsite and document why a temporary is
not constructed.
Converts from Option<X> to Option<Y> if X is convertible to Y.
Copy constructor for Option<T> which will
satisfy Copy<Option<T>> if
Copy<T> is satisfied.
If T can be trivially copy-constructed, then Option<T> can also be
trivially copy-constructed.
Move constructor for Option<T> which will
satisfy Move<Option<T>> if
Move<T> is satisfied.
If T can be trivially move-constructed, then Option<T> can also be
trivially move-constructed. When trivially-moved, the option is copied on
move, and the moved-from Option is unchanged but should still not be used
thereafter without reinitializing it. Use take() instead to move the
value out of the option when the option may be used again afterward.
Implicit conversion from std::optional.
Moves or copies val into a new option holding Some(val).
Implements From<Option<T>, T>.
sus::iter::Iterator<Iter, Option<T>>
sus::iter::Product<T>
Computes the product of an iterator over
Option<T> as long as there is no None found.
If a None is found, the function returns None.
Prefer to call product() on the iterator rather than calling
from_product() directly.
Implements sus::iter::Product<Option<T>>.
The product is computed using the implementation of the inner type T
which also satisfies sus::iter::Product<T>.
Computes the sum of an iterator over Option<T>
as long as there is no None found. If a None is found, the function
returns None.
Prefer to call sum() on the iterator rather than calling from_sum()
directly.
Implements sus::iter::Sum<Option<T>>.
The sum is computed using the implementation of the inner type T
which also satisfies sus::iter::Sum<T>.
Methods
Consumes this option and returns an option with None if this option
holds None, otherwise returns that option.
Consumes this option and returns an option with None if this option
holds None, otherwise calls f with the contained value and returns the
result.
The function f receives the option's inner T and can return any
Option<U>.
Some languages call this operation flatmap.
Returns an Option<T&> from this
Option<T>, that either holds None or a
reference to the value in this option.
Returns an Option<const T&> from this
Option<T>, that either holds None or a
reference to the value in this option.
Implementation Notes
Implementation note: We only allow calling this on an rvalue option if the contained value is a reference, otherwise we are returning a reference to a short-lived object which leads to common C++ memory bugs.
Returns a const reference to the contained value inside the option.
To extract the value inside an option, use
unwrap on
an rvalue, and take to move the
contents of an lvalue option to an rvalue.
Panics
The function will panic without a message if the option's state is
currently None.
Implementation Notes
Implementation note: We only allow calling this on an rvalue Option if
the contained value is a reference, otherwise we are returning a reference
to a short-lived object which leads to common C++ memory bugs.
Returns a mutable reference to the contained value inside the option.
To extract the value inside an option, use
unwrap on
an rvalue, and take to move the
contents of an lvalue option to an rvalue.
Panics
The function will panic without a message if the option's state is
currently None.
Implementation Notes
Implementation note: We only allow calling this on an rvalue Option if
the contained value is a reference, otherwise we are returning a reference
to a short-lived object which leads to common C++ memory bugs.
std::is_reference_v<T>
Returns a const reference to the contained value inside the option.
To extract the value inside an option, use
unwrap_unchecked on
an rvalue, and take to move the
contents of an lvalue option to an rvalue.
Safety
The option's state must be Some or Undefined Behaviour results.
Implementation Notes
Implementation note: We only allow calling this on an rvalue Option if
the contained value is a reference, otherwise we are returning a reference
to a short-lived object which leads to common C++ memory bugs.
std::is_reference_v<T>
std::is_reference_v<T>
Returns a mutable reference to the contained value inside the option.
To extract the value inside an option, use
unwrap_unchecked on
an rvalue, and take to move the
contents of an lvalue option to an rvalue.
Safety
The option's state must be Some or Undefined Behaviour results.
Implementation Notes
Implementation note: We only allow calling this on an rvalue Option if
the contained value is a reference, otherwise we are returning a reference
to a short-lived object which leads to common C++ memory bugs.
sus::mem::Clone<T>
!::sus::mem::CopyOrRef<T>
Satisifies the CloneFrom concept.
Maps an Option<T&> to an
Option<T> by cloning the referenced T.
Maps an Option<T&> to an
Option<T> by copying the referenced T.
Returns the contained value inside the option.
The function will panic with the given message if the option's state is
currently None.
Consumes the option and applies a predicate function to the value
contained in the option. Returns a new option with the same value if the
predicate returns true, otherwise returns an empty Option.
The predicate function must be able to receive const T& and return a
value that converts tobool.
Maps an Option<Option<T>> to an
Option<T>.
std::convertible_to<U, T>
std::is_reference_v<T>
sus::construct::SafelyConstructibleFromReference<T, U &&>
If the option holds a value, returns a mutable reference to it. Otherwise,
stores value inside the option and returns a mutable reference to it.
If it is non-trivial to construct T, the
Option::get_or_insert_with
method would be preferable, as it only constructs a T if needed.
If the option holds a value, returns a mutable reference to it. Otherwise,
constructs a default value T, stores it inside the option and returns a
mutable reference to the new value.
This method differs from
unwrap_or_default
in that it does not consume the option, and instead it can not be called
on rvalues.
This is a shorthand for
Option<T>::get_or_insert_with([] { return T(); }).
The option's contained type T must satisfy
Default so it can be constructed with its
default value.
If the option holds a value, returns a mutable reference to it. Otherwise,
constructs a T by calling f, stores it inside the option and returns a
mutable reference to the new value.
This method differs from
unwrap_or_else in that
it does not consume the option, and instead it can not be called on
rvalues.
Inserts value into the option, then returns a mutable reference to it.
If the option already contains a value, the old value is dropped.
See also
Option::get_or_insert,
which doesn’t update the value if the option already contains Some.
Produces an Iterator over the single item in the
Option, or an empty iterator. If the option holds a value, the iterator
will return ownership of the value. If the option holds a reference, it
will return that reference.
Returns whether the option is currently empty, containing no value.
Returns whether the option currently contains a value.
If there is a value present, it can be extracted with
unwrap or
expect. For lvalues, it can be
accessed as a reference through
as_value and
as_value_mut for explicit
const/mutable access, or through
operator*
and operator->.
Produces an Iterator over the single item in the
Option, or an empty iterator. The iterator will return a const
reference.
Produces an Iterator over the single item in the
Option, or an empty iterator. If the Option holds a value, the
iterator will return a mutable reference to it. If the Option holds a
reference, it will return that reference.
Maps the option's value through a function.
When called on an rvalue, it consumes the option, passing the value
through the map function, and returning an
Option<R> where R is the
return type of the map function.
Returns an Option<R> in state None
if the current option is in state None.
Returns the provided default result (if none), or applies a function to the contained value (if any).
Arguments passed to map_or are eagerly evaluated; if you are passing the
result of a function call, it is recommended to use
map_or_else, which is
lazily evaluated.
sus::fn::FnOnce<DefaultFn, ::sus::fn::NonVoid (void)>
sus::fn::FnOnce<MapFn, ::sus::fn::ReturnOnce<DefaultFn> (T &&)>
sus::fn::FnOnce<DefaultFn, ::sus::fn::NonVoid (void)>
sus::fn::FnOnce<MapFn, ::sus::fn::ReturnOnce<DefaultFn> (T &&)>
sus::mem::CopyOrRef<T>
Computes a default function result (if none), or applies a different function to the contained value (if any).
Transforms the Option<T> into a
Result<T, E>, mapping Some(v) to Ok(v) and
None to Err(e).
Arguments passed to ok_or are eagerly evaluated; if you are passing the
result of a function call, it is recommended to use
ok_or_else, which is
lazily evaluated.
sus::fn::FnOnce<ElseFn, ::sus::fn::NonVoid (void)>
!std::is_reference_v<T>
!std::is_reference_v<sus::fn::ReturnOnce<ElseFn>>
sus::fn::FnOnce<ElseFn, ::sus::fn::NonVoid (void)>
!std::is_reference_v<T>
!std::is_reference_v<sus::fn::ReturnOnce<ElseFn>>
sus::mem::CopyOrRef<T>
Transforms the Option<T> into a
Result<T, E>, mapping Some(v) to Ok(v) and
None to Err(f()).
Consumes and returns an option with the same value if this option contains
a value, otherwise returns the option returned by f.
Consumes and returns an option with the same value if this option contains
a value, otherwise returns that option.
Replaces whatever the option is currently holding with value and returns
an Option holding what was there previously, which may be empty.
Returns a new option containing whatever was inside the current option.
If this option contains None then it is left unchanged and returns an
option containing None. If this option contains Some with a value, the
value is moved into the returned option and this option will contain
None afterward.
::sus::result::__private::IsResultType<T>::value
::sus::result::__private::IsResultType<T>::value
sus::mem::CopyOrRef<T>
Transposes an Option of a
Result into a
Result of an
Option.
None will be mapped to Ok(None). Some(Ok(_)) and Some(Err(_)) will
be mapped to Ok(Some(_)) and Err(_).
Returns the contained value inside the option.
The function will panic without a message if the option's state is
currently None.
Returns the contained value inside the option, if there is one. Otherwise,
returns default_result.
Note that if it is non-trivial to construct a default_result, that
unwrap_or_else should be
used instead, as it will only construct the default value if required.
!std::is_reference_v<T>
sus::construct::Default<T>
sus::mem::Copy<T>
Returns the contained value inside the option, if there is one. Otherwise, constructs a default value for the type and returns that.
The option's contained type T must be
Default in order to be constructed with a
default value.
Returns the contained value inside the option, if there is one. Otherwise, returns the result of the given function.
Returns the contained value inside the option.
Safety
It is Undefined Behaviour to call this function when the option's state is
None. The caller is responsible for ensuring the option contains a value
beforehand, and the safer unwrap
or expect should almost always
be preferred. The compiler will typically elide the checks if they program
verified the value appropriately before use in order to not panic.
Unzips an option holding a Tuple of two
values into a Tuple of two
Options.
Option<Tuple<i32, u32>> is unzipped to
Tuple<Option<i32>, Option<u32>>.
If self is Some, the result is a tuple with both options holding the
values from self. Otherwise, the result is a tuple of two options set to
None.
Consumes this option and returns an option holding the value from either
this option or that option if exactly one of them holds a value,
otherwise returns an empty Option.
Zips self with another option.
If self is Some(s) and other is Some(o), this method returns
Some(Tuple(s, o)). Otherwise, None is returned.
Conversions
An operator which returns the state of the option, either Some or
None.
This supports the use of an option in a switch, allowing it to act as a tagged union between "some value" and "no value".
Example
auto x = Option<int>(2);
switch (x) {
case Some:
return sus::move(x).unwrap_unchecked(unsafe_fn);
case None:
return -1;
}
Implicit conversion to std::optional.
When the option is holding a reference, it will not convert. Use map to convert to a pointer or
cloned to create a cloned value.
Operators
Returns a reference to the contained value inside the option.
A shorthand for as_value and
as_value_mut that is less explicit
about const. The returned reference is const if the option is accessed as
const, and is mutable otherwise.
This method allows calling methods directly on the type inside the option
without unwrapping.
To extract the value inside an option, use
unwrap on
an rvalue, and take to move the
contents of an lvalue option to an rvalue.
Panics
The function will panic without a message if the option's state is
currently None.
Implementation Notes
Implementation note: We only allow calling this on an rvalue option if the contained value is a reference, otherwise we are returning a reference to a short-lived object which leads to common C++ memory bugs.
Implementation note: This method is added in addition to the Rust option API because:
- C++ moving is verbose, making
unwrapon lvalues loud. - Unwrapping requires a new lvalue name since C++ doesn't allow name reuse, making variable names bad.
- We also provide
as_valueandas_value_mutfor explicit const/mutable lvalue access but... - It's expected in C++ ecosystems, due to
std::optionaland other pre-existing collection-of-one things to provide access throughoperator*andoperator->.
Returns a pointer to the contained value inside the option.
The pointer is const if the option is const, and is mutable otherwise. This method allows calling methods directly on the type inside the option without unwrapping.
To extract the value inside an option, use
unwrap on
an rvalue, and take to move the
contents of an lvalue option to an rvalue.
Panics
The function will panic without a message if the option's state is
currently None.
Implementation Notes
Implementation note: We only allow calling this on an rvalue option if the contained value is a reference, otherwise we are returning a reference to a short-lived object which leads to common C++ memory bugs.
Implementation note: This method is added in addition to the Rust Option API because:
- C++ moving is verbose, making
unwrapon lvalues loud. - Unwrapping requires a new lvalue name since C++ doesn't allow name reuse, making variable names bad.
- We also provide
as_valueandas_value_mutfor explicit const/mutable lvalue access but... - It's expected in C++ ecosystems, due to
std::optionaland other pre-existing collection-of-one things to provide access throughoperator*andoperator->.
Copy assignment for Option which will
satisfy Copy for Option<T> if
T satisifes Copy.
If T can be trivially copy-assigned, then
Option<T> can also be trivially copy-assigned.
Move assignment for Option which will
satisfy Move for <Option<T> if T
satisifies Move.
If T can be trivially move-assigned, then
Option<T> can also be trivially move-assigned.
When trivially-moved, the Option is copied on move, and the moved-from
Option is unchanged but should still not be used thereafter without
reinitializing it. Use take to
move the value out of the Option when the Option may be used again
afterward, such as with class fields.