Export (0) Print
Expand All

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.

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 note 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:

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.

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.

Show:
© 2014 Microsoft