# Boost.MultiIndex Ranked indices reference

Ordered indices
Boost.MultiIndex reference
Hashed indices

## Contents

- Header `"boost/multi_index/ranked_index_fwd.hpp"` synopsis
- Header `"boost/multi_index/ranked_index.hpp"` synopsis
  - Index specifiers `ranked_unique` and `ranked_non_unique`
  - Ranked indices
    - Complexity signature
    - Instantiation types
    - Rank operations
    - Serialization

## Header `"boost/multi_index/ranked_index_fwd.hpp"` synopsis

>     namespace boost{

>     namespace multi_index{

>     // index specifiers ranked_unique and ranked_non_unique

>     template<consult ranked_unique reference for arguments>
>     struct ranked_unique;
>     template<consult ranked_non_unique reference for arguments>
>     struct ranked_non_unique;

>     // indices

>     namespace detail{

>     template<implementation defined> class index name is implementation defined;

>     } // namespace boost::multi_index::detail

>     } // namespace boost::multi_index

>     } // namespace boost

`ranked_index_fwd.hpp` provides forward declarations for index specifiers `ranked_unique` and `ranked_non_unique` and their associated ranked index classes.

## Header `"boost/multi_index/ranked_index.hpp"` synopsis

>     #include <initializer_list>

>     namespace boost{

>     namespace multi_index{

>     // index specifiers ranked_unique and ranked_non_unique

>     template<consult ranked_unique reference for arguments>
>     struct ranked_unique;
>     template<consult ranked_non_unique reference for arguments>
>     struct ranked_non_unique;

>     // indices

>     namespace detail{

>     template<implementation defined> class index class name implementation defined;

>     // index comparison:

>     // OP is any of ==,<,!=,>,>=,<=

>     template<arg set 1,arg set 2>
>     bool operator OP(
>       const index class name<arg set 1>& x,const index class name<arg set 2>& y);

>     // index specialized algorithms:

>     template<implementation defined>
>     void swap(index class name& x,index class name& y);

>     } // namespace boost::multi_index::detail

>     } // namespace boost::multi_index

>     } // namespace boost

### Index specifiers `ranked_unique` and `ranked_non_unique`

These index specifiers allow for insertion of ranked indices without and with allowance of duplicate elements, respectively. The syntax of `ranked_unique` and `ranked_non_unique` coincide, thus we describe them in a grouped manner. `ranked_unique` and `ranked_non_unique` can be instantiated in two different forms, according to whether a tag list for the index is provided or not:

>     template<
>       typename KeyFromValue,
>       typename Compare=std::less<KeyFromValue::result_type>
>     >
>     struct (ranked_unique | ranked_non_unique);

>     template<
>       typename TagList,
>       typename KeyFromValue,
>       typename Compare=std::less<KeyFromValue::result_type>
>     >
>     struct (ranked_unique | ranked_non_unique);

If provided, `TagList` must be an instantiation of the class template `tag`. The template arguments are used by the corresponding index implementation, refer to the ranked indices reference section for further explanations on their acceptable type values.

### Ranked indices

Ranked indices are a variation of ordered indices providing additional capabilities for calculation of and access by rank; the rank of an element is the distance to it from the beginning of the index. Besides this extension, ranked indices replicate the public interface of ordered indices with the difference, complexity-wise, that deletion is done in logarithmic rather than constant time. Also, execution times and memory consumption are expected to be poorer due to the internal bookkeeping needed to maintain rank-related information. As with ordered indices, ranked indices can be unique (no duplicate elements are allowed) or non-unique: either version is associated to a different index specifier, but the interface of both index types is the same.

In what follows, we only describe the extra operations provided by ranked indices: for the rest refer to the documentation for ordered indices, bearing in mind the occasional differences in complexity.

