From cppreference.com
Defined in header
Defined in header
inlinenamespace/* unspecified */{inlineconstexpr/* unspecified */begin=/* unspecified */;}(since C++20)
(customization point object)Call signature
template<classT>requires/* see below */constexprstd::input_or_output_iteratorautobegin(T&&t);(since C++20)Returns an iterator to the first element of the argument.
If the argument is an lvalue or ranges::enable_borrowed_range<std::remove_cv_t<T>> is true, then a call to ranges::begin is
to:
t+0 if t has an array type. If std::remove_all_extents_t<std::remove_reference_t<T>> is incomplete, then the call to ranges::begin is ill-formed, no diagnostic required.
Otherwise,
(t.begin())(until C++23)auto(t.begin())(since C++23), if that expression is valid and its type models
.
Otherwise,
(begin(t))(until C++23)auto(begin(t))(since C++23), if T is a class or enumeration type, that expression is valid and its type models
, where the meaning of begin is established as if by performing
only.
In all other cases, a call to ranges::begin is ill-formed, which can result in
when the call appears in the immediate context of a template instantiation.
Customization point objects
The name ranges::begin denotes a customization point object, which is a const
of a
class type. See
for details.
Notes
If the argument is an rvalue (i.e. T is an object type) and ranges::enable_borrowed_range<std::remove_cv_t<T>> is false, the call to ranges::begin is ill-formed, which also results in substitution failure.
The return type models
in all cases.
The C++20 standard requires that if the underlying begin 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 proposal
to match the implementations.
Example
Run this code
#include<cassert>#include<ranges>#include<vector>intmain(){std::vectorv{3,1,4};autovi=std::ranges::begin(v);autovci=std::ranges::cbegin(v);assert(*vi==3and*vi==*vci);++vi;++vci;// OK: vci is modifiable object*vi=42;// OK: vi points to mutable element// *vci = 13; // Error: vci points to immutable elementinta[]{-5,10,15};autoai=std::ranges::begin(a);// works with C-arrays as wellassert(*ai==-5);*ai=42;// OK}Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
C++20 there's machinery to prohibit certain non-member begin found by
removed such machinery See also
(C++20)
returns an iterator to the beginning of a read-only range
(customization point object)
(C++11)(C++14)
returns an iterator to the beginning of a container or array
(function template)