You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/standard-library/checked-iterators.md
+37-37Lines changed: 37 additions & 37 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,56 +1,55 @@
1
1
---
2
-
description: "Learn more about: Checked Iterators"
3
2
title: "Checked Iterators"
4
-
ms.date: "11/04/2016"
3
+
description: "Learn more about: Checked Iterators"
4
+
ms.date: 11/04/2016
5
5
f1_keywords: ["_SECURE_SCL_THROWS"]
6
6
helpviewer_keywords: ["Safe Libraries", "Safe Libraries, C++ Standard Library", "Safe C++ Standard Library", "iterators, checked", "checked iterators"]
7
-
ms.assetid: cfc87df8-e3d9-403b-ab78-e9483247d940
8
7
---
9
8
# Checked Iterators
10
9
11
-
Checked iterators ensure that the bounds of your container are not overwritten. Checked iterators apply to both release builds and debug builds. For more information about how to use debug iterators when you compile in debug mode, see [Debug Iterator Support](../standard-library/debug-iterator-support.md).
10
+
Checked iterators ensure that the bounds of your container are not overwritten. Checked iterators apply to both release builds and debug builds. For more information about how to use debug iterators when you compile in debug mode, see [Debug Iterator Support](debug-iterator-support.md).
12
11
13
12
## Remarks
14
13
15
-
For information about how to disable warnings that are generated by checked iterators, see [_SCL_SECURE_NO_WARNINGS](../standard-library/scl-secure-no-warnings.md).
14
+
For information about how to disable warnings that are generated by checked iterators, see [`_SCL_SECURE_NO_WARNINGS`](scl-secure-no-warnings.md).
16
15
17
-
You can use the [\_ITERATOR\_DEBUG\_LEVEL](../standard-library/iterator-debug-level.md) preprocessor macro to enable or disable the checked iterators feature. If _ITERATOR_DEBUG_LEVEL is defined as 1 or 2, unsafe use of iterators causes a runtime error and the program is terminated. If defined as 0, checked iterators are disabled. By default, the value for _ITERATOR_DEBUG_LEVEL is 0 for release builds and 2 for debug builds.
16
+
You can use the [`_ITERATOR_DEBUG_LEVEL`](iterator-debug-level.md) preprocessor macro to enable or disable the checked iterators feature. If `_ITERATOR_DEBUG_LEVEL` is defined as 1 or 2, unsafe use of iterators causes a runtime error and the program is terminated. If defined as 0, checked iterators are disabled. By default, the value for `_ITERATOR_DEBUG_LEVEL` is 0 for release builds and 2 for debug builds.
18
17
19
18
> [!IMPORTANT]
20
-
> Older documentation and source code may refer to the [_SECURE_SCL](../standard-library/secure-scl.md) macro. Use _ITERATOR_DEBUG_LEVEL to control _SECURE_SCL. For more information, see [_ITERATOR_DEBUG_LEVEL](../standard-library/iterator-debug-level.md).
19
+
> Older documentation and source code may refer to the [`_SECURE_SCL`](secure-scl.md) macro. Use `_ITERATOR_DEBUG_LEVEL` to control `_SECURE_SCL`. For more information, see [`_ITERATOR_DEBUG_LEVEL`](iterator-debug-level.md).
21
20
22
-
When _ITERATOR_DEBUG_LEVEL is defined as 1 or 2, these iterator checks are performed:
21
+
When `_ITERATOR_DEBUG_LEVEL` is defined as 1 or 2, these iterator checks are performed:
23
22
24
-
- All standard iterators (for example, [vector::iterator](../standard-library/vector-class.md#iterator)) are checked.
23
+
- All standard iterators (for example, [`vector::iterator`](vector-class.md#iterator)) are checked.
25
24
26
-
- If an output iterator is a checked iterator, calls to standard library functions such as [std::copy](../standard-library/algorithm-functions.md#copy) get checked behavior.
25
+
- If an output iterator is a checked iterator, calls to standard library functions such as [`std::copy`](algorithm-functions.md#copy) get checked behavior.
27
26
28
27
- If an output iterator is an unchecked iterator, calls to standard library functions cause compiler warnings.
29
28
30
29
- The following functions generate a runtime error if there is an access that is outside the bounds of the container:
- All standard iterators are unchecked. Iterators can move beyond the container boundaries, which leads to undefined behavior.
56
55
@@ -60,11 +59,11 @@ When _ITERATOR_DEBUG_LEVEL is defined as 0:
60
59
61
60
A checked iterator refers to an iterator that calls `invalid_parameter_handler` if you attempt to move past the boundaries of the container. For more information about `invalid_parameter_handler`, see [Parameter Validation](../c-runtime-library/parameter-validation.md).
62
61
63
-
The iterator adaptors that support checked iterators are [checked_array_iterator Class](../standard-library/checked-array-iterator-class.md) and [unchecked_array_iterator Class](../standard-library/unchecked-array-iterator-class.md).
62
+
The iterator adaptors that support checked iterators are [`checked_array_iterator` Class](checked-array-iterator-class.md) and [`unchecked_array_iterator` Class](unchecked-array-iterator-class.md).
64
63
65
64
## Examples
66
65
67
-
When you compile by using _ITERATOR_DEBUG_LEVEL set to 1 or 2, a runtime error will occur if you attempt to access an element that is outside the bounds of the container by using the indexing operator of certain classes.
66
+
When you compile by using `_ITERATOR_DEBUG_LEVEL` set to 1 or 2, a runtime error will occur if you attempt to access an element that is outside the bounds of the container by using the indexing operator of certain classes.
68
67
69
68
```cpp
70
69
// checked_iterators_1.cpp
@@ -79,19 +78,19 @@ using namespace std;
79
78
80
79
intmain()
81
80
{
82
-
vector<int> v;
83
-
v.push_back(67);
81
+
vector<int> v;
82
+
v.push_back(67);
84
83
85
-
int i = v[0];
86
-
cout << i << endl;
84
+
int i = v[0];
85
+
cout << i << endl;
87
86
88
-
i = v[1]; //triggers invalid parameter handler
87
+
i = v[1]; //triggers invalid parameter handler
89
88
}
90
89
```
91
90
92
91
This program prints "67" then pops up an assertion failure dialog box with additional information about the failure.
93
92
94
-
Similarly, when you compile by using _ITERATOR_DEBUG_LEVEL set to 1 or 2, a runtime error will occur if you attempt to access an element by using `front` or `back` in container classes when the container is empty.
93
+
Similarly, when you compile by using `_ITERATOR_DEBUG_LEVEL` set to 1 or 2, a runtime error will occur if you attempt to access an element by using `front` or `back` in container classes when the container is empty.
95
94
96
95
```cpp
97
96
// checked_iterators_2.cpp
@@ -105,15 +104,15 @@ using namespace std;
105
104
106
105
intmain()
107
106
{
108
-
vector<int> v;
107
+
vector<int> v;
109
108
110
-
int& i = v.front(); // triggers invalid parameter handler
109
+
int& i = v.front(); // triggers invalid parameter handler
111
110
}
112
111
```
113
112
114
113
This program pops up an assertion failure dialog box with additional information about the failure.
115
114
116
-
The following code demonstrates various iterator use-case scenarios with comments about each. By default, _ITERATOR_DEBUG_LEVEL is set to 2 in Debug builds, and to 0 in Retail builds.
115
+
The following code demonstrates various iterator use-case scenarios with comments about each. By default, `_ITERATOR_DEBUG_LEVEL` is set to 2 in Debug builds, and to 0 in Retail builds.
0 commit comments