>     namespace boost{

>     namespace multi_index{

>     implementation defined unbounded; // see range_rank()

>     namespace detail{

>     template<implementation defined: dependent on types Value, Allocator,
>       TagList, KeyFromValue, Compare>
>     class name is implementation defined
>     {
>     public:
>       // types:

>       typedef typename KeyFromValue::result_type         key_type;
>       typedef Value                                      value_type;
>       typedef KeyFromValue                               key_from_value;
>       typedef Compare                                    key_compare;
>       typedef implementation defined                     value_compare;
>       typedef boost::tuple<key_from_value,key_compare>   ctor_args;
>       typedef TagList                                    tag_list;
>       typedef Allocator                                  allocator_type;
>       typedef typename Allocator::reference              reference;
>       typedef typename Allocator::const_reference        const_reference;
>       typedef implementation defined                     iterator;
>       typedef implementation defined                     const_iterator;
>       typedef implementation defined                     size_type;
>       typedef implementation defined                     difference_type;
>       typedef typename Allocator::pointer                pointer;
>       typedef typename Allocator::const_pointer          const_pointer;
>       typedef equivalent to
>         std::reverse_iterator<iterator>                  reverse_iterator;
>       typedef equivalent to
>         std::reverse_iterator<const_iterator>            const_reverse_iterator;

>       // construct/copy/destroy:

>       index class name& operator=(const index class name& x);
>       index class name& operator=(std::initializer_list<value_type> list);

>       allocator_type get_allocator()const noexcept;

>       // iterators:

>       iterator               begin()noexcept;
>       const_iterator         begin()const noexcept;
>       iterator               end()noexcept;
>       const_iterator         end()const noexcept;
>       reverse_iterator       rbegin()noexcept;
>       const_reverse_iterator rbegin()const noexcept;
>       reverse_iterator       rend()noexcept;
>       const_reverse_iterator rend()const noexcept;
>       const_iterator         cbegin()const noexcept;
>       const_iterator         cend()const noexcept;
>       const_reverse_iterator crbegin()const noexcept;
>       const_reverse_iterator crend()const noexcept;

>       iterator       iterator_to(const value_type& x);
>       const_iterator iterator_to(const value_type& x)const;

>       // capacity:

>       bool      empty()const noexcept;
>       size_type size()const noexcept;
>       size_type max_size()const noexcept;

>       // modifiers:

>       template<typename... Args>
>       std::pair<iterator,bool> emplace(Args&&... args);
>       template <typename... Args>
>       iterator emplace_hint(iterator position,Args&&... args);
>       std::pair<iterator,bool> insert(const value_type& x);
>       std::pair<iterator,bool> insert(value_type&& x);
>       iterator insert(iterator position,const value_type& x);
>       iterator insert(iterator position,value_type&& x);
>       template<typename InputIterator>
>       void insert(InputIterator first,InputIterator last);
>       void insert(std::initializer_list<value_type> list);

>       iterator  erase(iterator position);
>       size_type erase(const key_type& x);
>       iterator  erase(iterator first,iterator last);

>       bool replace(iterator position,const value_type& x);
>       bool replace(iterator position,value_type&& x);
>       template<typename Modifier> bool modify(iterator position,Modifier mod);
>       template<typename Modifier,typename Rollback>
>       bool modify(iterator position,Modifier mod,Rollback back);
>       template<typename Modifier> bool modify_key(iterator position,Modifier mod);
>       template<typename Modifier,typename Rollback>
>       bool modify_key(iterator position,Modifier mod,Rollback back);

>       void swap(index class name& x);
>       void clear()noexcept;

>       // observers:

>       key_from_value key_extractor()const;
>       key_compare    key_comp()const;
>       value_compare  value_comp()const;

>       // set operations:

>       template<typename CompatibleKey>
>       iterator find(const CompatibleKey& x)const;
>       template<typename CompatibleKey,typename CompatibleCompare>
>       iterator find(
>         const CompatibleKey& x,const CompatibleCompare& comp)const;

>       template<typename CompatibleKey>
>       size_type count(const CompatibleKey& x)const;
>       template<typename CompatibleKey,typename CompatibleCompare>
>       size_type count(const CompatibleKey& x,const CompatibleCompare& comp)const;

>       template<typename CompatibleKey>
>       iterator lower_bound(const CompatibleKey& x)const;
>       template<typename CompatibleKey,typename CompatibleCompare>
>       iterator lower_bound(
>         const CompatibleKey& x,const CompatibleCompare& comp)const;

>       template<typename CompatibleKey>
>       iterator upper_bound(const CompatibleKey& x)const;
>       template<typename CompatibleKey,typename CompatibleCompare>
>       iterator upper_bound(
>         const CompatibleKey& x,const CompatibleCompare& comp)const;

>       template<typename CompatibleKey>
>       std::pair<iterator,iterator> equal_range(
>         const CompatibleKey& x)const;
>       template<typename CompatibleKey,typename CompatibleCompare>
>       std::pair<iterator,iterator> equal_range(
>         const CompatibleKey& x,const CompatibleCompare& comp)const;

>       // range:

>       template<typename LowerBounder,typename UpperBounder>
>       std::pair<iterator,iterator> range(
>         LowerBounder lower,UpperBounder upper)const;

>       // rank operations:

>       iterator  nth(size_type n)const;
>       size_type rank(iterator position)const;

>       template<typename CompatibleKey>
>       size_type find_rank(const CompatibleKey& x)const;
>       template<typename CompatibleKey,typename CompatibleCompare>
>       size_type find_rank(
>         const CompatibleKey& x,const CompatibleCompare& comp)const;

>       template<typename CompatibleKey>
>       size_type lower_bound_rank(const CompatibleKey& x)const;
>       template<typename CompatibleKey,typename CompatibleCompare>
>       size_type lower_bound_rank(
>         const CompatibleKey& x,const CompatibleCompare& comp)const;

>       template<typename CompatibleKey>
>       size_type upper_bound_rank(const CompatibleKey& x)const;
>       template<typename CompatibleKey,typename CompatibleCompare>
>       size_type upper_bound_rank(
>         const CompatibleKey& x,const CompatibleCompare& comp)const;

>       template<typename CompatibleKey>
>       std::pair<size_type,size_type> equal_range_rank(
>         const CompatibleKey& x)const;
>       template<typename CompatibleKey,typename CompatibleCompare>
>       std::pair<size_type,size_type> equal_range_rank(
>         const CompatibleKey& x,const CompatibleCompare& comp)const;

>       template<typename LowerBounder,typename UpperBounder>
>       std::pair<size_type,size_type>
>       range_rank(LowerBounder lower,UpperBounder upper)const;
>     };

>     // index comparison:

>     template<arg set 1,arg set 2>
>     bool operator==(
>       const index class name<arg set 1>& x,
>       const index class name<arg set 2>& y)
>     {
>       return x.size()==y.size()&&std::equal(x.begin(),x.end(),y.begin());
>     }

>     template<arg set 1,arg set 2>
>     bool operator<(
>       const index class name<arg set 1>& x,
>       const index class name<arg set 2>& y)
>     {
>       return std::lexicographical_compare(x.begin(),x.end(),y.begin(),y.end());
>     }

>     template<arg set 1,arg set 2>
>     bool operator!=(
>       const index class name<arg set 1>& x,
>       const index class name<arg set 2>& y)
>     {
>       return !(x==y);
>     }

>     template<arg set 1,arg set 2>
>     bool operator>(
>       const index class name<arg set 1>& x,
>       const index class name<arg set 2>& y)
>     {
>       return y<x;
>     }

>     template<arg set 1,arg set 2>
>     bool operator>=(
>       const index class name<arg set 1>& x,
>       const index class name<arg set 2>& y)
>     {
>       return !(x<y);
>     }

>     template<arg set 1,arg set 2>
>     bool operator<=(
>       const index class name<arg set 1>& x,
>       const index class name<arg set 2>& y)
>     {
>       return !(x>y);
>     }

>     // index specialized algorithms:

>     template<implementation defined>
>     void swap(index class name& x,index class name& y);

>     } // namespace boost::multi_index::detail

>     } // namespace boost::multi_index

>     } // namespace boost

