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

NAME
     std::rotate_copy - std::rotate_copy

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

	OutputIt rotate_copy( ForwardIt first, ForwardIt
	n_first,						  (1) (constexpr
     since C++20)

			      ForwardIt last, OutputIt d_first
	);
	template< class ExecutionPolicy,

		  class ForwardIt1, class ForwardIt2 >
	ForwardIt2 rotate_copy( ExecutionPolicy&& policy,
				ForwardIt1  first,  ForwardIt1	    (2)   (since
     C++17)
	n_first,

				ForwardIt1 last, ForwardIt2
	d_first );

	1)  Copies  the  elements from the range [first, last), to another range
     beginning at
	d_first in such a way, that the element *(n_first) becomes the first el-
     ement of the
	new range and *(n_first - 1) becomes the last element.
	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)

	If any of the following conditions is satisfied, the behavior  is  unde-
     fined:

	  * [first, n_first) or [n_first, last) is not a valid range.
	  * The source and destination ranges overlap.

Parameters
	first, last - the range of elements to copy
	n_first     - an iterator to an element in [first, last) that should ap-
     pear at the
		      beginning of the new range
	d_first     - beginning of the destination range
	policy	     - the execution policy to use. See execution policy for de-
     tails.

Type requirements
	-
	ForwardIt, ForwardIt1, ForwardIt2 must meet the requirements of
	LegacyForwardIterator.
	-
	OutputIt must meet the requirements of LegacyOutputIterator.

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

Complexity
	Exactly std::distance(first, last) 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 ForwardIt, class OutputIt>
	constexpr // since C++20
	OutputIt rotate_copy(ForwardIt first, ForwardIt n_first,
			     ForwardIt last, OutputIt d_first)
	{
	    d_first = std::copy(n_first, last, d_first);
	    return std::copy(first, n_first, d_first);
	}

Example
     // Run this code

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

      int main()
      {
	  std::vector<int> src{1, 2, 3, 4, 5};
	  std::vector<int> dest(src.size());
	  auto pivot = std::find(src.begin(), src.end(), 3);

	  std::rotate_copy(src.begin(), pivot, src.end(), dest.begin());
	  for (int i : dest)
	      std::cout << i << ' ';
	  std::cout << '\n';

	  // copy the rotation result directly to the std::cout
	  pivot = std::find(dest.begin(), dest.end(), 1);
	  std::rotate_copy(dest.begin(), pivot, dest.end(),
			   std::ostream_iterator<int>(std::cout, " "));
	  std::cout << '\n';
      }

Output:
      3 4 5 1 2
      1 2 3 4 5

See also
	rotate		    rotates the order of elements in a range
			    (function template)
	ranges::rotate_copy copies and rotate a range of elements
	(C++20) 	    (niebloid)

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