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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::apply - std::apply

Synopsis
	  Defined in header <tuple>
	  template<	    class	 F,	   class	Tuple	     >
       (since C++17)
	  constexpr   decltype(auto)   apply(	F&&   f,    Tuple&&    t    );
       (until C++23)
	  template< class F, tuple-like	Tuple >
	  constexpr  decltype(auto)  apply( F&&	f, Tuple&& t ) noexcept(/* see
       (since C++23)
	  below	*/);

	  Invoke the Callable object f with the	elements of t as arguments.

	  Given	the exposition-only function apply-impl	 defined  as  follows:
       template<class
	  F,class Tuple, std::size_t...	I>
	  constexpr decltype(auto)
	      apply-impl(F&& f,	Tuple&&	t, std::index_sequence<I...>) // expo-
       sition only
	  {
	      return  INVOKE(std::forward<F>(f),  std::get<I>(std::forward<Tu-
       ple>(t))...);
	  }

	  The effect is	equivalent to return apply-impl(std::forward<F>(f),
	  std::forward<Tuple>(t),
			    std::make_index_sequence<
				std::tuple_size_v<std::decay_t<Tuple>>>{}); .

Parameters
	  f - Callable object to be invoked
	  t - tuple whose elements to be used as arguments to f

Return value
	  The value returned by	f.

Exceptions
	  (none)
       (until
										  C++23)
	  noexcept specification:
	  noexcept(

	      noexcept(std::invoke(std::forward<F>(f),
				   std::get<Is>(std::forward<Tuple>(t))...))
       (since
										  C++23)
	  )

	  where	Is... denotes the parameter pack:

	    * 0, 1, ...,  std::tuple_size_v<std::remove_reference_t<Tuple>>  -
       1.

Notes
	  Tuple	need not be std::tuple,	and instead may	be anything that
	  supports std::get and	std::tuple_size; in particular,	std::array and
       (until C++23)
	  std::pair may	be used.
	  Tuple	is constrained to be tuple-like, i.e. each type	therein	is
	  required  to be a specialization of std::tuple or another type (such
       as (since C++23)
	  std::array and std::pair) that models	tuple-like.

	  Feature-test macro  Value    Std    Feature
	  __cpp_lib_apply    201603L (C++17) std::apply

Example
       // Run this code

	#include <iostream>
	#include <tuple>
	#include <utility>

	int add(int first, int second) { return	first +	second;	}

	template<typename T>
	T add_generic(T	first, T second) { return first	+ second; }

	auto add_lambda	= [](auto first, auto second) {	return first + second;
       };

	template<typename... Ts>
	std::ostream& operator<<(std::ostream&	os,  std::tuple<Ts...>	const&
       theTuple)
	{
	    std::apply
	    (
		[&os](Ts const&... tupleArgs)
		{
		    os << '[';
		    std::size_t	n{0};
		    ((os  << tupleArgs << (++n != sizeof...(Ts)	? ", " : "")),
       ...);
		    os << ']';
		}, theTuple
	    );
	    return os;
	}

	int main()
	{
	    // OK
	    std::cout << std::apply(add, std::pair(1, 2)) << '\n';

	    // Error: can't deduce the function	type
	    //	std::cout  <<	std::apply(add_generic,	  std::make_pair(2.0f,
       3.0f)) << '\n';

	    // OK
	    std::cout  <<  std::apply(add_lambda,  std::pair(2.0f,  3.0f))  <<
       '\n';

	    // advanced	example
	    std::tuple myTuple{25, "Hello", 9.31f, 'c'};
	    std::cout << myTuple << '\n';
	}

Output:
	3
	5
	[25, Hello, 9.31, c]

See also
	  make_tuple	   creates a tuple object of the type defined  by  the
       argument	types
	  (C++11)	   (function template)
	  forward_as_tuple creates a tuple of forwarding references
	  (C++11)	   (function template)
	  make_from_tuple  construct an	object with a tuple of arguments
	  (C++17)	   (function template)
	  invoke	   invokes any Callable	object with given arguments
	  invoke_r	   and possibility to specify return type
	  (C++17)	   (since C++23)
	  (C++23)	   (function template)

Category:
	    * conditionally noexcept

http://cppreference.com		  2024.06.10			 std::apply(3)

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

home | help