Merged revisions 41808-41821,41823-41927,41934-41942,41944-41950,41952-41993,41998-42091,42094-42095,42104-42105,42107,42109,42111-42152,42154,42160-42171,42173-42180,42183-42196,42198-42402 via svnmerge from

https://svn.boost.org/svn/boost/branches/unordered/dev

........
  r41993 | danieljames | 2007-12-13 00:23:27 +0000 (Thu, 13 Dec 2007) | 3 lines
  
  Add the hash documentation to the unordered library so that it'll be easier to
  link between the libraries.
........
  r42104 | danieljames | 2007-12-16 13:36:50 +0000 (Sun, 16 Dec 2007) | 1 line
  
  Don't include any hash source in tarballs (although I'm including the documentation).
........
  r42198 | danieljames | 2007-12-20 10:49:10 +0000 (Thu, 20 Dec 2007) | 1 line
  
  Restore the extra warnings in the unit tests.
........
  r42199 | danieljames | 2007-12-20 11:25:38 +0000 (Thu, 20 Dec 2007) | 1 line
  
  Make a cast explicit in order to avoid a warning.
........
  r42203 | danieljames | 2007-12-20 15:54:31 +0000 (Thu, 20 Dec 2007) | 1 line
  
  Use 'BOOST_UNORDERED' prefix for macros.
........
  r42209 | danieljames | 2007-12-20 19:41:17 +0000 (Thu, 20 Dec 2007) | 1 line
  
  Initialise this branch (hopefully..)
........
  r42210 | danieljames | 2007-12-20 19:51:21 +0000 (Thu, 20 Dec 2007) | 1 line
  
  Merge in changes.
........
  r42215 | danieljames | 2007-12-20 21:15:42 +0000 (Thu, 20 Dec 2007) | 1 line
  
  Don't add size_type to pointers, cast to difference_type.
........
  r42216 | danieljames | 2007-12-20 21:17:38 +0000 (Thu, 20 Dec 2007) | 1 line
  
  I messed up the last commit, this fixes it.
........
  r42218 | danieljames | 2007-12-20 21:22:20 +0000 (Thu, 20 Dec 2007) | 1 line
  
  Get rid of last_in_group.
........
  r42219 | danieljames | 2007-12-20 21:27:46 +0000 (Thu, 20 Dec 2007) | 1 line
  
  Use node_count to implement group_count.
........
  r42231 | danieljames | 2007-12-21 12:04:52 +0000 (Fri, 21 Dec 2007) | 1 line
  
  Some minor changes for Visual C++.
........
  r42233 | danieljames | 2007-12-21 19:41:27 +0000 (Fri, 21 Dec 2007) | 1 line
  
  Inline some more methods.
........
  r42335 | danieljames | 2007-12-29 13:14:45 +0000 (Sat, 29 Dec 2007) | 3 lines
  
  Some of the changes to the introduction mention in the review. Hopefully this
  will make it a little clearer.
........
  r42336 | danieljames | 2007-12-29 13:16:55 +0000 (Sat, 29 Dec 2007) | 3 lines
  
  Try to make the buckets explanation a little easier to read. Most of the
  changes were based on Jamie Allsop (same for the last commit).
........
  r42339 | danieljames | 2007-12-29 16:00:32 +0000 (Sat, 29 Dec 2007) | 1 line
  
  Specify the namespace for 'std::out_of_range' in the reference documentation.
........
  r42345 | danieljames | 2007-12-29 20:41:10 +0000 (Sat, 29 Dec 2007) | 8 lines
  
  Rewrite much of the 'controlling the number of buckets' section.
  
  I'm trying to make it clearer. It's a bit tricky as the standard doesn't guarantee much.
  Instead of diving straight into the details I have tried to give the reader a rough
  idea of what 'rehash' does and what the load factor is. This is hopefully enough to
  understand the more detailled discussion of how you can control the number of buckets.
  Then finally I discuss iterator invalidation.
........
  r42346 | danieljames | 2007-12-29 20:52:22 +0000 (Sat, 29 Dec 2007) | 1 line
  
  Move the table summarizing methods for controlling bucket size next to the discussion of these methods. The paragraphs about insert and invalidating iterator moves on to something else.
........
  r42348 | danieljames | 2007-12-29 20:55:30 +0000 (Sat, 29 Dec 2007) | 1 line
  
  Fix the badly marked up bullet points.
........
  r42349 | danieljames | 2007-12-29 20:57:53 +0000 (Sat, 29 Dec 2007) | 2 lines
  
  We now have cbegin and cend for local iterators.
........



[SVN r42403]
This commit is contained in:
Daniel James committed 2008-01-01 20:21:04 +00:00
1 parent 184a38fee1
commit e91f6d467b
13 files changed
+190 -171

No files matched your search

