Skip to content

Commit 751a431

Browse files
committed
docs: Add C++ unordered_set::cbegin() term entry (#8031)
1 parent 8433d22 commit 751a431

File tree

1 file changed

+99
-0
lines changed
  • content/cpp/concepts/unordered-set/terms/cbegin

1 file changed

+99
-0
lines changed
Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
Title: '.cbegin()'
3+
Description: 'Returns a constant iterator pointing to the first element of the unordered_set.'
4+
Subjects:
5+
- 'Computer Science'
6+
- 'Programming'
7+
Tags:
8+
- 'C++'
9+
- 'Unordered Set'
10+
- 'STL'
11+
- 'Iterators'
12+
CatalogContent:
13+
- 'learn-c-plus-plus'
14+
- 'paths/computer-science'
15+
---
16+
17+
The **`.cbegin()`** method returns a **constant iterator** that points to the first element in an `std::unordered_set`.
18+
19+
The key feature of a constant iterator (`const_iterator`) is that it allows you to **read** the elements but **prevents** you from modifying them. This is a best practice when iterating over a set to ensure data integrity. Since `unordered_set` does not guarantee any specific order, the element returned by `cbegin()` depends on the internal hash table structure.
20+
21+
## Syntax
22+
23+
The `.cbegin()` method is called directly on the `unordered_set` object.
24+
25+
```cpp
26+
unordered_set_name.cbegin();
27+
```
28+
29+
## Parameters
30+
31+
The method takes no parameters.
32+
33+
## Return Value
34+
35+
Returns a `const_iterator` (constant iterator) pointing to the first element in the `unordered_set`.
36+
37+
## Example
38+
39+
This example demonstrates obtaining the starting element of an `unordered_set` using `cbegin()`. Note that attempting to modify the element pointed to by the `const_iterator` would result in a compilation error.
40+
41+
```cpp
42+
#include <iostream>
43+
#include <string>
44+
#include <unordered_set>
45+
#include <algorithm> // Required for std::find or general use
46+
47+
int main() {
48+
std::unordered_set<int> unique_numbers = {10, 5, 20, 15};
49+
50+
// Get a constant iterator to the beginning
51+
auto it = unique_numbers.cbegin();
52+
53+
// Print the value of the first element (read-only access)
54+
std::cout << "The first element in the set's internal order is: " << *it << "\n";
55+
56+
// Advance the iterator to the next element
57+
// Note: The order of elements is not guaranteed!
58+
++it;
59+
60+
std::cout << "The second element is: " << *it << "\n";
61+
62+
// The following line would cause a compile-time error:
63+
// *it = 99;
64+
65+
return 0;
66+
}
67+
```
68+
69+
Output:
70+
71+
```
72+
The first element in the set's internal order is: 20
73+
The second element is: 5
74+
```
75+
76+
## Codebyte
77+
78+
Use the Codebyte below to access the first element of an `unordered_set` using the constant iterator returned by `.cbegin()`.
79+
80+
```cpp
81+
#include <iostream>
82+
#include <unordered_set>
83+
84+
int main() {
85+
std::unordered_set<std::string> colors = {"red", "green", "blue", "yellow"};
86+
87+
// Use cbegin() to get the constant iterator
88+
auto start_it = colors.cbegin();
89+
90+
// Print the value the iterator points to
91+
std::cout << "First element: " << *start_it << "\n";
92+
93+
// Advance the iterator
94+
++start_it;
95+
std::cout << "Second element: " << *start_it << "\n";
96+
97+
return 0;
98+
}
99+
```

0 commit comments

Comments
 (0)