Documentation of type_safe

( foonathan/type_safe)

Header file optional_ref.hpp

namespace type_safe
{
    template <typename T, bool XValue>
    class reference_optional_storage;
    
    template <typename T>
    using optional_ref = basic_optional<reference_optional_storage<T>>;
    
    template <typename T>
    optional_ref<T> opt_ref(const object_ref<T>& ref) noexcept;
    
    template <typename T>
    optional_ref<const T> opt_cref(const object_ref<T>& ref) noexcept;
    
    template <typename T>
    optional_ref<T> opt_ref(optional<T>& opt) noexcept;
    
    template <typename T>
    optional_ref<const T> opt_cref(optional<T>& opt) noexcept;
    
    template <typename T>
    optional_ref<T> opt_ref(T* ptr) noexcept;
    
    template <typename T>
    optional_ref<const T> opt_cref(const T* ptr) noexcept;
    
    template <typename T>
    using optional_xvalue_ref = basic_optional<reference_optional_storage<T, true>>;
    
    template <typename T>
    optional_xvalue_ref<T> opt_xref(T* ptr) noexcept;
    
    template <typename T>
    optional<typename std::remove_const<T>::type> copy(const optional_ref<T>& ref);
    
    template <typename T>
    optional<T> move(const optional_xvalue_ref<T>& ref) noexcept('hidden');
}

Class template type_safe::reference_optional_storage [optional]

template <typename T, bool XValue>
class reference_optional_storage
{
public:
    using value_type = object_ref<T, XValue>;
    
    using lvalue_reference = T&;
    
    using const_lvalue_reference = lvalue_reference;
    
    using rvalue_reference = 'hidden';
    
    using const_rvalue_reference = rvalue_reference;
    
    template <typename U>
    using rebind = reference_optional_storage<U, XValue>;
    
    reference_optional_storage() noexcept;
    
    template <typename U>
    )>void create_value(const basic_optional<reference_optional_storage<U, XValue>>& ref);
    
    void create_value(const reference_optional_storage& other) noexcept;
    
    void create_value(const object_ref<T, XValue>& other) noexcept;
    
    void create_value(std::nullptr_t) noexcept;
    
    template <typename U>
    )>void create_value_explicit(U& obj) noexcept;
    
    void create_value_explicit(T&&) = delete;
    
    void copy_value(const reference_optional_storage& other) noexcept;
    
    void swap_value(reference_optional_storage& other) noexcept;
    
    void destroy_value() noexcept;
    
    bool has_value() const noexcept;
    
    'hidden' get_value() const noexcept;
    
    'hidden' get_value_or(lvalue_reference other) const noexcept;
    
    result_type get_value_or(T&&) const = delete;
};

A StoragePolicy for ts::basic_optional that allows optional references.

The actual value_type passed to the optional is ts::object_ref, but the reference types are normal references, so value() will return a T& and value_or() takes a fallback reference of the same type and returns one of them. Assigning an optional will always change the target of the reference. You cannot pass rvalues.

If XValue is true, you still cannot pass rvalues, but the result of value()/value_or() will return an rvalue reference, to allow moving of the stored value into something else.

