FreeBSD Manual Pages
std::ranges::begin(3) C++ Standard Libary std::ranges::begin(3) NAME std::ranges::begin - std::ranges::begin Synopsis Defined in header <ranges> inline namespace /*unspecified*/ { inline constexpr /*unspecified*/ begin = (since C++20) /*unspecified*/; (customiza- tion point object) } Call signature template< class T > requires /* see below */ (since C++20) constexpr std::input_or_output_iterator auto begin( T&& t ); Returns an iterator to the first element of the argument. range-begin-end.svg If the argument is an lvalue or ranges::enable_bor- rowed_range<std::remove_cv_t<T>> is true, then a call to ranges::begin is expression-equivalent to: 1. t + 0 if t has an array type. If std::remove_all_extents_t<std::remove_refer- ence_t<T>> is incomplete, then the call to ranges::begin is ill- formed, no diagnostic required. 2. Otherwise, t.begin() converted to its decayed type, if that ex- pression with conversion is valid, and its converted type models std::input_or_output_iterator. 3. Otherwise, begin(t) converted to its decayed type, if t has a class or enumeration type, the aforementioned unqualified call with con- version is valid, and its converted type models std::input_or_output_iterator, where the overload resolution is performed with the following candidates: * any declarations of begin found by argument-dependent lookup. * void begin(auto&) = delete; * void begin(const auto&) = delete; In all other cases, a call to ranges::begin is ill-formed, which can result in substitution failure when the call appears in the immediate context of a template instantiation. Expression-equivalent Expression e is expression-equivalent to expression f, if * e and f have the same effects, and * either both are constant subexpressions or else neither is a constant subexpression, and * either both are potentially-throwing or else neither is poten- tially-throwing (i.e. noexcept(e) == noexcept(f)). Customization point objects The name ranges::begin denotes a customization point object, which is a const function object of a literal semiregular class type. For exposition purposes, the cv-unqualified version of its type is denoted as __begin_fn. All instances of __begin_fn are equal. The effects of invoking dif- ferent instances of type __begin_fn on the same arguments are equivalent, regardless of whether the expression denoting the instance is an lvalue or rvalue, and is const-qualified or not (however, a volatile-qualified instance is not required to be invocable). Thus, ranges::begin can be copied freely and its copies can be used inter- changeably. Given a set of types Args..., if std::declval<Args>()... meet the requirements for arguments to ranges::begin above, __begin_fn models * std::invocable<__begin_fn, Args...>, * std::invocable<const __begin_fn, Args...>, * std::invocable<__begin_fn&, Args...>, and * std::invocable<const __begin_fn&, Args...>. Otherwise, no function call operator of __begin_fn participates in overload resolution. 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 std::input_or_output_iterator 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 P0849R8 to match the implemen- tations. Example // Run this code #include <iostream> #include <vector> #include <ranges> int main() { std::vector<int> v = { 3, 1, 4 }; auto vi = std::ranges::begin(v); std::cout << *vi << '\n'; *vi = 42; // OK int a[] = { -5, 10, 15 }; auto ai = std::ranges::begin(a); std::cout << *ai << '\n'; *ai = 42; // OK } Output: 3 -5 See also ranges::cbegin returns an iterator to the beginning of a read-only range (C++20) (customization point object) begin cbegin returns an iterator to the beginning of a container or array (C++11) (function template) (C++14) http://cppreference.com 2022.07.31 std::ranges::begin(3)
NAME | Synopsis | Notes | Example | Output: | See also
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::ranges::begin&sektion=3&manpath=FreeBSD+Ports+15.0>