class Option

Declaration

template <class T>
class Option { /* full declaration omitted */ };

Description

The [`Option`]($sus::option::Option) type. See the [namespace level documentation]($sus::option) for more.

Declared at: sus/option/option.h:467

Templates

T

Method Overview

• public constexpr Option<T>(const T & t) noexcept
• public template <class U>constexpr Option<T>(const std::optional<U> & s) noexcept
• public template <class U>constexpr Option<T>(std::optional<U> && s) noexcept
• public Option<T>(const Option<T> & o)
• public Option<T>(const Option<T> & o)
• public Option<T>(Option<T> && o)
• public Option<T>(Option<T> && o)
• public inline Option<T>() noexcept
• public template <class U>constexpr Option<T>(U && u) noexcept
• public template <class U>constexpr Option<T>(U && u) noexcept
• public template <class U>constexpr Option<T>(const Option<U> & other)
• public template <class U>constexpr Option<T>(Option<U> && other)
• public template <class U>constexpr Option<T>(Option<U> && other)
• public template <class U>constexpr Option<U> and_that(Option<U> that) const & noexcept
• public template <class U>constexpr Option<U> and_that(Option<U> that) && noexcept
• public template <class AndFn>constexpr sus::fn::ReturnOnce<AndFn, T &&> and_then(AndFn f) && noexcept
• public template <class AndFn>constexpr sus::fn::ReturnOnce<AndFn, T &&> and_then(AndFn f) const & noexcept
• public constexpr Option<T &> as_mut() && noexcept
• public constexpr Option<T &> as_mut() const & noexcept
• public constexpr Option<T &> as_mut() & noexcept
• public constexpr Option<const std::remove_reference_t<T> &> as_ref() const & noexcept
• public constexpr Option<const std::remove_reference_t<T> &> as_ref() && noexcept
• public constexpr const std::remove_reference_t<T> & as_value() const & noexcept
• public constexpr const std::remove_reference_t<T> & as_value() && noexcept
• public constexpr std::remove_reference_t<T> & as_value_mut() & noexcept
• public constexpr std::remove_reference_t<T> & as_value_mut() && noexcept
• public constexpr std::remove_reference_t<T> & as_value_mut() const & noexcept
• public constexpr const std::remove_reference_t<T> & as_value_unchecked(::sus::marker::UnsafeFnMarker) const & noexcept
• public constexpr const std::remove_reference_t<T> & as_value_unchecked(::sus::marker::UnsafeFnMarker) && noexcept
• public constexpr std::remove_reference_t<T> & as_value_unchecked_mut(::sus::marker::UnsafeFnMarker) & noexcept
• public constexpr std::remove_reference_t<T> & as_value_unchecked_mut(::sus::marker::UnsafeFnMarker) && noexcept
• public constexpr std::remove_reference_t<T> & as_value_unchecked_mut(::sus::marker::UnsafeFnMarker) const & noexcept
• public constexpr Option<T> clone() const & noexcept
• public constexpr void clone_from(const Option<T> & source) & noexcept
• public constexpr Option<std::remove_const_t<std::remove_reference_t<T>>> cloned() const & noexcept
• public constexpr Option<std::remove_const_t<std::remove_reference_t<T>>> copied() const & noexcept
• public constexpr T expect(const char * _Nonnull message) const & noexcept
• public constexpr T expect(const char * _Nonnull message) && noexcept
• public template <class p:auto>constexpr Option<T> filter(::sus::fn::FnOnce<bool (const std::remove_reference_t<T> &)> auto p) const & noexcept
• public template <class p:auto>constexpr Option<T> filter(::sus::fn::FnOnce<bool (const std::remove_reference_t<T> &)> auto p) && noexcept
• public constexpr T flatten() const & noexcept
• public constexpr T flatten() && noexcept
• public template <class U>static constexpr Option<T> from(U && val) noexcept
• public template <class U>static constexpr Option<T> from(U && val) noexcept
• public template <class Iter>static constexpr Option<T> from_product(Iter && it) noexcept
• public template <class Iter>static constexpr Option<T> from_sum(Iter && it) noexcept
• public template <class U>constexpr T & get_or_insert(U && value) & noexcept
• public constexpr T & get_or_insert(T value) & noexcept
• public constexpr T & get_or_insert_default() & noexcept
• public template <class f:auto>constexpr T & get_or_insert_with(::sus::fn::FnOnce<T ()> auto f) & noexcept
• public constexpr T & insert(T value) & noexcept
• public template <class U>constexpr T & insert(U && value) & noexcept
• public constexpr OptionIter<T> into_iter() const & noexcept
• public constexpr OptionIter<T> into_iter() && noexcept
• public constexpr bool is_none() const noexcept
• public constexpr bool is_some() const noexcept
• public constexpr OptionIter<const std::remove_reference_t<T> &> iter() const & noexcept
• public constexpr OptionIter<const std::remove_reference_t<T> &> iter() && noexcept
• public constexpr OptionIter<const std::remove_reference_t<T> &> iter() const & noexcept
• public constexpr OptionIter<T &> iter_mut() & noexcept
• public constexpr OptionIter<T &> iter_mut() && noexcept
• public constexpr OptionIter<T &> iter_mut() const & noexcept
• public template <class MapFn>constexpr Option<sus::fn::ReturnOnce<MapFn, T &&>> map(MapFn m) const & noexcept
• public template <class MapFn>constexpr Option<sus::fn::ReturnOnce<MapFn, T &&>> map(MapFn m) && noexcept
• public template <class MapFn>constexpr sus::fn::ReturnOnce<MapFn, T &&> map_or(sus::fn::ReturnOnce<MapFn, T &&> default_result, MapFn m) const & noexcept
• public template <class MapFn>constexpr sus::fn::ReturnOnce<MapFn, T &&> map_or(sus::fn::ReturnOnce<MapFn, T &&> default_result, MapFn m) && noexcept
• public template <class DefaultFn, class MapFn>constexpr sus::fn::ReturnOnce<DefaultFn> map_or_else(DefaultFn default_fn, MapFn m) const & noexcept
• public template <class DefaultFn, class MapFn>constexpr sus::fn::ReturnOnce<DefaultFn> map_or_else(DefaultFn default_fn, MapFn m) && noexcept
• public template <class E, int &... , class Result = ::sus::result::Result<T, E>>constexpr Result ok_or(E e) && noexcept
• public template <class E, int &... , class Result = ::sus::result::Result<T, E>>constexpr Result ok_or(E e) const & noexcept
• public template <class ElseFn>constexpr sus::result::Result<T, sus::fn::ReturnOnce<ElseFn>> ok_or_else(ElseFn f) && noexcept
• public template <class ElseFn>constexpr sus::result::Result<T, sus::fn::ReturnOnce<ElseFn>> ok_or_else(ElseFn f) const & noexcept
• public template <class U>constexpr std::optional<U> operator optional<type-parameter-1-0>() const & noexcept
• public template <class U>constexpr std::optional<U> operator optional<type-parameter-1-0>() && noexcept
• public constexpr sus::option::State operator sus::option::State() const &
• public template <class f:auto>constexpr Option<T> or_else(::sus::fn::FnOnce<Option<T> ()> auto f) && noexcept
• public template <class f:auto>constexpr Option<T> or_else(::sus::fn::FnOnce<Option<T> ()> auto f) const & noexcept
• public constexpr Option<T> or_that(Option<T> that) const & noexcept
• public constexpr Option<T> or_that(Option<T> that) && noexcept
• public constexpr Option<T> replace(T value) & noexcept
• public template <class U>constexpr Option<T> replace(U && value) & noexcept
• public constexpr Option<T> take() & noexcept
• public template <int &... , class OkType = typename ::sus::result::__private::IsResultType<T>::ok_type, class ErrType = typename ::sus::result::__private::IsResultType<T>::err_type, class Result = ::sus::result::Result<Option<OkType>, ErrType>>constexpr Result transpose() && noexcept
• public template <int &... , class OkType = typename ::sus::result::__private::IsResultType<T>::ok_type, class ErrType = typename ::sus::result::__private::IsResultType<T>::err_type, class Result = ::sus::result::Result<Option<OkType>, ErrType>>constexpr Result transpose() const & noexcept
• public constexpr T unwrap() const & noexcept
• public constexpr T unwrap() && noexcept
• public constexpr T unwrap_or(T default_result) && noexcept
• public constexpr T unwrap_or(T default_result) const & noexcept
• public constexpr T unwrap_or_default() const & noexcept
• public constexpr T unwrap_or_default() && noexcept
• public template <class f:auto>constexpr T unwrap_or_else(::sus::fn::FnOnce<T ()> auto f) && noexcept
• public template <class f:auto>constexpr T unwrap_or_else(::sus::fn::FnOnce<T ()> auto f) const & noexcept
• public inline constexpr T unwrap_unchecked(::sus::marker::UnsafeFnMarker) && noexcept
• public inline constexpr T unwrap_unchecked(::sus::marker::UnsafeFnMarker) const & noexcept
• public constexpr auto unzip() && noexcept
• public constexpr auto unzip() const & noexcept
• public constexpr Option<T> xor_that(Option<T> that) const & noexcept
• public constexpr Option<T> xor_that(Option<T> that) && noexcept
• public template <class U, int &... , class Tuple = ::sus::tuple_type::Tuple<T, U>>constexpr Option<Tuple> zip(Option<U> o) && noexcept
• public template <class U, int &... , class Tuple = ::sus::tuple_type::Tuple<T, U>>constexpr Option<Tuple> zip(Option<U> o) const & noexcept
• public ~Option<T>() noexcept
• public ~Option<T>() noexcept

