Boost C++ Libraries of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.

Boost.Intrusive Iterator features

Null forward iterators
Scary Iterators

Boost.Intrusive implements C++14 Null Forward Iterators, a feature that was introduced with C++14. This means that equality and inequality comparison are defined over all iterators for the same underlying sequence and the value initialized-iterators.

Value initialized iterators behave as if they refer past the end of the same empty sequence:

list<MyType> l = { ... };
auto ni = list<MyType>::iterator();
auto nd = list<MyType2>::iterator();
ni == ni; // True.
nd != nd; // False.
ni == nd; // Won't compile.

The paper N2913, titled SCARY Iterator Assignment and Initialization, proposed a requirement that a standard container's iterator types have no dependency on any type argument apart from the container's value_type, difference_type, pointer type, and const_pointer type. In particular, according to the proposal, the types of a standard container's iterators should not depend on the container's key_compare, hasher, key_equal, or allocator types.

That paper demonstrated that SCARY operations were crucial to the performant implementation of common design patterns using STL components. It showed that implementations that support SCARY operations reduce object code bloat by eliminating redundant specializations of iterator and algorithm templates.

Boost.Intrusive containers are a bit different from standard containers. In particular, they have no allocator parameter and they can be configured with additional options not present in STL-like containers. Thus Boost.Intrusive offers its own SCARY iterator implementation, where iterator types don't change when the container is configured with an option that does not alter the value <-> node transformation. More concretely, the following options and conditions guarantee that iterator types are unchanged:

  • All containers: size_type<>, constant_time_size<>,
  • slist: cache_last<>, linear<>,
  • unordered_[multi]set: hash<>, equal<>, power_2_buckets<>, cache_begin<>.
  • All tree-like containers ([multi]set, avl_[multi]set, sg_[multi]set, bs_[multi]set, splay_[multi]set, treap_[multi]set): compare<>.
  • treap_[multi]set: priority<>
  • bs_[multi]set, sg_[multi]set, treap_[multi]set, splay_[multi]set: They share the same iterator type when configured with the same options.