Skip to content

Update "Checked Iterators" topic #5498

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 37 additions & 37 deletions docs/standard-library/checked-iterators.md
Original file line number Diff line number Diff line change
@@ -1,56 +1,55 @@
---
description: "Learn more about: Checked Iterators"
title: "Checked Iterators"
ms.date: "11/04/2016"
description: "Learn more about: Checked Iterators"
ms.date: 11/04/2016
f1_keywords: ["_SECURE_SCL_THROWS"]
helpviewer_keywords: ["Safe Libraries", "Safe Libraries, C++ Standard Library", "Safe C++ Standard Library", "iterators, checked", "checked iterators"]
ms.assetid: cfc87df8-e3d9-403b-ab78-e9483247d940
---
# Checked Iterators

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).
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).

## Remarks

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).
For information about how to disable warnings that are generated by checked iterators, see [`_SCL_SECURE_NO_WARNINGS`](scl-secure-no-warnings.md).

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.
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.

> [!IMPORTANT]
> 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).
> 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).

When _ITERATOR_DEBUG_LEVEL is defined as 1 or 2, these iterator checks are performed:
When `_ITERATOR_DEBUG_LEVEL` is defined as 1 or 2, these iterator checks are performed:

- All standard iterators (for example, [vector::iterator](../standard-library/vector-class.md#iterator)) are checked.
- All standard iterators (for example, [`vector::iterator`](vector-class.md#iterator)) are checked.

- 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.
- If an output iterator is a checked iterator, calls to standard library functions such as [`std::copy`](algorithm-functions.md#copy) get checked behavior.

- If an output iterator is an unchecked iterator, calls to standard library functions cause compiler warnings.

- The following functions generate a runtime error if there is an access that is outside the bounds of the container:

:::row:::
:::column span="":::
  [`basic_string::operator[]`](../standard-library/basic-string-class.md#op_at)\
  [`bitset::operator[]`](../standard-library/bitset-class.md#op_at)\
  [`deque::back`](../standard-library/deque-class.md#back)\
  [`deque::front`](../standard-library/deque-class.md#front)
[`basic_string::operator[]`](basic-string-class.md#op_at)\
[`bitset::operator[]`](bitset-class.md#op_at)\
[`deque::back`](deque-class.md#back)\
[`deque::front`](deque-class.md#front)
:::column-end:::
:::column span="":::
[`deque::operator[]`](../standard-library/deque-class.md#op_at)\
[`list::back`](../standard-library/list-class.md#back)\
[`list::front`](../standard-library/list-class.md#front)\
[`queue::back`](../standard-library/queue-class.md#back)
[`deque::operator[]`](deque-class.md#op_at)\
[`list::back`](list-class.md#back)\
[`list::front`](list-class.md#front)\
[`queue::back`](queue-class.md#back)
:::column-end:::
:::column span="":::
[`queue::front`](../standard-library/queue-class.md#front)\
[`vector::back`](../standard-library/vector-class.md#back)\
[`vector::front`](../standard-library/vector-class.md#front)\
[`vector::operator[]`](../standard-library/vector-class.md#op_at)
[`queue::front`](queue-class.md#front)\
[`vector::back`](vector-class.md#back)\
[`vector::front`](vector-class.md#front)\
[`vector::operator[]`](vector-class.md#op_at)
:::column-end:::
:::row-end:::

When _ITERATOR_DEBUG_LEVEL is defined as 0:
When `_ITERATOR_DEBUG_LEVEL` is defined as 0:

- All standard iterators are unchecked. Iterators can move beyond the container boundaries, which leads to undefined behavior.

Expand All @@ -60,11 +59,11 @@ When _ITERATOR_DEBUG_LEVEL is defined as 0:

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).

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).
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).

## Examples

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.
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.

```cpp
// checked_iterators_1.cpp
Expand All @@ -79,19 +78,19 @@ using namespace std;

int main()
{
vector<int> v;
v.push_back(67);
vector<int> v;
v.push_back(67);

int i = v[0];
cout << i << endl;
int i = v[0];
cout << i << endl;

i = v[1]; //triggers invalid parameter handler
i = v[1]; //triggers invalid parameter handler
}
```

This program prints "67" then pops up an assertion failure dialog box with additional information about the failure.

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.
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.

```cpp
// checked_iterators_2.cpp
Expand All @@ -105,15 +104,15 @@ using namespace std;

int main()
{
vector<int> v;
vector<int> v;

int& i = v.front(); // triggers invalid parameter handler
int& i = v.front(); // triggers invalid parameter handler
}
```

This program pops up an assertion failure dialog box with additional information about the failure.

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.
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.

```cpp
// checked_iterators_3.cpp
Expand All @@ -134,7 +133,8 @@ void print(const string& s, const C& c)
{
cout << s;

for (const auto& e : c) {
for (const auto& e : c)
{
cout << e << " ";
}

Expand Down Expand Up @@ -219,5 +219,5 @@ a8: 0 8 16 24 32 40 48 56 64 72 80 88 96 104 112 120

## See also

[C++ Standard Library Overview](../standard-library/cpp-standard-library-overview.md)\
[Debug Iterator Support](../standard-library/debug-iterator-support.md)
[C++ Standard Library Overview](cpp-standard-library-overview.md)\
[Debug Iterator Support](debug-iterator-support.md)