Methods

¶constexpr Option<T>(const T& t) noexcept

Description

Construct an option that is holding the given value. # Const References For [`Option <const T & >`]($sus::option::Option) 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`]($sus::construct::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. #[doc.overloads=ctor.some]

Declared at: sus/option/option.h:502

Parameters

const T& t

¶template <class U>
constexpr Option<T>(
    const std::optional<U>& s) noexcept

Description

#[doc.overloads=ctor.optional]

Declared at: sus/option/option.h:1904

Templates

U

Parameters

const std::optional<U>& s

¶template <class U>
constexpr Option<T>(std::optional<U>&& s) noexcept

Description

Implicit conversion from [`std::optional`]( https://en.cppreference.com/w/cpp/utility/optional). #[doc.overloads=ctor.optional]

Declared at: sus/option/option.h:1897

Templates

U

Parameters

std::optional<U>&& s

¶Option<T>(const Option<T>& o)

Description

Copy constructor for [`Option <T >`]($sus::option::Option) which will satisfy [`Copy <Option <T >>`]($sus::mem::Copy) if [`Copy <T >`]($sus::mem::Copy) is satisfied. If `T` can be trivially copy-constructed, then `Option <T >` can also be trivially copy-constructed. #[doc.overloads=copy]

Declared at: sus/option/option.h:621

Parameters

const Option<T>& o

¶Option<T>(const Option<T>& o)

Description

Copy constructor for [`Option <T >`]($sus::option::Option) which will satisfy [`Copy <Option <T >>`]($sus::mem::Copy) if [`Copy <T >`]($sus::mem::Copy) is satisfied. If `T` can be trivially copy-constructed, then `Option <T >` can also be trivially copy-constructed. #[doc.overloads=copy]

Declared at: sus/option/option.h:621

Parameters

const Option<T>& o

¶Option<T>(Option<T>&& o)

Description

Move constructor for [`Option <T >`]($sus::option::Option) which will satisfy [`Move <Option <T >>`]($sus::mem::Move) if [`Move <T >`]($sus::mem::Move) 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. #[doc.overloads=move]

Declared at: sus/option/option.h:640

Parameters

Option<T>&& o

¶Option<T>(Option<T>&& o)

Description

Move constructor for [`Option <T >`]($sus::option::Option) which will satisfy [`Move <Option <T >>`]($sus::mem::Move) if [`Move <T >`]($sus::mem::Move) 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. #[doc.overloads=move]

Declared at: sus/option/option.h:640

Parameters

Option<T>&& o

¶inline Option<T>() noexcept

Description

Default-construct an option that is holding no value. This satisfies [`Default`]($sus::construct::Default) for [`Option`]($sus::option::Option). #[doc.overloads=ctor.none]

Declared at: sus/option/option.h:484

¶template <class U>
constexpr Option<T>(U&& u) noexcept

Description

#[doc.overloads=ctor.some]

Declared at: sus/option/option.h:509

Templates

U

Parameters

U&& u

¶template <class U>
constexpr Option<T>(U&& u) noexcept

Description

#[doc.overloads=ctor.some]

Declared at: sus/option/option.h:509

Templates

U

Parameters

U&& u

¶template <class U>
constexpr Option<T>(const Option<U>& other)

Description

Converts from `Option <X >` to `Option <Y >` if `X` is convertible to `Y`. #[doc.overloads=ctor.convert]

Declared at: sus/option/option.h:527

Templates

U

Parameters

const Option<U>& other

¶template <class U>
constexpr Option<T>(Option<U>&& other)

Description

#[doc.overloads=ctor.convert]

Declared at: sus/option/option.h:532

Templates

U

Parameters

Option<U>&& other

¶template <class U>
constexpr Option<T>(Option<U>&& other)

Description

#[doc.overloads=ctor.convert]

Declared at: sus/option/option.h:532

Templates

U

Parameters

Option<U>&& other

¶template <class U>
constexpr Option<U> and_that(
    Option<U> that) const& noexcept

Declared at: sus/option/option.h:1312

Templates

U

Parameters

Option<U> that

¶template <class U>
constexpr Option<U> and_that(
    Option<U> that) && noexcept

Description

Consumes this option and returns an option with `None` if this option holds `None`, otherwise returns `that` option.

Declared at: sus/option/option.h:1303

Templates

U

Parameters

Option<U> that

¶template <class AndFn>
constexpr sus::fn::ReturnOnce<AndFn, T&&>
and_then(AndFn f) && noexcept

Description

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 >`]($sus::option::Option). Some languages call this operation flatmap.

Declared at: sus/option/option.h:1328

Templates

AndFn

Parameters

AndFn f

¶template <class AndFn>
constexpr sus::fn::ReturnOnce<AndFn, T&&>
and_then(AndFn f) const& noexcept

Declared at: sus/option/option.h:1338

Templates

AndFn

Parameters

AndFn f

¶constexpr Option<T&> as_mut() && noexcept

Declared at: sus/option/option.h:1671

¶constexpr Option<T&> as_mut() const& noexcept

Declared at: sus/option/option.h:1679

¶constexpr Option<T&> as_mut() & noexcept

Description

Returns an [`Option <T & >`]($sus::option::Option) from this [`Option <T >`]($sus::option::Option), that either holds `None` or a reference to the value in this option.

Declared at: sus/option/option.h:1662

¶constexpr Option<
    const std::remove_reference_t<T>&>
as_ref() const& noexcept

Description

Returns an [`Option <const T & >`]($sus::option::Option) from this [`Option <T >`]($sus::option::Option), 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.

Declared at: sus/option/option.h:1639

¶constexpr Option<
    const std::remove_reference_t<T>&>
as_ref() && noexcept

Declared at: sus/option/option.h:1648

¶constexpr const std::remove_reference_t<T>&
as_value() const& noexcept

Description

Returns a const reference to the contained value inside the option. To extract the value inside an option, use [`unwrap`]($sus::option::Option::unwrap) on an rvalue, and [`take`]($sus::option::Option::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.

Declared at: sus/option/option.h:883

¶constexpr const std::remove_reference_t<T>&
as_value() && noexcept

Declared at: sus/option/option.h:888

¶constexpr std::remove_reference_t<T>&
as_value_mut() & noexcept

Description

Returns a mutable reference to the contained value inside the option. To extract the value inside an option, use [`unwrap`]($sus::option::Option::unwrap) on an rvalue, and [`take`]($sus::option::Option::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.

Declared at: sus/option/option.h:911

¶constexpr std::remove_reference_t<T>&
as_value_mut() && noexcept

Declared at: sus/option/option.h:915

¶constexpr std::remove_reference_t<T>&
as_value_mut() const& noexcept

Declared at: sus/option/option.h:921

¶constexpr const std::remove_reference_t<T>&
    as_value_unchecked(
        ::sus::marker::UnsafeFnMarker)
        const& noexcept

Description

Returns a const reference to the contained value inside the option. To extract the value inside an option, use [`unwrap_unchecked`]($sus::option::Option::unwrap_unchecked) on an rvalue, and [`take`]($sus::option::Option::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.

Declared at: sus/option/option.h:942

Parameters

::sus::marker::UnsafeFnMarker

¶constexpr const std::remove_reference_t<T>&
as_value_unchecked(
    ::sus::marker::UnsafeFnMarker) && noexcept

Declared at: sus/option/option.h:946

Parameters

::sus::marker::UnsafeFnMarker

¶constexpr std::remove_reference_t<T>&
as_value_unchecked_mut(
    ::sus::marker::UnsafeFnMarker) & noexcept

Description

Returns a mutable reference to the contained value inside the option. To extract the value inside an option, use [`unwrap_unchecked`]($sus::option::Option::unwrap_unchecked) on an rvalue, and [`take`]($sus::option::Option::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.

Declared at: sus/option/option.h:967

Parameters

::sus::marker::UnsafeFnMarker

¶constexpr std::remove_reference_t<T>&
as_value_unchecked_mut(
    ::sus::marker::UnsafeFnMarker) && noexcept

Declared at: sus/option/option.h:971

Parameters

::sus::marker::UnsafeFnMarker

¶constexpr std::remove_reference_t<T>&
    as_value_unchecked_mut(
        ::sus::marker::UnsafeFnMarker)
        const& noexcept

Declared at: sus/option/option.h:977

Parameters

::sus::marker::UnsafeFnMarker

¶constexpr Option<T> clone() const& noexcept

Description

Satisifies the [`Clone`]($sus::mem::Clone) concept when `Option` is not [`Copy`]($sus::mem::Copy).

Declared at: sus/option/option.h:688

¶constexpr void clone_from(
    const Option<T>& source) & noexcept

Description

Satisifies the [`CloneFrom`]($sus::mem::CloneFrom) concept.

Declared at: sus/option/option.h:698

Parameters

const Option<T>& source

¶constexpr Option<std::remove_const_t<
    std::remove_reference_t<T>>>
cloned() const& noexcept

Description

Maps an [`Option <T & >`]($sus::option::Option) to an [`Option <T >`]($sus::option::Option) by cloning the referenced `T`.

Declared at: sus/option/option.h:1595

¶constexpr Option<std::remove_const_t<
    std::remove_reference_t<T>>>
copied() const& noexcept

Description

Maps an [`Option <T & >`]($sus::option::Option) to an [`Option <T >`]($sus::option::Option) by copying the referenced `T`.

Declared at: sus/option/option.h:1580

¶constexpr T expect(
    const char* _Nonnull message) const& noexcept

Declared at: sus/option/option.h:758

Parameters

const char* _Nonnull message

¶constexpr T expect(
    const char* _Nonnull message) && noexcept

Description

Returns the contained value inside the option. The function will panic with the given `message` if the option's state is currently `None`.

Declared at: sus/option/option.h:752

Parameters

const char* _Nonnull message

¶template <class p : auto>
constexpr Option<T> filter(
    ::sus::fn::FnOnce<bool(
        const std::remove_reference_t<T>&)> auto
        p) const& noexcept

Declared at: sus/option/option.h:1292

Templates

p:auto

Parameters

::sus::fn::FnOnce<bool( const std::remove_reference_t<T>&)> auto p

¶template <class p : auto>
constexpr Option<T> filter(
    ::sus::fn::FnOnce<bool(
        const std::remove_reference_t<T>&)> auto
        p) && noexcept

Declared at: sus/option/option.h:1275

Templates

p:auto

Parameters

::sus::fn::FnOnce<bool( const std::remove_reference_t<T>&)> auto p

¶constexpr T flatten() const& noexcept

Declared at: sus/option/option.h:1623

¶constexpr T flatten() && noexcept

Description

Maps an [`Option <Option <T >>`]($sus::option::Option) to an [`Option <T >`]($sus::option::Option).

Declared at: sus/option/option.h:1615

¶template <class U>
static constexpr Option<T> from(U&& val) noexcept

Description

Moves or copies `val` into a new option holding `Some(val)`. Implements [`From <Option <T >, T>`]($sus::construct::From). #[doc.overloads=from.t]

Declared at: sus/option/option.h:548

Templates

U

Parameters

U&& val

¶template <class U>
static constexpr Option<T> from(U&& val) noexcept

Description

Moves or copies `val` into a new option holding `Some(val)`. Implements [`From <Option <T >, T>`]($sus::construct::From). #[doc.overloads=from.t]

Declared at: sus/option/option.h:548

Templates

U

Parameters

U&& val

¶template <class Iter>
static constexpr Option<T> from_product(
    Iter&& it) noexcept

Description

Computes the product of an iterator over [`Option <T >`]($sus::option::Option) 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 >>`]($sus::iter::Product). The product is computed using the implementation of the inner type `T` which also satisfies [`sus::iter::Product <T >`]($sus::iter::Product).

