Returns an iterator to the first element of the argument.

If the argument is an lvalue orranges::enable_borrowed_range<std::remove_cv_t<T>> istrue, then a call toranges::begin isexpression-equivalent to:

1. t+0 ift has an array type.
   • Ifstd::remove_all_extents_t<std::remove_reference_t<T>> is incomplete, then the call toranges::begin is ill-formed, no diagnostic required.
2. Otherwise,decay-copy(t.begin())(until C++23)auto(t.begin())(since C++23), if that expression is valid and its type modelsstd::input_or_output_iterator.
3. Otherwise,decay-copy(begin(t))(until C++23)auto(begin(t))(since C++23), ifT is a class or enumeration type, that expression is valid and its type modelsstd::input_or_output_iterator, where the meaning ofbegin is established as if by performingargument-dependent lookup only.

In all other cases, a call toranges::begin is ill-formed, which can result insubstitution failure when the call appears in the immediate context of a template instantiation.

Customization point objects

The nameranges::begin denotes acustomization point object, which is a constfunction object of aliteralsemiregular class type. SeeCustomizationPointObject for details.

[edit]Notes

If the argument is an rvalue (i.e.T is an object type) andranges::enable_borrowed_range<std::remove_cv_t<T>> isfalse, the call toranges::begin is ill-formed, which also results in substitution failure.

The return type modelsstd::input_or_output_iterator in all cases.

The C++20 standard requires that if the underlyingbegin function call returns a prvalue, the return value is move-constructed from the materialized temporary object. All implementations directly return the prvalue instead. The requirement is corrected by the post-C++20 proposalP0849R8 to match the implementations.

[edit]Example

#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 wellassert(*ai==-5);*ai=42;// OK}

[edit]Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

[edit]See also

• In other languages

• Deutsch
• Español
• 日本語
• Русский
• 中文