CTR51-CPP. Use valid references, pointers, and iterators to reference elements of a container

Iterators are a generalization of pointers that allow a C++ program to work with different data structures (containers) in a uniform manner [ISO/IEC 14882-2014]. Pointers, references, and iterators share a close relationship in which it is required that referencing values be done through a valid iterator, pointer or reference. Storing an iterator, reference, or pointer to an element within a container for any length of time comes with a risk that the underlying container may be modified such that the stored iterator, pointer, or reference becomes invalid. For instance, when a sequence container such as std::vector requires an underlying reallocation, outstanding iterators, pointers, and references will be invalidated [Kalev 99]. Use only valid pointers, references, or iterators to refer to an element of a container.

According to the C++ Standard, [container.requirements.general], paragraph 12 [ISO/IEC 14882-2014]: 

Unless otherwise specified (either explicitly or by defining a function in terms of other functions), invoking a container member function or passing a container as an argument to a library function shall not invalidate iterators to, or change the values of, objects within that container.

Note that while the C++ Standard allows references and pointers to be invalidated independently, this is not a secure operation because the object pointed to by the pointer may be different than expected. For instance, it is possible to retrieve a pointer to an element from a container, erase that element (invalidating references when destroying the underlying object), then insert a new element at the same location within the container causing the extant pointer to now point to a valid, but different than the original, object. Thus, any operation that invalidates a pointer or a reference should be treated as though it invalidates both pointers and references.

The following container functions can invalidate iterators, references, and pointers under certain circumstances:

A std::basic_string object is also a container for which this rule applies. For more specific information pertaining to std::basic_string containers, see STR52-CPP. Use valid references, pointers, and iterators to reference elements of a basic_string.

Noncompliant Code Example

In this noncompliant code example, pos is invalidated after the first call to insert(), and subsequent loop iterations have undefined behavior:

#include <deque>
 
void f(const double *items, std::size_t count) {
  std::deque<double> d;
  auto pos = d.begin();
  for (std::size_t i = 0; i < count; ++i, ++pos) {
    d.insert(pos, items[i] + 41.0);
  }
}

Compliant Solution (Updated Iterator)

In this compliant solution, pos is assigned a valid iterator on each insertion, preventing undefined behavior:

#include <deque>
 
void f(const double *items, std::size_t count) {
  std::deque<double> d;
  auto pos = d.begin();
  for (std::size_t i = 0; i < count; ++i, ++pos) {
    pos = d.insert(pos, items[i] + 41.0);
  }
}

Compliant Solution (Generic Algorithm)

This compliant solution replaces the handwritten loop with the generic standard template library algorithm std::transform(). The call to std::transform() accepts the range of elements to transform, the location to store the transformed values (which, in this case, is a std::inserter object to insert them at the beginning of d), and the transformation function to apply (which, in this case, is a simple lambda).

#include <algorithm>
#include <deque>
#include <iterator>
 
void f(const double *items, std::size_t count) {
  std::deque<double> d;
  std::transform(items, items + count, std::inserter(d, d.begin()),
                 [](double d) { return d + 41.0; });
}

Noncompliant Code Example

In this noncompliant code example, data is invalidated after the call to replace(), and so its use in g() is undefined behavior:

#include <iostream>
#include <string>
 
extern void g(const char *);
 
void f(std::string &exampleString) {
  const char *data = exampleString.data();
  // ...
  exampleString.replace(0, 2, "bb");
  // ...
  g(data);

}

Compliant Solution

In this compliant solution, the pointer to exampleString's internal buffer is not generated until after the modifications from replace() have completed:

#include <iostream>
#include <string>

extern void g(const char *);

void f(std::string &exampleString) {
  // ...
  exampleString.replace(0, 2, "bb");
  // ...
  g(exampleString.data());
}

Risk Assessment

Using invalid references, pointers, or iterators to reference elements of a container results in undefined behavior.

Automated Detection

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the CERT website.

Related Guidelines

Bibliography