3 // Copyright (C) 2005-2013 Free Software Foundation, Inc.
5 // This file is part of the GNU ISO C++ Library. This library is free
6 // software; you can redistribute it and/or modify it under the terms
7 // of the GNU General Public License as published by the Free Software
8 // Foundation; either version 3, or (at your option) any later
11 // This library is distributed in the hope that it will be useful, but
12 // WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 // General Public License for more details.
16 // Under Section 7 of GPL version 3, you are granted additional
17 // permissions described in the GCC Runtime Library Exception, version
18 // 3.1, as published by the Free Software Foundation.
20 // You should have received a copy of the GNU General Public License and
21 // a copy of the GCC Runtime Library Exception along with this program;
22 // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
23 // <http://www.gnu.org/licenses/>.
25 // Copyright (C) 2004 Ami Tavory and Vladimir Dreizin, IBM-HRL.
27 // Permission to use, copy, modify, sell, and distribute this software
28 // is hereby granted without fee, provided that the above copyright
29 // notice appears in all copies, and that both that copyright notice
30 // and this permission notice appear in supporting documentation. None
31 // of the above authors, nor IBM Haifa Research Laboratories, make any
32 // representation about the suitability of this software for any
33 // purpose. It is provided "as is" without express or implied
37 * @file hash_policy.hpp
38 * Contains hash-related policies.
41 #ifndef PB_DS_HASH_POLICY_HPP
42 #define PB_DS_HASH_POLICY_HPP
44 #include <bits/c++config.h>
48 #include <ext/pb_ds/exception.hpp>
49 #include <ext/pb_ds/detail/type_utils.hpp>
50 #include <ext/pb_ds/detail/hash_fn/mask_based_range_hashing.hpp>
51 #include <ext/pb_ds/detail/hash_fn/mod_based_range_hashing.hpp>
52 #include <ext/pb_ds/detail/resize_policy/hash_load_check_resize_trigger_size_base.hpp>
56 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
57 #define PB_DS_CLASS_C_DEC linear_probe_fn<Size_Type>
59 /// A probe sequence policy using fixed increments.
60 template<typename Size_Type = std::size_t>
64 typedef Size_Type size_type;
67 swap(PB_DS_CLASS_C_DEC& other);
70 /// Returns the i-th offset from the hash value.
72 operator()(size_type i) const;
75 #include <ext/pb_ds/detail/hash_fn/linear_probe_fn_imp.hpp>
77 #undef PB_DS_CLASS_T_DEC
78 #undef PB_DS_CLASS_C_DEC
80 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
81 #define PB_DS_CLASS_C_DEC quadratic_probe_fn<Size_Type>
83 /// A probe sequence policy using square increments.
84 template<typename Size_Type = std::size_t>
85 class quadratic_probe_fn
88 typedef Size_Type size_type;
91 swap(PB_DS_CLASS_C_DEC& other);
94 /// Returns the i-th offset from the hash value.
96 operator()(size_type i) const;
99 #include <ext/pb_ds/detail/hash_fn/quadratic_probe_fn_imp.hpp>
101 #undef PB_DS_CLASS_T_DEC
102 #undef PB_DS_CLASS_C_DEC
104 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
105 #define PB_DS_CLASS_C_DEC direct_mask_range_hashing<Size_Type>
107 /// A mask range-hashing class (uses a bitmask).
108 template<typename Size_Type = std::size_t>
109 class direct_mask_range_hashing
110 : public detail::mask_based_range_hashing<Size_Type>
113 typedef detail::mask_based_range_hashing<Size_Type> mask_based_base;
116 typedef Size_Type size_type;
119 swap(PB_DS_CLASS_C_DEC& other);
123 notify_resized(size_type size);
125 /// Transforms the __hash value hash into a ranged-hash value
126 /// (using a bit-mask).
128 operator()(size_type hash) const;
131 #include <ext/pb_ds/detail/hash_fn/direct_mask_range_hashing_imp.hpp>
133 #undef PB_DS_CLASS_T_DEC
134 #undef PB_DS_CLASS_C_DEC
136 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
137 #define PB_DS_CLASS_C_DEC direct_mod_range_hashing<Size_Type>
139 /// A mod range-hashing class (uses the modulo function).
140 template<typename Size_Type = std::size_t>
141 class direct_mod_range_hashing
142 : public detail::mod_based_range_hashing<Size_Type>
145 typedef Size_Type size_type;
148 swap(PB_DS_CLASS_C_DEC& other);
152 notify_resized(size_type size);
154 /// Transforms the __hash value hash into a ranged-hash value
155 /// (using a modulo operation).
157 operator()(size_type hash) const;
160 typedef detail::mod_based_range_hashing<size_type> mod_based_base;
163 #include <ext/pb_ds/detail/hash_fn/direct_mod_range_hashing_imp.hpp>
165 #undef PB_DS_CLASS_T_DEC
166 #undef PB_DS_CLASS_C_DEC
168 #define PB_DS_CLASS_T_DEC template<bool External_Load_Access, typename Size_Type>
169 #define PB_DS_CLASS_C_DEC hash_load_check_resize_trigger<External_Load_Access, Size_Type>
170 #define PB_DS_SIZE_BASE_C_DEC detail::hash_load_check_resize_trigger_size_base<Size_Type, External_Load_Access>
172 /// A resize trigger policy based on a load check. It keeps the
173 /// load factor between some load factors load_min and load_max.
174 template<bool External_Load_Access = false, typename Size_Type = std::size_t>
175 class hash_load_check_resize_trigger : private PB_DS_SIZE_BASE_C_DEC
178 typedef Size_Type size_type;
182 /// Specifies whether the load factor can be accessed
183 /// externally. The two options have different trade-offs in
184 /// terms of flexibility, genericity, and encapsulation.
185 external_load_access = External_Load_Access
188 /// Default constructor, or constructor taking load_min and
189 /// load_max load factors between which this policy will keep the
191 hash_load_check_resize_trigger(float load_min = 0.125,
192 float load_max = 0.5);
195 swap(hash_load_check_resize_trigger& other);
198 ~hash_load_check_resize_trigger();
200 /// Returns a pair of the minimal and maximal loads, respectively.
201 inline std::pair<float, float>
204 /// Sets the loads through a pair of the minimal and maximal
205 /// loads, respectively.
207 set_loads(std::pair<float, float> load_pair);
211 notify_insert_search_start();
214 notify_insert_search_collision();
217 notify_insert_search_end();
220 notify_find_search_start();
223 notify_find_search_collision();
226 notify_find_search_end();
229 notify_erase_search_start();
232 notify_erase_search_collision();
235 notify_erase_search_end();
237 /// Notifies an element was inserted. The total number of entries
238 /// in the table is num_entries.
240 notify_inserted(size_type num_entries);
243 notify_erased(size_type num_entries);
245 /// Notifies the table was cleared.
249 /// Notifies the table was resized as a result of this object's
250 /// signifying that a resize is needed.
252 notify_resized(size_type new_size);
255 notify_externally_resized(size_type new_size);
258 is_resize_needed() const;
261 is_grow_needed(size_type size, size_type num_entries) const;
265 do_resize(size_type new_size);
267 typedef PB_DS_SIZE_BASE_C_DEC size_base;
269 #ifdef _GLIBCXX_DEBUG
271 assert_valid(const char* file, int line) const;
276 size_type m_next_shrink_size;
277 size_type m_next_grow_size;
278 bool m_resize_needed;
281 #include <ext/pb_ds/detail/resize_policy/hash_load_check_resize_trigger_imp.hpp>
283 #undef PB_DS_CLASS_T_DEC
284 #undef PB_DS_CLASS_C_DEC
285 #undef PB_DS_SIZE_BASE_C_DEC
287 #define PB_DS_CLASS_T_DEC template<bool External_Load_Access, typename Size_Type>
288 #define PB_DS_CLASS_C_DEC cc_hash_max_collision_check_resize_trigger<External_Load_Access, Size_Type>
290 /// A resize trigger policy based on collision checks. It keeps the
291 /// simulated load factor lower than some given load factor.
292 template<bool External_Load_Access = false, typename Size_Type = std::size_t>
293 class cc_hash_max_collision_check_resize_trigger
296 typedef Size_Type size_type;
300 /// Specifies whether the load factor can be accessed
301 /// externally. The two options have different trade-offs in
302 /// terms of flexibility, genericity, and encapsulation.
303 external_load_access = External_Load_Access
306 /// Default constructor, or constructor taking load, a __load
307 /// factor which it will attempt to maintain.
308 cc_hash_max_collision_check_resize_trigger(float load = 0.5);
311 swap(PB_DS_CLASS_C_DEC& other);
313 /// Returns the current load.
317 /// Sets the load; does not resize the container.
319 set_load(float load);
322 /// Notifies an insert search started.
324 notify_insert_search_start();
326 /// Notifies a search encountered a collision.
328 notify_insert_search_collision();
330 /// Notifies a search ended.
332 notify_insert_search_end();
334 /// Notifies a find search started.
336 notify_find_search_start();
338 /// Notifies a search encountered a collision.
340 notify_find_search_collision();
342 /// Notifies a search ended.
344 notify_find_search_end();
346 /// Notifies an erase search started.
348 notify_erase_search_start();
350 /// Notifies a search encountered a collision.
352 notify_erase_search_collision();
354 /// Notifies a search ended.
356 notify_erase_search_end();
358 /// Notifies an element was inserted.
360 notify_inserted(size_type num_entries);
362 /// Notifies an element was erased.
364 notify_erased(size_type num_entries);
366 /// Notifies the table was cleared.
370 /// Notifies the table was resized as a result of this object's
371 /// signifying that a resize is needed.
373 notify_resized(size_type new_size);
375 /// Notifies the table was resized externally.
377 notify_externally_resized(size_type new_size);
379 /// Queries whether a resize is needed.
381 is_resize_needed() const;
383 /// Queries whether a grow is needed. This method is called only
384 /// if this object indicated is needed.
386 is_grow_needed(size_type size, size_type num_entries) const;
393 calc_resize_needed();
399 bool m_resize_needed;
402 #include <ext/pb_ds/detail/resize_policy/cc_hash_max_collision_check_resize_trigger_imp.hpp>
404 #undef PB_DS_CLASS_T_DEC
405 #undef PB_DS_CLASS_C_DEC
407 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
408 #define PB_DS_CLASS_C_DEC hash_exponential_size_policy<Size_Type>
410 /// A size policy whose sequence of sizes form an exponential
411 /// sequence (typically powers of 2.
412 template<typename Size_Type = std::size_t>
413 class hash_exponential_size_policy
416 typedef Size_Type size_type;
418 /// Default constructor, or onstructor taking a start_size, or
419 /// constructor taking a start size and grow_factor. The policy
420 /// will use the sequence of sizes start_size, start_size*
421 /// grow_factor, start_size* grow_factor^2, ...
422 hash_exponential_size_policy(size_type start_size = 8,
423 size_type grow_factor = 2);
426 swap(PB_DS_CLASS_C_DEC& other);
430 get_nearest_larger_size(size_type size) const;
433 get_nearest_smaller_size(size_type size) const;
436 size_type m_start_size;
437 size_type m_grow_factor;
440 #include <ext/pb_ds/detail/resize_policy/hash_exponential_size_policy_imp.hpp>
442 #undef PB_DS_CLASS_T_DEC
443 #undef PB_DS_CLASS_C_DEC
445 #define PB_DS_CLASS_T_DEC
446 #define PB_DS_CLASS_C_DEC hash_prime_size_policy
448 /// A size policy whose sequence of sizes form a nearly-exponential
449 /// sequence of primes.
450 class hash_prime_size_policy
454 typedef std::size_t size_type;
456 /// Default constructor, or onstructor taking a start_size The
457 /// policy will use the sequence of sizes approximately
458 /// start_size, start_size* 2, start_size* 2^2, ...
459 hash_prime_size_policy(size_type start_size = 8);
462 swap(PB_DS_CLASS_C_DEC& other);
466 get_nearest_larger_size(size_type size) const;
469 get_nearest_smaller_size(size_type size) const;
472 size_type m_start_size;
475 #include <ext/pb_ds/detail/resize_policy/hash_prime_size_policy_imp.hpp>
477 #undef PB_DS_CLASS_T_DEC
478 #undef PB_DS_CLASS_C_DEC
480 #define PB_DS_CLASS_T_DEC template<typename Size_Policy, typename Trigger_Policy, bool External_Size_Access, typename Size_Type>
482 #define PB_DS_CLASS_C_DEC hash_standard_resize_policy<Size_Policy, Trigger_Policy, External_Size_Access, Size_Type>
484 /// A resize policy which delegates operations to size and trigger policies.
485 template<typename Size_Policy = hash_exponential_size_policy<>,
486 typename Trigger_Policy = hash_load_check_resize_trigger<>,
487 bool External_Size_Access = false,
488 typename Size_Type = std::size_t>
489 class hash_standard_resize_policy
490 : public Size_Policy, public Trigger_Policy
493 typedef Size_Type size_type;
494 typedef Trigger_Policy trigger_policy;
495 typedef Size_Policy size_policy;
499 external_size_access = External_Size_Access
502 /// Default constructor.
503 hash_standard_resize_policy();
505 /// constructor taking some policies r_size_policy will be copied
506 /// by the Size_Policy object of this object.
507 hash_standard_resize_policy(const Size_Policy& r_size_policy);
509 /// constructor taking some policies. r_size_policy will be
510 /// copied by the Size_Policy object of this
511 /// object. r_trigger_policy will be copied by the Trigger_Policy
512 /// object of this object.
513 hash_standard_resize_policy(const Size_Policy& r_size_policy,
514 const Trigger_Policy& r_trigger_policy);
517 ~hash_standard_resize_policy();
520 swap(PB_DS_CLASS_C_DEC& other);
522 /// Access to the Size_Policy object used.
526 /// Const access to the Size_Policy object used.
528 get_size_policy() const;
530 /// Access to the Trigger_Policy object used.
532 get_trigger_policy();
534 /// Access to the Trigger_Policy object used.
535 const Trigger_Policy&
536 get_trigger_policy() const;
538 /// Returns the actual size of the container.
540 get_actual_size() const;
542 /// Resizes the container to suggested_new_size, a suggested size
543 /// (the actual size will be determined by the Size_Policy
546 resize(size_type suggested_new_size);
550 notify_insert_search_start();
553 notify_insert_search_collision();
556 notify_insert_search_end();
559 notify_find_search_start();
562 notify_find_search_collision();
565 notify_find_search_end();
568 notify_erase_search_start();
571 notify_erase_search_collision();
574 notify_erase_search_end();
577 notify_inserted(size_type num_e);
580 notify_erased(size_type num_e);
586 notify_resized(size_type new_size);
589 is_resize_needed() const;
591 /// Queries what the new size should be, when the container is
592 /// resized naturally. The current __size of the container is
593 /// size, and the number of used entries within the container is
596 get_new_size(size_type size, size_type num_used_e) const;
599 /// Resizes to new_size.
601 do_resize(size_type new_size);
603 typedef Trigger_Policy trigger_policy_base;
605 typedef Size_Policy size_policy_base;
610 #include <ext/pb_ds/detail/resize_policy/hash_standard_resize_policy_imp.hpp>
612 #undef PB_DS_CLASS_T_DEC
613 #undef PB_DS_CLASS_C_DEC
615 } // namespace __gnu_pbds