Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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 heteroge-
       neous 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.

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 un-
       packs 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
       tuples
	  (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 specializa-
       tion)
	  std::tuple_element<std::tuple>	   obtains  the	 type  of  the
       specified element
	  (C++11)				   (class template specializa-
       tion)
	  std::uses_allocator<std::tuple>		specializes	   the
       std::uses_allocator type
	  (C++11)				  trait
						  (class  template specializa-
       tion)
	  std::basic_common_reference<tuple-like> determines the common	refer-
       ence type of a
	  (C++23)				  tuple	and a tuple-like type
						  (class template  specializa-
       tion)
	  std::common_type<tuple-like>		   determines  the common type
       of a tuple and a
	  (C++23)				  tuple-like type
						  (class template  specializa-
       tion)
	  std::formatter<std::tuple>		  formatting support for tuple
	  (C++23)				   (class template specializa-
       tion)
	  ignore				  placeholder to skip an  ele-
       ment when
	  (C++11)				  unpacking a tuple using tie
						  (constant)

	  Deduction guides (since C++17)

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 de-
       pending on
	  runtime values of the	tuple),	unless all  the	 elements  were	 them-
       selves 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		  Cor-
       rect behavior
	  LWG 2796 C++11      triviality of the	destructor of	     specified
			      std::tuple was unspecified
								     the  pro-
       gram is ill-formed
	  LWG 3990 C++11      a	program	could declare an explicit or in	this
			      partial specialization of	std::tuple   case  (no
       diagnostic
								     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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::tuple&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help