std::rotate_copy

Определено в заголовке `<algorithm>`
	(1)
template< class ForwardIt, class OutputIt > OutputIt rotate_copy( ForwardIt first, ForwardIt n_first, ForwardIt last, OutputIt d_first );		(до C++20)
template< class ForwardIt, class OutputIt > constexpr OutputIt rotate_copy( ForwardIt first, ForwardIt n_first, ForwardIt last, OutputIt d_first );		(с C++20)
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2 > ForwardIt2 rotate_copy( ExecutionPolicy&& policy, ForwardIt1 first, ForwardIt1 n_first, ForwardIt1 last, ForwardIt2 d_first );	(2)	(с C++17)

1) Копирует элементы из диапазона [first, last), в другой диапазон, начиная с d_first, таким образом, что элемент *(n_first) становится первым элементом нового диапазона, а *(n_first - 1) — последним.

Поведение не определено, если либо [first, n_first) , либо [n_first, last) не является допустимым диапазоном, или источник и целевой диапазоны перекрываются.

2) То же самое, что и (1), но выполняется согласно policy. Эта перегрузка не участвует в разрешении перегрузки, если

`std::is_execution_policy_v<std::decay_t<ExecutionPolicy>>` является `true`.	(до C++20)
`std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>` является `true`.	(с C++20)

Параметры

first, last	-	диапазон копируемых элементов
n_first	-	итератор на элемент в `[first,` `last)`, который должен появиться в начале нового диапазона
d_first	-	начало целевого диапазона
policy	-	политика выполнения. Подробнее см. политика выполнения.
Требования к типу
-`ForwardIt, ForwardIt1, ForwardIt2` должен соответствовать требованиям LegacyForwardIterator.
-`OutputIt` должен соответствовать требованиям LegacyOutputIterator.

Возвращаемое значение

Итератор на элемент после последнего скопированного элемента.

Сложность

линейная по расстоянию между first и last.

Исключения

Перегрузка с параметром шаблона ExecutionPolicy сообщает об ошибках следующим образом:

Если выполнение функции, вызываемой как часть алгоритма, выбрасывает исключение, и ExecutionPolicy является одной из стандартных политик, std::terminate вызывается. Для любой другой ExecutionPolicy, поведение определяется реализацией.
Если алгоритм не может выделить память, выбрасывается std::bad_alloc.

Возможная реализация

См. также реализации в libstdc++, libc++ и 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);
}

Пример

#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';
}

Вывод:

3 4 5 1 2
1 2 3 4 5

См. также

rotate	вращает порядок элементов в диапазоне (шаблон функции)
ranges::rotate_copy (C++20)	копирует и вращает диапазон элементов (niebloid)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/algorithm/rotate_copy