std::ranges::begin

inline namespace /* unspecified */ {
    inline constexpr /* unspecified */ begin = /* unspecified */;
}

template< class T >
    requires /* see below */
constexpr std::input_or_output_iterator auto begin( T&& t );

Возвращает итератор на первый элемент аргумента.

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

1. t + 0 если t имеет тип массива.
   • Если std::remove_all_extents_t<std::remove_reference_t<T>> неполна, то вызов ranges::begin некорректен; диагностика не требуется.
2. В противном случае, decay-copy(t.begin())(до C++23)auto(t.begin())(с C++23), если это выражение допустимо и его тип соответствует std::input_or_output_iterator.
3. В противном случае, decay-copy(begin(t))(до C++23)auto(begin(t))(с C++23), если T — класс или перечисление, это выражение допустимо и его тип соответствует std::input_or_output_iterator, где значение begin определяется как при выполнении поиска зависимого от аргумента поиска.

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

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

Имя ranges::begin обозначает объект точки кастомизации, который является константным объектом-функцией типа литерального semiregular класса. Для демонстрационных целей неквалифицированная версия его типа обозначается как __begin_fn.

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

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

• std::invocable<__begin_fn, Args...>,
• std::invocable<const __begin_fn, Args...>,
• std::invocable<__begin_fn&, Args...>, и
• std::invocable<const __begin_fn&, Args...>.
  

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

Примечания

Если аргумент является rvalue (т.е. T является типом объекта) и ranges::enable_borrowed_range<std::remove_cv_t<T>> является false, то вызов ranges::begin некорректен, что также приводит к отказу подстановки.

Возвращаемый тип соответствует std::input_or_output_iterator во всех случаях.

Стандарт C++20 требует, чтобы, если основной вызов begin функции возвращает prvalue, возвращаемое значение создается методом перемещения из объекте-временном объекте. Все реализации напрямую возвращают prvalue вместо этого. Требование исправлено предложением P0849R8 после C++20, чтобы соответствовать реализациям.

Пример

#include <cassert>
#include <ranges>
#include <vector>
 
int main() 
{
    std::vector v{3, 1, 4};
    auto vi = std::ranges::begin(v);
    auto vci = std::ranges::cbegin(v);
    assert(*vi == 3 and *vi == *vci);
    ++vi;
    ++vci; // OK: vci is modifiable object
    *vi = 42; // OK: vi points to mutable element
    // *vci = 13; // Error: vci points to immutable element
 
    int a[]{-5, 10, 15};
    auto ai = std::ranges::begin(a); // works with C-arrays as well
    assert(*ai == -5);
    *ai = 42; // OK
}

Отчёты об ошибках

Следующие отчёты об ошибках, изменяющие поведение, были применены ретроактивно к ранее опубликованным стандартам C++.

См. также