home | help 
std::tuple(3)		       C++ Standard Libary		   std::tuple(3)

NAME
     std::tuple - std::tuple

Synopsis
	Defined in header <tuple>
	template< class... Types >  (since C++11)
	class tuple;

	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::tu-
     ple, the
	program is ill-formed, no diagnostic required.

Template parameters
	Types... - the types of the elements that the tuple stores.  Empty  list
     is supported.

Member functions
	constructor   constructs a new tuple
		      (public member function)
	operator=     assigns the contents of one tuple to another
		      (public member function)
	swap	      swaps the contents of two tuples
		      (public member function)

Non-member functions
	make_tuple	       creates a tuple object of the type defined by the
     argument
	(C++11) 	      types
			      (function template)
	tie		      creates a tuple of lvalue references or unpacks  a
     tuple into
	(C++11) 	      individual objects
			      (function template)
	forward_as_tuple      creates a tuple of forwarding references
	(C++11) 	      (function template)
	tuple_cat	      creates a tuple by concatenating any number of tu-
     ples
	(C++11) 	      (function template)
	get(std::tuple)       tuple accesses specified element
	(C++11) 	      (function template)
	operator==
	operator!=
	operator<
	operator<=
	operator>
	operator>=	      lexicographically compares the values in the tuple
	operator<=>	      (function template)
	(removed in C++20)
	(removed in C++20)
	(removed in C++20)
	(removed in C++20)
	(removed in C++20)
	(C++20)
	std::swap(std::tuple) specializes the std::swap algorithm
	(C++11) 	      (function template)

	Helper concepts

	tuple-like specifies that a type implemented the tuple protocol
	pair-like  (std::get, std::tuple_element, std::tuple_size)
	(C++23)    (exposition-only concept*)

Helper classes
	std::tuple_size<std::tuple>		 obtains  the  size  of tuple at
     compile time
	(C++11) 				(class template specialization)
	std::tuple_element<std::tuple>		obtains the type of  the  speci-
     fied element
	(C++11) 				(class template specialization)
	std::uses_allocator<std::tuple> 	 specializes the std::uses_allo-
     cator type
	(C++11) 				trait
						(class template specialization)
	std::basic_common_reference<tuple-like> determines the common  reference
     type of a
	(C++23) 				tuple and a tuple-like type
						(class template specialization)
	std::common_type<tuple-like>		 determines the common type of a
     tuple and a
	(C++23) 				tuple-like type
						(class template specialization)
	std::formatter<std::tuple>		formatting support for tuple
	(C++23) 				(class template specialization)
	ignore					placeholder to skip  an  element
     when
	(C++11) 				unpacking a tuple using tie
						(constant)

	Deduction guides (since C++17)

Notes
	Since  the "shape" of a tuple a its size, the types of its elements, and
     the ordering
	of those types a are part of its type signature, they must all be avail-
     able at
	compile time and can only depend on other compile-time information. This
     means that
	many conditional operations  on  tuples  a  in	particular,  conditional
     prepend/append
	and  filter  a	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
	a  e.g.  returning a std::tuple<int, int> a but not to filter on whether
     or not each
	element is positive (which would have a different type signature depend-
     ing 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 N4387
	  return std::tuple<int, int>{1, -1}; // Always works
	  return std::make_tuple(1, -1); // Always works
      }

Example
     // Run this code

      #include <iostream>
      #include <stdexcept>
      #include <string>
      #include <tuple>

      std::tuple<double, char, std::string> get_student(int id)
      {
	  switch (id)
	  {
	      case 0: return {3.8, 'A', "Lisa Simpson"};
	      case 1: return {2.9, 'C', "Milhouse Van Houten"};
	      case 2: return {1.7, 'D', "Ralph Wiggum"};
	      case 3: return {0.6, 'F', "Bart Simpson"};
	  }

	  throw std::invalid_argument("id");
      }

      int main()
      {
	  const auto student0 = get_student(0);
	  std::cout << "ID: 0, "
		    << "GPA: " << std::get<0>(student0) << ", "
		    << "grade: " << std::get<1>(student0) << ", "
		    << "name: " << std::get<2>(student0) << '\n';

	  const auto 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:
	  const auto [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

	Defect reports

	The  following	behavior-changing  defect  reports were applied retroac-
     tively to
	previously published C++ standards.

	   DR	 Applied to	    Behavior as  published		 Correct
     behavior
	LWG 2796 C++11	    triviality of the destructor of	   specified
			    std::tuple was unspecified
								   the	 program
     is ill-formed
	LWG 3990 C++11	    a program could declare an explicit or in this
			    partial specialization of std::tuple   case (no  di-
     agnostic
								   required)

References
	  * C++23 standard (ISO/IEC 14882:2023):

	  * 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]

See also
	pair implements binary tuple, i.e. a pair of values
	     (class template)

http://cppreference.com 	   2024.06.10			   std::tuple(3)
home | help