--- title: "tuple" --- {{< callout type="info">}} Header: `tuple.h` Similar to: `std::tuple` {{< /callout >}} C++11 and above. A fixed-size collection of heterogeneous values. ```cpp template class tuple ``` ## Traits ```cpp template struct is_tuple ``` Type trait to check if a type is an `etl::tuple` ## Types ```cpp using value_type = THead; ///< The type contained by this tuple. using this_type = tuple; ///< The type of this tuple. using base_type = tuple; ///< The type of the base tuple. using type_list = etl::type_list; ///< The type list for this tuple. using index_sequence_type = etl::make_index_sequence< number_of_types< THead, TTail...>()>; ///< The index_sequence type for this tuple. ``` ## Constants ```cpp inline constexpr private_tuple::ignore_t ignore; ``` From: C++17 --- ```cpp static constexpr private_tuple::ignore_t ignore; ``` Before: C++17 ## Constructors ```cpp ETL_CONSTEXPR14 tuple() ``` **Description** Default constructor. --- ```cpp ETL_CONSTEXPR14 tuple(const tuple& other) = default; ``` **Description** Copy constructor. --- ```cpp ETL_CONSTEXPR14 tuple(tuple&& other) = default; ``` **Description** Move constructor. --- ```cpp ETL_CONSTEXPR14 tuple& operator=(const tuple& other) = default; ``` **Description** Copy assignment. --- ```cpp ETL_CONSTEXPR14 tuple& operator=(tuple&& other) = default; ``` **Description** Move assignment. --- ```cpp template ETL_CONSTEXPR14 tuple(tuple& other) ``` **Description** Copy construct from lvalue reference tuple type. Implicit conversion. Enabled if:- - The number of `UTypes` == number of `TTypes`. - The number of `TTYpes` >= 1. - `UTypes` are convertible to `TTypes`. --- ```cpp template ETL_CONSTEXPR14 explicit tuple(tuple& other) ``` **Description** Copy construct from lvalue reference tuple type. Explicit conversion. Enabled if:- - The number of `UTypes` == number of `TTypes`. - The number of `TTYpes` >= 1. - `UTypes` are **not** convertible to `TTypes`. --- ```cpp template ETL_CONSTEXPR14 tuple(const tuple& other) ``` **Description** Copy construct from const lvalue reference tuple type. Implicit conversion. Enabled if:- - The number of `UTypes` == number of `TTypes`. - The number of `TTYpes` >= 1. - `UTypes` are convertible to `TTypes`. --- ```cpp template ETL_CONSTEXPR14 explicit tuple(const tuple& other) ``` **Description** Copy construct from const lvalue reference tuple type. Explicit conversion. Enabled if:- - The number of `UTypes` == number of `TTypes`. - The number of `TTYpes` >= 1. - `UTypes` are **not** convertible to `TTypes`. --- ```cpp template ETL_CONSTEXPR14 tuple(tuple&& other) ``` **Description** Move construct from rvalue reference tuple type. Implicit conversion Enabled if:- - The number of `UTypes` == number of `TTypes`. - The number of `TTYpes` >= 1. - `UTypes` are convertible to `TTypes`. --- ```cpp template ETL_CONSTEXPR14 explicit tuple(tuple&& other) ``` **Description** Move construct from rvalue reference tuple type. Explicit conversion. Enabled if:- - The number of `UTypes` == number of `TTypes`. - The number of `TTYpes` >= 1. - `UTypes` are **not** convertible to `TTypes`. --- ```cpp template ETL_CONSTEXPR14 tuple(const tuple&& other) ``` **Description** Move construct from const rvalue reference tuple type. Implicit conversion Enabled if:- - The number of `UTypes` == number of `TTypes`. - The number of `TTYpes` >= 1. - `UTypes` are convertible to `TTypes`. --- ```cpp template ETL_CONSTEXPR14 explicit tuple(const tuple&& other) ``` **Description** Move construct from const rvalue reference tuple type. Explicit conversion. Enabled if:- - The number of `UTypes` == number of `TTypes`. - The number of `TTYpes` >= 1. - `UTypes` are **not** convertible to `TTypes`. --- ```cpp ETL_CONSTEXPR14 tuple(const TTypes&... args) ``` **Description** Construct from arguments. --- ```cpp template ETL_CONSTEXPR14 tuple(UHead&& head, UTail&&... tail) ETL_NOEXCEPT ``` **Description** Construct from arguments. Implicit conversion. Enabled if:- - The number of `UTypes` == number of `TTypes`. - The number of `TTYpes` >= 1. - `UTypes` are not convertible to `TTypes`. --- ```cpp template ETL_CONSTEXPR14 explicit tuple(UHead&& head, UTail&&... tail) ETL_NOEXCEPT ``` **Description** Construct from arguments. Explicit conversion. Enabled if:- - The number of `UTypes` == number of `TTypes`. - The number of `TTYpes` >= 1. - `UTypes` are **not** convertible to `TTypes`. --- ```cpp template & p) ETL_NOEXCEPT ``` **Description** Construct from lvalue reference pair. Implicit conversion. Enabled if:- - The number of `TTYpes` == 2. - `U1` and `U2` are convertible to `TTypes`. --- ```cpp template & p) ETL_NOEXCEPT ``` **Description** Construct from lvalue reference pair. Explicit conversion. Enabled if:- - The number of `TTYpes` == 2. - `U1` or `U2` are not convertible to `TTypes`. --- ```cpp template & p) ETL_NOEXCEPT ``` **Description** Construct from const lvalue reference pair. Implicit conversion. Enabled if:- - The number of `TTYpes` == 2. - `U1` and `U2` are convertible to `TTypes`. --- ```cpp template & p) ETL_NOEXCEPT ``` **Description** Construct from const lvalue reference pair. Explicit conversion. Enabled if:- - The number of `TTYpes` == 2. - `U1` or `U2` are not convertible to `TTypes`. --- ```cpp template && p) ETL_NOEXCEPT ``` **Description** Construct from rvalue reference pair. Implicit conversion. Enabled if:- - The number of `TTYpes` == 2. - `U1` and `U2` are convertible to `TTypes`. --- ```cpp template && p) ETL_NOEXCEPT ``` **Description** Construct from rvalue reference pair. Explicit conversion. Enabled if:- - The number of `TTYpes` == 2. - `U1` or `U2` are not convertible to `TTypes`. --- ```cpp template && p) ETL_NOEXCEPT ``` **Description** Construct from const rvalue reference pair. Implicit conversion. Enabled if:- - The number of `TTYpes` == 2. - `U1` and `U2` are convertible to `TTypes`. --- ```cpp template && p) ETL_NOEXCEPT ``` **Description** Construct from const rvalue reference pair. Explicit conversion. Enabled if:- - The number of `TTYpes` == 2. - `U1` or `U2` are not convertible to `TTypes`. ## Assignment ```cpp template ETL_CONSTEXPR14 tuple& operator=(const tuple& other) ``` **Description** Copy assign from other tuple type. Enabled if:- - The number of `UTypes` == number of `TTypes`. --- ```cpp template ETL_CONSTEXPR14 tuple& operator=(tuple&& other) ``` **Description** Move assign from other tuple type. Enabled if:- - The number of `UTypes` == number of `TTypes`. --- ```cpp template ETL_CONSTEXPR14 tuple& operator=(ETL_OR_STD::pair& p) ``` **Description** Assign from lvalue pair tuple type. Enabled if:- - The number of `TTYpes` == 2. --- ```cpp template ETL_CONSTEXPR14 tuple& operator=(const ETL_OR_STD::pair& p) ``` **Description** Assign from const lvalue pair tuple type. Enabled if:- - The number of `TTYpes` == 2. --- ```cpp template ETL_CONSTEXPR14 tuple& operator=(ETL_OR_STD::pair&& p) ``` **Description** Assign from rvalue pair tuple type. Enabled if:- - The number of `TTYpes` == 2. --- ```cpp template ETL_CONSTEXPR14 tuple& operator=(const ETL_OR_STD::pair&& p) ``` **Description** Assign from const rvalue pair tuple type. Enabled if:- - The number of `TTYpes` == 2. ## Other ```cpp ETL_CONSTEXPR14 void swap(this_type& other) ``` **Description** Swaps this tuple with another. --- ```cpp ETL_NODISCARD constexpr static size_t size() ``` **Description** Returns the number of elements in the tuple. ## Template deduction guides For C++17 and above. ```cpp template tuple(TArgs... args) -> tuple; ``` **Description** From variadic arguments. --- ```cpp template tuple(ETL_OR_STD::pair) -> tuple; ``` From a `pair`. ## Utility classes ```cpp template struct tuple_element> ``` **Description** Gets the element type at `Index` in the tuple. --- ```cpp template struct tuple_size> ``` **Description** Gets the size of the tuple. Derived from `etl::integral_constant`. --- ```cpp template struct common_type> ``` **Description** Gets the common type of a tuple. ## Get an element ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 etl::tuple_element_t>& get(tuple& t) ``` **Description** Extracts the element at `Index` from the tuple. `Index` must be an integer value in [`0`, `sizeof...(TTypes)`). Returns a reference to the value. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 const etl::tuple_element_t>& get(const tuple& t) ``` **Description** Extracts the element at `Index` from the tuple. `Index` must be an integer value in [`0`, `sizeof...(TTypes)`). Returns a const reference to the value. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 etl::tuple_element_t>&& get(tuple&& t) ``` **Description** Extracts the element at `Index` from the tuple. `Index` must be an integer value in [`0`, `sizeof...(TTypes)`). Returns an rvalue reference. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 const etl::tuple_element_t>&& get(const tuple&& t) ``` **Description** Extracts the element at `Index` from the tuple. `Index` must be an integer value in [`0`, `sizeof...(TTypes)`). Returns a const rvalue reference. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 T& get(tuple& t) ``` **Description** Extracts the element with type `T` from the tuple. Static asserts if the tuple contains more than one `T`, or does not contain a `T` element. Returns a reference to the value. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 const T& get(const tuple& t) ``` **Description** Extracts the element with type `T` from the tuple. Static asserts if the tuple contains more than one `T`, or does not contain a `T` element. Returns a const reference to the value. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 T&& get(tuple&& t) ``` **Description** Extracts the element with type `T` from the tuple. Static asserts if the tuple contains more than one `T`, or does not contain a `T` element. Returns an rvalue reference to the value. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 const T&& get(const tuple&& t) ``` **Description** Extracts the element with type `T` from the tuple. Static asserts if the tuple contain more than one `T`, or does not contain a `T` element. Returns a const rvalue reference to the value. --- ```cpp template ETL_CONSTEXPR etl::tuple tie(TTypes&... args) ``` **Description** Create a tuple of references to the provided arguments. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 etl::tuple...> make_tuple(TTypes&&... args) ``` **Description** Create a tuple from the provided arguments. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 auto select_from_tuple(TTuple&& tuple, etl::index_sequence) -> etl::tuple>...> ``` **Description** Create a new tuple by selecting elements from another, given a run time index sequence. Static asserts if the number of indices does not match the tuple size. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 auto select_from_tuple(TTuple&& tuple) -> etl::tuple>...> ``` **Description** Create a new tuple by selecting elements from another, given a template parameter index sequence. Static asserts if the number of indices does not match the tuple size. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 etl::tuple forward_as_tuple(TTypes&&... args) ``` **Description** Forward the arguments as a tuple. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 auto tuple_cat(Tuples&&... t) -> Tuple ``` **Description** Concatenate the list of tuples. --- ## If using the STL Converts an etl::tuple to a std::tuple. ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 auto to_std(const etl::tuple& etl_tuple) -> std::tuple...> ``` **Description** Converts a `const etl::tuple` to a `std::tuple`. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 auto to_std(etl::tuple&& etl_tuple) -> std::tuple...> ``` **Description** Converts an `etl::tuple` to a `std::tuple`. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 auto to_etl(const std::tuple& std_tuple) -> etl::tuple...> ``` **Description** Converts a `const std::tuple` to an `etl::tuple`. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 auto to_etl(std::tuple&& std_tuple) -> etl::tuple...> ``` **Description** Converts a `std::tuple` to an `etl::tuple`. ## Comparisons ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 bool operator==(const etl::tuple& lhs, const etl::tuple& rhs) ``` **Description** Equality operator. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 bool operator!=(const etl::tuple& lhs, const etl::tuple& rhs) ``` **Description** Inequality operator. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 bool operator<(const etl::tuple& lhs, const etl::tuple& rhs) ``` **Description** Less than operator. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 bool operator<=(const etl::tuple& lhs, const etl::tuple& rhs) ``` **Description** Less than or equals operator. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 bool operator>(const etl::tuple& lhs, const etl::tuple& rhs) ``` **Description** Greater than operator. --- ```cpp template ETL_NODISCARD ETL_CONSTEXPR14 bool operator>=(const etl::tuple& lhs, const etl::tuple& rhs) ``` **Description** Greater than or equals operator. ## Swap ```cpp template ETL_CONSTEXPR14 void swap(etl::tuple& lhs, etl::tuple& rhs) ``` **Description** Swap two tuples. ## Helpers ```cpp template struct tuple_from_type_list> ``` **Description** Helper to turn `etl::type_list` into `etl::tuple` --- ```cpp template using tuple_from_type_list_t = typename tuple_from_type_list::type ``` ## STL namespace definitions ```cpp template struct tuple_size> : etl::integral_constant ``` **Description** Specialisation of `tuple_size` to allow the use of C++ structured bindings. --- ```cpp template struct tuple_element> ``` **Description** Specialisation of `tuple_element` to allow the use of C++ structured bindings.