btree_map.h 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769
  1. // Copyright 2018 The Abseil Authors.
  2. //
  3. // Licensed under the Apache License, Version 2.0 (the "License");
  4. // you may not use this file except in compliance with the License.
  5. // You may obtain a copy of the License at
  6. //
  7. // https://www.apache.org/licenses/LICENSE-2.0
  8. //
  9. // Unless required by applicable law or agreed to in writing, software
  10. // distributed under the License is distributed on an "AS IS" BASIS,
  11. // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. // See the License for the specific language governing permissions and
  13. // limitations under the License.
  14. //
  15. // -----------------------------------------------------------------------------
  16. // File: btree_map.h
  17. // -----------------------------------------------------------------------------
  18. //
  19. // This header file defines B-tree maps: sorted associative containers mapping
  20. // keys to values.
  21. //
  22. // * `absl::btree_map<>`
  23. // * `absl::btree_multimap<>`
  24. //
  25. // These B-tree types are similar to the corresponding types in the STL
  26. // (`std::map` and `std::multimap`) and generally conform to the STL interfaces
  27. // of those types. However, because they are implemented using B-trees, they
  28. // are more efficient in most situations.
  29. //
  30. // Unlike `std::map` and `std::multimap`, which are commonly implemented using
  31. // red-black tree nodes, B-tree maps use more generic B-tree nodes able to hold
  32. // multiple values per node. Holding multiple values per node often makes
  33. // B-tree maps perform better than their `std::map` counterparts, because
  34. // multiple entries can be checked within the same cache hit.
  35. //
  36. // However, these types should not be considered drop-in replacements for
  37. // `std::map` and `std::multimap` as there are some API differences, which are
  38. // noted in this header file.
  39. //
  40. // Importantly, insertions and deletions may invalidate outstanding iterators,
  41. // pointers, and references to elements. Such invalidations are typically only
  42. // an issue if insertion and deletion operations are interleaved with the use of
  43. // more than one iterator, pointer, or reference simultaneously. For this
  44. // reason, `insert()` and `erase()` return a valid iterator at the current
  45. // position.
  46. #ifndef ABSL_CONTAINER_BTREE_MAP_H_
  47. #define ABSL_CONTAINER_BTREE_MAP_H_
  48. #include "absl/container/internal/btree.h" // IWYU pragma: export
  49. #include "absl/container/internal/btree_container.h" // IWYU pragma: export
  50. namespace absl {
  51. ABSL_NAMESPACE_BEGIN
  52. // absl::btree_map<>
  53. //
  54. // An `absl::btree_map<K, V>` is an ordered associative container of
  55. // unique keys and associated values designed to be a more efficient replacement
  56. // for `std::map` (in most cases).
  57. //
  58. // Keys are sorted using an (optional) comparison function, which defaults to
  59. // `std::less<K>`.
  60. //
  61. // An `absl::btree_map<K, V>` uses a default allocator of
  62. // `std::allocator<std::pair<const K, V>>` to allocate (and deallocate)
  63. // nodes, and construct and destruct values within those nodes. You may
  64. // instead specify a custom allocator `A` (which in turn requires specifying a
  65. // custom comparator `C`) as in `absl::btree_map<K, V, C, A>`.
  66. //
  67. template <typename Key, typename Value, typename Compare = std::less<Key>,
  68. typename Alloc = std::allocator<std::pair<const Key, Value>>>
  69. class btree_map
  70. : public container_internal::btree_map_container<
  71. container_internal::btree<container_internal::map_params<
  72. Key, Value, Compare, Alloc, /*TargetNodeSize=*/256,
  73. /*Multi=*/false>>> {
  74. using Base = typename btree_map::btree_map_container;
  75. public:
  76. // Constructors and Assignment Operators
  77. //
  78. // A `btree_map` supports the same overload set as `std::map`
  79. // for construction and assignment:
  80. //
  81. // * Default constructor
  82. //
  83. // absl::btree_map<int, std::string> map1;
  84. //
  85. // * Initializer List constructor
  86. //
  87. // absl::btree_map<int, std::string> map2 =
  88. // {{1, "huey"}, {2, "dewey"}, {3, "louie"},};
  89. //
  90. // * Copy constructor
  91. //
  92. // absl::btree_map<int, std::string> map3(map2);
  93. //
  94. // * Copy assignment operator
  95. //
  96. // absl::btree_map<int, std::string> map4;
  97. // map4 = map3;
  98. //
  99. // * Move constructor
  100. //
  101. // // Move is guaranteed efficient
  102. // absl::btree_map<int, std::string> map5(std::move(map4));
  103. //
  104. // * Move assignment operator
  105. //
  106. // // May be efficient if allocators are compatible
  107. // absl::btree_map<int, std::string> map6;
  108. // map6 = std::move(map5);
  109. //
  110. // * Range constructor
  111. //
  112. // std::vector<std::pair<int, std::string>> v = {{1, "a"}, {2, "b"}};
  113. // absl::btree_map<int, std::string> map7(v.begin(), v.end());
  114. btree_map() {}
  115. using Base::Base;
  116. // btree_map::begin()
  117. //
  118. // Returns an iterator to the beginning of the `btree_map`.
  119. using Base::begin;
  120. // btree_map::cbegin()
  121. //
  122. // Returns a const iterator to the beginning of the `btree_map`.
  123. using Base::cbegin;
  124. // btree_map::end()
  125. //
  126. // Returns an iterator to the end of the `btree_map`.
  127. using Base::end;
  128. // btree_map::cend()
  129. //
  130. // Returns a const iterator to the end of the `btree_map`.
  131. using Base::cend;
  132. // btree_map::empty()
  133. //
  134. // Returns whether or not the `btree_map` is empty.
  135. using Base::empty;
  136. // btree_map::max_size()
  137. //
  138. // Returns the largest theoretical possible number of elements within a
  139. // `btree_map` under current memory constraints. This value can be thought
  140. // of as the largest value of `std::distance(begin(), end())` for a
  141. // `btree_map<Key, T>`.
  142. using Base::max_size;
  143. // btree_map::size()
  144. //
  145. // Returns the number of elements currently within the `btree_map`.
  146. using Base::size;
  147. // btree_map::clear()
  148. //
  149. // Removes all elements from the `btree_map`. Invalidates any references,
  150. // pointers, or iterators referring to contained elements.
  151. using Base::clear;
  152. // btree_map::erase()
  153. //
  154. // Erases elements within the `btree_map`. If an erase occurs, any references,
  155. // pointers, or iterators are invalidated.
  156. // Overloads are listed below.
  157. //
  158. // iterator erase(iterator position):
  159. // iterator erase(const_iterator position):
  160. //
  161. // Erases the element at `position` of the `btree_map`, returning
  162. // the iterator pointing to the element after the one that was erased
  163. // (or end() if none exists).
  164. //
  165. // iterator erase(const_iterator first, const_iterator last):
  166. //
  167. // Erases the elements in the open interval [`first`, `last`), returning
  168. // the iterator pointing to the element after the interval that was erased
  169. // (or end() if none exists).
  170. //
  171. // template <typename K> size_type erase(const K& key):
  172. //
  173. // Erases the element with the matching key, if it exists, returning the
  174. // number of elements erased (0 or 1).
  175. using Base::erase;
  176. // btree_map::insert()
  177. //
  178. // Inserts an element of the specified value into the `btree_map`,
  179. // returning an iterator pointing to the newly inserted element, provided that
  180. // an element with the given key does not already exist. If an insertion
  181. // occurs, any references, pointers, or iterators are invalidated.
  182. // Overloads are listed below.
  183. //
  184. // std::pair<iterator,bool> insert(const value_type& value):
  185. //
  186. // Inserts a value into the `btree_map`. Returns a pair consisting of an
  187. // iterator to the inserted element (or to the element that prevented the
  188. // insertion) and a bool denoting whether the insertion took place.
  189. //
  190. // std::pair<iterator,bool> insert(value_type&& value):
  191. //
  192. // Inserts a moveable value into the `btree_map`. Returns a pair
  193. // consisting of an iterator to the inserted element (or to the element that
  194. // prevented the insertion) and a bool denoting whether the insertion took
  195. // place.
  196. //
  197. // iterator insert(const_iterator hint, const value_type& value):
  198. // iterator insert(const_iterator hint, value_type&& value):
  199. //
  200. // Inserts a value, using the position of `hint` as a non-binding suggestion
  201. // for where to begin the insertion search. Returns an iterator to the
  202. // inserted element, or to the existing element that prevented the
  203. // insertion.
  204. //
  205. // void insert(InputIterator first, InputIterator last):
  206. //
  207. // Inserts a range of values [`first`, `last`).
  208. //
  209. // void insert(std::initializer_list<init_type> ilist):
  210. //
  211. // Inserts the elements within the initializer list `ilist`.
  212. using Base::insert;
  213. // btree_map::insert_or_assign()
  214. //
  215. // Inserts an element of the specified value into the `btree_map` provided
  216. // that a value with the given key does not already exist, or replaces the
  217. // corresponding mapped type with the forwarded `obj` argument if a key for
  218. // that value already exists, returning an iterator pointing to the newly
  219. // inserted element. Overloads are listed below.
  220. //
  221. // pair<iterator, bool> insert_or_assign(const key_type& k, M&& obj):
  222. // pair<iterator, bool> insert_or_assign(key_type&& k, M&& obj):
  223. //
  224. // Inserts/Assigns (or moves) the element of the specified key into the
  225. // `btree_map`. If the returned bool is true, insertion took place, and if
  226. // it's false, assignment took place.
  227. //
  228. // iterator insert_or_assign(const_iterator hint,
  229. // const key_type& k, M&& obj):
  230. // iterator insert_or_assign(const_iterator hint, key_type&& k, M&& obj):
  231. //
  232. // Inserts/Assigns (or moves) the element of the specified key into the
  233. // `btree_map` using the position of `hint` as a non-binding suggestion
  234. // for where to begin the insertion search.
  235. using Base::insert_or_assign;
  236. // btree_map::emplace()
  237. //
  238. // Inserts an element of the specified value by constructing it in-place
  239. // within the `btree_map`, provided that no element with the given key
  240. // already exists.
  241. //
  242. // The element may be constructed even if there already is an element with the
  243. // key in the container, in which case the newly constructed element will be
  244. // destroyed immediately. Prefer `try_emplace()` unless your key is not
  245. // copyable or moveable.
  246. //
  247. // If an insertion occurs, any references, pointers, or iterators are
  248. // invalidated.
  249. using Base::emplace;
  250. // btree_map::emplace_hint()
  251. //
  252. // Inserts an element of the specified value by constructing it in-place
  253. // within the `btree_map`, using the position of `hint` as a non-binding
  254. // suggestion for where to begin the insertion search, and only inserts
  255. // provided that no element with the given key already exists.
  256. //
  257. // The element may be constructed even if there already is an element with the
  258. // key in the container, in which case the newly constructed element will be
  259. // destroyed immediately. Prefer `try_emplace()` unless your key is not
  260. // copyable or moveable.
  261. //
  262. // If an insertion occurs, any references, pointers, or iterators are
  263. // invalidated.
  264. using Base::emplace_hint;
  265. // btree_map::try_emplace()
  266. //
  267. // Inserts an element of the specified value by constructing it in-place
  268. // within the `btree_map`, provided that no element with the given key
  269. // already exists. Unlike `emplace()`, if an element with the given key
  270. // already exists, we guarantee that no element is constructed.
  271. //
  272. // If an insertion occurs, any references, pointers, or iterators are
  273. // invalidated.
  274. //
  275. // Overloads are listed below.
  276. //
  277. // std::pair<iterator, bool> try_emplace(const key_type& k, Args&&... args):
  278. // std::pair<iterator, bool> try_emplace(key_type&& k, Args&&... args):
  279. //
  280. // Inserts (via copy or move) the element of the specified key into the
  281. // `btree_map`.
  282. //
  283. // iterator try_emplace(const_iterator hint,
  284. // const key_type& k, Args&&... args):
  285. // iterator try_emplace(const_iterator hint, key_type&& k, Args&&... args):
  286. //
  287. // Inserts (via copy or move) the element of the specified key into the
  288. // `btree_map` using the position of `hint` as a non-binding suggestion
  289. // for where to begin the insertion search.
  290. using Base::try_emplace;
  291. // btree_map::extract()
  292. //
  293. // Extracts the indicated element, erasing it in the process, and returns it
  294. // as a C++17-compatible node handle. Overloads are listed below.
  295. //
  296. // node_type extract(const_iterator position):
  297. //
  298. // Extracts the element at the indicated position and returns a node handle
  299. // owning that extracted data.
  300. //
  301. // template <typename K> node_type extract(const K& k):
  302. //
  303. // Extracts the element with the key matching the passed key value and
  304. // returns a node handle owning that extracted data. If the `btree_map`
  305. // does not contain an element with a matching key, this function returns an
  306. // empty node handle.
  307. //
  308. // NOTE: when compiled in an earlier version of C++ than C++17,
  309. // `node_type::key()` returns a const reference to the key instead of a
  310. // mutable reference. We cannot safely return a mutable reference without
  311. // std::launder (which is not available before C++17).
  312. //
  313. // NOTE: In this context, `node_type` refers to the C++17 concept of a
  314. // move-only type that owns and provides access to the elements in associative
  315. // containers (https://en.cppreference.com/w/cpp/container/node_handle).
  316. // It does NOT refer to the data layout of the underlying btree.
  317. using Base::extract;
  318. // btree_map::merge()
  319. //
  320. // Extracts elements from a given `source` btree_map into this
  321. // `btree_map`. If the destination `btree_map` already contains an
  322. // element with an equivalent key, that element is not extracted.
  323. using Base::merge;
  324. // btree_map::swap(btree_map& other)
  325. //
  326. // Exchanges the contents of this `btree_map` with those of the `other`
  327. // btree_map, avoiding invocation of any move, copy, or swap operations on
  328. // individual elements.
  329. //
  330. // All iterators and references on the `btree_map` remain valid, excepting
  331. // for the past-the-end iterator, which is invalidated.
  332. using Base::swap;
  333. // btree_map::at()
  334. //
  335. // Returns a reference to the mapped value of the element with key equivalent
  336. // to the passed key.
  337. using Base::at;
  338. // btree_map::contains()
  339. //
  340. // template <typename K> bool contains(const K& key) const:
  341. //
  342. // Determines whether an element comparing equal to the given `key` exists
  343. // within the `btree_map`, returning `true` if so or `false` otherwise.
  344. //
  345. // Supports heterogeneous lookup, provided that the map is provided a
  346. // compatible heterogeneous comparator.
  347. using Base::contains;
  348. // btree_map::count()
  349. //
  350. // template <typename K> size_type count(const K& key) const:
  351. //
  352. // Returns the number of elements comparing equal to the given `key` within
  353. // the `btree_map`. Note that this function will return either `1` or `0`
  354. // since duplicate elements are not allowed within a `btree_map`.
  355. //
  356. // Supports heterogeneous lookup, provided that the map is provided a
  357. // compatible heterogeneous comparator.
  358. using Base::count;
  359. // btree_map::equal_range()
  360. //
  361. // Returns a closed range [first, last], defined by a `std::pair` of two
  362. // iterators, containing all elements with the passed key in the
  363. // `btree_map`.
  364. using Base::equal_range;
  365. // btree_map::find()
  366. //
  367. // template <typename K> iterator find(const K& key):
  368. // template <typename K> const_iterator find(const K& key) const:
  369. //
  370. // Finds an element with the passed `key` within the `btree_map`.
  371. //
  372. // Supports heterogeneous lookup, provided that the map is provided a
  373. // compatible heterogeneous comparator.
  374. using Base::find;
  375. // btree_map::operator[]()
  376. //
  377. // Returns a reference to the value mapped to the passed key within the
  378. // `btree_map`, performing an `insert()` if the key does not already
  379. // exist.
  380. //
  381. // If an insertion occurs, any references, pointers, or iterators are
  382. // invalidated. Otherwise iterators are not affected and references are not
  383. // invalidated. Overloads are listed below.
  384. //
  385. // T& operator[](key_type&& key):
  386. // T& operator[](const key_type& key):
  387. //
  388. // Inserts a value_type object constructed in-place if the element with the
  389. // given key does not exist.
  390. using Base::operator[];
  391. // btree_map::get_allocator()
  392. //
  393. // Returns the allocator function associated with this `btree_map`.
  394. using Base::get_allocator;
  395. // btree_map::key_comp();
  396. //
  397. // Returns the key comparator associated with this `btree_map`.
  398. using Base::key_comp;
  399. // btree_map::value_comp();
  400. //
  401. // Returns the value comparator associated with this `btree_map`.
  402. using Base::value_comp;
  403. };
  404. // absl::swap(absl::btree_map<>, absl::btree_map<>)
  405. //
  406. // Swaps the contents of two `absl::btree_map` containers.
  407. template <typename K, typename V, typename C, typename A>
  408. void swap(btree_map<K, V, C, A> &x, btree_map<K, V, C, A> &y) {
  409. return x.swap(y);
  410. }
  411. // absl::erase_if(absl::btree_map<>, Pred)
  412. //
  413. // Erases all elements that satisfy the predicate pred from the container.
  414. template <typename K, typename V, typename C, typename A, typename Pred>
  415. void erase_if(btree_map<K, V, C, A> &map, Pred pred) {
  416. for (auto it = map.begin(); it != map.end();) {
  417. if (pred(*it)) {
  418. it = map.erase(it);
  419. } else {
  420. ++it;
  421. }
  422. }
  423. }
  424. // absl::btree_multimap
  425. //
  426. // An `absl::btree_multimap<K, V>` is an ordered associative container of
  427. // keys and associated values designed to be a more efficient replacement for
  428. // `std::multimap` (in most cases). Unlike `absl::btree_map`, a B-tree multimap
  429. // allows multiple elements with equivalent keys.
  430. //
  431. // Keys are sorted using an (optional) comparison function, which defaults to
  432. // `std::less<K>`.
  433. //
  434. // An `absl::btree_multimap<K, V>` uses a default allocator of
  435. // `std::allocator<std::pair<const K, V>>` to allocate (and deallocate)
  436. // nodes, and construct and destruct values within those nodes. You may
  437. // instead specify a custom allocator `A` (which in turn requires specifying a
  438. // custom comparator `C`) as in `absl::btree_multimap<K, V, C, A>`.
  439. //
  440. template <typename Key, typename Value, typename Compare = std::less<Key>,
  441. typename Alloc = std::allocator<std::pair<const Key, Value>>>
  442. class btree_multimap
  443. : public container_internal::btree_multimap_container<
  444. container_internal::btree<container_internal::map_params<
  445. Key, Value, Compare, Alloc, /*TargetNodeSize=*/256,
  446. /*Multi=*/true>>> {
  447. using Base = typename btree_multimap::btree_multimap_container;
  448. public:
  449. // Constructors and Assignment Operators
  450. //
  451. // A `btree_multimap` supports the same overload set as `std::multimap`
  452. // for construction and assignment:
  453. //
  454. // * Default constructor
  455. //
  456. // absl::btree_multimap<int, std::string> map1;
  457. //
  458. // * Initializer List constructor
  459. //
  460. // absl::btree_multimap<int, std::string> map2 =
  461. // {{1, "huey"}, {2, "dewey"}, {3, "louie"},};
  462. //
  463. // * Copy constructor
  464. //
  465. // absl::btree_multimap<int, std::string> map3(map2);
  466. //
  467. // * Copy assignment operator
  468. //
  469. // absl::btree_multimap<int, std::string> map4;
  470. // map4 = map3;
  471. //
  472. // * Move constructor
  473. //
  474. // // Move is guaranteed efficient
  475. // absl::btree_multimap<int, std::string> map5(std::move(map4));
  476. //
  477. // * Move assignment operator
  478. //
  479. // // May be efficient if allocators are compatible
  480. // absl::btree_multimap<int, std::string> map6;
  481. // map6 = std::move(map5);
  482. //
  483. // * Range constructor
  484. //
  485. // std::vector<std::pair<int, std::string>> v = {{1, "a"}, {2, "b"}};
  486. // absl::btree_multimap<int, std::string> map7(v.begin(), v.end());
  487. btree_multimap() {}
  488. using Base::Base;
  489. // btree_multimap::begin()
  490. //
  491. // Returns an iterator to the beginning of the `btree_multimap`.
  492. using Base::begin;
  493. // btree_multimap::cbegin()
  494. //
  495. // Returns a const iterator to the beginning of the `btree_multimap`.
  496. using Base::cbegin;
  497. // btree_multimap::end()
  498. //
  499. // Returns an iterator to the end of the `btree_multimap`.
  500. using Base::end;
  501. // btree_multimap::cend()
  502. //
  503. // Returns a const iterator to the end of the `btree_multimap`.
  504. using Base::cend;
  505. // btree_multimap::empty()
  506. //
  507. // Returns whether or not the `btree_multimap` is empty.
  508. using Base::empty;
  509. // btree_multimap::max_size()
  510. //
  511. // Returns the largest theoretical possible number of elements within a
  512. // `btree_multimap` under current memory constraints. This value can be
  513. // thought of as the largest value of `std::distance(begin(), end())` for a
  514. // `btree_multimap<Key, T>`.
  515. using Base::max_size;
  516. // btree_multimap::size()
  517. //
  518. // Returns the number of elements currently within the `btree_multimap`.
  519. using Base::size;
  520. // btree_multimap::clear()
  521. //
  522. // Removes all elements from the `btree_multimap`. Invalidates any references,
  523. // pointers, or iterators referring to contained elements.
  524. using Base::clear;
  525. // btree_multimap::erase()
  526. //
  527. // Erases elements within the `btree_multimap`. If an erase occurs, any
  528. // references, pointers, or iterators are invalidated.
  529. // Overloads are listed below.
  530. //
  531. // iterator erase(iterator position):
  532. // iterator erase(const_iterator position):
  533. //
  534. // Erases the element at `position` of the `btree_multimap`, returning
  535. // the iterator pointing to the element after the one that was erased
  536. // (or end() if none exists).
  537. //
  538. // iterator erase(const_iterator first, const_iterator last):
  539. //
  540. // Erases the elements in the open interval [`first`, `last`), returning
  541. // the iterator pointing to the element after the interval that was erased
  542. // (or end() if none exists).
  543. //
  544. // template <typename K> size_type erase(const K& key):
  545. //
  546. // Erases the elements matching the key, if any exist, returning the
  547. // number of elements erased.
  548. using Base::erase;
  549. // btree_multimap::insert()
  550. //
  551. // Inserts an element of the specified value into the `btree_multimap`,
  552. // returning an iterator pointing to the newly inserted element.
  553. // Any references, pointers, or iterators are invalidated. Overloads are
  554. // listed below.
  555. //
  556. // iterator insert(const value_type& value):
  557. //
  558. // Inserts a value into the `btree_multimap`, returning an iterator to the
  559. // inserted element.
  560. //
  561. // iterator insert(value_type&& value):
  562. //
  563. // Inserts a moveable value into the `btree_multimap`, returning an iterator
  564. // to the inserted element.
  565. //
  566. // iterator insert(const_iterator hint, const value_type& value):
  567. // iterator insert(const_iterator hint, value_type&& value):
  568. //
  569. // Inserts a value, using the position of `hint` as a non-binding suggestion
  570. // for where to begin the insertion search. Returns an iterator to the
  571. // inserted element.
  572. //
  573. // void insert(InputIterator first, InputIterator last):
  574. //
  575. // Inserts a range of values [`first`, `last`).
  576. //
  577. // void insert(std::initializer_list<init_type> ilist):
  578. //
  579. // Inserts the elements within the initializer list `ilist`.
  580. using Base::insert;
  581. // btree_multimap::emplace()
  582. //
  583. // Inserts an element of the specified value by constructing it in-place
  584. // within the `btree_multimap`. Any references, pointers, or iterators are
  585. // invalidated.
  586. using Base::emplace;
  587. // btree_multimap::emplace_hint()
  588. //
  589. // Inserts an element of the specified value by constructing it in-place
  590. // within the `btree_multimap`, using the position of `hint` as a non-binding
  591. // suggestion for where to begin the insertion search.
  592. //
  593. // Any references, pointers, or iterators are invalidated.
  594. using Base::emplace_hint;
  595. // btree_multimap::extract()
  596. //
  597. // Extracts the indicated element, erasing it in the process, and returns it
  598. // as a C++17-compatible node handle. Overloads are listed below.
  599. //
  600. // node_type extract(const_iterator position):
  601. //
  602. // Extracts the element at the indicated position and returns a node handle
  603. // owning that extracted data.
  604. //
  605. // template <typename K> node_type extract(const K& k):
  606. //
  607. // Extracts the element with the key matching the passed key value and
  608. // returns a node handle owning that extracted data. If the `btree_multimap`
  609. // does not contain an element with a matching key, this function returns an
  610. // empty node handle.
  611. //
  612. // NOTE: when compiled in an earlier version of C++ than C++17,
  613. // `node_type::key()` returns a const reference to the key instead of a
  614. // mutable reference. We cannot safely return a mutable reference without
  615. // std::launder (which is not available before C++17).
  616. //
  617. // NOTE: In this context, `node_type` refers to the C++17 concept of a
  618. // move-only type that owns and provides access to the elements in associative
  619. // containers (https://en.cppreference.com/w/cpp/container/node_handle).
  620. // It does NOT refer to the data layout of the underlying btree.
  621. using Base::extract;
  622. // btree_multimap::merge()
  623. //
  624. // Extracts elements from a given `source` btree_multimap into this
  625. // `btree_multimap`. If the destination `btree_multimap` already contains an
  626. // element with an equivalent key, that element is not extracted.
  627. using Base::merge;
  628. // btree_multimap::swap(btree_multimap& other)
  629. //
  630. // Exchanges the contents of this `btree_multimap` with those of the `other`
  631. // btree_multimap, avoiding invocation of any move, copy, or swap operations
  632. // on individual elements.
  633. //
  634. // All iterators and references on the `btree_multimap` remain valid,
  635. // excepting for the past-the-end iterator, which is invalidated.
  636. using Base::swap;
  637. // btree_multimap::contains()
  638. //
  639. // template <typename K> bool contains(const K& key) const:
  640. //
  641. // Determines whether an element comparing equal to the given `key` exists
  642. // within the `btree_multimap`, returning `true` if so or `false` otherwise.
  643. //
  644. // Supports heterogeneous lookup, provided that the map is provided a
  645. // compatible heterogeneous comparator.
  646. using Base::contains;
  647. // btree_multimap::count()
  648. //
  649. // template <typename K> size_type count(const K& key) const:
  650. //
  651. // Returns the number of elements comparing equal to the given `key` within
  652. // the `btree_multimap`.
  653. //
  654. // Supports heterogeneous lookup, provided that the map is provided a
  655. // compatible heterogeneous comparator.
  656. using Base::count;
  657. // btree_multimap::equal_range()
  658. //
  659. // Returns a closed range [first, last], defined by a `std::pair` of two
  660. // iterators, containing all elements with the passed key in the
  661. // `btree_multimap`.
  662. using Base::equal_range;
  663. // btree_multimap::find()
  664. //
  665. // template <typename K> iterator find(const K& key):
  666. // template <typename K> const_iterator find(const K& key) const:
  667. //
  668. // Finds an element with the passed `key` within the `btree_multimap`.
  669. //
  670. // Supports heterogeneous lookup, provided that the map is provided a
  671. // compatible heterogeneous comparator.
  672. using Base::find;
  673. // btree_multimap::get_allocator()
  674. //
  675. // Returns the allocator function associated with this `btree_multimap`.
  676. using Base::get_allocator;
  677. // btree_multimap::key_comp();
  678. //
  679. // Returns the key comparator associated with this `btree_multimap`.
  680. using Base::key_comp;
  681. // btree_multimap::value_comp();
  682. //
  683. // Returns the value comparator associated with this `btree_multimap`.
  684. using Base::value_comp;
  685. };
  686. // absl::swap(absl::btree_multimap<>, absl::btree_multimap<>)
  687. //
  688. // Swaps the contents of two `absl::btree_multimap` containers.
  689. template <typename K, typename V, typename C, typename A>
  690. void swap(btree_multimap<K, V, C, A> &x, btree_multimap<K, V, C, A> &y) {
  691. return x.swap(y);
  692. }
  693. // absl::erase_if(absl::btree_multimap<>, Pred)
  694. //
  695. // Erases all elements that satisfy the predicate pred from the container.
  696. template <typename K, typename V, typename C, typename A, typename Pred>
  697. void erase_if(btree_multimap<K, V, C, A> &map, Pred pred) {
  698. for (auto it = map.begin(); it != map.end();) {
  699. if (pred(*it)) {
  700. it = map.erase(it);
  701. } else {
  702. ++it;
  703. }
  704. }
  705. }
  706. ABSL_NAMESPACE_END
  707. } // namespace absl
  708. #endif // ABSL_CONTAINER_BTREE_MAP_H_