Description

template<class Label, class Value, class IndexTypeTag>
struct Sawyer::Container::TraceIndexTraits< Label, Value, IndexTypeTag >

Traits for a Trace label index.

The IndexTypeTag argument is used to select the index implementation used to associate some data with each label. Sawyer defines two kinds of indexes: the TraceMapIndexTag selects an index based on std::map while the TraceVectorIndexTag selects an index based on std::vector. The vector-based index is suitable for labels that can be used as vector indexes. The map-based index should be used for all other cases, including integer labels that would result in very sparse vectors.

Users are welcome to define their own index class. Their class should have the following interface:

The index must be able to store labels of type Label. Each label will have a default constructor, a copy constructor, an assignment operator, and be comparable as equal or not-equal. Additional requirements can be imposed by the index.
The index needs to be able to store arbitrary data of type Value per label. These values will always have a default constructor, a copy constructor, and an assignment operator. The index cannot impose additional requirements.
The index must have a clear method that takes no arguments and resets the index to its default constructed state.
The index must have two array operators whose argument is a Label and whose signature differes only in whether the this pointer is const. Both return a reference to either the Value stored for that label or a default-constructed Value. The operator that takes a const this pointer should return a const reference, and the value that takes a non-const this pointer must return a non-const reference. Furthermore, the non-const version must first insert a default-constructed value if no value was previously stored for the specified label.
The index must be able to return a boost::iterator_range pair of iterators that will index over its labels. These range is permitted to iterate over labels that are not part of a trace, as long as the iteration also visits each defined label exactly once. Dereferencing an non-end iterator must result in a valid Label object (or const reference to such).
The index must define a reserve method that takes a size_t argument. Its purpose is to give the index a chance to pre-allocate space. The argument is only a hint for the number of distinct labels that the trace might eventually contain.

To use a user-defined index, the user should define their index class, define a tag for their class, and specialize TraceIndexTraits. Here's a simple example where the user has a custom index for a specific user-defined label type:

class MyLabel {...};
 
template<class Value>
class MyLabelIndex; // see requirements above
 
class MyLabelIndexTag {};
 
namespace Sawyer { namespace Container {
    template<class Value>
    struct TraceIndexTraits<MyLabel, Value, MyLabelIndexTag> {
        typedef MyIndex<Value> Index;
    };
}}