#### Complexity signature

We follow the terminology described in the complexity signature section. The complexity signature of ranked indices is:

- copying: `c(n)=n*log(n)`,
- insertion: `i(n)=log(n)`,
- hinted insertion: `h(n)=1` (constant) if the hint element is immediately after the point of insertion, `h(n)=log(n)` otherwise,
- deletion: `d(n)=log(n)` ,
- replacement: `r(n)=1` (constant) if the element position does not change, `r(n)=log(n)` otherwise,
- modifying: `m(n)=1` (constant) if the element position does not change, `m(n)=log(n)` otherwise.

These complexity guarantees are the same as those of ordered indices except for deletion, which is `log(n)` here and amortized constant there.

#### Instantiation types

Ordered indices are instantiated internally to `multi_index_container` and specified by means of `indexed_by` with index specifiers `ranked_unique` and `ranked_non_unique`. Instantiations are dependent on the following types:

- `Value` from `multi_index_container`,
- `Allocator` from `multi_index_container`,
- `TagList` from the index specifier (if provided, otherwise `tag<>` is assumed),
- `KeyFromValue` from the index specifier,
- `Compare` from the index specifier.

These types are subject to the same requirements as specified for ordered indices.

#### Rank operations

The rank of an iterator `it` of a given container `c` (and, by extension, of the element it points to if the iterator is dereferenceable) is `std::distance(c.begin(),it)`.

