Difference between revisions of "cpp/ranges/cbegin"

Latest revision as of 23:14, 7 November 2023

Defined in header `<ranges>`
Defined in header `<iterator>`
inline namespace /* unspecified / { inline constexpr / unspecified / cbegin = / unspecified */; }		(since C++20) (customization point object)
Call signature
template< class T > requires /* see below / constexpr / see below */ auto cbegin( T&& t );		(since C++20)

Returns an iterator to the first element of the const-qualified argument.	(until C++23)
Returns a constant iterator to the first element of the argument.	(since C++23)

Let CT be

const std::remove_reference_t<T>& if the argument is an lvalue (i.e. T is an lvalue reference type),
const T otherwise.

A call to ranges::cbegin is expression-equivalent to ranges::begin(static_cast<CT&&>(t)).

(until C++23)

If the argument is an lvalue or ranges::enable_borrowed_range<std::remove_cv_t<T>> is true, then a call to ranges::cbegin is expression-equivalent to:

std::const_iterator<decltype(U)>(U) for some expression U equivalent to ranges::begin(/*possibly-const-range*/(t)).

In all other cases, a call to ranges::cbegin is ill-formed, which can result in substitution failure when the call appears in the immediate context of a template instantiation.

(since C++23)

The return type models std::input_or_output_iterator and constant-iterator(since C++23) in all cases.

All instances of __cbegin_fn are equal. The effects of invoking different instances of type __cbegin_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::cbegin can be copied freely and its copies can be used interchangeably.

Given a set of types Args..., if std::declval<Args>()... meet the requirements for arguments to ranges::cbegin above, __cbegin_fn models

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

Otherwise, no function call operator of __cbegin_fn participates in overload resolution.

[edit] Notes

For an lvalue range e of type T, ranges::cbegin(e) is equivalent to

ranges::begin(std::as_const(e)).	(until C++23)
ranges::begin(e) if T models `constant_range`. Otherwise, ranges::begin(std::as_const(e)) if const T models `constant_range`. Otherwise, std::basic_const_iterator(ranges::begin(e)).	(since C++23)

[edit] Example

Run this code

#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
}

[edit] See also

ranges::begin (C++20)	returns an iterator to the beginning of a range (customization point object)[edit]
begincbegin (C++11)(C++14)	returns an iterator to the beginning of a container or array (function template) [edit]

@@ Line 3: / Line 3: @@
 {{dcl begin}}
 {{dcl header|ranges}}
+{{dcl header|iterator}}
 {{dcl|notes={{mark custpt}}|since=c++20|1=
 inline namespace /* unspecified */ {
@@ Line 16: / Line 17: @@
 {{dcl end}}
-{{rrev|until=c++23|Returns an iterator to the first element of the const-qualified argument.}}
+{{rrev multi|until1=c++23
-{{rrev|since=c++23|Returns a constant iterator to the first element of the argument.}}
+|rev1=Returns an iterator to the first element of the const-qualified argument.
+|rev2=Returns a constant iterator to the first element of the argument.}}
 {{image|range-begin-end.svg}}
-{{rrev|until=c++23|
+{{rrev multi|until1=c++23|rev1=
 Let {{tt|CT}} be
 * {{c|const std::remove_reference_t<T>&}} if the argument is an lvalue (i.e. {{tt|T}} is an lvalue reference type),
 * {{c|const T}} otherwise.
 A call to {{tt|ranges::cbegin}} is [[cpp/language/expressions#Expression-equivalence|expression-equivalent]] to {{c|ranges::begin(static_cast<CT&&>(t))}}.
-}}
+|rev2=
-{{rrev|since=c++23|
 If the argument is an lvalue or {{c|ranges::enable_borrowed_range<std::remove_cv_t<T>>}} is {{c|true}}, then a call to {{tt|ranges::cbegin}} is [[cpp/language/expressions#Expression-equivalence|expression-equivalent]] to:
 * {{c|std::const_iterator<decltype(U)>(U)}} for some expression {{tt|U}} equivalent to {{c|ranges::begin(/*possibly-const-range*/(t))}}.
-The function {{c|/*possibly-const-range*/(t)}} returns an lvalue [[cpp/language/expressions#Expression-equivalence|expression-equivalent]] to
-* {{c|const_cast<const T&>(t)}}, if {{c|ranges::constant_range<const R> && !ranges::constant_range<R>}} is {{c|true}}.
-* Otherwise, {{c|t}}
 In all other cases, a call to {{tt|ranges::cbegin}} is ill-formed, which can result in [[cpp/language/sfinae|substitution failure]] when the call appears in the immediate context of a template instantiation.
 }}
-The return type models {{lc|std::input_or_output_iterator}} {{rev inl|since=c++23| and [[cpp/ranges/constant_range|<i>{{lc|constant-iterator}}</i>]]}} in all cases.
+The return type models {{lc|std::input_or_output_iterator}} {{rev inl|since=c++23| and {{rlpi|constant_range|constant-iterator}}}} in all cases.
 {{cpp/ranges/cpo}}
+===Notes===
+For an lvalue range {{c|e}} of type {{c|T}}, {{c|ranges::cbegin(e)}} is equivalent to
+{{rrev multi|until1=c++23|rev1=
+{{c|ranges::begin(std::as_const(e))}}.
+|rev2=
+* {{c|ranges::begin(e)}} if {{c|T}} models {{lconcept|constant_range}}.
+* Otherwise, {{c|ranges::begin(std::as_const(e))}} if {{c|const T}} models {{lconcept|constant_range}}.
+* Otherwise, {{c|std::basic_const_iterator(ranges::begin(e))}}.
+}}
 ===Example===
@@ Line 48: / Line 53: @@
 |
 |code=
-#include <iostream>
+#include <cassert>
 #include <ranges>
 #include <vector>
@@ Line 54: / Line 59: @@
 int main()
 {
-     std::vector<int> v = {3, 1, 4};
+     std::vector v{3, 1, 4};
      auto vi = std::ranges::cbegin(v);
-     std::cout << *vi << '\n';
+     assert(3 == *vi);
-//  *vi = 42; // Error: read-only variable is not assignable
+    ++vi; // OK, constant-iterator object is mutable
+    assert(1 == *vi);
+    // *vi = 13; // Error: constant-iterator points to an immutable element
-     int a[] = {-5, 10, 15};
+     int a[]{3, 1, 4};
-     auto ai = std::ranges::cbegin(a);
+     auto ai = std::ranges::cbegin(a); // cbegin works with C-arrays as well
-     std::cout << *ai << '\n';
+     assert(3 == *ai and *(ai + 1) == 1);
-//  *ai = 42; // Error: read-only variable is not assignable
+    // *ai = 13; // Error: read-only variable is not assignable
 }
-|output=
--5
 }}

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/ranges/cbegin"

Latest revision as of 23:14, 7 November 2023

Contents

Customization point objects

[edit] Notes

[edit] Example

[edit] See also

Navigation

Toolbox