std::ranges::cbegin

Определено в заголовке `<ranges>`
Определено в заголовке `<iterator>`
inline namespace /* unspecified / { inline constexpr / unspecified / cbegin = / unspecified */; }		(с C++20) (объект точки кастомизации)
Подпись вызова
template< class T > requires /* see below / constexpr / see below */ auto cbegin( T&& t );		(с C++20)

Возвращает итератор на первый элемент квалифицированного аргумента const.	(до C++23)
Возвращает константный итератор на первый элемент аргумента.	(с C++23)

Пусть CT будет

const std::remove_reference_t<T>& если аргумент является lvalue (т.е. T является типом lvalue-ссылки),
const T в противном случае.

Вызов ranges::cbegin является эквивалентным выражению ranges::begin(static_cast<CT&&>(t)).

(до C++23)

Если аргумент является lvalue или ranges::enable_borrowed_range<std::remove_cv_t<T>> является true, тогда вызов ranges::cbegin является эквивалентным выражению:

std::const_iterator<decltype(U)>(U) для некоторого выражения U эквивалентного ranges::begin(/*possibly-const-range*/(t)).

Во всех остальных случаях вызов ranges::cbegin некорректен, что может привести к сбоям подстановки при появлении вызова в непосредственном контексте экземпляризации шаблона.

(с C++23)

Возвращаемый тип моделирует std::input_or_output_iterator и constant-iterator(с C++23) во всех случаях.

Объекты точки кастомизации

Имя ranges::cbegin обозначает объект точки кастомизации, который является const функциональным объектом типа литерального semiregular класса. Для целей изложения, неквалифицированная версия его типа обозначается как __cbegin_fn.

Все экземпляры __cbegin_fn равны. Действия вызова различных экземпляров типа __cbegin_fn на одних и тех же аргументах эквивалентны, независимо от того, является ли выражение, обозначающее экземпляр, lvalue или rvalue, и квалифицировано как const или нет (хотя не требуется, чтобы экземпляр с квалификатором volatile был вызываем). Таким образом, ranges::cbegin может быть свободно скопирован, а его копии могут быть использованы взаимозаменяемо.

Учитывая набор типов Args..., если std::declval<Args>()... удовлетворяет требованиям аргументов для ranges::cbegin выше, __cbegin_fn моделирует

std::invocable<__cbegin_fn, Args...>,
std::invocable<const __cbegin_fn, Args...>,
std::invocable<__cbegin_fn&, Args...>, и
std::invocable<const __cbegin_fn&, Args...>.

В противном случае, никакой оператор вызова функции __cbegin_fn не участвует в разрешении перегрузки.

Примечания

Для lvalue диапазона e типа T, ranges::cbegin(e) эквивалентно

`ranges::begin(std::as_const(e))`.	(до C++23)
`ranges::begin(e)` если `T` моделирует `constant_range`. В противном случае, `ranges::begin(std::as_const(e))` если `const T` моделирует `constant_range`. В противном случае, `std::basic_const_iterator(ranges::begin(e))`.	(с C++23)

Пример

#include <cassert>
#include <ranges>
#include <vector>
 
int main()
{
    std::vector v{3, 1, 4};
    auto vi = std::ranges::cbegin(v);
    assert(3 == *vi);
    ++vi; // OK, constant-iterator object is mutable
    assert(1 == *vi);
    // *vi = 13; // Error: constant-iterator points to an immutable element
 
    int a[]{3, 1, 4};
    auto ai = std::ranges::cbegin(a); // cbegin works with C-arrays as well
    assert(3 == *ai and *(ai + 1) == 1);
    // *ai = 13; // Error: read-only variable is not assignable
}

См. также

ranges::begin (C++20)	возвращает итератор в начало диапазона (объект точки кастомизации)
begincbegin (C++11)(C++14)	возвращает итератор в начало контейнера или массива (шаблон функции)

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