std::tuple
Defined in header <tuple> | ||
template<class... Types> class tuple; | (since C++11) | |
Class template std::tuple is a fixed-size collection of heterogeneous values. It is a generalization of std::pair.
If std::is_trivially_destructible<Ti>::value is true for every Ti in Types, the destructor of std::tuple is trivial.
If a program declares an explicit or partial specialization of std::tuple, the program is ill-formed, no diagnostic required.
Contents |
[edit]Template parameters
| Types... | - | the types of the elements that the tuple stores. Empty list is supported. |
[edit]Member functions
constructs a new tuple(public member function) | |
assigns the contents of one tuple to another (public member function) | |
swaps the contents of two tuples (public member function) |
[edit]Non-member functions
(C++11) | creates a tuple object of the type defined by the argument types (function template) |
(C++11) | creates a tuple of lvalue references or unpacks a tuple into individual objects (function template) |
(C++11) | creates a tuple of forwarding references(function template) |
(C++11) | creates a tuple by concatenating any number of tuples (function template) |
(C++11) | tuple accesses specified element (function template) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) | lexicographically compares the values in the tuple (function template) |
(C++11) | specializes the std::swap algorithm (function template) |
[edit]Helper concepts
(C++23) | specifies that a type implemented the tuple protocol (std::get, std::tuple_element, std::tuple_size) (exposition-only concept*) |
[edit]Helper classes
(C++11) | obtains the size of a |
| obtains the type of the specified element (class template specialization) | |
| specializes the std::uses_allocator type trait (class template specialization) | |
determines the common reference type of a tuple and a tuple-like type (class template specialization) | |
(C++23) | determines the common type of a tuple and a tuple-like type (class template specialization) |
(C++23) | formatting support for tuple(class template specialization) |
(C++11) | placeholder to skip an element when unpacking a tuple using tie(constant) |
[edit]Helper specializations
template<class... Ts> constexprbool enable_nonlocking_formatter_optimization<std::tuple<Ts...>> | (since C++23) | |
This specialization of std::enable_nonlocking_formatter_optimization enables efficient implementation of std::print and std::println for printing a tuple object when each element type enables it.
[edit]Deduction guides(since C++17)
[edit]Notes
Since the "shape" of a tuple – its size, the types of its elements, and the ordering of those types – are part of its type signature, they must all be available at compile time and can only depend on other compile-time information. This means that many conditional operations on tuples – in particular, conditional prepend/append and filter – are only possible if the conditions can be evaluated at compile time. For example, given a std::tuple<int, double, int>, it is possible to filter on types – e.g. returning a std::tuple<int, int> – but not to filter on whether or not each element is positive (which would have a different type signature depending on runtime values of the tuple), unless all the elements were themselves constexpr.
As a workaround, one can work with tuples of std::optional, but there is still no way to adjust the size based on runtime information.
Until N4387 (applied as a defect report for C++11), a function could not return a tuple using copy-list-initialization:
std::tuple<int, int> foo_tuple(){return{1, -1};// Error until N4387return std::tuple<int, int>{1, -1};// Always worksreturnstd::make_tuple(1, -1);// Always works}
[edit]Example
#include <iostream>#include <stdexcept>#include <string>#include <tuple> std::tuple<double, char, std::string> get_student(int id){switch(id){case0:return{3.8, 'A', "Lisa Simpson"};case1:return{2.9, 'C', "Milhouse Van Houten"};case2:return{1.7, 'D', "Ralph Wiggum"};case3:return{0.6, 'F', "Bart Simpson"};} throwstd::invalid_argument("id");} int main(){constauto student0 = get_student(0);std::cout<<"ID: 0, "<<"GPA: "<< std::get<0>(student0)<<", "<<"grade: "<< std::get<1>(student0)<<", "<<"name: "<< std::get<2>(student0)<<'\n'; constauto student1 = get_student(1);std::cout<<"ID: 1, "<<"GPA: "<< std::get<double>(student1)<<", "<<"grade: "<< std::get<char>(student1)<<", "<<"name: "<< std::get<std::string>(student1)<<'\n'; double gpa2;char grade2;std::string name2;std::tie(gpa2, grade2, name2)= get_student(2);std::cout<<"ID: 2, "<<"GPA: "<< gpa2 <<", "<<"grade: "<< grade2 <<", "<<"name: "<< name2 <<'\n'; // C++17 structured binding:constauto[gpa3, grade3, name3]= get_student(3);std::cout<<"ID: 3, "<<"GPA: "<< gpa3 <<", "<<"grade: "<< grade3 <<", "<<"name: "<< name3 <<'\n';}
Output:
ID: 0, GPA: 3.8, grade: A, name: Lisa Simpson ID: 1, GPA: 2.9, grade: C, name: Milhouse Van Houten ID: 2, GPA: 1.7, grade: D, name: Ralph Wiggum ID: 3, GPA: 0.6, grade: F, name: Bart Simpson
[edit]Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 2796 | C++11 | triviality of the destructor of std::tuple was unspecified | specified |
| LWG 3990 | C++11 | a program could declare an explicit or partial specialization of std::tuple | the program is ill-formed in this case (no diagnostic required) |
[edit]References
- C++23 standard (ISO/IEC 14882:2024):
- 22.4 Tuples [tuple]
- C++20 standard (ISO/IEC 14882:2020):
- 20.5 Tuples [tuple]
- C++17 standard (ISO/IEC 14882:2017):
- 23.5 Tuples [tuple]
- C++14 standard (ISO/IEC 14882:2014):
- 20.4 Tuples [tuple]
- C++11 standard (ISO/IEC 14882:2011):
- 20.4 Tuples [tuple]
[edit]See also
| implements binary tuple, i.e. a pair of values (class template) |
