std::ranges::rotate_copy, std::ranges::rotate_copy_result, std::ranges::rotate_copy_truncated_result

Defined in header `<algorithm>`
Call signature
template< std::forward_iterator I, std::sentinel_for<I> S, std::weakly_incrementable O > requires std::indirectly_copyable<I, O> constexpr rotate_copy_result<I, O> rotate_copy( I first, I middle, S last, O d_first );	(1)	(since C++20)
template< ranges::forward_range R, std::weakly_incrementable O > requires std::indirectly_copyable<ranges::iterator_t<R>, O> constexpr rotate_copy_result<ranges::borrowed_iterator_t<R>, O> rotate_copy( R&& r, ranges::iterator_t<R> middle, O d_first );	(2)	(since C++20)
template< /execution-policy/ Ep, std::random_access_iterator I, std::sized_sentinel_for<I> S, std::random_access_iterator O, std::sized_sentinel_for<O> OutS > requires std::indirectly_copyable<I, O> ranges::rotate_copy_truncated_result<I, O> rotate_copy( Ep&& policy, I first, I middle, S last, O d_first, OutS d_last );	(3)	(since C++26)
template< /execution-policy/ Ep, /sized-random-access-range/ R, /sized-random-access-range/ OutR > requires std::indirectly_copyable<ranges::iterator_t<R>, ranges::iterator_t<OutR>> ranges::rotate_copy_truncated_result<ranges::borrowed_iterator_t<R>, ranges::borrowed_iterator_t<OutR>> rotate_copy( Ep&& policy, R&& r, ranges::iterator_t<R> middle, OutR&& d_r );	(4)	(since C++26)
Helper types
template< class I, class O > using rotate_copy_result = ranges::in_out_result<I, O>;	(5)	(since C++20)
template< class I, class O > using rotate_copy_truncated_result = ranges::in_in_out_result<I, I, O>;	(6)	(since C++26)

For the definition of /*execution-policy*/, see this page; for the definition of /*sized-random-access-range*/, see this page.

Copies elements from the source range [first, last) or r to the destination range beginning at in rotated order.

1) In the destination range beginning at d_first, the elements originally in [first, middle) are placed after the elements originally in [middle, last) while the orders of the elements in both ranges are preserved.

2) Same as (1), but uses ranges::begin(r) as first and ranges::end(r) as last.

3) Same as (1), but executed according to policy, and the destination range is [d_first, d_end). If the destination range is exhausted before reaching middle again, the remaining elements in the source range will not be copied.

4) Same as (3), but uses ranges::begin(r) as first and ranges::begin(r) + ranges::distance(r) as last, and the destination range is d_r.

If any of the following conditions is satisfied, the behavior is undefined:

[first, middle) or [middle, last) is not a valid range.
For the non-parallel overloads (1,2), the source and destination ranges overlap.
For the parallel overloads (3,4), let count be ranges::size(first, last) or ranges::size(r):

3) The source range and [d_first, ranges::next(d_first, count, d_last)) overlap.

4) The source range and [d_r.begin(), ranges::next(d_r.begin(), count, d_r.end()) overlap.

The function-like entities described on this page are algorithm function objects (informally known as niebloids), that is:

Explicit template argument lists cannot be specified when calling any of them.
None of them are visible to argument-dependent lookup.
When any of them are found by normal unqualified lookup as the name to the left of the function-call operator, argument-dependent lookup is inhibited.

Parameters

first, last	-	the iterator-sentinel pair defining the source range
r	-	the source range
middle	-	the beginning of the part that should appear at the beginning of the destination range
d_first	-	the beginning of the destination range
d_end	-	the sentinel of the destination range
d_r	-	the destination range
policy	-	the execution policy to use

Return value

1,2) A ranges::rotate_copy_result object where:

The data member in holds the past-the-end iterator of the source range.
The data member out holds the past-the-end iterator of the destination range.

3,4) Let count be the number of elements copied, returns a ranges::rotate_copy_truncated_result object where:

The data member in1 holds last, or middle + count if count is less than last - middle.
The data member in2 holds an iterator past the last copied element in the source range, or first if count is less than or equal to last - middle.
The data member out holds an iterator past the last copy-assigned element in the destination range, or an iterator to the beginning of the destination range if no element is copied.

Complexity

Given

$\scriptsize N_1$ $N 1$ as ranges::distance(first, last) or ranges::distance(r),
$\scriptsize N_2$ $N 2$ as ranges::distance(d_first, d_last) or ranges::distance(d_r):

1,2) Exactly $\scriptsize N_1$

N 1

assignments.

3,4) Exactly $\scriptsize \min(N_1,N_2)$

min(N 1,N 2)

assignments.

Exceptions

3,4) During the execution process:

If the temporary memory resources required for parallelization are not available, std::bad_alloc is thrown.
If an uncaught exception is thrown while accessing objects via an algorithm argument, the behavior is determined by the execution policy (for standard policies, std::terminate is invoked).

Notes

If the value type is TriviallyCopyable and the iterator types satisfy contiguous_iterator, implementations of ranges::rotate_copy usually avoid multiple assignments by using a "bulk copy" function such as std::memmove.

Possible implementation

See also the implementations in libstdc++ and MSVC STL.

struct rotate_copy_fn
{
    template<std::forward_iterator I, std::sentinel_for<I> S, std::weakly_incrementable O>
        requires std::indirectly_copyable<I, O>
    constexpr ranges::rotate_copy_result<I, O>
        operator()(I first, I middle, S last, O result) const
    {
        auto c1{ranges::copy(middle, std::move(last), std::move(result))};
        auto c2{ranges::copy(std::move(first), std::move(middle), std::move(c1.out))};
        return {std::move(c1.in), std::move(c2.out)};
    }
    
    template<ranges::forward_range R, std::weakly_incrementable O>
        requires std::indirectly_copyable<ranges::iterator_t<R>, O>
    constexpr ranges::rotate_copy_result<ranges::borrowed_iterator_t<R>, O>
        operator()(R&& r, ranges::iterator_t<R> middle, O result) const
    {
        return (*this)(ranges::begin(r), std::move(middle),
                       ranges::next(ranges::begin(r), ranges::end(r)),
                       std::move(result));
    }
};

inline constexpr rotate_copy_fn rotate_copy{};

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::ranges::find(src, 3);
    
    std::ranges::rotate_copy(src, pivot, dest.begin());
    for (int i : dest)
        std::cout << i << ' ';
    std::cout << '\n';
    
    // copy the rotation result directly to the std::cout
    pivot = std::ranges::find(dest, 1);
    std::ranges::rotate_copy(dest, pivot, std::ostream_iterator<int>(std::cout, " "));
    std::cout << '\n';
}

Output:

3 4 5 1 2
1 2 3 4 5

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Diagnostics library
Memory management library
Metaprogramming library (C++11)
General utilities library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Strings library
Text processing library
Numerics library
Date and time library
Input/output library
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
Technical specifications
Symbols index
External libraries

rotate_copy	copies and rotate a range of elements (function template) [edit]
ranges::rotate (C++20)	rotates the order of elements in a range (algorithm function object)[edit]
ranges::copyranges::copy_if (C++20)(C++20)	copies a range of elements to a new location (algorithm function object)[edit]

cppreference.com

Search

Namespaces

Variants

Views

Actions

std::ranges::rotate_copy, std::ranges::rotate_copy_result, std::ranges::rotate_copy_truncated_result

Contents