feedc0de/boost_unordered
1
0
Fork 0
forked from boostorg/unordered
Code Pull Requests Activity

Merge pull request #87 from cmazakas/docs-cleanup

Browse Source 
Docs Cleanup
This commit is contained in:
Peter Dimov
2022-02-10 01:20:52 +02:00
committed by GitHub
parent 13c62043eb 120861bf55
commit 2d6ebf16d8
4 changed files with 49 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
doc/unordered/buckets.adoc
View File

@ -86,7 +86,7 @@ influence it:
* 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
lets you give a _hint_. And even then, the 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
@ -120,23 +120,33 @@ or close to the hint - unless your hint is unreasonably small or large.
== Iterator Invalidation
It is not specified how member functions other than `rehash` affect
It is not specified how member functions other than `rehash` and `reserve` 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
invalidated by calls to `insert`, `rehash` and `reserve`, 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
to call `reserve` 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());
x.reserve(n);
```
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.
Note:: `reserve(n)` reserves space for at least `n` elements, allocating enough buckets
so as to not exceed the maximum load factor.
+
Because the maximum load factor is defined as the number of elements divided by the total
number of available buckets, this function is logically equivalent to:
+
```
x.rehash(std::ceil(n / x.max_load_factor()))
```
+
See the <<unordered_map_rehash,reference for more details>> on the `rehash` function.

57
doc/unordered/changes.adoc
View File

@ -6,7 +6,7 @@
:github-pr-url: https://github.com/boostorg/unordered/pull
:cpp: C++
== Changes in Boost 1.79.0
== Release 1.79.0
* Improved {cpp}20 support:
** All containers have been updated to support
@ -20,8 +20,9 @@
* Various warning fixes in the test suite.
* Update code to internally use `boost::allocator_traits`.
* Switch to Fibonacci hashing.
* Update documentation to be written in AsciiDoc instead of QuickBook.
== Changes in Boost 1.67.0
== Release 1.67.0
* Improved {cpp}17 support:
** Add template deduction guides from the standard.
@ -51,12 +52,12 @@
* Various testing improvements.
* Miscellaneous internal changes.
== Changes in Boost 1.66.0
== Release 1.66.0
* Simpler move construction implementation.
* Documentation fixes ({github-pr-url}/6[GitHub #6^]).
== Changes in Boost 1.65.0
== Release 1.65.0
* Add deprecated attributes to `quick_erase` and `erase_return_void`.
I really will remove them in a future version this time.
@ -64,7 +65,7 @@
** `noexpect` specs for `swap` free functions.
** Add missing `insert(P&&)` methods.
== Changes in Boost 1.64.0
== Release 1.64.0
* Initial support for new {cpp}17 member functions:
`insert_or_assign` and `try_emplace` in `unordered_map`,
@ -74,7 +75,7 @@
`unordered_multiset` yet. That will hopefully be in the next version of
Boost.
== Changes in Boost 1.63.0
== Release 1.63.0
* Check hint iterator in `insert`/`emplace_hint`.
* Fix some warnings, mostly in the tests.
@ -98,7 +99,7 @@
arguments, but an off by one error in the preprocessor code meant it only
supported up to 9.
== Changes in Boost 1.62.0
== Release 1.62.0
* Remove use of deprecated `boost::iterator`.
* Remove `BOOST_NO_STD_DISTANCE` workaround.
@ -108,7 +109,7 @@
* Stop using return value SFINAE which some older compilers have issues
with.
== Changes in Boost 1.58.0
== Release 1.58.0
* Remove unnecessary template parameter from const iterators.
* Rename private `iterator` typedef in some iterator classes, as it
@ -119,13 +120,13 @@
* Fix potential overflow when calculating number of buckets to allocate
({github-pr-url}/4[GitHub #4^]).
== Changes in Boost 1.57.0
== Release 1.57.0
* Fix the `pointer` typedef in iterators ({svn-ticket-url}/10672[#10672^]).
* Fix Coverity warning
({github-pr-url}/2[GitHub #2^]).
== Changes in Boost 1.56.0
== Release 1.56.0
* Fix some shadowed variable warnings ({svn-ticket-url}/9377[#9377^]).
* Fix allocator use in documentation ({svn-ticket-url}/9719[#9719^]).
@ -134,7 +135,7 @@
uses slower ({svn-ticket-url}/9282[#9282^]).
* Only construct elements using allocators, as specified in {cpp}11 standard.
== Changes in Boost 1.55.0
== Release 1.55.0
* Avoid some warnings ({svn-ticket-url}/8851[#8851^], {svn-ticket-url}/8874[#8874^]).
* Avoid exposing some detail functions via. ADL on the iterators.
@ -142,14 +143,14 @@
methods to construct and destroy stored elements. Don't use them for internal
data like pointers.
== Changes in Boost 1.54.0
== Release 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.
== Changes in Boost 1.53.0
== Release 1.53.0
* Remove support for the old pre-standard variadic pair constructors, and
equality implementation. Both have been deprecated since Boost 1.48.
@ -157,7 +158,7 @@
* More internal implementation changes, including a much simpler
implementation of `erase`.
== Changes in Boost 1.52.0
== Release 1.52.0
* Faster assign, which assigns to existing nodes where possible, rather than
creating entirely new nodes and copy constructing.
@ -167,7 +168,7 @@
for {cpp}11 allocators.
* Simplified the implementation a bit. Hopefully more robust.
== Changes in Boost 1.51.0
== Release 1.51.0
* Fix construction/destruction issue when using a {cpp}11 compiler with a
{cpp}03 allocator ({svn-ticket-url}/7100[#7100^]).
@ -175,7 +176,7 @@
* Adjust SFINAE use to try to support g++ 3.4 ({svn-ticket-url}/7175[#7175^]).
* Updated to use the new config macros.
== Changes in Boost 1.50.0
== Release 1.50.0
* Fix equality for `unordered_multiset` and `unordered_multimap`.
* {svn-ticket-url}/6857[Ticket 6857^]:
@ -199,12 +200,12 @@
for 64 bit values.
* Some internal changes.
== Changes in Boost 1.49.0
== Release 1.49.0
* Fix warning due to accidental odd assignment.
* Slightly better error messages.
== Changes in Boost 1.48.0 - Major update
== Release 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 {cpp}11 standard. See the
@ -240,12 +241,12 @@ future version.
the variadic constructors define
`BOOST_UNORDERED_DEPRECATED_PAIR_CONSTRUCT`.
== Changes in Boost 1.45.0
== Release 1.45.0
* Fix a bug when inserting into an `unordered_map` or `unordered_set` using
iterators which returns `value_type` by copy.
== Changes in Boost 1.43.0
== Release 1.43.0
* {svn-ticket-url}/3966[Ticket 3966^]:
`erase_return_void` is now `quick_erase`, which is the
@ -257,7 +258,7 @@ future version.
* Use Boost.Exception.
* Stop using deprecated `BOOST_HAS_*` macros.
== Changes in Boost 1.42.0
== Release 1.42.0
* Support instantiating the containers with incomplete value types.
* Reduced the number of warnings (mostly in tests).
@ -271,7 +272,7 @@ future version.
Add missing `std` qualifier to `ptrdiff_t`.
* Some code formatting changes to fit almost all lines into 80 characters.
== Changes in Boost 1.41.0 - Major update
== Release 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
@ -286,7 +287,7 @@ future version.
* Buckets are allocated lazily which means that constructing an empty container
will not allocate any memory.
== Changes in Boost 1.40.0
== Release 1.40.0
* {svn-ticket-url}/2975[Ticket 2975^]:
Store the prime list as a preprocessor sequence - so that it will always get
@ -302,7 +303,7 @@ future version.
* Better configuration for {cpp}0x features when the headers aren't available.
* Create less buckets by default.
== Changes in Boost 1.39.0
== Release 1.39.0
* {svn-ticket-url}/2756[Ticket 2756^]: Avoid a warning
on Visual {cpp} 2009.
@ -312,7 +313,7 @@ future version.
* {svn-ticket-url}/2975[Ticket 2975^]: Fix length of
prime number list.
== Changes in Boost 1.38.0
== Release 1.38.0
* Use link:../../../core/swap.html[`boost::swap`^].
* {svn-ticket-url}/2237[Ticket 2237^]:
@ -332,16 +333,16 @@ future version.
* Add support for {cpp}0x initializer lists where they're available (currently
only g++ 4.4 in {cpp}0x mode).
== Changes in Boost 1.37.0
== Release 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.
modularization and hopefully make it easier to track Release subversion.
== Changes in Boost 1.36.0
== Release 1.36.0
First official release.

2
doc/unordered/hash_equality.adoc
View File

@ -131,7 +131,7 @@ boost::unordered_multiset<point> points;
```
See the link:../../../container_hash/index.html[Boost.Hash documentation^] for more detail on how to
do this. Remember that it relies on extensions to the draft standard - so it
do this. Remember that it relies on extensions to the standard - so it
won't work for other implementations of the unordered associative containers,
you'll need to explicitly use Boost.Hash.

4
doc/unordered/rationale.adoc
View File

@ -5,7 +5,7 @@
= 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
containers in the standard, so the interface was fixed. But there are
still some implementation decisions to make. The priorities are
conformance to the standard and portability.
@ -21,7 +21,7 @@ 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 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.