Declared at: sus/option/option.h:575

Templates

Iter

Parameters

Iter&& it

¶template <class Iter>
static constexpr Option<T> from_sum(
    Iter&& it) noexcept

Description

Computes the sum of an iterator over [`Option <T >`]($sus::option::Option) 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 >>`]($sus::iter::Sum). The sum is computed using the implementation of the inner type `T` which also satisfies [`sus::iter::Sum <T >`]($sus::iter::Sum).

Declared at: sus/option/option.h:592

Templates

Iter

Parameters

Iter&& it

¶template <class U>
constexpr T& get_or_insert(U&& value) & noexcept

Declared at: sus/option/option.h:1133

Templates

U

Parameters

U&& value

¶constexpr T& get_or_insert(T value) & noexcept

Description

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`]($sus::option::Option::get_or_insert_with) method would be preferable, as it only constructs a `T` if needed.

Declared at: sus/option/option.h:1123

Parameters

T value

¶constexpr T& get_or_insert_default() & noexcept

Description

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`]($sus::option::Option::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`]($sus::construct::Default) so it can be constructed with its default value.

Declared at: sus/option/option.h:1158

¶template <class f : auto>
constexpr T& get_or_insert_with(
    ::sus::fn::FnOnce<T()> auto f) & noexcept

Declared at: sus/option/option.h:1173

