From 71d3b77668b2879f58b4bbbfc0f8bcb5979bb05e Mon Sep 17 00:00:00 2001 From: Christian Mazakas Date: Thu, 24 Feb 2022 14:54:28 -0800 Subject: [PATCH] Correct reference docs for `merge()` --- doc/unordered/unordered_map.adoc | 41 +++++++++++++++++++-------- doc/unordered/unordered_multimap.adoc | 38 ++++++++++++++++++------- doc/unordered/unordered_multiset.adoc | 38 ++++++++++++++++++------- doc/unordered/unordered_set.adoc | 39 ++++++++++++++++++------- 4 files changed, 111 insertions(+), 45 deletions(-) diff --git a/doc/unordered/unordered_map.adoc b/doc/unordered/unordered_map.adoc index 053657d9..fa1d7803 100644 --- a/doc/unordered/unordered_map.adoc +++ b/doc/unordered/unordered_map.adoc @@ -125,7 +125,11 @@ namespace boost { template void xref:#unordered_map_merge[merge](unordered_map& source); template - void xref:#unordered_map_merge_rvalue_reference[merge](unordered_map&& source); + void xref:#unordered_map_merge[merge](unordered_map&& source); + template + void xref:#unordered_map_merge[merge](unordered_multimap& source); + template + void xref:#unordered_map_merge[merge](unordered_multimap&& source); // observers hasher xref:#unordered_map_hash_function[hash_function]() const; @@ -1084,23 +1088,36 @@ Throws:;; Never throws an exception. ==== merge ```c++ -template -void merge(unordered_map& source); +template + void merge(unordered_map& source); +template + void merge(unordered_map&& source); +template + void merge(unordered_multimap& source); +template + void merge(unordered_multimap&& source); ``` -[horizontal] -Notes:;; Does not support merging with a compatible `unordered_multimap` yet. +Attempt to "merge" two containers by iterating `source` and extracting any node in `source` that is not contained +in `*this` and then inserting it into `*this`. ---- +Because `source` can have a different hash function and key equality predicate, the key of each node in +`source` is rehashed using `this\->hash_function()` and then, if required, compared using `this\->key_eq()`. -==== merge (rvalue reference) -```c++ -template -void merge(unordered_map&& source); -``` +The behavior of this function is undefined if `this\->get_allocator() != source.get_allocator()`. + +This function does not copy or move any elements and instead simply relocates the nodes from `source` +into `*this`. [horizontal] -Notes:;; Does not support merging with a compatible `unordered_multimap` yet. +Notes:;; ++ +-- +* Pointers and references to transferred elements remain valid. +* Invalidates iterators to transferred elements. +* Invalidates iterators belonging to `*this`. +* Iterators to non-transferred elements in `source` remain valid. +-- --- diff --git a/doc/unordered/unordered_multimap.adoc b/doc/unordered/unordered_multimap.adoc index d8eae540..1eb9963c 100644 --- a/doc/unordered/unordered_multimap.adoc +++ b/doc/unordered/unordered_multimap.adoc @@ -126,7 +126,11 @@ namespace boost { template void xref:#unordered_multimap_merge[merge](unordered_multimap& source); template - void xref:#unordered_multimap_merge_rvalue_reference[merge](unordered_multimap&& source); + void xref:#unordered_multimap_merge[merge](unordered_multimap&& source); + template + void xref:#unordered_multimap_merge[merge](unordered_map& source); + template + void xref:#unordered_multimap_merge[merge](unordered_map&& source); // observers hasher xref:#unordered_multimap_hash_function[hash_function]() const; @@ -1055,21 +1059,33 @@ Throws:;; Never throws an exception. ```c++ template void merge(unordered_multimap& source); -``` - -[horizontal] -Notes:;; Does not support merging with a compatible `unordered_map` yet. - ---- - -==== merge (rvalue reference) -```c++ template void merge(unordered_multimap&& source); +template + void merge(unordered_map& source); +template + void merge(unordered_map&& source); ``` +Attempt to "merge" two containers by iterating `source` and extracting all nodes in `source` and inserting them into `*this`. + +Because `source` can have a different hash function and key equality predicate, the key of each node in +`source` is rehashed using `this\->hash_function()` and then, if required, compared using `this\->key_eq()`. + +The behavior of this function is undefined if `this\->get_allocator() != source.get_allocator()`. + +This function does not copy or move any elements and instead simply relocates the nodes from `source` +into `*this`. + [horizontal] -Notes:;; Does not support merging with a compatible `unordered_map` yet. +Notes:;; ++ +-- +* Pointers and references to transferred elements remain valid. +* Invalidates iterators to transferred elements. +* Invalidates iterators belonging to `*this`. +* Iterators to non-transferred elements in `source` remain valid. +-- --- diff --git a/doc/unordered/unordered_multiset.adoc b/doc/unordered/unordered_multiset.adoc index 0369673e..c42e36c2 100644 --- a/doc/unordered/unordered_multiset.adoc +++ b/doc/unordered/unordered_multiset.adoc @@ -120,7 +120,11 @@ namespace boost { template void xref:#unordered_multiset_merge[merge](unordered_multiset& source); template - void xref:#unordered_multiset_merge_rvalue_reference[merge](unordered_multiset&& source); + void xref:#unordered_multiset_merge[merge](unordered_multiset&& source); + template + void xref:#unordered_multiset_merge[merge](unordered_set& source); + template + void xref:#unordered_multiset_merge[merge](unordered_set&& source); // observers hasher xref:#unordered_multiset_hash_function[hash_function]() const; @@ -1013,21 +1017,33 @@ Throws:;; Never throws an exception. ```c++ template void merge(unordered_multiset& source); -``` - -[horizontal] -Notes:;; Does not support merging with a compatible `unordered_set` yet. - ---- - -==== merge (rvalue reference) -```c++ template void merge(unordered_multiset&& source); +template + void merge(unordered_set& source); +template + void merge(unordered_set&& source); ``` +Attempt to "merge" two containers by iterating `source` and extracting all nodes in `source` and inserting them into `*this`. + +Because `source` can have a different hash function and key equality predicate, the key of each node in +`source` is rehashed using `this\->hash_function()` and then, if required, compared using `this\->key_eq()`. + +The behavior of this function is undefined if `this\->get_allocator() != source.get_allocator()`. + +This function does not copy or move any elements and instead simply relocates the nodes from `source` +into `*this`. + [horizontal] -Notes:;; Does not support merging with a compatible `unordered_set` yet. +Notes:;; ++ +-- +* Pointers and references to transferred elements remain valid. +* Invalidates iterators to transferred elements. +* Invalidates iterators belonging to `*this`. +* Iterators to non-transferred elements in `source` remain valid. +-- --- diff --git a/doc/unordered/unordered_set.adoc b/doc/unordered/unordered_set.adoc index 44670457..e9634ec2 100644 --- a/doc/unordered/unordered_set.adoc +++ b/doc/unordered/unordered_set.adoc @@ -121,7 +121,11 @@ namespace boost { template void xref:#unordered_set_merge[merge](unordered_set& source); template - void xref:#unordered_set_merge_rvalue_reference[merge](unordered_set&& source); + void xref:#unordered_set_merge[merge](unordered_set&& source); + template + void xref:#unordered_set_merge[merge](unordered_multiset& source); + template + void xref:#unordered_set_merge[merge](unordered_multiset&& source); // observers hasher xref:#unordered_set_hash_function[hash_function]() const; @@ -1037,21 +1041,34 @@ Throws:;; Never throws an exception. ```c++ template void merge(unordered_set& source); -``` - -[horizontal] -Notes:;; Does not support merging with a compatible `unordered_multiset` yet. - ---- - -==== merge (rvalue reference) -```c++ template void merge(unordered_set&& source); +template + void merge(unordered_multiset& source); +template + void merge(unordered_multiset&& source); ``` +Attempt to "merge" two containers by iterating `source` and extracting any node in `source` that is not contained +in `*this` and then inserting it into `*this`. + +Because `source` can have a different hash function and key equality predicate, the key of each node in +`source` is rehashed using `this\->hash_function()` and then, if required, compared using `this\->key_eq()`. + +The behavior of this function is undefined if `this\->get_allocator() != source.get_allocator()`. + +This function does not copy or move any elements and instead simply relocates the nodes from `source` +into `*this`. + [horizontal] -Notes:;; Does not support merging with a compatible `unordered_multiset` yet. +Notes:;; ++ +-- +* Pointers and references to transferred elements remain valid. +* Invalidates iterators to transferred elements. +* Invalidates iterators belonging to `*this`. +* Iterators to non-transferred elements in `source` remain valid. +-- ---