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

NAME
     std::reverse_copy - std::reverse_copy

Synopsis
	Defined in header <algorithm>
	template< class BidirIt, class OutputIt >

	OutputIt  reverse_copy( BidirIt first, BidirIt last,	  (1) (constexpr
     since C++20)

			       OutputIt d_first );
	template< class ExecutionPolicy, class BidirIt, class
	ForwardIt >

	ForwardIt  reverse_copy(  ExecutionPolicy&&  policy,	     (2)  (since
     C++17)
				BidirIt first, BidirIt last,

				ForwardIt d_first );

	1)  Given  \(\scriptsize  N\)N as std::distance(first, last). Copies the
     elements from
	the range [first, last) (source range) to another range of \(\scriptsize
     N\)N
	elements beginning at d_first (destination range) in such a way that the
     elements in
	the destination range are in reverse order.
	Behaves as if by executing the assignment *(d_first +  N  -  1	-  i)  =
     *(first + i)^[1]
	once for each integer i in [0, N).
	If source and destination ranges overlap, the behavior is undefined.
	2) Same as (1), but executed according to policy.
	This overload participates in overload resolution only if

	std::is_execution_policy_v<std::decay_t<ExecutionPolicy>>    is    true.
     (until
										  C++20)
	std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>      is
     true. (since
										  C++20)

Parameters
	first, last	 -	the range of elements to copy
	d_first 	 -	the beginning of the destination range

Type requirements
	-
	BidirIt must meet the requirements of LegacyBidirectionalIterator.
	-
	OutputIt must meet the requirements of LegacyOutputIterator.
	-
	ForwardIt must meet the requirements of LegacyForwardIterator.

Return value
	Output iterator to the element past the last element copied.

Complexity
	Exactly \(\scriptsize N\)N assignments.

Exceptions
	The overload with a template parameter named ExecutionPolicy reports er-
     rors as
	follows:

	  *  If  execution of a function invoked as part of the algorithm throws
     an exception
	    and ExecutionPolicy is one of the standard policies,  std::terminate
     is called.
	    For  any  other  ExecutionPolicy, the behavior is implementation-de-
     fined.
	  * If the algorithm fails to allocate memory, std::bad_alloc is thrown.

Possible implementation
	See also the implementations in libstdc++, libc++, and MSVC STL.

	template<class BidirIt, class OutputIt>
	constexpr // since C++20
	OutputIt reverse_copy(BidirIt first, BidirIt last, OutputIt d_first)
	{
	    for (; first != last; ++d_first)
		*d_first = *(--last);
	    return d_first;
	}

Notes
	Implementations (e.g. MSVC STL) may enable vectorization when  the  both
     iterator
	types satisfy LegacyContiguousIterator and have the same value type, and
     the value
	type is TriviallyCopyable.

Example
     // Run this code

      #include <algorithm>
      #include <iostream>
      #include <vector>

      int main()
      {
	  auto print = [](const std::vector<int>& v)
	  {
	      for (const auto& value : v)
		  std::cout << value << ' ';
	      std::cout << '\n';
	  };

	  std::vector<int> v{1, 2, 3};
	  print(v);

	  std::vector<int> destination(3);
	  std::reverse_copy(std::begin(v),    std::end(v),   std::begin(destina-
     tion));
	  print(destination);

	  std::reverse_copy(std::rbegin(v),  std::rend(v),   std::begin(destina-
     tion));
	  print(destination);
      }

Output:
      1 2 3
      3 2 1
      1 2 3

	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
			    for each i, the assignment was	  corrected to
	LWG  2074 C++98      *(d_first + N - i) = *(first + i)^[1] *(d_first + N
     - 1 - i) =
								  *(first      +
     i)^[1]
	LWG  2150 C++98      only one element was required to be   corrected the
     requirement
			    assigned

	 1. a ^1.0 ^1.1 ^1.2 LegacyOutputIterator is not required to support bi-
     nary + and -.
	    The usages of + and - here are exposition-only: the actual	computa-
     tion does not
	    need to use them.

See also
	reverse 	     reverses the order of elements in a range
			     (function template)
	ranges::reverse_copy creates a copy of a range that is reversed
	(C++20) 	     (niebloid)

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