btree_set.h 29 KB

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