Key extraction classes are used by
key-based indices to
obtain the indexing keys from the elements of a multi_index_container.
An Assignable
class KeyFromValue is said to be a key extractor from a
type Type if

the type KeyFromValue::result_type is defined,

k1(ca) is defined and returns a value convertible
to const KeyFromValue::result_type&,

if k2 is a copy of k1, k1(ca) is the
same value as k2(ca),

for every k1, k2 of type const KeyFromValue,
and ca of type const Type&.

Additionally, KeyFromValue is a read/write key extractor
if the following extra conditions are met:

k1(a) is defined and returns a value convertible
to KeyFromValue::result_type&,

const_cast<const KeyFromValue::result_type&>(k1(a))
is the same value as
k1(const_cast<const Type&>(a)),

The key extractors provided by Boost.MultiIndex are templatized according
to the type Type and serve to extract keys not only from objects
of type Type, but also from reference wrappers provided by
Boost.Ref and from chained pointers
to Type (or to reference wrappers of Type): a chained pointer
is any type P such that, for an object p of type
const P

*p yields an object of type Type& or
boost::reference_wrapper<Type>, OR

*p yields a chained pointer to Type,

that is, chained pointers are arbitrary compositions of pointer-like objects
ultimately dereferencing to values of Type& or
boost::reference_wrapper<Type>.

identity is a Key Extractor
that acts as a do-nothing identity functor.

