# Boost.MultiIndex Advanced topics

Tutorial
Index
Reference

## Contents

- Hashed indices
  - Unique and non-unique variants
  - Specification
  - Lookup
  - Updating
  - Guarantees on iterator validity and exception safety
- Composite keys
  - Composite keys and hashed indices
- Advanced features of Boost.MultiIndex key extractors
- Use of `ctor_args_list`
- Serialization
- Debugging support
  - Safe mode
    - Serialization and safe mode
  - Invariant-checking mode
- Emulating standard containers with `multi_index_container`
  - Emulation of associative containers
  - Emulation of `std::list`
- Metaprogramming and `multi_index_container`
  - MPL analysis
  - MPL synthesis

## Hashed indices

Hashed indices constitute a trade-off with respect to ordered indices: if correctly used, they provide much faster lookup of elements, at the expense of losing sorting information. Let us revisit our `employee_set` example: suppose a field for storing the Social Security number is added, with the requisite that lookup by this number should be as fast as possible. Instead of the usual ordered index, a hashed index can be resorted to:

>     struct employee
>     {
>       int         id;
>       std::string name;
>       int         ssnumber;

>       employee(int id,const std::string& name,int ssnumber):
>         id(id),name(name),ssnumber(ssnumber){}

>       bool operator<(const employee& e)const{return id<e.id;}
>     };

>     typedef multi_index_container<
>       employee,
>       indexed_by<
>         // sort by employee::operator<
>         ordered_unique<identity<employee> >,

>         // sort by less<string> on name
>         ordered_non_unique<member<employee,std::string,&employee::name> >,

>         // hashed on ssnumber
>         hashed_unique<member<employee,int,&employee::ssnumber> >
>       >
>     > employee_set

Note that the hashed index does not guarantee any particular ordering of the elements: so, for instance, we cannot efficiently query the employees whose SSN is greater than a given number. Usually, you must consider these restrictions when determining whether a hashed index is preferred over an ordered one.

If you are familiar with non-standard `hash_set`s provided by some compiler vendors, then learning to use hashed indices should be straightforward. However, the interface of hashed indices is modeled after the specification for unordered associative containers by the C++ Standard Library Technical Report (TR1), which differs in some significant aspects from existing pre-standard implementations:

