Checked Iterators

Checked iterators ensure that the bounds of your container are not overwritten.

Checked iterators apply to release builds and debug builds. For more information about how to use iterators when you compile in debug mode, see Debug Iterator Support.

Remarks

For information about how to disable warnings that are generated by checked iterators, see _SCL_SECURE_NO_WARNINGS.

You can use the following symbol with the checked iterators feature.

• _SECURE_SCL

  Important

  Use _ITERATOR_DEBUG_LEVEL to control _SECURE_SCL. For more information, see _ITERATOR_DEBUG_LEVEL.

  If _SECURE_SCL is defined as 1, 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 _SECURE_SCL is 0 for release builds and 1 for debug builds.

When _SECURE_SCL is defined as 1, following SCL checks are performed:

• All standard iterators (for example, vector::iterator) are checked.

• If an output iterator is a checked iterator you will get checked behavior on calls to the standard function (for example, std::copy).

• If the output iterator is an unchecked iterator calls to the standard function will cause compiler warnings.

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

  basic_string::operator[]	bitset::operator[]	deque::back	deque::front
  deque::operator[]	list::back	list::front	queue::back
  queue::front	vector::operator[]	vector::back	vector::front

When _SECURE_SCL is defined as 0:

• All standard iterators are unchecked (iterators can move beyond the container boundaries, which leads to undefined behavior).

• If an output iterator is a checked iterator you will get checked behavior on calls to the standard function (for example, std::copy).

• If an output iterator is an unchecked iterator you will get unchecked behavior on calls to the standard function (for example, std::copy).

A checked iterator refers to an iterator that will call invalid_parameter_handler if you attempt to move past the boundaries of the container. For more information about invalid_parameter_handler, see Parameter Validation.

checked_array_iterator Class and unchecked_array_iterator Class are the iterator adaptors that support checked iterators.

Example

When you compile by using _SECURE_SCL 1, 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.

// checked_iterators_1.cpp
// cl.exe /Zi /MDd /EHsc /W4
 
#define _ITERATOR_DEBUG_LEVEL 1
// implies #define _SECURE_SCL 1
 
#include <vector>
#include <iostream>
 
using namespace std;
 
int main() 
{
    vector<int> v;
    v.push_back(67);
 
    int i = v[0];
    cout << i << endl;
 
    i = v[1]; // triggers invalid parameter handler
};

This program will print out "67" then pop an assertion failure dialog box with additional information about the failure.

Similarly, when you compile by using _SECURE_SCL 1, a runtime error will occur if you attempt to access an element by using front or back of certain classes, when the container is empty.

// checked_iterators_2.cpp
// cl.exe /Zi /MDd /EHsc /W4
 
#define _ITERATOR_DEBUG_LEVEL 1
// implies #define _SECURE_SCL 1
 
#include <vector>
#include <iostream>
 
using namespace std;
 
int main() 
{
    vector<int> v;
 
    int& i = v.front(); // triggers invalid parameter handler
};

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

See Also

Reference

Standard C++ Library Overview

Debug Iterator Support