Depending on the const-ness of T is the reference to const or non-const as well, unless XValue is true, in which caseTmust not beconst`.

Default constructor type_safe::reference_optional_storage::reference_optional_storage

reference_optional_storage() noexcept;

Effects: Creates it without a bound reference.

Function template type_safe::reference_optional_storage::create_value

template <typename U>
)>void create_value(const basic_optional<reference_optional_storage<U, XValue>>& ref);

Effects: Binds the same reference as stored in the optional.

Notes: This function only participates in overload resolution, if U is a reference compatible with T.

Function type_safe::reference_optional_storage::create_value

void create_value(const reference_optional_storage& other) noexcept;

Effects: Binds the reference to the same reference as in other.

Function type_safe::reference_optional_storage::create_value

void create_value(const object_ref<T, XValue>& other) noexcept;

Effects: Binds the reference to the same reference as in ref.

Function type_safe::reference_optional_storage::create_value

void create_value(std::nullptr_t) noexcept;

Effects: Same as destroy_value().

Function template type_safe::reference_optional_storage::create_value_explicit

template <typename U>
)>void create_value_explicit(U& obj) noexcept;

Effects: Binds the reference to obj.

Notes: This function only participates in overload resolution, if U is a reference compatible with T.

Function type_safe::reference_optional_storage::copy_value

void copy_value(const reference_optional_storage& other) noexcept;

Effects: Binds the reference to the same reference in other.

Function type_safe::reference_optional_storage::swap_value

void swap_value(reference_optional_storage& other) noexcept;

Effects: Swaps the reference with the reference in other, i.e. rebinds them, no value change.

Function type_safe::reference_optional_storage::destroy_value

void destroy_value() noexcept;

Effects: Unbinds the reference.

Function type_safe::reference_optional_storage::has_value

bool has_value() const noexcept;

Returns: true if the reference is bound, false otherwise.

Function type_safe::reference_optional_storage::get_value

'hidden' get_value() const noexcept;

Returns: The target of the reference. Depending on XValue, this will either be T& or T&&.

Function type_safe::reference_optional_storage::get_value_or

'hidden' get_value_or(lvalue_reference other) const noexcept;

Returns: Either get_value() or other. This must be given an lvalue of type T and it returns either an lvalue or an rvalue, depending on XValue.


Alias template type_safe::optional_ref [optional]

template <typename T>
using optional_ref = basic_optional<reference_optional_storage<T>>;

A ts::basic_optional that uses ts::reference_optional_storage. It is an optional reference.

Notes: T is the type without the reference, i.e. optional_ref<int>.

Function template type_safe::opt_ref [optional]

template <typename T>
optional_ref<T> opt_ref(const object_ref<T>& ref) noexcept;

Returns: A ts::optional_ref to the same target as ref.

Function template type_safe::opt_cref [optional]

template <typename T>
optional_ref<const T> opt_cref(const object_ref<T>& ref) noexcept;

Returns: A ts::optional_ref to const to the same target as ref.

Function template type_safe::opt_ref [optional]

template <typename T>
optional_ref<T> opt_ref(optional<T>& opt) noexcept;

Returns: A ts::optional_ref to the stored value in opt.

Function template type_safe::opt_cref [optional]

template <typename T>
optional_ref<const T> opt_cref(optional<T>& opt) noexcept;

Returns: A ts::optional_ref to const to the stored value in opt.

Function template type_safe::opt_ref [optional]

template <typename T>
optional_ref<T> opt_ref(T* ptr) noexcept;

Returns: A ts::optional_ref<T> to the pointee of ptr or nullopt.

Function template type_safe::opt_cref [optional]

template <typename T>
optional_ref<const T> opt_cref(const T* ptr) noexcept;

Returns: A ts::optional_ref<T> to const to the pointee of ptr or nullopt.

Alias template type_safe::optional_xvalue_ref [optional]

template <typename T>
using optional_xvalue_ref = basic_optional<reference_optional_storage<T, true>>;

A ts::basic_optional that uses ts::reference_optional_storage with XValue being true. It is an optional reference to an xvalue, i.e. an lvalue that can be moved from, like returned by std::move().

Notes: T is the type without the reference, i.e. optional_xvalue_ref<int>.

Function template type_safe::opt_xref [optional]

template <typename T>
optional_xvalue_ref<T> opt_xref(T* ptr) noexcept;

Returns: A ts::optional_xvalue_ref<T> to the pointee of ptr or nullopt.

Notes: The pointee will be moved from when you call value().

Function template type_safe::copy [optional]

template <typename T>
optional<typename std::remove_const<T>::type> copy(const optional_ref<T>& ref);

Returns: A ts::optional<T> containing a copy of the value of ref if there is any value.

Requires: T must be copyable.

Function template type_safe::move [optional]

template <typename T>
optional<T> move(const optional_xvalue_ref<T>& ref) noexcept('hidden');

Returns: A ts::optional<T> containing a copy of the value of ref created by move constructing if there is any value.

Requires: T must be moveable.