- As there is no notion of ordering between keys, the lookup interface does not offer `lower_bound` or `upper_bound` member functions (unlike Dinkumware's solution.)
- A set of member functions is provided for handling the internal bucket structure on which hashed indices rely. This includes facilities for rehashing, control of the load factor (number of elements divided by number of buckets), and inspection of the buckets contents. Pre-standard implementations do not have such an extensive functionality.

Check the reference for a complete specification of the interface of hashed indices, and example 8 and example 9 for practical applications.

### Unique and non-unique variants

Just like ordered indices, hashed indices have unique and non-unique variants, selected with the specifiers `hashed_unique` and `hashed_non_unique`, respectively. In the latter case, elements with equivalent keys are kept together and can be jointly retrieved by means of the `equal_range` member function.

### Specification

Hashed indices specifiers have two alternative syntaxes, depending on whether tags are provided or not:

>     (hashed_unique | hashed_non_unique)
>       <[(tag)[,(key extractor)[,(hash function)[,(equality predicate)]]]]>

>     (hashed_unique | hashed_non_unique)
>       <[(key extractor)[,(hash function)[,(equality predicate)]]]>

The key extractor parameter works in exactly the same way as for ordered indices; lookup, insertion, etc., are based on the key returned by the extractor rather than the whole element.

The hash function is the very core of the fast lookup capabilities of this type of indices: a hasher is just a `Unary Function` returning an `std::size_t` value for any given key. In general, it is impossible that every key map to a different hash value, for the space of keys can be greater than the number of permissible hash codes: what makes for a good hasher is that the probability of a collision (two different keys with the same hash value) is as close to zero as possible. This is a statistical property depending on the typical distribution of keys in a given application, so it is not feasible to have a general-purpose hash function with excellent results in every possible scenario; the default value for this parameter uses Boost.Hash, which often provides good enough results.

The equality predicate is used to determine whether two keys are to be treated as the same. The default value `std::equal_to<KeyFromValue::result_type>` is in most cases exactly what is needed, so very rarely will you have to provide your own predicate. Note that hashed indices require that two equivalent keys have the same hash value, which in practice greatly reduces the freedom in choosing an equality predicate.

### Lookup

The lookup interface of hashed indices consists in member functions `find`, `count` and `equal_range`. Note that `lower_bound` and `upper_bound` are not provided, as there is no intrinsic ordering of keys in this type of indices.

Just as with ordered indices, these member functions take keys as their search arguments, rather than entire objects. Remember that ordered indices lookup operations are further augmented to accept compatible keys, which can roughly be regarded as "subkeys". For hashed indices, a concept of compatible key is also supported, though its usefulness is much more limited: basically, a compatible key is an object which is entirely equivalent to a native object of `key_type` value, though maybe with a different internal representation:

>     // US SSN numbering scheme
>     struct ssn
>     {
>       ssn(int area_no,int group_no,int serial_no):
>         area_no(area_no),group_no(group_no),serial_no(serial_no)
>       {}

>       int to_int()const
>       {
>         return serial_no+10000*group_no+1000000*area_no;
>       }

>     private:
>       int area_no;
>       int group_no;
>       int serial_no;
>     };

>     // interoperability with SSNs in raw int form

>     struct ssn_equal
>     {
>       bool operator()(const ssn& x,int y)const
>       {
>         return x.to_int()==y;
>       }

>       bool operator()(int x,const ssn& y)const
>       {
>         return x==y.to_int();
>       }
>     };

>     struct ssn_hash
>     {
>       std::size_t operator()(const ssn& x)const
>       {
>         return boost::hash<int>()(x.to_int());
>       }

>       std::size_t operator()(int x)const
>       {
>         return boost::hash<int>()(x);
>       }
>     };

>     typedef employee_set::nth_index<2>::type employee_set_by_ssn;

>     employee_set         es;
>     employee_set_by_ssn& ssn_index=es.get<2>();
>     ...
>     // find an employee by ssn
>     employee e=*(ssn_index.find(ssn(12,1005,20678),ssn_hash(),ssn_equal()));

In the example, we provided a hash functor `ssn_hash` and an equality predicate `ssn_equal` allowing for interoperability between `ssn` objects and the raw `int`s stored as `SSN`s in `employee_set`.

By far, the most useful application of compatible keys in the context of hashed indices lies in the fact that they allow for seamless usage of composite keys.

### Updating

Hashed indices have `replace`, `modify` and `modify_key` member functions, with the same functionality as in ordered indices.

### Guarantees on iterator validity and exception safety

Due to the internal constraints imposed by the Boost.MultiIndex framework, hashed indices provide guarantees on iterator validity and exception safety that are actually stronger than required by the C++ Standard Library Technical Report (TR1) with respect to unordered associative containers:

- Iterator validity is preserved in any case during insertion or rehashing: TR1 allows for iterator invalidation when a rehash (implicit or explicit) is performed.
- Erasing an element or range of elements via iterators does not throw ever, as the internal hash function and equality predicate objects are not actually invoked.
- `rehash` provides the strong exception safety guarantee unconditionally. TR1 only warrants it if the internal hash function and equality predicate objects do not throw. The somewhat surprising consequence is that a TR1-compliant unordered associative container might erase elements if an exception is thrown during rehashing!

In general, these stronger guarantees play in favor of the user's convenience, specially that which refers to iterator stability. A (hopefully minimal) degradation in performance might result in exchange for these commodities, though.

## Composite keys

In relational databases, composite keys depend on two or more fields of a given table. The analogous concept in Boost.MultiIndex is modeled by means of `composite_key`, as shown in the example:

>     struct phonebook_entry
>     {
>       std::string family_name;
>       std::string given_name;
>       std::string phone_number;

>       phonebook_entry(
>         std::string family_name,
>         std::string given_name,
>         std::string phone_number):
>         family_name(family_name),given_name(given_name),phone_number(phone_number)
>       {}
>     };

>     // define a multi_index_container with a composite key on
>     // (family_name,given_name)
>     typedef multi_index_container<
>       phonebook_entry,
>       indexed_by<
>         //non-unique as some subscribers might have more than one number
>         ordered_non_unique<
>           composite_key<
>             phonebook_entry,
>             member<phonebook_entry,std::string,&phonebook_entry::family_name>,
>             member<phonebook_entry,std::string,&phonebook_entry::given_name>
>           >
>         >,
>         ordered_unique< // unique as numbers belong to only one subscriber
>           member<phonebook_entry,std::string,&phonebook_entry::phone_number>
>         >
>       >
>     > phonebook;

`composite_key` accepts two or more key extractors on the same value (here, `phonebook_entry`). Lookup operations on a composite key are accomplished by passing tuples with the values searched:

>     phonebook pb;
>     ...
>     // search for Dorothea White's number
>     phonebook::iterator it=pb.find(
>       boost::make_tuple(std::string("White"),std::string("Dorothea")));
>     std::string number=it->phone_number;

Composite keys are sorted by lexicographical order, i.e. sorting is performed by the first key, then the second key if the first one is equal, etc. This order allows for partial searches where only the first keys are specified:

>     phonebook pb;
>     ...
>     // look for all Whites
>     std::pair<phonebook::iterator,phonebook::iterator> p=
>       pb.equal_range(boost::make_tuple(std::string("White")));

On the other hand, partial searches without specifying the first keys are not allowed.

By default, the corresponding `std::less` predicate is used for each subkey of a composite key. Alternate comparison predicates can be specified with `composite_key_compare`:

>     // phonebook with given names in reverse order

>     typedef multi_index_container<
>       phonebook_entry,
>       indexed_by<
>         ordered_non_unique<
>           composite_key<
>             phonebook_entry,
>             member<phonebook_entry,std::string,&phonebook_entry::family_name>,
>             member<phonebook_entry,std::string,&phonebook_entry::given_name>
>           >,
>           composite_key_compare<
>             std::less<std::string>,   // family names sorted as by default
>             std::greater<std::string> // given names reversed
>           >
>         >,
>         ordered_unique<
>           member<phonebook_entry,std::string,&phonebook_entry::phone_number>
>         >
>       >
>     > phonebook;

See example 7 in the examples section for an application of `composite_key`.

### Composite keys and hashed indices

Composite keys can also be used with hashed indices in a straightforward manner:

>     struct street_entry
>     {
>       // quadrant coordinates
>       int x;
>       int y;

>       std::string name;

>       street_entry(int x,int y,const std::string& name):x(x),y(y),name(name){}
>     };

>     typedef multi_index_container<
>       street_entry,
>       indexed_by<
>         hashed_non_unique< // indexed by quadrant coordinates
>           composite_key<
>             street_entry,
>             member<street_entry,int,&street_entry::x>,
>             member<street_entry,int,&street_entry::y>
>           >
>         >,
>         hashed_non_unique< // indexed by street name
>           member<street_entry,std::string,&street_entry::name>
>         >
>       >
>     > street_locator;

>     street_locator sl;
>     ...
>     void streets_in_quadrant(int x,int y)
>     {
>       std::pair<street_locator::iterator,street_locator::iterator> p=
>         sl.equal_range(boost::make_tuple(x,y));

>       while(p.first!=p.second){
>         std::cout<<p.first->name<<std::endl;
>         ++p.first;
>       }
>     }

Note that hashing is automatically taken care of: `boost::hash` is specialized to hash a composite key as a function of the `boost::hash` values of its elements. Should we need to specify different hash functions for the elements of a composite key, we can explicitly do so by using the `composite_key_hash` utility:

>     struct tuned_int_hash
>     {
>       int operator()(int x)const
>       {
>         // specially tuned hash for this application
>       }
>     };

>     typedef multi_index_container<
>       street_entry,
>       indexed_by<
>         hashed_non_unique< // indexed by quadrant coordinates
>           composite_key<
>             street_entry,
>             member<street_entry,int,&street_entry::x>,
>             member<street_entry,int,&street_entry::y>
>           >,
>           composite_key_hash<
>             tuned_int_hash,
>             tuned_int_hash
>           >
>         >,
>         hashed_non_unique< // indexed by street name
>           member<street_entry,std::string,&street_entry::name>
>         >
>       >
>     > street_locator;

Also, equality of composite keys can be tuned with `composite_key_equal_to`, though in most cases the default equality predicate (relying on the `std::equal_to` instantiations for the element types) will be the right choice.

Unlike with ordered indices, we cannot perform partial searches specifying only the first elements of a composite key:

>     // try to locate streets in quadrants with x==0
>     // compile-time error: hashed indices do not allow such operations
>     std::pair<street_locator::iterator,street_locator::iterator> p=
>       sl.equal_range(boost::make_tuple(0));

The reason for this limitation is quite logical: as the hash value of a composite key depends on all of its elements, it is impossible to calculate it from partial information.

## Advanced features of Boost.MultiIndex key extractors

The `Key Extractor` concept allows the same object to extract keys from several different types, possibly through suitably defined overloads of `operator()`:

>     // example of a name extractor from employee and employee *
>     struct name_extractor
>     {
>       const std::string& operator()(const employee& e)const{return e.name;}
>       std::string&       operator()(employee& e)const{return e.name;}
>       std::string&       operator()(employee* e)const{return e->name;}
>     };

This possibility is fully exploited by predefined key extractors provided by Boost.MultiIndex, making it simpler to define `multi_index_container`s where elements are pointers or references to the actual objects. The following specifies a `multi_index_container` of pointers to employees sorted by their names.

>     typedef multi_index_container<
>       employee *,
>       indexed_by<
>         ordered_non_unique<member<employee,std::string,&employee::name> > >
>     > employee_set;

Note that this is specified in exactly the same manner as a `multi_index_container` of actual `employee` objects: `member` takes care of the extra dereferencing needed to gain access to `employee::name`. A similar functionality is provided for interoperability with reference wrappers from Boost.Ref:

>     typedef multi_index_container<
>       boost::reference_wrapper<const employee>,
>       indexed_by<
>         ordered_non_unique<member<employee,std::string,&employee::name> > >
>     > employee_set;

In fact, support for pointers is further extended to accept what we call chained pointers. Such a chained pointer is defined by induction as a raw or smart pointer or iterator to the actual element, to a reference wrapper of the element or to another chained pointer; that is, chained pointers are arbitrary compositions of pointer-like types ultimately dereferencing to the element from where the key is to be extracted. Examples of chained pointers to `employee` are:

- `employee *`,
- `const employee *`,
- `std::auto_ptr<employee>`,
- `std::list<boost::reference_wrapper<employee> >::iterator`,
- `employee **`,
- `boost::shared_ptr<const employee *>`.

In general, chained pointers with dereferencing distance greater than 1 are not likely to be used in a normal program, but they can arise in frameworks which construct "views" as `multi_index_container`s from preexisting `multi_index_container`s.

In order to present a short summary of the different usages of Boost.MultiIndex key extractors in the presence of reference wrappers and pointers, consider the following final type:

>     struct T
>     {
>       int       i;
>       const int j;
>       int       f()const;
>       int       g();
>     };

The table below lists the appropriate key extractors to be used for different pointer and reference wrapper types based on `T`, for each of its members.

Use cases for Boost.MultiIndex key extractors.
element type | key | key extractor | applicable to `const` elements? | read/write?
--- | --- | --- | --- | ---
`T` | `i` | `member<T,int,&T::i>` | yes | yes
`j` | `member<T,const int,&T::j>` | yes | no
`f()` | `const_mem_fun<T,int,&T::f>` | yes | no
`g()` | `mem_fun<T,int,&T::g>` | no | no
`reference_wrapper<T>` | `i` | `member<T,int,&T::i>` | yes | yes
`j` | `member<T,const int,&T::j>` | yes | no
`f()` | `const_mem_fun<T,int,&T::f>` | yes | no
`g()` | `mem_fun<T,int,&T::g>` | yes | no
`reference_wrapper<const T>` | `i` | `member<T,const int,&T::i>` | yes | no
`j` | `member<T,const int,&T::j>` | yes | no
`f()` | `const_mem_fun<T,int,&T::f>` | yes | no
`g()` |
chained pointer to `T` or to `reference_wrapper<T>` | `i` | `member<T,int,&T::i>` | yes | yes
`j` | `member<T,const int,&T::j>` | yes | no
`f()` | `const_mem_fun<T,int,&T::f>` | yes | no
`g()` | `mem_fun<T,int,&T::g>` | yes | no
chained pointer to `const T` or to `reference_wrapper<const T>` | `i` | `member<T,const int,&T::i>` | yes | no
`j` | `member<T,const int,&T::j>` | yes | no
`f()` | `const_mem_fun<T,int,&T::f>` | yes | no
`g()` |

The column "applicable to `const` elements?" states whether the corresponding key extractor can be used when passed constant elements (this relates to the elements specified in the first column, not the referenced `T` objects). The only negative case is for `T::g` when the elements are raw `T` objects, which make sense as we are dealing with a non-constant member function: this also implies that `multi_index_container`s of elements of `T` cannot be sorted by `T::g`, because elements contained within a `multi_index_container` are treated as constant.

A key extractor is called read/write if it returns a non-constant reference to the key when passed a non-constant element, and it is called read-only otherwise. In order to use `multi_index_container::modify_key`, the associated key extractor must be read/write. The column "read/write?" shows that most combinations yield read-only extractors.

Some care has to be taken to preserve `const`-correctness in the specification of the key extractors: in some sense, the `const` qualifier is carried along to the member part, even if that particular member is not defined as `const`. For instance, if the elements are of type `const T *`, sorting by `T::i` is not specified as `member<const T,int,&T::i>`, but rather as `member<T,const int,&T::i>`.

For practical demonstrations of use of these key extractors, refer to example 2 and example 6 in the examples section.

## Use of `ctor_args_list`

Although in most cases `multi_index_container`s will be default constructed (or copied from a preexisting `multi_index_container`), sometimes it is necessary to specify particular values for the internal objects used (key extractors, comparison predicates, allocator), for instance if some of these objects do not have a default constructor. The same situation can arise with standard STL containers, which allow for the optional specification of such objects:

>     // example of non-default constructed std::set
>     template<typename IntegralType>
>     struct modulo_less
>     {
>       modulo_less(IntegralType m):modulo(m){}

>       bool operator()(IntegralType x,IntegralType y)const
>       {
>         return (x%modulo)<(y%modulo);
>       }

>     private:
>       IntegralType modulo;
>     };

>     typedef std::set<unsigned int,modulo_less<unsigned int> > modulo_set;

>     modulo_set m(modulo_less<unsigned int>(10));

`multi_index_container` does also provide this functionality, though in a considerably more complex fashion, due to the fact that the constructor of a `multi_index_container` has to accept values for all the internal objects of its indices. The full form of `multi_index_container` constructor is

>     explicit multi_index_container(
>         const ctor_args_list& args_list=ctor_args_list(),
>         const allocator_type& al=allocator_type());

The specification of the allocator object poses no particular problems; as for the `ctor_args_list`, this object is designed so as to hold the necessary construction values for every index in the `multi_index_container`. From the point of view of the user, `ctor_args_list` is equivalent to the type

>     boost::tuple<C0,...,CI-1>

where `I` is the number of indices, and `Ci` is

>     nth_index<i>::type::ctor_args

that is, the nested type `ctor_args` of the `i`-th index. Each `ctor_args` type is in turn a tuple holding values for constructor arguments of the associated index: so, ordered indices demand a key extractor object and a comparison predicate, hashed indices take an initial number of buckets, a key extractor, a hash function and an equality predicate; while sequenced indices do not need any construction argument. For instance, given the definition

>     typedef multi_index_container<
>       unsigned int,
>       indexed_by<
>         hashed_unique<identity<unsigned int> >,
>         ordered_non_unique<identity<unsigned int>, modulo_less<unsigned int> >,
>         sequenced<>
>       >
>     > modulo_indexed_set;

the corresponding `ctor_args_list` type is equivalent to

>     boost::tuple<
>       // ctr_args of index #0
>       boost::tuple<
>         std::size_t, // initial number of buckets; 0 if unspecified
>         identity<unsigned int>,
>         boost::hash<unsigned int>,
>         std::equal_to<unsigned int> >,

>       // ctr_args of index #1
>       boost::tuple<
>         identity<unsigned int>,
>         modulo_less<unsigned int> >,

>       // sequenced indices do not have any construction argument
>       boost::tuple<>
>     >

Such a `modulo_indexed_set` cannot be default constructed, because `modulo_less` does not provide a default constructor. The following shows how the construction can be done:

>     modulo_indexed_set::ctor_args_list args_list=
>       boost::make_tuple(
>         // ctor_args for index #0 is default constructible
>         modulo_indexed_set::nth_index<0>::type::ctor_args(),

>         boost::make_tuple(identity<unsigned int>(),modulo_less<unsigned int>(10)),

>         // this is also default constructible  (actually, an empty tuple)
>         modulo_indexed_set::nth_index<2>::type::ctor_args(),
>       );

>     modulo_indexed_set m(args_list);

A program is provided in the examples section that puts in practise these concepts.

## Serialization

`multi_index_container`s can be archived and retrieved by means of the Boost Serialization Library. Both regular and XML archives are supported. The usage is straightforward and does not differ from any other serializable type. For instance:

>     #include <boost/archive/text_oarchive.hpp>
>     #include <boost/archive/text_iarchive.hpp>
>     #include <fstream>

>     ...

>     void save(const employee_set& es)
>     {
>       std::ofstream ofs("data");
>       boost::archive::text_oarchive oa(ofs);
>       oa<<es;
>     }

>     void load(employee_set& es)
>     {
>       std::ifstream ifs("data");
>       boost::archive::text_iarchive ia(ifs);
>       ia>>es;
>     }

>     ...

>     employee_set es;
>     ... // fill it with data
>     save(es);

>     ...

>     employee_set restored_es;
>     load(restored_es);

Serialization capabilities are automatically provided by just linking with the appropriate Boost.Serialization library module: it is not necessary to explicitly include any header from Boost.Serialization, apart from those declaring the type of archive used in the process. If not used, however, serialization support can be disabled by globally defining the macro `BOOST_MULTI_INDEX_DISABLE_SERIALIZATION`. Disabling serialization for Boost.MultiIndex can yield a small improvement in build times, and may be necessary in those defective compilers that fail to correctly process Boost.Serialization headers.

When retrieving an archived `multi_index_container`, not only the elements are restored, but also the order they were arranged into for every index of the container. This is specially important with sequenced indices, whose ordering is not automatically fixed, as happens for ordered unique indices. Ordered non-unique indices are an in-between case: elements with different keys are sorted in ascending order, but there is no implicit traversal order for elements with the same key. Serialization of `multi_index_container` addresses this issue, so that restored ordered non-unique indices are sorted in exactly the same way as their originals. As for hashed indices, no guarantee is made about the order in which elements will be iterated in the restored container: in general, it is unwise to rely on the ordering of elements of a hashed index, since it can change in arbitrary ways during insertion or rehashing.

Iterators to indices of a `multi_index_container` can also be serialized. Serialization of iterators must be done only after serializing its corresponding container.

Example 9 in the examples section shows the serialization capabilities of Boost.MultiIndex.

## Debugging support

The concept of Design by Contract, originally developed as part of Bertrand Meyer's Eiffel language, revolves around the formulation of a contract between the user of a library and the implementor, by which the first is required to respect some preconditions on the values passed when invoking methods of the library, and the implementor guarantees in return that certain constraints on the results are met (postconditions), as well as the honoring of specified internal consistency rules, called invariants. Eiffel natively supports the three parts of the contract just described by means of constructs `require`, `ensure` and `invariant`, respectively.

C++ does not enjoy direct support for Design by Contract techniques: these are customarily implemented as assertion code, often turned off in release mode for performance reasons. Following this approach, Boost.MultiIndex provides two distinct debugging modes:

- Safe mode checks preconditions on the invocations to the facilities of the library,
- invariant-checking mode performs post-execution checks aimed at ensuring that the internal consistency of the library is preserved.

These two modes are independent of each other and can be set on or off individually. It is important to note that errors detected by safe mode are due in principle to faulty code in the user's program, while invariant-checking mode detects potential internal bugs in the implementation of Boost.MultiIndex.

### Safe mode

The idea of adding precondition checking facilities to STL as a debugging aid was first introduced by Cay S. Horstmann in his Safe STL library and later adopted by STLport Debug Mode. Similarly, Boost.MultiIndex features the so-called safe mode in which all sorts of preconditions are checked when dealing with iterators and functions of the library.

Boost.MultiIndex safe mode is set by globally defining the macro `BOOST_MULTI_INDEX_ENABLE_SAFE_MODE`. Error conditions are checked via the macro `BOOST_MULTI_INDEX_SAFE_MODE_ASSERT`, which by default resolves to a call to `BOOST_ASSERT`.

If the user decides to define her own version of `BOOST_MULTI_INDEX_SAFE_MODE_ASSERT`, it has to take the form

>     BOOST_MULTI_INDEX_SAFE_MODE_ASSERT(expr,error_code)

where `expr` is the condition checked and `error_code` is one value of the `safe_mode::error_code` enumeration:

>     namespace boost{

>     namespace multi_index{

>     namespace safe_mode{

>     enum error_code
>     {
>       invalid_iterator,             // vg. default cted or pointing to erased element
>       not_dereferenceable_iterator, // iterator is not dereferenceable
>       not_incrementable_iterator,   // iterator points to end of sequence
>       not_decrementable_iterator,   // iterator points to beginning of sequence
>       not_owner,                    // iterator does not belong to the container
>       not_same_owner,               // iterators belong to different containers
>       invalid_range,                // last not reachable from first
>       inside_range,                 // iterator lies within a range (and it mustn't)
>       same_container                // containers ought to be different
>     };

>     } // namespace multi_index::safe_mode

>     } // namespace multi_index

>     } // namespace boost

For instance, the following replacement of `BOOST_MULTI_INDEX_SAFE_MODE_ASSERT` throws an exception instead of asserting:

>     #include <boost/multi_index_container/safe_mode_errors.hpp>

>     struct safe_mode_exception
>     {
>       safe_mode_exception(boost::multi_index::safe_mode::error_code error_code):
>         error_code(error_code)
>       {}

>       boost::multi_index::safe_mode::error_code error_code;
>     };

>     #define BOOST_MULTI_INDEX_SAFE_MODE_ASSERT(expr,error_code) \
>     if(!(expr)){throw safe_mode_exception(error_code);}

>     // This has to go before the inclusion of any header from Boost.MultiIndex,
>     // except possibly safe_error_codes.hpp.

Other possibilites, like outputting to a log or firing some kind of alert, are also implementable.

Warning: Safe mode adds a very important overhead to the program both in terms of space and time used, so in general it should not be set for `NDEBUG` builds. Also, this mode is intended solely as a debugging aid, and programs must not rely on it as part of their normal execution flow: in particular, no guarantee is made that all possible precondition errors are diagnosed, or that the checks remain stable across different versions of the library.

#### Serialization and safe mode

Iterators restored from an archive are not subject to safe mode checks. This is so because it is not possible to automatically know the associated `multi_index_container` of an iterator from the serialization information alone. However, if desired, a restored iterator can be converted to a checked value by using the following workaround:

>     employee_set es;
>     employee_set::nth_index<1>::iterator it;

>     // restore es and it from an archive ar
>     ar>>es;
>     ar>>it; // it won't benefit from safe mode checks

>     // turn it into a checked value by providing
>     // Boost.MultiIndex with info about the associated container
>     it=es.project<1>(it);

### Invariant-checking mode

The so called invariant-checking mode of Boost.MultiIndex can be set by globally defining the macro `BOOST_MULTI_INDEX_ENABLE_INVARIANT_CHECKING`. When this mode is in effect, all public functions of Boost.MultiIndex will perform post-execution tests aimed at ensuring that the basic internal invariants of the data structures managed are preserved.

If an invariant test fails, Boost.MultiIndex will indicate the failure by means of the unary macro `BOOST_MULTI_INDEX_INVARIANT_ASSERT`. Unless the user provides a definition for this macro, it defaults to `BOOST_ASSERT`. Any assertion of this kind should be regarded in principle as a bug in the library. Please report such problems, along with as much contextual information as possible, to the maintainer of the library.

It is recommended that users of Boost.MultiIndex always set the invariant-checking mode in debug builds.

## Emulating standard containers with `multi_index_container`

### Emulation of associative containers

Academic movitations aside, there is a practical interest in emulating standard associative containers by means of `multi_index_container`, namely to take advantage of extended functionalities provided by `multi_index_container` for lookup, range querying and updating.

In order to emulate a `std::set` one can follow the substitution rule:

>     std::set<Key,Compare,Allocator> ->
>       multi_index_container<
>         Key,
>         indexed_by<ordered_unique<identity<Key>,Compare> >,
>         Allocator
>       >

In the default case where `Compare=std::less<Key>` and `Allocator=std::allocator<Key>`, the substitution rule is simplified as

>     std::set<Key> -> multi_index_container<Key>

The substitution of `multi_index_container` for `std::set` keeps the whole set of functionality provided by `std::set`, so in principle it is a drop-in replacement needing no further adjustments.

`std::multiset` can be emulated in a similar manner, according to the following rule:

>     std::multiset<Key,Compare,Allocator> ->
>       multi_index_container<
>         Key,
>         indexed_by<ordered_non_unique<identity<Key>,Compare> >,
>         Allocator
>       >

When default values are taken into consideration, the rule takes the form

>     std::multiset<Key> ->
>       multi_index_container<
>         Key,
>         indexed_by<ordered_non_unique<identity<Key> > >
>       >

The emulation of `std::multiset`s with `multi_index_container` results in a slight difference with respect to the interface offered: the member function `insert(const value_type&)` does not return an `iterator` as in `std::multiset`s, but rather a `std::pair<iterator,bool>` in the spirit of `std::set`s. In this particular case, however, the `bool` member of the returned pair is always `true`.

The case of `std::map`s and `std::multimap`s does not lend itself to such a direct emulation by means of `multi_index_container`. The main problem lies in the fact that elements of a `multi_index_container` are treated as constant, while the `std::map` and `std::multimap` handle objects of type `std::pair<const Key,T>`, thus allowing for free modification of the value part. To overcome this difficulty we need to create an ad hoc pair class:

>     template <typename T1,typename T2>
>     struct mutable_pair
>     {
>       typedef T1 first_type;
>       typedef T2 second_type;

>       mutable_pair():first(T1()),second(T2()){}
>       mutable_pair(const T1& f,const T2& s):first(f),second(s){}
>       mutable_pair(const std::pair<T1,T2>& p):first(p.first),second(p.second){}

>       T1         first;
>       mutable T2 second;
>     };

and so the substitution rules are:

>     std::map<Key,T,Compare,Allocator> ->
>       multi_index_container<
>         Element,
>         indexed_by<
>           ordered_unique<member<Element,Key,&Element::first>,Compare>
>         >,
>         typename Allocator::template rebind<Element>::other
>       >

>     std::multimap<Key,T,Compare,Allocator> ->
>       multi_index_container<
>         Element,
>         indexed_by<
>           ordered_non_unique<member<Element,Key,&Element::first>,Compare>
>         >,
>         typename Allocator::template rebind<Element>::other
>       >

>     (with Element=mutable_pair<Key,T>)

If default values are considered, the rules take the form:

>     std::map<Key,T> ->
>       multi_index_container<
>         Element,
>         indexed_by<ordered_unique<member<Element,Key,&Element::first> > >
>       >

>     std::multimap<Key,T> ->
>       multi_index_container<
>         Element,
>         indexed_by<ordered_non_unique<member<Element,Key,&Element::first> > >
>       >

>     (with Element=mutable_pair<Key,T>)

Unlike as with standard sets, the interface of these `multi_index_container`-emulated maps does not exactly conform to that of `std::map`s and `std::multimap`s. The most obvious difference is the lack of `operator []`, either in read or write mode; this, however, can be emulated with appropriate use of `find` and `insert`.

These emulations of standard associative containers with `multi_index_container` are comparable to the original constructs in terms of space and time efficiency. See the performance section for further details.

### Emulation of `std::list`

Unlike the case of associative containers, emulating `std::list` in Boost.MultiIndex does not add any significant functionality, so the following is presented merely for completeness sake.

Much as with standard maps, the main difficulty to overcome when emulating `std::list` derives from the constant nature of elements of a `multi_index_container`. Again, some sort of adaption class is needed, like for instance the following:

>     template <typename T>
>     struct mutable_value
>     {
>       mutable_value(const T& t):t(t){}
>       operator T&()const{return t;}

>     private:
>       mutable T t;
>     };

which allows us to use the substitution rule:

>     std::list<T,Allocator> ->
>       multi_index_container<
>         Element,
>         indexed_by<sequenced<> >,
>         typename Allocator::template rebind<Element>::other
>       >

>     (with Element=mutable_value<T>)

or, if the default value `Allocator=std::allocator<T>` is used:

>     std::list<T> ->
>       multi_index_container<mutable_value<T>,indexed_by<sequenced<> > >

## Metaprogramming and `multi_index_container`

Boost.MultiIndex provides a number of facilities intended to allow the analysis and synthesis of `multi_index_container` instantiations by MPL metaprograms.

### MPL analysis

Given a `multi_index_container` instantiation, the following nested types are provided for compile-time inspection of the various types occurring in the definition of the `multi_index_container`:

- `index_specifier_type_list`,
- `index_type_list`,
- `iterator_type_list`,
- `const_iterator_type_list`.

Each of these types is an MPL sequence with as many elements as indices comprise the `multi_index_container`: for instance, the `n`-th element of `iterator_type_list` is the same as `nth_index_iterator<n>::type`.

A subtle but important distinction exists between `index_specifier_type_list` and `index_type_list`: the former typelist holds the index specifiers with which the `multi_index_container` instantiation was defined, while the latter gives access to the actual implementation classes corresponding to each specifier. An example will help to clarify this distinction. Given the instantiation:

>     typedef multi_index_container<
>       int,
>       indexed_by<
>         ordered_unique<identity<int> >,
>         sequenced<>
>       >
>     > indexed_t;

`indexed_t::index_specifier_type_list` is a type list with elements

>     ordered_unique<identity<int> >
>     sequenced<>

while `indexed_t::index_type_list` holds the types

>     multi_index_container::nth_type<0>::type
>     multi_index_container::nth_type<1>::type

so the typelists are radically different. Check the reference for the exact MPL sequence concepts modeled by these type lists.

### MPL synthesis

Although typically indices are specified by means of the `indexed_by` construct, actually any MPL sequence of index specifiers can be provided instead:

>     typedef mpl::vector<ordered_unique<identity<int> >,sequenced<> > index_list_t;

>     typedef multi_index_container<
>       int,
>       index_list_t
>     > indexed_t;

This possibility enables the synthesis of instantiations of `multi_index_container` through MPL metaprograms, as the following example shows:

>     // original multi_index_container instantiation
>     typedef multi_index_container<
>       int,
>       indexed_by<
>         ordered_unique<identity<int> >
>       >
>     >                                indexed_t1;

>     // we take its index list and add an index
>     typedef boost::mpl::push_front<
>       indexed_t1::index_specifier_type_list,
>       sequenced<>
>     >::type                          index_list_t;

>     // augmented multi_index_container
>     typedef multi_index_container<
>       int,
>       index_list_t
>     >                                indexed_t2;

Tutorial
Index
Reference

Revised August 24th 2005

© Copyright 2003-2005 Joaquín M López Muñoz. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)