+12 -14
View File
@@ -1,17 +1,15 @@
project boost/doc ;
import boostbook : boostbook ;
# Copyright 2005 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)
boostbook doc : src/boost.xml
:
using quickbook ;
## Build the various generated docs (Doxygen and QuickBook)...
xml unordered : unordered.qbk ;
boostbook standalone : unordered :
<xsl:param>boost.root=../../../..
<xsl:param>boost.libraries=../../../libraries.htm
<xsl:param>html.stylesheet=../../../../doc/html/boostbook.css
<xsl:param>chunk.first.sections=1
<xsl:param>chunk.section.depth=2
<xsl:param>generate.section.toc.level=2
<xsl:param>toc.section.depth=1
<xsl:param>toc.max.depth=1 ;
<dependency>../libs/unordered/doc//unordered
<implicit-dependency>../libs/unordered/doc//unordered
<dependency>../libs/functional/hash/doc//hash
<implicit-dependency>../libs/functional/hash/doc//hash
<xsl:param>boost.libraries=../../libs/libraries.htm
;
+51 -41
View File
@@ -20,17 +20,16 @@ value of type `std::size_t`. `std::size_t` has a much greater range of values
then the number of buckets, so that container applies another transformation to
that value to choose a bucket to place the element in.
If at a later date the container wants to find an element in the container it
just has to apply the same process to the element's key to discover which
bucket it is in. If the hash function has worked well the elements will be
evenly distributed amongst the buckets so it will only have to examine a small
number of elements.
Retreiving 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. 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.
You can see in the diagram that `A` & `D` have been placed in the same bucket.
This means that when looking for these elements, of another element that would
be placed in the same bucket, up to 2 comparison have to be made, making
searching slower. This is known as a collision. To keep things fast we try to
keep these to a minimum.
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 Methods for Accessing Buckets
[[Method] [Description]]
@@ -57,6 +56,8 @@ keep these to a minimum.
local_iterator end(size_type n);
const_local_iterator begin(size_type n) const;
const_local_iterator end(size_type n) const;
const_local_iterator cbegin(size_type n) const;
const_local_iterator cend(size_type n) const;
``]
[Return begin and end iterators for bucket `n`.]
]
@@ -65,42 +66,31 @@ keep these to a minimum.
[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 get worse. To
combat this the containers increase the bucket count as elements are inserted.
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 gives you two methods to influence the bucket count. First you can
specify the minimum number of buckets in the constructor, and later, by calling
`rehash`.
The standard leaves a lot of freedom to the implementor to decide how the
number of buckets are 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.
The other method is the `max_load_factor` member function. The 'load factor'
is the average number of elements per bucket, `max_load_factor` can be used
to give a /hint/ of a value that the load factor should be kept below. 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 probably
try to keep the number of elements below the max load factor, and set the
maximum load factor something the same or near to your hint - unless your hint
is unreasonably small.
You can't control the bucket count directly but there are two ways to
influence it:
It is not specified anywhere 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 reach the maximum. Which will
typically mean that insert will only change the number of buckets when an
insert causes this.
* Specify the minimum number of buckets when constructing a container or
when calling `rehash`.
* Suggest a maximum load factor by calling `max_load_factor`.
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() + 1);
[blurb Note: `rehash`'s argument is the number of buckets, not the number of
elements, which is why the new size is divided by the maximum load factor. The
+ 1 guarantees there is no invalidation; without it, reallocation could occur
if the number of bucket exactly divides the target size, since the container is
allowed to rehash when the load factor is equal to the maximum 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 Methods for Controlling Bucket Size
[[Method] [Description]]
@@ -125,4 +115,24 @@ allowed to rehash when the load factor is equal to the maximum load factor.]
]
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.
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() + 1);
[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. The
`+ 1` guarantees there is no invalidation; without it, reallocation could occur
if the number of bucket exactly divides the target size, since the container is
allowed to rehash when the load factor is equal to the maximum load factor.]
[endsect]
+6 -4
View File
@@ -28,11 +28,12 @@ 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. For a hash table you need an equality function
or isn't practical. In contrast, a hash table only needs an equality function
and a hash function for the key.
So the __tr1__ introduced the unordered associative containers, which are
implemented using hash tables, and they have now been added to the __draft__.
With this in mind, the __tr1__ introduced the unordered associative containers,
which are implemented using hash tables, and they have now been added to the
__draft__.
This library supplies an almost complete implementation of the specification in
the __draft__, (it doesn't support `emplace` yet, see the [link
@@ -110,6 +111,7 @@ can be in any order. For example, it might be:
three,3
missing,0
There are other differences, which will be detailed later.
There are other differences, which are listed in the
[link unordered.comparison Comparison with Associative Containers] section.
[endsect]
+1 -1
View File
@@ -1718,7 +1718,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>A reference to <code>x.second</code> where <code>x</code> is the (unique) element whose key is equivalent to <code>k</code>.</para>
</returns>
<throws>
<para>An exception object of type <code>out_of_range</code> if no such element is present.</para>
<para>An exception object of type <code>std::out_of_range</code> if no such element is present.</para>
</throws>
<notes>
<para>This is not specified in the draft standard, but that is probably an oversight. The issue has been raised in
+1 -1
View File
@@ -5,5 +5,5 @@
<title>The Boost C++ Unordered Containers Library Documentation</title>
<xi:include href="unordered.xml"/>
<!-- <xi:include href="hash.xml"/> -->
<xi:include href="hash.xml"/>
</boostbook>