3 // Copyright (C) 2005, 2006 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 2, 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 // You should have received a copy of the GNU General Public License
17 // along with this library; see the file COPYING. If not, write to
18 // the Free Software Foundation, 59 Temple Place - Suite 330, Boston,
19 // MA 02111-1307, USA.
21 // As a special exception, you may use this file as part of a free
22 // software library without restriction. Specifically, if other files
23 // instantiate templates or use macros or inline functions from this
24 // file, or you compile this file and link it with other files to
25 // produce an executable, this file does not by itself cause the
26 // resulting executable to be covered by the GNU General Public
27 // License. This exception does not however invalidate any other
28 // reasons why the executable file might be covered by the GNU General
31 // Copyright (C) 2004 Ami Tavory and Vladimir Dreizin, IBM-HRL.
33 // Permission to use, copy, modify, sell, and distribute this software
34 // is hereby granted without fee, provided that the above copyright
35 // notice appears in all copies, and that both that copyright notice
36 // and this permission notice appear in supporting documentation. None
37 // of the above authors, nor IBM Haifa Research Laboratories, make any
38 // representation about the suitability of this software for any
39 // purpose. It is provided "as is" without express or implied
43 * @file hash_policy.hpp
44 * Contains hash-related policies.
47 #ifndef PB_DS_HASH_POLICY_HPP
48 #define PB_DS_HASH_POLICY_HPP
53 #include <ext/pb_ds/exception.hpp>
54 #include <ext/pb_ds/detail/type_utils.hpp>
55 #include <ext/pb_ds/detail/hash_fn/mask_based_range_hashing.hpp>
56 #include <ext/pb_ds/detail/hash_fn/mod_based_range_hashing.hpp>
57 #include <ext/pb_ds/detail/resize_policy/hash_load_check_resize_trigger_size_base.hpp>
61 // A null hash function, indicating that the combining hash function
62 // is actually a ranged hash function.
66 // A null probe function, indicating that the combining probe
67 // function is actually a ranged probe function.
71 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
72 #define PB_DS_CLASS_C_DEC linear_probe_fn<Size_Type>
74 // A probe sequence policy using fixed increments.
75 template<typename Size_Type = size_t>
79 typedef Size_Type size_type;
82 swap(PB_DS_CLASS_C_DEC& other);
85 // Returns the i-th offset from the hash value.
87 operator()(size_type i) const;
90 #include <ext/pb_ds/detail/hash_fn/linear_probe_fn_imp.hpp>
92 #undef PB_DS_CLASS_T_DEC
93 #undef PB_DS_CLASS_C_DEC
95 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
96 #define PB_DS_CLASS_C_DEC quadratic_probe_fn<Size_Type>
98 // A probe sequence policy using square increments.
99 template<typename Size_Type = size_t>
100 class quadratic_probe_fn
103 typedef Size_Type size_type;
106 swap(PB_DS_CLASS_C_DEC& other);
109 // Returns the i-th offset from the hash value.
111 operator()(size_type i) const;
114 #include <ext/pb_ds/detail/hash_fn/quadratic_probe_fn_imp.hpp>
116 #undef PB_DS_CLASS_T_DEC
117 #undef PB_DS_CLASS_C_DEC
119 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
120 #define PB_DS_CLASS_C_DEC direct_mask_range_hashing<Size_Type>
122 // A mask range-hashing class (uses a bit-mask).
123 template<typename Size_Type = size_t>
124 class direct_mask_range_hashing
125 : public detail::mask_based_range_hashing<Size_Type>
128 typedef detail::mask_based_range_hashing<Size_Type> mask_based_base;
131 typedef Size_Type size_type;
134 swap(PB_DS_CLASS_C_DEC& other);
138 notify_resized(size_type size);
140 // Transforms the __hash value hash into a ranged-hash value
141 // (using a bit-mask).
143 operator()(size_type hash) const;
146 #include <ext/pb_ds/detail/hash_fn/direct_mask_range_hashing_imp.hpp>
148 #undef PB_DS_CLASS_T_DEC
149 #undef PB_DS_CLASS_C_DEC
151 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
152 #define PB_DS_CLASS_C_DEC direct_mod_range_hashing<Size_Type>
154 // A mod range-hashing class (uses the modulo function).
155 template<typename Size_Type = size_t>
156 class direct_mod_range_hashing
157 : public detail::mod_based_range_hashing<Size_Type>
160 typedef Size_Type size_type;
163 swap(PB_DS_CLASS_C_DEC& other);
167 notify_resized(size_type size);
169 // Transforms the __hash value hash into a ranged-hash value
170 // (using a modulo operation).
172 operator()(size_type hash) const;
175 typedef detail::mod_based_range_hashing<size_type> mod_based_base;
178 #include <ext/pb_ds/detail/hash_fn/direct_mod_range_hashing_imp.hpp>
180 #undef PB_DS_CLASS_T_DEC
181 #undef PB_DS_CLASS_C_DEC
183 #define PB_DS_CLASS_T_DEC template<bool External_Load_Access, typename Size_Type>
184 #define PB_DS_CLASS_C_DEC hash_load_check_resize_trigger<External_Load_Access, Size_Type>
185 #define PB_DS_SIZE_BASE_C_DEC detail::hash_load_check_resize_trigger_size_base<Size_Type, External_Load_Access>
187 // A resize trigger policy based on a load check. It keeps the
188 // load factor between some load factors load_min and load_max.
189 template<bool External_Load_Access = false, typename Size_Type = size_t>
190 class hash_load_check_resize_trigger : private PB_DS_SIZE_BASE_C_DEC
193 typedef Size_Type size_type;
197 external_load_access = External_Load_Access
200 // Default constructor, or constructor taking load_min and
201 // load_max load factors between which this policy will keep the
203 hash_load_check_resize_trigger(float load_min = 0.125,
204 float load_max = 0.5);
207 swap(hash_load_check_resize_trigger& other);
210 ~hash_load_check_resize_trigger();
212 // Returns a pair of the minimal and maximal loads, respectively.
213 inline std::pair<float, float>
216 // Sets the loads through a pair of the minimal and maximal
217 // loads, respectively.
219 set_loads(std::pair<float, float> load_pair);
223 notify_insert_search_start();
226 notify_insert_search_collision();
229 notify_insert_search_end();
232 notify_find_search_start();
235 notify_find_search_collision();
238 notify_find_search_end();
241 notify_erase_search_start();
244 notify_erase_search_collision();
247 notify_erase_search_end();
249 // Notifies an element was inserted. The total number of entries
250 // in the table is num_entries.
252 notify_inserted(size_type num_entries);
255 notify_erased(size_type num_entries);
257 // Notifies the table was cleared.
261 // Notifies the table was resized as a result of this object's
262 // signifying that a resize is needed.
264 notify_resized(size_type new_size);
267 notify_externally_resized(size_type new_size);
270 is_resize_needed() const;
273 is_grow_needed(size_type size, size_type num_entries) const;
277 do_resize(size_type new_size);
279 typedef PB_DS_SIZE_BASE_C_DEC size_base;
281 #ifdef _GLIBCXX_DEBUG
283 assert_valid() const;
288 size_type m_next_shrink_size;
289 size_type m_next_grow_size;
290 bool m_resize_needed;
293 #include <ext/pb_ds/detail/resize_policy/hash_load_check_resize_trigger_imp.hpp>
295 #undef PB_DS_CLASS_T_DEC
296 #undef PB_DS_CLASS_C_DEC
297 #undef PB_DS_SIZE_BASE_C_DEC
299 #define PB_DS_CLASS_T_DEC template<bool External_Load_Access, typename Size_Type>
300 #define PB_DS_CLASS_C_DEC cc_hash_max_collision_check_resize_trigger<External_Load_Access, Size_Type>
302 // A resize trigger policy based on collision checks. It keeps the
303 // simulated load factor lower than some given load factor.
304 template<bool External_Load_Access = false, typename Size_Type = size_t>
305 class cc_hash_max_collision_check_resize_trigger
308 typedef Size_Type size_type;
312 external_load_access = External_Load_Access
315 // Default constructor, or constructor taking load, a __load
316 // factor which it will attempt to maintain.
317 cc_hash_max_collision_check_resize_trigger(float load = 0.5);
320 swap(PB_DS_CLASS_C_DEC& other);
322 // Returns the current load.
326 // Sets the load; does not resize the container.
328 set_load(float load);
332 notify_insert_search_start();
335 notify_insert_search_collision();
338 notify_insert_search_end();
341 notify_find_search_start();
344 notify_find_search_collision();
347 notify_find_search_end();
350 notify_erase_search_start();
353 notify_erase_search_collision();
356 notify_erase_search_end();
359 notify_inserted(size_type num_entries);
362 notify_erased(size_type num_entries);
367 // Notifies the table was resized as a result of this object's
368 // signifying that a resize is needed.
370 notify_resized(size_type new_size);
373 notify_externally_resized(size_type new_size);
376 is_resize_needed() const;
379 is_grow_needed(size_type size, size_type num_entries) const;
386 calc_resize_needed();
392 bool m_resize_needed;
395 #include <ext/pb_ds/detail/resize_policy/cc_hash_max_collision_check_resize_trigger_imp.hpp>
397 #undef PB_DS_CLASS_T_DEC
398 #undef PB_DS_CLASS_C_DEC
400 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
401 #define PB_DS_CLASS_C_DEC hash_exponential_size_policy<Size_Type>
403 // A size policy whose sequence of sizes form an exponential
404 // sequence (typically powers of 2.
405 template<typename Size_Type = size_t>
406 class hash_exponential_size_policy
409 typedef Size_Type size_type;
411 // Default constructor, or onstructor taking a start_size, or
412 // constructor taking a start size and grow_factor. The policy
413 // will use the sequence of sizes start_size, start_size*
414 // grow_factor, start_size* grow_factor^2, ...
415 hash_exponential_size_policy(size_type start_size = 8,
416 size_type grow_factor = 2);
419 swap(PB_DS_CLASS_C_DEC& other);
423 get_nearest_larger_size(size_type size) const;
426 get_nearest_smaller_size(size_type size) const;
429 size_type m_start_size;
430 size_type m_grow_factor;
433 #include <ext/pb_ds/detail/resize_policy/hash_exponential_size_policy_imp.hpp>
435 #undef PB_DS_CLASS_T_DEC
436 #undef PB_DS_CLASS_C_DEC
438 #define PB_DS_CLASS_T_DEC
439 #define PB_DS_CLASS_C_DEC hash_prime_size_policy
441 // A size policy whose sequence of sizes form a nearly-exponential
442 // sequence of primes.
443 class hash_prime_size_policy
447 typedef size_t size_type;
449 // Default constructor, or onstructor taking a start_size The
450 // policy will use the sequence of sizes approximately
451 // start_size, start_size* 2, start_size* 2^2, ...
452 hash_prime_size_policy(size_type start_size = 8);
455 swap(PB_DS_CLASS_C_DEC& other);
459 get_nearest_larger_size(size_type size) const;
462 get_nearest_smaller_size(size_type size) const;
465 size_type m_start_size;
468 #include <ext/pb_ds/detail/resize_policy/hash_prime_size_policy_imp.hpp>
470 #undef PB_DS_CLASS_T_DEC
471 #undef PB_DS_CLASS_C_DEC
473 #define PB_DS_CLASS_T_DEC template<typename Size_Policy, typename Trigger_Policy, bool External_Size_Access, typename Size_Type>
475 #define PB_DS_CLASS_C_DEC hash_standard_resize_policy<Size_Policy, Trigger_Policy, External_Size_Access, Size_Type>
477 // A resize policy which delegates operations to size and trigger policies.
478 template<typename Size_Policy = hash_exponential_size_policy<>,
479 typename Trigger_Policy = hash_load_check_resize_trigger<>,
480 bool External_Size_Access = false,
481 typename Size_Type = size_t>
482 class hash_standard_resize_policy
483 : public Size_Policy, public Trigger_Policy
486 typedef Size_Type size_type;
487 typedef Trigger_Policy trigger_policy;
488 typedef Size_Policy size_policy;
492 external_size_access = External_Size_Access
495 // Default constructor.
496 hash_standard_resize_policy();
498 // constructor taking some policies r_size_policy will be copied
499 // by the Size_Policy object of this object.
500 hash_standard_resize_policy(const Size_Policy& r_size_policy);
502 // constructor taking some policies. r_size_policy will be
503 // copied by the Size_Policy object of this
504 // object. r_trigger_policy will be copied by the Trigger_Policy
505 // object of this object.
506 hash_standard_resize_policy(const Size_Policy& r_size_policy,
507 const Trigger_Policy& r_trigger_policy);
510 ~hash_standard_resize_policy();
513 swap(PB_DS_CLASS_C_DEC& other);
515 // Access to the Size_Policy object used.
519 // Const access to the Size_Policy object used.
521 get_size_policy() const;
523 // Access to the Trigger_Policy object used.
525 get_trigger_policy();
527 // Access to the Trigger_Policy object used.
528 const Trigger_Policy&
529 get_trigger_policy() const;
531 // Returns the actual size of the container.
533 get_actual_size() const;
535 // Resizes the container to suggested_new_size, a suggested size
536 // (the actual size will be determined by the Size_Policy
539 resize(size_type suggested_new_size);
543 notify_insert_search_start();
546 notify_insert_search_collision();
549 notify_insert_search_end();
552 notify_find_search_start();
555 notify_find_search_collision();
558 notify_find_search_end();
561 notify_erase_search_start();
564 notify_erase_search_collision();
567 notify_erase_search_end();
570 notify_inserted(size_type num_e);
573 notify_erased(size_type num_e);
579 notify_resized(size_type new_size);
582 is_resize_needed() const;
584 // Queries what the new size should be, when the container is
585 // resized naturally. The current __size of the container is
586 // size, and the number of used entries within the container is
589 get_new_size(size_type size, size_type num_used_e) const;
592 // Resizes to new_size.
594 do_resize(size_type new_size);
596 typedef Trigger_Policy trigger_policy_base;
598 typedef Size_Policy size_policy_base;
603 #include <ext/pb_ds/detail/resize_policy/hash_standard_resize_policy_imp.hpp>
605 #undef PB_DS_CLASS_T_DEC
606 #undef PB_DS_CLASS_C_DEC