1. Background

2. What it does

1. When an iterator is dereferenced, it must be valid (i.e. belong to a container and not be past the end).
2. When an iterator is incremented, it must be valid before the increment and valid or past the end after the increment. When an iterator is decremented, it must be valid or past the end before the decrement and valid after the decrement.
3. To compute the difference of two iterators or to compare two iterators with <, <=, >, >=, the iterators must point to the same container.
4. When a container is accessed through an iterator (like c.erase(i)), then the iterator must actually point inside the container.

If an error is detected, then an assertion failure is raised. (See section 6 to see how to change that behavior.)

Of course, checking and updating the iterators takes time. For release versions of your code, you would probably want to go back to the unchecked version of STL.

The interface of Safe STL is purposefully left the same as that of regular STL. It would be an easy matter to add public member functions to the iterators that check their status, but I believe that it is best not to develop yet another nonstandard template library.

Safe STL works better than a debugger or BoundsChecker for a number of reasons. If your code dies because of a pointer error that is the consequence of an STL usage error, the debugger will break deep in the bowels of STL code which is usually less than illuminating. If your code gets in an infinite loop because of an STL usage error, BoundsChecker will not actually complain. Some STL usage errors cause subtle inconsistencies in the STL data structures that will not lead to immediate failure. See the examples in section 4 for more information.

3. Some typical errors that Safe STL catches

• Runaway iterators

   list a;
   list b;
   // ...
  
   list::iterator p
   = find(a.begin(), b.end(), 100);
   // oops, should have been a.end()
  
   if (p != a.end()) a.erase(p);
  

  This code will loop forever when a.end() is reached.

  Of course nobody would make such a dumb coding mistake.

  I did several times, when I did some cut and paste and was sloppy about updating the pasted code.

• Muddled iterators

   list a;
   list b;
  
   list::iterator pa = a.begin();
   b.erase(pa);
  

  In the HP implementation, this will erase the first element of a, but reduce the length of b! Eventually, but not immediately, that will lead to weird behavior.
• Past the end iterators

   list::iterator p
    = find_if(a.begin(), a.end(), condition);
  
    cout << *p; // an error if p is past the end
  

• Uninitialized iterators

   list::iterator p;
   cout << *p; // an error
  

• Iterators to erased elements

   list::iterator p = a.begin();
   list::iterator q = p;
   a.erase(q);
  
   cout << *p; // an error
  

• Iterators to moved elements

   vector::iterator p = b.begin();
   b.reserve(1000);
   cout << *p; // maybe an error
  

• Iterators to destroyed containers

   list* pl = new list;
   list::iterator p = pl->begin();
   delete pl;
   cout << *p; // an error
  

4. How to use it

   algobase.h
   vector.h
   deque.h
   list.h
   tree.h

   bcc -I/safestl;/stl whatnot.cpp

Note: You must rebuild the ENTIRE application. You cannot have mixed object files that share STL containers and iterators, some compiled with the regular and others with the safe headers. I realize that may be impossible if some of your code is compiled into libraries whose interface references an STL container or iterator.

Once your application is debugged, simply remove /safestl from the include path and rebuild the application.

You will notice that Safe STL generates a large number of WARNINGS. Unfortunately, there is little I can do about that without modifying the original STL source extensively. Some warnings come from int/unsigned mismatches--they also occur in regular STL. Others have the form "functions with property X cannot be inline expanded". I don't want them inline expanded, but I have no choice--the Borland compiler does not support templates defining member functions of nested classes. If the Safe STL code becomes popular, I may rewrite it to eliminate most warnings, but deviating further from the regular STL code.

5. Changing the error handling

Why didn't I throw an exception when detecting a failure? That would have changed the interface of the STL classes, which I didn't want to do. Had the operations thrown exceptions upon failure, then you might write code catching them. That code would no longer work when you switch back to regular STL.

However, there is one major disadvantage to using assert. The debugger will not give you a stack trace at the point of failure, so you can't see what part of your code caused the problem. (The file and line number reported by assert are in the Safe STL header.) If your debugger can break on exception throw (like Turbo Debugger), you can view the stack and locate the offending code. A brutal but effective way is to turn the assertion failure into an exception. Before including the Safe STL headers,

 #define assert(X) if (!(X)) throw #X;

6. Supported platforms

7. Bug reports

PLEASE, NO REQUESTS FOR HANDHOLDING. If you can't compile the sample programs of the HP ftp site with regular and safe STL, or you don't know how to set up the files and the compiler, then I cannot and will not try to fix it for you.

I am particular interested in

• bugs that Safe STL should find but doesn't
• false alarms: bug messages in perfectly correct code (PLEASE read the STL documentation first before you report such a bug. For example, did you know that inserting into a deque invalidates ALL iterators to it?)