class Tuple

Declaration

template <class T, class... Ts>
class Tuple { /* full declaration omitted */ };

Description

A Tuple is a finite sequence of one or more heterogeneous values. The Tuple is similar to [std::tuple](https://en.cppreference.com/w/cpp/utility/tuple) with some differences: * It allows storing reference types. * It interacts with iterators through satisfying [`Extend`]($sus::iter::Extend), allowing an iterator to `unzip()` into a Tuple of collections that satisfy Extend. * It provides explicit methods for const, mutable or rvalue access to its values. * It satisfies [`Clone`]($sus::mem::Clone) if its elements all satisfy `Clone`. Tuple elements can also be accessed through `get()` for code that wants to work generically over tuple-like objects including `sus::Tuple` and `std::tuple`. # Tail padding The Tuple's tail padding may be reused when the Tuple is marked as `[[no_unique_address]]`. The Tuple will have tail padding if the first type has a size that is not a multiple of the Tuple's alignment. For example if it's smaller than the alignment, such as `Tuple <u8 , u64>` which has `(alignof(u64) == sizeof(u64)) - sizeof(u8)` or 7 bytes of tail padding. ``` struct S { [[no_unique_address]] Tuple <u32 , u64> tuple; // 16 bytes. u32 val; // 4 bytes. }; // 16 bytes, since `val` is stored inside `tuple`. ``` However note that this behaviour is compiler-dependent, and MSVC does not use the `[[no_unique_address]]` hint. Use `sus::data_size_of <T >()` to determine the size of T excluding its tail padding (so `sus::size_of <T >() - sus::data_size_of <T >()` is the tail padding), which can be useful to ensure you have the expected behaviour from your types. Additionally types within the tuple may be placed inside the tail padding of other types in the tuple, should such padding exist. Generally, but not always, use of tail padding in Tuple is optimized by ordering types (left-to-right in the template variables) from smallest-to- largest for simple types such as integers (which have no tail padding themselves), or in least-to-most tail-padding for more complex types. Elements in a Tuple are stored internally in reverse of the order they are specified, which is why the size of the *first* element matters for the Tuple's externally usable tail padding.

Declared at: sus/tuple/tuple.h:104

Templates

T

Ts

Method Overview

• public inline constexpr Tuple<T, Ts...>() noexcept
• public inline constexpr Tuple<T, Ts...>() noexcept
• public template <class U, class... Us>constexpr Tuple<T, Ts...>(U && first, Us &&... more) noexcept
• public template <class U, class... Us>constexpr Tuple<T, Ts...>(const Tuple<U, Us...> & tuple) noexcept
• public template <class U, class... Us>constexpr Tuple<T, Ts...>(Tuple<U, Us...> && tuple) noexcept
• public template <size_t I>inline constexpr const auto & at() const & noexcept
• public template <size_t I>inline constexpr const auto & at() &&
• public template <size_t I>inline constexpr auto & at_mut() & noexcept
• public constexpr Tuple<T, Ts...> clone() const & noexcept
• public template <class U, class... Us, class ii:auto>constexpr void extend(::sus::iter::IntoIterator<Tuple<U, Us...>> auto && ii) noexcept
• public template <size_t I>inline constexpr decltype(auto) into_inner() && noexcept

Methods

¶inline constexpr Tuple<T, Ts...>() noexcept

Description

Construct a Tuple with the default value for the types it contains. The Tuple's contained types must all be #Default, and will be constructed through that trait. #[doc.overloads=ctor.default]

Declared at: sus/tuple/tuple.h:112

¶inline constexpr Tuple<T, Ts...>() noexcept

Description

Construct a Tuple with the default value for the types it contains. The Tuple's contained types must all be #Default, and will be constructed through that trait. #[doc.overloads=ctor.default]

Declared at: sus/tuple/tuple.h:112

¶template <class U, class... Us>
constexpr Tuple<T, Ts...>(U&& first,
                          Us&&... more) noexcept

Description

Construct a Tuple with the given values. # Const References For `Result <const T & , E>` 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 `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 it =)). #[doc.overloads=ctor.values]

Declared at: sus/tuple/tuple.h:148

Templates

U

Us

Parameters

U&& first

Us&&... more

¶template <class U, class... Us>
constexpr Tuple<T, Ts...>(
    const Tuple<U, Us...>& tuple) noexcept

Description

Converts from `Tuple <X ', Y', Z'>` to `Tuple <X , Y, Z>` when `X'`, `Y'`, and `Z'` can be converted to `X`, `Y`, and `Z`. #[doc.overloads=ctor.convert]

Declared at: sus/tuple/tuple.h:186

Templates

U

Us

Parameters

const Tuple<U, Us...>& tuple

¶template <class U, class... Us>
constexpr Tuple<T, Ts...>(
    Tuple<U, Us...>&& tuple) noexcept

Description

#[doc.overloads=ctor.convert]

Declared at: sus/tuple/tuple.h:208

Templates

U

Us

Parameters

Tuple<U, Us...>&& tuple

¶template <size_t I>
inline constexpr const auto& at() const& noexcept

Description

Gets a const reference to the `I`th element in the tuple.

Declared at: sus/tuple/tuple.h:226

Templates

size_t I

¶template <size_t I>
inline constexpr const auto& at() &&

Declared at: sus/tuple/tuple.h:231

Templates

size_t I

¶template <size_t I>
inline constexpr auto& at_mut() & noexcept

Description

Gets a mutable reference to the `I`th element in the tuple.

Declared at: sus/tuple/tuple.h:236

Templates

size_t I

¶constexpr Tuple<T, Ts...> clone() const& noexcept

Description

sus::mem::Clone trait.

Declared at: sus/tuple/tuple.h:164

¶template <class U, class... Us, class ii : auto>
constexpr void extend(
    ::sus::iter::IntoIterator<
        Tuple<U, Us...>> auto&& ii) noexcept

Description

Satisfies sus::iter::Extend for a Tuple of collections that each satisfies Extend for its position-relative type in the iterator of tuples. The tuple this is called on is a set of collections. The iterable passed in as an argument yields tuples of items that will be appended to the collections. The item types in the argument can not be deduced, so they must be explicitly specified by the caller, such as: ```cpp collections.extend <i32 , std::string>(iter_over_tuples_i32_string()); ``` Allows to `extend` a tuple of collections that also implement `Extend`. See also: `IteratorBase::unzip`.

Declared at: sus/tuple/tuple.h:358

Templates

U

Us

ii:auto

Parameters

::sus::iter::IntoIterator<Tuple<U, Us...>> auto&& ii

¶template <size_t I>
inline constexpr decltype(auto)
into_inner() && noexcept

Description

Removes the `I`th element from the tuple, leaving the Tuple in a moved-from state where it should no longer be used.

Declared at: sus/tuple/tuple.h:244

Templates

size_t I