See the documentation of ordered indices for an explanation of the notions of compatible extension, compatible key, lower bounder and upper bounder, which are referred to below.

`iterator nth(size_type n)const;`

> Effects: Returns an iterator with rank `n`, or `end()` if `n>=size()`.
> Complexity: `O(log(n))`.

`size_type rank(iterator position)const;`

> Requires: `position` is a valid iterator of the index.
> Effects: Returns the rank of `position`.
> Complexity: `O(log(n))`.

`template<typename CompatibleKey> size_type find_rank(const CompatibleKey& x)const;`

> Requires: `CompatibleKey` is a compatible key of `key_compare`.
> Effects: Equivalent to `rank(find(k))`.
> Complexity: `O(log(n))`.

`template<typename CompatibleKey,typename CompatibleCompare>
size_type find_rank(const CompatibleKey& x,const CompatibleCompare& comp)const;`

> Requires: (`CompatibleKey`, `CompatibleCompare`) is a compatible extension of `key_compare`.
> Effects: Equivalent to `rank(find(x,comp))`.
> Complexity: `O(log(n))`.

`template<typename CompatibleKey>
size_type lower_bound_rank(const CompatibleKey& x)const;`

> Requires: `CompatibleKey` is a compatible key of `key_compare`.
> Effects: Equivalent to `rank(lower_bound(x))`.
> Complexity: `O(log(n))`.

`template<typename CompatibleKey,typename CompatibleCompare>
size_type lower_bound_rank(const CompatibleKey& x,const CompatibleCompare& comp)const;`

> Requires: (`CompatibleKey`, `CompatibleCompare`) is a compatible extension of `key_compare`.
> Effects: Equivalent to `rank(lower_bound(x,comp))`.
> Complexity: `O(log(n))`.

`template<typename CompatibleKey>
size_type upper_bound_rank(const CompatibleKey& x)const;`

> Requires: `CompatibleKey` is a compatible key of `key_compare`.
> Effects: Equivalent to `rank(upper_bound(x))`.
> Complexity: `O(log(n))`.

`template<typename CompatibleKey,typename CompatibleCompare>
size_type upper_bound_rank(const CompatibleKey& x,const CompatibleCompare& comp)const;`

> Requires: (`CompatibleKey`, `CompatibleCompare`) is a compatible extension of `key_compare`.
> Effects: Equivalent to `rank(upper_bound(x,comp))`.
> Complexity: `O(log(n))`.

`template<typename CompatibleKey>
std::pair<size_type,size_type> equal_range_rank(
const CompatibleKey& x)const;`

> Requires: `CompatibleKey` is a compatible key of `key_compare`.
> Effects: Equivalent to `make_pair(lower_bound_rank(x),upper_bound_rank(x))`.
> Complexity: `O(log(n))`.

`template<typename CompatibleKey,typename CompatibleCompare>
std::pair<size_type,size_type> equal_range_rank(
const CompatibleKey& x,const CompatibleCompare& comp)const;`

> Requires: (`CompatibleKey`, `CompatibleCompare`) is a compatible extension of `key_compare`.
> Effects: Equivalent to `make_pair(lower_bound_rank(x,comp),upper_bound_rank(x,comp))`.
> Complexity: `O(log(n))`.

`template<typename LowerBounder,typename UpperBounder>
std::pair<size_type,size_type> range_rank(
LowerBounder lower,UpperBounder upper)const;`

> Requires: `LowerBounder` and `UpperBounder` are a lower and upper bounder of `key_compare`, respectively.
> Effects: Equivalent to

> >     auto p=range(lower,upper);
> >     return make_pair(rank(p.first),rank(p.second));

> Complexity: `O(log(n))`.
> Variants: In place of `lower` or `upper` (or both), the singular value `boost::multi_index::unbounded` can be provided. This acts as a predicate which all values of type `key_type` satisfy.

#### Serialization

The prerequisites and postconditions associated to serialization of `multi_index_container`s with ranked indices are exactly the same as those of ordered indices.

Ordered indices
Boost.MultiIndex reference
Hashed indices

Revised May 4th 2015

© Copyright 2003-2015 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)