boostorg/unordered
1
0
Fork 1
mirror of https://github.com/boostorg/unordered.git synced 2025-07-29 19:07:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #86 from cmazakas/qbk-cleanup

Browse Source 
Remove obsoleted documentation files
This commit is contained in:
Peter Dimov
2022-02-07 17:56:45 +02:00
committed by GitHub
parent b14aefa1d3 ef951094b3
commit cb4b417f76
16 changed files with 0 additions and 10273 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
doc/bibliography.xml
View File

@ -1,26 +0,0 @@
<!--
Copyright Daniel James 2008-2009
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)
-->
<section id="unordered.bibliography">
<title>Bibliography</title>
<bibliography>
<biblioentry>
<biblioset relation="journal">
<title>C/C++ Users Journal</title>
<date>February, 2006</date>
</biblioset>
<biblioset relation="article">
<authorgroup>
<author>
<firstname>Pete</firstname>
<surname>Becker</surname>
</author>
</authorgroup>
<title><ulink url="http://www.ddj.com/cpp/184402066">STL and TR1: Part III - Unordered containers</ulink></title>
</biblioset>
<para>An introducation to the standard unordered containers.</para>
</biblioentry>
</bibliography>
</section>

168
doc/buckets.qbk
View File

@ -1,168 +0,0 @@
[/ Copyright 2006-2008 Daniel James.
/ 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) ]
[section:buckets The Data Structure]
The containers are made up of a number of 'buckets', each of which can contain
any number of elements. For example, the following diagram shows an [classref
boost::unordered_set unordered_set] with 7 buckets containing 5 elements, `A`,
`B`, `C`, `D` and `E` (this is just for illustration, containers will typically
have more buckets).
[diagram buckets]
In order to decide which bucket to place an element in, the container applies
the hash function, `Hash`, to the element's key (for `unordered_set` and
`unordered_multiset` the key is the whole element, but is referred to as the key
so that the same terminology can be used for sets and maps). This returns a
value of type `std::size_t`. `std::size_t` has a much greater range of values
then the number of buckets, so the container applies another transformation to
that value to choose a bucket to place the element in.
Retrieving the elements for a given key is simple. The same process is applied
to the key to find the correct bucket. Then the key is compared with the
elements in the bucket to find any elements that match (using the equality
predicate `Pred`). If the hash function has worked well the elements will be
evenly distributed amongst the buckets so only a small number of elements will
need to be examined.
There is [link unordered.hash_equality more information on hash functions and
equality predicates in the next section].
You can see in the diagram that `A` & `D` have been placed in the same bucket.
When looking for elements in this bucket up to 2 comparisons are made, making
the search slower. This is known as a collision. To keep things fast we try to
keep collisions to a minimum.
'''
<table frame="all"><title>Methods for Accessing Buckets</title>
<tgroup cols="2">
<thead><row>
<entry><para>Method</para></entry>
<entry><para>Description</para></entry>
</row></thead>
<tbody>
<row>
<entry>'''`size_type bucket_count() const`'''</entry>
<entry>'''The number of buckets.'''</entry>
</row>
<row>
<entry>'''`size_type max_bucket_count() const`'''</entry>
<entry>'''An upper bound on the number of buckets.'''</entry>
</row>
<row>
<entry>'''`size_type bucket_size(size_type n) const`'''</entry>
<entry>'''The number of elements in bucket `n`.'''</entry>
</row>
<row>
<entry>'''`size_type bucket(key_type const& k) const`'''</entry>
<entry>'''Returns the index of the bucket which would contain `k`.'''</entry>
</row>
<row>
<entry>'''`local_iterator begin(size_type n);`'''</entry>
<entry morerows='5'>'''Return begin and end iterators for bucket `n`.'''</entry>
</row>
<row>
<entry>'''`local_iterator end(size_type n);`'''</entry>
</row>
<row>
<entry>'''`const_local_iterator begin(size_type n) const;`'''</entry>
</row>
<row>
<entry>'''`const_local_iterator end(size_type n) const;`'''</entry>
</row>
<row>
<entry>'''`const_local_iterator cbegin(size_type n) const;`'''</entry>
</row>
<row>
<entry>'''`const_local_iterator cend(size_type n) const;`'''</entry>
</row>
</tbody>
</tgroup>
</table>
'''
[h2 Controlling the number of buckets]
As more elements are added to an unordered associative container, the number
of elements in the buckets will increase causing performance to degrade.
To combat this the containers increase the bucket count as elements are inserted.
You can also tell the container to change the bucket count (if required) by
calling `rehash`.
The standard leaves a lot of freedom to the implementer to decide how the
number of buckets is chosen, but it does make some requirements based on the
container's 'load factor', the average number of elements per bucket.
Containers also have a 'maximum load factor' which they should try to keep the
load factor below.
You can't control the bucket count directly but there are two ways to
influence it:
* Specify the minimum number of buckets when constructing a container or
when calling `rehash`.
* Suggest a maximum load factor by calling `max_load_factor`.
`max_load_factor` doesn't let you set the maximum load factor yourself, it just
lets you give a /hint/. And even then, the draft standard doesn't actually
require the container to pay much attention to this value. The only time the
load factor is /required/ to be less than the maximum is following a call to
`rehash`. But most implementations will try to keep the number of elements
below the max load factor, and set the maximum load factor to be the same as
or close to the hint - unless your hint is unreasonably small or large.
[table:bucket_size Methods for Controlling Bucket Size
[[Method] [Description]]
[
[`X(size_type n)`]
[Construct an empty container with at least `n` buckets (`X` is the container type).]
]
[
[`X(InputIterator i, InputIterator j, size_type n)`]
[Construct an empty container with at least `n` buckets and insert elements
from the range \[`i`, `j`) (`X` is the container type).]
]
[
[`float load_factor() const`]
[The average number of elements per bucket.]
]
[
[`float max_load_factor() const`]
[Returns the current maximum load factor.]
]
[
[`float max_load_factor(float z)`]
[Changes the container's maximum load factor, using `z` as a hint.]
]
[
[`void rehash(size_type n)`]
[Changes the number of buckets so that there at least `n` buckets, and
so that the load factor is less than the maximum load factor.]
]
]
[h2 Iterator Invalidation]
It is not specified how member functions other than `rehash` affect
the bucket count, although `insert` is only allowed to invalidate iterators
when the insertion causes the load factor to be greater than or equal to the
maximum load factor. For most implementations this means that `insert` will only
change the number of buckets when this happens. While iterators can be
invalidated by calls to `insert` and `rehash`, pointers and references to the
container's elements are never invalidated.
In a similar manner to using `reserve` for `vector`s, it can be a good idea
to call `rehash` before inserting a large number of elements. This will get
the expensive rehashing out of the way and let you store iterators, safe in
the knowledge that they won't be invalidated. If you are inserting `n`
elements into container `x`, you could first call:
x.rehash((x.size() + n) / x.max_load_factor());
[blurb Note: `rehash`'s argument is the minimum number of buckets, not the
number of elements, which is why the new size is divided by the maximum load factor.]
[endsect]

375
doc/changes.qbk
View File

@ -1,375 +0,0 @@
[/ Copyright 2008 Daniel James.
/ 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) ]
[template ticket[number]'''<ulink
url="https://svn.boost.org/trac/boost/ticket/'''[number]'''">'''#[number]'''</ulink>''']
[template pull_request[number][@https://github.com/boostorg/unordered/pull/[number] GitHub #[number]]]
[section:changes Change Log]
[heading Changes in Boost 1.79.0]
* Improved C++20 support:
* All containers have been updated to support
heterogeneous `count`, `equal_range` and `find`.
* All containers now implement the member function `contains`
* Improved C++23 support:
* All containers have been updated to support
heterogeneous `erase` and `extract`.
* Changed behavior of `reserve` to eagerly
allocate ([@https://github.com/boostorg/unordered/pull/59 PR#59]).
* Various warning fixes in the test suite.
* Update code to internally use `boost::allocator_traits`.
[heading Changes in Boost 1.67.0]
* Improved C++17 support:
* Add template deduction guides from the standard.
* Use a simple implementation of `optional` in node handles, so
that they're closer to the standard.
* Add missing `noexcept` specifications to `swap`, `operator=`
and node handles, and change the implementation to match.
Using `std::allocator_traits::is_always_equal`, or our own
implementation when not available, and
`boost::is_nothrow_swappable` in the implementation.
* Improved C++20 support:
* Use `boost::to_address`, which has the proposed C++20 semantics,
rather than the old custom implementation.
* Add `element_type` to iterators, so that `std::pointer_traits`
will work.
* Use `std::piecewise_construct` on recent versions of Visual C++,
and other uses of the Dinkumware standard library,
now using Boost.Predef to check compiler and library versions.
* Use `std::iterator_traits` rather than the boost iterator traits
in order to remove dependency on Boost.Iterator.
* Remove iterators' inheritance from `std::iterator`, which is
deprecated in C++17, thanks to Daniela Engert
([@https://github.com/boostorg/unordered/pull/7 PR#7]).
* Stop using `BOOST_DEDUCED_TYPENAME`.
* Update some Boost include paths.
* Rename some internal methods, and variables.
* Various testing improvements.
* Miscellaneous internal changes.
[heading Changes in Boost 1.66.0]
* Simpler move construction implementation.
* Documentation fixes ([pull_request 6]).
[heading Changes in Boost 1.65.0]
* Add deprecated attributes to `quick_erase` and `erase_return_void`.
I really will remove them in a future version this time.
* Small standards compliance fixes:
* `noexpect` specs for `swap` free functions.
* Add missing `insert(P&&)` methods.
[heading Changes in Boost 1.64.0]
* Initial support for new C++17 member functions:
`insert_or_assign` and `try_emplace` in `unordered_map`,
* Initial support for `merge` and `extract`.
Does not include transferring nodes between
`unordered_map` and `unordered_multimap` or between `unordered_set` and
`unordered_multiset` yet. That will hopefully be in the next version of
Boost.
[heading Changes in Boost 1.63.0]
* Check hint iterator in `insert`/`emplace_hint`.
* Fix some warnings, mostly in the tests.
* Manually write out `emplace_args` for small numbers of arguments -
should make template error messages a little more bearable.
* Remove superfluous use of `boost::forward` in emplace arguments,
which fixes emplacing string literals in old versions of Visual C++.
* Fix an exception safety issue in assignment. If bucket allocation
throws an exception, it can overwrite the hash and equality functions while
leaving the existing elements in place. This would mean that the function
objects wouldn't match the container elements, so elements might be in the
wrong bucket and equivalent elements would be incorrectly handled.
* Various reference documentation improvements.
* Better allocator support ([ticket 12459]).
* Make the no argument constructors implicit.
* Implement missing allocator aware constructors.
* Fix assigning the hash/key equality functions for empty containers.
* Remove unary/binary_function from the examples in the documentation.
They are removed in C++17.
* Support 10 constructor arguments in emplace. It was meant to support up to 10
arguments, but an off by one error in the preprocessor code meant it only
supported up to 9.
[heading Changes in Boost 1.62.0]
* Remove use of deprecated `boost::iterator`.
* Remove `BOOST_NO_STD_DISTANCE` workaround.
* Remove `BOOST_UNORDERED_DEPRECATED_EQUALITY` warning.
* Simpler implementation of assignment, fixes an exception safety issue
for `unordered_multiset` and `unordered_multimap`. Might be a little slower.
* Stop using return value SFINAE which some older compilers have issues
with.
[heading Changes in Boost 1.58.0]
* Remove unnecessary template parameter from const iterators.
* Rename private `iterator` typedef in some iterator classes, as it
confuses some traits classes.
* Fix move assignment with stateful, propagate_on_container_move_assign
allocators ([ticket 10777]).
* Fix rare exception safety issue in move assignment.
* Fix potential overflow when calculating number of buckets to allocate
([@https://github.com/boostorg/unordered/pull/4 GitHub #4]).
[heading Changes in Boost 1.57.0]
* Fix the `pointer` typedef in iterators ([ticket 10672]).
* Fix Coverity warning
([@https://github.com/boostorg/unordered/pull/2 GitHub #2]).
[heading Changes in Boost 1.56.0]
* Fix some shadowed variable warnings ([ticket 9377]).
* Fix allocator use in documentation ([ticket 9719]).
* Always use prime number of buckets for integers. Fixes performance
regression when inserting consecutive integers, although makes other
uses slower ([ticket 9282]).
* Only construct elements using allocators, as specified in C++11 standard.
[heading Changes in Boost 1.55.0]
* Avoid some warnings ([ticket 8851], [ticket 8874]).
* Avoid exposing some detail functions via. ADL on the iterators.
* Follow the standard by only using the allocators' construct and destroy
methods to construct and destroy stored elements. Don't use them for internal
data like pointers.
[heading Changes in Boost 1.54.0]
* Mark methods specified in standard as `noexpect`. More to come in the next
release.
* If the hash function and equality predicate are known to both have nothrow
move assignment or construction then use them.
[heading Changes in Boost 1.53.0]
* Remove support for the old pre-standard variadic pair constructors, and
equality implementation. Both have been deprecated since Boost 1.48.
* Remove use of deprecated config macros.
* More internal implementation changes, including a much simpler
implementation of `erase`.
[heading Changes in Boost 1.52.0]
* Faster assign, which assigns to existing nodes where possible, rather than
creating entirely new nodes and copy constructing.
* Fixed bug in `erase_range` ([ticket 7471]).
* Reverted some of the internal changes to how nodes are created, especially
for C++11 compilers. 'construct' and 'destroy' should work a little better
for C++11 allocators.
* Simplified the implementation a bit. Hopefully more robust.
[heading Changes in Boost 1.51.0]
* Fix construction/destruction issue when using a C++11 compiler with a
C++03 allocator ([ticket 7100]).
* Remove a `try..catch` to support compiling without exceptions.
* Adjust SFINAE use to try to support g++ 3.4 ([ticket 7175]).
* Updated to use the new config macros.
[heading Changes in Boost 1.50.0]
* Fix equality for `unordered_multiset` and `unordered_multimap`.
* [@https://svn.boost.org/trac/boost/ticket/6857 Ticket 6857]:
Implement `reserve`.
* [@https://svn.boost.org/trac/boost/ticket/6771 Ticket 6771]:
Avoid gcc's `-Wfloat-equal` warning.
* [@https://svn.boost.org/trac/boost/ticket/6784 Ticket 6784]:
Fix some Sun specific code.
* [@https://svn.boost.org/trac/boost/ticket/6190 Ticket 6190]:
Avoid gcc's `-Wshadow` warning.
* [@https://svn.boost.org/trac/boost/ticket/6905 Ticket 6905]:
Make namespaces in macros compatible with `bcp` custom namespaces.
Fixed by Luke Elliott.
* Remove some of the smaller prime number of buckets, as they may make
collisions quite probable (e.g. multiples of 5 are very common because
we used base 10).
* On old versions of Visual C++, use the container library's implementation
of `allocator_traits`, as it's more likely to work.
* On machines with 64 bit std::size_t, use power of 2 buckets, with Thomas
Wang's hash function to pick which one to use. As modulus is very slow
for 64 bit values.
* Some internal changes.
[heading Changes in Boost 1.49.0]
* Fix warning due to accidental odd assignment.
* Slightly better error messages.
[heading Changes in Boost 1.48.0 - Major update]
This is major change which has been converted to use Boost.Move's move
emulation, and be more compliant with the C++11 standard. See the
[link unordered.compliance compliance section] for details.
The container now meets C++11's complexity requirements, but to do so
uses a little more memory. This means that `quick_erase` and
`erase_return_void` are no longer required, they'll be removed in a
future version.
C++11 support has resulted in some breaking changes:
* Equality comparison has been changed to the C++11 specification.
In a container with equivalent keys, elements in a group with equal
keys used to have to be in the same order to be considered equal,
now they can be a permutation of each other. To use the old
behavior define the macro `BOOST_UNORDERED_DEPRECATED_EQUALITY`.
* The behaviour of swap is different when the two containers to be
swapped has unequal allocators. It used to allocate new nodes using
the appropriate allocators, it now swaps the allocators if
the allocator has a member structure `propagate_on_container_swap`,
such that `propagate_on_container_swap::value` is true.
* Allocator's `construct` and `destroy` functions are called with raw
pointers, rather than the allocator's `pointer` type.
* `emplace` used to emulate the variadic pair constructors that
appeared in early C++0x drafts. Since they were removed it no
longer does so. It does emulate the new `piecewise_construct`
pair constructors - only you need to use
`boost::piecewise_construct`. To use the old emulation of
the variadic constructors define
`BOOST_UNORDERED_DEPRECATED_PAIR_CONSTRUCT`.
[heading Changes in Boost 1.45.0]
* Fix a bug when inserting into an `unordered_map` or `unordered_set` using
iterators which returns `value_type` by copy.
[heading Changes in Boost 1.43.0]
* [@http://svn.boost.org/trac/boost/ticket/3966 Ticket 3966]:
`erase_return_void` is now `quick_erase`, which is the
[@http://home.roadrunner.com/~hinnant/issue_review/lwg-active.html#579
current forerunner for resolving the slow erase by iterator], although
there's a strong possibility that this may change in the future. The old
method name remains for backwards compatibility but is considered deprecated
and will be removed in a future release.
* Use Boost.Exception.
* Stop using deprecated `BOOST_HAS_*` macros.
[heading Changes in Boost 1.42.0]
* Support instantiating the containers with incomplete value types.
* Reduced the number of warnings (mostly in tests).
* Improved codegear compatibility.
* [@http://svn.boost.org/trac/boost/ticket/3693 Ticket 3693]:
Add `erase_return_void` as a temporary workaround for the current
`erase` which can be inefficient because it has to find the next
element to return an iterator.
* Add templated find overload for compatible keys.
* [@http://svn.boost.org/trac/boost/ticket/3773 Ticket 3773]:
Add missing `std` qualifier to `ptrdiff_t`.
* Some code formatting changes to fit almost all lines into 80 characters.
[heading Changes in Boost 1.41.0 - Major update]
* The original version made heavy use of macros to sidestep some of the older
compilers' poor template support. But since I no longer support those
compilers and the macro use was starting to become a maintenance burden it
has been rewritten to use templates instead of macros for the implementation
classes.
* The container object is now smaller thanks to using `boost::compressed_pair`
for EBO and a slightly different function buffer - now using a bool instead
of a member pointer.
* Buckets are allocated lazily which means that constructing an empty container
will not allocate any memory.
[heading Changes in Boost 1.40.0]
* [@https://svn.boost.org/trac/boost/ticket/2975 Ticket 2975]:
Store the prime list as a preprocessor sequence - so that it will always get
the length right if it changes again in the future.
* [@https://svn.boost.org/trac/boost/ticket/1978 Ticket 1978]:
Implement `emplace` for all compilers.
* [@https://svn.boost.org/trac/boost/ticket/2908 Ticket 2908],
[@https://svn.boost.org/trac/boost/ticket/3096 Ticket 3096]:
Some workarounds for old versions of borland, including adding explicit
destructors to all containers.
* [@https://svn.boost.org/trac/boost/ticket/3082 Ticket 3082]:
Disable incorrect Visual C++ warnings.
* Better configuration for C++0x features when the headers aren't available.
* Create less buckets by default.
[heading Changes in Boost 1.39.0]
* [@https://svn.boost.org/trac/boost/ticket/2756 Ticket 2756]: Avoid a warning
on Visual C++ 2009.
* Some other minor internal changes to the implementation, tests and
documentation.
* Avoid an unnecessary copy in `operator[]`.
* [@https://svn.boost.org/trac/boost/ticket/2975 Ticket 2975]: Fix length of
prime number list.
[heading Changes in Boost 1.38.0]
* Use [@boost:/libs/core/swap.html `boost::swap`].
* [@https://svn.boost.org/trac/boost/ticket/2237 Ticket 2237]:
Document that the equality and inequality operators are undefined for two
objects if their equality predicates aren't equivalent. Thanks to Daniel
Krügler.
* [@https://svn.boost.org/trac/boost/ticket/1710 Ticket 1710]:
Use a larger prime number list. Thanks to Thorsten Ottosen and Hervé
Brönnimann.
* Use
[@boost:/libs/type_traits/doc/html/boost_typetraits/category/alignment.html
aligned storage] to store the types. This changes the way the allocator is
used to construct nodes. It used to construct the node with two calls to
the allocator's `construct` method - once for the pointers and once for the
value. It now constructs the node with a single call to construct and
then constructs the value using in place construction.
* Add support for C++0x initializer lists where they're available (currently
only g++ 4.4 in C++0x mode).
[heading Changes in Boost 1.37.0]
* Rename overload of `emplace` with hint, to `emplace_hint` as specified in
[@http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2008/n2691.pdf n2691].
* Provide forwarding headers at `<boost/unordered/unordered_map_fwd.hpp>` and
`<boost/unordered/unordered_set_fwd.hpp>`.
* Move all the implementation inside `boost/unordered`, to assist
modularization and hopefully make it easier to track Changes in Boost subversion.
[heading Changes in Boost 1.36.0]
First official release.
* Rearrange the internals.
* Move semantics - full support when rvalue references are available, emulated
using a cut down version of the Adobe move library when they are not.
* Emplace support when rvalue references and variadic template are available.
* More efficient node allocation when rvalue references and variadic template
are available.
* Added equality operators.
[heading Boost 1.35.0 Add-on - 31st March 2008]
Unofficial release uploaded to vault, to be used with Boost 1.35.0. Incorporated
many of the suggestions from the review.
* Improved portability thanks to Boost regression testing.
* Fix lots of typos, and clearer text in the documentation.
* Fix floating point to `std::size_t` conversion when calculating sizes from
the max load factor, and use `double` in the calculation for greater accuracy.
* Fix some errors in the examples.
[heading Review Version]
Initial review version, for the review conducted from 7th December 2007 to
16th December 2007.
[endsect]

161
doc/comparison.qbk
View File

@ -1,161 +0,0 @@
[/ Copyright 2006-2011 Daniel James.
/ 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) ]
[section:comparison Comparison with Associative Containers]
[table:interface_differences Interface differences.
[[Associative Containers] [Unordered Associative Containers]]
[
[Parameterized by an ordering relation `Compare`]
[Parameterized by a function object `Hash` and an equivalence relation
`Pred`]
]
[
[Keys can be compared using `key_compare` which is accessed by member function `key_comp()`,
values can be compared using `value_compare` which is accessed by member function `value_comp()`.]
[Keys can be hashed using `hasher` which is accessed by member function `hash_function()`,
and checked for equality using `key_equal` which is accessed by member function `key_eq()`.
There is no function object for compared or hashing values.]
]
[
[Constructors have optional extra parameters for the comparison object.]
[Constructors have optional extra parameters for the initial minimum
number of buckets, a hash function and an equality object.]
]
[
[Keys `k1`, `k2` are considered equivalent if
`!Compare(k1, k2) && !Compare(k2, k1)`]
[Keys `k1`, `k2` are considered equivalent if `Pred(k1, k2)`]
]
[
[Member function `lower_bound(k)` and `upper_bound(k)`]
[No equivalent. Since the elements aren't ordered `lower_bound` and
`upper_bound` would be meaningless.]
]
[
[`equal_range(k)` returns an empty range at the position that k
would be inserted if k isn't present in the container.]
[`equal_range(k)` returns a range at the end of the container if
k isn't present in the container. It can't return a positioned
range as k could be inserted into multiple place. To find out the
bucket that k would be inserted into use `bucket(k)`. But remember
that an insert can cause the container to rehash - meaning that the
element can be inserted into a different bucket.]
]
[
[`iterator`, `const_iterator` are of the bidirectional category.]
[`iterator`, `const_iterator` are of at least the forward category.]
]
[
[Iterators, pointers and references to the container's elements are
never invalidated.]
[[link unordered.buckets.iterator_invalidation Iterators can
be invalidated by calls to insert or rehash]. Pointers and
references to the container's elements are never invalidated.]
]
[
[Iterators iterate through the container in the order defined by
the comparison object.]
[Iterators iterate through the container in an arbitrary order, that
can change as elements are inserted, although equivalent elements
are always adjacent.]
]
[
[No equivalent]
[Local iterators can be used to iterate through individual buckets.
(The order of local iterators and iterators aren't
required to have any correspondence.)]
]
[
[Can be compared using the `==`, `!=`, `<`, `<=`, `>`, `>=` operators.]
[Can be compared using the `==` and `!=` operators.]
]
[
[]
[When inserting with a hint, implementations are permitted to ignore
the hint.]
]
[
[`erase` never throws an exception]
[The containers' hash or predicate function can throw exceptions
from `erase`]
]
]
[table:complexity_guarantees Complexity Guarantees
[[Operation] [Associative Containers] [Unordered Associative Containers]]
[
[Construction of empty container]
[constant]
[O(/n/) where /n/ is the minimum number of buckets.]
]
[
[Construction of container from a range of /N/ elements]
[O(/N/ log /N/), O(/N/) if the range is sorted with `value_comp()`]
[Average case O(/N/), worst case
O(/N/'''<superscript>2</superscript>''')]
]
[
[Insert a single element]
[logarithmic]
[Average case constant, worst case linear]
]
[
[Insert a single element with a hint]
[Amortized constant if t elements inserted right after hint,
logarithmic otherwise]
[Average case constant, worst case linear (ie. the same as
a normal insert).]
]
[
[Inserting a range of /N/ elements]
[ /N/ log(`size()`+/N/) ]
[Average case O(/N/), worst case O(/N/ * `size()`)]
]
[
[Erase by key, `k`]
[O(log(`size()`) + `count(k)`)]
[Average case: O(`count(k)`), Worst case: O(`size()`)]
]
[
[Erase a single element by iterator]
[Amortized constant]
[Average case: O(1), Worst case: O(`size()`)]
]
[
[Erase a range of /N/ elements]
[O(log(`size()`) + /N/)]
[Average case: O(/N/), Worst case: O(`size()`)]
]
[
[Clearing the container]
[O(`size()`)]
[O(`size()`)]
]
[
[Find]
[logarithmic]
[Average case: O(1), Worst case: O(`size()`)]
]
[/ TODO: Average case is probably wrong. ]
[
[Count]
[O(log(`size()`) + `count(k)`)]
[Average case: O(1), Worst case: O(`size()`)]
]
[
[`equal_range(k)`]
[logarithmic]
[Average case: O(`count(k)`), Worst case: O(`size()`)]
]
[
[`lower_bound`,`upper_bound`]
[logarithmic]
[n/a]
]
]
[endsect]

128
doc/compliance.qbk
View File

@ -1,128 +0,0 @@
[/ Copyright 2011 Daniel James.
/ 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) ]
[section:compliance Standard Compliance]
The intent of Boost.Unordered is to implement a close (but imperfect)
implementation of the C++17 standard, that will work with C++98 upwards.
The wide compatibility does mean some comprimises have to be made.
With a compiler and library that fully support C++11, the differences should
be minor.
[section:move Move emulation]
Support for move semantics is implemented using Boost.Move. If rvalue
references are available it will use them, but if not it uses a close,
but imperfect emulation. On such compilers:
* Non-copyable objects can be stored in the containers.
They can be constructed in place using `emplace`, or if they support
Boost.Move, moved into place.
* The containers themselves are not movable.
* Argument forwarding is not perfect.
[endsect]
[section:allocator_compliance Use of allocators]
C++11 introduced a new allocator system. It's backwards compatible due to
the lax requirements for allocators in the old standard, but might need
some changes for allocators which worked with the old versions of the
unordered containers.
It uses a traits class, `allocator_traits` to handle the allocator
adding extra functionality, and making some methods and types optional.
During development a stable release of
`allocator_traits` wasn't available so an internal partial implementation
is always used in this version. Hopefully a future version will use the
standard implementation where available.
The member functions `construct`, `destroy` and `max_size` are now
optional, if they're not available a fallback is used.
A full implementation of `allocator_traits` requires sophisticated
member function detection so that the fallback is used whenever the
member function call is not well formed.
This requires support for SFINAE expressions, which are available on
GCC from version 4.4 and Clang.
On other compilers, there's just a test to see if the allocator has
a member, but no check that it can be called. So rather than using a
fallback there will just be a compile error.
`propagate_on_container_copy_assignment`,
`propagate_on_container_move_assignment`,
`propagate_on_container_swap` and
`select_on_container_copy_construction` are also supported.
Due to imperfect move emulation, some assignments might check
`propagate_on_container_copy_assignment` on some compilers and
`propagate_on_container_move_assignment` on others.
[endsect]
[section:construction Construction/Destruction using allocators]
The following support is required for full use of C++11 style
construction/destruction:
* Variadic templates.
* Piecewise construction of `std::pair`.
* Either `std::allocator_traits` or expression SFINAE.
This is detected using Boost.Config. The macro
`BOOST_UNORDERED_CXX11_CONSTRUCTION` will be set to 1 if it is found, or 0
otherwise.
When this is the case `allocator_traits::construct` and
`allocator_traits::destroy` will always be used, apart from when piecewise
constructing a `std::pair` using `boost::tuple` (see [link
unordered.compliance.pairs below]), but that should be easily avoided.
When support is not available `allocator_traits::construct` and
`allocator_traits::destroy` are never called.
[endsect]
[section:pointer_traits Pointer Traits]
`pointer_traits` aren't used. Instead, pointer types are obtained from
rebound allocators, this can cause problems if the allocator can't be
used with incomplete types. If `const_pointer` is not defined in the
allocator, `boost::pointer_to_other<pointer, const value_type>::type`
is used to obtain a const pointer.
[endsect]
[#unordered.compliance.pairs]
[section:pairs Pairs]
Since the containers use `std::pair` they're limited to the version
from the current standard library. But since C++11 `std::pair`'s
`piecewise_construct` based constructor is very useful, `emplace`
emulates it with a `piecewise_construct` in the `boost::unordered`
namespace. So for example, the following will work:
boost::unordered_multimap<std::string, std::complex> x;
x.emplace(
boost::unordered::piecewise_construct,
boost::make_tuple("key"), boost::make_tuple(1, 2));
Older drafts of the standard also supported variadic constructors
for `std::pair`, where the first argument would be used for the
first part of the pair, and the remaining for the second part.
[endsect]
[section:misc Miscellaneous]
When swapping, `Pred` and `Hash` are not currently swapped by calling
`swap`, their copy constructors are used. As a consequence when swapping
an exception may be thrown from their copy constructor.
Variadic constructor arguments for `emplace` are only used when both
rvalue references and variadic template parameters are available.
Otherwise `emplace` can only take up to 10 constructors arguments.
[endsect]
[endsect]

313
doc/diagrams/buckets.svg
View File

@ -1,313 +0,0 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
version="1.0"
width="507.85925"
height="400.45422"
viewBox="1.33 0.95 6.01 4.09"
id="svg2">
<defs
id="defs95" />
<rect
width="6.0023117"
height="4.0815721"
x="1.3310578"
y="0.95080346"
id="rect4"
style="fill:#e5e5e5;stroke:none;stroke-width:0" />
<rect
width="6.0023117"
height="4.0815721"
x="1.3310578"
y="0.95080346"
id="rect6"
style="opacity:1;fill:none;stroke:#000000;stroke-width:0.02400924" />
<rect
width="1.2004625"
height="1.6806473"
x="1.5711501"
y="1.1908962"
id="rect8"
style="fill:#ffffff;stroke:none;stroke-width:0" />
<rect
width="1.2004625"
height="1.6806473"
x="1.5711501"
y="1.1908962"
id="rect10"
style="fill:none;stroke:#000000;stroke-width:0.02400924" />
<text
x="1.7289008"
y="1.4950322"
id="text12"
style="font-size:0.19207397px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Bucket 1</text>
<line
x1="1.5711501"
y1="1.6710808"
x2="2.7716124"
y2="1.6710808"
id="line14"
style="stroke:#000000;stroke-width:0.02400924" />
<rect
width="1.2004625"
height="1.6806473"
x="3.0117054"
y="1.1908962"
id="rect16"
style="fill:#ffffff;stroke:none;stroke-width:0" />
<rect
width="1.2004625"
height="1.6806473"
x="3.0117054"
y="1.1908962"
id="rect18"
style="fill:none;stroke:#000000;stroke-width:0.02400924" />
<text
x="3.1603069"
y="1.4950322"
id="text20"
style="font-size:0.19207397px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Bucket 2</text>
<line
x1="3.0117054"
y1="1.6710808"
x2="4.2121677"
y2="1.6710808"
id="line22"
style="stroke:#000000;stroke-width:0.02400924" />
<rect
width="1.2004625"
height="1.6806473"
x="4.4522605"
y="1.1908962"
id="rect24"
style="fill:#ffffff;stroke:none;stroke-width:0" />
<rect
width="1.2004625"
height="1.6806473"
x="4.4522605"
y="1.1908962"
id="rect26"
style="fill:none;stroke:#000000;stroke-width:0.02400924" />
<text
x="4.5917125"
y="1.4950322"
id="text28"
style="font-size:0.19207397px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Bucket 3</text>
<line
x1="4.4522605"
y1="1.6710808"
x2="5.6527228"
y2="1.6710808"
id="line30"
style="stroke:#000000;stroke-width:0.02400924" />
<rect
width="1.2004625"
height="1.6806473"
x="5.8928151"
y="1.1908962"
id="rect32"
style="fill:#ffffff;stroke:none;stroke-width:0" />
<rect
width="1.2004625"
height="1.6806473"
x="5.8928151"
y="1.1908962"
id="rect34"
style="fill:none;stroke:#000000;stroke-width:0.02400924" />
<text
x="6.0688629"
y="1.4858831"
id="text36"
style="font-size:0.19207397px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Bucket 4</text>
<line
x1="5.8928151"
y1="1.6710808"
x2="7.093277"
y2="1.6710808"
id="line38"
style="stroke:#000000;stroke-width:0.02400924" />
<rect
width="1.2004625"
height="1.6806473"
x="2.2941716"
y="3.1054616"
id="rect40"
style="fill:#ffffff;stroke:none;stroke-width:0" />
<rect
width="1.2004625"
height="1.6806473"
x="2.2941716"
y="3.1054616"
id="rect42"
style="fill:none;stroke:#000000;stroke-width:0.02400924" />
<text
x="2.4427731"
y="3.4187472"
id="text44"
style="font-size:0.19207397px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Bucket 5</text>
<line
x1="2.2941716"
y1="3.5856469"
x2="3.4946339"
y2="3.5856469"
id="line46"
style="stroke:#000000;stroke-width:0.02400924" />
<rect
width="1.2004625"
height="1.6806473"
x="3.7347264"
y="3.1054616"
id="rect48"
style="fill:#ffffff;stroke:none;stroke-width:0" />
<rect
width="1.2004625"
height="1.6806473"
x="3.7347264"
y="3.1054616"
id="rect50"
style="fill:none;stroke:#000000;stroke-width:0.02400924" />
<text
x="3.8833277"
y="3.4187472"
id="text52"
style="font-size:0.19207397px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Bucket 6</text>
<line
x1="3.7347264"
y1="3.5856469"
x2="4.9351892"
y2="3.5856469"
id="line54"
style="stroke:#000000;stroke-width:0.02400924" />
<rect
width="1.2004625"
height="1.6806473"
x="5.175281"
y="3.1054616"
id="rect56"
style="fill:#ffffff;stroke:none;stroke-width:0" />
<rect
width="1.2004625"
height="1.6806473"
x="5.175281"
y="3.1054616"
id="rect58"
style="fill:none;stroke:#000000;stroke-width:0.02400924" />
<text
x="5.3330317"
y="3.4187472"
id="text60"
style="font-size:0.19207397px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Bucket 7</text>
<line
x1="5.175281"
y1="3.5856469"
x2="6.3757439"
y2="3.5856469"
id="line62"
style="stroke:#000000;stroke-width:0.02400924" />
<ellipse
cx="7.1999998"
cy="4.0110002"
rx="0.308"
ry="0.308"
transform="matrix(0.6859785,0,0,0.6859785,1.3310577,-0.7298436)"
id="ellipse64"
style="fill:#ffffff;stroke:none" />
<ellipse
cx="7.1999998"
cy="4.0110002"
rx="0.308"
ry="0.308"
transform="matrix(0.6859785,0,0,0.6859785,1.3310577,-0.7298436)"
id="ellipse66"
style="fill:none;stroke:#000000;stroke-width:0.035" />
<text
x="6.1443377"
y="2.1364057"
id="text68"
style="font-size:0.34038281px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#000000;font-family:Sans;-inkscape-font-specification:Sans">A</text>
<ellipse
cx="3.007"
cy="4.0300002"
rx="0.308"
ry="0.308"
transform="matrix(0.6859785,0,0,0.6859785,1.3310577,-0.7298436)"
id="ellipse70"
style="fill:#ffffff;stroke:none" />
<ellipse
cx="3.007"
cy="4.0300002"
rx="0.308"
ry="0.308"
transform="matrix(0.6859785,0,0,0.6859785,1.3310577,-0.7298436)"
id="ellipse72"
style="fill:none;stroke:#000000;stroke-width:0.035" />
<text
x="3.2742035"
y="2.1540098"
id="text74"
style="font-size:0.34038281px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#000000;font-family:Sans;-inkscape-font-specification:Sans">B</text>
<ellipse
cx="4.0599999"
cy="6.7820001"
rx="0.308"
ry="0.308"
transform="matrix(0.6859785,0,0,0.6859785,1.3310577,-0.7298436)"
id="ellipse76"
style="fill:#ffffff;stroke:none" />
<ellipse
cx="4.0599999"
cy="6.7820001"
rx="0.308"
ry="0.308"
transform="matrix(0.6859785,0,0,0.6859785,1.3310577,-0.7298436)"
id="ellipse78"
style="fill:none;stroke:#000000;stroke-width:0.035" />
<text
x="3.976877"
y="4.0473108"
id="text80"
style="font-size:0.34038281px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#000000;font-family:Sans;-inkscape-font-specification:Sans">C</text>
<ellipse
cx="7.8449998"
cy="4.6550002"
rx="0.308"
ry="0.308"
transform="matrix(0.6859785,0,0,0.6859785,1.3310577,-0.7298436)"
id="ellipse82"
style="fill:#ffffff;stroke:none" />
<ellipse
cx="7.8449998"
cy="4.6550002"
rx="0.308"
ry="0.308"
transform="matrix(0.6859785,0,0,0.6859785,1.3310577,-0.7298436)"
id="ellipse84"
style="fill:none;stroke:#000000;stroke-width:0.035" />
<text
x="6.5808516"
y="2.5937216"
id="text86"
style="font-size:0.34038281px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#000000;font-family:Sans;-inkscape-font-specification:Sans">D</text>
<ellipse
cx="0.87"
cy="4.0079999"
rx="0.308"
ry="0.308"
transform="matrix(0.6859785,0,0,0.6859785,1.3310577,-0.7298436)"
id="ellipse88"
style="fill:#ffffff;stroke:none" />
<ellipse
cx="0.87"
cy="4.0079999"
rx="0.308"
ry="0.308"
transform="matrix(0.6859785,0,0,0.6859785,1.3310577,-0.7298436)"
id="ellipse90"
style="fill:none;stroke:#000000;stroke-width:0.035" />
<text
x="1.7991183"
y="2.1403852"
id="text92"
style="font-size:0.34038281px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#000000;font-family:Sans;-inkscape-font-specification:Sans">E</text>
</svg>
Side by Side

Before

Width:  |  Height:  |  Size: 9.1 KiB

86
doc/hash_equality.qbk
View File

@ -1,86 +0,0 @@
[/ Copyright 2006-2008 Daniel James.
/ 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) ]
[section:hash_equality Equality Predicates and Hash Functions]
While the associative containers use an ordering relation to specify how the
elements are stored, the unordered associative containers use an equality
predicate and a hash function. For example, [classref boost::unordered_map]
is declared as:
template <
class Key, class Mapped,
class Hash = ``[classref boost::hash]``<Key>,
class Pred = std::equal_to<Key>,
class Alloc = std::allocator<std::pair<Key const, Mapped> > >
class ``[classref boost::unordered_map unordered_map]``;
The hash function comes first as you might want to change the hash function
but not the equality predicate. For example, if you wanted to use the
[@http://www.isthe.com/chongo/tech/comp/fnv/ FNV-1 hash] you could write:
[import src_code/dictionary.cpp]
[case_sensitive_dictionary_fnv]
There is an [@boost:/libs/unordered/examples/fnv1.hpp implementation
of FNV-1] in the examples directory.
If you wish to use a different equality function,
you will also need to use a matching hash function. For
example, to implement a case insensitive dictionary you need to define a
case insensitive equality predicate and hash function:
[case_insensitive_functions]
Which you can then use in a case insensitive dictionary:
[case_insensitive_dictionary]
This is a simplified version of the example at
[@boost:/libs/unordered/examples/case_insensitive.hpp /libs/unordered/examples/case_insensitive.hpp]
which supports other locales and string types.
[caution
Be careful when using the equality (`==`) operator with custom equality
predicates, especially if you're using a function pointer. If you compare two
containers with different equality predicates then the result is undefined.
For most stateless function objects this is impossible - since you can only
compare objects with the same equality predicate you know the equality
predicates must be equal. But if you're using function pointers or a stateful
equality predicate (e.g. boost::function) then you can get into trouble.
]
[h2 Custom Types]
Similarly, a custom hash function can be used for custom types:
[import src_code/point1.cpp]
[point_example1]
Since the default hash function is [link hash Boost.Hash],
we can [link hash.custom extend it to support the type]
so that the hash function doesn't need to be explicitly given:
[import src_code/point2.cpp]
[point_example2]
See the [link hash.custom Boost.Hash documentation] for more detail on how to
do this. Remember that it relies on extensions to the draft standard - so it
won't work for other implementations of the unordered associative containers,
you'll need to explicitly use Boost.Hash.
[table:access_methods Methods for accessing the hash and equality functions.
[[Method] [Description]]
[
[`hasher hash_function() const`]
[Returns the container's hash function.]
]
[
[`key_equal key_eq() const`]
[Returns the container's key equality function.]
]
]
[endsect]

101
doc/intro.qbk
View File

@ -1,101 +0,0 @@
[/ Copyright 2006-2008 Daniel James.
/ 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) ]
[def __hash-table__ [@http://en.wikipedia.org/wiki/Hash_table
hash table]]
[def __hash-function__ [@http://en.wikipedia.org/wiki/Hash_function
hash function]]
[section:intro Introduction]
For accessing data based on key lookup, the C++ standard library offers `std::set`,
`std::map`, `std::multiset` and `std::multimap`. These are generally
implemented using balanced binary trees so that lookup time has
logarithmic complexity. That is generally okay, but in many cases a
__hash-table__ can perform better, as accessing data has constant complexity,
on average. The worst case complexity is linear, but that occurs rarely and
with some care, can be avoided.
Also, the existing containers require a 'less than' comparison object
to order their elements. For some data types this is impossible to implement
or isn't practical. In contrast, a hash table only needs an equality function
and a hash function for the key.
With this in mind, unordered associative containers were added to the C++
standard. This is an implementation of the containers described in C++11,
with some [link unordered.compliance deviations from the standard] in
order to work with non-C++11 compilers and libraries.
`unordered_set` and `unordered_multiset` are defined in the header
<[headerref boost/unordered_set.hpp]>
namespace boost {
template <
class Key,
class Hash = ``[classref boost::hash]``<Key>,
class Pred = std::equal_to<Key>,
class Alloc = std::allocator<Key> >
class ``[classref boost::unordered_set unordered_set]``;
template<
class Key,
class Hash = ``[classref boost::hash]``<Key>,
class Pred = std::equal_to<Key>,
class Alloc = std::allocator<Key> >
class ``[classref boost::unordered_multiset unordered_multiset]``;
}
`unordered_map` and `unordered_multimap` are defined in the header
<[headerref boost/unordered_map.hpp]>
namespace boost {
template <
class Key, class Mapped,
class Hash = ``[classref boost::hash]``<Key>,
class Pred = std::equal_to<Key>,
class Alloc = std::allocator<std::pair<Key const, Mapped> > >
class ``[classref boost::unordered_map unordered_map]``;
template<
class Key, class Mapped,
class Hash = ``[classref boost::hash]``<Key>,
class Pred = std::equal_to<Key>,
class Alloc = std::allocator<std::pair<Key const, Mapped> > >
class ``[classref boost::unordered_multimap unordered_multimap]``;
}
When using Boost.TR1, these classes are included from `<unordered_set>` and
`<unordered_map>`, with the classes added to the `std::tr1` namespace.
The containers are used in a similar manner to the normal associative
containers:
[import src_code/intro.cpp]
[intro_example1_2]
But since the elements aren't ordered, the output of:
[intro_example1_3]
can be in any order. For example, it might be:
two,2
one,1
three,3
To store an object in an unordered associative container requires both a
key equality function and a hash function. The default function objects in
the standard containers support a few basic types including integer types,
floating point types, pointer types, and the standard strings. Since
Boost.Unordered uses [classref boost::hash] it also supports some other types,
including standard containers. To use any types not supported by these methods
you have to [link hash.custom extend Boost.Hash to support the type] or use
your own custom equality predicates and hash functions. See the
[link unordered.hash_equality Equality Predicates and Hash Functions] section
for more details.
There are other differences, which are listed in the
[link unordered.comparison Comparison with Associative Containers] section.
[endsect]

111
doc/rationale.qbk
View File

@ -1,111 +0,0 @@
[/ Copyright 2006-2008 Daniel James.
/ 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) ]
[def __wang__
[@http://web.archive.org/web/20121102023700/http://www.concentric.net/~Ttwang/tech/inthash.htm
Thomas Wang's article on integer hash functions]]
[section:rationale Implementation Rationale]
The intent of this library is to implement the unordered
containers in the draft standard, so the interface was fixed. But there are
still some implementation decisions to make. The priorities are
conformance to the standard and portability.
The [@http://en.wikipedia.org/wiki/Hash_table Wikipedia article on hash tables]
has a good summary of the implementation issues for hash tables in general.
[h2 Data Structure]
By specifying an interface for accessing the buckets of the container the
standard pretty much requires that the hash table uses chained addressing.
It would be conceivable to write a hash table that uses another method. For
example, it could use open addressing, and use the lookup chain to act as a
bucket but there are some serious problems with this:
* The draft standard requires that pointers to elements aren't invalidated, so
the elements can't be stored in one array, but will need a layer of
indirection instead - losing the efficiency and most of the memory gain,
the main advantages of open addressing.
* Local iterators would be very inefficient and may not be able to
meet the complexity requirements.
* There are also the restrictions on when iterators can be invalidated. Since
open addressing degrades badly when there are a high number of collisions the
restrictions could prevent a rehash when it's really needed. The maximum load
factor could be set to a fairly low value to work around this - but the
standard requires that it is initially set to 1.0.
* And since the standard is written with a eye towards chained
addressing, users will be surprised if the performance doesn't reflect that.
So chained addressing is used.
[/ (Removing for now as this is out of date)
For containers with unique keys I store the buckets in a single-linked list.
There are other possible data structures (such as a double-linked list)
that allow for some operations to be faster (such as erasing and iteration)
but the possible gain seems small compared to the extra memory needed.
The most commonly used operations (insertion and lookup) would not be improved
at all.
But for containers with equivalent keys a single-linked list can degrade badly
when a large number of elements with equivalent keys are inserted. I think it's
reasonable to assume that users who choose to use `unordered_multiset` or
`unordered_multimap` do so because they are likely to insert elements with
equivalent keys. So I have used an alternative data structure that doesn't
degrade, at the expense of an extra pointer per node.
This works by adding storing a circular linked list for each group of equivalent
nodes in reverse order. This allows quick navigation to the end of a group (since
the first element points to the last) and can be quickly updated when elements
are inserted or erased. The main disadvantage of this approach is some hairy code
for erasing elements.
]
[/ (Starting to write up new structure, might not be ready in time)
The node used to be stored in a linked list for each bucket but that
didn't meet the complexity requirements for C++11, so now the nodes
are stored in one long single linked list. But there needs a way to get
the bucket from the node, to do that a copy of the key's hash value is
stored in the node. Another possibility would be to store a pointer to
the bucket, or the bucket's index, but storing the hash value allows
some operations to be faster.
]
[h2 Number of Buckets]
There are two popular methods for choosing the number of buckets in a hash
table. One is to have a prime number of buckets, another is to use a power
of 2.
Using a prime number of buckets, and choosing a bucket by using the modulus
of the hash function's result will usually give a good result. The downside
is that the required modulus operation is fairly expensive. This is what the
containers do in most cases.
Using a power of 2 allows for much quicker selection of the bucket
to use, but at the expense of losing the upper bits of the hash value.
For some specially designed hash functions it is possible to do this and
still get a good result but as the containers can take arbitrary hash
functions this can't be relied on.
To avoid this a transformation could be applied to the hash function, for an
example see __wang__. Unfortunately, a transformation like Wang's requires
knowledge of the number of bits in the hash value, so it isn't portable enough
to use as a default. It can applicable in certain cases so the containers
have a policy based implementation that can use this alternative technique.
Currently this is only done on 64 bit architectures, where prime number
modulus can be expensive. Although this varies depending on the architecture,
so I probably should revisit it.
I'm also thinking of introducing a mechanism whereby a hash function can
indicate that it's safe to be used directly with power of 2 buckets, in
which case a faster plain power of 2 implementation can be used.
[endsect]

1962
doc/ref.php
View File

File diff suppressed because it is too large Load Diff

6585
doc/ref.xml
View File

File diff suppressed because it is too large Load Diff

101
doc/src_code/dictionary.cpp
View File

@ -1,101 +0,0 @@
// Copyright 2006-2007 Daniel James.
// 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)
#include <boost/unordered_map.hpp>
#include <boost/core/lightweight_test.hpp>
#include <boost/algorithm/string/predicate.hpp>
#include "../../examples/fnv1.hpp"
//[case_insensitive_functions
struct iequal_to
{
bool operator()(std::string const& x,
std::string const& y) const
{
return boost::algorithm::iequals(x, y, std::locale());
}
};
struct ihash
{
std::size_t operator()(std::string const& x) const
{
std::size_t seed = 0;
std::locale locale;
for(std::string::const_iterator it = x.begin();
it != x.end(); ++it)
{
boost::hash_combine(seed, std::toupper(*it, locale));
}
return seed;
}
};
//]
int main() {
//[case_sensitive_dictionary_fnv
boost::unordered_map<std::string, int, hash::fnv_1>
dictionary;
//]
BOOST_TEST(dictionary.empty());
dictionary["one"] = 1;
BOOST_TEST(dictionary.size() == 1);
BOOST_TEST(dictionary.find("ONE") == dictionary.end());
dictionary.insert(std::make_pair("ONE", 2));
BOOST_TEST(dictionary.size() == 2);
BOOST_TEST(dictionary.find("ONE") != dictionary.end() &&
dictionary.find("ONE")->first == "ONE" &&
dictionary.find("ONE")->second == 2);
dictionary["One"] = 3;
BOOST_TEST(dictionary.size() == 3);
BOOST_TEST(dictionary.find("One") != dictionary.end() &&
dictionary.find("One")->first == "One" &&
dictionary.find("One")->second == 3);
dictionary["two"] = 4;
BOOST_TEST(dictionary.size() == 4);
BOOST_TEST(dictionary.find("Two") == dictionary.end() &&
dictionary.find("two") != dictionary.end() &&
dictionary.find("two")->second == 4);
//[case_insensitive_dictionary
boost::unordered_map<std::string, int, ihash, iequal_to>
idictionary;
//]
BOOST_TEST(idictionary.empty());
idictionary["one"] = 1;
BOOST_TEST(idictionary.size() == 1);
BOOST_TEST(idictionary.find("ONE") != idictionary.end() &&
idictionary.find("ONE") == idictionary.find("one"));
idictionary.insert(std::make_pair("ONE", 2));
BOOST_TEST(idictionary.size() == 1);
BOOST_TEST(idictionary.find("ONE") != idictionary.end() &&
idictionary.find("ONE")->first == "one" &&
idictionary.find("ONE")->second == 1);
idictionary["One"] = 3;
BOOST_TEST(idictionary.size() == 1);
BOOST_TEST(idictionary.find("ONE") != idictionary.end() &&
idictionary.find("ONE")->first == "one" &&
idictionary.find("ONE")->second == 3);
idictionary["two"] = 4;
BOOST_TEST(idictionary.size() == 2);
BOOST_TEST(idictionary.find("two") != idictionary.end() &&
idictionary.find("TWO")->first == "two" &&
idictionary.find("Two")->second == 4);
return boost::report_errors();
}

30
doc/src_code/intro.cpp
View File

@ -1,30 +0,0 @@
// Copyright 2006-2009 Daniel James.
// 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)
//[intro_example1_1
#include <boost/unordered_map.hpp>
#include <boost/foreach.hpp>
#include <cassert>
#include <iostream>
//]
int main() {
//[intro_example1_2
typedef boost::unordered_map<std::string, int> map;
map x;
x["one"] = 1;
x["two"] = 2;
x["three"] = 3;
assert(x.at("one") == 1);
assert(x.find("missing") == x.end());
//]
//[intro_example1_3
BOOST_FOREACH(map::value_type i, x) {
std::cout<<i.first<<","<<i.second<<"\n";
}
//]
}

44
doc/src_code/point1.cpp
View File

@ -1,44 +0,0 @@
// Copyright 2006-2009 Daniel James.
// 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)
#include <boost/unordered_set.hpp>
#include <boost/core/lightweight_test.hpp>
//[point_example1
struct point {
int x;
int y;
};
bool operator==(point const& p1, point const& p2)
{
return p1.x == p2.x && p1.y == p2.y;
}
struct point_hash
{
std::size_t operator()(point const& p) const
{
std::size_t seed = 0;
boost::hash_combine(seed, p.x);
boost::hash_combine(seed, p.y);
return seed;
}
};
boost::unordered_multiset<point, point_hash> points;
//]
int main() {
point x[] = {{1,2}, {3,4}, {1,5}, {1,2}};
for(int i = 0; i < sizeof(x) / sizeof(point); ++i)
points.insert(x[i]);
BOOST_TEST(points.count(x[0]) == 2);
BOOST_TEST(points.count(x[1]) == 1);
point y = {10, 2};
BOOST_TEST(points.count(y) == 0);
return boost::report_errors();
}

43
doc/src_code/point2.cpp
View File

@ -1,43 +0,0 @@
// Copyright 2006-2009 Daniel James.
// 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)
#include <boost/unordered_set.hpp>
#include <boost/functional/hash.hpp>
#include <boost/core/lightweight_test.hpp>
//[point_example2
struct point {
int x;
int y;
};
bool operator==(point const& p1, point const& p2)
{
return p1.x == p2.x && p1.y == p2.y;
}
std::size_t hash_value(point const& p) {
std::size_t seed = 0;
boost::hash_combine(seed, p.x);
boost::hash_combine(seed, p.y);
return seed;
}
// Now the default function objects work.
boost::unordered_multiset<point> points;
//]
int main() {
point x[] = {{1,2}, {3,4}, {1,5}, {1,2}};
for(int i = 0; i < sizeof(x) / sizeof(point); ++i)
points.insert(x[i]);
BOOST_TEST(points.count(x[0]) == 2);
BOOST_TEST(points.count(x[1]) == 1);
point y = {10, 2};
BOOST_TEST(points.count(y) == 0);
return boost::report_errors();
}

39
doc/unordered.qbk
View File

@ -1,39 +0,0 @@
[/ Copyright 2006-2008 Daniel James.
/ 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) ]
[library Boost.Unordered
[quickbook 1.7]
[compatibility-mode 1.5]
[authors [James, Daniel]]
[copyright 2003 2004 Jeremy B. Maitin-Shepard]
[copyright 2005 2006 2007 2008 Daniel James]
[purpose std::tr1 compliant hash containers]
[id unordered]
[dirname unordered]
[license
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])
]
]
[template diagram[name] '''<inlinemediaobject>
<imageobject role="html">
<imagedata align = "center" fileref="../../libs/unordered/doc/diagrams/'''[name]'''.png"></imagedata>
</imageobject>
<imageobject role="print">
<imagedata align = "center" fileref="../../libs/unordered/doc/diagrams/'''[name]'''.svg"></imagedata>
</imageobject>
</inlinemediaobject>''']
[include:unordered intro.qbk]
[include:unordered buckets.qbk]
[include:unordered hash_equality.qbk]
[include:unordered comparison.qbk]
[include:unordered compliance.qbk]
[include:unordered rationale.qbk]
[include:unordered changes.qbk]
[xinclude ref.xml]
[xinclude bibliography.xml]