std::ranges::shift_left, std::ranges::shift_right

Определён в заголовочном файле `<algorithm>`
Сигнатура вызова
template< std::permutable I, std::sentinel_for<I> S > constexpr ranges::subrange<I> shift_left( I first, S last, std::iter_difference_t<I> n );	(1)	(начиная с C++23)
template< ranges::forward_range R > requires std::permutable<ranges::iterator_t<R>> constexpr ranges::borrowed_subrange_t<R> shift_left( R&& r, ranges::range_difference_t<R> n );	(2)	(начиная с C++23)
template< std::permutable I, std::sentinel_for<I> S > constexpr ranges::subrange<I> shift_right( I first, S last, std::iter_difference_t<I> n );	(3)	(начиная с C++23)
template< ranges::forward_range R > requires std::permutable<ranges::iterator_t<R>> constexpr ranges::borrowed_subrange_t<R> shift_right( R&& r, ranges::range_difference_t<R> n );	(4)	(начиная с C++23)

Сдвигает элементы в диапазоне [first, last) или r на n позиций. Поведение не определено, если [first, last) не является допустимым диапазоном.

1) Сдвигает элементы к началу диапазона:

Если n == 0 || n >= last - first, эффект отсутствует.
Если n < 0, поведение не определено.
В противном случае для каждого целого числа i в [0, last - first - n) перемещает элемент, изначально находившийся в позиции first + n + i, в позицию first + i. Перемещения выполняются в порядке возрастания i, начиная с 0.

3) Сдвигает элементы к концу диапазона:

Если n == 0 || n >= last - first, эффект отсутствует.
Если n < 0, поведение не определено.
В противном случае для каждого целого числа i в [0, last - first - n) перемещает элемент, изначально находившийся в позиции first + i, в позицию first + n + i. Если I моделирует bidirectional_iterator, перемещения выполняются в порядке убывания i, начиная с last - first - n - 1.

2,4) То же, что и (1) или (3) соответственно, но в качестве диапазона используется r, как если бы ranges::begin(r) использовался в качестве first, а ranges::end(r) — в качестве last.

Элементы, находящиеся в исходном диапазоне, но не входящие в новый диапазон, остаются в допустимом, но неуказанном состоянии.

Описанные на этой странице функциональные объекты — это функциональные объекты алгоритмов (неформально называемые неблоидами), то есть:

При вызове любого из них нельзя указать явный список аргументов шаблона.
Ни один из них не виден при поиске, зависящем от аргументов.
Если любой из них найден посредством обычного поиска без квалификатора как имя слева от оператора вызова функции, поиск, зависящий от аргументов, подавляется.

Параметры

first, last	-	пара итератор–сентинел, задающая диапазон элементов для сдвига
r	-	диапазон элементов для сдвига
n	-	количество позиций для сдвига

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

1,2) {first, /*NEW_LAST*/}, где NEW_LAST — конец результирующего диапазона и эквивалентен:

first + (last - first - n), если n меньше last - first;
first в противном случае.

3,4) {/*NEW_FIRST*/, last}, где NEW_FIRST — начало результирующего диапазона и эквивалентен:

first + n, если n меньше last - first;
last в противном случае.

Сложность

1,2) Не более ranges::distance(first, last) - n присваиваний.

3,4) Не более ranges::distance(first, last) - n присваивания или обмена.

Примечания

ranges::shift_left / ranges::shift_right эффективнее в распространённых реализациях, если I моделирует bidirectional_iterator или (что предпочтительнее) random_access_iterator.

Реализации (например, MSVC STL) могут включать векторизацию, если тип итератора моделирует contiguous_iterator, а обмен значениями его типа не вызывает ни нетривиальных специальных функций-членов, ни swap, найденных посредством ADL.

Макрос проверки возможностей	Значение	Стандарт	Возможность
`__cpp_lib_shift`	`202202L`	(C++23)	`std::ranges::shift_left` и `std::ranges::shift_right`

Пример

#include <algorithm>
#include <iostream>
#include <string>
#include <type_traits>
#include <vector>

struct S
{
    int value{0};
    bool specified_state{true};

    S(int v = 0) : value{v} {}
    S(S const& rhs) = default;
    S(S&& rhs) { *this = std::move(rhs); }
    S& operator=(S const& rhs) = default;
    S& operator=(S&& rhs)
    {
        if (this != &rhs)
        {
            value = rhs.value;
            specified_state = rhs.specified_state;
            rhs.specified_state = false;
        }
        return *this;
    }
};

template<typename T>
std::ostream& operator<<(std::ostream& os, std::vector<T> const& v)
{
    for (const auto& s : v)
    {
        if constexpr (std::is_same_v<T, S>)
            s.specified_state ? os << s.value << ' ' : os << ". ";
        else if constexpr (std::is_same_v<T, std::string>)
            os << (s.empty() ? "." : s) << ' ';
        else
            os << s << ' ';
    }
    return os;
}

int main()
{
    std::cout << std::left;

    std::vector<S> a{1, 2, 3, 4, 5, 6, 7};
    std::vector<int> b{1, 2, 3, 4, 5, 6, 7};
    std::vector<std::string> c{"α", "β", "γ", "δ", "ε", "ζ", "η"};

    std::cout << "vector<S> \tvector<int> \tvector<string>\n";
    std::cout << a << "  " << b << "  " << c << '\n';

    std::ranges::shift_left(a, 3);
    std::ranges::shift_left(b, 3);
    std::ranges::shift_left(c, 3);
    std::cout << a << "  " << b << "  " << c << '\n';

    std::ranges::shift_right(a, 2);
    std::ranges::shift_right(b, 2);
    std::ranges::shift_right(c, 2);
    std::cout << a << "  " << b << "  " << c << '\n';

    std::ranges::shift_left(a, 8); // has no effect: n >= last - first
    std::ranges::shift_left(b, 8); // ditto
    std::ranges::shift_left(c, 8); // ditto
    std::cout << a << "  " << b << "  " << c << '\n';

//  std::ranges::shift_left(a, -3); // UB
}

Возможный вывод:

vector<S>       vector<int>     vector<string>
1 2 3 4 5 6 7   1 2 3 4 5 6 7   α β γ δ ε ζ η
4 5 6 7 . . .   4 5 6 7 5 6 7   δ ε ζ η . . .
. . 4 5 6 7 .   4 5 4 5 6 7 5   . . δ ε ζ η .
. . 4 5 6 7 .   4 5 4 5 6 7 5   . . δ ε ζ η .

См. также

ranges::move (C++20)	перемещает диапазон элементов в новое место (функциональный объект алгоритма)
ranges::move_backward (C++20)	перемещает диапазон элементов в новое место в обратном порядке (функциональный объект алгоритма)
ranges::rotate (C++20)	циклически сдвигает порядок элементов в диапазоне (функциональный объект алгоритма)
shift_leftshift_right (C++20)(C++20)	сдвигает элементы в диапазоне (шаблон функции)

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