mirror of
https://github.com/boostorg/multi_index.git
synced 2025-05-09 23:14:04 +00:00
910 lines
59 KiB
HTML
910 lines
59 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0.1 Transitional//EN">
|
|
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>Boost.MultiIndex Documentation - Ordered indices reference</title>
|
|
<link rel="stylesheet" href="../style.css" type="text/css">
|
|
</head>
|
|
|
|
<body>
|
|
<h1><img src="../../../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align=
|
|
"middle" width="277" height="86">Boost.MultiIndex Ordered indices reference</h1>
|
|
|
|
<div class="prev_link"><a href="indices.html"><img src="../prev.gif" alt="index reference" border="0"><br>
|
|
Index reference
|
|
</a></div>
|
|
<div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.MultiIndex reference" border="0"><br>
|
|
Boost.MultiIndex reference
|
|
</a></div>
|
|
<div class="next_link"><a href="seq_indices.html"><img src="../next.gif" alt="sequenced indices" border="0"><br>
|
|
Sequenced indices
|
|
</a></div><br clear="all" style="clear: all;">
|
|
|
|
<hr>
|
|
|
|
<h2>Contents</h2>
|
|
|
|
<ul>
|
|
<li><a href="#ord_index_fwd_synopsis">Header
|
|
<code>"boost/multi_index/ordered_index_fwd.hpp"</code> synopsis</a></li>
|
|
<li><a href="#synopsis">Header
|
|
<code>"boost/multi_index/ordered_index.hpp"</code> synopsis</a>
|
|
<ul>
|
|
<li><a href="#unique_non_unique">
|
|
Index specifiers <code>ordered_unique</code> and <code>ordered_non_unique</code>
|
|
</a></li>
|
|
<li><a href="#ord_indices">Ordered indices</a>
|
|
<ul>
|
|
<li><a href="#complexity_signature">Complexity signature</a></li>
|
|
<li><a href="#instantiation_types">Instantiation types</a></li>
|
|
<li><a href="#constructors">Constructors, copy and assignment</a></li>
|
|
<li><a href="#modifiers">Modifiers</a></li>
|
|
<li><a href="#observers">Observers</a></li>
|
|
<li><a href="#set_operations">Set operations</a></li>
|
|
<li><a href="#range_operations">Range operations</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h2>
|
|
<a name="ord_index_fwd_synopsis">Header
|
|
<a href="../../../../boost/multi_index/ordered_index_fwd.hpp">
|
|
<code>"boost/multi_index/ordered_index_fwd.hpp"</code></a> synopsis</a></h2>
|
|
|
|
<blockquote><pre>
|
|
<span class=keyword>namespace</span> <span class=identifier>boost</span><span class=special>{</span>
|
|
|
|
<span class=keyword>namespace</span> <span class=identifier>multi_index</span><span class=special>{</span>
|
|
|
|
<span class=comment>// index specifiers unique and ordered_non_unique</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><b>consult ordered_unique reference for arguments</b><span class=special>></span>
|
|
<span class=keyword>struct</span> <span class=identifier>ordered_unique</span><span class=special>;</span>
|
|
<span class=keyword>template</span><span class=special><</span><b>consult ordered_non_unique reference for arguments</b><span class=special>></span>
|
|
<span class=keyword>struct</span> <span class=identifier>ordered_non_unique</span><span class=special>;</span>
|
|
|
|
<span class=comment>// indices</span>
|
|
|
|
<span class=keyword>namespace</span> <span class=identifier>detail</span><span class=special>{</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><b>implementation defined</b><span class=special>></span> <span class=keyword>class</span> <b>index name is implementation defined</b><span class=special>;</span>
|
|
|
|
<span class=special>}</span> <span class=comment>// namespace boost::multi_index::detail</span>
|
|
|
|
<span class=special>}</span> <span class=comment>// namespace boost::multi_index</span>
|
|
|
|
<span class=special>}</span> <span class=comment>// namespace boost</span>
|
|
</pre></blockquote>
|
|
|
|
<p>
|
|
<code>index_fwd.hpp</code> provides forward declarations for index specifiers
|
|
<a href="#unique_non_unique"><code>ordered_unique</code> and <code>ordered_non_unique</code></a> and
|
|
their associated <a href="#ord_indices">ordered index</a> classes.
|
|
</p>
|
|
|
|
<h2>
|
|
<a name="synopsis">Header
|
|
<a href="../../../../boost/multi_index/ordered_index.hpp">
|
|
<code>"boost/multi_index/ordered_index.hpp"</code></a> synopsis</a></h2>
|
|
|
|
<blockquote><pre>
|
|
<span class=keyword>namespace</span> <span class=identifier>boost</span><span class=special>{</span>
|
|
|
|
<span class=keyword>namespace</span> <span class=identifier>multi_index</span><span class=special>{</span>
|
|
|
|
<span class=comment>// index specifiers unique and ordered_non_unique</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><b>consult ordered_unique reference for arguments</b><span class=special>></span>
|
|
<span class=keyword>struct</span> <span class=identifier>ordered_unique</span><span class=special>;</span>
|
|
<span class=keyword>template</span><span class=special><</span><b>consult ordered_non_unique reference for arguments</b><span class=special>></span>
|
|
<span class=keyword>struct</span> <span class=identifier>ordered_non_unique</span><span class=special>;</span>
|
|
|
|
<span class=comment>// indices</span>
|
|
|
|
<span class=keyword>namespace</span> <span class=identifier>detail</span><span class=special>{</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><b>implementation defined</b><span class=special>></span> <span class=keyword>class</span> <b>index class name implementation defined</b><span class=special>;</span>
|
|
|
|
<span class=comment>// index comparison:</span>
|
|
|
|
<span class=comment>// <b>OP</b> is any of ==,<,!=,>,>=,<=</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><b>arg set 1</b><span class=special>,</span><b>arg set 2</b><span class=special>></span>
|
|
<span class=keyword>bool</span> <span class=keyword>operator</span> <b><i>OP</i></b><span class=special>(</span>
|
|
<span class=keyword>const</span> <b>index class name</b><span class=special><</span><b>arg set 1</b><span class=special>>&</span> <span class=identifier>x</span><span class=special>,</span><span class=keyword>const</span> <b>index class name</b><span class=special><</span><b>arg set 2</b><span class=special>>&</span> <span class=identifier>y</span><span class=special>);</span>
|
|
|
|
<span class=comment>// index specialized algorithms:</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><b>implementation defined</b><span class=special>></span>
|
|
<span class=keyword>void</span> <span class=identifier>swap</span><span class=special>(</span><b>index class name</b><span class=special>&</span> <span class=identifier>x</span><span class=special>,</span><b>index class name</b><span class=special>&</span> <span class=identifier>y</span><span class=special>);</span>
|
|
|
|
<span class=special>}</span> <span class=comment>// namespace boost::multi_index::detail</span>
|
|
|
|
<span class=special>}</span> <span class=comment>// namespace boost::multi_index</span>
|
|
|
|
<span class=special>}</span> <span class=comment>// namespace boost</span>
|
|
</pre></blockquote>
|
|
|
|
<h3><a name="unique_non_unique">
|
|
Index specifiers <code>ordered_unique</code> and <code>ordered_non_unique</code>
|
|
</a></h3>
|
|
|
|
<p>
|
|
These <a href="indices.html#index_specification">index specifiers</a> allow
|
|
for insertion of <a href="#ord_indices">ordered indices</a> without and with
|
|
allowance of duplicate elements, respectively. The syntax of <code>ordered_unique</code>
|
|
and <code>ordered_non_unique</code> coincide, thus we describe them in a grouped manner.
|
|
<code>ordered_unique</code> and <code>ordered_non_unique</code> can be instantiated in
|
|
two different forms, according to whether a tag list for the index is provided or not:
|
|
</p>
|
|
|
|
<blockquote><pre>
|
|
<span class=keyword>template</span><span class=special><</span>
|
|
<span class=keyword>typename</span> <span class=identifier>KeyFromValue</span><span class=special>,</span>
|
|
<span class=keyword>typename</span> <span class=identifier>Compare</span><span class=special>=</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>less</span><span class=special><</span><span class=identifier>KeyFromValue</span><span class=special>::</span><span class=identifier>result_type</span>
|
|
<span class=special>></span>
|
|
<span class=keyword>struct</span> <span class=special>(</span><span class=identifier>ordered_unique</span> <span class=special>|</span> <span class=identifier>ordered_non_unique</span><span class=special>)</span><span class=special>;</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span>
|
|
<span class=keyword>typename</span> <span class=identifier>TagList</span><span class=special>,</span>
|
|
<span class=keyword>typename</span> <span class=identifier>KeyFromValue</span><span class=special>,</span>
|
|
<span class=keyword>typename</span> <span class=identifier>Compare</span><span class=special>=</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>less</span><span class=special><</span><span class=identifier>KeyFromValue</span><span class=special>::</span><span class=identifier>result_type</span><span class=special>></span>
|
|
<span class=special>></span>
|
|
<span class=keyword>struct</span> <span class=special>(</span><span class=identifier>ordered_unique</span> <span class=special>|</span> <span class=identifier>ordered_non_unique</span><span class=special>)</span><span class=special>;</span>
|
|
</pre></blockquote>
|
|
|
|
<p>
|
|
If provided, <code>TagList</code> must be an instantiation of the class template
|
|
<a href="#tag"><code>tag</code></a>.
|
|
The template arguments are used by the corresponding index implementation,
|
|
refer to the <a href="#ord_indices">ordered indices</a> reference section for further
|
|
explanations on their acceptable type values.
|
|
</p>
|
|
|
|
<h3><a name="ord_indices">Ordered indices</a></h3>
|
|
|
|
<p>
|
|
An ordered index provides a set-like interface to the underlying heap of
|
|
elements contained in a <code>multi_index_container</code>. An ordered index is
|
|
particularized according to a given
|
|
<a href="key_extraction.html#key_extractors"><code>Key Extractor</code></a>
|
|
that retrieves keys from elements of <code>multi_index_container</code> and a comparison
|
|
predicate.
|
|
</p>
|
|
|
|
<p>
|
|
There are two variants of ordered indices: <i>unique</i>, which do
|
|
not allow duplicate elements (with respect to its associated comparison
|
|
predicate) and <i>non-unique</i>, which accept those duplicates.
|
|
The interface of these two variants is the same, so they are documented
|
|
together, with minor differences explicitly stated when they exist.
|
|
</p>
|
|
|
|
<p>
|
|
Except where noted, ordered indices (both unique and non-unique) are models of
|
|
<a href="http://www.sgi.com/tech/stl/SortedAssociativeContainer.html">
|
|
<code>Sorted Associative Container</code></a> and
|
|
<a href="http://www.sgi.com/tech/stl/UniqueAssociativeContainer.html">
|
|
<code>Unique Associative Container</code></a>, much as <code>std::set</code>s
|
|
are. Accordingly, validity of iterators and references to elements is
|
|
preserved. We only provide descriptions of those types and operations that are
|
|
either not present in the concepts modeled or do not exactly conform to the
|
|
requirements for these types of containers.
|
|
</p>
|
|
|
|
<blockquote><pre>
|
|
<span class=keyword>namespace</span> <span class=identifier>boost</span><span class=special>{</span>
|
|
|
|
<span class=keyword>namespace</span> <span class=identifier>multi_index</span><span class=special>{</span>
|
|
|
|
<span class=keyword>namespace</span><span class=special>{</span> <b>implementation defined </b><span class=identifier>unbounded</span><span class=special>;</span> <span class=special>}</span> <span class=comment>// see range()</span>
|
|
|
|
<span class=keyword>namespace</span> <span class=identifier>detail</span><span class=special>{</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><b>implementation defined: dependent on types Value, Allocator,
|
|
TagList, KeyFromValue, Compare</b><span class=special>></span>
|
|
<span class=keyword>class</span> <b>name is implementation defined</b>
|
|
<span class=special>{</span>
|
|
<span class=keyword>public</span><span class=special>:</span>
|
|
<span class=comment>// types:</span>
|
|
|
|
<span class=keyword>typedef</span> <span class=keyword>typename</span> <span class=identifier>KeyFromValue</span><span class=special>::</span><span class=identifier>result_type</span> <span class=identifier>key_type</span><span class=special>;</span>
|
|
<span class=keyword>typedef</span> <span class=identifier>Value</span> <span class=identifier>value_type</span><span class=special>;</span>
|
|
<span class=keyword>typedef</span> <span class=identifier>KeyFromValue</span> <span class=identifier>key_from_value</span><span class=special>;</span>
|
|
<span class=keyword>typedef</span> <span class=identifier>Compare</span> <span class=identifier>key_compare</span><span class=special>;</span>
|
|
<span class=keyword>typedef</span> <b>implementation defined </b><span class=identifier>value_compare</span><span class=special>;</span>
|
|
<span class=keyword>typedef</span> <span class=identifier>tuple</span><span class=special><</span><span class=identifier>key_from_value</span><span class=special>,</span><span class=identifier>key_compare</span><span class=special>></span> <span class=identifier>ctor_args</span><span class=special>;</span>
|
|
<span class=keyword>typedef</span> <span class=identifier>Allocator</span> <span class=identifier>allocator_type</span><span class=special>;</span>
|
|
<span class=keyword>typedef</span> <span class=keyword>typename</span> <span class=identifier>Allocator</span><span class=special>::</span><span class=identifier>reference</span> <span class=identifier>reference</span><span class=special>;</span>
|
|
<span class=keyword>typedef</span> <span class=keyword>typename</span> <span class=identifier>Allocator</span><span class=special>::</span><span class=identifier>const_reference</span> <span class=identifier>const_reference</span><span class=special>;</span>
|
|
<span class=keyword>typedef</span> <b>implementation defined </b><span class=identifier>iterator</span><span class=special>;</span>
|
|
<span class=keyword>typedef</span> <b>implementation defined </b><span class=identifier>const_iterator</span><span class=special>;</span>
|
|
<span class=keyword>typedef</span> <b>implementation defined </b><span class=identifier>size_type</span><span class=special>;</span>
|
|
<span class=keyword>typedef</span> <b>implementation defined </b><span class=identifier>difference_type</span><span class=special>;</span>
|
|
<span class=keyword>typedef</span> <span class=keyword>typename</span> <span class=identifier>Allocator</span><span class=special>::</span><span class=identifier>pointer</span> <span class=identifier>pointer</span><span class=special>;</span>
|
|
<span class=keyword>typedef</span> <span class=keyword>typename</span> <span class=identifier>Allocator</span><span class=special>::</span><span class=identifier>const_pointer</span> <span class=identifier>const_pointer</span><span class=special>;</span>
|
|
<span class=keyword>typedef</span> <b>equivalent to
|
|
std::reverse_iterator<iterator></b> <span class=identifier>reverse_iterator</span><span class=special>;</span>
|
|
<span class=keyword>typedef</span> <b>equivalent to
|
|
std::reverse_iterator<const_iterator></b> <span class=identifier>const_reverse_iterator</span><span class=special>;</span>
|
|
|
|
<span class=comment>// construct/copy/destroy:</span>
|
|
|
|
<b>index class name</b><span class=special>&</span> <span class=keyword>operator</span><span class=special>=(</span><span class=keyword>const</span> <b>index class name</b><span class=special>&</span> <span class=identifier>x</span><span class=special>);</span>
|
|
|
|
<span class=identifier>allocator_type</span> <span class=identifier>get_allocator</span><span class=special>()</span><span class=keyword>const</span><span class=special>;</span>
|
|
|
|
<span class=comment>// iterators:</span>
|
|
|
|
<span class=identifier>iterator</span> <span class=identifier>begin</span><span class=special>();</span>
|
|
<span class=identifier>const_iterator</span> <span class=identifier>begin</span><span class=special>()</span><span class=keyword>const</span><span class=special>;</span>
|
|
<span class=identifier>iterator</span> <span class=identifier>end</span><span class=special>();</span>
|
|
<span class=identifier>const_iterator</span> <span class=identifier>end</span><span class=special>()</span><span class=keyword>const</span><span class=special>;</span>
|
|
<span class=identifier>reverse_iterator</span> <span class=identifier>rbegin</span><span class=special>();</span>
|
|
<span class=identifier>const_reverse_iterator</span> <span class=identifier>rbegin</span><span class=special>()</span><span class=keyword>const</span><span class=special>;</span>
|
|
<span class=identifier>reverse_iterator</span> <span class=identifier>rend</span><span class=special>();</span>
|
|
<span class=identifier>const_reverse_iterator</span> <span class=identifier>rend</span><span class=special>()</span><span class=keyword>const</span><span class=special>;</span>
|
|
|
|
<span class=comment>// capacity:</span>
|
|
|
|
<span class=keyword>bool</span> <span class=identifier>empty</span><span class=special>()</span><span class=keyword>const</span><span class=special>;</span>
|
|
<span class=identifier>size_type</span> <span class=identifier>size</span><span class=special>()</span><span class=keyword>const</span><span class=special>;</span>
|
|
<span class=identifier>size_type</span> <span class=identifier>max_size</span><span class=special>()</span><span class=keyword>const</span><span class=special>;</span>
|
|
|
|
<span class=comment>// modifiers:</span>
|
|
|
|
<span class=identifier>std</span><span class=special>::</span><span class=identifier>pair</span><span class=special><</span><span class=identifier>iterator</span><span class=special>,</span><span class=keyword>bool</span><span class=special>></span> <span class=identifier>insert</span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>value_type</span><span class=special>&</span> <span class=identifier>x</span><span class=special>);</span>
|
|
<span class=identifier>iterator</span> <span class=identifier>insert</span><span class=special>(</span><span class=identifier>iterator</span> <span class=identifier>position</span><span class=special>,</span><span class=keyword>const</span> <span class=identifier>value_type</span><span class=special>&</span> <span class=identifier>x</span><span class=special>);</span>
|
|
<span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>InputIterator</span><span class=special>></span>
|
|
<span class=keyword>void</span> <span class=identifier>insert</span><span class=special>(</span><span class=identifier>InputIterator</span> <span class=identifier>first</span><span class=special>,</span><span class=identifier>InputIterator</span> <span class=identifier>last</span><span class=special>);</span>
|
|
|
|
<span class=keyword>void</span> <span class=identifier>erase</span><span class=special>(</span><span class=identifier>iterator</span> <span class=identifier>position</span><span class=special>);</span>
|
|
<span class=identifier>size_type</span> <span class=identifier>erase</span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>key_type</span><span class=special>&</span> <span class=identifier>x</span><span class=special>);</span>
|
|
<span class=keyword>void</span> <span class=identifier>erase</span><span class=special>(</span><span class=identifier>iterator</span> <span class=identifier>first</span><span class=special>,</span><span class=identifier>iterator</span> <span class=identifier>last</span><span class=special>);</span>
|
|
|
|
<span class=keyword>bool</span> <span class=identifier>replace</span><span class=special>(</span><span class=identifier>iterator</span> <span class=identifier>position</span><span class=special>,</span><span class=keyword>const</span> <span class=identifier>value_type</span><span class=special>&</span> <span class=identifier>x</span><span class=special>);</span>
|
|
<span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>Modifier</span><span class=special>></span> <span class=keyword>bool</span> <span class=identifier>modify</span><span class=special>(</span><span class=identifier>iterator</span> <span class=identifier>position</span><span class=special>,</span><span class=identifier>Modifier</span> <span class=identifier>mod</span><span class=special>);</span>
|
|
<span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>Modifier</span><span class=special>></span> <span class=keyword>bool</span> <span class=identifier>modify_key</span><span class=special>(</span><span class=identifier>iterator</span> <span class=identifier>position</span><span class=special>,</span><span class=identifier>Modifier</span> <span class=identifier>mod</span><span class=special>);</span>
|
|
|
|
<span class=keyword>void</span> <span class=identifier>swap</span><span class=special>(</span><b>index class name</b><span class=special>&</span> <span class=identifier>x</span><span class=special>);</span>
|
|
<span class=keyword>void</span> <span class=identifier>clear</span><span class=special>();</span>
|
|
|
|
<span class=comment>// observers:</span>
|
|
|
|
<span class=identifier>key_from_value</span> <span class=identifier>key_extractor</span><span class=special>()</span><span class=keyword>const</span><span class=special>;</span>
|
|
<span class=identifier>key_compare</span> <span class=identifier>key_comp</span><span class=special>()</span><span class=keyword>const</span><span class=special>;</span>
|
|
<span class=identifier>value_compare</span> <span class=identifier>value_comp</span><span class=special>()</span><span class=keyword>const</span><span class=special>;</span>
|
|
|
|
<span class=comment>// set operations:</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>CompatibleKey</span><span class=special>></span>
|
|
<span class=identifier>const_iterator</span> <span class=identifier>find</span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>CompatibleKey</span><span class=special>&</span> <span class=identifier>x</span><span class=special>)</span><span class=keyword>const</span><span class=special>;</span>
|
|
<span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>CompatibleKey</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>CompatibleCompare</span><span class=special>></span>
|
|
<span class=identifier>const_iterator</span> <span class=identifier>find</span><span class=special>(</span>
|
|
<span class=keyword>const</span> <span class=identifier>CompatibleKey</span><span class=special>&</span> <span class=identifier>x</span><span class=special>,</span><span class=keyword>const</span> <span class=identifier>CompatibleCompare</span><span class=special>&</span> <span class=identifier>comp</span><span class=special>)</span><span class=keyword>const</span><span class=special>;</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>CompatibleKey</span><span class=special>></span>
|
|
<span class=identifier>size_type</span> <span class=identifier>count</span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>CompatibleKey</span><span class=special>&</span> <span class=identifier>x</span><span class=special>)</span><span class=keyword>const</span><span class=special>;</span>
|
|
<span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>CompatibleKey</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>CompatibleCompare</span><span class=special>></span>
|
|
<span class=identifier>size_type</span> <span class=identifier>count</span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>CompatibleKey</span><span class=special>&</span> <span class=identifier>x</span><span class=special>,</span><span class=keyword>const</span> <span class=identifier>CompatibleCompare</span><span class=special>&</span> <span class=identifier>comp</span><span class=special>)</span><span class=keyword>const</span><span class=special>;</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>CompatibleKey</span><span class=special>></span>
|
|
<span class=identifier>const_iterator</span> <span class=identifier>lower_bound</span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>CompatibleKey</span><span class=special>&</span> <span class=identifier>x</span><span class=special>)</span><span class=keyword>const</span><span class=special>;</span>
|
|
<span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>CompatibleKey</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>CompatibleCompare</span><span class=special>></span>
|
|
<span class=identifier>const_iterator</span> <span class=identifier>lower_bound</span><span class=special>(</span>
|
|
<span class=keyword>const</span> <span class=identifier>CompatibleKey</span><span class=special>&</span> <span class=identifier>x</span><span class=special>,</span><span class=keyword>const</span> <span class=identifier>CompatibleCompare</span><span class=special>&</span> <span class=identifier>comp</span><span class=special>)</span><span class=keyword>const</span><span class=special>;</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>CompatibleKey</span><span class=special>></span>
|
|
<span class=identifier>const_iterator</span> <span class=identifier>upper_bound</span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>CompatibleKey</span><span class=special>&</span> <span class=identifier>x</span><span class=special>)</span><span class=keyword>const</span><span class=special>;</span>
|
|
<span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>CompatibleKey</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>CompatibleCompare</span><span class=special>></span>
|
|
<span class=identifier>const_iterator</span> <span class=identifier>upper_bound</span><span class=special>(</span>
|
|
<span class=keyword>const</span> <span class=identifier>CompatibleKey</span><span class=special>&</span> <span class=identifier>x</span><span class=special>,</span><span class=keyword>const</span> <span class=identifier>CompatibleCompare</span><span class=special>&</span> <span class=identifier>comp</span><span class=special>)</span><span class=keyword>const</span><span class=special>;</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>CompatibleKey</span><span class=special>></span>
|
|
<span class=identifier>std</span><span class=special>::</span><span class=identifier>pair</span><span class=special><</span><span class=identifier>const_iterator</span><span class=special>,</span><span class=identifier>const_iterator</span><span class=special>></span> <span class=identifier>equal_range</span><span class=special>(</span>
|
|
<span class=keyword>const</span> <span class=identifier>CompatibleKey</span><span class=special>&</span> <span class=identifier>x</span><span class=special>)</span><span class=keyword>const</span><span class=special>;</span>
|
|
<span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>CompatibleKey</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>CompatibleCompare</span><span class=special>></span>
|
|
<span class=identifier>std</span><span class=special>::</span><span class=identifier>pair</span><span class=special><</span><span class=identifier>const_iterator</span><span class=special>,</span><span class=identifier>const_iterator</span><span class=special>></span> <span class=identifier>equal_range</span><span class=special>(</span>
|
|
<span class=keyword>const</span> <span class=identifier>CompatibleKey</span><span class=special>&</span> <span class=identifier>x</span><span class=special>,</span><span class=keyword>const</span> <span class=identifier>CompatibleCompare</span><span class=special>&</span> <span class=identifier>comp</span><span class=special>)</span><span class=keyword>const</span><span class=special>;</span>
|
|
|
|
<span class=comment>// range:</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>LowerBounder</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>UpperBounder</span><span class=special>></span>
|
|
<span class=identifier>std</span><span class=special>::</span><span class=identifier>pair</span><span class=special><</span><span class=identifier>const_iterator</span><span class=special>,</span><span class=identifier>const_iterator</span><span class=special>></span> <span class=identifier>range</span><span class=special>(</span>
|
|
<span class=identifier>LowerBounder</span> <span class=identifier>lower</span><span class=special>,</span><span class=identifier>UpperBounder</span> <span class=identifier>upper</span><span class=special>)</span><span class=keyword>const</span><span class=special>;</span>
|
|
<span class=special>};</span>
|
|
|
|
<span class=comment>// index comparison:</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><b>arg set 1</b><span class=special>,</span><b>arg set 2</b><span class=special>></span>
|
|
<span class=keyword>bool</span> <span class=keyword>operator</span><span class=special>==(</span>
|
|
<span class=keyword>const</span> <b>index class name</b><span class=special><</span><b>arg set 1</b><span class=special>>&</span> <span class=identifier>x</span><span class=special>,</span>
|
|
<span class=keyword>const</span> <b>index class name</b><span class=special><</span><b>arg set 2</b><span class=special>>&</span> <span class=identifier>y</span><span class=special>)</span>
|
|
<span class=special>{</span>
|
|
<span class=keyword>return</span> <span class=identifier>x</span><span class=special>.</span><span class=identifier>size</span><span class=special>()==</span><span class=identifier>y</span><span class=special>.</span><span class=identifier>size</span><span class=special>()&&</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>equal</span><span class=special>(</span><span class=identifier>x</span><span class=special>.</span><span class=identifier>begin</span><span class=special>(),</span><span class=identifier>x</span><span class=special>.</span><span class=identifier>end</span><span class=special>(),</span><span class=identifier>y</span><span class=special>.</span><span class=identifier>begin</span><span class=special>());</span>
|
|
<span class=special>}</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><b>arg set 1</b><span class=special>,</span><b>arg set 2</b><span class=special>></span>
|
|
<span class=keyword>bool</span> <span class=keyword>operator</span><span class=special><(</span>
|
|
<span class=keyword>const</span> <b>index class name</b><span class=special><</span><b>arg set 1</b><span class=special>>&</span> <span class=identifier>x</span><span class=special>,</span>
|
|
<span class=keyword>const</span> <b>index class name</b><span class=special><</span><b>arg set 2</b><span class=special>>&</span> <span class=identifier>y</span><span class=special>)</span>
|
|
<span class=special>{</span>
|
|
<span class=keyword>return</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>lexicographical_compare</span><span class=special>(</span><span class=identifier>x</span><span class=special>.</span><span class=identifier>begin</span><span class=special>(),</span><span class=identifier>x</span><span class=special>.</span><span class=identifier>end</span><span class=special>(),</span><span class=identifier>y</span><span class=special>.</span><span class=identifier>begin</span><span class=special>(),</span><span class=identifier>y</span><span class=special>.</span><span class=identifier>end</span><span class=special>());</span>
|
|
<span class=special>}</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><b>arg set 1</b><span class=special>,</span><b>arg set 2</b><span class=special>></span>
|
|
<span class=keyword>bool</span> <span class=keyword>operator</span><span class=special>!=(</span>
|
|
<span class=keyword>const</span> <b>index class name</b><span class=special><</span><b>arg set 1</b><span class=special>>&</span> <span class=identifier>x</span><span class=special>,</span>
|
|
<span class=keyword>const</span> <b>index class name</b><span class=special><</span><b>arg set 2</b><span class=special>>&</span> <span class=identifier>y</span><span class=special>)</span>
|
|
<span class=special>{</span>
|
|
<span class=keyword>return</span> <span class=special>!(</span><span class=identifier>x</span><span class=special>==</span><span class=identifier>y</span><span class=special>);</span>
|
|
<span class=special>}</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><b>arg set 1</b><span class=special>,</span><b>arg set 2</b><span class=special>></span>
|
|
<span class=keyword>bool</span> <span class=keyword>operator</span><span class=special>>(</span>
|
|
<span class=keyword>const</span> <b>index class name</b><span class=special><</span><b>arg set 1</b><span class=special>>&</span> <span class=identifier>x</span><span class=special>,</span>
|
|
<span class=keyword>const</span> <b>index class name</b><span class=special><</span><b>arg set 2</b><span class=special>>&</span> <span class=identifier>y</span><span class=special>)</span>
|
|
<span class=special>{</span>
|
|
<span class=keyword>return</span> <span class=identifier>y</span><span class=special><</span><span class=identifier>x</span><span class=special>;</span>
|
|
<span class=special>}</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><b>arg set 1</b><span class=special>,</span><b>arg set 2</b><span class=special>></span>
|
|
<span class=keyword>bool</span> <span class=keyword>operator</span><span class=special>>=(</span>
|
|
<span class=keyword>const</span> <b>index class name</b><span class=special><</span><b>arg set 1</b><span class=special>>&</span> <span class=identifier>x</span><span class=special>,</span>
|
|
<span class=keyword>const</span> <b>index class name</b><span class=special><</span><b>arg set 2</b><span class=special>>&</span> <span class=identifier>y</span><span class=special>)</span>
|
|
<span class=special>{</span>
|
|
<span class=keyword>return</span> <span class=special>!(</span><span class=identifier>x</span><span class=special><</span><span class=identifier>y</span><span class=special>);</span>
|
|
<span class=special>}</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><b>arg set 1</b><span class=special>,</span><b>arg set 2</b><span class=special>></span>
|
|
<span class=keyword>bool</span> <span class=keyword>operator</span><span class=special><=(</span>
|
|
<span class=keyword>const</span> <b>index class name</b><span class=special><</span><b>arg set 1</b><span class=special>>&</span> <span class=identifier>x</span><span class=special>,</span>
|
|
<span class=keyword>const</span> <b>index class name</b><span class=special><</span><b>arg set 2</b><span class=special>>&</span> <span class=identifier>y</span><span class=special>)</span>
|
|
<span class=special>{</span>
|
|
<span class=keyword>return</span> <span class=special>!(</span><span class=identifier>x</span><span class=special>></span><span class=identifier>y</span><span class=special>);</span>
|
|
<span class=special>}</span>
|
|
|
|
<span class=comment>// index specialized algorithms:</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span><b>implementation defined</b><span class=special>></span>
|
|
<span class=keyword>void</span> <span class=identifier>swap</span><span class=special>(</span><b>index class name</b><span class=special>&</span> <span class=identifier>x</span><span class=special>,</span><b>index class name</b><span class=special>&</span> <span class=identifier>y</span><span class=special>);</span>
|
|
|
|
<span class=special>}</span> <span class=comment>// namespace boost::multi_index::detail</span>
|
|
|
|
<span class=special>}</span> <span class=comment>// namespace boost::multi_index</span>
|
|
|
|
<span class=special>}</span> <span class=comment>// namespace boost</span>
|
|
</pre></blockquote>
|
|
|
|
<h4><a name="complexity_signature">Complexity signature</a></h4>
|
|
|
|
<p>
|
|
Here and in the descriptions of operations of ordered indices, we adopt the
|
|
scheme outlined in the
|
|
<a href="indices.html#complexity_signature">complexity signature
|
|
section</a>. The complexity signature of ordered indices is:
|
|
<ul>
|
|
<li>copying: <code>c(n)=n*log(n)</code>,</li>
|
|
<li>insertion: <code>i(n)=log(n)</code>,</li>
|
|
<li>hinted insertion: <code>h(n)=1</code> (constant) if the hint element
|
|
precedes the point of insertion, <code>h(n)=log(n)</code> otherwise,</li>
|
|
<li>deletion: <code>d(n)=1</code> (constant),</li>
|
|
<li>replacement: <code>r(n)=1</code> (constant) if the element position does not
|
|
change, <code>r(n)=log(n)</code> otherwise,</li>
|
|
<li>modifying: <code>m(n)=1</code> (constant) if the element position does not
|
|
change, <code>m(n)=log(n)</code> otherwise.</li>
|
|
</ul>
|
|
</p>
|
|
|
|
<h4><a name="instantiation_types">Instantiation types</a></h4>
|
|
|
|
<p>Ordered indices are instantiated internally to <code>multi_index_container</code> and
|
|
specified by means of <a href="indices.html#indexed_by"><code>indexed_by</code></a>
|
|
with <a href="#unique_non_unique"> index specifiers <code>ordered_unique</code>
|
|
and <code>ordered_non_unique</code></a>. Instantiations are dependent on the
|
|
following types:
|
|
<ul>
|
|
<li><code>Value</code> from <code>multi_index_container</code>,</li>
|
|
<li><code>Allocator</code> from <code>multi_index_container</code>,</li>
|
|
<li><code>TagList</code> from the index specifier (if provided),</li>
|
|
<li><code>KeyFromValue</code> from the index specifier,</li>
|
|
<li><code>Compare</code> from the index specifier.</li>
|
|
</ul>
|
|
<code>TagList</code> must be an instantiation of
|
|
<a href="indices.html#tag"><code>tag</code></a>. The type <code>KeyFromValue</code>,
|
|
which determines the mechanism for extracting a key from <code>Value</code>,
|
|
must be a model of <a href="key_extraction.html#key_extractors">
|
|
<code>Key Extractor</code></a> from <code>Value</code>. <code>Compare</code> is a
|
|
<a href="http://www.sgi.com/tech/stl/StrictWeakOrdering.html">
|
|
<code>Strict Weak Ordering</code></a> on elements of
|
|
<code>KeyFromValue::result_type</code>.
|
|
</p>
|
|
|
|
<h4><a name="constructors">Constructors, copy and assignment</a></h4>
|
|
|
|
<p>
|
|
As explained in the <a href="indices.html#index_concepts">index
|
|
concepts section</a>, indices do not have public constructors or destructors.
|
|
Assignment, on the other hand, is provided.
|
|
</p>
|
|
|
|
<code><b>index class name</b>& operator=(const <b>index class name</b>& x);</code>
|
|
|
|
<blockquote>
|
|
<b>Effects:</b>
|
|
<blockquote><pre>
|
|
<span class=identifier>a</span><span class=special>=</span><span class=identifier>b</span><span class=special>;</span>
|
|
</pre></blockquote>
|
|
where <code>a</code> and <code>b</code> are the <code>multi_index_container</code>
|
|
objects to which <code>*this</code> and <code>x</code> belongs, respectively.<br>
|
|
<b>Returns:</b> <code>*this</code>.<br>
|
|
</blockquote>
|
|
|
|
<h4><a name="modifiers">Modifiers</a></h4>
|
|
|
|
<code>std::pair<iterator,bool> insert(const value_type& x);</code>
|
|
|
|
<blockquote>
|
|
<b>Effects:</b> Inserts <code>x</code> into the <code>multi_index_container</code> to which
|
|
the index belongs if
|
|
<ul>
|
|
<li>the index is non-unique OR no other element exists with
|
|
equivalent key,</li>
|
|
<li>AND insertion is allowed by all other indices of the
|
|
<code>multi_index_container</code>.</li>
|
|
</ul>
|
|
<b>Returns:</b> The return value is a pair <code>p</code>. <code>p.second</code>
|
|
is <code>true</code> if and only if insertion took place. On successful insertion,
|
|
<code>p.first</code> points to the element inserted; otherwise, <code>p.first</code>
|
|
points to an element that caused the insertion to be banned. Note that more than
|
|
one element can be causing insertion not to be allowed.<br>
|
|
<b>Complexity:</b> <code>O(I(n))</code>.<br>
|
|
<b>Exception safety:</b> Strong.<br>
|
|
</blockquote>
|
|
|
|
<code>iterator insert(iterator position,const value_type& x);</code>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> <code>position</code> is a valid iterator of the index.</br>
|
|
<b>Effects:</b> Inserts <code>x</code> into the <code>multi_index_container</code> to which
|
|
the index belongs if
|
|
<ul>
|
|
<li>the index is non-unique OR no other element exists with
|
|
equivalent key,</li>
|
|
<li>AND insertion is allowed by all other indices of the
|
|
<code>multi_index_container</code>.</li>
|
|
</ul>
|
|
<code>position</code> is used as a hint to improve the efficiency of the
|
|
operation.<br>
|
|
<b>Returns:</b> On successful insertion, an iterator to the newly inserted
|
|
element. Otherwise, an iterator to an element that caused the insertion to be
|
|
banned. Note that more than one element can be causing insertion not to be
|
|
allowed.<br>
|
|
<b>Complexity:</b> <code>O(H(n))</code>.<br>
|
|
<b>Exception safety:</b> Strong.<br>
|
|
</blockquote>
|
|
|
|
<code>template<typename InputIterator><br>
|
|
void insert(InputIterator first,InputIterator last);</code>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> <code>InputIterator</code> is a model of
|
|
<a href="http://www.sgi.com/tech/stl/InputIterator.html">
|
|
<code>Input Iterator</code></a> over elements of type
|
|
<code>value_type</code> or a type convertible to <code>value_type</code>.
|
|
<code>first</code> and <code>last</code> are not iterators into any
|
|
index of the <code>multi_index_container</code> to which this index belongs.
|
|
<code>last</code> is reachable from <code>first</code>.</br>
|
|
<b>Effects:</b>
|
|
<blockquote><pre>
|
|
<span class=identifier>iterator</span> <span class=identifier>hint</span><span class=special>=</span><span class=identifier>end</span><span class=special>();</span>
|
|
<span class=keyword>while</span><span class=special>(</span><span class=identifier>first</span><span class=special>!=</span><span class=identifier>last</span><span class=special>)</span><span class=identifier>hint</span><span class=special>=</span><span class=identifier>insert</span><span class=special>(</span><span class=identifier>hint</span><span class=special>,*</span><span class=identifier>first</span><span class=special>++);</span>
|
|
</pre></blockquote>
|
|
<b>Complexity:</b> <code>O(m*H(n+m))</code>, where
|
|
<code>m</code> is the number of elements in [<code>first</code>,
|
|
<code>last</code>).<br>
|
|
<b>Exception safety:</b> Basic.<br>
|
|
</blockquote>
|
|
|
|
<code>void erase(iterator position);</code>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> <code>position</code> is a valid dereferenceable iterator
|
|
of the index.</br>
|
|
<b>Effects:</b> Deletes the element pointed to by <code>position</code>.<br>
|
|
<b>Complexity:</b> <code>O(D(n))</code>.<br>
|
|
<b>Exception safety:</b> <code>nothrow</code>.<br>
|
|
</blockquote>
|
|
|
|
<code>size_type erase(const key_type& x);</code>
|
|
|
|
<blockquote>
|
|
<b>Effects:</b> Deletes the elements with key equivalent to <code>x</code>.<br>
|
|
<b>Returns:</b> Number of elements deleted.<br>
|
|
<b>Complexity:</b> <code>O(log(n) + m*D(n))</code>, where <code>m</code> is
|
|
the number of elements deleted.<br>
|
|
<b>Exception safety:</b> <code>nothrow</code>.<br>
|
|
</blockquote>
|
|
|
|
<code>void erase(iterator first,iterator last);</code>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> [<code>first</code>,<code>last</code>) is a valid
|
|
range of the index.<br>
|
|
<b>Effects:</b> Deletes the elements in [<code>first</code>,<code>last</code>).<br>
|
|
<b>Complexity:</b> <code>O(log(n) + m*D(n))</code>, where <code>m</code> is
|
|
the number of elements in [<code>first</code>,<code>last</code>).<br>
|
|
<b>Exception safety:</b> <code>nothrow</code>.<br>
|
|
</blockquote>
|
|
|
|
<a name="replace"><code>bool replace(iterator position,const value_type& x);</code></a>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> <code>position</code> is a valid dereferenceable iterator
|
|
of the index.</br>
|
|
<b>Effects:</b> Assigns the value <code>x</code> to the element pointed
|
|
to by <code>position</code> into the <code>multi_index_container</code> to which
|
|
the index belongs if, for the value <code>x</code>
|
|
<ul>
|
|
<li>the index is non-unique OR no other element exists
|
|
(except possibly <code>*position</code>) with equivalent key,</li>
|
|
<li>AND replacing is allowed by all other indices of the
|
|
<code>multi_index_container</code>.</li>
|
|
</ul>
|
|
<b>Postconditions:</b> Validity of <code>position</code> is preserved
|
|
in all cases.<br>
|
|
<b>Returns:</b> <code>true</code> if the replacement took place,
|
|
<code>false</code> otherwise.<br>
|
|
<b>Complexity:</b> <code>O(R(n))</code>.<br>
|
|
<b>Exception safety:</b> Strong. If an exception is thrown by some
|
|
user-provided operation the <code>multi_index_container</code> to which the index
|
|
belongs remains in its original state.
|
|
</blockquote>
|
|
|
|
<a name="modify">
|
|
<code>template<typename Modifier> bool modify(iterator position,Modifier mod);</code></a>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> <code>Modifier</code> is a model of
|
|
<a href="http://www.sgi.com/tech/stl/UnaryFunction.html">
|
|
<code>Unary Function</code></a> accepting arguments of type
|
|
<code>value_type&</code>. <code>position</code> is a valid dereferenceable
|
|
iterator of the index.</br>
|
|
<b>Effects:</b> Calls <code>mod(e)</code> where <code>e</code> is the element
|
|
pointed to by <code>position</code> and rearranges <code>*position</code> into
|
|
all the indices of the <code>multi_index_container</code>. Rearrangement is successful if
|
|
<ul>
|
|
<li>the index is non-unique OR no other element exists
|
|
with equivalent key,</li>
|
|
<li>AND rearrangement is allowed by all other indices of the
|
|
<code>multi_index_container</code>.</li>
|
|
</ul>
|
|
If the rearrangement fails, the element is erased.<br>
|
|
<b>Postconditions:</b> Validity of <code>position</code> is preserved if the
|
|
operation succeeds.<br>
|
|
<b>Returns:</b> <code>true</code> if the operation succeeded, <code>false</code>
|
|
otherwise.<br>
|
|
<b>Complexity:</b> <code>O(M(n))</code>.<br>
|
|
<b>Exception safety:</b> Basic. If an exception is thrown by some
|
|
user-provided operation (except possibly <code>mod</code>), then
|
|
the element pointed to by <code>position</code> is erased.
|
|
</blockquote>
|
|
|
|
<a name="modify_key">
|
|
<code>template<typename Modifier> bool modify_key(iterator position,Modifier mod);</code></a>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> <code>key_from_value</code> is a read/write
|
|
<a href="key_extraction.html#key_extractors"><code>Key Extractor</code></a>
|
|
from <code>value_type</code>. <code>Modifier</code> is a model of
|
|
<a href="http://www.sgi.com/tech/stl/UnaryFunction.html">
|
|
<code>Unary Function</code></a> accepting arguments of type
|
|
<code>key_type&</code>. <code>position</code> is a valid dereferenceable
|
|
iterator of the index.</br>
|
|
<b>Effects:</b> Calls <code>mod(k)</code> where <code>k</code> is the key
|
|
obtained by the internal <code>KeyFromValue</code> object of the index from
|
|
the element pointed to by <code>position</code>, and rearranges
|
|
<code>*position</code> into all the indices of the <code>multi_index_container</code>.
|
|
Rearrangement is successful if
|
|
<ul>
|
|
<li>the index is non-unique OR no other element exists
|
|
with equivalent key,</li>
|
|
<li>AND rearrangement is allowed by all other indices of the
|
|
<code>multi_index_container</code>.</li>
|
|
</ul>
|
|
If the rearrangement fails, the element is erased.<br>
|
|
<b>Postconditions:</b>Validity of <code>position</code> is preserved if
|
|
the operation succeeds.<br>
|
|
<b>Returns:</b> <code>true</code> if the operation succeeded, <code>false</code>
|
|
otherwise.<br>
|
|
<b>Complexity:</b> <code>O(M(n))</code>.<br>
|
|
<b>Exception safety:</b> Basic. If an exception is thrown by some
|
|
user-provided operation (except possibly <code>mod</code>), then
|
|
the element pointed to by <code>position</code> is erased.
|
|
</blockquote>
|
|
|
|
<h4><a name="observers">Observers</a></h4>
|
|
|
|
<p>Apart from standard <code>key_comp</code> and <code>value_comp</code>,
|
|
ordered indices have a member function for retrieving the internal key extractor
|
|
used.
|
|
</p>
|
|
|
|
<code>key_from_value key_extractor()const;</code>
|
|
|
|
<blockquote>
|
|
Returns a copy of the <code>key_from_value</code> object used to construct
|
|
the index.<br>
|
|
<b>Complexity:</b> Constant.
|
|
</blockquote>
|
|
|
|
<h4><a name="set_operations">Set operations</a></h4>
|
|
|
|
<p>
|
|
Ordered indices provide the full lookup functionality required by
|
|
<a href="http://www.sgi.com/tech/stl/SortedAssociativeContainer.html">
|
|
<code>Sorted Associative Containers</code></a> and
|
|
<a href="http://www.sgi.com/tech/stl/UniqueAssociativeContainer.html">
|
|
<code>Unique Associative Containers</code></a>, namely <code>find</code>,
|
|
<code>count</code>, <code>lower_bound</code>, <code>upper_bound</code>
|
|
and <code>equal_range</code>. Additionally, these member functions are
|
|
templatized to allow for non-standard arguments, so extending
|
|
the types of search operations allowed. The kind of arguments permissible
|
|
when invoking the lookup member functions is defined by the following
|
|
concept.
|
|
</p>
|
|
|
|
<p>
|
|
Consider a
|
|
<a href="http://www.sgi.com/tech/stl/StrictWeakOrdering.html">
|
|
<code>Strict Weak Ordering</code></a> <code>Compare</code> over values
|
|
of type <code>Key</code>. A pair of types (<code>CompatibleKey</code>,
|
|
<code>CompatibleCompare</code>) is said to be a <i>compatible extension</i>
|
|
of <code>Compare</code> if
|
|
<ol>
|
|
<li><code>CompatibleCompare</code> is a
|
|
<a href="http://www.sgi.com/tech/stl/BinaryPredicate.html">
|
|
<code>Binary Predicate</code></a> over (<code>Key</code>,
|
|
<code>CompatibleKey</code>),</li>
|
|
<li><code>CompatibleCompare</code> is a
|
|
<a href="http://www.sgi.com/tech/stl/BinaryPredicate.html">
|
|
<code>Binary Predicate</code></a> over (<code>CompatibleKey</code>,
|
|
<code>Key</code>),</li>
|
|
<li>if <code>c_comp(ck,k1)</code> then <code>!c_comp(k1,ck)</code>,</li>
|
|
<li>if <code>!c_comp(ck,k1)</code> and <code>!comp(k1,k2)</code> then
|
|
<code>!c_comp(ck,k2)</code>,</li>
|
|
<li>if <code>!c_comp(k1,ck)</code> and <code>!comp(k2,k1)</code> then
|
|
<code>!c_comp(k2,ck)</code>,</li>
|
|
</ol>
|
|
for every <code>c_comp</code> of type <code>CompatibleCompare</code>,
|
|
<code>comp</code> of type <code>Compare</code>, <code>ck</code> of type
|
|
<code>CompatibleKey</code> and <code>k1</code>, <code>k2</code> of type
|
|
<code>Key</code>.
|
|
</p>
|
|
|
|
|
|
|
|
<p>Additionally, a type <code>CompatibleKey</code> is said to be a
|
|
<i>compatible key</i> of <code>Compare</code> if (<code>CompatibleKey</code>,
|
|
<code>Compare</code>) is a compatible extension of <code>Compare</code>.
|
|
This implies that <code>Compare</code>, as well as being a strict
|
|
weak ordering, accepts arguments of type <code>CompatibleKey</code>,
|
|
which usually means it has several overloads of <code>operator()</code>.
|
|
</p>
|
|
|
|
<p>
|
|
In the context of a compatible extension or a compatible key, the expressions
|
|
"equivalent", "less than" and "greater than" take on their obvious
|
|
interpretations.
|
|
</p>
|
|
|
|
<code>template<typename CompatibleKey> const_iterator find(const CompatibleKey& x)const;
|
|
</code>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> <code>CompatibleKey</code> is a compatible key of
|
|
<code>key_compare</code>.</br>
|
|
<b>Effects:</b> Returns a pointer to an element whose key is equivalent to
|
|
<code>x</code>, or <code>end()</code> if such an element does not exist.<br>
|
|
<b>Complexity:</b> <code>O(log(n))</code>.<br>
|
|
</blockquote>
|
|
|
|
<code>template<typename CompatibleKey,typename CompatibleCompare><br>
|
|
const_iterator find(const CompatibleKey& x,const CompatibleCompare& comp)const;
|
|
</code>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> (<code>CompatibleKey</code>, <code>CompatibleCompare</code>)
|
|
is a compatible extension of <code>key_compare</code>.</br>
|
|
<b>Effects:</b> Returns a pointer to an element whose key is equivalent to
|
|
<code>x</code>, or <code>end()</code> if such an element does not exist.<br>
|
|
<b>Complexity:</b> <code>O(log(n))</code>.<br>
|
|
</blockquote>
|
|
|
|
<code>template<typename CompatibleKey> size_type<br>
|
|
count(const CompatibleKey& x)const;
|
|
</code>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> <code>CompatibleKey</code> is a compatible key of
|
|
<code>key_compare</code>.</br>
|
|
<b>Effects:</b> Returns the number of elements with key equivalent to <code>x</code>.<br>
|
|
<b>Complexity:</b> <code>O(log(n) + count(x))</code>.<br>
|
|
</blockquote>
|
|
|
|
<code>template<typename CompatibleKey,typename CompatibleCompare><br>
|
|
size_type count(const CompatibleKey& x,const CompatibleCompare& comp)const;
|
|
</code>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> (<code>CompatibleKey</code>, <code>CompatibleCompare</code>)
|
|
is a compatible extension of <code>key_compare</code>.</br>
|
|
<b>Effects:</b> Returns the number of elements with key equivalent to <code>x</code>.<br>
|
|
<b>Complexity:</b> <code>O(log(n) + count(x,comp))</code>.<br>
|
|
</blockquote>
|
|
|
|
<code>template<typename CompatibleKey><br>
|
|
const_iterator lower_bound(const CompatibleKey& x)const;
|
|
</code>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> <code>CompatibleKey</code> is a compatible key of
|
|
<code>key_compare</code>.</br>
|
|
<b>Effects:</b> Returns an iterator pointing to the first element with
|
|
key not less than <code>x</code>, or <code>end()</code> if such an element does
|
|
not exist.<br>
|
|
<b>Complexity:</b> <code>O(log(n))</code>.<br>
|
|
</blockquote>
|
|
|
|
<code>template<typename CompatibleKey,typename CompatibleCompare><br>
|
|
const_iterator lower_bound(const CompatibleKey& x,const CompatibleCompare& comp)const;
|
|
</code>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> (<code>CompatibleKey</code>, <code>CompatibleCompare</code>)
|
|
is a compatible extension of <code>key_compare</code>.</br>
|
|
<b>Effects:</b> Returns an iterator pointing to the first element with
|
|
key not less than <code>x</code>, or <code>end()</code> if such an element does
|
|
not exist.<br>
|
|
<b>Complexity:</b> <code>O(log(n))</code>.<br>
|
|
</blockquote>
|
|
|
|
<code>template<typename CompatibleKey><br>
|
|
const_iterator upper_bound(const CompatibleKey& x)const;
|
|
</code>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> <code>CompatibleKey</code> is a compatible key of
|
|
<code>key_compare</code>.</br>
|
|
<b>Effects:</b> Returns an iterator pointing to the first element with
|
|
key greater than <code>x</code>, or <code>end()</code> if such an element does
|
|
not exist.<br>
|
|
<b>Complexity:</b> <code>O(log(n))</code>.<br>
|
|
</blockquote>
|
|
|
|
<code>template<typename CompatibleKey,typename CompatibleCompare><br>
|
|
const_iterator upper_bound(const CompatibleKey& x,const CompatibleCompare& comp)const;
|
|
</code>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> (<code>CompatibleKey</code>, <code>CompatibleCompare</code>)
|
|
is a compatible extension of <code>key_compare</code>.</br>
|
|
<b>Effects:</b> Returns an iterator pointing to the first element with
|
|
key greater than <code>x</code>, or <code>end()</code> if such an element does
|
|
not exist.<br>
|
|
<b>Complexity:</b> <code>O(log(n))</code>.<br>
|
|
</blockquote>
|
|
|
|
<code>template<typename CompatibleKey><br>
|
|
std::pair<const_iterator,const_iterator> equal_range(<br>
|
|
const CompatibleKey& x)const;
|
|
</code>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> <code>CompatibleKey</code> is a compatible key of
|
|
<code>key_compare</code>.</br>
|
|
<b>Effects:</b> Equivalent to <code>make_pair(lower_bound(x),upper_bound(x))</code>.<br>
|
|
<b>Complexity:</b> <code>O(log(n))</code>.<br>
|
|
</blockquote>
|
|
|
|
<code>template<typename CompatibleKey,typename CompatibleCompare><br>
|
|
std::pair<const_iterator,const_iterator> equal_range(</br>
|
|
const CompatibleKey& x,const CompatibleCompare& comp)const;
|
|
</code>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> (<code>CompatibleKey</code>, <code>CompatibleCompare</code>)
|
|
is a compatible extension of <code>key_compare</code>.</br>
|
|
<b>Effects:</b> Equivalent to
|
|
<code>make_pair(lower_bound(x,comp),upper_bound(x,comp))</code>.<br>
|
|
<b>Complexity:</b> <code>O(log(n))</code>.<br>
|
|
</blockquote>
|
|
|
|
|
|
<h4><a name="range_operations">Range operations</a></h4>
|
|
|
|
<p>
|
|
The member function <code>range</code> is not defined for sorted associative
|
|
containers, but ordered indices provide it as a convenient utility. A range
|
|
or interval is defined by two conditions for the lower and upper bounds, which
|
|
are modeled after the following concepts.
|
|
</p>
|
|
|
|
<p>
|
|
Consider a
|
|
<a href="http://www.sgi.com/tech/stl/StrictWeakOrdering.html">
|
|
<code>Strict Weak Ordering</code></a> <code>Compare</code> over values
|
|
of type <code>Key</code>. A type <code>LowerBounder</code> is said to be
|
|
a <i>lower bounder</i> of <code>Compare</code> if
|
|
<ol>
|
|
<li><code>LowerBounder</code> is a
|
|
<a href="http://www.sgi.com/tech/stl/Predicate.html">
|
|
<code>Predicate</code></a> over <code>Key</code>,</li>
|
|
<li>if <code>lower(k1)</code> and <code>!comp(k2,k1)</code> then
|
|
<code>lower(k2)</code>,</li>
|
|
</ol>
|
|
for every <code>lower</code> of type <code>LowerBounder</code>,
|
|
<code>comp</code> of type <code>Compare</code>, and <code>k1</code>,
|
|
<code>k2</code> of type <code>Key</code>. Similarly, an <i>upper bounder</i>
|
|
is a type <code>UpperBounder</code> such that
|
|
<ol>
|
|
<li><code>UpperBounder</code> is a
|
|
<a href="http://www.sgi.com/tech/stl/Predicate.html">
|
|
<code>Predicate</code></a> over <code>Key</code>,</li>
|
|
<li>if <code>upper(k1)</code> and <code>!comp(k1,k2)</code> then
|
|
<code>upper(k2)</code>,</li>
|
|
</ol>
|
|
for every <code>upper</code> of type <code>UpperBounder</code>,
|
|
<code>comp</code> of type <code>Compare</code>, and <code>k1</code>,
|
|
<code>k2</code> of type <code>Key</code>.
|
|
</p>
|
|
|
|
<code>template<typename LowerBounder,typename UpperBounder><br>
|
|
std::pair<const_iterator,const_iterator> range(<br>
|
|
LowerBounder lower,UpperBounder upper)const;
|
|
</code>
|
|
|
|
<blockquote>
|
|
<b>Requires:</b> <code>LowerBounder</code> and <code>UpperBounder</code> are
|
|
a lower and upper bounder of <code>key_compare</code>, respectively.</br>
|
|
<b>Effects:</b> Returns a pair of iterators pointing to the beginning and one
|
|
past the end of the subsequence of elements satisfying <code>lower</code> and
|
|
<code>upper</code> simultaneously. If no such elements exist, the iterators
|
|
both point to the first element satisfying <code>lower</code>, or else
|
|
are equal to <code>end()</code> if this latter element does not exist.<br>
|
|
<b>Complexity:</b> <code>O(log(n))</code>.<br>
|
|
<b>Variants:</b> In place of <code>lower</code> or <code>upper</code> (or both),
|
|
the singular value <code>boost::multi_index::unbounded</code> can be
|
|
provided. This acts as a predicate which all values of type <code>key_type</code>
|
|
satisfy.<br>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
|
|
<div class="prev_link"><a href="indices.html"><img src="../prev.gif" alt="index reference" border="0"><br>
|
|
Index reference
|
|
</a></div>
|
|
<div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.MultiIndex reference" border="0"><br>
|
|
Boost.MultiIndex reference
|
|
</a></div>
|
|
<div class="next_link"><a href="seq_indices.html"><img src="../next.gif" alt="sequenced indices" border="0"><br>
|
|
Sequenced indices
|
|
</a></div><br clear="all" style="clear: all;">
|
|
|
|
<br>
|
|
|
|
<p>Revised May 7th 2004</p>
|
|
|
|
<p>Copyright © 2003-2004 Joaquín M López Muñoz.
|
|
Use, modification, and distribution are subject to the Boost Software
|
|
License, Version 1.0. (See accompanying file <a href="../../../../LICENSE_1_0.txt">
|
|
LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
|
|
www.boost.org/LICENSE_1_0.txt</a>)
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|