template<typenameType>structidentity{typedefTyperesult_type;// only provided if const ChainedPtr& is not convertible to const Type&template<typenameChainedPtr>Type&operator()(constChainedPtr&x)const;constType&operator()(constType&x)const;Type&operator()(Type&x)const;// only provided if Type is non-const
// only provided if Type is non-constconstType&operator()(constreference_wrapper<constType>&x)const;// only provided if Type is constType&operator()(constreference_wrapper<typenameremove_const<Type>::type>&x)const;Type&operator()(constreference_wrapper<Type>&x)const;};

member is a Key Extractor
aimed at accessing a given member of a class.

template<classClass,typenameType,TypeClass::*PtrToMember>structmember{typedefTyperesult_type;// only provided if const ChainedPtr& is not convertible to const Class&template<typenameChainedPtr>Type&operator()(constChainedPtr&x)const;constType&operator()(constClass&x)const;Type&operator()(Class&x)const;// only provided if Type is non-constconstType&operator()(constreference_wrapper<constClass>&x)const;Type&operator()(constreference_wrapper<Class>&x)const;};

The PtrToMember template argument specifies the particular
Type Class::* pointer to the member to be extracted.
member<Class,Type,PtrToMember> is a model of:

In this situation, member_offset provides an
alternative to member accepting offsets
instead of pointers to members. Please note that the use of
offsetof on non-POD types is forbidden by the standard;
luckily enough, most compilers accept it nevertheless, so
member_offset serves as a workaround for most practical purposes.

template<classClass,typenameType,std::size_tOffsetOfMember>structmember_offset{typedefTyperesult_type;// only provided if const ChainedPtr& is not convertible to const Class&template<typenameChainedPtr>Type&operator()(constChainedPtr&x)const;constType&operator()(constClass&x)const;Type&operator()(Class&x)const;// only provided if Type is non-constconstType&operator()(constreference_wrapper<constClass>&x)const;Type&operator()(constreference_wrapper<Class>&x)const;};

As an example of use, given the class

classA{intx;}

the instantiation member<A,int,&A::x> can be simulated then
as member_offset<A,int,offsetof(A,x)>.

const_mem_fun is a Key Extractor
returning as key the result of invoking a given constant member function of a class.

template<classClass,typenameType,Type(Class::*PtrToMemberFunction)()const>structconst_mem_fun{typedeftypenameremove_reference<Type>::typeresult_type;// only provided if const ChainedPtr& is not convertible to const Class&template<typenameChainedPtr>Typeoperator()(constChainedPtr&x)const;Typeoperator()(constClass&x)const;Typeoperator()(constreference_wrapper<constClass>&x)const;Typeoperator()(constreference_wrapper<Class>&x)const;};

The PtrToMemberFunction template argument specifies the particular
Type (Class::*PtrToMemberFunction)()const pointer to the the constant
member function used in the extraction.
const_mem_fun<Class,Type,PtrToMemberFunction> is a model of:

mem_fun is a Key Extractor
returning as key the result of invoking a given member function of a class.

template<classClass,typenameType,Type(Class::*PtrToMemberFunction)()>structmem_fun{typedeftypenameremove_reference<Type>::typeresult_type;// only provided if ChainedPtr& is not convertible to Class&template<typenameChainedPtr>Typeoperator()(constChainedPtr&x)const;Typeoperator()(Class&x)const;Typeoperator()(constreference_wrapper<Class>&x)const;};

The PtrToMemberFunction template argument specifies the particular
Type (Class::*PtrToMemberFunction)() pointer to the the member
function used in the extraction.
mem_fun<Class,Type,PtrToMemberFunction> is a model of:

MSVC++ 6.0 do not properly support pointers to constant member functions as non-type
template parameters, thus const_mem_fun cannot be
used in this compiler. A simple workaround consists in specifying the type of
these pointers as an additional template parameter.

template<classClass,typenameType,typenamePtrToMemberFunctionType,PtrToMemberFunctionTypePtrToMemberFunction>structconst_mem_fun_explicit{typedeftypenameremove_reference<Type>::typeresult_type;// only provided if const ChainedPtr& is not convertible to const Class&template<typenameChainedPtr>Typeoperator()(constChainedPtr&x)const;Typeoperator()(constClass&x)const;Typeoperator()(constreference_wrapper<constClass>&x)const;Typeoperator()(constreference_wrapper<Class>&x)const;};

const_mem_fun_explicit provides the very same functionality as
its const_mem_fun analogous instantiation. For example, given the type

structA{intf()const;};

the extractor const_mem_fun<A,int,&A::f> can be replaced by
const_mem_fun_explicit<A,int,int (A::*)()const,&A::f>.

For analogy with const_mem_fun_explicit,
a variation of mem_fun is provided accepting
an additional parameter with the type of the pointer to non-constant member function
used for extraction.

template<classClass,typenameType,typenamePtrToMemberFunctionType,PtrToMemberFunctionTypePtrToMemberFunction>structmem_fun_explicit{typedeftypenameremove_reference<Type>::typeresult_type;// only provided if ChainedPtr& is not convertible to Class&template<typenameChainedPtr>Typeoperator()(constChainedPtr&x)const;Typeoperator()(Class&x)const;Typeoperator()(constreference_wrapper<Class>&x)const;};

composite_key is a Key Extractor
returning the combined value of several key extractors whose type is specified
at compile time. The returned object is of type
composite_key_result<composite_key>.

template<typenameValue,typenameKeyFromValue0,...,typenameKeyFromValuen>structcomposite_key{typedeftuple<KeyFromValue0,...,KeyFromValuen>key_extractor_tuple;typedefValuevalue_type;typedefcomposite_key_result<composite_key>result_type;composite_key(constKeyFromValue0&k0=KeyFromValue0(),...constKeyFromValuen&kn=KeyFromValuen());composite_key(constkey_extractor_tuple&x);constkey_extractor_tuple&key_extractors()const;key_extractor_tuple&key_extractors()// only provided if const ChainedPtr& is not convertible to const value_type&template<typenameChainedPtr>result_typeoperator()(constChainedPtr&x)const;result_typeoperator()(constvalue_type&x)const;result_typeoperator()(constreference_wrapper<constvalue_type>&x)const;result_typeoperator()(constreference_wrapper<value_type>&x)const;};

KeyFromValue0, ... , KeyFromValuen are the types of
the key extractors combined into the composite key. Each of these types
must be a Key Extractor from
Value. At least a key extractor must be provided. The maximum
number of key extractors of a composite_key instantiation is
implementation defined. composite_key internally stores an
object of every constituent key extractor type.
composite_key<Value,KeyFromValue0,...,KeyFromValuen> is a model
of:

This is an opaque type returned by composite_key
instantiations as their extracted key.

template<typenameCompositeKey>structcomposite_key_result{no public interface available};// comparison:// OP is any of =,<,!=,>,>=,<=template<typenameCompositeKey1,typenameCompositeKey2>booloperatorOP(constcomposite_key_result<CompositeKey1>&x,constcomposite_key_result<CompositeKey2>&y);template<typenameCompositeKey,typenameValue0,...,typenameValuen>booloperatorOP(constcomposite_key_result<CompositeKey>&x,consttuple<Value0,...,Valuen>&y);template<typenameValue0,...,typenameValuen,typenameCompositeKey>booloperatorOP(consttuple<Value0,...,Valuen>&x,constcomposite_key_result<CompositeKey>&y);

CompositeKey is the composite_key instantiation to
which the composite_key_result type is associated. Objects of type
composite_key_result returned by a composite key must be always treated
as temporary, i.e. they should not be stored or copied.
composite_key_result is not guaranteed to be a model of
Default Constructible or
Assignable.
Every object of type composite_key_result<CompositeKey> is
internally associated to the CompositeKey from which it is returned
and the object of type CompositeKey::value_type to which the
composite key was applied.

Requires:length(x)==length(y). The expression
xi==yi is valid for all i
in [0,length(x)).
Returns:true if and only if

xi==yi for all i
in [0,length(x)).

Complexity: No more key extraction operations and comparisons
are performed than those necessary for the evaluation of the expression above,
starting at i==0. The evaluation is short-circuited as soon as
the result is determined to be false.

Requires: The expressions
xi<yi and
yi<xi are valid for all i
in [0,min(length(x),length(y))).
Returns:true if and only if there exists some
j in the range [0,min(length(x),length(y)))
such that

!(xi<yi) && !(yi<xi)
for all i in [0,j), xj<yj.

Complexity: No more key extraction operations and comparisons
are performed than those necessary for the evaluation of the expression above,
starting at i==0. The evaluation is short-circuited as soon as
the result is determined to be false.

Pred0, ... , Predn are the types of the equality
predicates stored by composite_key_equal_to. Each of these types
must be a Binary Predicate. At least an
equality predicate must be provided. The maximum number of equality predicates of
a composite_key_equal_to instantiation is implementation defined.
composite_key_equal_to is
Assignable.
It is also
Default Constructible
if each Predi is
Default Constructible.

Note that formally it is not required that the Predi types
behave as equality predicates in any definite way. However, the
semantics of composite_key_equal_to is well defined if this
is the case, as explained in the section on the
semantics of composite_key_result.

Notation

In what follows we use the same notation
introduced for composite_key_result.

Requires:length(x)==length(y). The expressions
key_eqs().get<i>()(xi,yi) and
key_eqs().get<i>()(yi,xi)
are valid for all i in [0,length(x)).
Returns:true if and only

key_eqs().get<i>()(xi,yi)
for all i in [0,length(x)).

Complexity: No more key extraction operations and comparisons
are performed than those necessary for the evaluation of the expression above,
starting at i==0. The evaluation is short-circuited as soon as
the result is determined to be false.

CompositeKeyResult must be an instantiation of
composite_key_result for some type
composite_key<KeyFromValue0,...,KeyFromValuen>.
composite_key_result_equal_to<CompositeKeyResult>::operator() is
then equivalent to
composite_key_equal_to<Pred0,...,Predn>::operator(), taking

Predi = std::equal_to<KeyFromValuei::result_type> for all
i = 0,...,n.

Compare0, ... , Comparen are the types of the comparison
predicates stored by composite_key_compare. Each of these types
must be a Binary Predicate. At least a
comparison predicate must be provided. The maximum number of comparison predicates of
a composite_key_compare instantiation is implementation defined.
composite_key_compare is
Assignable.
It is also
Default Constructible
if each Comparei is
Default Constructible.

Note that formally it is not required that the Comparei types
behave as comparison predicates in any definite way. However, the
semantics of composite_key_compare is well defined if this
is the case, as explained in the section on the
semantics of composite_key_result.

Notation

In what follows we use the same notation
introduced for composite_key_result.

Requires: The expressions
key_comps().get<i>()(xi,yi) and
key_comps().get<i>()(yi,xi)
are valid for all i
in [0,min(length(x),length(y))).
Returns:true if and only if there exists some
j in the range [0,min(length(x),length(y)))
such that

!key_comps().get<i>()(xi,yi) && !key_comps().get<i>()(yi,xi)
for all i in [0,j), key_comps().get<j>()(xj,yj).

Complexity: No more key extraction operations and comparisons
are performed than those necessary for the evaluation of the expression above,
starting at i==0. The evaluation is short-circuited as soon as
the result is determined to be false.

CompositeKeyResult must be an instantiation of
composite_key_result for some type
composite_key<KeyFromValue0,...,KeyFromValuen>.
composite_key_result_less<CompositeKeyResult>::operator() is
then equivalent to
composite_key_compare<Compare0,...,Comparen>::operator(), taking

CompositeKeyResult must be an instantiation of
composite_key_result for some type
composite_key<KeyFromValue0,...,KeyFromValuen>.
composite_key_result_greater<CompositeKeyResult>::operator() is
then equivalent to
composite_key_compare<Compare0,...,Comparen>::operator(), taking

Comparei = std::greater<KeyFromValuei::result_type> for all
i = 0,...,n.

Hash0, ... , Hashn are the types of the hash functors
stored by composite_key_hash. Each of these types
must be a
Unary Function
returning a value of type std::size_t in the range
[0, std::numeric_limits<std::size_t>::max()).
At least a
hash functor must be provided. The maximum number of hash functors of
a composite_key_hash instantiation is implementation defined.
composite_key_hash is
Assignable.
It is also
Default Constructible
if each Hashi is
Default Constructible.

Notation

In what follows we use the same notation
introduced for composite_key_result.

Requires:length(x)==length(key_hash_functions()).
The expression
key_hash_functions().get<i>()(xi)
is valid for all i in [0,length(x)).
Returns: A value in the range
[0, std::numeric_limits<std::size_t>::max()) that
solely depends on the numerical tuple

CompositeKeyResult must be an instantiation of
composite_key_result for some type
composite_key<KeyFromValue0,...,KeyFromValuen>.
composite_key_result_hash<CompositeKeyResult>::operator() is
then equivalent to
composite_key_hash<Hash0,...,Hashn>::operator(), taking

The design of equality, comparison and hash operations for
composite_key_result objects is based on the following rationale:
a composite_key_result is regarded as a "virtual" tuple, each
of its elements being the result of the corresponding elementary
key extractor. Accordingly, any given operation resolves to a
combination of the corresponding elementwise operations.
This mapping preserves the fundamental properties of the elementary operations
involved; for instance, it defines a true equivalence relation if the
basic predicates induce equivalence relations themselves.
We can state these facts in a formal way as follows.

Consider an instantiation of composite_key_equal_to
with types Pred0, ... , Predn such that each
Predi induces an equivalence relation on a certain type Ti,
and let CompositeKey be a type of the form
composite_key<Value,KeyFromValue0,...,KeyFromValuej>,
with j <= n, such that

KeyFromValuei::result_type = Ti, for all i = 0,...,j.

Then, composite_key_equal_to induces an equivalence relation
on elements of type composite_key_result<CompositeKey>;
such two objects are equivalent if all its elementary key extractor values
are also equivalent. Additionally, given an instantiation
composite_key_hash<Hash0,...,Hashj>, the following types are
Compatible Keys of
(composite_key_hash, composite_key_equal_to)
with respect to composite_key_result<CompositeKey>:

tuple<Q0,...,Qj>,composite_key_result<composite_key<K0,...,Kj> >, with
Ki::result_type = Qi for all i = 0,...,j.

provided that each Qi is either Ti or a
Compatible Key
of (Hashi, Predi).

As for comparison, consider an instantiation of composite_key_compare
with types Compare0, ... , Comparen such that each
Comparei is a
Strict
Weak Ordering on the type Ti. Then, for a
CompositeKey type defined in the same manner as above,
composite_key_compare is a
Strict
Weak Ordering on elements of type
composite_key_result<CompositeKey>, and the order induced
is lexicographical. Also, the following types are
Compatible Keys of
composite_key_compare with respect to
composite_key_result<CompositeKey>:

provided that each Qi is either Ti or a
Compatible Key
of Comparei. In this case, the comparison is done
lexicographically only on the first 1+min(j,k) elements.

Analogous properties hold for the equality and comparison operators
of composite_key_result. Note, however,
that equality is only defined for objects of the same length, whilst
comparison takes the minimum length of the operands considered.
Therefore, the equivalence classes induced by x==y are
subsets of those associated to !(x<y)&&!(y<x).