Templates

f:auto

Parameters

::sus::fn::FnOnce<T()> auto f

¶constexpr T& insert(T value) & noexcept

Description

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`]($sus::option::Option::get_or_insert), which doesn’t update the value if the option already contains `Some`.

Declared at: sus/option/option.h:1101

Parameters

T value

¶template <class U>
constexpr T& insert(U&& value) & noexcept

Declared at: sus/option/option.h:1109

Templates

U

Parameters

U&& value

¶constexpr OptionIter<T> into_iter()
    const& noexcept

Declared at: sus/option/option.h:1710

¶constexpr OptionIter<T> into_iter() && noexcept

Description

Produces an [`Iterator`]($sus::iter::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.

Declared at: sus/option/option.h:1709

¶constexpr bool is_none() const noexcept

Description

Returns whether the option is currently empty, containing no value.

Declared at: sus/option/option.h:725

¶constexpr bool is_some() const noexcept

Description

Returns whether the option currently contains a value. If there is a value present, it can be extracted with [`unwrap`]($sus::option::Option::unwrap) or [`expect`]($sus::option::Option::expect). For lvalues, it can be accessed as a reference through [`as_value`]($sus::option::Option::as_value) and [`as_value_mut`]($sus::option::Option::as_value_mut) for explicit const/mutable access, or through [`operator*`]($sus::option::Option::operator*) and [`operator->`]($sus::option::Option::operator->).

Declared at: sus/option/option.h:721

¶constexpr OptionIter<
    const std::remove_reference_t<T>&>
iter() const& noexcept

Description

Produces an [`Iterator`]($sus::iter::Iterator) over the single item in the `Option`, or an empty iterator. The iterator will return a const reference.

Declared at: sus/option/option.h:1688

¶constexpr OptionIter<
    const std::remove_reference_t<T>&>
iter() && noexcept

Declared at: sus/option/option.h:1690

¶constexpr OptionIter<
    const std::remove_reference_t<T>&>
iter() const& noexcept

Description

Produces an [`Iterator`]($sus::iter::Iterator) over the single item in the `Option`, or an empty iterator. The iterator will return a const reference.

Declared at: sus/option/option.h:1688

¶constexpr OptionIter<T&> iter_mut() & noexcept

Description

Produces an [`Iterator`]($sus::iter::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.

Declared at: sus/option/option.h:1699

¶constexpr OptionIter<T&> iter_mut() && noexcept

Declared at: sus/option/option.h:1700

¶constexpr OptionIter<T&> iter_mut()
    const& noexcept

Declared at: sus/option/option.h:1702

¶template <class MapFn>
constexpr Option<sus::fn::ReturnOnce<MapFn, T&&>>
map(MapFn m) const& noexcept

Declared at: sus/option/option.h:1213

Templates

MapFn

Parameters

MapFn m

¶template <class MapFn>
constexpr Option<sus::fn::ReturnOnce<MapFn, T&&>>
map(MapFn m) && noexcept

Description

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 >`]($sus::option::Option) where `R` is the return type of the map function. Returns an [`Option <R >`]($sus::option::Option) in state `None` if the current option is in state `None`.

