|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Member functions | ||||
| Non-member functions | ||||
(until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20) | ||||
| Helper concepts | ||||
(C++23) | ||||
| Helper classes | ||||
(C++23) | ||||
(C++23) | ||||
| Deduction guides(C++17) |
Defined in header <tuple> | ||
template<class...Types> class tuple; | (since C++11) | |
Class templatestd::tuple is a fixed-size collection of heterogeneous values. It is a generalization ofstd::pair.
Ifstd::is_trivially_destructible<Ti>::value istrue for everyTi inTypes, the destructor ofstd::tuple is trivial.
If a program declares anexplicit orpartial specialization ofstd::tuple, the program is ill-formed, no diagnostic required.
Contents |
| Types... | - | the types of the elements that the tuple stores. Empty list is supported. |
constructs a newtuple(public member function)[edit] | |
assigns the contents of onetuple to another(public member function)[edit] | |
swaps the contents of twotuples(public member function)[edit] |
(C++11) | creates atuple object of the type defined by the argument types(function template)[edit] |
(C++11) | creates atuple of lvalue references or unpacks a tuple into individual objects (function template)[edit] |
(C++11) | creates atuple offorwarding references(function template)[edit] |
(C++11) | creates atuple by concatenating any number of tuples(function template)[edit] |
(C++11) | tuple accesses specified element (function template)[edit] |
(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)[edit] |
(C++11) | specializes thestd::swap algorithm (function template)[edit] |
(C++23) | specifies that a type implemented thetuple protocol (std::get,std::tuple_element,std::tuple_size) (exposition-only concept*)[edit] |
(C++11) | obtains the size of a |
| obtains the type of the specified element (class template specialization)[edit] | |
| specializes thestd::uses_allocator type trait (class template specialization)[edit] | |
determines the common reference type of atuple and atuple-like type(class template specialization)[edit] | |
(C++23) | determines the common type of atuple and atuple-like type(class template specialization)[edit] |
(C++23) | formatting support fortuple(class template specialization)[edit] |
(C++11) | placeholder to skip an element when unpacking atuple usingtie(constant)[edit] |
template<class...Ts> constexprbool enable_nonlocking_formatter_optimization<std::tuple<Ts...>> | (since C++23) | |
This specialization ofstd::enable_nonlocking_formatter_optimization enables efficient implementation ofstd::print andstd::println for printing atuple object when each element type enables it.
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 astd::tuple<int,double,int>, it is possible to filter on types – e.g. returning astd::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 themselvesconstexpr.
As a workaround, one can work with tuples ofstd::optional, but there is still no way to adjust the size based on runtime information.
UntilN4387 (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}
#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 SimpsonID: 1, GPA: 2.9, grade: C, name: Milhouse Van HoutenID: 2, GPA: 1.7, grade: D, name: Ralph WiggumID: 3, GPA: 0.6, grade: F, name: Bart Simpson
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 ofstd::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) |
| implements binary tuple, i.e. a pair of values (class template)[edit] |
