libstdc++-v3/include/ext/pb_ds/hash_policy.hpp

   1 // -*- C++ -*-
   2
   3 // Copyright (C) 2005, 2006 Free Software Foundation, Inc.
   4 //
   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
   9 // version.
  10
  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.
  15
  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.
  20
  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
  29 // Public License.
  30
  31 // Copyright (C) 2004 Ami Tavory and Vladimir Dreizin, IBM-HRL.
  32
  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
  40 // warranty.
  41
  42 /**
  43  * @file hash_policy.hpp
  44  * Contains hash-related policies.
  45  */
  46
  47 #ifndef PB_DS_HASH_POLICY_HPP
  48 #define PB_DS_HASH_POLICY_HPP
  49
  50 #include <algorithm>
  51 #include <vector>
  52 #include <cmath>
  53 #include <ext/pb_ds/exception.hpp>
  54 #include <ext/pb_ds/detail/hash_fn/mask_based_range_hashing.hpp>
  55 #include <ext/pb_ds/detail/hash_fn/mod_based_range_hashing.hpp>
  56 #include <ext/pb_ds/detail/resize_policy/hash_load_check_resize_trigger_size_base.hpp>
  57
  58 namespace pb_ds
  59 {
  60   // A null hash function, indicating that the combining hash function
  61   // is actually a ranged hash function.
  62   struct null_hash_fn
  63   { };
  64
  65   // A null probe function, indicating that the combining probe
  66   // function is actually a ranged probe function.
  67   struct null_probe_fn
  68   { };
  69
  70 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
  71 #define PB_DS_CLASS_C_DEC linear_probe_fn<Size_Type>
  72
  73   // A probe sequence policy using fixed increments.
  74   template<typename Size_Type = size_t>
  75   class linear_probe_fn
  76   {
  77   public:
  78     typedef Size_Type size_type;
  79
  80     void
  81     swap(PB_DS_CLASS_C_DEC& other);
  82
  83   protected:
  84     // Returns the i-th offset from the hash value.
  85     inline size_type
  86     operator()(size_type i) const;
  87   };
  88
  89 #include <ext/pb_ds/detail/hash_fn/linear_probe_fn_imp.hpp>
  90
  91 #undef PB_DS_CLASS_T_DEC
  92 #undef PB_DS_CLASS_C_DEC
  93
  94 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
  95 #define PB_DS_CLASS_C_DEC quadratic_probe_fn<Size_Type>
  96
  97   // A probe sequence policy using square increments.
  98   template<typename Size_Type = size_t>
  99   class quadratic_probe_fn
 100   {
 101   public:
 102     typedef Size_Type size_type;
 103
 104     void
 105     swap(PB_DS_CLASS_C_DEC& other);
 106
 107   protected:
 108     // Returns the i-th offset from the hash value.
 109     inline size_type
 110     operator()(size_type i) const;
 111   };
 112
 113 #include <ext/pb_ds/detail/hash_fn/quadratic_probe_fn_imp.hpp>
 114
 115 #undef PB_DS_CLASS_T_DEC
 116 #undef PB_DS_CLASS_C_DEC
 117
 118 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
 119 #define PB_DS_CLASS_C_DEC direct_mask_range_hashing<Size_Type>
 120
 121   // A mask range-hashing class (uses a bit-mask).
 122   template<typename Size_Type = size_t>
 123   class direct_mask_range_hashing
 124   : public detail::mask_based_range_hashing<Size_Type>
 125   {
 126   private:
 127     typedef detail::mask_based_range_hashing<Size_Type> mask_based_base;
 128
 129   public:
 130     typedef Size_Type size_type;
 131
 132     void
 133     swap(PB_DS_CLASS_C_DEC& other);
 134
 135   protected:
 136     void
 137     notify_resized(size_type size);
 138
 139     // Transforms the __hash value hash into a ranged-hash value
 140     // (using a bit-mask).
 141     inline size_type
 142     operator()(size_type hash) const;
 143   };
 144
 145 #include <ext/pb_ds/detail/hash_fn/direct_mask_range_hashing_imp.hpp>
 146
 147 #undef PB_DS_CLASS_T_DEC
 148 #undef PB_DS_CLASS_C_DEC
 149
 150 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
 151 #define PB_DS_CLASS_C_DEC direct_mod_range_hashing<Size_Type>
 152
 153   // A mod range-hashing class (uses the modulo function).
 154   template<typename Size_Type = size_t>
 155   class direct_mod_range_hashing
 156   : public detail::mod_based_range_hashing<Size_Type>
 157   {
 158   public:
 159     typedef Size_Type size_type;
 160
 161     void
 162     swap(PB_DS_CLASS_C_DEC& other);
 163
 164   protected:
 165     void
 166     notify_resized(size_type size);
 167
 168     // Transforms the __hash value hash into a ranged-hash value
 169     // (using a modulo operation).
 170     inline size_type
 171     operator()(size_type hash) const;
 172
 173   private:
 174     typedef detail::mod_based_range_hashing<size_type> mod_based_base;
 175   };
 176
 177 #include <ext/pb_ds/detail/hash_fn/direct_mod_range_hashing_imp.hpp>
 178
 179 #undef PB_DS_CLASS_T_DEC
 180 #undef PB_DS_CLASS_C_DEC
 181
 182 #define PB_DS_CLASS_T_DEC template<bool External_Load_Access, typename Size_Type>
 183 #define PB_DS_CLASS_C_DEC hash_load_check_resize_trigger<External_Load_Access, Size_Type>
 184 #define PB_DS_SIZE_BASE_C_DEC detail::hash_load_check_resize_trigger_size_base<Size_Type, External_Load_Access>
 185
 186   // A resize trigger policy based on a load check. It keeps the
 187   // load factor between some load factors load_min and load_max.
 188   template<bool External_Load_Access = false, typename Size_Type = size_t>
 189   class hash_load_check_resize_trigger : private PB_DS_SIZE_BASE_C_DEC
 190   {
 191   public:
 192     typedef Size_Type size_type;
 193
 194     enum
 195       {
 196         external_load_access = External_Load_Access
 197       };
 198
 199     // Default constructor, or constructor taking load_min and
 200     // load_max load factors between which this policy will keep the
 201     // actual load.
 202     hash_load_check_resize_trigger(float load_min = 0.125,
 203                                    float load_max = 0.5);
 204
 205     void
 206     swap(hash_load_check_resize_trigger& other);
 207
 208     virtual
 209     ~hash_load_check_resize_trigger();
 210
 211     // Returns a pair of the minimal and maximal loads, respectively.
 212     inline std::pair<float, float>
 213     get_loads() const;
 214
 215     // Sets the loads through a pair of the minimal and maximal
 216     // loads, respectively.
 217     void
 218     set_loads(std::pair<float, float> load_pair);
 219
 220   protected:
 221     inline void
 222     notify_insert_search_start();
 223
 224     inline void
 225     notify_insert_search_collision();
 226
 227     inline void
 228     notify_insert_search_end();
 229
 230     inline void
 231     notify_find_search_start();
 232
 233     inline void
 234     notify_find_search_collision();
 235
 236     inline void
 237     notify_find_search_end();
 238
 239     inline void
 240     notify_erase_search_start();
 241
 242     inline void
 243     notify_erase_search_collision();
 244
 245     inline void
 246     notify_erase_search_end();
 247
 248     // Notifies an element was inserted. The total number of entries
 249     // in the table is num_entries.
 250     inline void
 251     notify_inserted(size_type num_entries);
 252
 253     inline void
 254     notify_erased(size_type num_entries);
 255
 256     // Notifies the table was cleared.
 257     void
 258     notify_cleared();
 259
 260     // Notifies the table was resized as a result of this object's
 261     // signifying that a resize is needed.
 262     void
 263     notify_resized(size_type new_size);
 264
 265     void
 266     notify_externally_resized(size_type new_size);
 267
 268     inline bool
 269     is_resize_needed() const;
 270
 271     inline bool
 272     is_grow_needed(size_type size, size_type num_entries) const;
 273
 274   private:
 275     virtual void
 276     do_resize(size_type new_size);
 277
 278     typedef PB_DS_SIZE_BASE_C_DEC size_base;
 279
 280 #ifdef _GLIBCXX_DEBUG
 281     void
 282     assert_valid() const;
 283 #endif
 284
 285     float       m_load_min;
 286     float       m_load_max;
 287     size_type   m_next_shrink_size;
 288     size_type   m_next_grow_size;
 289     bool        m_resize_needed;
 290   };
 291
 292 #include <ext/pb_ds/detail/resize_policy/hash_load_check_resize_trigger_imp.hpp>
 293
 294 #undef PB_DS_CLASS_T_DEC
 295 #undef PB_DS_CLASS_C_DEC
 296 #undef PB_DS_SIZE_BASE_C_DEC
 297
 298 #define PB_DS_CLASS_T_DEC template<bool External_Load_Access, typename Size_Type>
 299 #define PB_DS_CLASS_C_DEC cc_hash_max_collision_check_resize_trigger<External_Load_Access, Size_Type>
 300
 301   // A resize trigger policy based on collision checks. It keeps the
 302   // simulated load factor lower than some given load factor.
 303   template<bool External_Load_Access = false, typename Size_Type = size_t>
 304   class cc_hash_max_collision_check_resize_trigger
 305   {
 306   public:
 307     typedef Size_Type size_type;
 308
 309     enum
 310       {
 311         external_load_access = External_Load_Access
 312       };
 313
 314     // Default constructor, or constructor taking load, a __load
 315     // factor which it will attempt to maintain.
 316     cc_hash_max_collision_check_resize_trigger(float load = 0.5);
 317
 318     void
 319     swap(PB_DS_CLASS_C_DEC& other);
 320
 321     // Returns the current load.
 322     inline float
 323     get_load() const;
 324
 325     // Sets the load; does not resize the container.
 326     void
 327     set_load(float load);
 328
 329   protected:
 330     inline void
 331     notify_insert_search_start();
 332
 333     inline void
 334     notify_insert_search_collision();
 335
 336     inline void
 337     notify_insert_search_end();
 338
 339     inline void
 340     notify_find_search_start();
 341
 342     inline void
 343     notify_find_search_collision();
 344
 345     inline void
 346     notify_find_search_end();
 347
 348     inline void
 349     notify_erase_search_start();
 350
 351     inline void
 352     notify_erase_search_collision();
 353
 354     inline void
 355     notify_erase_search_end();
 356
 357     inline void
 358     notify_inserted(size_type num_entries);
 359
 360     inline void
 361     notify_erased(size_type num_entries);
 362
 363     void
 364     notify_cleared();
 365
 366     // Notifies the table was resized as a result of this object's
 367     // signifying that a resize is needed.
 368     void
 369     notify_resized(size_type new_size);
 370
 371     void
 372     notify_externally_resized(size_type new_size);
 373
 374     inline bool
 375     is_resize_needed() const;
 376
 377     inline bool
 378     is_grow_needed(size_type size, size_type num_entries) const;
 379
 380   private:
 381     void
 382     calc_max_num_coll();
 383
 384     inline void
 385     calc_resize_needed();
 386
 387     float       m_load;
 388     size_type   m_size;
 389     size_type   m_num_col;
 390     size_type   m_max_col;
 391     bool        m_resize_needed;
 392   };
 393
 394 #include <ext/pb_ds/detail/resize_policy/cc_hash_max_collision_check_resize_trigger_imp.hpp>
 395
 396 #undef PB_DS_CLASS_T_DEC
 397 #undef PB_DS_CLASS_C_DEC
 398
 399 #define PB_DS_CLASS_T_DEC template<typename Size_Type>
 400 #define PB_DS_CLASS_C_DEC hash_exponential_size_policy<Size_Type>
 401
 402   // A size policy whose sequence of sizes form an exponential
 403   // sequence (typically powers of 2.
 404   template<typename Size_Type = size_t>
 405   class hash_exponential_size_policy
 406   {
 407   public:
 408     typedef Size_Type size_type;
 409
 410     // Default constructor, or onstructor taking a start_size, or
 411     // constructor taking a start size and grow_factor. The policy
 412     // will use the sequence of sizes start_size, start_size*
 413     // grow_factor, start_size* grow_factor^2, ...
 414     hash_exponential_size_policy(size_type start_size = 8,
 415                                  size_type grow_factor = 2);
 416
 417     void
 418     swap(PB_DS_CLASS_C_DEC& other);
 419
 420   protected:
 421     size_type
 422     get_nearest_larger_size(size_type size) const;
 423
 424     size_type
 425     get_nearest_smaller_size(size_type size) const;
 426
 427   private:
 428     size_type m_start_size;
 429     size_type m_grow_factor;
 430   };
 431
 432 #include <ext/pb_ds/detail/resize_policy/hash_exponential_size_policy_imp.hpp>
 433
 434 #undef PB_DS_CLASS_T_DEC
 435 #undef PB_DS_CLASS_C_DEC
 436
 437 #define PB_DS_CLASS_T_DEC
 438 #define PB_DS_CLASS_C_DEC hash_prime_size_policy
 439
 440   // A size policy whose sequence of sizes form a nearly-exponential
 441   // sequence of primes.
 442   class hash_prime_size_policy
 443   {
 444   public:
 445     // Size type.
 446     typedef size_t size_type;
 447
 448     // Default constructor, or onstructor taking a start_size The
 449     // policy will use the sequence of sizes approximately
 450     // start_size, start_size* 2, start_size* 2^2, ...
 451     hash_prime_size_policy(size_type start_size = 8);
 452
 453     inline void
 454     swap(PB_DS_CLASS_C_DEC& other);
 455
 456   protected:
 457     size_type
 458     get_nearest_larger_size(size_type size) const;
 459
 460     size_type
 461     get_nearest_smaller_size(size_type size) const;
 462
 463   private:
 464     size_type m_start_size;
 465   };
 466
 467 #include <ext/pb_ds/detail/resize_policy/hash_prime_size_policy_imp.hpp>
 468
 469 #undef PB_DS_CLASS_T_DEC
 470 #undef PB_DS_CLASS_C_DEC
 471
 472 #define PB_DS_CLASS_T_DEC template<typename Size_Policy, typename Trigger_Policy, bool External_Size_Access, typename Size_Type>
 473
 474 #define PB_DS_CLASS_C_DEC hash_standard_resize_policy<Size_Policy, Trigger_Policy, External_Size_Access, Size_Type>
 475
 476   // A resize policy which delegates operations to size and trigger policies.
 477   template<typename Size_Policy = hash_exponential_size_policy<>,
 478            typename Trigger_Policy = hash_load_check_resize_trigger<>,
 479            bool External_Size_Access = false,
 480            typename Size_Type = size_t>
 481   class hash_standard_resize_policy
 482   : public Size_Policy, public Trigger_Policy
 483   {
 484   public:
 485     typedef Size_Type           size_type;
 486     typedef Trigger_Policy      trigger_policy;
 487     typedef Size_Policy         size_policy;
 488
 489     enum
 490       {
 491         external_size_access = External_Size_Access
 492       };
 493
 494     // Default constructor.
 495     hash_standard_resize_policy();
 496
 497     // constructor taking some policies r_size_policy will be copied
 498     // by the Size_Policy object of this object.
 499     hash_standard_resize_policy(const Size_Policy& r_size_policy);
 500
 501     // constructor taking some policies. r_size_policy will be
 502     // copied by the Size_Policy object of this
 503     // object. r_trigger_policy will be copied by the Trigger_Policy
 504     // object of this object.
 505     hash_standard_resize_policy(const Size_Policy& r_size_policy,
 506                                 const Trigger_Policy& r_trigger_policy);
 507
 508     virtual
 509     ~hash_standard_resize_policy();
 510
 511     inline void
 512     swap(PB_DS_CLASS_C_DEC& other);
 513
 514     // Access to the Size_Policy object used.
 515     Size_Policy&
 516     get_size_policy();
 517
 518     // Const access to the Size_Policy object used.
 519     const Size_Policy&
 520     get_size_policy() const;
 521
 522     // Access to the Trigger_Policy object used.
 523     Trigger_Policy&
 524     get_trigger_policy();
 525
 526     // Access to the Trigger_Policy object used.
 527     const Trigger_Policy&
 528     get_trigger_policy() const;
 529
 530     // Returns the actual size of the container.
 531     inline size_type
 532     get_actual_size() const;
 533
 534     // Resizes the container to suggested_new_size, a suggested size
 535     // (the actual size will be determined by the Size_Policy
 536     // object).
 537     void
 538     resize(size_type suggested_new_size);
 539
 540   protected:
 541     inline void
 542     notify_insert_search_start();
 543
 544     inline void
 545     notify_insert_search_collision();
 546
 547     inline void
 548     notify_insert_search_end();
 549
 550     inline void
 551     notify_find_search_start();
 552
 553     inline void
 554     notify_find_search_collision();
 555
 556     inline void
 557     notify_find_search_end();
 558
 559     inline void
 560     notify_erase_search_start();
 561
 562     inline void
 563     notify_erase_search_collision();
 564
 565     inline void
 566     notify_erase_search_end();
 567
 568     inline void
 569     notify_inserted(size_type num_e);
 570
 571     inline void
 572     notify_erased(size_type num_e);
 573
 574     void
 575     notify_cleared();
 576
 577     void
 578     notify_resized(size_type new_size);
 579
 580     inline bool
 581     is_resize_needed() const;
 582
 583     // Queries what the new size should be, when the container is
 584     // resized naturally. The current __size of the container is
 585     // size, and the number of used entries within the container is
 586     // num_used_e.
 587     size_type
 588     get_new_size(size_type size, size_type num_used_e) const;
 589
 590   private:
 591     // Resizes to new_size.
 592     virtual void
 593     do_resize(size_type new_size);
 594
 595     typedef Trigger_Policy trigger_policy_base;
 596
 597     typedef Size_Policy size_policy_base;
 598
 599     size_type m_size;
 600   };
 601
 602 #include <ext/pb_ds/detail/resize_policy/hash_standard_resize_policy_imp.hpp>
 603
 604 #undef PB_DS_CLASS_T_DEC
 605 #undef PB_DS_CLASS_C_DEC
 606
 607 } // namespace pb_ds
 608
 609 #endif