Declared at: sus/option/option.h:1204

Templates

MapFn

Parameters

MapFn m

¶template <class MapFn>
constexpr sus::fn::ReturnOnce<MapFn, T&&> map_or(
    sus::fn::ReturnOnce<MapFn, T&&>
        default_result,
    MapFn m) const& noexcept

Declared at: sus/option/option.h:1237

Templates

MapFn

Parameters

sus::fn::ReturnOnce<MapFn, T&&> default_result

MapFn m

¶template <class MapFn>
constexpr sus::fn::ReturnOnce<MapFn, T&&> map_or(
    sus::fn::ReturnOnce<MapFn, T&&>
        default_result,
    MapFn m) && noexcept

Description

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`]($sus::option::Option::map_or_else), which is lazily evaluated.

Declared at: sus/option/option.h:1227

Templates

MapFn

Parameters

sus::fn::ReturnOnce<MapFn, T&&> default_result

MapFn m

¶template <class DefaultFn, class MapFn>
constexpr sus::fn::ReturnOnce<DefaultFn>
map_or_else(DefaultFn default_fn,
            MapFn m) const& noexcept

Declared at: sus/option/option.h:1261

Templates

DefaultFn

MapFn

Parameters

DefaultFn default_fn

MapFn m

¶template <class DefaultFn, class MapFn>
constexpr sus::fn::ReturnOnce<DefaultFn>
map_or_else(DefaultFn default_fn,
            MapFn m) && noexcept

Description

Computes a default function result (if none), or applies a different function to the contained value (if any).

Declared at: sus/option/option.h:1250

Templates

DefaultFn

MapFn

Parameters

DefaultFn default_fn

MapFn m

¶template <
    class E,
    int&...,
    class Result = ::sus::result::Result<T, E>>
constexpr Result ok_or(E e) && noexcept

Description

Transforms the [`Option <T >`]($sus::option::Option) into a [`Result <T , E>`]($sus::result::Result), 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`]($sus::option::Option::ok_or_else), which is lazily evaluated.

Declared at: sus/option/option.h:1411

Templates

E

int &

Result

Parameters

E e

¶template <
    class E,
    int&...,
    class Result = ::sus::result::Result<T, E>>
constexpr Result ok_or(E e) const& noexcept

Declared at: sus/option/option.h:1420

Templates

E

int &

Result

Parameters

E e

¶template <class ElseFn>
constexpr sus::result::
    Result<T, sus::fn::ReturnOnce<ElseFn>>
    ok_or_else(ElseFn f) && noexcept

Description

Transforms the [`Option <T >`]($sus::option::Option) into a [`Result <T , E>`]($sus::result::Result), mapping `Some(v)` to `Ok(v)` and `None` to `Err(f())`.

Declared at: sus/option/option.h:1433

Templates

ElseFn

Parameters

ElseFn f

¶template <class ElseFn>
constexpr sus::result::
    Result<T, sus::fn::ReturnOnce<ElseFn>>
    ok_or_else(ElseFn f) const& noexcept

Declared at: sus/option/option.h:1445

Templates

ElseFn

Parameters

ElseFn f

¶template <class U>
constexpr std::optional<U> operator optional<
    type - parameter - 1 - 0>() const& noexcept

Description

Implicit conversion to [`std::optional`]( https://en.cppreference.com/w/cpp/utility/optional). When the option is holding a reference, it will not convert. Use [`map`]( $sus::option::Option::map) to convert to a pointer or [`cloned`]($sus::option::Option::cloned) to create a cloned value.

Declared at: sus/option/option.h:1916

Templates

U

¶template <class U>
constexpr std::optional<U> operator optional<
    type - parameter - 1 - 0>() && noexcept

Declared at: sus/option/option.h:1926

Templates

U

¶constexpr sus::option::State
operator sus::option::State() const&

Description

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 ```cpp auto x = Option <int >(2); switch (x) { case Some: return sus::move(x).unwrap_unchecked(unsafe_fn); case None: return -1; } ```

Declared at: sus/option/option.h:746

¶template <class f : auto>
constexpr Option<T> or_else(
    ::sus::fn::FnOnce<Option<T>()> auto
        f) && noexcept

Declared at: sus/option/option.h:1360

Templates

f:auto

Parameters

::sus::fn::FnOnce<Option<T>()> auto f

¶template <class f : auto>
constexpr Option<T> or_else(
    ::sus::fn::FnOnce<Option<T>()> auto f)
    const& noexcept

Declared at: sus/option/option.h:1367

Templates

f:auto

Parameters

::sus::fn::FnOnce<Option<T>()> auto f

¶constexpr Option<T> or_that(
    Option<T> that) const& noexcept

Declared at: sus/option/option.h:1352

Parameters

Option<T> that

¶constexpr Option<T> or_that(
    Option<T> that) && noexcept

Description

Consumes and returns an option with the same value if this option contains a value, otherwise returns `that` option.

Declared at: sus/option/option.h:1346

Parameters

Option<T> that

¶constexpr Option<T> replace(T value) & noexcept

Description

Replaces whatever the option is currently holding with `value` and returns an `Option` holding what was there previously, which may be empty.

Declared at: sus/option/option.h:1554

Parameters

T value

¶template <class U>
constexpr Option<T> replace(U&& value) & noexcept

Declared at: sus/option/option.h:1566

Templates

U

Parameters

U&& value

¶constexpr Option<T> take() & noexcept

Description

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.

Declared at: sus/option/option.h:1187

¶template <int&...,
          class OkType = typename ::sus::result::
              __private::IsResultType<T>::ok_type,
          class ErrType =
              typename ::sus::result::__private::
                  IsResultType<T>::err_type,
          class Result = ::sus::result::
              Result<Option<OkType>, ErrType>>
constexpr Result transpose() && noexcept

Description

Transposes an [`Option`]($sus::option::Option) of a [`Result`]($sus::result::Result) into a [`Result`]($sus::result::Result) of an [`Option`]($sus::option::Option). `None` will be mapped to `Ok(None)`. `Some(Ok(_))` and `Some(Err(_))` will be mapped to `Ok(Some(_))` and `Err(_)`.

Declared at: sus/option/option.h:1468

Templates

int &

OkType

ErrType

Result

¶template <int&...,
          class OkType = typename ::sus::result::
              __private::IsResultType<T>::ok_type,
          class ErrType =
              typename ::sus::result::__private::
                  IsResultType<T>::err_type,
          class Result = ::sus::result::
              Result<Option<OkType>, ErrType>>
constexpr Result transpose() const& noexcept

Declared at: sus/option/option.h:1489

Templates

int &

OkType

ErrType

Result

¶constexpr T unwrap() const& noexcept

Declared at: sus/option/option.h:774

¶constexpr T unwrap() && noexcept

Description

Returns the contained value inside the option. The function will panic without a message if the option's state is currently `None`.

Declared at: sus/option/option.h:770

¶constexpr T unwrap_or(
    T default_result) && noexcept

Description

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`]($sus::option::Option::unwrap_or_else) should be used instead, as it will only construct the default value if required.

Declared at: sus/option/option.h:786

Parameters

T default_result

¶constexpr T unwrap_or(
    T default_result) const& noexcept

Declared at: sus/option/option.h:793

Parameters

T default_result

¶constexpr T unwrap_or_default() const& noexcept

Declared at: sus/option/option.h:830

¶constexpr T unwrap_or_default() && noexcept

Description

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`]($sus::construct::Default) in order to be constructed with a default value.

Declared at: sus/option/option.h:820

¶template <class f : auto>
constexpr T unwrap_or_else(
    ::sus::fn::FnOnce<T()> auto f) && noexcept

Declared at: sus/option/option.h:801

Templates

f:auto

Parameters

::sus::fn::FnOnce<T()> auto f

¶template <class f : auto>
constexpr T unwrap_or_else(
    ::sus::fn::FnOnce<T()> auto f) const& noexcept

Declared at: sus/option/option.h:808

Templates

f:auto

Parameters

::sus::fn::FnOnce<T()> auto f

¶inline constexpr T unwrap_unchecked(
    ::sus::marker::UnsafeFnMarker) && noexcept

Description

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`]($sus::option::Option::unwrap) or [`expect`]($sus::option::Option::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.

Declared at: sus/option/option.h:848

Parameters

::sus::marker::UnsafeFnMarker

¶inline constexpr T unwrap_unchecked(
    ::sus::marker::UnsafeFnMarker) const& noexcept

Declared at: sus/option/option.h:859

Parameters

::sus::marker::UnsafeFnMarker

¶constexpr auto unzip() && noexcept

Description

Unzips an option holding a [`Tuple`]($sus::tuple_type::Tuple) of two values into a [`Tuple`]($sus::tuple_type::Tuple) of two [`Option`]($sus::option::Option)s. [`Option <Tuple <i32 , u32>>`]($sus::option::Option) is unzipped to [`Tuple <Option <i32 >, Option <u32 >>`]($sus::tuple_type::Tuple). 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.

Declared at: sus/option/option.h:1531

¶constexpr auto unzip() const& noexcept

Declared at: sus/option/option.h:1545

¶constexpr Option<T> xor_that(
    Option<T> that) const& noexcept

Declared at: sus/option/option.h:1394

Parameters

Option<T> that

¶constexpr Option<T> xor_that(
    Option<T> that) && noexcept

Description

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`.

Declared at: sus/option/option.h:1377

Parameters

Option<T> that

¶template <
    class U,
    int&...,
    class Tuple = ::sus::tuple_type::Tuple<T, U>>
constexpr Option<Tuple> zip(
    Option<U> o) && noexcept

Description

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.

Declared at: sus/option/option.h:1500

Templates

U

int &

Tuple

Parameters

Option<U> o

¶template <
    class U,
    int&...,
    class Tuple = ::sus::tuple_type::Tuple<T, U>>
constexpr Option<Tuple> zip(
    Option<U> o) const& noexcept

Declared at: sus/option/option.h:1515

Templates

U

int &

Tuple

Parameters

Option<U> o

¶~Option<T>() noexcept

Description

Destructor for the option. Destroys the value contained within the option, if there is one. If `T` can be trivially destroyed, we don't need to explicitly destroy it, so we can use the default destructor, which allows [`Option <T >`]($sus::option::Option) to also be trivially destroyed.

Declared at: sus/option/option.h:603

¶~Option<T>() noexcept

Description

Destructor for the option. Destroys the value contained within the option, if there is one. If `T` can be trivially destroyed, we don't need to explicitly destroy it, so we can use the default destructor, which allows [`Option <T >`]($sus::option::Option) to also be trivially destroyed.

Declared at: sus/option/option.h:603