From 554fd8c5195424bdbcabf5de30fdc183aba391bd Mon Sep 17 00:00:00 2001 From: upstream source tree Date: Sun, 15 Mar 2015 20:14:05 -0400 Subject: obtained gcc-4.6.4.tar.bz2 from upstream website; verified gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream tarball. downloading a git-generated archive based on the 'upstream' tag should provide you with a source tree that is binary identical to the one extracted from the above tarball. if you have obtained the source via the command 'git clone', however, do note that line-endings of files in your working directory might differ from line-endings of the respective files in the upstream repository. --- .../doc/html/ext/pb_ds/PythonPoweredSmall.gif | Bin 0 -> 361 bytes libstdc++-v3/doc/html/ext/pb_ds/acks.html | 65 ++ .../doc/html/ext/pb_ds/assoc_container_tag_cd.png | Bin 0 -> 21668 bytes .../doc/html/ext/pb_ds/assoc_container_tag_cd.svg | 491 +++++++++ .../doc/html/ext/pb_ds/assoc_container_traits.html | 170 ++++ libstdc++-v3/doc/html/ext/pb_ds/assoc_design.html | 46 + .../doc/html/ext/pb_ds/assoc_examples.html | 151 +++ .../html/ext/pb_ds/assoc_performance_tests.html | 345 +++++++ .../doc/html/ext/pb_ds/assoc_regression_tests.html | 93 ++ libstdc++-v3/doc/html/ext/pb_ds/assoc_tests.html | 24 + .../html/ext/pb_ds/associative_container_tag.html | 47 + libstdc++-v3/doc/html/ext/pb_ds/balls_and_bins.png | Bin 0 -> 10139 bytes .../doc/html/ext/pb_ds/basic_hash_table.html | 436 ++++++++ .../doc/html/ext/pb_ds/basic_hash_tag.html | 47 + .../ext/pb_ds/basic_invalidation_guarantee.html | 26 + libstdc++-v3/doc/html/ext/pb_ds/basic_tree.html | 660 ++++++++++++ ...c_tree_assoc_container_const_node_iterator.html | 383 +++++++ .../doc/html/ext/pb_ds/basic_tree_tag.html | 47 + .../doc/html/ext/pb_ds/binary_heap_tag.html | 47 + ...ority_queue_random_int_push_timing_test_gcc.png | Bin 0 -> 5357 bytes ...ity_queue_random_int_push_timing_test_local.png | Bin 0 -> 6710 bytes ...rity_queue_random_int_push_timing_test_msvc.png | Bin 0 -> 5373 bytes .../doc/html/ext/pb_ds/binomial_heap_tag.html | 47 + ...cc_hash_max_collision_check_resize_trigger.html | 532 ++++++++++ .../cc_hash_random_int_find_timing_test_gcc.png | Bin 0 -> 7074 bytes .../cc_hash_random_int_find_timing_test_local.png | Bin 0 -> 8534 bytes .../cc_hash_random_int_find_timing_test_msvc.png | Bin 0 -> 7235 bytes ...h_random_int_subscript_timing_test_find_gcc.png | Bin 0 -> 6811 bytes ...random_int_subscript_timing_test_find_local.png | Bin 0 -> 8445 bytes ..._random_int_subscript_timing_test_find_msvc.png | Bin 0 -> 7230 bytes ...random_int_subscript_timing_test_insert_gcc.png | Bin 0 -> 7636 bytes ...ndom_int_subscript_timing_test_insert_local.png | Bin 0 -> 9396 bytes ...andom_int_subscript_timing_test_insert_msvc.png | Bin 0 -> 6840 bytes libstdc++-v3/doc/html/ext/pb_ds/cc_hash_table.html | 724 +++++++++++++ libstdc++-v3/doc/html/ext/pb_ds/cc_hash_tag.html | 47 + ...random_int_subscript_timing_test_insert_gcc.png | Bin 0 -> 7355 bytes ...ndom_int_subscript_timing_test_insert_local.png | Bin 0 -> 9557 bytes ...andom_int_subscript_timing_test_insert_msvc.png | Bin 0 -> 7572 bytes .../doc/html/ext/pb_ds/checked_by_tidy.gif | Bin 0 -> 1367 bytes libstdc++-v3/doc/html/ext/pb_ds/concepts.html | 118 +++ libstdc++-v3/doc/html/ext/pb_ds/contact.html | 22 + .../doc/html/ext/pb_ds/container_base.html | 1063 ++++++++++++++++++++ libstdc++-v3/doc/html/ext/pb_ds/container_cd.png | Bin 0 -> 11884 bytes libstdc++-v3/doc/html/ext/pb_ds/container_cd.svg | 418 ++++++++ libstdc++-v3/doc/html/ext/pb_ds/container_tag.html | 24 + .../doc/html/ext/pb_ds/counter_lu_policy.html | 259 +++++ libstdc++-v3/doc/html/ext/pb_ds/design.html | 96 ++ .../html/ext/pb_ds/different_underlying_dss.png | Bin 0 -> 31858 bytes .../html/ext/pb_ds/direct_mask_range_hashing.html | 167 +++ .../html/ext/pb_ds/direct_mod_range_hashing.html | 144 +++ libstdc++-v3/doc/html/ext/pb_ds/disclaimer.html | 34 + libstdc++-v3/doc/html/ext/pb_ds/ds_gen.html | 344 +++++++ .../doc/html/ext/pb_ds/embedded_lists_1.png | Bin 0 -> 16350 bytes .../doc/html/ext/pb_ds/embedded_lists_2.png | Bin 0 -> 18206 bytes .../doc/html/ext/pb_ds/embedded_lists_3.png | Bin 0 -> 5612 bytes libstdc++-v3/doc/html/ext/pb_ds/examples.html | 24 + libstdc++-v3/doc/html/ext/pb_ds/exceptions.html | 46 + .../gp_hash_random_int_find_timing_test_gcc.png | Bin 0 -> 6194 bytes .../gp_hash_random_int_find_timing_test_local.png | Bin 0 -> 7916 bytes .../gp_hash_random_int_find_timing_test_msvc.png | Bin 0 -> 6140 bytes ...h_random_int_subscript_timing_test_find_gcc.png | Bin 0 -> 6110 bytes ...random_int_subscript_timing_test_find_local.png | Bin 0 -> 7570 bytes ..._random_int_subscript_timing_test_find_msvc.png | Bin 0 -> 6314 bytes ...random_int_subscript_timing_test_insert_gcc.png | Bin 0 -> 6763 bytes ...ndom_int_subscript_timing_test_insert_local.png | Bin 0 -> 8499 bytes ...andom_int_subscript_timing_test_insert_msvc.png | Bin 0 -> 6721 bytes libstdc++-v3/doc/html/ext/pb_ds/gp_hash_table.html | 891 ++++++++++++++++ libstdc++-v3/doc/html/ext/pb_ds/gp_hash_tag.html | 47 + .../doc/html/ext/pb_ds/hash_based_containers.html | 835 +++++++++++++++ .../ext/pb_ds/hash_exponential_size_policy.html | 183 ++++ .../ext/pb_ds/hash_load_check_resize_trigger.html | 583 +++++++++++ libstdc++-v3/doc/html/ext/pb_ds/hash_policy_cd.png | Bin 0 -> 25302 bytes .../doc/html/ext/pb_ds/hash_prime_size_policy.html | 149 +++ .../hash_random_int_erase_mem_usage_test.html | 173 ++++ .../hash_random_int_erase_mem_usage_test_gcc.png | Bin 0 -> 6356 bytes .../hash_random_int_erase_mem_usage_test_local.png | Bin 0 -> 7405 bytes .../hash_random_int_erase_mem_usage_test_msvc.png | Bin 0 -> 6401 bytes .../hash_random_int_find_find_timing_test.html | 247 +++++ ...hash_random_int_subscript_find_timing_test.html | 220 ++++ ...sh_random_int_subscript_insert_timing_test.html | 365 +++++++ .../ext/pb_ds/hash_range_hashing_seq_diagram.png | Bin 0 -> 12962 bytes .../ext/pb_ds/hash_range_hashing_seq_diagram2.png | Bin 0 -> 8918 bytes .../pb_ds/hash_ranged_hash_range_hashing_fns.png | Bin 0 -> 19773 bytes .../ext/pb_ds/hash_standard_resize_policy.html | 795 +++++++++++++++ .../ext/pb_ds/hash_text_find_find_timing_test.html | 164 +++ ...hash_zlob_random_int_find_find_timing_test.html | 163 +++ .../hash_zlob_random_int_find_timing_test_gcc.png | Bin 0 -> 6910 bytes ...hash_zlob_random_int_find_timing_test_local.png | Bin 0 -> 8436 bytes .../hash_zlob_random_int_find_timing_test_msvc.png | Bin 0 -> 7204 bytes libstdc++-v3/doc/html/ext/pb_ds/index.html | 146 +++ libstdc++-v3/doc/html/ext/pb_ds/insert_error.html | 53 + .../ext/pb_ds/insert_resize_sequence_diagram1.png | Bin 0 -> 25834 bytes .../ext/pb_ds/insert_resize_sequence_diagram2.png | Bin 0 -> 25522 bytes .../ext/pb_ds/insert_resize_sequence_diagram3.png | Bin 0 -> 24542 bytes libstdc++-v3/doc/html/ext/pb_ds/interface.html | 446 ++++++++ libstdc++-v3/doc/html/ext/pb_ds/introduction.html | 120 +++ .../html/ext/pb_ds/invalidation_guarantee_cd.png | Bin 0 -> 8331 bytes .../ext/pb_ds/invalidation_guarantee_erase.png | Bin 0 -> 25884 bytes libstdc++-v3/doc/html/ext/pb_ds/join_error.html | 48 + .../doc/html/ext/pb_ds/linear_probe_fn.html | 140 +++ libstdc++-v3/doc/html/ext/pb_ds/list_update.html | 316 ++++++ .../doc/html/ext/pb_ds/list_update_tag.html | 47 + libstdc++-v3/doc/html/ext/pb_ds/lu.png | Bin 0 -> 20987 bytes .../doc/html/ext/pb_ds/lu_based_containers.html | 229 +++++ libstdc++-v3/doc/html/ext/pb_ds/misc.html | 26 + libstdc++-v3/doc/html/ext/pb_ds/motivation.html | 993 ++++++++++++++++++ .../html/ext/pb_ds/move_to_front_lu_policy.html | 194 ++++ .../multimap_text_find_timing_test_large.html | 215 ++++ ...ap_text_find_timing_test_large_s2p_hash_gcc.png | Bin 0 -> 6323 bytes ..._text_find_timing_test_large_s2p_hash_local.png | Bin 0 -> 7299 bytes ...p_text_find_timing_test_large_s2p_hash_msvc.png | Bin 0 -> 6490 bytes ...ap_text_find_timing_test_large_s2p_tree_gcc.png | Bin 0 -> 6284 bytes ..._text_find_timing_test_large_s2p_tree_local.png | Bin 0 -> 6706 bytes ...p_text_find_timing_test_large_s2p_tree_msvc.png | Bin 0 -> 6204 bytes .../multimap_text_find_timing_test_small.html | 215 ++++ ...ap_text_find_timing_test_small_s2p_hash_gcc.png | Bin 0 -> 6237 bytes ..._text_find_timing_test_small_s2p_hash_local.png | Bin 0 -> 6732 bytes ...p_text_find_timing_test_small_s2p_hash_msvc.png | Bin 0 -> 6268 bytes ...ap_text_find_timing_test_small_s2p_tree_gcc.png | Bin 0 -> 6064 bytes ..._text_find_timing_test_small_s2p_tree_local.png | Bin 0 -> 6396 bytes ...p_text_find_timing_test_small_s2p_tree_msvc.png | Bin 0 -> 6012 bytes .../multimap_text_insert_mem_usage_test_large.html | 210 ++++ ...xt_insert_mem_usage_test_large_s2p_hash_gcc.png | Bin 0 -> 6835 bytes ..._insert_mem_usage_test_large_s2p_hash_local.png | Bin 0 -> 7275 bytes ...t_insert_mem_usage_test_large_s2p_hash_msvc.png | Bin 0 -> 6588 bytes ...xt_insert_mem_usage_test_large_s2p_tree_gcc.png | Bin 0 -> 6778 bytes ..._insert_mem_usage_test_large_s2p_tree_local.png | Bin 0 -> 7191 bytes ...t_insert_mem_usage_test_large_s2p_tree_msvc.png | Bin 0 -> 6535 bytes .../multimap_text_insert_mem_usage_test_small.html | 212 ++++ ...xt_insert_mem_usage_test_small_s2p_hash_gcc.png | Bin 0 -> 6449 bytes ..._insert_mem_usage_test_small_s2p_hash_local.png | Bin 0 -> 6845 bytes ...t_insert_mem_usage_test_small_s2p_hash_msvc.png | Bin 0 -> 6570 bytes ...xt_insert_mem_usage_test_small_s2p_tree_gcc.png | Bin 0 -> 6419 bytes ..._insert_mem_usage_test_small_s2p_tree_local.png | Bin 0 -> 6925 bytes ...t_insert_mem_usage_test_small_s2p_tree_msvc.png | Bin 0 -> 6569 bytes .../multimap_text_insert_timing_test_large.html | 212 ++++ ..._text_insert_timing_test_large_s2p_hash_gcc.png | Bin 0 -> 6380 bytes ...ext_insert_timing_test_large_s2p_hash_local.png | Bin 0 -> 7000 bytes ...text_insert_timing_test_large_s2p_hash_msvc.png | Bin 0 -> 6460 bytes ..._text_insert_timing_test_large_s2p_tree_gcc.png | Bin 0 -> 6204 bytes ...ext_insert_timing_test_large_s2p_tree_local.png | Bin 0 -> 6764 bytes ...text_insert_timing_test_large_s2p_tree_msvc.png | Bin 0 -> 6357 bytes .../multimap_text_insert_timing_test_small.html | 217 ++++ ..._text_insert_timing_test_small_s2p_hash_gcc.png | Bin 0 -> 6456 bytes ...ext_insert_timing_test_small_s2p_hash_local.png | Bin 0 -> 7035 bytes ...text_insert_timing_test_small_s2p_hash_msvc.png | Bin 0 -> 6547 bytes ..._text_insert_timing_test_small_s2p_tree_gcc.png | Bin 0 -> 6111 bytes ...ext_insert_timing_test_small_s2p_tree_local.png | Bin 0 -> 6853 bytes ...text_insert_timing_test_small_s2p_tree_msvc.png | Bin 0 -> 6430 bytes .../ext/pb_ds/node_invariant_invalidations.png | Bin 0 -> 32276 bytes .../doc/html/ext/pb_ds/node_invariants.png | Bin 0 -> 16553 bytes libstdc++-v3/doc/html/ext/pb_ds/null_hash_fn.html | 32 + .../doc/html/ext/pb_ds/null_lu_metadata.html | 25 + .../doc/html/ext/pb_ds/null_mapped_type.html | 25 + libstdc++-v3/doc/html/ext/pb_ds/null_probe_fn.html | 29 + .../doc/html/ext/pb_ds/null_tree_node_update.html | 101 ++ .../doc/html/ext/pb_ds/null_trie_node_update.html | 102 ++ libstdc++-v3/doc/html/ext/pb_ds/ov_tree_tag.html | 47 + .../doc/html/ext/pb_ds/pairing_heap_tag.html | 47 + ...riority_queue_text_push_pop_timing_test_gcc.png | Bin 0 -> 5395 bytes ...ority_queue_text_push_pop_timing_test_local.png | Bin 0 -> 6892 bytes ...iority_queue_text_push_pop_timing_test_msvc.png | Bin 0 -> 5514 bytes ...ng_priority_queue_text_push_timing_test_gcc.png | Bin 0 -> 5678 bytes ..._priority_queue_text_push_timing_test_local.png | Bin 0 -> 6760 bytes ...g_priority_queue_text_push_timing_test_msvc.png | Bin 0 -> 5878 bytes libstdc++-v3/doc/html/ext/pb_ds/pat_trie.png | Bin 0 -> 26182 bytes libstdc++-v3/doc/html/ext/pb_ds/pat_trie_tag.html | 47 + .../ext/pb_ds/point_invalidation_guarantee.html | 51 + .../doc/html/ext/pb_ds/point_iterators_cd.png | Bin 0 -> 20307 bytes .../html/ext/pb_ds/point_iterators_range_ops_1.png | Bin 0 -> 14206 bytes .../html/ext/pb_ds/point_iterators_range_ops_2.png | Bin 0 -> 12876 bytes .../doc/html/ext/pb_ds/pq_container_traits.html | 132 +++ libstdc++-v3/doc/html/ext/pb_ds/pq_design.html | 381 +++++++ .../html/ext/pb_ds/pq_different_underlying_dss.png | Bin 0 -> 15660 bytes libstdc++-v3/doc/html/ext/pb_ds/pq_examples.html | 54 + .../doc/html/ext/pb_ds/pq_performance_tests.html | 332 ++++++ .../doc/html/ext/pb_ds/pq_regression_tests.html | 52 + libstdc++-v3/doc/html/ext/pb_ds/pq_tests.html | 24 + libstdc++-v3/doc/html/ext/pb_ds/prerequisites.html | 46 + .../doc/html/ext/pb_ds/priority_queue.html | 995 ++++++++++++++++++ ...rity_queue_random_int_push_pop_timing_test.html | 161 +++ ...y_queue_random_int_push_pop_timing_test_gcc.png | Bin 0 -> 7350 bytes ...queue_random_int_push_pop_timing_test_local.png | Bin 0 -> 9275 bytes ..._queue_random_int_push_pop_timing_test_msvc.png | Bin 0 -> 7065 bytes ...priority_queue_random_int_push_timing_test.html | 200 ++++ ...ority_queue_random_int_push_timing_test_gcc.png | Bin 0 -> 7021 bytes ...ity_queue_random_int_push_timing_test_local.png | Bin 0 -> 8986 bytes ...rity_queue_random_int_push_timing_test_msvc.png | Bin 0 -> 7100 bytes .../doc/html/ext/pb_ds/priority_queue_tag.html | 47 + .../doc/html/ext/pb_ds/priority_queue_tag_cd.png | Bin 0 -> 10845 bytes .../doc/html/ext/pb_ds/priority_queue_tag_cd.svg | 368 +++++++ .../priority_queue_text_join_timing_test.html | 141 +++ .../priority_queue_text_join_timing_test_gcc.png | Bin 0 -> 6458 bytes .../priority_queue_text_join_timing_test_local.png | Bin 0 -> 7989 bytes .../priority_queue_text_join_timing_test_msvc.png | Bin 0 -> 6461 bytes ...riority_queue_text_modify_down_timing_test.html | 204 ++++ ...rity_queue_text_modify_down_timing_test_gcc.png | Bin 0 -> 6788 bytes ...ty_queue_text_modify_down_timing_test_local.png | Bin 0 -> 7633 bytes ...ity_queue_text_modify_down_timing_test_msvc.png | Bin 0 -> 6956 bytes ...xt_modify_down_timing_test_pairing_thin_gcc.png | Bin 0 -> 5007 bytes ..._modify_down_timing_test_pairing_thin_local.png | Bin 0 -> 5878 bytes ...t_modify_down_timing_test_pairing_thin_msvc.png | Bin 0 -> 4996 bytes .../priority_queue_text_modify_up_timing_test.html | 222 ++++ ...iority_queue_text_modify_up_timing_test_gcc.png | Bin 0 -> 6950 bytes ...rity_queue_text_modify_up_timing_test_local.png | Bin 0 -> 7748 bytes ...ority_queue_text_modify_up_timing_test_msvc.png | Bin 0 -> 6983 bytes ...text_modify_up_timing_test_pairing_thin_gcc.png | Bin 0 -> 4867 bytes ...xt_modify_up_timing_test_pairing_thin_local.png | Bin 0 -> 6105 bytes ...ext_modify_up_timing_test_pairing_thin_msvc.png | Bin 0 -> 5216 bytes .../priority_queue_text_pop_mem_usage_test.html | 143 +++ .../priority_queue_text_pop_mem_usage_test_gcc.png | Bin 0 -> 6582 bytes ...riority_queue_text_pop_mem_usage_test_local.png | Bin 0 -> 7424 bytes ...priority_queue_text_pop_mem_usage_test_msvc.png | Bin 0 -> 6849 bytes .../priority_queue_text_push_pop_timing_test.html | 209 ++++ ...riority_queue_text_push_pop_timing_test_gcc.png | Bin 0 -> 7072 bytes ...ority_queue_text_push_pop_timing_test_local.png | Bin 0 -> 9006 bytes ...iority_queue_text_push_pop_timing_test_msvc.png | Bin 0 -> 7289 bytes .../priority_queue_text_push_timing_test.html | 219 ++++ .../priority_queue_text_push_timing_test_gcc.png | Bin 0 -> 6832 bytes .../priority_queue_text_push_timing_test_local.png | Bin 0 -> 8477 bytes .../priority_queue_text_push_timing_test_msvc.png | Bin 0 -> 7266 bytes .../doc/html/ext/pb_ds/quadratic_probe_fn.html | 141 +++ .../random_int_find_find_timing_test_tree_gcc.png | Bin 0 -> 5960 bytes ...random_int_find_find_timing_test_tree_local.png | Bin 0 -> 7377 bytes .../random_int_find_find_timing_test_tree_msvc.png | Bin 0 -> 5636 bytes .../ext/pb_ds/range_invalidation_guarantee.html | 52 + .../html/ext/pb_ds/rationale_null_node_updator.png | Bin 0 -> 25097 bytes libstdc++-v3/doc/html/ext/pb_ds/rb_tree_tag.html | 47 + .../doc/html/ext/pb_ds/rc_binomial_heap_tag.html | 47 + libstdc++-v3/doc/html/ext/pb_ds/references.html | 258 +++++ libstdc++-v3/doc/html/ext/pb_ds/resize_error.html | 50 + .../doc/html/ext/pb_ds/resize_policy_cd.png | Bin 0 -> 20806 bytes .../html/ext/pb_ds/restoring_node_invariants.png | Bin 0 -> 14432 bytes .../doc/html/ext/pb_ds/sample_probe_fn.html | 152 +++ .../doc/html/ext/pb_ds/sample_range_hashing.html | 172 ++++ .../doc/html/ext/pb_ds/sample_ranged_hash_fn.html | 171 ++++ .../doc/html/ext/pb_ds/sample_ranged_probe_fn.html | 178 ++++ .../doc/html/ext/pb_ds/sample_resize_policy.html | 413 ++++++++ .../doc/html/ext/pb_ds/sample_resize_trigger.html | 462 +++++++++ .../doc/html/ext/pb_ds/sample_size_policy.html | 163 +++ .../html/ext/pb_ds/sample_tree_node_update.html | 193 ++++ .../ext/pb_ds/sample_trie_e_access_traits.html | 231 +++++ .../html/ext/pb_ds/sample_trie_node_update.html | 194 ++++ .../doc/html/ext/pb_ds/sample_update_policy.html | 178 ++++ libstdc++-v3/doc/html/ext/pb_ds/simple_list.png | Bin 0 -> 4299 bytes .../doc/html/ext/pb_ds/splay_tree_tag.html | 47 + .../ext/pb_ds/string_trie_e_access_traits.html | 400 ++++++++ libstdc++-v3/doc/html/ext/pb_ds/tests.html | 24 + .../ext/pb_ds/text_find_timing_test_hash_gcc.png | Bin 0 -> 7013 bytes .../ext/pb_ds/text_find_timing_test_hash_local.png | Bin 0 -> 9361 bytes .../ext/pb_ds/text_find_timing_test_hash_msvc.png | Bin 0 -> 6932 bytes .../pb_ds/text_find_timing_test_tree_like_gcc.png | Bin 0 -> 6207 bytes .../text_find_timing_test_tree_like_local.png | Bin 0 -> 7650 bytes .../pb_ds/text_find_timing_test_tree_like_msvc.png | Bin 0 -> 6059 bytes libstdc++-v3/doc/html/ext/pb_ds/thin_heap_tag.html | 47 + libstdc++-v3/doc/html/ext/pb_ds/tree.html | 516 ++++++++++ .../doc/html/ext/pb_ds/tree_based_containers.html | 358 +++++++ .../doc/html/ext/pb_ds/tree_node_iterator.html | 143 +++ .../html/ext/pb_ds/tree_node_updator_policy_cd.png | Bin 0 -> 9236 bytes .../pb_ds/tree_order_statistics_node_update.html | 678 +++++++++++++ .../pb_ds/tree_order_statistics_timing_test.html | 118 +++ .../tree_order_statistics_timing_test_gcc.png | Bin 0 -> 5698 bytes .../tree_order_statistics_timing_test_local.png | Bin 0 -> 6739 bytes .../tree_order_statistics_timing_test_msvc.png | Bin 0 -> 5684 bytes .../tree_random_int_find_find_timing_test.html | 160 +++ .../ext/pb_ds/tree_split_join_timing_test.html | 143 +++ .../ext/pb_ds/tree_split_join_timing_test_gcc.png | Bin 0 -> 5649 bytes .../pb_ds/tree_split_join_timing_test_local.png | Bin 0 -> 6734 bytes .../ext/pb_ds/tree_split_join_timing_test_msvc.png | Bin 0 -> 5675 bytes libstdc++-v3/doc/html/ext/pb_ds/tree_tag.html | 47 + .../ext/pb_ds/tree_text_find_find_timing_test.html | 162 +++ .../ext/pb_ds/tree_text_insert_timing_test.html | 226 +++++ .../tree_text_insert_timing_test_node_tree_gcc.png | Bin 0 -> 5373 bytes ...ree_text_insert_timing_test_node_tree_local.png | Bin 0 -> 6690 bytes ...tree_text_insert_timing_test_node_tree_msvc.png | Bin 0 -> 5212 bytes .../tree_text_insert_timing_test_pat_trie_gcc.png | Bin 0 -> 4895 bytes ...tree_text_insert_timing_test_pat_trie_local.png | Bin 0 -> 6011 bytes .../tree_text_insert_timing_test_pat_trie_msvc.png | Bin 0 -> 4881 bytes ...ree_text_insert_timing_test_vector_tree_gcc.png | Bin 0 -> 5140 bytes ...e_text_insert_timing_test_vector_tree_local.png | Bin 0 -> 6270 bytes ...ee_text_insert_timing_test_vector_tree_msvc.png | Bin 0 -> 5131 bytes .../pb_ds/tree_text_lor_find_find_timing_test.html | 126 +++ .../pb_ds/tree_text_lor_find_timing_test_gcc.png | Bin 0 -> 6162 bytes .../pb_ds/tree_text_lor_find_timing_test_local.png | Bin 0 -> 7796 bytes .../pb_ds/tree_text_lor_find_timing_test_msvc.png | Bin 0 -> 5831 bytes libstdc++-v3/doc/html/ext/pb_ds/trie.html | 489 +++++++++ .../doc/html/ext/pb_ds/trie_based_containers.html | 241 +++++ .../html/ext/pb_ds/trie_const_node_iterator.html | 478 +++++++++ .../doc/html/ext/pb_ds/trie_node_iterator.html | 235 +++++ .../html/ext/pb_ds/trie_node_updator_policy_cd.png | Bin 0 -> 12126 bytes .../pb_ds/trie_order_statistics_node_update.html | 770 ++++++++++++++ .../ext/pb_ds/trie_prefix_search_node_update.html | 628 ++++++++++++ libstdc++-v3/doc/html/ext/pb_ds/trie_tag.html | 47 + .../doc/html/ext/pb_ds/trivial_iterator_tag.html | 25 + libstdc++-v3/doc/html/ext/pb_ds/tutorial.html | 670 ++++++++++++ .../doc/html/ext/pb_ds/update_policy_cd.png | Bin 0 -> 8570 bytes .../doc/html/ext/pb_ds/update_seq_diagram.png | Bin 0 -> 10789 bytes 297 files changed, 30357 insertions(+) create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/PythonPoweredSmall.gif create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/acks.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/assoc_container_tag_cd.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/assoc_container_tag_cd.svg create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/assoc_container_traits.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/assoc_design.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/assoc_examples.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/assoc_performance_tests.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/assoc_regression_tests.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/assoc_tests.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/associative_container_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/balls_and_bins.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/basic_hash_table.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/basic_hash_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/basic_invalidation_guarantee.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/basic_tree.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/basic_tree_assoc_container_const_node_iterator.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/basic_tree_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/binary_heap_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/binary_priority_queue_random_int_push_timing_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/binary_priority_queue_random_int_push_timing_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/binary_priority_queue_random_int_push_timing_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/binomial_heap_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/cc_hash_max_collision_check_resize_trigger.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_find_timing_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_find_timing_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_find_timing_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_find_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_find_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_find_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_insert_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_insert_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_insert_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/cc_hash_table.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/cc_hash_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/ccgp_hash_random_int_subscript_timing_test_insert_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/ccgp_hash_random_int_subscript_timing_test_insert_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/ccgp_hash_random_int_subscript_timing_test_insert_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/checked_by_tidy.gif create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/concepts.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/contact.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/container_base.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/container_cd.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/container_cd.svg create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/container_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/counter_lu_policy.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/design.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/different_underlying_dss.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/direct_mask_range_hashing.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/direct_mod_range_hashing.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/disclaimer.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/ds_gen.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/embedded_lists_1.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/embedded_lists_2.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/embedded_lists_3.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/examples.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/exceptions.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_find_timing_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_find_timing_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_find_timing_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_find_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_find_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_find_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_insert_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_insert_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_insert_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/gp_hash_table.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/gp_hash_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_based_containers.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_exponential_size_policy.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_load_check_resize_trigger.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_policy_cd.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_prime_size_policy.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_erase_mem_usage_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_erase_mem_usage_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_erase_mem_usage_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_erase_mem_usage_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_find_find_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_subscript_find_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_subscript_insert_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_range_hashing_seq_diagram.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_range_hashing_seq_diagram2.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_ranged_hash_range_hashing_fns.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_standard_resize_policy.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_text_find_find_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_zlob_random_int_find_find_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_zlob_random_int_find_timing_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_zlob_random_int_find_timing_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/hash_zlob_random_int_find_timing_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/index.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/insert_error.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/insert_resize_sequence_diagram1.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/insert_resize_sequence_diagram2.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/insert_resize_sequence_diagram3.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/interface.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/introduction.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/invalidation_guarantee_cd.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/invalidation_guarantee_erase.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/join_error.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/linear_probe_fn.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/list_update.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/list_update_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/lu.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/lu_based_containers.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/misc.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/motivation.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/move_to_front_lu_policy.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_hash_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_hash_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_hash_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_tree_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_tree_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_tree_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_hash_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_hash_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_hash_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_tree_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_tree_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_tree_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_hash_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_hash_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_hash_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_tree_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_tree_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_tree_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_hash_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_hash_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_hash_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_tree_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_tree_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_tree_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_hash_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_hash_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_hash_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_tree_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_tree_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_tree_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_hash_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_hash_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_hash_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_tree_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_tree_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_tree_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/node_invariant_invalidations.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/node_invariants.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/null_hash_fn.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/null_lu_metadata.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/null_mapped_type.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/null_probe_fn.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/null_tree_node_update.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/null_trie_node_update.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/ov_tree_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/pairing_heap_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_pop_timing_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_pop_timing_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_pop_timing_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_timing_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_timing_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_timing_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/pat_trie.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/pat_trie_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/point_invalidation_guarantee.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/point_iterators_cd.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/point_iterators_range_ops_1.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/point_iterators_range_ops_2.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/pq_container_traits.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/pq_design.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/pq_different_underlying_dss.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/pq_examples.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/pq_performance_tests.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/pq_regression_tests.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/pq_tests.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/prerequisites.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_pop_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_pop_timing_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_pop_timing_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_pop_timing_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_timing_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_timing_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_timing_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_tag_cd.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_tag_cd.svg create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_join_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_join_timing_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_join_timing_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_join_timing_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_pairing_thin_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_pairing_thin_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_pairing_thin_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_pairing_thin_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_pairing_thin_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_pairing_thin_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_pop_mem_usage_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_pop_mem_usage_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_pop_mem_usage_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_pop_mem_usage_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_pop_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_pop_timing_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_pop_timing_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_pop_timing_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_timing_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_timing_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_timing_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/quadratic_probe_fn.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/random_int_find_find_timing_test_tree_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/random_int_find_find_timing_test_tree_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/random_int_find_find_timing_test_tree_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/range_invalidation_guarantee.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/rationale_null_node_updator.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/rb_tree_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/rc_binomial_heap_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/references.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/resize_error.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/resize_policy_cd.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/restoring_node_invariants.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/sample_probe_fn.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/sample_range_hashing.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/sample_ranged_hash_fn.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/sample_ranged_probe_fn.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/sample_resize_policy.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/sample_resize_trigger.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/sample_size_policy.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/sample_tree_node_update.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/sample_trie_e_access_traits.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/sample_trie_node_update.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/sample_update_policy.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/simple_list.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/splay_tree_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/string_trie_e_access_traits.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tests.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_hash_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_hash_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_hash_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_tree_like_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_tree_like_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_tree_like_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/thin_heap_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_based_containers.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_node_iterator.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_node_updator_policy_cd.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_node_update.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_timing_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_timing_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_timing_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_random_int_find_find_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_split_join_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_split_join_timing_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_split_join_timing_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_split_join_timing_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_text_find_find_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_node_tree_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_node_tree_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_node_tree_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_pat_trie_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_pat_trie_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_pat_trie_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_vector_tree_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_vector_tree_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_vector_tree_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_text_lor_find_find_timing_test.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_text_lor_find_timing_test_gcc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_text_lor_find_timing_test_local.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tree_text_lor_find_timing_test_msvc.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/trie.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/trie_based_containers.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/trie_const_node_iterator.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/trie_node_iterator.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/trie_node_updator_policy_cd.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/trie_order_statistics_node_update.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/trie_prefix_search_node_update.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/trie_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/trivial_iterator_tag.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/tutorial.html create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/update_policy_cd.png create mode 100644 libstdc++-v3/doc/html/ext/pb_ds/update_seq_diagram.png (limited to 'libstdc++-v3/doc/html/ext/pb_ds') diff --git a/libstdc++-v3/doc/html/ext/pb_ds/PythonPoweredSmall.gif b/libstdc++-v3/doc/html/ext/pb_ds/PythonPoweredSmall.gif new file mode 100644 index 000000000..268980706 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/PythonPoweredSmall.gif differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/acks.html b/libstdc++-v3/doc/html/ext/pb_ds/acks.html new file mode 100644 index 000000000..6612a4a81 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/acks.html @@ -0,0 +1,65 @@ + + + + + + + Acknowledgments + + + + +
+

Acknowledgments

+ +
    +
  1. This library was partially written at IBM's Haifa Research + Labs.
    2. + +
  2. The library is based heavily on policy-based design and + uses many useful techniques from [alexandrescu01modern].
    3. + +
  3. Two ideas are borrowed from the SGI-STL implementation + [sgi_stl]: + +
      +
    1. The prime-based resize policies use a list of primes + taken from the SGI-STL implementation.
      2. + +
    2. The red-black trees contain both a root node and a + header node (containing metadata), connected in a way + that forward and reverse iteration can be performed + efficiently.
      3. +
    +
    4. + +
  4. Some test utilities borrow ideas from [boost_timer].
    5. + +
  5. We would like to thank Scott Meyers for useful comments + (without attributing to him any flaws in the design or + implementation of the library).
    6. + +
  6. Much of the documentation is [Python Powered] (especially through PyChart, Beautiful + Soup, and kjbuckets) + and uses [HTML tidy]. The CSS-driven menus are + slightly modified from Brothercake + (hopefully without introducing errors).
    7. +
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/assoc_container_tag_cd.png b/libstdc++-v3/doc/html/ext/pb_ds/assoc_container_tag_cd.png new file mode 100644 index 000000000..16cc6da87 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/assoc_container_tag_cd.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/assoc_container_tag_cd.svg b/libstdc++-v3/doc/html/ext/pb_ds/assoc_container_tag_cd.svg new file mode 100644 index 000000000..02be62416 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/assoc_container_tag_cd.svg @@ -0,0 +1,491 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + Benjamin Kosnik + + + + + + + + + + + + basic_hash_table_tag + basic_tree_tag + + + tree_tag + trie_tag + + associative_container_tag + + + + + cc_hash_table_tag + gp_hash_table_tag + + + + + list_update_tag + + rb_tree_tag + splay_tree_tag + + + + pat_trie_tag + + ov_tree_tag + + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/assoc_container_traits.html b/libstdc++-v3/doc/html/ext/pb_ds/assoc_container_traits.html new file mode 100644 index 000000000..7814712c3 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/assoc_container_traits.html @@ -0,0 +1,170 @@ + + + + + + + container_traits Interface + + + + +
+

container_traits Interface

+ +

Traits of an associative-container based on its underlying + data structure.

+ +

Defined in: tag_and_trait.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+class Cntnr
+
+ 		+

Container type.

+ 		-
+ +

Public Types and + Constants

+ +

Container Attributes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+invalidation_guarantee
+
+ 		+ 
+Invalidation guarantee.
+
+ 		+

Invalidation-guarantee type.

+ +

This is either basic_invalidation_guarantee, + point_invalidation_guarantee, or + range_invalidation_guarantee

+
+ 
+order_preserving
+
+ 		+ 
+True only if Cntnr objects guarantee storing  keys by order.
+
+ 		+

Order-preserving indicator.

+
+ 
+erase_can_throw
+
+ 		+ 
+True only if erasing a key can throw.
+
+ 		+

Erase-throw indicator.

+
+ 
+reverse_iteration
+
+ 		+ 
+True only reverse iterators are supported.
+
+ 		+

Reverse iteration indicator.

+
+ 
+split_join_can_throw
+
+ 		+ 
+True only if split or join operations can throw.
+
+ 		+

Split-join throw indicator.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/assoc_design.html b/libstdc++-v3/doc/html/ext/pb_ds/assoc_design.html new file mode 100644 index 000000000..6c501e26b --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/assoc_design.html @@ -0,0 +1,46 @@ + + + + + + + Associative Containers + + + + +
+

Associative-Container Design

+ +
    +
  1. Data-Structure Genericity
    2. + +
  2. Genericity discusses generic manipulation of + containers based on different underlying + data structures.
    3. + +
  3. Genericity discusses generic manipulation of + containers with different mapping semantics.
    4. + +
  4. Tree-Based + Containers describes the design and policies of + tree-based containers.
    5. + +
  5. Trie-Based + Containers describes the design and policies of + trie-based containers.
    6. + +
  6. Hash-Based + Containers describes the design and policies of + hash-based containers.
    7. + +
  7. List-Based + Containers describes the design and policies of + list-based containers with update policies.
    8. +
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/assoc_examples.html b/libstdc++-v3/doc/html/ext/pb_ds/assoc_examples.html new file mode 100644 index 000000000..b64c74745 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/assoc_examples.html @@ -0,0 +1,151 @@ + + + + + + + Examples + + + + +
+

Associative-Container Examples

+ +

Basic Use

+ +
    +
  1. + basic_map.cc + Basic use of "maps".
    2. + +
  2. basic_set.cc + Basic use of "sets".
    3. + +
  3. erase_if.cc + Conditionally erasing values from a container object.
    4. +
+ +

Generics

+ +
    +
  1. assoc_container_traits.cc + Using container_traits to query + about underlying data structure behavior.
    2. + +
  2. hash_find_neg.cc + A non-compiling example showing wrong use of finding keys in + hash-based containers.
    3. +
+ +

Hash-Based + Containers

+ + +

Resize + Related

+ + +
    +
  1. hash_initial_size.cc + Setting the initial size of a hash-based container + object.
    2. + +
  2. hash_resize_neg.cc + A non-compiling example showing how not to resize a + hash-based container object.
    3. + +
  3. hash_resize.cc + Resizing the size of a hash-based container object.
    4. + +
  4. hash_illegal_resize.cc + Showing an illegal resize of a hash-based container + object.
    5. + +
  5. hash_load_set_change.cc + Changing the load factors of a hash-based container + object.
    6. +
+ +

Hash-Function + Related

+ + +
    +
  1. hash_mod.cc + Using a modulo range-hashing function for the case of an + unknown skewed key distribution.
    2. + +
  2. shift_mask.cc + Writing a range-hashing functor for the case of a known + skewed key distribution.
    3. + +
  3. store_hash.cc + Storing the hash value along with each key.
    4. + +
  4. ranged_hash.cc + Writing a ranged-hash functor.
    5. +
+ +

Tree-Like Containers (Trees and + Tries)

+ + +

Node-Invariants

+ + +
    +
  1. tree_order_statistics.cc + Using trees for order statistics.
    2. + +
  2. tree_intervals.cc + Augmenting trees to support operations on line + intervals.
    3. +
+ +

Split and + Join

+ + +
    +
  1. tree_join.cc + Joining two tree-based container objects.
    2. + +
  2. trie_split.cc + Splitting a PATRICIA trie container object.
    3. + +
  3. tree_order_statistics_join.cc + Order statistics while joining two tree-based container + objects.
    4. +
+ +

Trie-Based + Containers

+ + +
    +
  1. trie_dna.cc + Using a PATRICIA trie for DNA strings.
    2. + +
  2. trie_prefix_search.cc + Using a PATRICIA trie for finding all entries whose key + matches a given prefix.
    3. +
+ +

"Multimaps" and + "Multisets".

+
    +
  1. basic_multimap.cc + Basic use of "multimaps".
    2. + +
  2. basic_multiset.cc + Basic use of "multisets".
    3. +
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/assoc_performance_tests.html b/libstdc++-v3/doc/html/ext/pb_ds/assoc_performance_tests.html new file mode 100644 index 000000000..642f84809 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/assoc_performance_tests.html @@ -0,0 +1,345 @@ + + + + + +Associative-Container Performance Tests + + + +
+

Associative-Container + Performance Tests

+

Settings

+

This section describes performance tests and their results. + In the following, g++, msvc++, and local (the build used for generating this + documentation) stand for three different builds:

+
+
+

g++

+
    +
  • CPU speed - cpu MHz : 2660.644
    • +
  • Memory - MemTotal: 484412 kB
    • +
  • Platform - + Linux-2.6.12-9-386-i686-with-debian-testing-unstable
    • +
  • Compiler - g++ (GCC) 4.0.2 20050808 (prerelease) + (Ubuntu 4.0.1-4ubuntu9) Copyright (C) 2005 Free Software + Foundation, Inc. This is free software; see the source + for copying conditions. There is NO warranty; not even + for MERCHANTABILITY or FITNESS FOR A PARTICULAR + PURPOSE.
    • +
+
+
+
+
+
+

msvc++

+
    +
  • CPU speed - cpu MHz : 2660.554
    • +
  • Memory - MemTotal: 484412 kB
    • +
  • Platform - Windows XP Pro
    • +
  • Compiler - Microsoft (R) 32-bit C/C++ Optimizing + Compiler Version 13.10.3077 for 80x86 Copyright (C) + Microsoft Corporation 1984-2002. All rights + reserved.
    • +
+
+
+
+

local

    +
  • CPU speed - cpu MHz : 2250.000
    • +
  • Memory - MemTotal: 2076248 kB
    • +
  • Platform - Linux-2.6.16-1.2133_FC5-i686-with-redhat-5-Bordeaux
    • +
  • Compiler - g++ (GCC) 4.1.1 20060525 (Red Hat 4.1.1-1) +Copyright (C) 2006 Free Software Foundation, Inc. +This is free software; see the source for copying conditions. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +
    • +
+
+

Tests

+

Hash-Based + Containers

+
    +
  1. Hash-Based + Text find Find Timing Test
    2. +
  2. Hash-Based + Random-Integer find Find Timing Test
    3. +
  3. Hash-Based + Random-Integer Subscript Find Timing Test
    4. +
  4. Hash-Based + Random-Integer Subscript Insert Timing Test
    5. +
  5. Hash-Based + Skewed-Distribution Random-Integer find Find Timing + Test
    6. +
  6. Hash-Based Erase + Memory Use Test
    7. +
+

Tree-Like-Based Containers

+
    +
  1. Tree-Based + and Trie-Based Text Insert Timing Test
    2. +
  2. Tree-Based + and Trie-Based Text find Find Timing Test
    3. +
  3. Tree-Based + Locality-of-Reference Text find Find Timing + Test
    4. +
  4. Tree-Based + Random-Integer find Find Timing Test
    5. +
  5. Tree Split and + Join Timing Test
    6. +
  6. Tree + Order-Statistics Timing Test
    7. +
+

Multimaps

+
    +
  1. "Multimap" + Text Find Timing Test with Small Average Secondary-Key + to Primary-Key Ratio
    2. +
  2. "Multimap" + Text Find Timing Test with Large Average Secondary-Key + to Primary-Key Ratio
    3. +
  3. "Multimap" + Text Insert Timing Test with Small Average + Secondary-Key to Primary-Key Ratio
    4. +
  4. "Multimap" + Text Insert Timing Test with Large Average + Secondary-Key to Primary-Key Ratio
    5. +
  5. "Multimap" + Text Insert Memory-Use Test with Small Average + Secondary-Key to Primary-Key Ratio
    6. +
  6. "Multimap" + Text Insert Memory-Use Test with Large Average + Secondary-Key to Primary-Key Ratio
    7. +
+

Observations

+

Underlying Data-Structure Families

+

In general, hash-based containers (see Design::Associative + Containers::Hash-Based Containers) have better timing + performance than containers based on different underlying-data + structures. The main reason to choose a tree-based (see + Design::Associative + Containers::Tree-Based Containers) or trie-based container + (see Design::Associative + Containers::Trie-Based Containers) is if a byproduct of the + tree-like structure is required: either order-preservation, or + the ability to utilize node invariants (see Design::Associative + Containers::Tree-Based Containers::Node Invariants and + Design::Associative + Containers::Trie-Based Containers::Node Invariants). If + memory-use is the major factor, an ordered-vector tree (see + Design::Associative + Containers::Tree-Based Containers) gives optimal results + (albeit with high modificiation costs), and a list-based + container (see Design::Associative + Containers::List-Based Containers) gives reasonable + results.

+

Hash-Based + Container Types

+

Hash-based containers are typically either collision + chaining or probing (see Design::Associative + Containers::Hash-Based Containers). Collision-chaining + containers are more flexible internally, and so offer better + timing performance. Probing containers, if used for simple + value-types, manage memory more efficiently (they perform far + fewer allocation-related calls). In general, therefore, a + collision-chaining table should be used. A probing container, + conversely, might be used efficiently for operations such as + eliminating duplicates in a sequence, or counting the number of + occurrences within a sequence. Probing containers might be more + useful also in multithreaded applications where each thread + manipulates a hash-based container: in the STL, allocators have + class-wise semantics (see [meyers96more] - Item 10); a + probing container might incur less contention in this case.

+

Hash-Based Containers' Policies

+

In hash-based containers, the range-hashing scheme (see + Design::Associative + Containers::Hash-Based Containers::Hash Policies) seems to + affect performance more than other considerations. In most + settings, a mask-based scheme works well (or can be made to + work well). If the key-distribution can be estimated a-priori, + a simple hash function can produce nearly uniform hash-value + distribution. In many other cases (e.g., text hashing, + floating-point hashing), the hash function is powerful enough + to generate hash values with good uniformity properties + [knuth98sorting]; + a modulo-based scheme, taking into account all bits of the hash + value, appears to overlap the hash function in its effort.

+

The range-hashing scheme determines many of the other + policies (see Design::Hash-Based + Containers::Policy Interaction). A mask-based scheme works + well with an exponential-size policy (see Design::Associative + Containers::Hash-Based Containers::Resize Policies) ; for + probing-based containers, it goes well with a linear-probe + function (see Design::Associative + Containers::Hash-Based Containers::Hash Policies).

+

An orthogonal consideration is the trigger policy (see + Design::Associative + Containers::Hash-Based Containers::Resize Policies). This + presents difficult tradeoffs. E.g., different load + factors in a load-check trigger policy yield a + space/amortized-cost tradeoff.

+

Tree-Like-Based Container + Types

+

In general, there are several families of tree-based + underlying data structures: balanced node-based trees + (e.g., red-black or AVL trees), high-probability + balanced node-based trees (e.g., random treaps or + skip-lists), competitive node-based trees (e.g., splay + trees), vector-based "trees", and tries. (Additionally, there + are disk-residing or network-residing trees, such as B-Trees + and their numerous variants. An interface for this would have + to deal with the execution model and ACID guarantees; this is + out of the scope of this library.) Following are some + observations on their application to different settings.

+

Of the balanced node-based trees, this library includes a + red-black tree (see Design::Associative + Containers::Tree-Based Containers), as does STL (in + practice). This type of tree is the "workhorse" of tree-based + containers: it offers both reasonable modification and + reasonable lookup time. Unfortunately, this data structure + stores a huge amount of metadata. Each node must contain, + besides a value, three pointers and a boolean. This type might + be avoided if space is at a premium [austern00noset].

+

High-probability balanced node-based trees suffer the + drawbacks of deterministic balanced trees. Although they are + fascinating data structures, preliminary tests with them showed + their performance was worse than red-black trees. The library + does not contain any such trees, therefore.

+

Competitive node-based trees have two drawbacks. They are + usually somewhat unbalanced, and they perform a large number of + comparisons. Balanced trees perform one comparison per each + node they encounter on a search path; a splay tree performs two + comparisons. If the keys are complex objects, e.g., + std::string, this can increase the running time. + Conversely, such trees do well when there is much locality of + reference. It is difficult to determine in which case to prefer + such trees over balanced trees. This library includes a splay + tree (see Design::Associative + Containers::Tree-Based Containers).

+

Ordered-vector trees (see Design::Associative + Containers::Tree-Based Containers) use very little space + [austern00noset]. + They do not have any other advantages (at least in this + implementation).

+

Large-fan-out PATRICIA tries (see Design::Associative + Containers::Trie-Based Containers) have excellent lookup + performance, but they do so through maintaining, for each node, + a miniature "hash-table". Their space efficiency is low, and + their modification performance is bad. These tries might be + used for semi-static settings, where order preservation is + important. Alternatively, red-black trees cross-referenced with + hash tables can be used. [okasaki98mereable] + discusses small-fan-out PATRICIA tries for integers, but the + cited results seem to indicate that the amortized cost of + maintaining such trees is higher than that of balanced trees. + Moderate-fan-out trees might be useful for sequences where each + element has a limited number of choices, e.g., DNA + strings (see Examples::Associative + Containers::Trie-Based Containers).

+

Mapping-Semantics + Considerations

+

Different mapping semantics were discussed in Motivation::Associative + Containers::Alternative to Multiple Equivalent Keys and + Tutorial::Associative + Containers::Associative Containers Others than Maps. We + will focus here on the case where a keys can be composed into + primary keys and secondary keys. (In the case where some keys + are completely identical, it is trivial that one should use an + associative container mapping values to size types.) In this + case there are (at least) five possibilities:

+
    +
  1. Use an associative container that allows equivalent-key + values (such as std::multimap)
    2. +
  2. Use a unique-key value associative container that maps + each primary key to some complex associative container of + secondary keys, say a tree-based or hash-based container (see + Design::Associative + Containers::Tree-Based Containers and Design::Associative + Containers::Hash-Based Containers)
    3. +
  3. Use a unique-key value associative container that maps + each primary key to some simple associative container of + secondary keys, say a list-based container (see Design::Associative + Containers::List-Based Containers)
    4. +
  4. Use a unique-key value associative container that maps + each primary key to some non-associative container + (e.g., std::vector)
    5. +
  5. Use a unique-key value associative container that takes + into account both primary and secondary keys.
    6. +
+

We do not think there is a simple answer for this (excluding + option 1, which we think should be avoided in all cases).

+

If the expected ratio of secondary keys to primary keys is + small, then 3 and 4 seem reasonable. Both types of secondary + containers are relatively lightweight (in terms of memory use + and construction time), and so creating an entire container + object for each primary key is not too expensive. Option 4 + might be preferable to option 3 if changing the secondary key + of some primary key is frequent - one cannot modify an + associative container's key, and the only possibility, + therefore, is erasing the secondary key and inserting another + one instead; a non-associative container, conversely, can + support in-place modification. The actual cost of erasing a + secondary key and inserting another one depends also on the + allocator used for secondary associative-containers (The tests + above used the standard allocator, but in practice one might + choose to use, e.g., [boost_pool]). Option 2 is + definitely an overkill in this case. Option 1 loses out either + immediately (when there is one secondary key per primary key) + or almost immediately after that. Option 5 has the same + drawbacks as option 2, but it has the additional drawback that + finding all values whose primary key is equivalent to some key, + might be linear in the total number of values stored (for + example, if using a hash-based container).

+

If the expected ratio of secondary keys to primary keys is + large, then the answer is more complicated. It depends on the + distribution of secondary keys to primary keys, the + distribution of accesses according to primary keys, and the + types of operations most frequent.

+

To be more precise, assume there are m primary keys, + primary key i is mapped to ni + secondary keys, and each primary key is mapped, on average, to + n secondary keys (i.e., + E(ni) = n).

+

Suppose one wants to find a specific pair of primary and + secondary keys. Using 1 with a tree based container + (std::multimap), the expected cost is + E(Θ(log(m) + ni)) = Θ(log(m) + + n); using 1 with a hash-based container + (std::tr1::unordered_multimap), the expected cost is + Θ(n). Using 2 with a primary hash-based container + and secondary hash-based containers, the expected cost is + O(1); using 2 with a primary tree-based container and + secondary tree-based containers, the expected cost is (using + the Jensen inequality [motwani95random]) + E(O(log(m) + log(ni)) = O(log(m)) + + E(O(log(ni)) = O(log(m)) + O(log(n)), + assuming that primary keys are accessed equiprobably. 3 and 4 + are similar to 1, but with lower constants. Using 5 with a + hash-based container, the expected cost is O(1); using 5 + with a tree based container, the cost is + E(Θ(log(mn))) = Θ(log(m) + + log(n)).

+

Suppose one needs the values whose primary key matches some + given key. Using 1 with a hash-based container, the expected + cost is Θ(n), but the values will not be ordered + by secondary keys (which may or may not be required); using 1 + with a tree-based container, the expected cost is + Θ(log(m) + n), but with high constants; again the + values will not be ordered by secondary keys. 2, 3, and 4 are + similar to 1, but typically with lower constants (and, + additionally, if one uses a tree-based container for secondary + keys, they will be ordered). Using 5 with a hash-based + container, the cost is Θ(mn).

+

Suppose one wants to assign to a primary key all secondary + keys assigned to a different primary key. Using 1 with a + hash-based container, the expected cost is Θ(n), + but with very high constants; using 1 with a tree-based + container, the cost is Θ(nlog(mn)). Using 2, 3, + and 4, the expected cost is Θ(n), but typically + with far lower costs than 1. 5 is similar to 1.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/assoc_regression_tests.html b/libstdc++-v3/doc/html/ext/pb_ds/assoc_regression_tests.html new file mode 100644 index 000000000..9b6b6b839 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/assoc_regression_tests.html @@ -0,0 +1,93 @@ + + + + + + + Associative-Container Regression Tests + + + + + +
+

Associative-Container Regression Tests

+ +

Description

+ +

The library contains a single comprehensive regression test. + For a given container type in pb_ds, the test creates + an object of the container type and an object of the + corresponding STL type (e.g., std::set). It + then performs a random sequence of methods with random + arguments (e.g., inserts, erases, and so forth) on both + objects. At each operation, the test checks the return value of + the method, and optionally both compares pb_ds's + object with the STL's object as well as performing other + consistency checks on pb_ds's object (e.g., + order preservation, when applicable, or node invariants, when + applicable).

+ +

Additionally, the test integrally checks exception safety + and resource leaks. This is done as follows. A special + allocator type, written for the purpose of the test, both + randomly throws an exceptions when allocations are performed, + and tracks allocations and de-allocations. The exceptions thrown + at allocations simulate memory-allocation failures; the + tracking mechanism checks for memory-related bugs (e.g., + resource leaks and multiple de-allocations). Both + pb_ds's containers and the containers' value-types are + configured to use this allocator.

+ +

Due to compiler constraints, the test is split into the + several sources, each checking only some containers.

+ +

Tests

+ +

"Set" + Tests

+ +

The following check all "set" types:

+ +
    +
  1. hash_no_data_map_rand.cc + checks all hash-based "set" types.
    2. + +
  2. list_update_no_data_map_rand.cc + checks all list-based "set" types.
    3. + +
  3. tree_no_data_map_rand.cc + checks all tree-based "set" types.
    4. + +
  4. trie_no_data_map_rand.cc + checks all PATRICIA-trie-based "set" types.
    5. +
+ +

"Map" + Tests

+ +

The following check all "map" types:

+ +
    +
  1. hash_data_map_rand.cc + checks all hash-based "map" types.
    2. + +
  2. list_update_data_map_rand.cc + checks all list-based "map" types.
    3. + +
  3. tree_data_map_rand.cc + checks all tree-based "map" types.
    4. + +
  4. trie_data_map_rand.cc + checks all PATRICIA-trie-based "map" types.
    5. +
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/assoc_tests.html b/libstdc++-v3/doc/html/ext/pb_ds/assoc_tests.html new file mode 100644 index 000000000..6e4474945 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/assoc_tests.html @@ -0,0 +1,24 @@ + + + + + + + Associative-Container Tests + + + + +
+

Associative-Container Tests

+ +

Associative-Container + Regression Tests describes the regression tests; Associative-Container + Performance Tests describes the performance tests.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/associative_container_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/associative_container_tag.html new file mode 100644 index 000000000..ceb91cdc7 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/associative_container_tag.html @@ -0,0 +1,47 @@ + + + + + + + associative_container_tag Interface + + + + +
+

associative_container_tag Interface

+ +

Basic associative-container data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+container_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/balls_and_bins.png b/libstdc++-v3/doc/html/ext/pb_ds/balls_and_bins.png new file mode 100644 index 000000000..529c3ae41 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/balls_and_bins.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/basic_hash_table.html b/libstdc++-v3/doc/html/ext/pb_ds/basic_hash_table.html new file mode 100644 index 000000000..668e681d8 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/basic_hash_table.html @@ -0,0 +1,436 @@ + + + + + + + basic_hash_table Interface + + + + +
+

basic_hash_table Interface

+ +

An abstract basic hash-based associative container.

+ +

Defined in: assoc_container.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+typename Key
+
+ 		+

Key type.

+ 		-
+ 
+typename Mapped
+
+ 		+

Mapped type.

+ 		-
+ 
+class Hash_Fn
+
+ 		+

Hash functor.

+ 		-
+ 
+class Eq_Fn
+
+ 		+

Equivalence functor.

+ 		-
+ 
+class Resize_Policy
+
+ 		+

Resize policy.

+ 		-
+ 
+bool Store_Hash
+
+ 		+

Indicates whether the hash value will be stored along + with each key.

+ 		-
+ 
+class Tag
+
+ 		+

Mapped-structure tag.

+ 		-
+ 
+class Allocator
+
+ 		+

Allocator type.

+ 		-
+ +

Base Classes

+ + + + + + + + + + + + + + + + + + + +
ClassDerivation Type
+ 
+Resize_Policy
+
+ 		+

public

+
+ 
+container_base
+
+ 		+

public

+
+ +

Public Types and + Constants

+ +

Policy Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+hash_fn
+
+ 		+ 
+Hash_Fn
+
+ 		+

Hash functor type.

+
+ 
+eq_fn
+
+ 		+ 
+Eq_Fn
+
+ 		+

Equivalence functor type.

+
+ 
+resize_policy
+
+ 		+ 
+Resize_Policy
+
+ 		+

Resize policy type.

+
+ 
+store_hash
+
+ 		+ 
+Store_Hash
+
+ 		+

Indicates whether a hash value is stored with each + entry.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + +
MethodDescription
+ 
+virtual 
+  ~basic_hash_table
+  ()
+
+ 		+

Destructor.

+
+ +

Policy Access Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+hash_fn &
+  get_hash_fn
+  ()
+
+ 		+

Access to the hash_fn object.

+
+ 
+const hash_fn &
+  get_hash_fn
+  () const
+
+ 		+

Const access to the hash_fn object.

+
+ 
+eq_fn &
+  get_eq_fn
+  ()
+
+ 		+

Access to the eq_fn + object.

+
+ 
+const eq_fn &
+  get_eq_fn
+  () const
+
+ 		+

Const access to the eq_fn object.

+
+ 
+resize_policy &
+  get_resize_policy
+  ()
+
+ 		+

Access to the resize_policy + object.

+
+ 
+const resize_policy &
+  get_resize_policy
+  () const
+
+ 		+

Const access to the resize_policy + object.

+
+ +

Private Methods

+ +

Resize Methods

+ + + + + + + + + + + + + +
MethodDescription
+ 
+virtual void 
+  do_resize
+  (size_type new_size)
+
+ 		+

Resizes the container object to new_size.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/basic_hash_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/basic_hash_tag.html new file mode 100644 index 000000000..9dc5e6d86 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/basic_hash_tag.html @@ -0,0 +1,47 @@ + + + + + + + basic_hash_tag Interface + + + + +
+

basic_hash_tag Interface

+ +

Basic hash data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+associative_container_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/basic_invalidation_guarantee.html b/libstdc++-v3/doc/html/ext/pb_ds/basic_invalidation_guarantee.html new file mode 100644 index 000000000..d4a0df23f --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/basic_invalidation_guarantee.html @@ -0,0 +1,26 @@ + + + + + + + basic_invalidation_guarantee Interface + + + + +
+

basic_invalidation_guarantee Interface

+ +

Signifies a basic invalidation guarantee that any iterator, + pointer, or reference to a container object's mapped value type + is valid as long as the container is not modified.

+ +

Defined in: tag_and_trait.hpp

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/basic_tree.html b/libstdc++-v3/doc/html/ext/pb_ds/basic_tree.html new file mode 100644 index 000000000..3811707fa --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/basic_tree.html @@ -0,0 +1,660 @@ + + + + + + + basic_tree Interface + + + + +
+

basic_tree Interface

+ +

An abstract basic tree-like-based associative container.

+ +

Defined in: assoc_container.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+typename Key
+
+ 		+

Key type.

+ 		-
+ 
+typename Mapped
+
+ 		+

Mapped type.

+ 		-
+ 
+class Tag
+
+ 		+

Mapped-structure tag.

+ 		-
+ 
+class Node_Update
+
+ 		+

Node updater.

+ +

Restores node-invariants when invalidated.

+ 		-
+ 
+class Policy_Tl
+
+ 		+

Policy typelist.

+ +

Contains subclasses' policies.

+ 		-
+ 
+class Allocator
+
+ 		+

Allocator type.

+ 		-
+ +

Base Classes

+ + + + + + + + + + + + + + + + + + + +
ClassDerivation Type
+ 
+Node_Update
+
+ 		+

public

+
+ 
+container_base
+
+ 		+

public

+
+ +

Public Types and + Constants

+ +

Key-Type Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+const_key_reference
+
+ 		+ 
+typename container_base::const_key_reference
+
+ 		+

Const key reference type.

+
+ +

Policy Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+node_update
+
+ 		+ 
+Node_Update
+
+ 		+

Node updater type.

+
+ +

Iterator Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+const_iterator
+
+ 		+ 
+typename container_base::const_iterator
+
+ 		+

Const range-type iterator.

+
+ 
+iterator
+
+ 		+ 
+typename container_base::iterator
+
+ 		+

Range-type iterator.

+
+ 
+const_reverse_iterator
+
+ 		+ 
+Const reverse range-type iterator.
+
+ 		+

Const reverse range-type iterator.

+
+ 
+reverse_iterator
+
+ 		+ 
+Reverse range-type iterator.

+If Mapped is null_mapped_type, then this is synonymous to const_reverse_iterator
+
+ 		+

Reverse range-type iterator.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + +
MethodDescription
+ 
+virtual 
+  ~basic_tree
+  ()
+
+ 		+

Destructor.

+
+ +

Policy Access Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+node_update &
+  get_node_update
+  ()
+
+ 		+

Access to the node_update + object.

+
+ 
+const node_update &
+  get_node_update
+  () const
+
+ 		+

Const access to the node_update + object.

+
+ +

Find Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+iterator
+  lower_bound
+  (const_key_reference r_key)
+
+ 		+

Returns an iterator corresponding + to the entry whose key is the smallest one at least as + large as r_key.

+
+ 
+const_iterator
+  lower_bound
+  (const_key_reference r_key) const
+
+ 		+

Returns a const iterator corresponding + to the entry whose key is the smallest one at least as + large as r_key.

+
+ 
+iterator
+  upper_bound
+  (const_key_reference r_key)
+
+ 		+

Returns an iterator corresponding + to the entry whose key is the smallest one larger than + r_key.

+
+ 
+const_iterator
+  upper_bound
+  (const_key_reference r_key) const
+
+ 		+

Returns a const_iterator + corresponding to the entry whose key is the smallest one + larger than r_key.

+
+ +

Erase Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+iterator
+  erase
+  (iterator it)
+
+ 		+

Erases the value_type corresponding to the iterator it. Returns the iterator corresponding + to the next value_type.

+
+ 
+reverse_iterator
+  erase
+  (reverse_iterator it)
+
+ 		+

Erases the value_type corresponding to the reverse_iterator + it. Returns the reverse_iterator + corresponding to the previous value_type.

+
+ +

Iteration Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+reverse_iterator
+  rbegin
+  ()
+
+ 		+

Returns a reverse_iterator + corresponding to the last value_type in the + container.

+
+ 
+const_reverse_iterator
+  rbegin
+  () const
+
+ 		+

Returns a const_reverse_iterator + corresponding to the last value_type in the + container.

+
+ 
+reverse_iterator
+  rend
+  ()
+
+ 		+

Returns a reverse_iterator + corresponding to the just-before-first value_type in the + container.

+
+ 
+const_reverse_iterator
+  rend
+  () const
+
+ 		+

Returns a const_reverse_iterator + corresponding to the just-before-first value_type in the + container.

+
+ +

Split and join + Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+void 
+  join
+  (basic_tree &other)
+
+ 		+

Joins two trees. When this function returns, + other will be + empty.

+ +

When calling this method, other's keys must be all larger or + all smaller than this object's keys, and other's policies must be + equivalent to this object's policies.

+
+ 
+void
+  split
+  (const_key_reference r_key, 
+    basic_tree &other)
+
+ 		+

Splits into two trees. When this function returns, + other will contain + only keys larger than r_key.

+ +

When calling this method, other's policies must be + equivalent to this object's policies.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/basic_tree_assoc_container_const_node_iterator.html b/libstdc++-v3/doc/html/ext/pb_ds/basic_tree_assoc_container_const_node_iterator.html new file mode 100644 index 000000000..5647f551e --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/basic_tree_assoc_container_const_node_iterator.html @@ -0,0 +1,383 @@ + + + + + + + tree::const_node_iterator + Interface + + + + +
+

tree::const_node_iterator + Interface

+ +

Const node iterator.

+ +

This is an &qout;iterator to an iterator&qout; - it + iterates over nodes, and de-referencing it returns one of the + tree's iterators

+ +

Public Types and + Constants

+ +

Iterator Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+iterator_category
+
+ 		+ 
+trivial_iterator_tag
+
+ 		+

Category.

+ +

This tag identifies that the iterator has none of the + STL's iterators' movement abilities.

+
+ 
+difference_type
+
+ 		+ 
+void
+
+ 		+

Difference type.

+
+ +

Value-Type Definitions

+ +

Note that a node iterator's value type is actually a tree + iterator.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+value_type
+
+ 		+ 
+container_base::const_iterator
+
+ 		+

Iterator's value type.

+
+ 
+reference
+
+ 		+ 
+container_base::const_iterator
+
+ 		+

Iterator's reference type.

+
+ 
+const_reference
+
+ 		+ 
+container_base::const_iterator
+
+ 		+

Iterator's const reference type.

+
+ +

Metadata Definitions

+ +

These are only defined if + basic_tree::Node_Update + is not null_tree_node_update

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+metadata_type
+
+ 		+ 
+typename basic_tree::Node_Update::metadata_type
+
+ 		+

Metadata type.

+
+ 
+const_metadata_reference
+
+ 		+ 
+typename Allocator::template rebind<
+    metadata_type>::other::const_reference
+
+ 		+

Const metadata reference type.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline 
+  const_node_iterator
+  ()
+
+ 		+

Default constructor.

+
+ +

Access Methods

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline const_reference
+  operator*
+  () const
+
+ 		+

Access.

+
+ +

Metadata Access Methods

+ +

These are only defined if + basic_tree::Node_Update + is not null_tree_node_update

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline const_metadata_reference
+  get_metadata
+  () const
+
+ 		+

Metadata access.

+
+ +

Movement Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline const_node_iterator
+  get_l_child
+  () const
+
+ 		+

Returns the const node iterator associated with the + left node.

+
+ 
+inline const_node_iterator
+  get_r_child
+  () const
+
+ 		+

Returns the const node iterator associated with the + right node.

+
+ +

Comparison Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline bool
+  operator==
+  (const const_node_iterator &other) const
+
+ 		+

Compares to a different iterator object.

+
+ 
+inline bool
+  operator!=
+  (const const_node_iterator &other) const
+
+ 		+

Compares (negatively) to a different iterator + object.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/basic_tree_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/basic_tree_tag.html new file mode 100644 index 000000000..8eca2a818 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/basic_tree_tag.html @@ -0,0 +1,47 @@ + + + + + + + basic_tree_tag Interface + + + + +
+

basic_tree_tag Interface

+ +

Basic tree-like data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+associative_container_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/binary_heap_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/binary_heap_tag.html new file mode 100644 index 000000000..47873b1cf --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/binary_heap_tag.html @@ -0,0 +1,47 @@ + + + + + + + binary_heap_tag Interface + + + + +
+

binary_heap_tag Interface

+ +

Binary-heap (array-based) data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+priority_queue_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/binary_priority_queue_random_int_push_timing_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/binary_priority_queue_random_int_push_timing_test_gcc.png new file mode 100644 index 000000000..07f0953a6 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/binary_priority_queue_random_int_push_timing_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/binary_priority_queue_random_int_push_timing_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/binary_priority_queue_random_int_push_timing_test_local.png new file mode 100644 index 000000000..76e02f134 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/binary_priority_queue_random_int_push_timing_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/binary_priority_queue_random_int_push_timing_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/binary_priority_queue_random_int_push_timing_test_msvc.png new file mode 100644 index 000000000..b8a3b2371 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/binary_priority_queue_random_int_push_timing_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/binomial_heap_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/binomial_heap_tag.html new file mode 100644 index 000000000..fde6a913b --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/binomial_heap_tag.html @@ -0,0 +1,47 @@ + + + + + + + binomial_heap_tag Interface + + + + +
+

binomial_heap_tag Interface

+ +

Binomial-heap data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+priority_queue_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_max_collision_check_resize_trigger.html b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_max_collision_check_resize_trigger.html new file mode 100644 index 000000000..a6b512b0d --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_max_collision_check_resize_trigger.html @@ -0,0 +1,532 @@ + + + + + + + cc_hash_max_collision_check_resize_trigger + Interface + + + + +
+

cc_hash_max_collision_check_resize_trigger + Interface

+ +

A resize trigger policy based on collision checks. It keeps + the simulated load factor lower than some given load + factor.

+ +

Defined in: hash_policy.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+bool External_Load_Access 
+
+ 		+

Specifies whether the load factor can be accessed + externally. The two options have different trade-offs in + terms of flexibility, genericity, and encapsulation.

+ 		false
+ 
+typename Size_Type 
+
+ 		+

Size type.

+ 		size_t
+ +

Public Types and + Constants

+ +

General Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+Size_Type
+
+ 		+

Size type.

+
+ 
+external_load_access
+
+ 		+ 
+External_Load_Access
+
+ 		+

Indicates whether loads can be accessed externally

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  cc_hash_max_collision_check_resize_trigger
+  (float load = 0.5)
+
+ 		+

Default constructor, or constructor taking + load, a load factor + which it will attempt to maintain.

+
+ 
+void
+  swap
+  (cc_hash_max_collision_check_resize_trigger &other)
+
+ 		+

Swaps content.

+
+ +

Load Access Methods

+ +

These methods are only available if the external access + parameter is set.

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline float
+  get_load
+  () const
+
+ 		+

Returns the current load.

+ +

Calling this method will not compile when External_Load_Access + == false.

+
+ 
+void 
+  set_load
+  (float load)
+
+ 		+

Sets the load; does + not resize the container.

+ +

It is the responsibility of the user to pass an + appropriate load to this + function. Calling this method will not compile when + External_Load_Access + == false.

+
+ +

Protected Methods

+ +

Insert Search + Notifications.

+ +

Notifications called during an insert operation.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_insert_search_start
+  ()
+
+ 		+

Notifies a search started.

+
+ 
+inline void
+  notify_insert_search_collision
+  ()
+
+ 		+

Notifies a search encountered a collision.

+
+ 
+inline void
+  notify_insert_search_end
+  ()
+
+ 		+

Notifies a search ended.

+
+ +

Find Search + Notifications.

+ +

Notifications called during a find operation.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_find_search_start
+  ()
+
+ 		+

Notifies a search started.

+
+ 
+inline void
+  notify_find_search_collision
+  ()
+
+ 		+

Notifies a search encountered a collision.

+
+ 
+inline void
+  notify_find_search_end
+  ()
+
+ 		+

Notifies a search ended.

+
+ +

Erase Search + Notifications.

+ +

Notifications called during an insert operation.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_erase_search_start
+  ()
+
+ 		+

Notifies a search started.

+
+ 
+inline void
+  notify_erase_search_collision
+  ()
+
+ 		+

Notifies a search encountered a collision.

+
+ 
+inline void
+  notify_erase_search_end
+  ()
+
+ 		+

Notifies a search ended.

+
+ +

Content Change + Notifications

+ +

Notifications called when the content of the table changes + in a way that can affect the resize policy.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_inserted
+  (size_type num_entries)
+
+ 		+

Notifies an element was inserted.

+
+ 
+inline void
+  notify_erased
+  (size_type num_entries)
+
+ 		+

Notifies an element was erased.

+
+ 
+void 
+  notify_cleared
+  ()
+
+ 		+

Notifies the table was cleared.

+
+ +

Size Change + Notifications

+ +

Notifications called when the table changes size.

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+void
+  notify_resized
+  (size_type new_size)
+
+ 		+

Notifies the table was resized as a result of this + object's signifying that a resize is needed.

+
+ 
+void
+  notify_externally_resized
+  (size_type new_size)
+
+ 		+

Notifies the table was resized externally.

+
+ +

Queries

+ +

Called to query whether/how to resize.

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline bool 
+  is_resize_needed
+  () const
+
+ 		+

Queries whether a resize is needed.

+
+ 
+inline bool
+  is_grow_needed
+  (size_type size, size_type num_entries) const
+
+ 		+

Queries whether a grow is needed.

+ +

This method is called only if this object indicated is + needed.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_find_timing_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_find_timing_test_gcc.png new file mode 100644 index 000000000..85b9eca4f Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_find_timing_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_find_timing_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_find_timing_test_local.png new file mode 100644 index 000000000..4f578c65b Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_find_timing_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_find_timing_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_find_timing_test_msvc.png new file mode 100644 index 000000000..d1234aa11 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_find_timing_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_find_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_find_gcc.png new file mode 100644 index 000000000..1db2cc0c6 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_find_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_find_local.png b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_find_local.png new file mode 100644 index 000000000..ca4db96f4 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_find_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_find_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_find_msvc.png new file mode 100644 index 000000000..0b51d9432 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_find_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_insert_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_insert_gcc.png new file mode 100644 index 000000000..6e4940381 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_insert_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_insert_local.png b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_insert_local.png new file mode 100644 index 000000000..48fcf76c0 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_insert_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_insert_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_insert_msvc.png new file mode 100644 index 000000000..39c96ad8d Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_random_int_subscript_timing_test_insert_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_table.html b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_table.html new file mode 100644 index 000000000..0557732a5 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_table.html @@ -0,0 +1,724 @@ + + + + + + + cc_hash_table Interface + + + + +
+

cc_hash_table Interface

+ +

A concrete collision-chaining hash-based associative + container.

+ +

Defined in: assoc_container.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+typename Key
+
+ 		+

Key type.

+ 		-
+ 
+typename Mapped
+
+ 		+

Mapped type.

+ 		-
+ 
+class Hash_Fn 
+
+ 		+

Hash functor.

+ 		+ 
+__gnu_cxx::hash<Key>
+
if using gcc; + 
+stdext::hash_value<Key>
+
if using Visual C++ .net +
+ 
+class Eq_Fn 
+
+ 		+

Equivalence functor.

+ 		+ 
+std::equal_to<Key>
+
+
+ 
+class Comb_Hash_Fn 
+
+ 		+

Combining hash functor.

+ +

If Hash_Fn is + not null_hash_fn, then this is the + ranged-hash functor; otherwise, this is the range-hashing + functor.

+ +

(See Design::Hash-Based + Containers::Hash Policies.)

+ 		+ 
+direct_mask_range_hashing
+
+
+ 
+class Resize_Policy 
+
+ 		+

Resize policy.

+ 		+ If Comb_Hash_Fn + is direct_mask_range_hashing, + then + 
+hash_standard_resize_policy<
+  hash_exponential_size_policy<
+    typename Comb_Hash_Fn::size_type>,
+  hash_load_check_resize_trigger<
+    typename Comb_Hash_Fn::size_type>,
+  false,
+  typename Comb_Hash_Fn::size_type>
+
otherwise, + 
+hash_standard_resize_policy<
+  hash_exponential_size_policy<
+    typename Comb_Hash_Fn::size_type>,
+  hash_load_check_resize_trigger<
+    typename Comb_Hash_Fn::size_type>,
+  false,
+  typename Comb_Hash_Fn::size_type>
+
+
+ 
+bool Store_Hash 
+
+ 		+

Indicates whether the hash value will be stored along + with each key.

+ +

If hash_fn is null_hash_fn, then the container + will not compile if this value is + true

+ 		+ 
+false
+
+
+ 
+class Allocator 
+
+ 		+

Allocator type.

+ 		+ 
+std::allocator<char>
+
+
+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+basic_hash_table
+
+ 		+

public

+
+ +

Public Types and + Constants

+ +

Policy Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+hash_fn
+
+ 		+ 
+Hash_Fn
+
+ 		+

Hash functor type.

+
+ 
+eq_fn
+
+ 		+ 
+Eq_Fn
+
+ 		+

Equivalence functor type.

+
+ 
+resize_policy
+
+ 		+ 
+Resize_Policy
+
+ 		+

Resize policy type.

+
+ 
+comb_hash_fn
+
+ 		+ 
+Comb_Hash_Fn
+
+ 		+

Combining hash functor type.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  cc_hash_table
+  ()
+
+ 		+

Default constructor.

+
+ 
+  cc_hash_table
+  (const hash_fn &r_hash_fn)
+
+ 		+

Constructor taking some policy objects. r_hash_fn will be copied by the + Hash_Fn object of + the container object.

+
+ 
+  cc_hash_table
+  (const hash_fn &r_hash_fn, 
+    const eq_fn &r_eq_fn)
+
+ 		+

Constructor taking some policy objects. r_hash_fn will be copied by the + hash_fn object of + the container object, and r_eq_fn will be copied by the + eq_fn object of the + container object.

+
+ 
+  cc_hash_table
+  (const hash_fn &r_hash_fn, 
+    const eq_fn &r_eq_fn, 
+    const comb_hash_fn &r_comb_hash_fn)
+
+ 		+

Constructor taking some policy objects. r_hash_fn will be copied by the + hash_fn object of + the container object, r_eq_fn will be copied by the + eq_fn object of the + container object, and r_comb_hash_fn will be copied by the + comb_hash_fn + object of the container object.

+
+ 
+  cc_hash_table
+  (const hash_fn &r_hash_fn, 
+    const eq_fn &r_eq_fn, 
+    const comb_hash_fn &r_comb_hash_fn, 
+    const resize_policy &r_resize_policy)
+
+ 		+

Constructor taking some policy objects. r_hash_fn will be copied by the + hash_fn object of + the container object, r_eq_fn will be copied by the + eq_fn object of the + container object, r_comb_hash_fn will be copied by the + comb_hash_fn + object of the container object, and r_resize_policy will be copied by + the resize_policy + object of the container object.

+
+ 
+template<
+    class It>
+  cc_hash_table
+  (It first_it, 
+    It last_it)
+
+ 		+

Constructor taking iterators to a range of + value_types. The value_types between first_it and last_it will be inserted into the + container object.

+
+ 
+template<
+    class It>
+  cc_hash_table
+  (It first_it, 
+    It last_it,
+    const hash_fn &r_hash_fn)
+
+ 		+

Constructor taking iterators to a range of value_types + and some policy objects. The value_types between + first_it and + last_it will be inserted + into the container object.

+
+ 
+template<
+    class It>
+  cc_hash_table
+  (It first_it, 
+    It last_it,
+    const hash_fn &r_hash_fn, 
+    const eq_fn &r_eq_fn)
+
+ 		+

Constructor taking iterators to a range of value_types + and some policy objects The value_types between + first_it and + last_it will be inserted + into the container object. r_hash_fn will be copied by the + hash_fn object of + the container object, and r_eq_fn will be copied by the + eq_fn object of the + container object.

+
+ 
+template<
+    class It>
+  cc_hash_table
+  (It first_it, 
+    It last_it,
+    const hash_fn &r_hash_fn, 
+    const eq_fn &r_eq_fn, 
+    const comb_hash_fn &r_comb_hash_fn)
+
+ 		+

Constructor taking iterators to a range of value_types + and some policy objects The value_types between + first_it and + last_it will be inserted + into the container object. r_hash_fn will be copied by the + hash_fn object of + the container object, r_eq_fn will be copied by the + eq_fn object of the + container object, and r_comb_hash_fn will be copied by the + comb_hash_fn + object of the container object.

+
+ 
+template<
+    class It>
+  cc_hash_table
+  (It first_it, 
+    It last_it,
+    const hash_fn &r_hash_fn, 
+    const eq_fn &r_eq_fn, 
+    const comb_hash_fn &r_comb_hash_fn, 
+    const resize_policy &r_resize_policy)
+
+ 		+

Constructor taking iterators to a range of value_types + and some policy objects The value_types between + first_it and + last_it will be inserted + into the container object. r_hash_fn will be copied by the + hash_fn object of + the container object, r_eq_fn will be copied by the + eq_fn object of the + container object, r_comb_hash_fn will be copied by the + comb_hash_fn + object of the container object, and r_resize_policy will be copied by + the resize_policy + object of the container object.

+
+ 
+  cc_hash_table
+  (const cc_hash_table &other)
+
+ 		+

Copy constructor.

+
+ 
+virtual 
+  ~cc_hash_table
+  ()
+
+ 		+

Destructor.

+
+ 
+cc_hash_table &
+  operator=
+  (const cc_hash_table &other)
+
+ 		+

Assignment operator.

+
+ 
+void
+  swap
+  (cc_hash_table &other)
+
+ 		+

Swaps content.

+
+ +

Policy Access Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+comb_hash_fn &
+  get_comb_hash_fn
+  ()
+
+ 		+

Access to the comb_hash_fn + object.

+
+ 
+const comb_hash_fn &
+  get_comb_hash_fn
+  () const
+
+ 		+

Const access to the comb_hash_fn + object.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_tag.html new file mode 100644 index 000000000..1923e20fb --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/cc_hash_tag.html @@ -0,0 +1,47 @@ + + + + + + + cc_hash_tag Interface + + + + +
+

cc_hash_tag Interface

+ +

Collision-chaining hash data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+basic_hash_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/ccgp_hash_random_int_subscript_timing_test_insert_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/ccgp_hash_random_int_subscript_timing_test_insert_gcc.png new file mode 100644 index 000000000..fde6b41bf Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/ccgp_hash_random_int_subscript_timing_test_insert_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/ccgp_hash_random_int_subscript_timing_test_insert_local.png b/libstdc++-v3/doc/html/ext/pb_ds/ccgp_hash_random_int_subscript_timing_test_insert_local.png new file mode 100644 index 000000000..2449e1de3 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/ccgp_hash_random_int_subscript_timing_test_insert_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/ccgp_hash_random_int_subscript_timing_test_insert_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/ccgp_hash_random_int_subscript_timing_test_insert_msvc.png new file mode 100644 index 000000000..11dca77fc Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/ccgp_hash_random_int_subscript_timing_test_insert_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/checked_by_tidy.gif b/libstdc++-v3/doc/html/ext/pb_ds/checked_by_tidy.gif new file mode 100644 index 000000000..47c2c4859 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/checked_by_tidy.gif differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/concepts.html b/libstdc++-v3/doc/html/ext/pb_ds/concepts.html new file mode 100644 index 000000000..9f6c22462 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/concepts.html @@ -0,0 +1,118 @@ + + + + + + + Concepts + + + + +
+

Concepts

+ +

Point and Range Methods and + Iterators

+ +

A point-type iterator is an iterator that refers to a + specific element, e.g. as returned through an + associative-container's find method; a range-type + iterator is an iterator that is used to go over a sequence of + elements, e.g., as returned by a container's + find method. A point-type method is a method that + returns a point-type iterator; a range-type method is a method + that returns a range-type iterator.

+ +

For most containers, these types are synonymous; for + self-organizing containers, such as hash-based containers or + priority queues, these are inherently different (in any + implementation, including that of the STL), but in + pb_ds this is made explicit - they are distinct + types.

+ + +

Invalidation Guarantees

+ +

If one manipulates a container object, then iterators + previously obtained from it can be invalidated. In some cases a + previously-obtained iterator cannot be de-referenced; in other + cases, the iterator's next or previous element might have + changed unpredictably. This corresponds exactly to the question + whether a point-type or range-type iterator (see previous + concept) is valid or not. In pb_ds one can query a + container (in compile time) what are its invalidation + guarantees.

+ +

Primary and Secondary Keys + and Associative Containers

+ +

In pb_ds there are no associative containers which + allow multiple values with equivalent keys (such as the STL's + std::multimap, for example). Instead, one maps the + unique part of a key - the primary key, into an + associative-container of the (originally) non-unique parts of + the key - the secondary key. A primary associative-container is + an associative container of primary keys; a secondary + associative-container is an associative container of secondary + keys.

+ + +

Null Policy Classes

+ +

Associative containers are typically parametrized by + various policies. For example, a hash-based associative + container is parametrized by a hash-functor, transforming each + key into an non-negative numerical type. Each such value is + then further mapped into a position within the table. The + mapping of a key into a position within the table is therefore + a two-step process.

+ +

In some cases, instantiations are redundant. For + example, when the keys are integers, it is possible to use a + redundant hash policy, which transforms each key into + its value.

+ +

In some other cases, these policies are irrelevant. + For example, a hash-based associative container might transform + keys into positions within a table by a different method than + the two-step method described above. In such a case, the hash + functor is simply irrelevant.

+ +

pb_ds uses special pre-defined "null policies" + classes for these cases. Some null policies in pb_ds + are:

+ +
    +
  1. null_mapped_type
    2. + +
  2. null_tree_node_update
    3. + +
  3. null_trie_node_update
    4. + +
  4. null_hash_fn
    5. + +
  5. null_probe_fn
    6. +
+ +

A "set" in pb_ds, for example, is an associative + container with its Data_Parameter instantiated by + null_mapped_type. + Design::Tree-Based + Containers::Node Invariants explains another case where a + null policy is needed.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/contact.html b/libstdc++-v3/doc/html/ext/pb_ds/contact.html new file mode 100644 index 000000000..3d506c975 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/contact.html @@ -0,0 +1,22 @@ + + + + + + + Contact + + + + +
+

Contact

+ +

For anything relevant, please write to pbassoc@gmail.com

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/container_base.html b/libstdc++-v3/doc/html/ext/pb_ds/container_base.html new file mode 100644 index 000000000..359e02459 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/container_base.html @@ -0,0 +1,1063 @@ + + + + + + + container_base Interface + + + + +
+

container_base Interface

+ +

An abstract basic associative container.

+ +

Defined in: assoc_container.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+typename Key
+
+ 		+

Key type.

+ 		-
+ 
+typename Mapped
+
+ 		+

Mapped type.

+ 		-
+ 
+class Tag
+
+ 		+

Data structure tag.

+ 		-
+ 
+class Policy_Tl
+
+ 		+

Policy typelist.

+ +

Contains subclasses' policies.

+ 		-
+ 
+class Allocator
+
+ 		+

Allocator type.

+ 		-
+ +

Public Types and + Constants

+ +

General Container + Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+typename Allocator::size_type
+
+ 		+

Size type.

+
+ 
+difference_type
+
+ 		+ 
+typename Allocator::difference_type
+
+ 		+

Difference type.

+
+ +

Categories

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+container_category
+
+ 		+ 
+Tag
+
+ 		+

The underlying mapped-structure tag of the + container.

+ +

This is one of:

+ +
    +
  1. cc_hash_tag
    2. + +
  2. gp_hash_tag
    3. + +
  3. rb_tree_tag
    4. + +
  4. ov_tree_tag
    5. + +
  5. splay_tree_tag
    6. + +
  6. pat_trie_tag
    7. + +
  7. list_update_tag
    8. +
+
+ +

Policy Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+allocator
+
+ 		+ 
+Allocator
+
+ 		+

Allocator + type.

+
+ +

Key-Type Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+key_type
+
+ 		+ 
+typename allocator::template rebind<
+    Key>::other::value_type
+
+ 		+

Key type.

+
+ 
+key_reference
+
+ 		+ 
+typename allocator::template rebind<
+    key_type>::other::reference
+
+ 		+

Key reference + type.

+
+ 
+const_key_reference
+
+ 		+ 
+typename allocator::template rebind<
+    key_type>::other::const_reference
+
+ 		+

Const key reference type.

+
+ 
+key_pointer
+
+ 		+ 
+typename allocator::template rebind<
+    key_type>::other::pointer
+
+ 		+

Key pointer type.

+
+ 
+const_key_pointer
+
+ 		+ 
+typename allocator::template rebind<
+    key_type>::other::const_pointer
+
+ 		+

Const key pointer type.

+
+ +

Mapped-Type Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+mapped_type
+
+ 		+ 
+Mapped
+
+ 		+

Mapped type.

+
+ 
+mapped_reference
+
+ 		+ 
+typename allocator::template rebind<
+    mapped_type>::other::reference
+
+ 		+

Mapped reference + type.

+
+ 
+const_mapped_reference
+
+ 		+ 
+typename allocator::template rebind<
+    mapped_type>::other::const_reference
+
+ 		+

Const mapped reference type.

+
+ 
+mapped_pointer
+
+ 		+ 
+typename allocator::template rebind<
+    mapped_type>::other::pointer
+
+ 		+

Mapped pointer + type.

+
+ 
+const_mapped_pointer
+
+ 		+ 
+typename allocator::template rebind<
+    mapped_type>::other::const_pointer
+
+ 		+

Const mapped pointer type.

+
+ +

Value-Type Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+value_type
+
+ 		+ 
+

+If Mapped is null_mapped_type, then Key

+Otherwise, Mapped
+
+ 		+

Value type.

+
+ 
+reference
+
+ 		+ 
+typename allocator::template rebind<
+    value_type>::other::reference
+
+ 		+

Value reference type.

+
+ 
+const_reference
+
+ 		+ 
+typename allocator::template rebind<
+    value_type>::other::const_reference
+
+ 		+

Const value reference type.

+
+ 
+pointer
+
+ 		+ 
+typename allocator::template rebind<
+    value_type>::other::pointer
+
+ 		+

Value pointer type.

+
+ 
+const_pointer
+
+ 		+ 
+typename allocator::template rebind<
+    value_type>::other::const_pointer
+
+ 		+

Const Value pointer type.

+
+ +

Iterator Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+const_point_iterator
+
+ 		+ 
+Const point-type iterator.
+
+ 		+

Const point-type iterator.

+
+ 
+point_iterator
+
+ 		+ 
+

+Point-type iterator.

+If Mapped is null_mapped_type, then this is synonymous to const_point_iterator
+
+ 		+

Point-type iterator.

+
+ 
+const_iterator
+
+ 		+ 
+Const range-type iterator.
+
+ 		+

Const range-type iterator.

+
+ 
+iterator
+
+ 		+ 
+

+Range-type iterator.

+If Mapped is null_mapped_type, then this is synonymous to const_iterator
+
+ 		+

Range-type iterator.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + +
MethodDescription
+ 
+virtual 
+  ~container_base
+  ()
+
+ 		+

Destructor.

+
+ +

Information Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline size_type
+  size
+  () const
+
+ 		+

Returns the number of distinct value_type objects + the container object is storing.

+
+ 
+inline size_type
+  max_size
+  () const
+
+ 		+

Returns an upper bound on the number of distinct + value_type + objects this container can store.

+
+ 
+inline bool
+  empty
+  () const
+
+ 		+

Returns whether the container object is not storing + any value_type + objects.

+
+ +

Insert Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+std::pair<point_iterator, bool>
+  insert
+  (const_reference r_val)
+
+ 		+

Inserts a value_type object. If + no value_type + with r_val's key was in + the container object, inserts and returns (point_iterator + object associated with r_val, true); + otherwise just returns (point_iterator + object associated with r_val's key, + false).

+
+ 
+mapped_reference
+  operator[]
+  (const_key_reference r_key)
+
+ 		+

Subscript operator.

+
+ +

Find Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+point_iterator 
+  find
+  (const_key_reference r_key)
+
+ 		+

Returns the point_iterator + corresponding to the value_type with + r_key as its key, or the + point_iterator + corresponding to the just-after-last entry if no such + value_type.

+
+ 
+const_point_iterator 
+  find
+  (const_key_reference r_key) const
+
+ 		+

Returns the const_point_iterator + corresponding to the value_type with + r_key as its key, or the + const_point_iterator + corresponding to the just-after-last entry if no such + value_type.

+
+ +

Erase Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+bool
+  erase
+  (const_key_reference r_key)
+
+ 		+

Erases the value_type associated + with r_key. returns + false iff r_key was not contained.

+
+ 
+template<
+  class Pred>
+size_type 
+  erase_if
+  (Pred prd)
+
+ 		+

Erases any value_type satisfying + the predicate prd (this + is transactional, either all matching value_types are + erased, or, if an exception is thrown (for types whose + erase can throw an exception) none); returns the number + of value_types + erased.

+
+ 
+void 
+  clear
+  ()
+
+ 		+

Clears the container object.

+
+ +

Iteration Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+iterator
+  begin
+  ()
+
+ 		+

Returns an iterator corresponding + to the first value_type in the + container.

+
+ 
+const_iterator
+  begin
+  () const
+
+ 		+

Returns a const_iterator + corresponding to the first value_type in the + container.

+
+ 
+iterator
+  end
+  ()
+
+ 		+

Returns an iterator corresponding + to the just-after-last value_type in the + container.

+
+ 
+const_iterator
+  end
+  () const
+
+ 		+

Returns a const_iterator + corresponding to the just-after-last value_type in the + container.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/container_cd.png b/libstdc++-v3/doc/html/ext/pb_ds/container_cd.png new file mode 100644 index 000000000..52553278c Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/container_cd.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/container_cd.svg b/libstdc++-v3/doc/html/ext/pb_ds/container_cd.svg new file mode 100644 index 000000000..3b5a98189 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/container_cd.svg @@ -0,0 +1,418 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + Benjamin Kosnik + + + + + + + + + + list_update + basic_hash_table + basic_tree + + + + + tree + trie + cc_hash_table + gp_hash_table + + container_base + + + + + + + + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/container_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/container_tag.html new file mode 100644 index 000000000..de187a94d --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/container_tag.html @@ -0,0 +1,24 @@ + + + + + + + container _tag Interface + + + + +
+

container _tag Interface

+ +

Basic data structure tag.

+ +

Defined in: tag_and_trait.hpp

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/counter_lu_policy.html b/libstdc++-v3/doc/html/ext/pb_ds/counter_lu_policy.html new file mode 100644 index 000000000..d9d5112c0 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/counter_lu_policy.html @@ -0,0 +1,259 @@ + + + + + + + counter_lu_policy Interface + + + + +
+

counter_lu_policy Interface

+ +

A list-update policy that moves elements to the front of the + list based on the counter algorithm.

+ +

Defined in: list_update_policy.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+size_t Max_Count 
+
+ 		+

Maximum count.

+ +

When some element is accessed this number of times, it + will be moved to the front of the list.

+ 		5
+ 
+class Allocator 
+
+ 		+

Allocator type.

+ +

This is used only for definitions, e.g., the size + type.

+ 		+ 
+std::allocator<char>
+
+
+ +

Public Types and + Constants

+ +

Policy Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+allocator
+
+ 		+ 
+Allocator
+
+ 		+

Allocator + type.

+
+ 
+max_count
+
+ 		+ 
+Max_Count
+}
+
+ 		+

Maximum count.

+
+ +

General Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+typename allocator::size_type
+
+ 		+

Size type.

+
+ +

Metadata-Type + Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+metadata_type
+
+ 		+ 
+Some class containing a counter.
+
+ 		+

Metadata on which this functor operates.

+
+ 
+metadata_reference
+
+ 		+ 
+typename Allocator::template rebind<
+    metadata_type>::other::reference
+
+ 		+

Reference to metadata on which this functor + operates.

+
+ +

Public Methods

+ +

Metadata Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+metadata_type
+  operator()
+  () const
+
+ 		+

Creates a metadata object.

+
+ 
+bool 
+  operator()
+  (metadata_reference r_metadata) const
+
+ 		+

Decides whether a metadata object should be moved to + the front of the list.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/design.html b/libstdc++-v3/doc/html/ext/pb_ds/design.html new file mode 100644 index 000000000..e83bd4dd2 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/design.html @@ -0,0 +1,96 @@ + + + + + + + Design + + + + +
+

Design

+ +

The pb_ds namespace contains:

+ +
    +
  1. Exception classes (see Interface::Exceptions::Common)
    2. + +
  2. Invalidation-guarantee tags (see Design::Invalidation Guarantees + and Interface::Data-Structure Tags + and Traits::Invalidation-Guarantee Tags).
    3. + +
  3. Associative Containers (see Design::Associative + Containers::Tree-Based Containers, Design::Associative + Containers::Trie-Based Containers, Design::Associative + Containers::Hash-Based Containers, and Design::Associative + Containers::List-Based Containers, and Interface::Containers::Associative + Containers).
    4. + +
  4. Associative Container tags and traits + (see Design::Associative + Containers::Data-Structure Genericity, Interface::Data-Structure Tags + and Traits::Data-Structure Tags::Associative-Containers, + and Interface::Data-Structure Tags and + Traits::Data-Structure + Traits::Associative-Containers).
    5. + +
  5. Associative Container policies (see + Design::Associative + Containers::Tree-Based Containers, Design::Associative + Containers::Trie-Based Containers, Design::Associative + Containers::Hash-Based Containers, and Design::Associative + Containers::List-Based Containers, and Interface::Container + Policy Classes).
    6. + + +
  6. Mapped types for setting the mapping semantics of + associative containers (see Tutorial::Associative + Containers::Associative Containers Others than Maps and + Interface::Mapped-Type + Policies).
    7. + + +
  7. Priority Queues (see Design::Priority + Queues and Interface::Containers::Priority + Queues).
    8. + +
  8. Priority Queue tags and traits + (see Design::Priority + Queues::Traits, Interface::Data-Structure Tags and + Traits::Data-Structure Tags::Priority Queues, and + Interface::Data-Structure + Tags and Traits::Data-Structure Traits::Priority + Queues).
    9. +
+ + +

Associative-Container Design + describes associative-container design.

+ +

Priority-Queue Design describes + priority-queue design.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/different_underlying_dss.png b/libstdc++-v3/doc/html/ext/pb_ds/different_underlying_dss.png new file mode 100644 index 000000000..adee12636 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/different_underlying_dss.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/direct_mask_range_hashing.html b/libstdc++-v3/doc/html/ext/pb_ds/direct_mask_range_hashing.html new file mode 100644 index 000000000..19f8621c2 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/direct_mask_range_hashing.html @@ -0,0 +1,167 @@ + + + + + + + direct_mask_range_hashing Interface + + + + +
+

direct_mask_range_hashing Interface

+ +

A mask range-hashing class (uses a bit-mask).

+ +

Defined in: hash_policy.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+typename Size_Type 
+
+ 		+

Size type.

+ 		size_t
+ +

Public Types and + Constants

+ +

General Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+Size_Type
+
+ 		+

Size type.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + +
MethodDescription
+ 
+void
+  swap
+  (direct_mask_range_hashing &other)
+
+ 		+

Swaps content.

+
+ +

Protected Methods

+ +

Notification Methods

+ + + + + + + + + + + + + +
MethodDescription
+ 
+void 
+  notify_resized
+  (size_type size)
+
+ 		+

Notifies the policy object that the container's size + has changed to size.

+
+ +

Operators.

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline size_type
+  operator()
+  (size_type hash) const
+
+ 		+

Transforms the hash value hash into a ranged-hash value (using + a bit-mask).

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/direct_mod_range_hashing.html b/libstdc++-v3/doc/html/ext/pb_ds/direct_mod_range_hashing.html new file mode 100644 index 000000000..f3f9295d4 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/direct_mod_range_hashing.html @@ -0,0 +1,144 @@ + + + + + + + direct_mod_range_hashing Interface + + + + +
+

direct_mod_range_hashing Interface

+ +

A mod range-hashing class (uses the modulo function).

+ +

Defined in: hash_policy.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+typename Size_Type 
+
+ 		+

Size type.

+ 		size_t
+ +

Public Types and + Constants

+ +

General Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+Size_Type
+
+ 		+

Size type.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + +
MethodDescription
+ 
+void
+  swap
+  (direct_mod_range_hashing &other)
+
+ 		+

Swaps content.

+
+ +

Protected Methods

+ +

Notification Methods

+ +

Operators.

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline size_type
+  operator()
+  (size_type hash) const
+
+ 		+

Transforms the hash value hash into a ranged-hash value (using + a modulo operation).

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/disclaimer.html b/libstdc++-v3/doc/html/ext/pb_ds/disclaimer.html new file mode 100644 index 000000000..681af4edf --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/disclaimer.html @@ -0,0 +1,34 @@ + + + + + + + What, me worry? + + + + +
+

Disclaimer and Copyright

+ +

Revised 16 February, 2004

© Copyright Ami Tavory and + Vladimir Dreizin, IBM-HRL, 2004, and Benjamin Kosnik, Red Hat, + 2004. + +

Permission to use, copy, modify, sell, and distribute this + software is hereby granted without fee, provided that the above + copyright notice appears in all copies, and that both that + copyright notice and this permission notice appear in + supporting documentation.

+ +

None of the above authors, nor IBM Haifa Research + Laboratories, Red Hat, or both, make any representation about + the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/ds_gen.html b/libstdc++-v3/doc/html/ext/pb_ds/ds_gen.html new file mode 100644 index 000000000..ec99c4d5f --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/ds_gen.html @@ -0,0 +1,344 @@ + + + + + + + Data-Structure Genericity + + + + +
+

Data-Structure Genericity

+ +

The Basic Problem

+ +

The design attempts to address the following problem. When + writing a function manipulating a generic container object, + what is the behavior of the object? E.g., suppose one + writes

+ 
+template<typename Cntnr>
+void
+some_op_sequence(Cntnr &r_container)
+{
+    ...
+}
+
then one needs to address the following questions in the body +of some_op_sequence: + +
    +
  1. Which types and methods does Cntnr support? + Containers based on hash tables can be queries for the + hash-functor type and object; this is meaningless for + tree-based containers. Containers based on trees can be + split, joined, or can erase iterators and return the + following iterator; this cannot be done by hash-based + containers.
    2. + +
  2. What are the guarantees of Cntnr? A container + based on a probing hash-table invalidates all iterators when + it is modified; this is not the case for containers based on + node-based trees. Containers based on a node-based tree can + be split or joined without exceptions; this is not the case + for containers based on vector-based trees.
    3. + +
  3. How does the container maintain its elements? Tree-based + and Trie-based containers store elements by key order; + others, typically, do not. A container based on a splay trees + or lists with update policies "cache" "frequently accessed" + elements; containers based on most other underlying + data structures do not.
    4. +
+ +

The remainder of this section deals with these issues.

+ +

Container + Hierarchy

+ +

Figure Container class hierarchy shows the + container hierarchy.

+ +
+
+ +
Container class hierarchy.
+ +
    +
  1. container_base is an + abstract base class for associative containers.
    2. + +
  2. Tree-Like-Based Associative-Containers: + +
      +
    1. basic_tree + is an abstract base class for tree-like-based + associative-containers
      2. + +
    2. tree + is a concrete base class for tree-based + associative-containers
      3. + +
    3. trie + is a concrete base class trie-based + associative-containers
      4. +
    +
    3. + +
  3. Hash-Based Associative-Containers: + +
      +
    1. basic_hash_table + is an abstract base class for hash-based + associative-containers
      2. + +
    2. cc_hash_table + is a concrete collision-chaining hash-based + associative-containers
      3. + +
    3. gp_hash_table + is a concrete (general) probing hash-based + associative-containers
      4. +
    +
    4. + +
  4. List-Based Associative-Containers: + +
      +
    1. list_update - + list-based update-policy associative container
      2. +
    +
    5. +
+ +

The hierarchy is composed naturally so that commonality is + captured by base classes. Thus operator[] is + defined container_base, since + all containers support it. Conversely split is defined + in basic_tree, + since only tree-like containers support it. Data-Structure Tags and Traits discusses how + to query which types and methods each container supports.

+ +

Data-Structure Tags and + Traits

+ +

Tags and traits are very useful for manipulating generic + types. For example, if It is an iterator class, then + typename It::iterator_category or + typename + std::iterator_traits<It>::iterator_category will + yield its category, and typename + std::iterator_traits<It>::value_type will yield its + value type.

+ +

pb_ds contains a tag hierarchy corresponding to the + hierarchy in Figure Class hierarchy. The tag + hierarchy is shown in Figure Data-structure tag class hierarchy.

+ +
no image
+ +
Data-structure tag class hierarchy.
+ +

container_base + publicly defines container_category as one of the classes in + Figure Data-structure tag class + hierarchy. Given any container Cntnr, the tag of + the underlying data structure can be found via + typename Cntnr::container_category.

+ +

Additionally, a traits mechanism can be used to query a + container type for its attributes. Given any container + Cntnr, then __gnu_pbds::container_traits<Cntnr> + is a traits class identifying the properties of the + container.

+ +

To find if a container can throw when a key is erased (which + is true for vector-based trees, for example), one can + use

container_traits<Cntnr>::erase_can_throw, + for example. + +

Some of the definitions in container_traits are + dependent on other definitions. E.g., if container_traits<Cntnr>::order_preserving + is true (which is the case for containers based + on trees and tries), then the container can be split or joined; + in this case, container_traits<Cntnr>::split_join_can_throw + indicates whether splits or joins can throw exceptions (which + is true for vector-based trees); otherwise container_traits<Cntnr>::split_join_can_throw + will yield a compilation error. (This is somewhat similar to a + compile-time version of the COM model [mscom]).

+ +

Point-Type and + Range-Type Methods and Iterators

+ +

Iterators in + Unordered Container Types

+ +

pb_ds differentiates between two types of methods + and iterators: point-type methods and iterators, and range-type + methods and iterators (see Motivation::Associative + Containers::Differentiating between Iterator Types and + Tutorial::Associative + Containers::Point-Type and Range-Type Methods and + Iterators). Each associative container's interface includes + the methods:

+ 
+const_point_iterator
+find(const_key_reference r_key) const;                
+
+point_iterator
+find(const_key_reference r_key);         
+    
+std::pair<point_iterator,bool>
+insert(const_reference r_val);
+
+ +

The relationship between these iterator types varies between + container types. Figure Point-type and range-type iterators-A + shows the most general invariant between point-type and + range-type iterators: iterator, e.g., can + always be converted to point_iterator. Figure Point-type and range-type iterators-B + shows invariants for order-preserving containers: point-type + iterators are synonymous with range-type iterators. + Orthogonally, Figure Point-type + and range-type iterators-C shows invariants for "set" + containers: iterators are synonymous with const iterators.

+ +
+
+ +
Point-type and range-type iterators.
+ +

Note that point-type iterators in self-organizing containers + (e.g., hash-based associative containers) lack movement + operators, such as operator++ - in fact, this + is the reason why pb_ds differentiates from the STL's + design on this point.

+ +

Typically, one can determine an iterator's movement + capabilities in the STL using + std::iterator_traits<It>iterator_category, which + is a struct indicating the iterator's movement + capabilities. Unfortunately, none of the STL's predefined + categories reflect a pointer's not having any movement + capabilities whatsoever. Consequently, pb_ds adds a + type trivial_iterator_tag + (whose name is taken from a concept in [sgi_stl]), which is the category + of iterators with no movement capabilities. All other STL tags, + such as forward_iterator_tag retain their common + use.

+ +

Invalidation + Guarantees

+ +

Motivation::Associative + Containers::Differentiating between Iterator + Types::Invalidation Guarantees posed a problem. Given three + different types of associative containers, a modifying + operation (in that example, erase) invalidated + iterators in three different ways: the iterator of one + container remained completely valid - it could be de-referenced + and incremented; the iterator of a different container could + not even be de-referenced; the iterator of the third container + could be de-referenced, but its "next" iterator changed + unpredictably.

+ +

Distinguishing between find and range types allows + fine-grained invalidation guarantees, because these questions + correspond exactly to the question of whether point-type + iterators and range-type iterators are valid. Invalidation guarantees class + hierarchy shows tags corresponding to different types of + invalidation guarantees.

+ +
no image
+ +
Invalidation guarantees class hierarchy.
+ +
    +
  1. basic_invalidation_guarantee + corresponds to a basic guarantee that a point-type iterator, + a found pointer, or a found reference, remains valid as long + as the container object is not modified.
    2. + +
  2. point_invalidation_guarantee + corresponds to a guarantee that a point-type iterator, a + found pointer, or a found reference, remains valid even if + the container object is modified.
    3. + +
  3. range_invalidation_guarantee + corresponds to a guarantee that a range-type iterator remains + valid even if the container object is modified.
    4. +
+ +

As shown in Tutorial::Associative + Containers::Point-Type and Range-Type Methods and + Iterators, to find the invalidation guarantee of a + container, one can use

+ 
+typename container_traits<Cntnr>::invalidation_guarantee
+
+ +

which is one of the classes in Figure Invalidation guarantees class + hierarchy.

+ +

Note that this hierarchy corresponds to the logic it + represents: if a container has range-invalidation guarantees, + then it must also have find invalidation guarantees; + correspondingly, its invalidation guarantee (in this case + range_invalidation_guarantee) + can be cast to its base class (in this case point_invalidation_guarantee). + This means that this this hierarchy can be used easily using + standard metaprogramming techniques, by specializing on the + type of invalidation_guarantee.

+ +

(These types of problems were addressed, in a more general + setting, in [meyers96more] - Item 2. In + our opinion, an invalidation-guarantee hierarchy would solve + these problems in all container types - not just associative + containers.)

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/embedded_lists_1.png b/libstdc++-v3/doc/html/ext/pb_ds/embedded_lists_1.png new file mode 100644 index 000000000..9470a65b5 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/embedded_lists_1.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/embedded_lists_2.png b/libstdc++-v3/doc/html/ext/pb_ds/embedded_lists_2.png new file mode 100644 index 000000000..d2ac91c1a Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/embedded_lists_2.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/embedded_lists_3.png b/libstdc++-v3/doc/html/ext/pb_ds/embedded_lists_3.png new file mode 100644 index 000000000..08ecb0ffe Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/embedded_lists_3.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/examples.html b/libstdc++-v3/doc/html/ext/pb_ds/examples.html new file mode 100644 index 000000000..03c7a3910 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/examples.html @@ -0,0 +1,24 @@ + + + + + + + Examples + + + + +
+

Examples

+ +

Associative-Container + Examples shows examples for associative containers; + Priority-Queue Examples shows + examples for priority queues.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/exceptions.html b/libstdc++-v3/doc/html/ext/pb_ds/exceptions.html new file mode 100644 index 000000000..a51e8ebe0 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/exceptions.html @@ -0,0 +1,46 @@ + + + + + + +container_error Interface + + + + +
+

container_error Interface

+ +

Base class for associative-container exceptions.

+ +

Defined in: exception.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+
+std::logic_error
+
+		 +

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_find_timing_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_find_timing_test_gcc.png new file mode 100644 index 000000000..d86299b7e Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_find_timing_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_find_timing_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_find_timing_test_local.png new file mode 100644 index 000000000..1b31b7f27 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_find_timing_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_find_timing_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_find_timing_test_msvc.png new file mode 100644 index 000000000..b7082f286 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_find_timing_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_find_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_find_gcc.png new file mode 100644 index 000000000..b9fbe00de Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_find_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_find_local.png b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_find_local.png new file mode 100644 index 000000000..c693ed386 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_find_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_find_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_find_msvc.png new file mode 100644 index 000000000..248ff6b88 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_find_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_insert_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_insert_gcc.png new file mode 100644 index 000000000..ac4f838fe Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_insert_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_insert_local.png b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_insert_local.png new file mode 100644 index 000000000..9fa08a0c2 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_insert_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_insert_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_insert_msvc.png new file mode 100644 index 000000000..5f1d740b8 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_random_int_subscript_timing_test_insert_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_table.html b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_table.html new file mode 100644 index 000000000..dd9d725d3 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_table.html @@ -0,0 +1,891 @@ + + + + + + + gp_hash_table Interface + + + + +
+

gp_hash_table Interface

+ +

A concrete general-probing hash-based associative + container.

+ +

Defined in: assoc_container.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+typename Key
+
+ 		+

Key type.

+ 		-
+ 
+typename Mapped
+
+ 		+

Mapped type.

+ 		-
+ 
+class Hash_Fn 
+
+ 		+

Hash functor.

+ 		+ 
+__gnu_cxx::hash<Key>
+
if using gcc; + 
+stdext::hash_value<Key>
+
if using Visual C++ .net +
+ 
+class Eq_Fn 
+
+ 		+

Equivalence functor.

+ 		+ 
+std::equal_to<Key>
+
+
+ 
+class Comb_Probe_Fn 
+
+ 		+

Combining probe functor.

+ +

If Hash_Fn is + null_hash_fn, and Probe_Fn is null_probe_fn, then this is the + ranged-probe functor; otherwise, this is the + range-hashing functor.

+ +

(See Design::Hash-Based + Containers::Hash Policies.)

+ 		direct_mask_range_hashing
+ 
+class Probe_Fn 
+
+ 		+

Probe functor.

+ 		+ If Comb_Probe_Fn + is direct_mask_range_hashing, then + 
+linear_probe_fn<
+  typename Comb_Probe_Fn::size_type>
+
otherwise, + 
+quadratic_probe_fn<
+  typename Comb_Probe_Fn::size_type>
+
+
+ 
+class Resize_Policy 
+
+ 		+

Resize policy.

+ 		+ If Comb_Probe_Fn + is direct_mask_range_hashing, + then + 
+hash_standard_resize_policy<
+  hash_exponential_size_policy<
+    typename Comb_Probe_Fn::size_type>,
+  hash_load_check_resize_trigger<
+    typename Comb_Probe_Fn::size_type>,
+  false,
+  typename Comb_Probe_Fn::size_type>
+
otherwise, + 
+hash_standard_resize_policy<
+  hash_exponential_size_policy<
+    typename Comb_Probe_Fn::size_type>,
+  hash_load_check_resize_trigger<
+    typename Comb_Probe_Fn::size_type>,
+  false,
+  typename Comb_Probe_Fn::size_type>
+
+
+ 
+bool Store_Hash 
+
+ 		+

Indicates whether the hash value will be stored along + with each key.

+ +

If hash_fn is null_hash_fn, then the container + will not compile if this value is + true

+ 		+ 
+false
+
+
+ 
+class Allocator 
+
+ 		+

Allocator type.

+ 		+ 
+std::allocator<char>
+
+
+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+basic_hash_table
+
+ 		+

public

+
+ +

Public Types and + Constants

+ +

Policy Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+hash_fn
+
+ 		+ 
+Hash_Fn
+
+ 		+

Hash functor type.

+
+ 
+eq_fn
+
+ 		+ 
+Eq_Fn
+
+ 		+

Equivalence functor type.

+
+ 
+comb_probe_fn
+
+ 		+ 
+Comb_Probe_Fn
+
+ 		+

Combining probe functor type.

+
+ 
+probe_fn
+
+ 		+ 
+Probe_Fn
+
+ 		+

Probe functor type.

+
+ 
+resize_policy
+
+ 		+ 
+Resize_Policy
+
+ 		+

Resize policy type.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  gp_hash_table
+  ()
+
+ 		+

Default constructor.

+
+ 
+  gp_hash_table
+  (const hash_fn &r_hash_fn)
+
+ 		+

Constructor taking some policy objects. r_hash_fn will be copied by the + hash_fn object of + the container object.

+
+ 
+  gp_hash_table
+  (const hash_fn &r_hash_fn, 
+    const eq_fn &r_eq_fn)
+
+ 		+

Constructor taking some policy objects. r_hash_fn will be copied by the + hash_fn object of + the container object, and r_eq_fn will be copied by the + eq_fn object of the + container object.

+
+ 
+  gp_hash_table
+  (const hash_fn &r_hash_fn, 
+    const eq_fn &r_eq_fn, 
+    const comb_probe_fn &r_comb_probe_fn)
+
+ 		+

Constructor taking some policy objects. r_hash_fn will be copied by the + hash_fn object of + the container object, r_eq_fn will be copied by the + eq_fn object of the + container object, and r_comb_probe_fn will be copied by + the comb_probe_fn + object of the container object.

+
+ 
+  gp_hash_table
+  (const hash_fn &r_hash_fn, 
+    const eq_fn &r_eq_fn, 
+    const comb_probe_fn &r_comb_probe_fn,
+    const probe_fn &r_probe_fn)
+
+ 		+

Constructor taking some policy objects. r_hash_fn will be copied by the + hash_fn object of + the container object, r_eq_fn will be copied by the + eq_fn object of the + container object, r_comb_probe_fn will be copied by + the comb_probe_fn + object of the container object, and r_probe_fn will be copied by the + probe_fn object + of the container object.

+
+ 
+  gp_hash_table
+  (const hash_fn &r_hash_fn, 
+    const eq_fn &r_eq_fn, 
+    const comb_probe_fn &r_comb_probe_fn, 
+    const probe_fn &r_probe_fn,
+    const resize_policy &r_resize_policy)
+
+ 		+

Constructor taking some policy objects. r_hash_fn will be copied by the + hash_fn object of + the container object, r_eq_fn will be copied by the + eq_fn object of the + container object, r_comb_probe_fn will be copied by + the comb_probe_fn + object of the container object, r_probe_fn will be copied by the + probe_fn object + of the container object, and r_resize_policy will be copied by + the Resize_Policy + object of the container object.

+
+ 
+template<
+    class It>
+  gp_hash_table
+  (It first_it, 
+    It last_it)
+
+ 		+

Constructor taking iterators to a range of + value_types. The value_types between first_it and last_it will be inserted into the + container object.

+
+ 
+template<
+    class It>
+  gp_hash_table
+  (It first_it, 
+    It last_it,
+    const hash_fn &r_hash_fn)
+
+ 		+

Constructor taking iterators to a range of value_types + and some policy objects. The value_types between + first_it and + last_it will be inserted + into the container object. r_hash_fn will be copied by the + hash_fn object of + the container object.

+
+ 
+template<
+    class It>
+  gp_hash_table
+  (It first_it, 
+    It last_it,
+    const hash_fn &r_hash_fn, 
+    const eq_fn &r_eq_fn)
+
+ 		+

Constructor taking iterators to a range of value_types + and some policy objects. The value_types between + first_it and + last_it will be inserted + into the container object. r_hash_fn will be copied by the + hash_fn object of + the container object, and r_eq_fn will be copied by the + eq_fn object of the + container object.

+
+ 
+template<
+    class It>
+  gp_hash_table
+  (It first_it, 
+    It last_it,
+    const hash_fn &r_hash_fn, 
+    const eq_fn &r_eq_fn, 
+    const comb_probe_fn &r_comb_probe_fn)
+
+ 		+

Constructor taking iterators to a range of value_types + and some policy objects. The value_types between + first_it and + last_it will be inserted + into the container object. r_hash_fn will be copied by the + hash_fn object of + the container object, r_eq_fn will be copied by the + eq_fn object of the + container object, and r_comb_probe_fn will be copied by + the comb_probe_fn + object of the container object.

+
+ 
+template<
+    class It>
+  gp_hash_table
+  (It first_it, 
+    It last_it,
+    const hash_fn &r_hash_fn, 
+    const eq_fn &r_eq_fn, 
+    const comb_probe_fn &r_comb_probe_fn,
+    const probe_fn &r_probe_fn)
+
+ 		+

Constructor taking iterators to a range of value_types + and some policy objects. The value_types between + first_it and + last_it will be inserted + into the container object. r_hash_fn will be copied by the + hash_fn object of + the container object, r_eq_fn will be copied by the + eq_fn object of the + container object, r_comb_probe_fn will be copied by + the comb_probe_fn + object of the container object, and r_probe_fn will be copied by the + probe_fn object + of the container object.

+
+ 
+template<
+    class It>
+  gp_hash_table
+  (It first_it, 
+    It last_it,
+    const hash_fn &r_hash_fn, 
+    const eq_fn &r_eq_fn, 
+    const comb_probe_fn &r_comb_probe_fn, 
+    const probe_fn &r_probe_fn,      
+    const resize_policy &r_resize_policy)
+
+ 		+

Constructor taking iterators to a range of value_types + and some policy objects. The value_types between + first_it and + last_it will be inserted + into the container object. r_hash_fn will be copied by the + hash_fn object of + the container object, r_eq_fn will be copied by the + eq_fn object of the + container object, r_comb_probe_fn will be copied by + the comb_probe_fn + object of the container object, r_probe_fn will be copied by the + probe_fn object + of the container object, and r_resize_policy will be copied by + the resize_policy + object of the container object.

+
+ 
+  gp_hash_table
+  (const gp_hash_table &other)
+
+ 		+

Copy constructor.

+
+ 
+virtual 
+  ~gp_hash_table
+  ()
+
+ 		+

Destructor.

+
+ 
+gp_hash_table &
+  operator=
+  (const gp_hash_table &other)
+
+ 		+

Assignment operator.

+
+ 
+void
+  swap
+  (gp_hash_table &other)
+
+ 		+

Swaps content.

+
+ +

Policy Access Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+comb_probe_fn &
+  get_comb_probe_fn
+  ()
+
+ 		+

Access to the comb_probe_fn + object.

+
+ 
+const comb_probe_fn &
+  get_comb_probe_fn
+  () const
+
+ 		+

Const access to the comb_probe_fn + object.

+
+ 
+probe_fn &
+  get_probe_fn
+  ()
+
+ 		+

Access to the probe_fn object.

+
+ 
+const probe_fn &
+  get_probe_fn
+  () const
+
+ 		+

Const access to the probe_fn object.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_tag.html new file mode 100644 index 000000000..4c5f06b57 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/gp_hash_tag.html @@ -0,0 +1,47 @@ + + + + + + + gp_hash_tag Interface + + + + +
+

gp_hash_tag Interface

+ +

General-probing hash data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+basic_hash_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_based_containers.html b/libstdc++-v3/doc/html/ext/pb_ds/hash_based_containers.html new file mode 100644 index 000000000..21d092a76 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/hash_based_containers.html @@ -0,0 +1,835 @@ + + + + + + + Hash-Based Containers + + + + +
+

Hash Table Design

+ +

Overview

+ +

The collision-chaining hash-based container has the + following declaration.

+ 
+template<
+    typename Key,
+    typename Mapped,
+    typename Hash_Fn = std::hash<Key>,
+    typename Eq_Fn = std::equal_to<Key>,
+    typename Comb_Hash_Fn = direct_mask_range_hashing<>
+    typename Resize_Policy = default explained below.
+     bool Store_Hash = false,
+     typename Allocator = std::allocator<char> >
+class cc_hash_table;
+
+ +

The parameters have the following meaning:

+ +
    +
  1. Key is the key type.
    2. + +
  2. Mapped is the mapped-policy, and is explained in + Tutorial::Associative + Containers::Associative Containers Others than Maps.
    3. + +
  3. Hash_Fn is a key hashing functor.
    4. + +
  4. Eq_Fn is a key equivalence functor.
    5. + +
  5. Comb_Hash_Fn is a range-hashing_functor; + it describes how to translate hash values into positions + within the table. This is described in Hash Policies.
    6. + +
  6. Resize_Policy describes how a container object + should change its internal size. This is described in + Resize Policies.
    7. + +
  7. Store_Hash indicates whether the hash value + should be stored with each entry. This is described in + Policy Interaction.
    8. + +
  8. Allocator is an allocator + type.
    9. +
+ +

The probing hash-based container has the following + declaration.

+ 
+template<
+    typename Key,
+    typename Mapped,
+    typename Hash_Fn = std::hash<Key>,
+    typename Eq_Fn = std::equal_to<Key>,
+    typename Comb_Probe_Fn = direct_mask_range_hashing<>
+    typename Probe_Fn = default explained below.
+    typename Resize_Policy = default explained below.
+    bool Store_Hash = false,
+    typename Allocator =  std::allocator<char> >
+class gp_hash_table;
+
+ +

The parameters are identical to those of the + collision-chaining container, except for the following.

+ +
    +
  1. Comb_Probe_Fn describes how to transform a probe + sequence into a sequence of positions within the table.
    2. + +
  2. Probe_Fn describes a probe sequence policy.
    3. +
+ +

Some of the default template values depend on the values of + other parameters, and are explained in Policy Interaction.

+ +

Hash + Policies

+ +

General + Terms

+ +

Following is an explanation of some functions which hashing + involves. Figure Hash functions, + ranged-hash functions, and range-hashing functions) + illustrates the discussion.

+ +
+
+ +
Hash functions, ranged-hash functions, and + range-hashing functions.
+ +

Let U be a domain (e.g., the integers, or the + strings of 3 characters). A hash-table algorithm needs to map + elements of U "uniformly" into the range [0,..., m - + 1] (where m is a non-negative integral value, and + is, in general, time varying). I.e., the algorithm needs + a ranged-hash function

+ +

f : U × Z+ → Z+ + ,

+ +

such that for any u in U ,

+ +

0 ≤ f(u, m) ≤ m - 1 ,

+ +

and which has "good uniformity" properties [knuth98sorting]. One + common solution is to use the composition of the hash + function

+ +

h : U → Z+ ,

+ +

which maps elements of U into the non-negative + integrals, and

+ +

g : Z+ × Z+ → + Z+,

+ +

which maps a non-negative hash value, and a non-negative + range upper-bound into a non-negative integral in the range + between 0 (inclusive) and the range upper bound (exclusive), + i.e., for any r in Z+,

+ +

0 ≤ g(r, m) ≤ m - 1 .

+ +

The resulting ranged-hash function, is

+ +

f(u , m) = + g(h(u), m) (1) .

+ +

From the above, it is obvious that given g and + h, f can always be composed (however the converse + is not true). The STL's hash-based containers allow specifying + a hash function, and use a hard-wired range-hashing function; + the ranged-hash function is implicitly composed.

+ +

The above describes the case where a key is to be mapped + into a single position within a hash table, e.g., + in a collision-chaining table. In other cases, a key is to be + mapped into a sequence of positions within a table, + e.g., in a probing table. Similar terms apply in this + case: the table requires a ranged probe function, + mapping a key into a sequence of positions withing the table. + This is typically achieved by composing a hash function + mapping the key into a non-negative integral type, a + probe function transforming the hash value into a + sequence of hash values, and a range-hashing function + transforming the sequence of hash values into a sequence of + positions.

+ +

Range-Hashing Functions

+ +

Some common choices for range-hashing functions are the + division, multiplication, and middle-square methods [knuth98sorting], defined + as

+ +

g(r, m) = + r mod m (2) ,

+ +

g(r, m) = ⌈ u/v ( a r mod v ) ⌉ ,

+ +

and

+ +

g(r, m) = ⌈ u/v ( r2 mod v ) ⌉ + ,

+ +

respectively, for some positive integrals u and + v (typically powers of 2), and some a. Each of + these range-hashing functions works best for some different + setting.

+ +

The division method (2) is a + very common choice. However, even this single method can be + implemented in two very different ways. It is possible to + implement (2) using the low + level % (modulo) operation (for any m), or the + low level & (bit-mask) operation (for the case where + m is a power of 2), i.e.,

+ +

g(r, m) = r % m (3) ,

+ +

and

+ +

g(r, m) = r & m - 1, (m = + 2k) for some k) (4),

+ +

respectively.

+ +

The % (modulo) implementation (3) has the advantage that for + m a prime far from a power of 2, g(r, m) is + affected by all the bits of r (minimizing the chance of + collision). It has the disadvantage of using the costly modulo + operation. This method is hard-wired into SGI's implementation + [sgi_stl].

+ +

The & (bit-mask) implementation (4) has the advantage of + relying on the fast bit-wise and operation. It has the + disadvantage that for g(r, m) is affected only by the + low order bits of r. This method is hard-wired into + Dinkumware's implementation [dinkumware_stl].

+ +

Ranged-Hash + Functions

+ +

In cases it is beneficial to allow the + client to directly specify a ranged-hash hash function. It is + true, that the writer of the ranged-hash function cannot rely + on the values of m having specific numerical properties + suitable for hashing (in the sense used in [knuth98sorting]), since + the values of m are determined by a resize policy with + possibly orthogonal considerations.

+ +

There are two cases where a ranged-hash function can be + superior. The firs is when using perfect hashing [knuth98sorting]; the + second is when the values of m can be used to estimate + the "general" number of distinct values required. This is + described in the following.

+ +

Let

+ +

s = [ s0,..., st - 1]

+ +

be a string of t characters, each of which is from + domain S. Consider the following ranged-hash + function:

+ +

f1(s, m) = ∑ i = + 0t - 1 si ai mod + m (5) ,

+ +

where a is some non-negative integral value. This is + the standard string-hashing function used in SGI's + implementation (with a = 5) [sgi_stl]. Its advantage is that + it takes into account all of the characters of the string.

+ +

Now assume that s is the string representation of a + of a long DNA sequence (and so S = {'A', 'C', 'G', + 'T'}). In this case, scanning the entire string might be + prohibitively expensive. A possible alternative might be to use + only the first k characters of the string, where

+ +

|S|k ≥ m ,

+ +

i.e., using the hash function

+ +

f2(s, m) = ∑ i + = 0k - 1 si ai mod + m , (6)

+ +

requiring scanning over only

+ +

k = log4( m )

+ +

characters.

+ +

Other more elaborate hash-functions might scan k + characters starting at a random position (determined at each + resize), or scanning k random positions (determined at + each resize), i.e., using

+ +

f3(s, m) = ∑ i = + r0r0 + k - 1 si + ai mod m ,

+ +

or

+ +

f4(s, m) = ∑ i = 0k - + 1 sri ari mod + m ,

+ +

respectively, for r0,..., rk-1 + each in the (inclusive) range [0,...,t-1].

+ +

It should be noted that the above functions cannot be + decomposed as (1) .

+ +

Implementation

+ +

This sub-subsection describes the implementation of the + above in pb_ds. It first explains range-hashing + functions in collision-chaining tables, then ranged-hash + functions in collision-chaining tables, then probing-based + tables, and, finally, lists the relevant classes in + pb_ds.

+ +

Range-Hashing and Ranged-Hashes in Collision-Chaining + Tables

+ +

cc_hash_table is + parametrized by Hash_Fn and Comb_Hash_Fn, a + hash functor and a combining hash functor, respectively.

+ +

In general, Comb_Hash_Fn is considered a + range-hashing functor. cc_hash_table + synthesizes a ranged-hash function from Hash_Fn and + Comb_Hash_Fn (see (1) + above). Figure Insert + hash sequence diagram shows an insert sequence + diagram for this case. The user inserts an element (point A), + the container transforms the key into a non-negative integral + using the hash functor (points B and C), and transforms the + result into a position using the combining functor (points D + and E).

+ +
no image
+ +
Insert hash sequence diagram.
+ +

If cc_hash_table's + hash-functor, Hash_Fn is instantiated by null_hash_fn (see Interface::Concepts::Null + Policy Classes), then Comb_Hash_Fn is taken to be + a ranged-hash function. Figure Insert hash sequence diagram + with a null hash policy shows an insert sequence + diagram. The user inserts an element (point A), the container + transforms the key into a position using the combining functor + (points B and C).

+ +
+
+ +
Insert hash sequence diagram with a null hash + policy.
+ +

Probing Tables

+ +

gp_hash_table is + parametrized by Hash_Fn, Probe_Fn, and + Comb_Probe_Fn. As before, if Hash_Fn and + Probe_Fn are, respectively, null_hash_fn and null_probe_fn, then + Comb_Probe_Fn is a ranged-probe functor. Otherwise, + Hash_Fn is a hash functor, Probe_Fn is a + functor for offsets from a hash value, and + Comb_Probe_Fn transforms a probe sequence into a + sequence of positions within the table.

+ +

Pre-Defined Policies

+ +

pb_ds contains some pre-defined classes + implementing range-hashing and probing functions:

+ +
    +
  1. direct_mask_range_hashing + and direct_mod_range_hashing + are range-hashing functions based on a bit-mask and a modulo + operation, respectively.
    2. + +
  2. linear_probe_fn, and + quadratic_probe_fn are + a linear probe and a quadratic probe function, + respectively.
    3. +
Figure Hash policy class + diagram shows a class diagram. + +
+
+ +
Hash policy class diagram.
+ +

Resize + Policies

+ +

General Terms

+ +

Hash-tables, as opposed to trees, do not naturally grow or + shrink. It is necessary to specify policies to determine how + and when a hash table should change its size. Usually, resize + policies can be decomposed into orthogonal policies:

+ +
    +
  1. A size policy indicating how a hash table + should grow (e.g., it should multiply by powers of + 2).
    2. + +
  2. A trigger policy indicating when a hash + table should grow (e.g., a load factor is + exceeded).
    3. +
+ +

Size + Policies

+ +

Size policies determine how a hash table changes size. These + policies are simple, and there are relatively few sensible + options. An exponential-size policy (with the initial size and + growth factors both powers of 2) works well with a mask-based + range-hashing function (see Range-Hashing Policies), and is the + hard-wired policy used by Dinkumware [dinkumware_stl]. A + prime-list based policy works well with a modulo-prime range + hashing function (see Range-Hashing + Policies), and is the hard-wired policy used by SGI's + implementation [sgi_stl].

+ +

Trigger + Policies

+ +

Trigger policies determine when a hash table changes size. + Following is a description of two policies: load-check + policies, and collision-check policies.

+ +

Load-check policies are straightforward. The user specifies + two factors, αmin and + αmax, and the hash table maintains the + invariant that

+ +

αmin ≤ (number of + stored elements) / (hash-table size) ≤ + αmax (1) .

+ +

Collision-check policies work in the opposite direction of + load-check policies. They focus on keeping the number of + collisions moderate and hoping that the size of the table will + not grow very large, instead of keeping a moderate load-factor + and hoping that the number of collisions will be small. A + maximal collision-check policy resizes when the longest + probe-sequence grows too large.

+ +

Consider Figure Balls and + bins. Let the size of the hash table be denoted by + m, the length of a probe sequence be denoted by + k, and some load factor be denoted by α. We would + like to calculate the minimal length of k, such that if + there were α m elements in the hash table, a probe + sequence of length k would be found with probability at + most 1/m.

+ +
+
+ +
Balls and bins.
+ +

Denote the probability that a probe sequence of length + k appears in bin i by pi, the + length of the probe sequence of bin i by + li, and assume uniform distribution. Then

+ +

p1 = (3)

+ +

P(l1 ≥ k) =

+ +

P(l1 ≥ α ( 1 + k / α - 1 + ) ≤ (a)

+ +

e ^ ( - ( α ( k / α - 1 )2 ) /2 + ) ,

+ +

where (a) follows from the Chernoff bound [motwani95random]. To + calculate the probability that some bin contains a probe + sequence greater than k, we note that the + li are negatively-dependent [dubhashi98neg]. Let + I(.) denote the indicator function. Then

+ +

P( existsi + li ≥ k ) = (3)

+ +

P ( ∑ i = 1m + I(li ≥ k) ≥ 1 ) =

+ +

P ( ∑ i = 1m I ( + li ≥ k ) ≥ m p1 ( 1 + 1 / (m + p1) - 1 ) ) ≤ (a)

+ +

e ^ ( ( - m p1 ( 1 / (m p1) + - 1 ) 2 ) / 2 ) ,

+ +

where (a) follows from the fact that the Chernoff bound can + be applied to negatively-dependent variables [dubhashi98neg]. Inserting + (2) into (3), and equating with + 1/m, we obtain

+ +

k ~ √ ( 2 α ln 2 m ln(m) ) + ) .

+ +

Implementation

+ +

This sub-subsection describes the implementation of the + above in pb_ds. It first describes resize policies and + their decomposition into trigger and size policies, then + describes pre-defined classes, and finally discusses controlled + access the policies' internals.

+ +

Resize Policies and Their Decomposition

+ +

Each hash-based container is parametrized by a + Resize_Policy parameter; the container derives + publicly from Resize_Policy. For + example:

+ 
+cc_hash_table<
+    typename Key,
+    typename Mapped,
+    ...
+    typename Resize_Policy
+    ...> :
+        public Resize_Policy
+
+ +

As a container object is modified, it continuously notifies + its Resize_Policy base of internal changes + (e.g., collisions encountered and elements being + inserted). It queries its Resize_Policy base whether + it needs to be resized, and if so, to what size.

+ +

Figure Insert + resize sequence diagram shows a (possible) sequence diagram + of an insert operation. The user inserts an element; the hash + table notifies its resize policy that a search has started + (point A); in this case, a single collision is encountered - + the table notifies its resize policy of this (point B); the + container finally notifies its resize policy that the search + has ended (point C); it then queries its resize policy whether + a resize is needed, and if so, what is the new size (points D + to G); following the resize, it notifies the policy that a + resize has completed (point H); finally, the element is + inserted, and the policy notified (point I).

+ +
+
+ +
Insert resize sequence diagram.
+ +

In practice, a resize policy can be usually orthogonally + decomposed to a size policy and a trigger policy. Consequently, + the library contains a single class for instantiating a resize + policy: hash_standard_resize_policy + is parametrized by Size_Policy and + Trigger_Policy, derives publicly from + both, and acts as a standard delegate [gamma95designpatterns] + to these policies.

+ +

Figures Standard + resize policy trigger sequence diagram and Standard resize policy size + sequence diagram show sequence diagrams illustrating the + interaction between the standard resize policy and its trigger + and size policies, respectively.

+ +
+
+ +
Standard resize policy trigger sequence + diagram.
+ +
+
+ +
Standard resize policy size sequence + diagram.
+ +

Pre-Defined Policies

+ +

The library includes the following + instantiations of size and trigger policies:

+ +
    +
  1. hash_load_check_resize_trigger + implements a load check trigger policy.
    2. + +
  2. cc_hash_max_collision_check_resize_trigger + implements a collision check trigger policy.
    3. + +
  3. hash_exponential_size_policy + implements an exponential-size policy (which should be used + with mask range hashing).
    4. + +
  4. hash_prime_size_policy + implementing a size policy based on a sequence of primes + [sgi_stl] (which should + be used with mod range hashing
    5. +
+ +

Figure Resize policy class + diagram gives an overall picture of the resize-related + classes. basic_hash_table + is parametrized by Resize_Policy, which it subclasses + publicly. This class is currently instantiated only by hash_standard_resize_policy. + hash_standard_resize_policy + itself is parametrized by Trigger_Policy and + Size_Policy. Currently, Trigger_Policy is + instantiated by hash_load_check_resize_trigger, + or cc_hash_max_collision_check_resize_trigger; + Size_Policy is instantiated by hash_exponential_size_policy, + or hash_prime_size_policy.

+ +
+
+ +
Resize policy class diagram.
+ +

Controlled Access to Policies' Internals

+ +

There are cases where (controlled) access to resize + policies' internals is beneficial. E.g., it is sometimes + useful to query a hash-table for the table's actual size (as + opposed to its size() - the number of values it + currently holds); it is sometimes useful to set a table's + initial size, externally resize it, or change load factors.

+ +

Clearly, supporting such methods both decreases the + encapsulation of hash-based containers, and increases the + diversity between different associative-containers' interfaces. + Conversely, omitting such methods can decrease containers' + flexibility.

+ +

In order to avoid, to the extent possible, the above + conflict, the hash-based containers themselves do not address + any of these questions; this is deferred to the resize policies, + which are easier to change or replace. Thus, for example, + neither cc_hash_table nor + gp_hash_table + contain methods for querying the actual size of the table; this + is deferred to hash_standard_resize_policy.

+ +

Furthermore, the policies themselves are parametrized by + template arguments that determine the methods they support + ([alexandrescu01modern] + shows techniques for doing so). hash_standard_resize_policy + is parametrized by External_Size_Access that + determines whether it supports methods for querying the actual + size of the table or resizing it. hash_load_check_resize_trigger + is parametrized by External_Load_Access that + determines whether it supports methods for querying or + modifying the loads. cc_hash_max_collision_check_resize_trigger + is parametrized by External_Load_Access that + determines whether it supports methods for querying the + load.

+ +

Some operations, for example, resizing a container at + run time, or changing the load factors of a load-check trigger + policy, require the container itself to resize. As mentioned + above, the hash-based containers themselves do not contain + these types of methods, only their resize policies. + Consequently, there must be some mechanism for a resize policy + to manipulate the hash-based container. As the hash-based + container is a subclass of the resize policy, this is done + through virtual methods. Each hash-based container has a + private virtual method:

+ 
+virtual void
+    do_resize
+    (size_type new_size);
+
+ +

which resizes the container. Implementations of + Resize_Policy can export public methods for resizing + the container externally; these methods internally call + do_resize to resize the table.

+ +

Policy + Interaction

+ +

Hash-tables are unfortunately especially susceptible to + choice of policies. One of the more complicated aspects of this + is that poor combinations of good policies can form a poor + container. Following are some considerations.

+ +

Probe Policies, Size + Policies, and Trigger Policies

+ +

Some combinations do not work well for probing containers. + For example, combining a quadratic probe policy with an + exponential size policy can yield a poor container: when an + element is inserted, a trigger policy might decide that there + is no need to resize, as the table still contains unused + entries; the probe sequence, however, might never reach any of + the unused entries.

+ +

Unfortunately, pb_ds cannot detect such problems at + compilation (they are halting reducible). It therefore defines + an exception class insert_error to throw an + exception in this case.

+ +

Hash Policies and Trigger + Policies

+ +

Some trigger policies are especially susceptible to poor + hash functions. Suppose, as an extreme case, that the hash + function transforms each key to the same hash value. After some + inserts, a collision detecting policy will always indicate that + the container needs to grow.

+ +

The library, therefore, by design, limits each operation to + one resize. For each insert, for example, it queries + only once whether a resize is needed.

+ +

Equivalence Functors, Storing + Hash Values, and Hash Functions

+ +

cc_hash_table and + gp_hash_table are + parametrized by an equivalence functor and by a + Store_Hash parameter. If the latter parameter is + true, then the container stores with each entry + a hash value, and uses this value in case of collisions to + determine whether to apply a hash value. This can lower the + cost of collision for some types, but increase the cost of + collisions for other types.

+ +

If a ranged-hash function or ranged probe function is + directly supplied, however, then it makes no sense to store the + hash value with each entry. pb_ds's container will + fail at compilation, by design, if this is attempted.

+ +

Size Policies and + Load-Check Trigger Policies

+ +

Assume a size policy issues an increasing sequence of sizes + a, a q, a q1, a q2, ... For + example, an exponential size policy might issue the sequence of + sizes 8, 16, 32, 64, ...

+ +

If a load-check trigger policy is used, with loads + αmin and αmax, + respectively, then it is a good idea to have:

+ +
    +
  1. αmax ~ 1 / q
    2. + +
  2. αmin < 1 / (2 q)
    3. +
+ +

This will ensure that the amortized hash cost of each + modifying operation is at most approximately 3.

+ +

αmin ~ αmax is, in + any case, a bad choice, and αmin > + αmax is horrendous.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_exponential_size_policy.html b/libstdc++-v3/doc/html/ext/pb_ds/hash_exponential_size_policy.html new file mode 100644 index 000000000..1089b1544 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/hash_exponential_size_policy.html @@ -0,0 +1,183 @@ + + + + + + + hash_exponential_size_policy Interface + + + + +
+

hash_exponential_size_policy Interface

+ +

A size policy whose sequence of sizes form an exponential + sequence (typically powers of 2)

+ +

Defined in: hash_policy.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+typename Size_Type 
+
+ 		+

Size type.

+ 		size_t
+ +

Public Types and + Constants

+ +

General Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+Size_Type
+
+ 		+

Size type.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  hash_exponential_size_policy
+  (size_type start_size = 8, 
+    size_type grow_factor = 2)
+
+ 		+

Default constructor, or constructor taking a + start_size, or + constructor taking a start size and grow_factor. The policy will use the + sequence of sizes start_size, start_size * grow_factor, start_size * grow_factor^2, ...

+
+ 
+void 
+  swap
+  (hash_exponential_size_policy &other)
+
+ 		+

Swaps content.

+
+ +

Protected Methods

+ +

Size methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+size_type
+  get_nearest_larger_size
+  (size_type size) const
+
+ 		+

Given a size size, + returns a size that is larger.

+
+ 
+size_type
+  get_nearest_smaller_size
+  (size_type size) const
+
+ 		+

Given a size size, + returns a size that is smaller.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_load_check_resize_trigger.html b/libstdc++-v3/doc/html/ext/pb_ds/hash_load_check_resize_trigger.html new file mode 100644 index 000000000..b22b7b5cf --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/hash_load_check_resize_trigger.html @@ -0,0 +1,583 @@ + + + + + + + hash_load_check_resize_trigger Interface + + + + +
+

hash_load_check_resize_trigger Interface

+ +

A resize trigger policy based on a load check. It keeps the + load factor between some load factors load_min and + load_max.

+ +

Defined in: hash_policy.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+bool External_Load_Access 
+
+ 		+

Specifies whether the load factor can be accessed + externally. The two options have different trade-offs in + terms of flexibility, genericity, and encapsulation.

+ 		false
+ 
+typename Size_Type 
+
+ 		+

Size type.

+ 		size_t
+ +

Public Types and + Constants

+ +

General Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+Size_Type
+
+ 		+

Size type.

+
+ 
+external_load_access
+
+ 		+ 
+External_Load_Access
+
+ 		+

Indicates whether loads can be accessed externally

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  hash_load_check_resize_trigger
+  (float load_min = 0.125, 
+    float load_max = 0.5)
+
+ 		+

Default constructor, or constructor taking + load_min and + load_max load factors + between which this policy will keep the actual load.

+ +

It is the responsibility of the user to ensure that + load_min is smaller than + load_max.

+
+ 
+void
+  swap
+  (hash_load_check_resize_trigger &other)
+
+ 		+

Swaps content.

+
+ 
+  virtual
+    ~hash_load_check_resize_trigger
+    ()
+
+ 		+

Destructor.

+
+ +

Load Access Methods

+ +

These methods are only available if the external access + parameter is set.

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline std::pair<float, float>
+  get_loads
+  () const
+
+ 		+

Returns a pair of the minimal and maximal loads, + respectively.

+ +

Calling this method will not compile when External_Load_Access + == false.

+
+ 
+void 
+  set_loads
+  (std::pair<float, float> load_pair)
+
+ 		+

Sets the loads through a pair of the minimal and + maximal loads, respectively.

+ +

Calling this method resizes the container, and might + throw an exception. It is the responsibility of the user + to pass appropriate loads to this function. Calling this + method will not compile when External_Load_Access + == false.

+
+ +

Protected Methods

+ +

Insert Search + Notifications.

+ +

Notifications called during an insert operation.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_insert_search_start
+  ()
+
+ 		+

Notifies a search started.

+
+ 
+inline void
+  notify_insert_search_collision
+  ()
+
+ 		+

Notifies a search encountered a collision.

+
+ 
+inline void
+  notify_insert_search_end
+  ()
+
+ 		+

Notifies a search ended.

+
+ +

Find Search + Notifications.

+ +

Notifications called during a find operation.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_find_search_start
+  ()
+
+ 		+

Notifies a search started.

+
+ 
+inline void
+  notify_find_search_collision
+  ()
+
+ 		+

Notifies a search encountered a collision.

+
+ 
+inline void
+  notify_find_search_end
+  ()
+
+ 		+

Notifies a search ended.

+
+ +

Erase Search + Notifications.

+ +

Notifications called during an insert operation.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_erase_search_start
+  ()
+
+ 		+

Notifies a search started.

+
+ 
+inline void
+  notify_erase_search_collision
+  ()
+
+ 		+

Notifies a search encountered a collision.

+
+ 
+inline void
+  notify_erase_search_end
+  ()
+
+ 		+

Notifies a search ended.

+
+ +

Content Change + Notifications.

+ +

Notifications called when the content of the table changes + in a way that can affect the resize policy.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_inserted
+  (size_type num_entries)
+
+ 		+

Notifies an element was inserted. the total number of + entries in the table is num_entries.

+
+ 
+inline void
+  notify_erased
+  (size_type num_entries)
+
+ 		+

Notifies an element was erased.

+
+ 
+void 
+  notify_cleared
+  ()
+
+ 		+

Notifies the table was cleared.

+
+ +

Size Change + Notifications.

+ +

Notifications called when the table changes size.

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+void
+  notify_resized
+  (size_type new_size)
+
+ 		+

Notifies the table was resized as a result of this + object's signifying that a resize is needed.

+
+ 
+void
+  notify_externally_resized
+  (size_type new_size)
+
+ 		+

Notifies the table was resized externally.

+
+ +

Queries

+ +

Called to query whether/how to resize.

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline bool 
+  is_resize_needed
+  () const
+
+ 		+

Queries whether a resize is needed.

+
+ 
+inline bool
+  is_grow_needed
+  (size_type size, 
+    size_type num_entries) const
+
+ 		+

Queries whether a grow is needed.

+ +

This method is called only if this object indicated + resize is needed. The actual size of the table is size, and the number of entries in + it is num_entries.

+
+ +

Private Methods

+ +

Overrides

+ + + + + + + + + + + + + +
MethodDescription
+ 
+virtual void
+  do_resize
+  (size_type new_size)
+
+ 		+

Resizes to new_size.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_policy_cd.png b/libstdc++-v3/doc/html/ext/pb_ds/hash_policy_cd.png new file mode 100644 index 000000000..f3122a112 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/hash_policy_cd.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_prime_size_policy.html b/libstdc++-v3/doc/html/ext/pb_ds/hash_prime_size_policy.html new file mode 100644 index 000000000..8976767b4 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/hash_prime_size_policy.html @@ -0,0 +1,149 @@ + + + + + + + hash_prime_size_policy Interface + + + + +
+

hash_prime_size_policy Interface

+ +

A size policy whose sequence of sizes form a + nearly-exponential sequence of primes.

+ +

Defined in: hash_policy.hpp

+ +

Public Types and + Constants

+ +

General Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+size_t
+
+ 		+

Size type.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  hash_prime_size_policy
+  (size_type start_size = 8)
+
+ 		+

Default constructor, or constructor taking a + start_size The policy + will use the sequence of sizes approximately start_size, start_size * 2, start_size * 2^2, ...

+
+ 
+inline void
+  swap
+  (hash_prime_size_policy &other)
+
+ 		+

Swaps content.

+
+ +

Protected Methods

+ +

Size methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+size_type
+  get_nearest_larger_size
+  (size_type size) const
+
+ 		+

Given a size size, + returns a size that is larger.

+
+ 
+size_type
+  get_nearest_smaller_size
+  (size_type size) const
+
+ 		+

Given a size size, + returns a size that is smaller.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_erase_mem_usage_test.html b/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_erase_mem_usage_test.html new file mode 100644 index 000000000..2867595b0 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_erase_mem_usage_test.html @@ -0,0 +1,173 @@ + + + + + +Tree Text Locality of Reference Timing Test + + + +
+

Hash-Based Erase Memory-Use Test

+

Description

+

This test inserts a number of uniform i.i.d. integer keys + into a container, then erases all keys except one. It measures + the final size of the container.

+

(The test was executed with hash_random_int_erase_mem_usage.cc + 2000 2000 2100)

+

Purpose

+

The test checks how containers adjust internally as their + logical size decreases (see Motivation::Associative + Containers::Slightly Different Methods::Methods Related to + Erase).

+

Results

+

Figures NHG, NHM and + NHL show the results for the native and + collision-chaining types in g++, msvc++ and + local, + respectively.

+
+
+
+
+
no image
NHG: Native, collision-chaing, and probing, hash random int erase test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_set_ncah- +std::tr1::unordered_set with cache_hash_code = false
    2. +
  2. +gp_hash_mask_linp_exp_nea_lc_1div8_1div2_nsth_set- +gp_hash_table + with Comb_Hash_Fn = direct_mask_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = linear_probe_fn +
    3. +
  3. +cc_hash_mod_prime_nea_lc_1div8_1div1_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    4. +
  4. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    5. +
+
+
+
+
+
+
+
+
+
+
no image
NHM: Native, collision-chaing, and probing, hash random int erase test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_set_ncah- +stdext::hash_set
    2. +
  2. +gp_hash_mask_linp_exp_nea_lc_1div8_1div2_nsth_set- +gp_hash_table + with Comb_Hash_Fn = direct_mask_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = linear_probe_fn +
    3. +
  3. +cc_hash_mod_prime_nea_lc_1div8_1div1_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    4. +
  4. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    5. +
+
+
+
+
+
+
+
+
+
+
no image
NHM: Native, collision-chaing, and probing, hash random int erase test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_set_ncah- +stdext::hash_set
    2. +
  2. +gp_hash_mask_linp_exp_nea_lc_1div8_1div2_nsth_set- +gp_hash_table + with Comb_Hash_Fn = direct_mask_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = linear_probe_fn +
    3. +
  3. +cc_hash_mod_prime_nea_lc_1div8_1div1_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    4. +
  4. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    5. +
+
+
+
+
+
+
+
+
+
+
no image
NHL: Native, collision-chaing, and probing, hash random int erase test - local
+
+
+
+
+

Observations

+

STL hash-based containers act very differently than trees in + this respect. When erasing numerous keys from an STL + associative-container, the resulting memory user varies greatly + depending on whether the container is tree-based or hash-based. + As noted in Motivation::Choice of + Methods , this is a fundamental consequence of the STL's + associative containers' interface, it is not due to a specific + implementation.

+

(See Priority Queue + Text pop Memory Use Test for a similar phenomenon + regarding priority queues.)

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_erase_mem_usage_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_erase_mem_usage_test_gcc.png new file mode 100644 index 000000000..c552506a7 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_erase_mem_usage_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_erase_mem_usage_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_erase_mem_usage_test_local.png new file mode 100644 index 000000000..dbd3ee9d3 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_erase_mem_usage_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_erase_mem_usage_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_erase_mem_usage_test_msvc.png new file mode 100644 index 000000000..8c23d46da Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_erase_mem_usage_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_find_find_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_find_find_timing_test.html new file mode 100644 index 000000000..b6066e7cf --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_find_find_timing_test.html @@ -0,0 +1,247 @@ + + + + + +Hash Random Int Find Timing Test + + + +
+

Hash-Based Random-Integer find Find Timing + Test

+

Description

+

This test inserts a number of values with uniform i.i.d. + integer keys into a container, then performs a series of finds + using find. It measures the average time + forfind as a function of the number of values + inserted.

+

(The test was executed with random_int_find_timing_test + 200 200 2100)

+

Purpose

+

The test checks the effect of different underlying + hash-tables (see Design::Associative + Containers::Associative Containers::Hash-Based Containers), + range-hashing functions, and trigger policies (see Design::Associative + Containers::Hash-Based Containers::Hash Policies and + Design::Associative + Containers::Hash-Based Containers::Resize Policies).

+

Results

+

Figures NCCG, NCCM, + and NCCL show the results for the native + and collision-chaining types in g++, MSVC++, and + local, + respectively; Figures NGPG, NGPM, and NGPL show the results + for the native and probing types in g++, MSVC++, and + local + respectively.

+
+
+
+
+
no image
NCCG: Native and collision-chaining hash random int find timing test using find - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_map_ncah- +std::tr1::unordered_map with cache_hash_code = false
    2. +
  2. +cc_hash_mod_prime_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    3. +
  3. +cc_hash_mod_prime_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    4. +
  4. +cc_hash_mask_exp_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    5. +
  5. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    6. +
+
+
+
+
+
+
+
+
+
+
no image
NCCM: Native and collision-chaining hash random int find timing test using find - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +cc_hash_mod_prime_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    2. +
  2. +cc_hash_mod_prime_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    3. +
  3. +n_hash_map_ncah- +stdext::hash_map
    4. +
  4. +cc_hash_mask_exp_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    5. +
  5. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    6. +
+
+
+
+
+
+
+
+
+
+
no image
NCCL: Native and collision-chaining hash random int find timing test using find - local
+
+
+
+
+
+
+
+
+
no image
NGPG: Native and collision-chaining hash random int find timing test using find - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +gp_hash_mod_quadp_prime_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mod_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = quadratic_probe_fn +
    2. +
  2. +n_hash_map_ncah- +std::tr1::unordered_map with cache_hash_code = false
    3. +
  3. +gp_hash_mask_linp_exp_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mask_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = linear_probe_fn +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NGPM: Native and collision-chaining hash random int find timing test using find - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +gp_hash_mod_quadp_prime_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mod_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = quadratic_probe_fn +
    2. +
  2. +n_hash_map_ncah- +stdext::hash_map
    3. +
  3. +gp_hash_mask_linp_exp_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mask_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = linear_probe_fn +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NGPL: Native and collision-chaining hash random int find timing test using find - local
+
+
+
+
+

Observations

+

In this setting, the choice of underlying hash-table (see + Design::Associative + Containers::Hash-Based Containers ) affects performance + most, then the range-hashing scheme (See Design::Associative + Containers::Hash-Based Containers::Hash Policies ), and, + only finally, other policies.

+

When comparing Figures NCCG and NCCM to NGPG and NGPM , respectively, it is apparent that the + probing containers are less efficient than the + collision-chaining containers (both + std::tr1::unordered_map and stdext::hash_map + use collision-chaining) in this case.

+

( Hash-Based + Random-Integer Subscript Insert Timing Test shows a + different case, where the situation is reversed; Observations::Hash-Based + Container Types discusses some further considerations.)

+

Within each type of hash-table, the range-hashing scheme + affects performance more than other policies; Hash-Based + Text find Find Timing Test::Observations discusses + this. In Figures NCCG , NCCM , NGPG , and NGPM , it should be noted that + std::tr1::unordered_map and stdext::hash_map + are hard-wired currently to mod-based and mask-based schemes, + respectively.

+

Observations::Hash-Based + Container Types summarizes some observations on hash-based + containers; Observations::Hash-Based + Containers' Policies summarizes some observations on + hash-based containers' policies.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_subscript_find_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_subscript_find_timing_test.html new file mode 100644 index 000000000..002516370 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_subscript_find_timing_test.html @@ -0,0 +1,220 @@ + + + + + +Hash Random Int Subscript Find Timing Test + + + +
+

Hash-Based Random-Integer operator[] + FindTiming Test

+

Description

+

This test inserts a number of values with uniform i.i.d. + integer keys into a container, then performs a series of finds + using operator[]. It measures the average time + for operator[] as a function of the number of + values inserted.

+

(The test was executed with hash_random_int_subscript_find_timing_test + 200 200 2100)

+

Purpose

+

The test checks the effect of different underlying + hash-tables (see Design::Hash-Based Containers + ), range-hashing functions, and trigger policies (see Design::Hash-Based + Containers::Hash Policies and Design::Hash-Based + Containers::Resize Policies ).

+

Results

+

Figures NCCG, NCCM, + and NCCL show the results for the native + and collision-chaining types in g++, MSVC++, and + local, + respectively; Figures NGPG, NGPM, and NGPL show the results + for the native and probing types in g++, MSVC++, and + local, + respectively.

+
+
+
+
+
no image
NCCG: Native and collision-chaining hash random int find timing test using operator[] - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_map_ncah- +std::tr1::unordered_map with cache_hash_code = false
    2. +
  2. +cc_hash_mod_prime_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    3. +
  3. +cc_hash_mod_prime_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    4. +
  4. +cc_hash_mask_exp_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    5. +
  5. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    6. +
+
+
+
+
+
+
+
+
+
+
no image
NCCM: Native and collision-chaining hash random int find timing test using operator[] - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +cc_hash_mod_prime_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    2. +
  2. +cc_hash_mod_prime_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    3. +
  3. +n_hash_map_ncah- +stdext::hash_map
    4. +
  4. +cc_hash_mask_exp_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    5. +
  5. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    6. +
+
+
+
+
+
+
+
+
+
+
no image
NCCL: Native and collision-chaining hash random int find timing test using operator[] - local
+
+
+
+
+
+
+
+
+
no image
NGPG: Native and probing hash random int find timing test using operator[] - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_map_ncah- +std::tr1::unordered_map with cache_hash_code = false
    2. +
  2. +gp_hash_mod_quadp_prime_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mod_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = quadratic_probe_fn +
    3. +
  3. +gp_hash_mask_linp_exp_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mask_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = linear_probe_fn +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NGPM: Native and probing hash random int find timing test using operator[] - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +gp_hash_mod_quadp_prime_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mod_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = quadratic_probe_fn +
    2. +
  2. +n_hash_map_ncah- +stdext::hash_map
    3. +
  3. +gp_hash_mask_linp_exp_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mask_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = linear_probe_fn +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NGPL: Native and probing hash random int find timing test using operator[] - local
+
+
+
+
+

Observations

+

This test shows similar results to Hash-Based + Random-Integer find Find Timing Test .

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_subscript_insert_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_subscript_insert_timing_test.html new file mode 100644 index 000000000..a15d03ba4 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/hash_random_int_subscript_insert_timing_test.html @@ -0,0 +1,365 @@ + + + + + +Hash Random Int Subscript Insert Timing Test + + + +
+

Hash-Based Random-Integer operator[] Insert + Timing Test

+

Description

+

This test inserts a number of values with uniform i.i.d. + integer keys into a container, using + operator[]. It measures the average time for + operator[] as a function of the number of + values inserted.

+

(The test was executed with hash_random_int_subscript_insert_timing_test + 200 200 2100)

+

Purpose

+

The test primarily checks the effect of different underlying + hash-tables (see Design::Associative + Containers::Associative Containers::Hash-Based + Containers).

+

Results

+

Figures NCCG, NCCM, + and NCCL show the results for the native + and collision-chaining types in g++, MSVC++, and + local, + respectively; Figures NGPG, NGPM, and NGPL show the results + for the native and probing types in g++, msvc++, and + local + respectively; Figures CCGPG, CCGPM, and CCGPL compare the + results for the collision-chaining and probing types of + pb_ds only, in g++, MSVC++, and + local + respectively.

+
+
+
+
+
no image
NCCG: Native and collision-chaining hash random int insert timing test using operator - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +cc_hash_mod_prime_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    2. +
  2. +n_hash_map_ncah- +std::tr1::unordered_map with cache_hash_code = false
    3. +
  3. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    4. +
  4. +cc_hash_mod_prime_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    5. +
  5. +cc_hash_mask_exp_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    6. +
+
+
+
+
+
+
+
+
+
+
no image
NCCM: Native and collision-chaining hash random int insert timing test using operator - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_map_ncah- +stdext::hash_map
    2. +
  2. +cc_hash_mod_prime_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    3. +
  3. +cc_hash_mod_prime_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    4. +
  4. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    5. +
  5. +cc_hash_mask_exp_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    6. +
+
+
+
+
+
+
+
+
+
+
no image
NCCL: Native and collision-chaining hash random int insert timing test using operator - local
+
+
+
+
+
+
+
+
+
no image
NGPG: Native and probing hash random int insert timing test using operator - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +gp_hash_mod_quadp_prime_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mod_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = quadratic_probe_fn +
    2. +
  2. +n_hash_map_ncah- +std::tr1::unordered_map with cache_hash_code = false
    3. +
  3. +gp_hash_mask_linp_exp_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mask_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = linear_probe_fn +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NGPM: Native and probing hash random int insert timing test using operator - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_map_ncah- +stdext::hash_map
    2. +
  2. +gp_hash_mod_quadp_prime_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mod_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = quadratic_probe_fn +
    3. +
  3. +gp_hash_mask_linp_exp_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mask_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = linear_probe_fn +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NGPL: Native and probing hash random int insert timing test using operator - local
+
+
+
+
+
+
+
+
+
no image
CCGPG: Collision-chaining and probing hash random int insert timing test using operator - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +gp_hash_mod_quadp_prime_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mod_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = quadratic_probe_fn +
    2. +
  2. +cc_hash_mod_prime_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    3. +
  3. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    4. +
  4. +gp_hash_mask_linp_exp_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mask_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = linear_probe_fn +
    5. +
+
+
+
+
+
+
+
+
+
+
no image
CCGPM: Collision-chaining and probing hash random int insert timing test using operator - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +cc_hash_mod_prime_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    2. +
  2. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    3. +
  3. +gp_hash_mod_quadp_prime_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mod_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = quadratic_probe_fn +
    4. +
  4. +gp_hash_mask_linp_exp_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mask_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = linear_probe_fn +
    5. +
+
+
+
+
+
+
+
+
+
+
no image
CCGPL: Collision-chaining and probing hash random int insert timing test using operator - local
+
+
+
+
+

Observations

+

In this setting, as in Hash-Based Text + find Find Timing Test and Hash-Based + Random-Integer find Find Timing Test , the choice + of underlying hash-table underlying hash-table (see Design::Associative + Containers::Hash-Based Containers ) affects performance + most, then the range-hashing scheme (See Design::Associative + Containers::Hash-Based Containers::Hash Policies ), and, + only finally, other policies.

+

There are some differences, however:

+
    +
  1. In this setting, probing tables function sometimes more + efficiently than collision-chaining tables (see Figures + CCGPG and CCGPM ). + This is explained shortly.
    2. +
  2. The performance graphs have a "saw-tooth" shape. The + average insert time rises and falls. As values are inserted + into the container, the load factor grows larger. Eventually, + a resize occurs. The reallocations and rehashing are + relatively expensive. After this, the load factor is smaller + than before.
    3. +
+

Collision-chaining containers use indirection for greater + flexibility; probing containers store values contiguously, in + an array (see Figure Motivation::Different + underlying data structures A and B, respectively). It + follows that for simple data types, probing containers access + their allocator less frequently than collision-chaining + containers, (although they still have less efficient probing + sequences). This explains why some probing containers fare + better than collision-chaining containers in this case.

+

Within each type of hash-table, the range-hashing scheme + affects performance more than other policies. This is similar + to the situation in Hash-Based Text + find Find Timing Test and Hash-Based + Random-Integer find Find Timing Test. + Unsurprisingly, however, containers with lower +alphamax perform worse in this case, + since more re-hashes are performed.

+

Observations::Hash-Based + Container Types summarizes some observations on hash-based + containers; Observations::Hash-Based + Containers' Policies summarizes some observations on + hash-based containers' policies.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_range_hashing_seq_diagram.png b/libstdc++-v3/doc/html/ext/pb_ds/hash_range_hashing_seq_diagram.png new file mode 100644 index 000000000..5c37407dd Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/hash_range_hashing_seq_diagram.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_range_hashing_seq_diagram2.png b/libstdc++-v3/doc/html/ext/pb_ds/hash_range_hashing_seq_diagram2.png new file mode 100644 index 000000000..87763caac Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/hash_range_hashing_seq_diagram2.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_ranged_hash_range_hashing_fns.png b/libstdc++-v3/doc/html/ext/pb_ds/hash_ranged_hash_range_hashing_fns.png new file mode 100644 index 000000000..5e0d7f403 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/hash_ranged_hash_range_hashing_fns.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_standard_resize_policy.html b/libstdc++-v3/doc/html/ext/pb_ds/hash_standard_resize_policy.html new file mode 100644 index 000000000..8dbc57ce2 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/hash_standard_resize_policy.html @@ -0,0 +1,795 @@ + + + + + + + hash_standard_resize_policy Interface + + + + +
+

hash_standard_resize_policy Interface

+ +

A resize policy which delegates operations to size and + trigger policies.

+ +

Defined in: hash_policy.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+class Size_Policy 
+
+ 		+

Size policy type.

+ 		hash_exponential_size_policy
+ 
+class Trigger_Policy 
+
+ 		+

Trigger policy type.

+ 		hash_load_check_resize_trigger
+ 
+bool External_Size_Access 
+
+ 		+

Indicates whether physical sizes can be accessed + externally.

+ 		false
+ 
+typename Size_Type 
+
+ 		+

Size type.

+ 		size_t
+ +

Base Classes

+ + + + + + + + + + + + + + + + + + + +
ClassDerivation Type
+ 
+Size_Policy
+
+ 		+

public

+
+ 
+Trigger_Policy
+
+ 		+

public

+
+ +

Public Types and + Constants

+ +

General Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+Size_Type
+
+ 		+

Size type.

+
+ +

Policy Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+trigger_policy
+
+ 		+ 
+Trigger_Policy
+
+ 		+

Trigger policy type.

+
+ 
+size_policy
+
+ 		+ 
+Size_Policy
+
+ 		+

Size policy type.

+
+ 
+external_size_access
+
+ 		+ 
+External_Size_Access
+
+ 		+

Indicates whether sizes can be accessed + externally.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  hash_standard_resize_policy
+  ()
+
+ 		+

Default constructor.

+
+ 
+  hash_standard_resize_policy
+  (const Size_Policy &r_size_policy)
+
+ 		+

constructor taking some policies r_size_policy will be copied by the + Size_Policy + object of this object.

+
+ 
+  hash_standard_resize_policy
+  (const Size_Policy &r_size_policy,
+    const Trigger_Policy &r_trigger_policy)
+
+ 		+

constructor taking some policies. r_size_policy will be copied by the + Size_Policy + object of this object. r_trigger_policy will be copied by + the Trigger_Policy + object of this object.

+
+ 
+virtual 
+  ~hash_standard_resize_policy
+  ()
+
+ 		+

Destructor.

+
+ 
+inline void 
+  swap
+  (hash_standard_resize_policy &other)
+
+ 		+

Swaps content.

+
+ +

Policy Access Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+Size_Policy &
+  get_size_policy
+  ()
+
+ 		+

Access to the Size_Policy object + used.

+
+ 
+const Size_Policy &
+  get_size_policy
+  () const
+
+ 		+

Const access to the Size_Policy object + used.

+
+ 
+Trigger_Policy &
+  get_trigger_policy
+  ()
+
+ 		+

Access to the Trigger_Policy + object used.

+
+ 
+const Trigger_Policy &
+  get_trigger_policy
+  () const
+
+ 		+

Access to the Trigger_Policy + object used.

+
+ +

Size Access Methods

+ +

These methods are available only if the external size + parameter indicates that external size access is allowed.

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline size_type 
+  get_actual_size
+  () const
+
+ 		+

Returns the actual size of the container.

+ +

This method returns the number of entries (used and + unused) in the container. It is different from the + container's size method, which returns the number of used + entries. Calling this method will not compile when + External_Size_Access + == false.

+
+ 
+void 
+  resize
+  (size_type suggested_new_size)
+
+ 		+

Resizes the container to suggested_new_size, a suggested size + (the actual size will be determined by the Size_Policy + object).

+ +

Calling this method will not compile when External_Size_Access + == false.

+
+ +

Protected Methods

+ +

Insert Search + Notifications.

+ +

Notifications called during an insert operation.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_insert_search_start
+  ()
+
+ 		+

Notifies a search started.

+
+ 
+inline void
+  notify_insert_search_collision
+  ()
+
+ 		+

Notifies a search encountered a collision.

+
+ 
+inline void
+  notify_insert_search_end
+  ()
+
+ 		+

Notifies a search ended.

+
+ +

Find Search + Notifications.

+ +

Notifications called during a find operation.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_find_search_start
+  ()
+
+ 		+

Notifies a search started.

+
+ 
+inline void
+  notify_find_search_collision
+  ()
+
+ 		+

Notifies a search encountered a collision.

+
+ 
+inline void
+  notify_find_search_end
+  ()
+
+ 		+

Notifies a search ended.

+
+ +

Erase Search + Notifications.

+ +

Notifications called during an insert operation.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_erase_search_start
+  ()
+
+ 		+

Notifies a search started.

+
+ 
+inline void
+  notify_erase_search_collision
+  ()
+
+ 		+

Notifies a search encountered a collision.

+
+ 
+inline void
+  notify_erase_search_end
+  ()
+
+ 		+

Notifies a search ended.

+
+ +

Content Change + Notifications

+ +

Notifications called when the content of the table changes + in a way that can affect the resize policy.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_inserted
+  (size_type num_e)
+
+ 		+

Notifies an element was inserted.

+
+ 
+inline void
+  notify_erased
+  (size_type num_e)
+
+ 		+

Notifies an element was erased.

+
+ 
+void 
+  notify_cleared
+  ()
+
+ 		+

Notifies the table was cleared.

+
+ +

Size Change + Notifications

+ +

Notifications called when the table changes size.

+ + + + + + + + + + + + + +
MethodDescription
+ 
+void
+  notify_resized
+  (size_type new_size)
+
+ 		+

Notifies the table was resized to new_size.

+
+ +

Queries

+ +

Called to query whether/how to resize.

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline bool
+  is_resize_needed
+  () const
+
+ 		+

Queries whether a resize is needed.

+
+ 
+size_type
+  get_new_size
+  (size_type size, 
+    size_type num_used_e) const
+
+ 		+

Queries what the new size should be, when the container + is resized naturally. The current size of the container + is size, and the number + of used entries within the container is num_used_e.

+
+ +

Private Methods

+ +

Overrides

+ + + + + + + + + + + + + +
MethodDescription
+ 
+virtual void
+  do_resize
+  (size_type new_size)
+
+ 		+

Resizes to new_size.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_text_find_find_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/hash_text_find_find_timing_test.html new file mode 100644 index 000000000..60c30fd34 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/hash_text_find_find_timing_test.html @@ -0,0 +1,164 @@ + + + + + +Hash Text Find Timing Test + + + +
+

Hash-Based Text find Find Timing Test

+

Description

+

This test inserts a number of values with keys from an + arbitrary text ([ wickland96thirty ]) into + a container, then performs a series of finds using + find . It measures the average time for find + as a function of the number of values inserted.

+

(The test was executed with text_find_timing_test + thirty_years_among_the_dead_preproc.txt 200 200 2100)

+

Purpose

+

The test checks the effect of different range-hashing + functions, trigger policies, and cache-hashing policies (see + Design::Associative + Containers::Associative Containers::Hash-Based Containers::Hash + Policies and Design::Associative + Containers::Hash-Based Containers::Resize Policies ).

+

Results

+

Figures NCCG, NCCM + and NCCL show the results for the native + and collision-chaining types in g++, msvc++, and + local, + respetively.

+
+
+
+
+
no image
NCCG: Native and collision-chaining hash text find timing test using find - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_map_ncah- +std::tr1::unordered_map with cache_hash_code = false
    2. +
  2. +cc_hash_mod_prime_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    3. +
  3. +cc_hash_mask_exp_nea_lc_1div8_1div2_sth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    4. +
  4. +cc_hash_mask_exp_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    5. +
  5. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    6. +
+
+
+
+
+
+
+
+
+
+
no image
NCCM: Native and collision-chaining hash text find timing test using find - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_map_ncah- +stdext::hash_map
    2. +
  2. +cc_hash_mod_prime_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    3. +
  3. +cc_hash_mask_exp_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    4. +
  4. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    5. +
  5. +cc_hash_mask_exp_nea_lc_1div8_1div2_sth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    6. +
+
+
+
+
+
+
+
+
+
+
no image
NCCL: Native and collision-chaining hash text find timing test using find - local
+
+
+
+
+

Observations

+

In this setting, the range-hashing scheme (See Design::Associative + Containers::Hash-Based Containers::Hash Policies ) affects + performance more than other policies. As Figure NCCG shows, containers using mod-based + range-hashing (including the native hash-based container, which + is currently hard-wired to this scheme) have lower performance + than those using mask-based range-hashing. A modulo-based + range-hashing scheme's main benefit is that it takes into + account all hash-value bits. Standard string hash-functions are + designed to create hash values that are nearly-uniform as is [ + knuth98sorting + ].

+

Trigger policies (see Design::Associative + Containers::Hash-Based Containers::Resize Policies ), + i.e. the load-checks constants, affect performance to a + lesser extent.

+

Perhaps surprisingly, storing the hash value alongside each + entry affects performance only marginally, at least in + pb_ds 's implementation. (Unfortunately, it was not + possible to run the tests with std::tr1::unordered_map + 's cache_hash_code = true , as it appeared to + malfuntion.)

+

Observations::Hash-Based + Containers' Policies summarizes some observations on + hash-based containers' policies.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_zlob_random_int_find_find_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/hash_zlob_random_int_find_find_timing_test.html new file mode 100644 index 000000000..bfbb3b086 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/hash_zlob_random_int_find_find_timing_test.html @@ -0,0 +1,163 @@ + + + + + +Hash Skewed Distribution Memory Use Test + + + +
+

Hash-Based Skewed-Distribution Random-Integer find + Find Timing Test

+

Description

+

This test inserts a number of values with a markedly + non-uniform i.i.d. integer keys into a container, then performs + a series of finds using find . It measures the average + time for find as a function of the number of values in + the containers. The keys are generated as follows. First, a + uniform integer is created; it is then shifted left 8 bits.

+

(The test was executed with hash_zlob_random_int_find_timing_test + 200 200 2100)

+

Purpose

+

The test checks the effect of different range-hashing + functions and trigger policies (see Design::Associative + Containers::Hash-Based Containers::Hash Policies and + Design::Associative + Containers::Hash-Based Containers::Resize Policies).

+

Results

+

Figures NHG, NHM, and + NHL show the results for various hash-based + associative-containers in g++, MSVC++, and + local, + respectively.

+
+
+
+
+
no image
NHG: Skewed-distribution random int find timing test using find - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +cc_hash_mask_exp_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    2. +
  2. +gp_hash_mod_quadp_prime_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mod_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = quadratic_probe_fn +
    3. +
  3. +n_hash_map_ncah- +std::tr1::unordered_map with cache_hash_code = false
    4. +
  4. +cc_hash_mod_prime_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    5. +
+
+
+
+
+
+
+
+
+
+
no image
NHM: Skewed-distribution random int find timing test using find - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_map_ncah- +stdext::hash_map
    2. +
  2. +cc_hash_mask_exp_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    3. +
  3. +gp_hash_mod_quadp_prime_nea_lc_1div8_1div2_nsth_map- +gp_hash_table + with Comb_Hash_Fn = direct_mod_range_hashing +, Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, and Probe_Fn = quadratic_probe_fn +
    4. +
  4. +cc_hash_mod_prime_nea_lc_1div8_1div1_nsth_map- +cc_hash_table +with Comb_Hash_Fn = direct_mod_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_prime_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/1
    5. +
+
+
+
+
+
+
+
+
+
+
no image
NHL: Skewed-distribution random int find timing test using find - local
+
+
+
+
+

Observations

+

In this setting, the keys' distribution is so skewed that + the unerlying hash-table type affects performance marginally. + (This is in contrast with Hash-Based Text + find Find Timing Test , Hash-Based + Random-Integer find Find Timing Test , Hash-Based + Random-Integer Subscript Find Timing Test and Hash-Based + Random-Integer Subscript Insert Timing Test .)

+

The range-hashing scheme affects performance dramatically. A + mask-based range-hashing scheme effectively maps all values + into the same bucket. Access degenerates into a search within + an unordered linked-list. In Figures NHG and + NHM , it should be noted that + std::tr1::unordered_map and stdext::hash_map + are hard-wired currently to mod-based and mask-based schemes, + respectively.

+

When observing the settings of this test, it is apparent + that the keys' distribution is far from natural. One might ask + if the test is not contrived to show that, in some cases, + mod-based range hashing does better than mask-based range + hashing. This is, in fact just the case. We did not encounter a + more natural case in which mod-based range hashing is better. + In our opnion, real-life key distributions are handled better + with an appropriate hash function and a mask-based + range-hashing function. (shift_mask.cc + shows an example of handling this a-priori known skewed + distribution with a mask-based range-hashing function). If hash + performance is bad, a Χ2 test can be used + to check how to transform it into a more uniform + distribution.

+

For this reason, pb_ds's default range-hashing + function is mask-based.

+

Observations::Hash-Based + Container Types summarizes some observations on hash-based + containers; Observations::Hash-Based + Containers' Policies summarizes some observations on + hash-based containers' policies.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_zlob_random_int_find_timing_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/hash_zlob_random_int_find_timing_test_gcc.png new file mode 100644 index 000000000..8d170db1a Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/hash_zlob_random_int_find_timing_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_zlob_random_int_find_timing_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/hash_zlob_random_int_find_timing_test_local.png new file mode 100644 index 000000000..0be2f00fa Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/hash_zlob_random_int_find_timing_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/hash_zlob_random_int_find_timing_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/hash_zlob_random_int_find_timing_test_msvc.png new file mode 100644 index 000000000..874e7a780 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/hash_zlob_random_int_find_timing_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/index.html b/libstdc++-v3/doc/html/ext/pb_ds/index.html new file mode 100644 index 000000000..4c73c2e91 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/index.html @@ -0,0 +1,146 @@ + + + + + + + Policy-Based Data Structures + + + + +
+

Policy-Based Data Structures

+ +
Ami Tavory and Vladimir Dreizin, IBM Haifa Research + Laboratories, and Benjamin Kosnik, Red Hat
+ +
pbassoc@gmail.com
+ +

This is a library of policy-based elementary + data structures: associative containers and priority queues. It + is designed for high-performance, flexibility, semantic safety, + and conformance to the corresponding containers in std + and std::tr1 (except for some points where it differs by + design).

+ +

The documentation is organized as follows:

+ +
    +
  1. + Introductory + +
      +
    1. Introduction
      2. + +
    2. Motivation
      3. + +
    3. Usage + Prerequisites
      4. +
    +
    2. + +
  2. + Interface + +
      +
    1. Short Tutorial
      2. + +
    2. Concepts
      3. + +
    3. Specifics
      4. +
    +
    3. + +
  3. + Design + +
      +
    1. + Associative Containers + +
        +
      1. Data-Structure + Genericity and Interface
        2. + +
      2. Tree-Based + Containers
        3. + +
      3. Trie-Based + Containers
        4. + +
      4. Hash-Based + Containers
        5. + +
      5. List-Based + Containers
        6. +
      +
      2. + +
    2. Priority Queues
      3. +
    +
    4. + +
  4. + Examples + +
      +
    1. Associative + Containers
      2. + +
    2. Priority Queues
      3. +
    +
    5. + +
  5. + Tests + +
      +
    1. + Associative Containers + +
        +
      1. Regression + Tests
        2. + +
      2. Performance + Tests
        3. +
      +
      2. + +
    2. + Priority Queues + +
        +
      1. Regression + Tests
        2. + +
      2. Performance + Tests
        3. +
      +
      3. +
    +
    6. + +
  6. + Misc. + +
      +
    1. Acknowledgments
      2. + +
    2. Contact
      3. + +
    3. Disclaimer and + Copyright
      4. + +
    4. References
      5. +
    +
    7. +
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/insert_error.html b/libstdc++-v3/doc/html/ext/pb_ds/insert_error.html new file mode 100644 index 000000000..37a89aaf9 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/insert_error.html @@ -0,0 +1,53 @@ + + + + + + +insert_error Interface + + + + +
+

insert_error Interface

+ +

An entry cannot be inserted into a container object for logical +reasons (not, e.g., if memory is unavailable, in which case the +allocator's exception will be thrown).

+ +

This exception may be thrown, e.g., when a probe sequence in + a probing hash table does not encounter any free positions, + even though free positions are available.

+ +

Defined in: exception.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+insert_error
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/insert_resize_sequence_diagram1.png b/libstdc++-v3/doc/html/ext/pb_ds/insert_resize_sequence_diagram1.png new file mode 100644 index 000000000..f64764ec9 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/insert_resize_sequence_diagram1.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/insert_resize_sequence_diagram2.png b/libstdc++-v3/doc/html/ext/pb_ds/insert_resize_sequence_diagram2.png new file mode 100644 index 000000000..e4645973e Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/insert_resize_sequence_diagram2.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/insert_resize_sequence_diagram3.png b/libstdc++-v3/doc/html/ext/pb_ds/insert_resize_sequence_diagram3.png new file mode 100644 index 000000000..5535c5fe6 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/insert_resize_sequence_diagram3.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/interface.html b/libstdc++-v3/doc/html/ext/pb_ds/interface.html new file mode 100644 index 000000000..a48a8bbad --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/interface.html @@ -0,0 +1,446 @@ + + + + + + +Interface + + + + +
+

Interface Specifics

+ +

Following are the library's interface specifics. Short Tutorial is a short tutorial, and + Concepts describes some + concepts.

+
+ +

Namespace

+ +

All code is enclosed in namespace pb_ds. Nested within + this is namespace detail, which contains the parts of this + library that are considered implementation details.

+
+ +

Containers

+ +

Associative Containers

+ +
    +
  1. container_base - + abstract base class for associative containers.
    2. + +
  2. Hash-based: + +
      +
    1. basic_hash_table + - abstract base class for hash-based + containers
      2. + +
    2. cc_hash_table + - concrete collision-chaining hash-based + containers
      3. + +
    3. gp_hash_table + - concrete (general) probing hash-based + containers
      4. +
    +
    3. + +
  3. Tree-based: + +
      +
    1. basic_tree + - abstract base class for tree and trie based + containers
      2. + +
    2. tree + - concrete base class for tree-based + containers
      3. + +
    3. trie + - concrete base class for trie-based + containers
      4. +
    +
    4. + +
  4. List-based: + +
      +
    1. list_update - + singly-linked list with update-policy container
      2. +
    +
    5. +
+ +

Priority + Queues

+ +
    +
  1. priority_queue + - priority queue
    2. +
+
+ +

Container Tags and + Traits

+ +

Container Tags

+ +

Common

+ +
    +
  1. container_tag - + base class for data structure tags
    2. +
+ +

Associative-Containers

+ +
    +
  1. associative_container_tag - + base class for associative-container data structure tags
    2. + +
  2. basic_hash_tag - + base class for hash-based structure tags
    3. + +
  3. cc_hash_tag + - collision-chaining hash structure tag
    4. + +
  4. gp_hash_tag + - (general) probing hash structure tag
    5. + +
  5. basic_tree_tag + - base class for tree-like structure tags
    6. + +
  6. tree_tag - + base class for tree structure tags
    7. + +
  7. rb_tree_tag + - red-black tree structure tag/li>
    8. + +
  8. splay_tree_tag - + splay tree structure tag
    9. + +
  9. ov_tree_tag + - ordered-vector tree structure tag
    10. + +
  10. trie_tag - + trie structure tag
    11. + +
  11. pat_trie_tag - + PATRICIA trie structure tag
    12. + +
  12. list_update_tag - list + (with updates) structure tag
    13. +
+ +

Priority-Queues

+ +
    +
  1. priority_queue_tag - base + class for priority-queue data structure tags
    2. + +
  2. pairing_heap_tag - + pairing-heap structure tag.
    3. + +
  3. binomial_heap_tag + - binomial-heap structure tag
    4. + +
  4. rc_binomial_heap_tag + - redundant-counter binomial-heap (i.e., a heap where + binomial trees form a sequence that is similar to a + de-amortized bit-addition algorithm) structure tag
    5. + +
  5. binary_heap_tag - + binary heap (based on an array or an array of nodes) + structure tag
    6. + +
  6. thin_heap_tag - thin + heap (an alternative [kt99fat_heaps] to + Fibonacci heap) data structure tag.
    7. +
+ +

Invalidation-Guarantee + Tags

+ +
    +
  1. basic_invalidation_guarantee + - weakest invalidation guarantee
    2. + +
  2. point_invalidation_guarantee + - stronger invalidation guarantee
    3. + +
  3. range_invalidation_guarantee + - strongest invalidation guarantee
    4. +
+ +

Container + Traits

+ +
    +
  1. container_traits - + traits for determining underlying data structure + properties
    2. +
+
+ +

Container Policy Classes

+ +

Hash Policies

+ +

Hash and Probe Policies

+ +
    +
  1. Hash Functions: + +
      +
    1. null_hash_fn + - type indicating one-step range-hashing
      2. +
    +
    2. + +
  2. Range-Hashing Functions: + +
      +
    1. Sample + range-hashing function - interface required of a + range-hashing functor
      2. + +
    2. direct_mask_range_hashing + - (bit) mask-based range hashing functor
      3. + +
    3. direct_mod_range_hashing + - modulo-based range hashing functor
      4. +
    +
    3. + +
  3. Probe Functions: + +
      +
    1. Sample probe + function - interface required of a probe functor
      2. + +
    2. null_probe_fn - type + indicating one-step ranged-probe
      3. + +
    3. linear_probe_fn - + linear-probe functor
      4. + +
    4. quadratic_probe_fn- + quadratic-probe functor
      5. +
    +
    4. + +
  4. Ranged-Hash Functions: + +
      +
    1. Sample + ranged-hash function - interface required of a + ranged-hash functor
      2. +
    +
    5. + +
  5. Ranged-Probe Functions: + +
      +
    1. Sample + ranged-probe function - interface required of a + ranged-probe functor
      2. +
    +
    6. +
+ +

Resize Policies

+
    +
  1. Resize Policies: + +
      +
    1. Sample resize + policy - interface required of a resize policy
      2. + +
    2. hash_standard_resize_policy + - standard resize policy
      3. +
    +
    2. + +
  2. Size Policies: + +
      +
    1. Sample size + policy - interface required of a size policy
      2. + +
    2. hash_exponential_size_policy + - exponential size policy (typically used with (bit) mask + range-hashing)
      3. + +
    3. hash_prime_size_policy + - prime size policy (typically used with modulo + range-hashing)
      4. +
    +
    3. + +
  3. Trigger Policies: + +
      +
    1. Sample trigger + policy - interface required of a trigger policy
      2. + +
    2. hash_load_check_resize_trigger + - trigger policy based on load checks
      3. + +
    3. cc_hash_max_collision_check_resize_trigger + - trigger policy based on collision checks
      4. +
    +
    4. +
+ +

Tree Policies

+ +

Tree Node-Update Policies

+ + +
    +
  1. Sample node +updater policy - interface required of a tree +node-updating functor
    2. + +
  2. null_tree_node_update +- null policy indicating no updates are required
    3. + +
  3. tree_order_statistics_node_update +- updater enabling order statistics queries
    4. +
+ +

Trie Policies

+ + +

Trie Element-Access Traits

+ +
    +
  1. Sample + element-access traits - interface required of + element-access traits
    2. + +
  2. string_trie_e_access_traits + - String element-access traits
    3. +
+ +

Trie Node-Update Policies

+ + +
    +
  1. Sample node +updater policy - interface required of a trie node +updater
    2. + +
  2. null_trie_node_update +- null policy indicating no updates are required
    3. + +
  3. trie_prefix_search_node_update +- updater enabling prefix searches
    4. + +
  4. trie_order_statistics_node_update +- updater enabling order statistics queries
    5. +
+ +

List Policies

+ +

List Update Policies

+ + +
    +
  1. Sample list update + policy - interface required of a list update policy
    2. + +
  2. move_to_front_lu_policy + - move-to-front update algorithm
    3. + +
  3. counter_lu_policy - + counter update algorithm
    4. +
+ +

Mapped-Type Policies

+ + +
    +
  1. null_mapped_type - data + policy indicating that a container is a "set"
    2. +
+
+ +

Exceptions

+ + +
    +
  1. container_error + - base class for all policy-based data structure errors
    2. + +
  2. insert_error
    3. + +
  3. join_error
    4. + +
  4. resize_error
    5. +
+ +
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/introduction.html b/libstdc++-v3/doc/html/ext/pb_ds/introduction.html new file mode 100644 index 000000000..b3ccbd76a --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/introduction.html @@ -0,0 +1,120 @@ + + + + + + + Introduction + + + + +
+

Introduction

+ +

This section describes what problems the library attempts to + solve. Motivation describes the + reasons we think it solves these problems better than similar + libraries.

+ +

Associative Containers

+ +
    +
  1. Associative containers depend on their policies to a very + large extent. Implicitly hard-wiring policies can hamper their + performance and limit their functionality. An efficient + hash-based container, for example, requires policies for + testing key equivalence, hashing keys, translating hash + values into positions within the hash table, and determining + when and how to resize the table internally. A tree-based + container can efficiently support order statistics, + i.e., the ability to query what is the order of each + key within the sequence of keys in the container, but only if + the container is supplied with a policy to internally update + meta-data. There are many other such examples.

    2. + +
  2. Ideally, all associative containers would share the same + interface. Unfortunately, underlying data structures and + mapping semantics differentiate between different containers. + For example, suppose one writes a generic function + manipulating an associative container Cntnr: + 
    +template<typename Cntnr>
+  void
+  some_op_sequence(Cntnr& r_cnt)
+  {
+    ...
+  }
+
    + +then what can one assume about Cntnr? The answer +varies according to its underlying data structure. If the +underlying data structure of Cntnr is based on a tree or +trie, then the order of elements is well defined; otherwise, it is +not, in general. If the underlying data structure of Cntnr +is based on a collision-chaining hash table, then modifying +r_Cntnr will not invalidate its iterators' order; if the +underlying data structure is a probing hash table, then this is not +the case. If the underlying data structure is based on a tree or +trie, then r_cnt can efficiently be split; otherwise, it +cannot, in general. If the underlying data structure is a red-black +tree, then splitting r_cnt is exception-free; if it is an +ordered-vector tree, exceptions can be thrown. +

    3. +
+ +

Priority Queues

+ +

Priority queues are useful when one needs to efficiently + access a minimum (or maximum) value as the set of values + changes.

+ +
    +
  1. Most useful data structures for priority queues have a + relatively simple structure, as they are geared toward + relatively simple requirements. Unfortunately, these structures + do not support access to an arbitrary value, which turns out to + be necessary in many algorithms. Say, decreasing an arbitrary + value in a graph algorithm. Therefore, some extra mechanism is + necessary and must be invented for accessing arbitrary + values. There are at least two alternatives: embedding an + associative container in a priority queue, or allowing + cross-referencing through iterators. The first solution adds + significant overhead; the second solution requires a precise + definition of iterator invalidation. Which is the next + point...

    2. + +
  2. Priority queues, like hash-based containers, store values in + an order that is meaningless and undefined externally. For + example, a push operation can internally reorganize the + values. Because of this characteristic, describing a priority + queues' iterator is difficult: on one hand, the values to which + iterators point can remain valid, but on the other, the logical + order of iterators can change unpredictably.

    3. + +
  3. Roughly speaking, any element that is both inserted to a + priority queue (e.g., through push) and removed + from it (e.g., through pop), incurs a + logarithmic overhead (in the amortized sense). Different + underlying data structures place the actual cost differently: + some are optimized for amortized complexity, whereas others + guarantee that specific operations only have a constant + cost. One underlying data structure might be chosen if modifying + a value is frequent (Dijkstra's shortest-path algorithm), + whereas a different one might be chosen + otherwise. Unfortunately, an array-based binary heap - an + underlying data structure that optimizes (in the amortized + sense) push and pop operations, differs from + the others in terms of its invalidation guarantees. Other design + decisions also impact the cost and placement of the overhead, at + the expense of more difference in the the kinds of operations + that the underlying data structure can support. These + differences pose a challenge when creating a uniform interface + for priority queues.

    4. +
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/invalidation_guarantee_cd.png b/libstdc++-v3/doc/html/ext/pb_ds/invalidation_guarantee_cd.png new file mode 100644 index 000000000..1f9d1243c Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/invalidation_guarantee_cd.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/invalidation_guarantee_erase.png b/libstdc++-v3/doc/html/ext/pb_ds/invalidation_guarantee_erase.png new file mode 100644 index 000000000..940a27f71 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/invalidation_guarantee_erase.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/join_error.html b/libstdc++-v3/doc/html/ext/pb_ds/join_error.html new file mode 100644 index 000000000..f3e3eaf97 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/join_error.html @@ -0,0 +1,48 @@ + + + + + + +join_error Interface + + + + +
+

join_error Interface

+ +

A join cannot be performed logical reasons (i.e., the ranges of the + two container objects + being joined + overlaps.

+ +

Defined in: exception.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+
join_error
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/linear_probe_fn.html b/libstdc++-v3/doc/html/ext/pb_ds/linear_probe_fn.html new file mode 100644 index 000000000..6387d3a33 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/linear_probe_fn.html @@ -0,0 +1,140 @@ + + + + + + + linear_probe_fn Interface + + + + +
+

linear_probe_fn Interface

+ +

A probe sequence policy using fixed increments.

+ +

Defined in: hash_policy.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+typename Size_Type 
+
+ 		+

Size type.

+ 		size_t
+ +

Public Types and + Constants

+ +

General Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+Size_Type
+
+ 		+

Size type.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + +
MethodDescription
+ 
+void
+  swap
+  (linear_probe_fn &other)
+
+ 		+

Swaps content.

+
+ +

Protected Methods

+ +

Offset Methods

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline size_type
+  operator()
+  (size_type i) const
+
+ 		+

Returns the i-th + offset from the hash value.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/list_update.html b/libstdc++-v3/doc/html/ext/pb_ds/list_update.html new file mode 100644 index 000000000..434e82f42 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/list_update.html @@ -0,0 +1,316 @@ + + + + + + + list_update Interface + + + + +
+

list_update Interface

+ +

A list-update based associative container.

+ +

Defined in: assoc_container.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+typename Key
+
+ 		+

Key type.

+ 		-
+ 
+typename Mapped
+
+ 		+

Mapped type.

+ 		-
+ 
+class Eq_Fn 
+
+ 		+

Equivalence functor.

+ 		+ 
+std::equal_to<Key>
+
+
+ 
+class Update_Policy 
+
+ 		+

Update policy (determines when an element will be + moved to the front of the list.

+ 		move_to_front_lu_policy
+ 
+class Allocator 
+
+ 		+

Allocator type.

+ 		+ 
+std::allocator<char>
+
+
+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+container_base
+
+ 		+

public

+
+ +

Public Types and + Constants

+ +

Policy definitions.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+eq_fn
+
+ 		+ 
+Eq_Fn
+
+ 		+

Equivalence functor type.

+
+ 
+update_policy
+
+ 		+ 
+Update_Policy
+
+ 		+

List update policy type.

+
+ 
+allocator
+
+ 		+ 
+Allocator
+
+ 		+

Allocator + type.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  list_update
+  ()
+
+ 		+

Default constructor.

+
+ 
+template<
+    class It>
+  list_update
+  (It first_it, 
+    It last_it)
+
+ 		+

Constructor taking iterators to a range of + value_types. The value_types between first_it and last_it will be inserted into the + container object.

+
+ 
+  list_update
+  (const list_update &other)
+
+ 		+

Copy constructor.

+
+ 
+virtual 
+  ~list_update
+  ()
+
+ 		+

Destructor.

+
+ 
+list_update &
+  operator=
+  (const list_update &other)
+
+ 		+

Assignment operator.

+
+ 
+void
+  swap
+  (list_update &other)
+
+ 		+

Swaps content.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/list_update_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/list_update_tag.html new file mode 100644 index 000000000..f04aaeacb --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/list_update_tag.html @@ -0,0 +1,47 @@ + + + + + + + list_update_tag Interface + + + + +
+

list_update_tag Interface

+ +

List-update data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+associative_container_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/lu.png b/libstdc++-v3/doc/html/ext/pb_ds/lu.png new file mode 100644 index 000000000..7c96dcaf6 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/lu.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/lu_based_containers.html b/libstdc++-v3/doc/html/ext/pb_ds/lu_based_containers.html new file mode 100644 index 000000000..c8693437d --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/lu_based_containers.html @@ -0,0 +1,229 @@ + + + + + + + List-Based Containers + + + + +
+

List-Update Design

+ +

Overview

+ +

The list-based container has the following declaration:

+ 
+template<
+    typename Key,
+    typename Mapped,
+    typename Eq_Fn = std::equal_to<Key>,
+    typename Update_Policy = move_to_front_lu_policy<>,
+    typename Allocator = std::allocator<char> >
+class list_update;
+
+ +

The parameters have the following meaning:

+ +
    +
  1. Key is the key type.
    2. + +
  2. Mapped is the mapped-policy, and is explained in + Tutorial::Associative + Containers::Associative Containers Others than Maps.
    3. + +
  3. Eq_Fn is a key equivalence functor.
    4. + +
  4. Update_Policy is a policy updating positions in + the list based on access patterns. It is described in the + following subsection.
    5. + +
  5. Allocator is an allocator + type.
    6. +
+ +

A list-based associative container is a container that + stores elements in a linked-list. It does not order the + elements by any particular order related to the keys. + List-based containers are primarily useful for creating + "multimaps" (see Motivation::Associative + Containers::Avoiding Multiple Keys and Tutorial::Associative + Containers::Associative Containers Others than Maps). In + fact, list-based containers are designed in pb_ds + expressly for this purpose. This is explained further in + Use for "Multimaps".

+ +

List-based containers might also be useful for some rare + cases, where a key is encapsulated to the extent that only + key-equivalence can be tested. Hash-based containers need to + know how to transform a key into a size type, and tree-based + containers need to know if some key is larger than another. + List-based associative containers, conversely, only need to + know if two keys are equivalent.

+ +

Since a list-based associative container does not order + elements by keys, is it possible to order the list in some + useful manner? Remarkably, many on-line competitive [motwani95random] + algorithms exist for reordering lists to reflect access + prediction [andrew04mtf].

+ +

List + Updates

+ +

General Terms

+ +

Figure A simple list shows a + simple list of integer keys. If we search for the integer 6, we + are paying an overhead: the link with key 6 is only the fifth + link; if it were the first link, it could be accessed + faster.

+ +
no image
+ +
A simple list.
+ +

List-update algorithms reorder lists as elements are + accessed. They try to determine, by the access history, which + keys to move to the front of the list. Some of these algorithms + require adding some metadata alongside each entry.

+ +

For example, Figure The counter algorithm + -A shows the counter algorithm. Each node contains both a key + and a count metadata (shown in bold). When an element is + accessed (e.g. 6) its count is incremented, as shown in + Figure The counter algorithm -B. If the count + reaches some predetermined value, say 10, as shown in Figure + The counter algorithm -C, the count is set to + 0 and the node is moved to the front of the list, as in Figure + The counter algorithm -D.

+ +
+
+ +
The counter algorithm.
+ +

Implementation

+ +

pb_ds allows instantiating lists with policies + implementing any algorithm moving nodes to the front of the + list (policies implementing algorithms interchanging nodes are + unsupported).

+ +

Associative containers based on lists are parametrized by a + Update_Policy parameter. This parameter defines the + type of metadata each node contains, how to create the + metadata, and how to decide, using this metadata, whether to + move a node to the front of the list. A list-based associative + container object derives (publicly) from its update policy. + Figure A list and its update + policy shows the scheme, as well as some predefined + policies (which are explained below).

+ +
+
+ +
A list and its update policy.
+ +

An instantiation of Update_Policy must define + internally update_metadata as the metadata it + requires. Internally, each node of the list contains, besides + the usual key and data, an instance of typename + Update_Policy::update_metadata.

+ +

An instantiation of Update_Policy must define + internally two operators:

+ 
+update_metadata
+operator()();
+
+bool
+operator()(update_metadata &);
+
+ +

The first is called by the container object, when creating a + new node, to create the node's metadata. The second is called + by the container object, when a node is accessed (e.g., + when a find operation's key is equivalent to the key of the + node), to determine whether to move the node to the front of + the list.

+ +

The library contains two predefined implementations of + list-update policies [andrew04mtf]. The first is + counter_lu_policy, which + implements the counter algorithm described above. The second is + move_to_front_lu_policy, + which unconditionally move an accessed element to the front of + the list. The latter type is very useful in pb_ds, + since there is no need to associate metadata with each element + (this is explained further in Use for + "Multimaps").

+ +

Use for "Multimaps"

+ +

In pb_ds, there are no equivalents for the STL's + multimaps and multisets; instead one uses an associative + container mapping primary keys to secondary keys (see Motivation::Associative + Containers::Alternative to Multiple Equivalent Keys and + Tutorial::Associative + Containers::Associative Containers Others than Maps).

+ +

List-based containers are especially useful as associative + containers for secondary keys. In fact, they are implemented + here expressly for this purpose.

+ +

To begin with, these containers use very little per-entry + structure memory overhead, since they can be implemented as + singly-linked lists. (Arrays use even lower per-entry memory + overhead, but they are less flexible in moving around entries, + and have weaker invalidation guarantees).

+ +

More importantly, though, list-based containers use very + little per-container memory overhead. The memory overhead of an + empty list-based container is practically that of a pointer. + This is important for when they are used as secondary + associative-containers in situations where the average ratio of + secondary keys to primary keys is low (or even 1).

+ +

In order to reduce the per-container memory overhead as much + as possible, they are implemented as closely as possible to + singly-linked lists.

+ +
    +
  1. List-based containers do not store internally the number + of values that they hold. This means that their size + method has linear complexity (just like std::list). + Note that finding the number of equivalent-key values in an + STL multimap also has linear complexity (because it must be + done, e.g., via std::distance of the + multimap's equal_range method), but usually with + higher constants.
    2. + +
  2. Most associative-container objects each hold a policy + object (e.g., a hash-based container object holds a + hash functor). List-based containers, conversely, only have + class-wide policy objects.
    3. +
+ +

See also Associative-Container + Performance Tests::Observations::Mapping-Semantics + Considerations.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/misc.html b/libstdc++-v3/doc/html/ext/pb_ds/misc.html new file mode 100644 index 000000000..01029e134 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/misc.html @@ -0,0 +1,26 @@ + + + + + + + Misc. + + + + +
+

Misc.

+ +

Acks + contains acknowledgments; Contact + contains contact information;Disclaimer and Copyright is a standard + disclaimer, and References + contains references.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/motivation.html b/libstdc++-v3/doc/html/ext/pb_ds/motivation.html new file mode 100644 index 000000000..627317217 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/motivation.html @@ -0,0 +1,993 @@ + + + + + + + Motivation + + + + +
+

Motivation

+ +

Many fine associative-container libraries were already + written, most notably, the STL's associative containers. Why + then write another library? This section shows some possible + advantages of this library, when considering the challenges in + Introduction. Many of these + points stem from the fact that the STL introduced + associative-containers in a two-step process (first + standardizing tree-based containers, only then adding + hash-based containers, which are fundamentally different), did + not standardize priority queues as containers, and (in our + opinion) overloads the iterator concept.

+ +

Associative Containers

+ +

More + Configuration Choices

+ +

Associative containers require a relatively large number of + policies to function efficiently in various settings. In some + cases this is needed for making their common operations more + efficient, and in other cases this allows them to support a + larger set of operations

+ +
    +
  1. Hash-based containers, for example, support look-up and + insertion methods (e.g., find and + insert). In order to locate elements quickly, they + are supplied a hash functor, which instruct how to transform + a key object into some size type; e.g., a hash functor + might transform "hello" into 1123002298. A + hash table, though, requires transforming each key object + into some size-type type in some specific domain; + e.g., a hash table with a 128-long table might + transform "hello" into position 63. The policy by + which the hash value is transformed into a position within + the table can dramatically affect performance (see Design::Associative + Containers::Hash-Based Containers::Hash Policies). + Hash-based containers also do not resize naturally (as + opposed to tree-based containers, for example). The + appropriate resize policy is unfortunately intertwined with + the policy that transforms hash value into a position within + the table (see Design::Associative + Containers::Hash-Based Containers::Resize Policies). + +

    Associative-Container + Performance Tests::Hash-Based Containers quantifies + some of these points.

    +
    2. + +
  2. Tree-based containers, for example, also support look-up + and insertion methods, and are primarily useful when + maintaining order between elements is important. In some + cases, though, one can utilize their balancing algorithms for + completely different purposes. + +

    Figure Metadata for + order-statistics and interval intersections-A, for + example, shows a tree whose each node contains two entries: + a floating-point key, and some size-type metadata + (in bold beneath it) that is the number of nodes in the + sub-tree. (E.g., the root has key 0.99, and has 5 + nodes (including itself) in its sub-tree.) A container based + on this data structure can obviously answer efficiently + whether 0.3 is in the container object, but it can also + answer what is the order of 0.3 among all those in the + container object [clrs2001] (see Associative Container + Examples::Tree-Like-Based Containers (Trees and + Tries)).

    + +

    As another example, Figure Metadata for order-statistics and + interval intersections-B shows a tree whose each node + contains two entries: a half-open geometric line interval, + and a number metadata (in bold beneath it) that is + the largest endpoint of all intervals in its sub-tree. + (E.g., the root describes the interval [20, + 36), and the largest endpoint in its sub-tree is 99.) A + container based on this data structure can obviously answer + efficiently whether [3, 41) is in the container + object, but it can also answer efficiently whether the + container object has intervals that intersect [3, + 41) (see Associative Container + Examples::Tree-Like-Based Containers (Trees and + Tries)). These types of queries are very useful in + geometric algorithms and lease-management algorithms.

    + +

    It is important to note, however, that as the trees are + modified, their internal structure changes. To maintain + these invariants, one must supply some policy that is aware + of these changes (see Design::Associative + Containers::Tree-Based Containers::Node Invariants); + without this, it would be better to use a linked list (in + itself very efficient for these purposes).

    + +

    Associative-Container + Performance Tests::Tree-Like-Based Containers + quantifies some of these points.

    +
    3. +
+ +
+
+ +
Metadata for order-statistics and interval + intersections.
+ +

More + Data Structures and Traits

+ +

The STL contains associative containers based on red-black + trees and collision-chaining hash tables. These are obviously + very useful, but they are not ideal for all types of + settings.

+ +

Figure Different underlying + data structures shows different underlying data structures + (the ones currently supported in pb_ds). A shows a + collision-chaining hash-table, B shows a probing hash-table, C + shows a red-black tree, D shows a splay tree, E shows a tree + based on an ordered vector(implicit in the order of the + elements), F shows a PATRICIA trie, and G shows a list-based + container with update policies.

+ +

Each of these data structures has some performance benefits, + in terms of speed, size or both (see Associative-Container + Performance Tests and Associative-Container + Performance Tests::Observations::Underlying Data-Structure + Families). For now, though, note that e.g., + vector-based trees and probing hash tables manipulate memory + more efficiently than red-black trees and collision-chaining + hash tables, and that list-based associative containers are + very useful for constructing "multimaps" (see Alternative to Multiple Equivalent + Keys, Associative Container + Performance Tests::Multimaps, and Associative Container + Performance Tests::Observations::Mapping-Semantics + Considerations).

+ +
no image
+ +
Different underlying data structures.
+ +

Now consider a function manipulating a generic associative + container, e.g.,

+ 
+template<
+    class Cntnr>
+int 
+    some_op_sequence
+    (Cntnr &r_cnt)
+{
+    ...
+}
+
+ +

Ideally, the underlying data structure of Cntnr + would not affect what can be done with r_cnt. + Unfortunately, this is not the case.

+ +

For example, if Cntnr is std::map, then + the function can use std::for_each(r_cnt.find(foo), + r_cnt.find(bar), foobar) in order to apply foobar + to all elements between foo and bar. If + Cntnr is a hash-based container, then this call's + results are undefined.

+ +

Also, if Cntnr is tree-based, the type and object + of the comparison functor can be accessed. If Cntnr is + hash based, these queries are nonsensical.

+ +

There are various other differences based on the container's + underlying data structure. For one, they can be constructed by, + and queried for, different policies. Furthermore:

+ +
    +
  1. Containers based on C, D, E and F store elements in a + meaningful order; the others store elements in a meaningless + (and probably time-varying) order. By implication, only + containers based on C, D, E and F can support erase + operations taking an iterator and returning an iterator to + the following element without performance loss (see Slightly Different Methods::Methods + Related to Erase).
    2. + +
  2. Containers based on C, D, E, and F can be split and + joined efficiently, while the others cannot. Containers based + on C and D, furthermore, can guarantee that this is + exception-free; containers based on E cannot guarantee + this.
    3. + +
  3. Containers based on all but E can guarantee that erasing + an element is exception free; containers based on E cannot + guarantee this. Containers based on all but B and E can + guarantee that modifying an object of their type does not + invalidate iterators or references to their elements, while + containers based on B and E cannot. Containers based on C, D, + and E can furthermore make a stronger guarantee, namely that + modifying an object of their type does not affect the order + of iterators.
    4. +
+ +

A unified tag and traits system (as used for the STL's + iterators, for example) can ease generic manipulation of + associative containers based on different underlying + data structures (see Tutorial::Associative + Containers::Determining Containers' Attributes and Design::Associative + Containers::Data-Structure Genericity::Data-Structure Tags and + Traits).

+ +

Differentiating + between Iterator Types

+ +

Iterators are centric to the STL's design, because of the + container/algorithm/iterator decomposition that allows an + algorithm to operate on a range through iterators of some + sequence (e.g., one originating from a container). + Iterators, then, are useful because they allow going over a + sequence. The STL also uses iterators for accessing a + specific element - e.g., when an associative + container returns one through find. The STL, however, + consistently uses the same types of iterators for both + purposes: going over a range, and accessing a specific found + element. Before the introduction of hash-based containers to + the STL, this made sense (with the exception of priority + queues, which are discussed in Priority + Queues).

+ +

Using the STL's associative containers together with + non-order-preserving associative containers (and also because + of priority-queues container), there is a possible need for + different types of iterators for self-organizing containers - + the iterator concept seems overloaded to mean two different + things (in some cases). The following subsections explain this; + Tutorial::Associative + Containers::Point-Type and Range-Type Methods explains an + alternative design which does not complicate the use of + order-preserving containers, but is better for unordered + containers; Design::Associative + Containers::Data-Structure Genericity::Point-Type and + Range-Type Methods explains the design further.

+ +

Using Point-Type Iterators for + Range-Type Operations

+ +

Suppose cntnr is some associative container, and + say c is an object of type cntnr. Then what + will be the outcome of

+ 
+std::for_each(c.find(1), c.find(5), foo);
+
+ +

If cntnr is a tree-based container object, then an + in-order walk will apply foo to the relevant elements, + e.g., as in Figure Range + iteration in different data structures -A. If c is + a hash-based container, then the order of elements between any + two elements is undefined (and probably time-varying); there is + no guarantee that the elements traversed will coincide with the + logical elements between 1 and 5, e.g., as in + Figure Range iteration in different + data structures-B.

+ +
no image
+ +
Range iteration in different + data structures.
+ +

In our opinion, this problem is not caused just because + red-black trees are order preserving while collision-chaining + hash tables are (generally) not - it is more fundamental. Most + of the STL's containers order sequences in a well-defined + manner that is determined by their interface: calling + insert on a tree-based container modifies its sequence + in a predictable way, as does calling push_back on a + list or a vector. Conversely, collision-chaining hash tables, + probing hash tables, priority queues, and list-based containers + (which are very useful for "multimaps") are self-organizing + data structures; the effect of each operation modifies their + sequences in a manner that is (practically) determined by their + implementation.

+ +

Consequently, applying an algorithm to a sequence obtained + from most containers may or may not make sense, but + applying it to a sub-sequence of a self-organizing container + does not.

+ +

The Cost of Enabling Range + Capabilities to Point-Type Iterators

+ +

Suppose c is some collision-chaining hash-based + container object, and one calls c.find(3). Then what + composes the returned iterator?

+ +

Figure Point-type + iterators in hash tables-A shows the simplest (and most + efficient) implementation of a collision-chaining hash table. + The little box marked point_iterator shows an object + that contains a pointer to the element's node. Note that this + "iterator" has no way to move to the next element (i.e., + it cannot support operator++). Conversely, the + little box marked iterator stores both a pointer to + the element, as well as some other information (e.g., + the bucket number of the element). the second iterator, then, + is "heavier" than the first one- it requires more time and + space. If we were to use a different container to + cross-reference into this hash-table using these iterators - it + would take much more space. As noted in Using Point-Type Iterators for + Range-Type Operations, nothing much can be done by + incrementing these iterators, so why is this extra information + needed?

+ +

Alternatively, one might create a collision-chaining + hash-table where the lists might be linked, forming a + monolithic total-element list, as in Figure Point-type iterators in hash + tables-B (this seems similar to the Dinkumware design + [dinkumware_stl]). + Here the iterators are as light as can be, but the hash-table's + operations are more complicated.

+ +
no image
+ +
Point-type iterators in hash tables.
+ +

It should be noted that containers based on + collision-chaining hash-tables are not the only ones with this + type of behavior; many other self-organizing data structures + display it as well.

+ +

Invalidation + Guarantees

+ +

Consider the following snippet:

+ 
+it = c.find(3);
+
+c.erase(5);
+
+ +

Following the call to erase, what is the validity + of it: can it be de-referenced? can it be + incremented?

+ +

The answer depends on the underlying data structure of the + container. Figure Effect of erase in different + underlying data structures shows three cases: A1 and A2 + show a red-black tree; B1 and B2 show a probing hash-table; C1 + and C2 show a collision-chaining hash table.

+ +
no image
+ +
Effect of erase in different underlying + data structures.
+ +
    +
  1. Erasing 5 from A1 yields A2. Clearly, an iterator to 3 + can be de-referenced and incremented. The sequence of + iterators changed, but in a way that is well-defined by the + interface.
    2. + +
  2. Erasing 5 from B1 yields B2. Clearly, an iterator to 3 is + not valid at all - it cannot be de-referenced or incremented; + the order of iterators changed in a way that is (practically) + determined by the implementation and not by the + interface.
    3. + +
  3. Erasing 5 from C1 yields C2. Here the situation is more + complicated. On the one hand, there is no problem in + de-referencing it. On the other hand, the order of + iterators changed in a way that is (practically) determined + by the implementation and not by the + interface.
    4. +
+ +

So in classic STL, it is not always possible to express + whether it is valid or not. This is true also for + insert, e.g.. Again, the iterator concept seems + overloaded.

+ +

Slightly + Different Methods

+ +

[meyers02both] + points out that a class's methods should comprise only + operations which depend on the class's internal structure; + other operations are best designed as external functions. + Possibly, therefore, the STL's associative containers lack some + useful methods, and provide some other methods which would be + better left out (e.g., [sgi_stl] ).

+ +

Methods + Related to Erase

+ +
    +
  1. Order-preserving STL associative containers provide the + method + 
    +iterator 
+    erase
+    (iterator it)
+
    which takes an iterator, erases the corresponding element, +and returns an iterator to the following element. Also hash-based +STL associative containers provide this method. This seemingly +increases genericity between associative containers, since, + e.g., it is possible to use + 
    +typename C::iterator it = c.begin();
+typename C::iterator e_it = c.end();
+
+while(it != e_it)
+    it = pred(*it)? c.erase(it) : ++it;
+
    in order to erase from a container object + c all element which match a predicate pred. + However, in a different sense this actually + decreases genericity: an integral implication of + this method is that tree-based associative containers' + memory use is linear in the total number of elements they + store, while hash-based containers' memory use is unbounded + in the total number of elements they store. Assume a + hash-based container is allowed to decrease its size when + an element is erased. Then the elements might be rehashed, + which means that there is no "next" element - it is simply + undefined. Consequently, it is possible to infer from the + fact that STL hash-based containers provide this method + that they cannot downsize when elements are erased + (Performance + Tests::Hash-Based Container Tests quantifies this.) As + a consequence, different code is needed to manipulate + different containers, assuming that memory should be + conserved. pb_ds's non-order preserving + associative containers omit this method. +
    2. + +
  2. All of pb_ds's associative containers include a + conditional-erase method + 
    +template<
+    class Pred>
+size_type
+    erase_if
+    (Pred pred)
+
    which erases all elements matching a predicate. This is +probably the only way to ensure linear-time multiple-item erase +which can actually downsize a container. +
    3. + +
  3. STL associative containers provide methods for + multiple-item erase of the form + 
    +size_type
+    erase
+    (It b, 
+        It e)
+
    erasing a range of elements given by a pair of iterators. For +tree-based or trie-based containers, this can implemented more +efficiently as a (small) sequence of split and join operations. For +other, unordered, containers, this method isn't much better than an +external loop. Moreover, if c is a hash-based container, +then, e.g., c.erase(c.find(2), c.find(5)) is almost +certain to do something different than erasing all elements whose +keys are between 2 and 5, and is likely to produce other undefined +behavior. +
    4. +
+ +

Methods Related to Split and + Join

+ +

It is well-known that tree-based and trie-based container + objects can be efficiently split or joined [clrs2001]. Externally splitting + or joining trees is super-linear, and, furthermore, can throw + exceptions. Split and join methods, consequently, seem good + choices for tree-based container methods, especially, since as + noted just before, they are efficient replacements for erasing + sub-sequences. Performance + Tests::Tree-Like-Based Container Tests quantifies this.

+ +

Methods Related to Insert

+ +

STL associative containers provide methods of the form

+ 
+template<
+    class It>
+size_type
+    insert
+    (It b,
+        It e);
+
for inserting a range of elements given by a pair of +iterators. At best, this can be implemented as an external loop, +or, even more efficiently, as a join operation (for the case of +tree-based or trie-based containers). Moreover, these methods seem +similar to constructors taking a range given by a pair of +iterators; the constructors, however, are transactional, whereas +the insert methods are not; this is possibly confusing. + +

Functions Related to + Comparison

+ +

Associative containers are parametrized by policies + allowing to test key equivalence; e.g. a hash-based + container can do this through its equivalence functor, and a + tree-based container can do this through its comparison + functor. In addition, some STL associative containers have + global function operators, e.g., + operator== and operator<=, + that allow comparing entire associative containers.

+ +

In our opinion, these functions are better left out. To + begin with, they do not significantly improve over an external + loop. More importantly, however, they are possibly misleading - + operator==, for example, usually checks for + equivalence, or interchangeability, but the associative + container cannot check for values' equivalence, only keys' + equivalence; also, are two containers considered equivalent if + they store the same values in different order? this is an + arbitrary decision.

+ +

Alternative to Multiple Equivalent + Keys

+ +

Maps (or sets) allow mapping (or storing) unique-key values. + The STL, however, also supplies associative containers which + map (or store) multiple values with equivalent keys: + std::multimap, std::multiset, + std::tr1::unordered_multimap, and + unordered_multiset. We first discuss how these might + be used, then why we think it is best to avoid them.

+ +

Suppose one builds a simple bank-account application that + records for each client (identified by an std::string) + and account-id (marked by an unsigned long) - + the balance in the account (described by a + float). Suppose further that ordering this + information is not useful, so a hash-based container is + preferable to a tree based container. Then one can use

+ 
+std::tr1::unordered_map<std::pair<std::string, unsigned long>, float, ...>
+
which hashes every combination of client and +account-id. This might work well, except for the fact that it +is now impossible to efficiently list all of the accounts of a +specific client (this would practically require iterating over all +entries). Instead, one can use + 
+std::tr1::unordered_multimap<std::pair<std::string, unsigned long>, float, ...>
+
which hashes every client, and decides equivalence +based on client only. This will ensure that all accounts +belonging to a specific user are stored consecutively. + +

Also, suppose one wants an integers' priority queue + (i.e., a container that supports push, + pop, and top operations, the last of which + returns the largest int) that also supports + operations such as find and lower_bound. A + reasonable solution is to build an adapter over + std::set<int>. In this adapter, + e.g., push will just call the tree-based + associative container's insert method; pop + will call its end method, and use it to return the + preceding element (which must be the largest). Then this might + work well, except that the container object cannot hold + multiple instances of the same integer (push(4), + e.g., will be a no-op if 4 is already in the + container object). If multiple keys are necessary, then one + might build the adapter over an + std::multiset<int>.

+ +

STL non-unique-mapping containers, then, are + useful when (1) a key can be decomposed in to a primary key and + a secondary key, (2) a key is needed multiple times, or (3) any + combination of (1) and (2).

+ +

Figure Non-unique mapping + containers in the STL's design shows how the STL's design + works internally; in this figure nodes shaded equally represent + equivalent-key values. Equivalent keys are stored consecutively + using the properties of the underlying data structure: binary + search trees (Figure Non-unique + mapping containers in the STL's design-A) store + equivalent-key values consecutively (in the sense of an + in-order walk) naturally; collision-chaining hash tables + (Figure Non-unique mapping + containers in the STL's design-B) store equivalent-key + values in the same bucket, the bucket can be arranged so that + equivalent-key values are consecutive.

+ +
+
+ +
Non-unique mapping containers in the STL's + design.
+ +

Put differently, STL non-unique mapping + associative-containers are associative containers that map + primary keys to linked lists that are embedded into the + container. Figure Effect of + embedded lists in STL multimaps shows again the two + containers from Figure Non-unique + mapping containers in the STL's design, this time with the + embedded linked lists of the grayed nodes marked + explicitly.

+ +
+
+ +
Effect of embedded lists in STL multimaps.
+ +

These embedded linked lists have several disadvantages.

+ +
    +
  1. The underlying data structure embeds the linked lists + according to its own consideration, which means that the + search path for a value might include several different + equivalent-key values. For example, the search path for the + the black node in either of Figures Non-unique mapping containers in the + STL's design A or B, includes more than a single gray + node.
    2. + +
  2. The links of the linked lists are the underlying + data structures' nodes, which typically are quite structured. + E.g., in the case of tree-based containers (Figure + Effect of embedded lists in STL + multimaps-B), each "link" is actually a node with three + pointers (one to a parent and two to children), and a + relatively-complicated iteration algorithm. The linked lists, + therefore, can take up quite a lot of memory, and iterating + over all values equal to a given key (e.g., through + the return value of the STL's equal_range) can be + expensive.
    3. + +
  3. The primary key is stored multiply; this uses more + memory.
    4. + +
  4. Finally, the interface of this design excludes several + useful underlying data structures. E.g., of all the + unordered self-organizing data structures, practically only + collision-chaining hash tables can (efficiently) guarantee + that equivalent-key values are stored consecutively.
    5. +
+ +

The above reasons hold even when the ratio of secondary keys + to primary keys (or average number of identical keys) is small, + but when it is large, there are more severe problems:

+ +
    +
  1. The underlying data structures order the links inside + each embedded linked-lists according to their internal + considerations, which effectively means that each of the + links is unordered. Irrespective of the underlying + data structure, searching for a specific value can degrade to + linear complexity.
    2. + +
  2. Similarly to the above point, it is impossible to apply + to the secondary keys considerations that apply to primary + keys. For example, it is not possible to maintain secondary + keys by sorted order.
    3. + +
  3. While the interface "understands" that all equivalent-key + values constitute a distinct list (e.g., through + equal_range), the underlying data structure + typically does not. This means, e.g., that operations + such as erasing from a tree-based container all values whose + keys are equivalent to a a given key can be super-linear in + the size of the tree; this is also true also for several + other operations that target a specific list.
    4. +
+ +

In pb_ds, therefore, all associative containers map + (or store) unique-key values. One can (1) map primary keys to + secondary associative-containers (i.e., containers of + secondary keys) or non-associative containers (2) map identical + keys to a size-type representing the number of times they + occur, or (3) any combination of (1) and (2). Instead of + allowing multiple equivalent-key values, pb_ds + supplies associative containers based on underlying + data structures that are suitable as secondary + associative-containers (see Associative-Container + Performance Tests::Observations::Mapping-Semantics + Considerations).

+ +

Figures Non-unique mapping + containers in pb_ds A and B show the equivalent + structures in pb_ds's design, to those in Figures + Non-unique mapping containers in + the STL's design A and B, respectively. Each shaded box + represents some size-type or secondary + associative-container.

+ +
+
+ +
Non-unique mapping containers in the + pb_ds.
+ +

In the first example above, then, one would use an + associative container mapping each user to an associative + container which maps each application id to a start time (see + basic_multimap.cc); + in the second example, one would use an associative container + mapping each int to some size-type indicating + the number of times it logically occurs (see basic_multiset.cc).

+ +

Associative-Container + Performance Tests::Multimaps quantifies some of these + points, and Associative-Container + Performance Tests::Observations::Mapping-Semantics + Considerations shows some simple calculations.

+ +

Associative-Container + Examples::Multimaps shows some simple examples of using + "multimaps".

+ +

Design::Associative + Containers::List-Based Containers discusses types of + containers especially suited as secondary + associative-containers.

+ +

Priority Queues

+ +

Slightly Different + Methods

+ +

Priority queues are containers that allow efficiently + inserting values and accessing the maximal value (in the sense + of the container's comparison functor); i.e., their + interface supports push and pop. The STL's + priority queues indeed support these methods, but they support + little else. For algorithmic and software-engineering purposes, + other methods are needed:

+ +
    +
  1. Many graph algorithms [clrs2001] require increasing a + value in a priority queue (again, in the sense of the + container's comparison functor), or joining two + priority-queue objects.
    2. + +
  2. It is sometimes necessary to erase an arbitrary value in + a priority queue. For example, consider the select + function for monitoring file descriptors: + 
    +int 
+    select
+    (int nfds,             
+        fd_set *readfds,                
+        fd_set *writefds,
+        fd_set *errorfds, 
+        struct timeval *timeout);
+
    then, as the select manual page [select_man] states: + +

    The nfds argument specifies the range of file + descriptors to be tested. The select() function tests file + descriptors in the range of 0 to nfds-1.

    + +

    It stands to reason, therefore, that we might wish to + maintain a minimal value for nfds, and priority + queues immediately come to mind. Note, though, that when a + socket is closed, the minimal file description might + change; in the absence of an efficient means to erase an + arbitrary value from a priority queue, we might as well + avoid its use altogether.

    + +

    Priority-Queue + Examples::Cross-Referencing shows examples for these + types of operations.

    +
    3. + +
  3. STL containers typically support iterators. It is + somewhat unusual for std::priority_queue to omit + them (see, e.g., [meyers01stl]). One might + ask why do priority queues need to support iterators, since + they are self-organizing containers with a different purpose + than abstracting sequences. There are several reasons: + +
      +
    1. Iterators (even in self-organizing containers) are + useful for many purposes, e.g., cross-referencing + containers, serialization, and debugging code that uses + these containers.
      2. + +
    2. The STL's hash-based containers support iterators, + even though they too are self-organizing containers with + a different purpose than abstracting sequences.
      3. + +
    3. In STL-like containers, it is natural to specify the + interface of operations for modifying a value or erasing + a value (discussed previously) in terms of a iterators. + This is discussed further in Design::Priority + Queues::Iterators. It should be noted that the STL's + containers also use iterators for accessing and + manipulating a specific value. E.g., in hash-based + containers, one checks the existence of a key by + comparing the iterator returned by find to the + iterator returned by end, and not by comparing a + pointer returned by find to NULL.
      4. +
    +
    4. +
+ +

Performance + Tests::Priority Queues quantifies some of these points.

+ +

More Data + Structures and Traits

+ +

There are three main implementations of priority queues: the + first employs a binary heap, typically one which uses a + sequence; the second uses a tree (or forest of trees), which is + typically less structured than an associative container's tree; + the third simply uses an associative container. These are + shown, respectively, in Figures Underlying Priority-Queue + Data-Structures A1 and A2, B, and C.

+ +
no image
+ +
Underlying Priority-Queue Data-Structures.
+ +

No single implementation can completely replace any of the + others. Some have better push and pop + amortized performance, some have better bounded (worst case) + response time than others, some optimize a single method at the + expense of others, etc.. In general the "best" + implementation is dictated by the problem (see Performance + Tests::Priority Queues::Observations).

+ +

As with associative containers (see Associative Containers::Traits for + Underlying Data-Structures), the more implementations + co-exist, the more necessary a traits mechanism is for handling + generic containers safely and efficiently. This is especially + important for priority queues, since the invalidation + guarantees of one of the most useful data structures - binary + heaps - is markedly different than those of most of the + others.

+ +

Design::Priority + Queues::Traits discusses this further.

+ +

Binary Heap + Implementation

+ +

Binary heaps are one of the most useful underlying + data structures for priority queues. They are very efficient in + terms of memory (since they don't require per-value structure + metadata), and have the best amortized push and + pop performance for primitive types (e.g., + ints).

+ +

The STL's priority_queue implements this data + structure as an adapter over a sequence, typically + std::vector or std::deque, which correspond + to Figures Underlying + Priority-Queue Data-Structures A1 and A2, respectively.

+ +

This is indeed an elegant example of the adapter concept and + the algorithm/container/iterator decomposition (see [nelson96stlpql]). There are + possibly reasons, however, why a binary-heap priority queue + would be better implemented as a container instead of a + sequence adapter:

+ +
    +
  1. std::priority_queue cannot erase values from its + adapted sequence (irrespective of the sequence type). This + means that the memory use of an std::priority_queue + object is always proportional to the maximal number of values + it ever contained, and not to the number of values that it + currently contains (see Priority Queue + Text pop Memory Use Test); this implementation + of binary heaps acts very differently than other underlying + data structures (e.g., pairing heaps).
    2. + +
  2. Some combinations of adapted sequences and value types + are very inefficient or just don't make sense. If one uses + std::priority_queue<std::vector<std::string> + > >, for example, then not only will each + operation perform a logarithmic number of + std::string assignments, but, furthermore, any + operation (including pop) can render the container + useless due to exceptions. Conversely, if one uses + std::priority_queue<std::deque<int> > + >, then each operation uses incurs a logarithmic + number of indirect accesses (through pointers) unnecessarily. + It might be better to let the container make a conservative + deduction whether to use the structure in Figures Underlying Priority-Queue + Data-Structures A1 or A2.
    3. + +
  3. There does not seem to be a systematic way to determine + what exactly can be done with the priority queue. + +
      +
    1. If p is a priority queue adapting an + std::vector, then it is possible to iterate over + all values by using &p.top() and + &p.top() + p.size(), but this will not work + if p is adapting an std::deque; in any + case, one cannot use p.begin() and + p.end(). If a different sequence is adapted, it + is even more difficult to determine what can be + done.
      2. + +
    2. If p is a priority queue adapting an + std::deque, then the reference return by + p.top() will remain valid until it is popped, + but if p adapts an std::vector, the + next push will invalidate it. If a different + sequence is adapted, it is even more difficult to + determine what can be done.
      3. +
    +
    4. + +
  4. Sequence-based binary heaps can still implement + linear-time erase and modify operations. + This means that if one needs, e.g., to erase a small + (say logarithmic) number of values, then one might still + choose this underlying data structure. Using + std::priority_queue, however, this will generally + change the order of growth of the entire sequence of + operations.
    5. +
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/move_to_front_lu_policy.html b/libstdc++-v3/doc/html/ext/pb_ds/move_to_front_lu_policy.html new file mode 100644 index 000000000..4ed4d40bd --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/move_to_front_lu_policy.html @@ -0,0 +1,194 @@ + + + + + + + move_to_front_lu_policy Interface + + + + +
+

move_to_front_lu_policy Interface

+ +

A list-update policy that unconditionally moves elements to + the front of the list.

+ +

Defined in: list_update_policy.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+class Allocator 
+
+ 		+

Allocator type.

+ +

This is used only for definitions, e.g., the size + type.

+ 		+ 
+std::allocator<char>
+
+
+ +

Public Types and + Constants

+ +

Policy Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+allocator
+
+ 		+ 
+Allocator
+
+ 		+

Allocator + type.

+
+ +

Metadata-Type + Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+metadata_type
+
+ 		+ 
+null_lu_metadata
+
+ 		+

Metadata on which this functor operates.

+ +

In this case, none.

+
+ 
+metadata_reference
+
+ 		+ 
+typename Allocator::template rebind<  
+    metadata_type>::other::reference
+
+ 		+

Reference to metadata on which this functor + operates.

+
+ +

Public Methods

+ +

Metadata Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+metadata_type
+  operator()
+  () const
+
+ 		+

Creates a metadata object.

+
+ 
+inline bool 
+  operator()
+  (metadata_reference r_metadata) const
+
+ 		+

Decides whether a metadata object should be moved to + the front of the list.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large.html b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large.html new file mode 100644 index 000000000..74d33a326 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large.html @@ -0,0 +1,215 @@ + + + + + +"Multimap" Text Find Timing Test with Large Average + Secondary-Key to Primary-Key Ratio + + + +
+

"Multimap" Text Find Timing Test with Large Average + Secondary-Key to Primary-Key Ratio

+

Description

+

This test inserts a number of pairs into a container. The + first item of each pair is a string from an arbitrary text + [wickland96thirty], and + the second is a uniform i.i.d.integer. The container is a + "multimap" - it considers the first member of each pair as a + primary key, and the second member of each pair as a secondary + key (see Motivation::Associative + Containers::Alternative to Multiple Equivalent Keys). There + are 100 distinct primary keys, and the ratio of secondary keys + to primary keys ranges to about 20.

+

The test measures the average find-time as a function of the + number of values inserted. For pb_ds's containers, it + finds the secondary key from a container obtained from finding + a primary key. For the native multimaps, it searches a range + obtained using std::equal_range on a primary key.

+

(The test was executed with multimap_text_find_timing_test + thirty_years_among_the_dead_preproc.txt 100 3 4 4)

+

Purpose

+

The test checks the find-time scalability of different + "multimap" designs (see Motivation::Associative + Containers::Mapping Semantics).

+

Results

+

Figures NTG, NTM, and + NTL show the results for "multimaps" which + use a tree-based container for primary keys, in g++, msvc++, and + local, + respectively; Figures NHG, NHM, and NHL show the results for + "multimaps" which use a hash-based container for primary keys, + in g++, + msvc++, + and local, + respectively.

+
+
+
+
+
no image
NTG: Native and primary tree-based multimap types find timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_mmap- +std::multimap
    2. +
  2. +rb_tree_mmap_lu_mtf_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    3. +
  3. +rb_tree_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NTM: Native and primary tree-based multimap types find timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_mmap- +std::multimap
    2. +
  2. +rb_tree_mmap_lu_mtf_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    3. +
  3. +rb_tree_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NTL: Native and primary tree-based multimap types find timing test - local
+
+
+
+
+
+
+
+
+
no image
NHG: Native and primary hash-based multimap types find timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_mmap- +__gnucxx::hash_multimap
    2. +
  2. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_lu_mtf_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    3. +
  3. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NHM: Native and primary hash-based multimap types find timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_mmap- +stdext::hash_multimap
    2. +
  2. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_lu_mtf_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    3. +
  3. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NHL: Native and primary hash-based multimap types find timing test - local
+
+
+
+
+

Observations

+

See Observations::Mapping-Semantics + Considerations.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_hash_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_hash_gcc.png new file mode 100644 index 000000000..03a62f52b Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_hash_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_hash_local.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_hash_local.png new file mode 100644 index 000000000..32a61cac9 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_hash_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_hash_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_hash_msvc.png new file mode 100644 index 000000000..4462d289a Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_hash_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_tree_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_tree_gcc.png new file mode 100644 index 000000000..89e464481 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_tree_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_tree_local.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_tree_local.png new file mode 100644 index 000000000..10b3980ed Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_tree_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_tree_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_tree_msvc.png new file mode 100644 index 000000000..20320953e Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_large_s2p_tree_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small.html b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small.html new file mode 100644 index 000000000..1b379d821 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small.html @@ -0,0 +1,215 @@ + + + + + +"Multimap" Text Find Timing Test with Small Average + Secondary-Key to Primary-Key Ratio + + + +
+

"Multimap" Text Find Timing Test with Small Average + Secondary-Key to Primary-Key Ratio

+

Description

+

This test inserts a number of pairs into a container. The + first item of each pair is a string from an arbitrary text + [wickland96thirty], and + the second is a uniform i.i.d.integer. The container is a + "multimap" - it considers the first member of each pair as a + primary key, and the second member of each pair as a secondary + key (see Motivation::Associative + Containers::Alternative to Multiple Equivalent Keys). There + are 400 distinct primary keys, and the ratio of secondary keys + to primary keys ranges from 1 to 5.

+

The test measures the average find-time as a function of the + number of values inserted. For pb_ds's containers, it + finds the secondary key from a container obtained from finding + a primary key. For the native multimaps, it searches a range + obtained using std::equal_range on a primary key.

+

(The test was executed with multimap_text_find_timing_test + thirty_years_among_the_dead_preproc.txt 400 1 1 6)

+

Purpose

+

The test checks the find-time scalability of different + "multimap" designs (see Motivation::Associative + Containers::Mapping Semantics).

+

Results

+

Figures NTG, NTM, and + NTL show the results for "multimaps" which + use a tree-based container for primary keys, in g++, msvc++, and + local, + respectively; Figures NHG, NHM, and NHL show the results for + "multimaps" which use a hash-based container for primary keys, + in g++, + msvc++, + and local, + respectively.

+
+
+
+
+
no image
NTG: NHG Native and primary tree-based multimap types find timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_mmap- +std::multimap
    2. +
  2. +rb_tree_mmap_lu_mtf_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    3. +
  3. +rb_tree_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NTM: NHM Native and primary tree-based multimap types find timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_mmap- +std::multimap
    2. +
  2. +rb_tree_mmap_lu_mtf_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    3. +
  3. +rb_tree_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NTL: Native and primary tree-based multimap types find timing test - local
+
+
+
+
+
+
+
+
+
no image
NHG: Native and primary hash-based multimap types find timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_mmap- +__gnucxx::hash_multimap
    2. +
  2. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_lu_mtf_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    3. +
  3. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NHM: Native and primary hash-based multimap types find timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_mmap- +stdext::hash_multimap
    2. +
  2. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_lu_mtf_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    3. +
  3. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NHL: Native and primary hash-based multimap types find timing test - local
+
+
+
+
+

Observations

+

See Observations::Mapping-Semantics + Considerations.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_hash_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_hash_gcc.png new file mode 100644 index 000000000..60e850937 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_hash_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_hash_local.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_hash_local.png new file mode 100644 index 000000000..a8fa26117 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_hash_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_hash_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_hash_msvc.png new file mode 100644 index 000000000..11aa9e07b Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_hash_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_tree_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_tree_gcc.png new file mode 100644 index 000000000..f54369b15 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_tree_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_tree_local.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_tree_local.png new file mode 100644 index 000000000..b3d10612f Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_tree_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_tree_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_tree_msvc.png new file mode 100644 index 000000000..035fd9389 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_find_timing_test_small_s2p_tree_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large.html b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large.html new file mode 100644 index 000000000..4affbf440 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large.html @@ -0,0 +1,210 @@ + + + + + +Hash-List "Multimap" Text Memory Use Test with Large + Average Secondary-Key to Primary-Key Ratio + + + +
+

"Multimap" Text Memory Use Test with Large Average + Secondary-Key to Primary-Key Ratio

+

Description

+

This test inserts a number of pairs into a container. The + first item of each pair is a string from an arbitrary text + [wickland96thirty], and + the second is a uniform i.i.d.integer. The container is a + "multimap" - it considers the first member of each pair as a + primary key, and the second member of each pair as a secondary + key (see Motivation::Associative + Containers::Alternative to Multiple Equivalent Keys). There + are 100 distinct primary keys. The test measures the memory use + as a function of the number of values inserted.

+

(The test was executed with multimap_text_insert_mem_usage_test + thirty_years_among_the_dead_preproc.txt 100 200 2100 100)

+

Purpose

+

The test checks the memory scalability of different + "multimap" designs (see Motivation::Associative + Containers::Mapping Semantics).

+

Results

+

Figures NTG, NTM, and + NTL show the results for "multimaps" which + use a tree-based container for primary keys, in g++, msvc++, and + local, + respectively; Figures NHG, NHM, and NHL show the results for + "multimaps" which use a hash-based container for primary keys, + in g++, + msvc++, + and local, + respectively.

+
+
+
+
+
no image
NTG: NHG Native and primary tree-based multimap types mem usage test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +rb_tree_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    2. +
  2. +n_mmap- +std::multimap
    3. +
  3. +rb_tree_mmap_lu_mtf_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NTM: NHM Native and primary tree-based multimap types mem usage test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_mmap- +std::multimap
    2. +
  2. +rb_tree_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    3. +
  3. +rb_tree_mmap_lu_mtf_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NTL: Native and primary tree-based multimap types mem usage test - local
+
+
+
+
+
+
+
+
+
no image
NHG: Native and primary hash-based multimap types mem usage test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    2. +
  2. +n_hash_mmap- +__gnucxx::hash_multimap
    3. +
  3. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_lu_mtf_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NHM: Native and primary hash-based multimap types mem usage test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_mmap- +stdext::hash_multimap
    2. +
  2. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    3. +
  3. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_lu_mtf_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NHL: Native and primary hash-based multimap types mem usage test - local
+
+
+
+
+

Observations

+

See Observations::Mapping-Semantics + Considerations.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_hash_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_hash_gcc.png new file mode 100644 index 000000000..51a3f8d61 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_hash_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_hash_local.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_hash_local.png new file mode 100644 index 000000000..8af7100c6 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_hash_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_hash_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_hash_msvc.png new file mode 100644 index 000000000..3a938c0bb Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_hash_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_tree_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_tree_gcc.png new file mode 100644 index 000000000..a992d8f7c Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_tree_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_tree_local.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_tree_local.png new file mode 100644 index 000000000..63c0c8db7 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_tree_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_tree_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_tree_msvc.png new file mode 100644 index 000000000..26841bd10 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_large_s2p_tree_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small.html b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small.html new file mode 100644 index 000000000..462fce4ca --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small.html @@ -0,0 +1,212 @@ + + + + + +Hash-List "Multimap" Text Memory Use Test with Small + Average Secondary-Key to Primary-Key Ratio + + + +
+

"Multimap" Text Memory Use Test with Small Average + Secondary-Key to Primary-Key Ratio

+

Description

+

This test inserts a number of pairs into a container. The + first item of each pair is a string from an arbitrary text + [wickland96thirty], and + the second is a uniform i.i.d.integer. The container is a + "multimap" - it considers the first member of each pair as a + primary key, and the second member of each pair as a secondary + key (see Motivation::Associative + Containers::Alternative to Multiple Equivalent Keys). There + are 100 distinct primary keys, and the ratio of secondary keys + to primary keys ranges to about 20.

+

The test measures the memory use as a function of the number + of values inserted.

+

(The test was executed with multimap_text_insert_mem_usage_test + thirty_years_among_the_dead_preproc.txt 100 3 4 4)

+

Purpose

+

The test checks the memory scalability of different + "multimap" designs (see Motivation::Associative + Containers::Mapping Semantics).

+

Results

+

Figures NTG, NTM, and + NTL show the results for "multimaps" which + use a tree-based container for primary keys, in g++, msvc++, and + local, + respectively; Figures NHG, NHM, and NHL show the results for + "multimaps" which use a hash-based container for primary keys, + in g++, + msvc++, + and local, + respectively.

+
+
+
+
+
no image
NTG: Native and primary tree-based multimap types mem usage test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +rb_tree_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    2. +
  2. +n_mmap- +std::multimap
    3. +
  3. +rb_tree_mmap_lu_mtf_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NTM: NHM Native and primary tree-based multimap types mem usage test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +rb_tree_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    2. +
  2. +n_mmap- +std::multimap
    3. +
  3. +rb_tree_mmap_lu_mtf_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NTL: Native and primary tree-based multimap types mem usage test - local
+
+
+
+
+
+
+
+
+
no image
NHG: Native and primary hash-based multimap types mem usage test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    2. +
  2. +n_hash_mmap- +__gnucxx::hash_multimap
    3. +
  3. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_lu_mtf_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NHM: Native and primary hash-based multimap types mem usage test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    2. +
  2. +n_hash_mmap- +stdext::hash_multimap
    3. +
  3. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_lu_mtf_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NHL: Native and primary hash-based multimap types mem usage test - local
+
+
+
+
+

Observations

+

See Observations::Mapping-Semantics + Considerations.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_hash_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_hash_gcc.png new file mode 100644 index 000000000..d3eba9da4 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_hash_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_hash_local.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_hash_local.png new file mode 100644 index 000000000..589dccdef Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_hash_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_hash_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_hash_msvc.png new file mode 100644 index 000000000..1828896ee Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_hash_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_tree_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_tree_gcc.png new file mode 100644 index 000000000..9334bc35b Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_tree_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_tree_local.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_tree_local.png new file mode 100644 index 000000000..d7322f287 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_tree_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_tree_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_tree_msvc.png new file mode 100644 index 000000000..2f20e57e5 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_mem_usage_test_small_s2p_tree_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large.html b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large.html new file mode 100644 index 000000000..b9a2d9952 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large.html @@ -0,0 +1,212 @@ + + + + + +"Multimap" Text Insert Timing Test with Large Average + Secondary-Key to Primary-Key Ratio + + + +
+

"Multimap" Text Insert Timing Test with Large Average + Secondary-Key to Primary-Key Ratio

+

Description

+

This test inserts a number of pairs into a container. The + first item of each pair is a string from an arbitrary text + [wickland96thirty], and + the second is a uniform i.i.d.integer. The container is a + "multimap" - it considers the first member of each pair as a + primary key, and the second member of each pair as a secondary + key (see Motivation::Associative + Containers::Alternative to Multiple Equivalent Keys). There + are 100 distinct primary keys, and the ratio of secondary keys + to primary keys ranges to about 20.

+

The test measures the memory use as a function of the number + of values inserted.

+

(The test was executed with multimap_text_insert_mem_usage_test + thirty_years_among_the_dead_preproc.txt 400 1 6 6)

+

Purpose

+

The test checks the insert-time scalability of different + "multimap" designs (see Motivation::Associative + Containers::Mapping Semantics).

+

Results

+

Figures NTG, NTM, and + NTL show the results for "multimaps" which + use a tree-based container for primary keys, in g++, msvc++, and + local, + respectively; Figures NHG, NHM, and NHL show the results for + "multimaps" which use a hash-based container for primary keys, + in g++, + msvc++, + and local, + respectively.

+
+
+
+
+
no image
NTG: Native and primary tree-based multimap types insert timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_mmap- +std::multimap
    2. +
  2. +rb_tree_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    3. +
  3. +rb_tree_mmap_lu_mtf_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NTM: NHM Native and primary tree-based multimap types insert timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +rb_tree_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    2. +
  2. +n_mmap- +std::multimap
    3. +
  3. +rb_tree_mmap_lu_mtf_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NTL: Native and primary tree-based multimap types insert timing test - local
+
+
+
+
+
+
+
+
+
no image
NHG: Native and primary hash-based multimap types insert timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_mmap- +__gnucxx::hash_multimap
    2. +
  2. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    3. +
  3. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_lu_mtf_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NHM: Native and primary hash-based multimap types insert timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_mmap- +stdext::hash_multimap
    2. +
  2. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    3. +
  3. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_lu_mtf_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NHL: Native and primary hash-based multimap types insert timing test - local
+
+
+
+
+

Observations

+

See Observations::Mapping-Semantics + Considerations.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_hash_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_hash_gcc.png new file mode 100644 index 000000000..55b0bf467 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_hash_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_hash_local.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_hash_local.png new file mode 100644 index 000000000..5f8946008 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_hash_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_hash_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_hash_msvc.png new file mode 100644 index 000000000..02f5d0b20 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_hash_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_tree_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_tree_gcc.png new file mode 100644 index 000000000..83366eb37 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_tree_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_tree_local.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_tree_local.png new file mode 100644 index 000000000..2b496b48d Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_tree_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_tree_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_tree_msvc.png new file mode 100644 index 000000000..47196bff7 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_large_s2p_tree_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small.html b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small.html new file mode 100644 index 000000000..cda3629b7 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small.html @@ -0,0 +1,217 @@ + + + + + +"Multimap" Text Insert Timing Test with Small Average + Secondary-Key to Primary-Key Ratio + + + +
+

"Multimap" Text Insert Timing Test with Small Average + Secondary-Key to Primary-Key Ratio

+

Description

+

This test inserts a number of pairs into a container. The + first item of each pair is a string from an arbitrary text + [wickland96thirty], and + the second is a uniform i.i.d.integer. The container is a + "multimap" - it considers the first member of each pair as a + primary key, and the second member of each pair as a secondary + key (see Motivation::Associative + Containers::Alternative to Multiple Equivalent Keys). There + are 400 distinct primary keys, and the ratio of secondary keys + to primary keys ranges from 1 to 5.

+

The test measures the average insert-time as a function of + the number of values inserted. For pb_ds's containers, + it inserts a primary key into the primary associative + container, then a secondary key into the secondary associative + container. For the native multimaps, it obtains a range using + std::equal_range, and inserts a value only if it was + not contained already.

+

(The test was executed with multimap_text_insert_timing_test + thirty_years_among_the_dead_preproc.txt 400 1 1 6)

+

Purpose

+

The test checks the insert-time scalability of different + "multimap" designs (see Motivation::Associative + Containers::Alternative to Multiple Equivalent Keys).

+

Results

+

Figures NTG, NTM, and + NTL show the results for "multimaps" which + use a tree-based container for primary keys, in g++, msvc++, and + local, + respectively; Figures NHG, NHM, and NHL show the results for + "multimaps" which use a hash-based container for primary keys, + in g++, + msvc++, + and local, + respectively.

+
+
+
+
+
no image
NTG: Native and primary tree-based multimap types insert timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_mmap- +std::multimap
    2. +
  2. +rb_tree_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    3. +
  3. +rb_tree_mmap_lu_mtf_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NTM: NHM Native and primary tree-based multimap types insert timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +rb_tree_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    2. +
  2. +n_mmap- +std::multimap
    3. +
  3. +rb_tree_mmap_lu_mtf_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NTL: Native and primary tree-based multimap types insert timing test - local
+
+
+
+
+
+
+
+
+
no image
NHG: Native and primary hash-based multimap types insert timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_hash_mmap- +__gnucxx::hash_multimap
    2. +
  2. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    3. +
  3. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_lu_mtf_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NHM: Native and primary hash-based multimap types insert timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2
    2. +
  2. +n_hash_mmap- +stdext::hash_multimap
    3. +
  3. +cc_hash_mask_exp_nea_lc_1div8_1div2_nsth_mmap_lu_mtf_set- +cc_hash_table +with Comb_Hash_Fn = direct_mask_range_hashing +, and Resize_Policy = hash_standard_resize_policy + with Size_Policy = hash_exponential_size_policy +, and Trigger_Policy = hash_load_check_resize_trigger + with αmin = 1/8 and αmax = 1/2, mapping each key to list_update + with Update_Policy = move_to_front_lu_policy +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NHL: Native and primary hash-based multimap types insert timing test - local
+
+
+
+
+

Observations

+

See Observations::Mapping-Semantics + Considerations.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_hash_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_hash_gcc.png new file mode 100644 index 000000000..3c2d87ecf Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_hash_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_hash_local.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_hash_local.png new file mode 100644 index 000000000..4af78faa5 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_hash_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_hash_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_hash_msvc.png new file mode 100644 index 000000000..81d583904 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_hash_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_tree_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_tree_gcc.png new file mode 100644 index 000000000..368f07350 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_tree_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_tree_local.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_tree_local.png new file mode 100644 index 000000000..40b5b2c43 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_tree_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_tree_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_tree_msvc.png new file mode 100644 index 000000000..99f2d690f Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/multimap_text_insert_timing_test_small_s2p_tree_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/node_invariant_invalidations.png b/libstdc++-v3/doc/html/ext/pb_ds/node_invariant_invalidations.png new file mode 100644 index 000000000..bbd91842b Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/node_invariant_invalidations.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/node_invariants.png b/libstdc++-v3/doc/html/ext/pb_ds/node_invariants.png new file mode 100644 index 000000000..b375f5168 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/node_invariants.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/null_hash_fn.html b/libstdc++-v3/doc/html/ext/pb_ds/null_hash_fn.html new file mode 100644 index 000000000..34f1ee06a --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/null_hash_fn.html @@ -0,0 +1,32 @@ + + + + + + + null_hash_fn Interface + + + + +
+

null_hash_fn Interface

+ +

A "null" hash function, indicating that the combining hash + function is actually a ranged hash function.

+ +

Interface::Concepts::Null + Policy Classes explains the concept of a null policy. See + also Design::Hash-Based + Containers::Hash Policies.

+ +

Defined in: hash_policy.hpp

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/null_lu_metadata.html b/libstdc++-v3/doc/html/ext/pb_ds/null_lu_metadata.html new file mode 100644 index 000000000..e8fb6a3c8 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/null_lu_metadata.html @@ -0,0 +1,25 @@ + + + + + + + null_lu_metadata Interface + + + + +
+

null_lu_metadata Interface

+ +

A null type that means that each link in a list-based + container does not actually need metadata.

+ +

Defined in: list_update_policy.hpp

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/null_mapped_type.html b/libstdc++-v3/doc/html/ext/pb_ds/null_mapped_type.html new file mode 100644 index 000000000..d62fac5c9 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/null_mapped_type.html @@ -0,0 +1,25 @@ + + + + + + + null_mapped_type Interface + + + + +
+

null_mapped_type Interface

+ +

A mapped-policy indicating that an associative container is + a "set"

+ +

Defined in: tag_and_trait.hpp

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/null_probe_fn.html b/libstdc++-v3/doc/html/ext/pb_ds/null_probe_fn.html new file mode 100644 index 000000000..1c8811e96 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/null_probe_fn.html @@ -0,0 +1,29 @@ + + + + + + + null_probe_fn Interface + + + + +
+

null_probe_fn Interface

+ +

A "null" probe function, indicating that the combining probe + function is actually a ranged probe function.

+ +

Interface::Concepts::Null + Policy Classes explains the concept of a null policy.

+ +

Defined in: hash_policy.hpp

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/null_tree_node_update.html b/libstdc++-v3/doc/html/ext/pb_ds/null_tree_node_update.html new file mode 100644 index 000000000..cc1c90054 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/null_tree_node_update.html @@ -0,0 +1,101 @@ + + + + + + + null_tree_node_update Interface + + + + +
+

null_tree_node_update Interface

+ +

A "null" node updater, indicating that no node updates are + required.

+ +

Interface::Concepts::Null + Policy Classes explains the concept of a null policy.

+ +

Defined in: tree_policy.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+class Const_Node_Iterator
+
+ 		+

Const node iterator type.

+ 		-
+ 
+class Node_Iterator
+
+ 		+

Node iterator type.

+ 		-
+ 
+class Cmp_Fn
+
+ 		+

Comparison functor.

+ 		-
+ 
+class Allocator
+
+ 		+

Allocator type.

+ 		-
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/null_trie_node_update.html b/libstdc++-v3/doc/html/ext/pb_ds/null_trie_node_update.html new file mode 100644 index 000000000..18ea00739 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/null_trie_node_update.html @@ -0,0 +1,102 @@ + + + + + + + null_trie_node_update Interface + + + + +
+

null_trie_node_update Interface

+ +

A "null" node updater, indicating that no node updates are + required.

+ +

Interface::Concepts::Null + Policy Classes explains the concept of a null policy.

+ +

Defined in: trie_policy.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+class Const_Node_Iterator
+
+ 		+

Const node iterator type.

+ 		-
+ 
+class Node_Iterator
+
+ 		+

Node iterator type.

+ 		-
+ 
+class E_Access_Traits
+
+ 		+

Comparison functor.

+ 		-
+ 
+class Allocator
+
+ 		+

Allocator type.

+ 		-
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/ov_tree_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/ov_tree_tag.html new file mode 100644 index 000000000..01d7f9082 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/ov_tree_tag.html @@ -0,0 +1,47 @@ + + + + + + + ov_tree_tag Interface + + + + +
+

ov_tree_tag Interface

+ +

Ordered-vector tree data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+tree_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/pairing_heap_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/pairing_heap_tag.html new file mode 100644 index 000000000..5901d1a88 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/pairing_heap_tag.html @@ -0,0 +1,47 @@ + + + + + + + pairing_heap_tag Interface + + + + +
+

pairing_heap_tag Interface

+ +

Pairing-heap data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+priority_queue_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_pop_timing_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_pop_timing_test_gcc.png new file mode 100644 index 000000000..4168787ec Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_pop_timing_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_pop_timing_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_pop_timing_test_local.png new file mode 100644 index 000000000..97ca4e9da Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_pop_timing_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_pop_timing_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_pop_timing_test_msvc.png new file mode 100644 index 000000000..42b707965 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_pop_timing_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_timing_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_timing_test_gcc.png new file mode 100644 index 000000000..9a7ce6c36 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_timing_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_timing_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_timing_test_local.png new file mode 100644 index 000000000..cedcb4cf4 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_timing_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_timing_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_timing_test_msvc.png new file mode 100644 index 000000000..d5488efcf Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/pairing_priority_queue_text_push_timing_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/pat_trie.png b/libstdc++-v3/doc/html/ext/pb_ds/pat_trie.png new file mode 100644 index 000000000..e7129a1a6 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/pat_trie.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/pat_trie_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/pat_trie_tag.html new file mode 100644 index 000000000..2e9a32c91 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/pat_trie_tag.html @@ -0,0 +1,47 @@ + + + + + + + pat_trie_tag Interface + + + + +
+

pat_trie_tag Interface

+ +

PATRICIA trie data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+tree_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/point_invalidation_guarantee.html b/libstdc++-v3/doc/html/ext/pb_ds/point_invalidation_guarantee.html new file mode 100644 index 000000000..f67722169 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/point_invalidation_guarantee.html @@ -0,0 +1,51 @@ + + + + + + + point_invalidation_guarantee Interface + + + + +
+

point_invalidation_guarantee Interface

+ +

Signifies an invalidation guarantee that includes all those + of its base, and additionally, that any point-type iterator, + pointer, or reference to a container object's mapped value type + is valid as long as its corresponding entry has not be erased, + regardless of modifications to the container object.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+basic_invalidation_guarantee
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/point_iterators_cd.png b/libstdc++-v3/doc/html/ext/pb_ds/point_iterators_cd.png new file mode 100644 index 000000000..25a69fc6e Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/point_iterators_cd.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/point_iterators_range_ops_1.png b/libstdc++-v3/doc/html/ext/pb_ds/point_iterators_range_ops_1.png new file mode 100644 index 000000000..c5bc8e5d6 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/point_iterators_range_ops_1.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/point_iterators_range_ops_2.png b/libstdc++-v3/doc/html/ext/pb_ds/point_iterators_range_ops_2.png new file mode 100644 index 000000000..c3f94ee93 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/point_iterators_range_ops_2.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/pq_container_traits.html b/libstdc++-v3/doc/html/ext/pb_ds/pq_container_traits.html new file mode 100644 index 000000000..dcd995f5f --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/pq_container_traits.html @@ -0,0 +1,132 @@ + + + + + + + container_traits Interface + + + + +
+

container_traits Interface

+ +

Traits of a priority-queue container based on its underlying + data structure.

+ +

Defined in: tag_and_trait.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+class Cntnr
+
+ 		+

Container type.

+ 		-
+ +

Public Types and + Constants

+ +

Container Attributes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+container_category
+
+ 		+ 
+Underlying data structure.
+
+ 		+

Data structure category.

+
+ 
+invalidation_guarantee
+
+ 		+ 
+Invalidation guarantee.
+
+ 		+

Invalidation-guarantee type.

+ +

This is either basic_invalidation_guarantee, + point_invalidation_guarantee, or + range_invalidation_guarantee

+
+ 
+split_join_can_throw
+
+ 		+ 
+True only if split or join operations can throw.
+
+ 		+

Split-join throw indicator.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/pq_design.html b/libstdc++-v3/doc/html/ext/pb_ds/pq_design.html new file mode 100644 index 000000000..959560045 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/pq_design.html @@ -0,0 +1,381 @@ + + + + + + + Priority-Queues + + + + +
+

Priority-Queue Design

+ +

Overview

+ +

The priority-queue container has the following + declaration:

+ 
+template<
+    typename Value_Type,
+    typename Cmp_Fn = std::less<Value_Type>,
+    typename Tag = pairing_heap_tag,
+    typename Allocator = std::allocator<char> >
+class priority_queue;
+
+ +

The parameters have the following meaning:

+ +
    +
  1. Value_Type is the value type.
    2. + +
  2. Cmp_Fn is a value comparison functor
    3. + +
  3. Tag specifies which underlying data structure + to use.
    4. + +
  4. Allocator is an allocator + type.
    5. +
+ +

The Tag parameter specifies which underlying + data structure to use. Instantiating it by pairing_heap_tag, + binary_heap_tag, + binomial_heap_tag, + rc_binomial_heap_tag, + or thin_heap_tag, + specifies, respectively, an underlying pairing heap [fredman86pairing], + binary heap [clrs2001], + binomial heap [clrs2001], a binomial heap with + a redundant binary counter [maverik_lowerbounds], + or a thin heap [kt99fat_heas]. These are + explained further in Implementations.

+ +

As mentioned in Tutorial::Priority Queues, + __gnu_pbds::priority_queue + shares most of the same interface with std::priority_queue. + E.g. if q is a priority queue of type + Q, then q.top() will return the "largest" + value in the container (according to typename + Q::cmp_fn). __gnu_pbds::priority_queue + has a larger (and very slightly different) interface than + std::priority_queue, however, since typically + push and pop are deemed insufficient for + manipulating priority-queues.

+ +

Different settings require different priority-queue + implementations which are described in Implementations; Traits + discusses ways to differentiate between the different traits of + different implementations.

+ +

Iterators

+ +

There are many different underlying-data structures for + implementing priority queues. Unfortunately, most such + structures are oriented towards making push and + top efficient, and consequently don't allow efficient + access of other elements: for instance, they cannot support an efficient + find method. In the use case where it + is important to both access and "do something with" an + arbitrary value, one would be out of luck. For example, many graph algorithms require + modifying a value (typically increasing it in the sense of the + priority queue's comparison functor).

+ +

In order to access and manipulate an arbitrary value in a + priority queue, one needs to reference the internals of the + priority queue from some form of an associative container - + this is unavoidable. Of course, in order to maintain the + encapsulation of the priority queue, this needs to be done in a + way that minimizes exposure to implementation internals.

+ +

In pb_ds the priority queue's insert + method returns an iterator, which if valid can be used for subsequent modify and + erase operations. This both preserves the priority + queue's encapsulation, and allows accessing arbitrary values (since the + returned iterators from the push operation can be + stored in some form of associative container).

+ +

Priority queues' iterators present a problem regarding their + invalidation guarantees. One assumes that calling + operator++ on an iterator will associate it + with the "next" value. Priority-queues are + self-organizing: each operation changes what the "next" value + means. Consequently, it does not make sense that push + will return an iterator that can be incremented - this can have + no possible use. Also, as in the case of hash-based containers, + it is awkward to define if a subsequent push operation + invalidates a prior returned iterator: it invalidates it in the + sense that its "next" value is not related to what it + previously considered to be its "next" value. However, it might not + invalidate it, in the sense that it can be + de-referenced and used for modify and erase + operations.

+ +

Similarly to the case of the other unordered associative + containers, pb_ds uses a distinction between + point-type and range type iterators. A priority queue's iterator can always be + converted to a point_iterator, and a + const_iterator can always be converted to a + const_point_iterator.

+ +

The following snippet demonstrates manipulating an arbitrary + value:

+ 
+// A priority queue of integers.
+priority_queue<int> p;
+
+// Insert some values into the priority queue.
+priority_queue<int>::point_iterator it = p.push(0);
+
+p.push(1);
+p.push(2);
+
+// Now modify a value.
+p.modify(it, 3);
+
+assert(p.top() == 3);
+
+ +

(Priority Queue + Examples::Cross-Referencing shows a more detailed + example.)

+ +

It should be noted that an alternative design could embed an + associative container in a priority queue. Could, but most probably should not. To begin with, it should be noted that one + could always encapsulate a priority queue and an associative + container mapping values to priority queue iterators with no + performance loss. One cannot, however, "un-encapsulate" a + priority queue embedding an associative container, which might + lead to performance loss. Assume, that one needs to + associate each value with some data unrelated to priority + queues. Then using pb_ds's design, one could use an + associative container mapping each value to a pair consisting + of this data and a priority queue's iterator. Using the + embedded method would need to use two associative + containers. Similar problems might arise in cases where a value + can reside simultaneously in many priority queues.

+ +

Implementations

+ +

There are three main implementations of priority queues: the + first employs a binary heap, typically one which uses a + sequence; the second uses a tree (or forest of trees), which is + typically less structured than an associative container's tree; + the third simply uses an associative container. These are + shown, respectively, in Figures Underlying Priority-Queue + Data-Structures A1 and A2, Figure Underlying Priority-Queue + Data-Structures B, and Figures Underlying Priority-Queue + Data-Structures C.

+ +
no image
+ +
Underlying Priority-Queue Data-Structures.
+ +

Roughly speaking, any value that is both pushed and popped + from a priority queue must incur a logarithmic expense (in the + amortized sense). Any priority queue implementation that would + avoid this, would violate known bounds on comparison-based + sorting (see, e.g., [clrs2001] and brodal96priority]).

+ +

Most implementations do + not differ in the asymptotic amortized complexity of + push and pop operations, but they differ in + the constants involved, in the complexity of other operations + (e.g., modify), and in the worst-case + complexity of single operations. In general, the more + "structured" an implementation (i.e., the more internal + invariants it possesses) - the higher its amortized complexity + of push and pop operations.

+ +

pb_ds implements different algorithms using a + single class: priority_queue. + Instantiating the Tag template parameter, "selects" + the implementation:

+ +
    +
  1. Instantiating Tag = binary_heap_tag creates + a binary heap of the form in Figures Underlying Priority-Queue + Data-Structures A1 or A2. The former is internally + selected by priority_queue + if Value_Type is instantiated by a primitive type + (e.g., an int); the latter is + internally selected for all other types (e.g., + std::string). This implementations is relatively + unstructured, and so has good push and pop + performance; it is the "best-in-kind" for primitive + types, e.g., ints. Conversely, it has + high worst-case performance, and can support only linear-time + modify and erase operations; this is + explained further in Traits.
    2. + +
  2. Instantiating Tag = pairing_heap_tag + creates a pairing heap of the form in Figure Underlying Priority-Queue + Data-Structures B. This implementations too is relatively + unstructured, and so has good push and pop + performance; it is the "best-in-kind" for non-primitive + types, e.g., std:strings. It also has very + good worst-case push and join performance + (O(1)), but has high worst-case pop + complexity.
    3. + +
  3. Instantiating Tag = binomial_heap_tag + creates a binomial heap of the form in Figure Underlying Priority-Queue + Data-Structures B. This implementations is more + structured than a pairing heap, and so has worse + push and pop performance. Conversely, it + has sub-linear worst-case bounds for pop, + e.g., and so it might be preferred in cases where + responsiveness is important.
    4. + +
  4. Instantiating Tag = rc_binomial_heap_tag + creates a binomial heap of the form in Figure Underlying Priority-Queue + Data-Structures B, accompanied by a redundant counter + which governs the trees. This implementations is therefore + more structured than a binomial heap, and so has worse + push and pop performance. Conversely, it + guarantees O(1) push complexity, and so it + might be preferred in cases where the responsiveness of a + binomial heap is insufficient.
    5. + +
  5. Instantiating Tag = thin_heap_tag creates a + thin heap of the form in Figure Underlying Priority-Queue + Data-Structures B. This implementations too is more + structured than a pairing heap, and so has worse + push and pop performance. Conversely, it + has better worst-case and identical amortized complexities + than a Fibonacci heap, and so might be more appropriate for + some graph algorithms.
    6. +
+ +

Priority-Queue + Performance Tests shows some results for the above, and + discusses these points further.

+ +

Of course, one can use any order-preserving associative + container as a priority queue, as in Figure Underlying Priority-Queue + Data-Structures C, possibly by creating an adapter class + over the associative container (much as + std::priority_queue can adapt std::vector). + This has the advantage that no cross-referencing is necessary + at all; the priority queue itself is an associative container. + Most associative containers are too structured to compete with + priority queues in terms of push and pop + performance.

+ +

Traits

+ +

It would be nice if all priority queues could + share exactly the same behavior regardless of implementation. Sadly, this is not possible. Just one for instance is in join operations: joining + two binary heaps might throw an exception (not corrupt + any of the heaps on which it operates), but joining two pairing + heaps is exception free.

+ +

Tags and traits are very useful for manipulating generic + types. __gnu_pbds::priority_queue + publicly defines container_category as one of the tags + discussed in Implementations. Given any + container Cntnr, the tag of the underlying + data structure can be found via typename + Cntnr::container_category; this is one of the types shown in + Figure Data-structure tag class + hierarchy.

+ +
+
+ +
Data-structure tag class hierarchy.
+ +

Additionally, a traits mechanism can be used to query a + container type for its attributes. Given any container + Cntnr, then __gnu_pbds::container_traits<Cntnr> + is a traits class identifying the properties of the + container.

+ +

To find if a container might throw if two of its objects are + joined, one can use container_traits<Cntnr>::split_join_can_throw, + for example.

+ +

Different priority-queue implementations have different invalidation guarantees. This is + especially important, since as explained in Iterators, there is no way to access an arbitrary + value of priority queues except for iterators. Similarly to + associative containers, one can use + container_traits<Cntnr>::invalidation_guarantee + to get the invalidation guarantee type of a priority queue.

+ +

It is easy to understand from Figure Underlying Priority-Queue + Data-Structures, what container_traits<Cntnr>::invalidation_guarantee + will be for different implementations. All implementations of + type Underlying + Priority-Queue Data-Structures B have point_invalidation_guarantee: + the container can freely internally reorganize the nodes - + range-type iterators are invalidated, but point-type iterators + are always valid. Implementations of type Underlying Priority-Queue + Data-Structures A1 and A2 have basic_invalidation_guarantee: + the container can freely internally reallocate the array - both + point-type and range-type iterators might be invalidated.

+ +

This has major implications, and constitutes a good reason to avoid + using binary heaps. A binary heap can perform modify + or erase efficiently given a valid point-type + iterator. However, inn order to supply it with a valid point-type + iterator, one needs to iterate (linearly) over all + values, then supply the relevant iterator (recall that a + range-type iterator can always be converted to a point-type + iterator). This means that if the number of modify or + erase operations is non-negligible (say + super-logarithmic in the total sequence of operations) - binary + heaps will perform badly.

+ 
+
+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/pq_different_underlying_dss.png b/libstdc++-v3/doc/html/ext/pb_ds/pq_different_underlying_dss.png new file mode 100644 index 000000000..9d84791fc Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/pq_different_underlying_dss.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/pq_examples.html b/libstdc++-v3/doc/html/ext/pb_ds/pq_examples.html new file mode 100644 index 000000000..15311ebc3 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/pq_examples.html @@ -0,0 +1,54 @@ + + + + + + + Examples + + + + +
+

Priority-Queue Examples

+ +

Basic Use

+ +
    +
  1. basic_priority_queue.cc + Basic use of priority queues.
    2. + +
  2. priority_queue_split_join.cc + Splitting and joining priority queues.
    3. + +
  3. priority_queue_erase_if.cc + Conditionally erasing values from a container object.
    4. +
+ +

Generics

+ +
    +
  1. priority_queue_container_traits.cc + Using container_traits + to query about underlying data structure behavior.
    2. +
+ +

Cross Referencing

+ + +
    +
  1. priority_queue_xref.cc + Cross referencing an associative container and a priority + queue.
    2. + +
  2. priority_queue_dijkstra.cc + Cross referencing a vector and a priority queue using a + very simple version of Dijkstra's shortest path + algorithm.
    3. +
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/pq_performance_tests.html b/libstdc++-v3/doc/html/ext/pb_ds/pq_performance_tests.html new file mode 100644 index 000000000..3a6b26912 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/pq_performance_tests.html @@ -0,0 +1,332 @@ + + + + + +Priority-Queue Performance Tests + + + +
+

Priority-Queue Performance Tests

+

Settings

+

This section describes performance tests and their results. + In the following, g++, msvc++, and local (the build used for generating this + documentation) stand for three different builds:

+
+
+

g++

+
    +
  • CPU speed - cpu MHz : 2660.644
    • +
  • Memory - MemTotal: 484412 kB
    • +
  • Platform - + Linux-2.6.12-9-386-i686-with-debian-testing-unstable
    • +
  • Compiler - g++ (GCC) 4.0.2 20050808 (prerelease) + (Ubuntu 4.0.1-4ubuntu9) Copyright (C) 2005 Free Software + Foundation, Inc. This is free software; see the source + for copying conditions. There is NO warranty; not even + for MERCHANTABILITY or FITNESS FOR A PARTICULAR + PURPOSE.
    • +
+
+
+
+
+
+

msvc++

+
    +
  • CPU speed - cpu MHz : 2660.554
    • +
  • Memory - MemTotal: 484412 kB
    • +
  • Platform - Windows XP Pro
    • +
  • Compiler - Microsoft (R) 32-bit C/C++ Optimizing + Compiler Version 13.10.3077 for 80x86 Copyright (C) + Microsoft Corporation 1984-2002. All rights + reserved.
    • +
+
+
+
+

local

    +
  • CPU speed - cpu MHz : 2250.000
    • +
  • Memory - MemTotal: 2076248 kB
    • +
  • Platform - Linux-2.6.16-1.2133_FC5-i686-with-redhat-5-Bordeaux
    • +
  • Compiler - g++ (GCC) 4.1.1 20060525 (Red Hat 4.1.1-1) +Copyright (C) 2006 Free Software Foundation, Inc. +This is free software; see the source for copying conditions. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +
    • +
+
+

Tests

+
    +
  1. Priority Queue + Text push Timing Test
    2. +
  2. Priority + Queue Text push and pop Timing + Test
    3. +
  3. Priority + Queue Random Integer push Timing Test
    4. +
  4. Priority + Queue Random Integer push and pop Timing + Test
    5. +
  5. Priority Queue + Text pop Memory Use Test
    6. +
  6. Priority Queue + Text join Timing Test
    7. +
  7. Priority + Queue Text modify Timing Test - I
    8. +
  8. Priority + Queue Text modify Timing Test - II
    9. +
+

Observations

+

Underlying Data Structures + Complexity

+

The following table shows the complexities of the different + underlying data structures in terms of orders of growth. It is + interesting to note that this table implies something about the + constants of the operations as well (see Amortized push + and pop operations).

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
pushpopmodifyerasejoin
+

std::priority_queue

+		 +

Θ(n) worst

+

Θ(log(n)) amortized

+		 +

Θ(log(n)) Worst

+		 +

Theta;(n log(n)) Worst

+

[std note 1]

+		 +

Θ(n log(n))

+

[std note 2]

+		 +

Θ(n log(n))

+

[std note 1]

+
+

priority_queue

+

with Tag =

+

pairing_heap_tag

+		 +

O(1)

+		 +

Θ(n) worst

+

Θ(log(n)) amortized

+		 +

Θ(n) worst

+

Θ(log(n)) amortized

+		 +

Θ(n) worst

+

Θ(log(n)) amortized

+		 +

O(1)

+
+

priority_queue

+

with Tag =

+

binary_heap_tag

+		 +

Θ(n) worst

+

Θ(log(n)) amortized

+		 +

Θ(n) worst

+

Θ(log(n)) amortized

+		 +

Θ(n)

+		 +

Θ(n)

+		 +

Θ(n)

+
+

priority_queue

+

with Tag =

+

binomial_heap_tag

+		 +

Θ(log(n)) worst

+

O(1) amortized

+		 +

Θ(log(n))

+		 +

Θ(log(n))

+		 +

Θ(log(n))

+		 +

Θ(log(n))

+
+

priority_queue

+

with Tag =

+

rc_binomial_heap_tag

+		 +

O(1)

+		 +

Θ(log(n))

+		 +

Θ(log(n))

+		 +

Θ(log(n))

+		 +

Θ(log(n))

+
+

priority_queue

+

with Tag =

+

thin_heap_tag

+		 +

O(1)

+		 +

Θ(n) worst

+

Θ(log(n)) amortized

+		 +

Θ(log(n)) worst

+

O(1) amortized,

or + +

Θ(log(n)) amortized

+

[thin_heap_note]

+		 +

Θ(n) worst

+

Θ(log(n)) amortized

+		 +

Θ(n)

+
+

[std note 1] This + is not a property of the algorithm, but rather due to the fact + that the STL's priority queue implementation does not support + iterators (and consequently the ability to access a specific + value inside it). If the priority queue is adapting an + std::vector, then it is still possible to reduce this + to Θ(n) by adapting over the STL's adapter and + using the fact that top returns a reference to the + first value; if, however, it is adapting an + std::deque, then this is impossible.

+

[std note 2] As + with [std note 1], this is not a + property of the algorithm, but rather the STL's implementation. + Again, if the priority queue is adapting an + std::vector then it is possible to reduce this to + Θ(n), but with a very high constant (one must call + std::make_heap which is an expensive linear + operation); if the priority queue is adapting an + std::dequeu, then this is impossible.

+

[thin_heap_note] A thin heap has + &Theta(log(n)) worst case modify time + always, but the amortized time depends on the nature of the + operation: I) if the operation increases the key (in the sense + of the priority queue's comparison functor), then the amortized + time is O(1), but if II) it decreases it, then the + amortized time is the same as the worst case time. Note that + for most algorithms, I) is important and II) is not.

+

Amortized push + and pop operations

+

In many cases, a priority queue is needed primarily for + sequences of push and pop operations. All of + the underlying data structures have the same amortized + logarithmic complexity, but they differ in terms of + constants.

+

The table above shows that the different data structures are + "constrained" in some respects. In general, if a data structure + has lower worst-case complexity than another, then it will + perform slower in the amortized sense. Thus, for example a + redundant-counter binomial heap (priority_queue with + Tag = rc_binomial_heap_tag) + has lower worst-case push performance than a binomial + heap (priority_queue + with Tag = binomial_heap_tag), + and so its amortized push performance is slower in + terms of constants.

+

As the table shows, the "least constrained" underlying + data structures are binary heaps and pairing heaps. + Consequently, it is not surprising that they perform best in + terms of amortized constants.

+
    +
  1. Pairing heaps seem to perform best for non-primitive + types (e.g., std::strings), as shown by + Priority + Queue Text push Timing Test and Priority + Queue Text push and pop Timing + Test
    2. +
  2. binary heaps seem to perform best for primitive types + (e.g., ints), as shown by Priority + Queue Random Integer push Timing Test and + Priority + Queue Random Integer push and pop Timing + Test.
    3. +
+

Graph Algorithms

+

In some graph algorithms, a decrease-key operation is + required [clrs2001]; + this operation is identical to modify if a value is + increased (in the sense of the priority queue's comparison + functor). The table above and Priority Queue + Text modify Timing Test - I show that a thin heap + (priority_queue with + Tag = thin_heap_tag) + outperforms a pairing heap (priority_queue with + Tag =Tag = pairing_heap_tag), + but the rest of the tests show otherwise.

+

This makes it difficult to decide which implementation to + use in this case. Dijkstra's shortest-path algorithm, for + example, requires Θ(n) push and + pop operations (in the number of vertices), but + O(n2) modify operations, which can + be in practice Θ(n) as well. It is difficult to + find an a-priori characterization of graphs in which the + actual number of modify operations will dwarf + the number of push and pop operations.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/pq_regression_tests.html b/libstdc++-v3/doc/html/ext/pb_ds/pq_regression_tests.html new file mode 100644 index 000000000..9084409d3 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/pq_regression_tests.html @@ -0,0 +1,52 @@ + + + + + + + Priority-Queue Regression Tests + + + + +
+

Priority-Queue Regression Tests

+ +

Description

+ +

The library contains a single comprehensive regression test. + For a given container type in pb_ds, the test creates + an object of the container type and an object of the + corresponding STL type (i.e., + std::priority_queue). It then performs a random + sequence of methods with random arguments (e.g., pushes, + pops, and so forth) on both objects. At each operation, the + test checks the return value of the method, and optionally both + compares pb_ds's object with the STL's object as well + as performing other consistency checks on pb_ds's + object (e.g., that the size returned by the + size method corresponds to the distance between its + begin and end iterators).

+ +

Additionally, the test integrally checks exception safety + and resource leaks. This is done as follows. A special + allocator type, written for the purpose of the test, both + randomly throws an exceptions when allocations are performed, + and tracks allocations and de-allocations. The exceptions thrown + at allocations simulate memory-allocation failures; the + tracking mechanism checks for memory-related bugs (e.g., + resource leaks and multiple de-allocations). Both + pb_ds's containers and the containers' value-types are + configured to use this allocator.

+ +

Tests

+ +

priority_queue_rand.cc + checks all priority queue types.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/pq_tests.html b/libstdc++-v3/doc/html/ext/pb_ds/pq_tests.html new file mode 100644 index 000000000..de8cb447c --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/pq_tests.html @@ -0,0 +1,24 @@ + + + + + + + Priority-Queue Tests + + + + +
+

Priority-Queue Tests

+ +

Priority-Queue Regression + Tests describes the regression tests; Priority-Queue Performance + Tests describes the performance tests.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/prerequisites.html b/libstdc++-v3/doc/html/ext/pb_ds/prerequisites.html new file mode 100644 index 000000000..7c8888499 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/prerequisites.html @@ -0,0 +1,46 @@ + + + + + + + Prerequisites + + + + +
+

Usage Prerequisites

+ +

pb_ds has been successfully tested with the + following compilers:

+ +
    +
  1. g++ 3.3.1, 3.4.4, 4.0, 4.1, and what will be 4.2
    2. + +
  2. Intel icpc 8.1 and 9
    3. + +
  3. Visual C++ .Net 2005
    4. +
+ +

The library contains only header files, and does not require + any other libraries except the STL. All classes are defined in + namespace pb_ds. The library internally uses + macros beginning with PB_DS (e.g., for header + guards), but #undefs anything it + #defines (except for header guards). Compiling + the library in an environment where macros beginning in + PB_DS are defined, may yield unpredictable results in + compilation, execution, or both.

+ +

Further dependencies are necessary to create the visual output + for the performance tests. To create these graphs, two additional + packages will be needed: pychart and Beautiful + Soup. Both are freely available. +

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue.html b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue.html new file mode 100644 index 000000000..def310f0c --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue.html @@ -0,0 +1,995 @@ + + + + + + + priority_queue Interface + + + + +
+

priority_queue Interface

+ +

Basic priority queue.

+ +

Defined in: priority_queue.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+typename Value_Type
+
+ 		+

Value type.

+ 		-
+ 
+class Cmp_Fn 
+
+ 		+

Comparison functor.

+ 		+ 
+std::less<Value_Type>
+
+
+ 
+class Tag 
+
+ 		+

Data-structure tag.

+ 		pairing_heap_tag
+ 
+class Allocator 
+
+ 		+

Allocator type.

+ 		+ 
+std::allocator<char>
+
+
+ +

Public Types and + Constants

+ +

General Container + Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+typename Allocator::size_type
+
+ 		+

Size type.

+
+ 
+difference_type
+
+ 		+ 
+typename Allocator::difference_type
+
+ 		+

Difference type.

+
+ +

Categories

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+container_category
+
+ 		+ 
+Tag
+
+ 		+

The underlying mapped-structure tag of the + container.

+ +

This is one of:

+ +
    +
  1. binary_heap_tag
    2. + +
  2. binomial_heap_tag
    3. + +
  3. rc_binomial_heap_tag
    4. + +
  4. pairing_heap_tag
    5. + +
  5. thin_heap_tag
    6. +
+
+ +

Policy Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+cmp_fn
+
+ 		+ 
+Cmp_Fn
+
+ 		+

Comparison functor type.

+
+ 
+allocator
+
+ 		+ 
+Allocator
+
+ 		+

Allocator + type.

+
+ +

Value-Type Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+value_type
+
+ 		+ 
+Value_Type
+
+ 		+

Value type.

+
+ 
+reference
+
+ 		+ 
+typename allocator::template rebind<
+    value_type>::other::reference
+
+ 		+

Value reference type.

+
+ 
+const_reference
+
+ 		+ 
+typename allocator::template rebind<
+    value_type>::other::const_reference
+
+ 		+

Const value reference type.

+
+ 
+pointer
+
+ 		+ 
+typename allocator::template rebind<
+    value_type>::other::pointer
+
+ 		+

Value pointer type.

+
+ 
+const_pointer
+
+ 		+ 
+typename allocator::template rebind<
+    value_type>::other::const_pointer
+
+ 		+

Const Value pointer type.

+
+ +

Iterator Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+const_point_iterator
+
+ 		+ 
+Const point-type iterator.
+
+ 		+

Const point-type iterator.

+
+ 
+point_iterator
+
+ 		+ 
+Point-type iterator.
+
+ 		+

Point-type iterator.

+
+ 
+const_iterator
+
+ 		+ 
+Const range-type iterator.
+
+ 		+

Const range-type iterator.

+
+ 
+iterator
+
+ 		+ 
+Range-type iterator.
+
+ 		+

Range-type iterator.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  priority_queue
+  ()
+
+ 		+

Default constructor.

+
+ 
+  priority_queue
+  (const cmp_fn &r_cmp_fn)
+
+ 		+

Constructor taking some policy objects. r_cmp_fn will be copied by the + Cmp_Fn object of the + container object.

+
+ 
+template<
+    class It>
+  priority_queue
+  (It first_it, 
+    It last_it)
+
+ 		+

Constructor taking iterators to a range of value_types. The + value_types + between first_it and + last_it will be inserted + into the container object.

+
+ 
+template<
+    class It>
+  priority_queue
+  (It first_it, 
+    It last_it,
+    const cmp_fn &r_cmp_fn)
+
+ 		+

Constructor taking iterators to a range of value_types and some + policy objects The value_types between + first_it and + last_it will be inserted + into the container object. r_cmp_fn will be copied by the + cmp_fn object of the + container object.

+
+ 
+  priority_queue
+  (const priority_queue &other)
+
+ 		+

Copy constructor.

+
+ 
+virtual 
+  ~priority_queue
+  ()
+
+ 		+

Destructor.

+
+ 
+priority_queue &
+  operator=
+  (const priority_queue &other)
+
+ 		+

Assignment operator.

+
+ 
+void
+  swap
+  (priority_queue &other)
+
+ 		+

Swaps content.

+
+ +

Information Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline size_type
+  size
+  () const
+
+ 		+

Returns the number of distinct value_type objects + the container object is storing.

+
+ 
+inline size_type
+  max_size
+  () const
+
+ 		+

Returns an upper bound on the number of distinct + value_type + objects this container can store.

+
+ 
+inline bool
+  empty
+  () const
+
+ 		+

Returns whether the container object is not storing + any value_type + objects.

+
+ +

Insert Methods

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline point_iterator
+  push
+  (const_reference r_val)
+
+ 		+

Inserts a value_type object. + returns a point_iterator + object associated with the new pushed r_val.

+
+ +

Find Methods

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline const_reference 
+  top
+  () const
+
+ 		+

Returns the const_reference + of the largest value_type in the + container object, i.e., a value_type v_max for + which any other value_type v in the + container object will satisfy !cmp_fn()(v_max, v).

+
+ +

Modify Methods

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  modify
+  (point_iterator it,
+    const_reference r_new_val)
+
+ 		+

Modifies the value_type associated + with the point_iterator + it into r_new_val.

+ +

To use this method, value_type must be + assignable.

+
+ +

Erase Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  pop
+  ()
+
+ 		+

Pops the largest value_type.

+ +

If the container object is empty, results are + undefined.

+
+ 
+inline void
+  erase
+  (point_iterator it)
+
+ 		+

Erases the value_type associated + with the point_iterator + it.

+
+ 
+template<
+  class Pred>
+inline size_type 
+  erase_if
+  (Pred prd)
+
+ 		+

Erases any value_type satisfying + the predicate prd; + returns the number of value_types + erased.

+
+ 
+void 
+  clear
+  ()
+
+ 		+

Clears the container object.

+
+ +

Split and join + Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+void 
+  join
+  (priority_queue &other)
+
+ 		+

Joins two container objects. When this function + returns, other will be + empty.

+ +

When calling this method, other's policies must be + equivalent to this object's policies.

+
+ 
+template<
+  class Pred>
+inline void
+  split
+  (Pred prd,
+    priority_queue &other)
+
+ 		+

Splits into two container objects. When this function + returns, other will be + contain only values v for which prd(v) is true.

+ +

When calling this method, other's policies must be + equivalent to this object's policies.

+
+ +

Iteration Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline iterator
+  begin
+  ()
+
+ 		+

Returns an iterator corresponding + to the first value_type in the + container.

+
+ 
+inline const_iterator
+  begin
+  () const
+
+ 		+

Returns a const_iterator + corresponding to the first value_type in the + container.

+
+ 
+inline iterator
+  end
+  ()
+
+ 		+

Returns an iterator corresponding + to the just-after-last value_type in the + container.

+
+ 
+inline const_iterator
+  end
+  () const
+
+ 		+

Returns a const_iterator + corresponding to the just-after-last value_type in the + container.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_pop_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_pop_timing_test.html new file mode 100644 index 000000000..903331d9d --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_pop_timing_test.html @@ -0,0 +1,161 @@ + + + + + +Priority Queue Random Int Push Pop Timing Test + + + +
+

Priority Queue Random Integer push and + pop Timing Test

+

Description

+

This test inserts a number of values with i.i.d. integer + keys into a container using push , then removes them + using pop . It measures the average time for + push and pop as a function of the number of + values.

+

(The test was executed with +priority_queue_random_int_push_pop_timing_test + thirty_years_among_the_dead_preproc.txt 200 200 2100)

+

Purpose

+

The test checks the effect of different underlying + data structures (see Design::Priority + Queues::Implementations).

+

Results

+

Figures NPG, NPM, and + NPL shows the results for the native + priority queues and pb_ds 's priority queues in + g++, + msvc++, and + local, + respectively.

+
+
+
+
+
no image
NPG: Native and pb ds priority queue push pop timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    2. +
  2. +rc_binomial_heap- +priority_queue + with Tag = rc_binomial_heap_tag +
    3. +
  3. +binomial_heap- +priority_queue + with Tag = binomial_heap_tag +
    4. +
  4. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    5. +
  5. +n_pq_deque- +std::priority_queue adapting std::deque
    6. +
  6. +n_pq_vector- +std::priority_queue adapting std::vector
    7. +
  7. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    8. +
+
+
+
+
+
+
+
+
+
+
no image
NPM: Native and pb ds priority queue push pop timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    2. +
  2. +rc_binomial_heap- +priority_queue + with Tag = rc_binomial_heap_tag +
    3. +
  3. +binomial_heap- +priority_queue + with Tag = binomial_heap_tag +
    4. +
  4. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    5. +
  5. +n_pq_deque- +std::priority_queue adapting std::deque
    6. +
  6. +n_pq_vector- +std::priority_queue adapting std::vector
    7. +
  7. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    8. +
+
+
+
+
+
+
+
+
+
+
no image
NPL: Native and pb ds priority queue push pop timing test - local
+
+
+
+
+

Observations

+

Binary heaps are the most suited for sequences of + push and pop operations of primitive types + (e.g. ints). This is explained in + Priority + Queue Random Int push Timing Test . (See Priority Queue + Text push Timing Test for the case of primitive + types.)

+

At first glance it seems that the STL's vector-based + priority queue is approximately on par with pb_ds's + corresponding priority queue. There are two differences + however:

+
    +
  1. The STL's priority queue does not downsize the underlying + vector (or deque) as the priority queue becomes smaller + (see Priority Queue + Text pop Memory Use Test). It is therefore + gaining some speed at the expense of space.
    2. +
  2. From Priority + Queue Random Integer push and pop Timing + Test, it seems that the STL's priority queue is slower in + terms of pus operations. Since the number of + pop operations is at most that of push + operations, the test here is the "best" for the STL's + priority queue.
    3. +
+

Priority-Queue + Performance Tests::Observations discusses this further and + summarizes.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_pop_timing_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_pop_timing_test_gcc.png new file mode 100644 index 000000000..68f5e2b6b Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_pop_timing_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_pop_timing_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_pop_timing_test_local.png new file mode 100644 index 000000000..51f8211f1 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_pop_timing_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_pop_timing_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_pop_timing_test_msvc.png new file mode 100644 index 000000000..4fc191c8b Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_pop_timing_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_timing_test.html new file mode 100644 index 000000000..ba91f601a --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_timing_test.html @@ -0,0 +1,200 @@ + + + + + +Priority Queue Random Int Push Timing Test + + + +
+

Priority Queue Random Integer push Timing + Test

+

Description

+

This test inserts a number of values with i.i.d integer keys + into a container using push . It measures the average + time for push as a function of the number of + values.

+

(The test was executed with + priority_queue_random_intpush_timing_test + thirty_years_among_the_dead_preproc.txt 200 200 2100)

+

Purpose

+

The test checks the effect of different underlying + data structures (see Design::Priority + Queues::Implementations).

+

Results

+

Figures NPG, NPM, and + NPL show the results for the native priority + queues and pb_ds 's priority queues in g++, msvc++, and + local, + respectively; Figures NBPG, NBPM, and NBPL shows the + results for the binary-heap based native priority queues and + pb_ds 's priority queues in g++, msvc++, and + local, + respectively

+
+
+
+
+
no image
NPG: Native and pb ds priority queue push timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +rc_binomial_heap- +priority_queue + with Tag = rc_binomial_heap_tag +
    2. +
  2. +binomial_heap- +priority_queue + with Tag = binomial_heap_tag +
    3. +
  3. +n_pq_deque- +std::priority_queue adapting std::deque
    4. +
  4. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    5. +
  5. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    6. +
  6. +n_pq_vector- +std::priority_queue adapting std::vector
    7. +
  7. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    8. +
+
+
+
+
+
+
+
+
+
+
no image
NPM: Native and pb ds priority queue push timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +rc_binomial_heap- +priority_queue + with Tag = rc_binomial_heap_tag +
    2. +
  2. +binomial_heap- +priority_queue + with Tag = binomial_heap_tag +
    3. +
  3. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    4. +
  4. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    5. +
  5. +n_pq_deque- +std::priority_queue adapting std::deque
    6. +
  6. +n_pq_vector- +std::priority_queue adapting std::vector
    7. +
  7. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    8. +
+
+
+
+
+
+
+
+
+
+
no image
NPL: Native and pb ds priority queue push timing test - local
+
+
+
+
+
+
+
+
+
no image
NBPG: Native and pb ds binary priority queue push timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_deque- +std::priority_queue adapting std::deque
    2. +
  2. +n_pq_vector- +std::priority_queue adapting std::vector
    3. +
  3. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NBPM: Native and pb ds binary priority queue push timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_deque- +std::priority_queue adapting std::deque
    2. +
  2. +n_pq_vector- +std::priority_queue adapting std::vector
    3. +
  3. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NBPL: Native and pb ds binary priority queue push timing test - local
+
+
+
+
+

Observations

+

Binary heaps are the most suited for sequences of + push and pop operations of primitive types + (e.g. ints). They are less constrained + than any other type, and since it is very efficient to store + such types in arrays, they outperform even pairing heaps. (See + Priority + Queue Text push Timing Test for the case of + non-primitive types.)

+

Priority-Queue + Performance Tests::Observations discusses this further and + summarizes.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_timing_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_timing_test_gcc.png new file mode 100644 index 000000000..ee8c9b7d9 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_timing_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_timing_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_timing_test_local.png new file mode 100644 index 000000000..dead185fa Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_timing_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_timing_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_timing_test_msvc.png new file mode 100644 index 000000000..0a1a8eaef Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_random_int_push_timing_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_tag.html new file mode 100644 index 000000000..8b6d81c37 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_tag.html @@ -0,0 +1,47 @@ + + + + + + + priority_queue_tag Interface + + + + +
+

priority_queue_tag Interface

+ +

Basic priority-queue data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+container_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_tag_cd.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_tag_cd.png new file mode 100644 index 000000000..ed8d875f0 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_tag_cd.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_tag_cd.svg b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_tag_cd.svg new file mode 100644 index 000000000..be007aecb --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_tag_cd.svg @@ -0,0 +1,368 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + Benjamin Kosnik + + + + + + + + + pairing_heap_tag + bionomial_heap_tag + + priority_queue_tag + + + rc_binomial_heap_tag + + binary_heap_tag + + + thin_heap_tag + + + + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_join_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_join_timing_test.html new file mode 100644 index 000000000..a4bf576ff --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_join_timing_test.html @@ -0,0 +1,141 @@ + + + + + +Priority Queue Text Join Timing Test + + + +
+

Priority Queue Text join Timing Test

+

Description

+

This test inserts a number of values with keys from an + arbitrary text ([ wickland96thirty ]) into + two containers, then merges the containers. It uses + join for pb_ds's priority queues; for the + STL's priority queues, it successively pops values from one + container and pushes them into the other. The test measures the + average time as a function of the number of values.

+

(The test was executed with priority_queue_text_join_timing_test + thirty_years_among_the_dead_preproc.txt 200 200 2100)

+

Purpose

+

The test checks the effect of different underlying + data structures (see Design::Priority + Queues::Implementations).

+

Results

+

Figures NPG, NPM, and + NPL show the results for the native priority + queues and pb_ds 's priority queues in g++, msvc, and local, + respectively.

+
+
+
+
+
no image
NPG: Native tree and pb ds priority queue push timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_deque- +std::priority_queue adapting std::deque
    2. +
  2. +n_pq_vector- +std::priority_queue adapting std::vector
    3. +
  3. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    4. +
  4. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    5. +
  5. +rc_binomial_heap- +priority_queue + with Tag = rc_binomial_heap_tag +
    6. +
  6. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    7. +
  7. +binomial_heap- +priority_queue + with Tag = binomial_heap_tag +
    8. +
+
+
+
+
+
+
+
+
+
+
no image
NPM: Native tree and pb ds priority queue push timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_deque- +std::priority_queue adapting std::deque
    2. +
  2. +n_pq_vector- +std::priority_queue adapting std::vector
    3. +
  3. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    4. +
  4. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    5. +
  5. +rc_binomial_heap- +priority_queue + with Tag = rc_binomial_heap_tag +
    6. +
  6. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    7. +
  7. +binomial_heap- +priority_queue + with Tag = binomial_heap_tag +
    8. +
+
+
+
+
+
+
+
+
+
+
no image
NPL: Native tree and pb ds priority queue push timing test - local
+
+
+
+
+

Observations

+

In this test the node-based heaps perform join in + either logarithmic or constant time. The binary heap requires + linear time, since the well-known heapify algorithm [clrs2001] is linear.

+

It would be possible to apply the heapify algorithm to the + STL containers, if they would support iteration (which they + don't). Barring iterators, it is still somehow possible to + perform linear-time merge on a std::vector-based STL + priority queue, using top() and size() (since + they are enough to expose the underlying array), but this is + impossible for a std::deque-based STL priority queue. + Without heapify, the cost is super-linear.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_join_timing_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_join_timing_test_gcc.png new file mode 100644 index 000000000..a48bb3586 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_join_timing_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_join_timing_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_join_timing_test_local.png new file mode 100644 index 000000000..1701b4d8a Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_join_timing_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_join_timing_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_join_timing_test_msvc.png new file mode 100644 index 000000000..0575b99c0 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_join_timing_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test.html new file mode 100644 index 000000000..7ece80bcf --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test.html @@ -0,0 +1,204 @@ + + + + + +Priority Queue Text Modify (Down) Timing Test + + + +
+

Priority Queue Text modify Timing Test - II

+

Description

+

This test inserts a number of values with keys from an + arbitrary text ([ wickland96thirty ]) into + into a container then modifies each one "down" (i.e., it + makes it smaller). It uses modify for pb_ds's + priority queues; for the STL's priority queues, it pops values + from a container until it reaches the value that should be + modified, then pushes values back in. It measures the average + time for modify as a function of the number of + values.

+

(The test was executed with priority_queue_text_modify_down_timing_test + thirty_years_among_the_dead_preproc.txt 200 200 2100 f)

+

Purpose

+

The main purpose of this test is to contrast Priority Queue + Text modify Timing Test - I.

+

Results

+

Figures NPG, NPM, and + NPL show the results for the native priority + queues and pb_ds 's priority queues in g++, msvc++, and + local, + respectively; Figures NRTG, NRTM, and NRTL show the results + for the pairing heap and thin heaps in g++, msvc++, and + local, + respectively,

+
+
+
+
+
no image
NPG: Native and pb ds priority queue modify timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_deque- +std::priority_queue adapting std::deque
    2. +
  2. +n_pq_vector- +std::priority_queue adapting std::vector
    3. +
  3. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    4. +
  4. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    5. +
  5. +rc_binomial_heap- +priority_queue + with Tag = rc_binomial_heap_tag +
    6. +
  6. +binomial_heap- +priority_queue + with Tag = binomial_heap_tag +
    7. +
  7. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    8. +
+
+
+
+
+
+
+
+
+
+
no image
NPM: Native and pb ds priority queue modify timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_deque- +std::priority_queue adapting std::deque
    2. +
  2. +n_pq_vector- +std::priority_queue adapting std::vector
    3. +
  3. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    4. +
  4. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    5. +
  5. +rc_binomial_heap- +priority_queue + with Tag = rc_binomial_heap_tag +
    6. +
  6. +binomial_heap- +priority_queue + with Tag = binomial_heap_tag +
    7. +
  7. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    8. +
+
+
+
+
+
+
+
+
+
+
no image
NPL: Native and pb ds priority queue modify timing test - local
+
+
+
+
+
+
+
+
+
no image
NRTG: Pairing and thin priority queue modify timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    2. +
  2. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    3. +
+
+
+
+
+
+
+
+
+
+
no image
NRTM: Pairing and thin priority queue modify timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    2. +
  2. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    3. +
+
+
+
+
+
+
+
+
+
+
no image
NRTL: Pairing and thin priority queue modify timing test - local
+
+
+
+
+

Observations

+

Most points in these results are similar to Priority Queue + Text modify Timing Test - I.

+

It is interesting to note, however, that as opposed to that + test, a thin heap (priority_queue with + Tag = thin_heap_tag) is + outperformed by a pairing heap (priority_queue with + Tag = pairing_heap_tag). + In this case, both heaps essentially perform an erase + operation followed by a push operation. As the other + tests show, a pairing heap is usually far more efficient than a + thin heap, so this is not surprising.

+

Most algorithms that involve priority queues increase values + (in the sense of the priority queue's comparison functor), and + so Priority Queue + Text modify Timing Test - I is more interesting + than this test.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_gcc.png new file mode 100644 index 000000000..74cbc6523 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_local.png new file mode 100644 index 000000000..2fa9c7988 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_msvc.png new file mode 100644 index 000000000..20b663736 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_pairing_thin_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_pairing_thin_gcc.png new file mode 100644 index 000000000..ca901831e Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_pairing_thin_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_pairing_thin_local.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_pairing_thin_local.png new file mode 100644 index 000000000..977d16718 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_pairing_thin_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_pairing_thin_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_pairing_thin_msvc.png new file mode 100644 index 000000000..bf68bf992 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_down_timing_test_pairing_thin_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test.html new file mode 100644 index 000000000..72a1e0a75 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test.html @@ -0,0 +1,222 @@ + + + + + +Priority Queue Text Modify (Up) Timing Test + + + +
+

Priority Queue Text modify Timing Test - I

+

Description

+

This test inserts a number of values with keys from an + arbitrary text ([ wickland96thirty ]) into + into a container then modifies each one "up" (i.e., it + makes it larger). It uses modify for pb_ds's + priority queues; for the STL's priority queues, it pops values + from a container until it reaches the value that should be + modified, then pushes values back in. It measures the average + time for modify as a function of the number of + values.

+

(The test was executed with priority_queue_text_modify_up_timing_test + thirty_years_among_the_dead_preproc.txt 200 200 2100 t)

+

Purpose

+

The test checks the effect of different underlying + data structures (see Design::Priority + Queues::Implementations) for graph algorithms settings. + Note that making an arbitrary value larger (in the sense of the + priority queue's comparison functor) corresponds to + decrease-key in standard graph algorithms [clrs2001].

+

Results

+

Figures NPG, NPM, and + NPL show the results for the native priority + queues and pb_ds 's priority queues in g++, msvc++, and + local, + respectively; Figures NRTG, NRTM, and NRTL show the results + for the pairing heap and thin heaps in g++, msvc++, and + local, + respectively,

+
+
+
+
+
no image
NPG: Native and pb ds priority queue modify timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_deque- +std::priority_queue adapting std::deque
    2. +
  2. +n_pq_vector- +std::priority_queue adapting std::vector
    3. +
  3. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    4. +
  4. +rc_binomial_heap- +priority_queue + with Tag = rc_binomial_heap_tag +
    5. +
  5. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    6. +
  6. +binomial_heap- +priority_queue + with Tag = binomial_heap_tag +
    7. +
  7. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    8. +
+
+
+
+
+
+
+
+
+
+
no image
NPM: Native and pb ds priority queue modify timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_deque- +std::priority_queue adapting std::deque
    2. +
  2. +n_pq_vector- +std::priority_queue adapting std::vector
    3. +
  3. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    4. +
  4. +rc_binomial_heap- +priority_queue + with Tag = rc_binomial_heap_tag +
    5. +
  5. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    6. +
  6. +binomial_heap- +priority_queue + with Tag = binomial_heap_tag +
    7. +
  7. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    8. +
+
+
+
+
+
+
+
+
+
+
no image
NPL: Native and pb ds priority queue modify timing test - local
+
+
+
+
+
+
+
+
+
no image
NRTG: Pairing and thin priority queue modify timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    2. +
  2. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    3. +
+
+
+
+
+
+
+
+
+
+
no image
NRTM: Pairing and thin priority queue modify timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    2. +
  2. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    3. +
+
+
+
+
+
+
+
+
+
+
no image
NRTL: Pairing and thin priority queue modify timing test - local
+
+
+
+
+

Observations

+

As noted above, increasing an arbitrary value (in the sense + of the priority queue's comparison functor) is very common in + graph-related algorithms. In this case, a thin heap (priority_queue with + Tag = thin_heap_tag) + outperforms a pairing heap (priority_queue with + Tag = pairing_heap_tag). + Conversely, Priority Queue Text + push Timing Test, Priority Queue + Text push and pop Timing Test, Priority + Queue Random Integer push Timing Test, and + Priority + Queue Random Integer push and pop Timing + Test show that the situation is reversed for other + operations. It is not clear when to prefer one of these two + different types.

+

In this test pb_ds's binary heaps effectively + perform modify in linear time. As explained in Priority Queue Design::Traits, + given a valid point-type iterator, a binary heap can perform + modify logarithmically. The problem is that binary + heaps invalidate their find iterators with each modifying + operation, and so the only way to obtain a valid point-type + iterator is to iterate using a range-type iterator until + finding the appropriate value, then use the range-type iterator + for the modify operation.

+

The explanation for the STL's priority queues' performance + is similar to that in Priority Queue Text + join Timing Test.

+

Priority-Queue + Performance Tests::Observations discusses this further and + summarizes.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_gcc.png new file mode 100644 index 000000000..d9dedc20c Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_local.png new file mode 100644 index 000000000..31575b452 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_msvc.png new file mode 100644 index 000000000..4005547c8 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_pairing_thin_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_pairing_thin_gcc.png new file mode 100644 index 000000000..1aa5aba94 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_pairing_thin_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_pairing_thin_local.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_pairing_thin_local.png new file mode 100644 index 000000000..b878dde66 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_pairing_thin_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_pairing_thin_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_pairing_thin_msvc.png new file mode 100644 index 000000000..740594384 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_modify_up_timing_test_pairing_thin_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_pop_mem_usage_test.html b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_pop_mem_usage_test.html new file mode 100644 index 000000000..2545fc07d --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_pop_mem_usage_test.html @@ -0,0 +1,143 @@ + + + + + +Priority Queue Text Pop Memory Use Test + + + +
+

Priority Queue Text pop Memory Use Test

+

Description

+

This test inserts a number of values with keys from an + arbitrary text ([ wickland96thirty ]) into + a container, then pops them until only one is left in the + container. It measures the memory use as a function of the + number of values pushed to the container.

+

(The test was executed with priority_queue_text_pop_mem_usage_test + thirty_years_among_the_dead_preproc.txt 200 200 2100)

+

Purpose

+

The test checks the effect of different underlying + data structures (see Design::Priority + Queues::Implementations).

+

Results

+

Figures NPG, NPM, and + NPL show the results for the native priority + queues and pb_ds 's priority queues in g++, msvc++, and + local, + respectively.

+
+
+
+
+
no image
NPG: Native and pb ds priority queue pop memory-use test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_vector- +std::priority_queue adapting std::vector
    2. +
  2. +n_pq_deque- +std::priority_queue adapting std::deque
    3. +
  3. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    4. +
  4. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    5. +
  5. +binomial_heap- +priority_queue + with Tag = binomial_heap_tag +
    6. +
  6. +rc_binomial_heap- +priority_queue + with Tag = rc_binomial_heap_tag +
    7. +
  7. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    8. +
+
+
+
+
+
+
+
+
+
+
no image
NPM: Native and pb ds priority queue pop memory-use test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_vector- +std::priority_queue adapting std::vector
    2. +
  2. +n_pq_deque- +std::priority_queue adapting std::deque
    3. +
  3. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    4. +
  4. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    5. +
  5. +binomial_heap- +priority_queue + with Tag = binomial_heap_tag +
    6. +
  6. +rc_binomial_heap- +priority_queue + with Tag = rc_binomial_heap_tag +
    7. +
  7. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    8. +
+
+
+
+
+
+
+
+
+
+
no image
NPL: Native and pb ds priority queue pop memory-use test - local
+
+
+
+
+

Observations

+

The priority queue implementations (excluding the STL's) use + memory proportionally to the number of values they hold: + node-based implementations (e.g., a pairing heap) do so + naturally; pb_ds's binary heap de-allocates memory when + a certain lower threshold is exceeded.

+

Note from Priority Queue + Text push and pop Timing Test and + Priority + Queue Random Integer push and pop Timing + Test that this does not impede performance compared to the + STL's priority queues.

+

(See Hash-Based Erase + Memory Use Test for a similar phenomenon regarding priority + queues.)

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_pop_mem_usage_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_pop_mem_usage_test_gcc.png new file mode 100644 index 000000000..2c1918d06 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_pop_mem_usage_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_pop_mem_usage_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_pop_mem_usage_test_local.png new file mode 100644 index 000000000..c1413fc93 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_pop_mem_usage_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_pop_mem_usage_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_pop_mem_usage_test_msvc.png new file mode 100644 index 000000000..9717f498b Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_pop_mem_usage_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_pop_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_pop_timing_test.html new file mode 100644 index 000000000..3c143fe5a --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_pop_timing_test.html @@ -0,0 +1,209 @@ + + + + + +Priority Queue Text Push Pop Timing Test + + + +
+

Priority Queue Text push and pop Timing + Test

+

Description

+

This test inserts a number of values with keys from an + arbitrary text ([ wickland96thirty ]) into + a container using push , then removes them using + pop . It measures the average time for push + as a function of the number of values.

+

(The test was executed with + priority_queue_text_push_pop_timing_test + thirty_years_among_the_dead_preproc.txt 200 200 2100)

+

Purpose

+

The test checks the effect of different underlying + data structures (see Design::Priority + Queues::Implementations).

+

Results

+

Figures NPG, NPM, and + NPL show the results for the native priority + queues and pb_ds 's priority queues in g++, msvc++, and + local, + respectively; Figures NBRG, NBRM, and NBRL show the results + for the native priority queues and pb_ds's pairing + queues in g++, msvc++, and + local, + respectively.

+
+
+
+
+
no image
NPG: Native tree and pb ds priority queue push and pop timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_vector- +std::priority_queue adapting std::vector
    2. +
  2. +n_pq_deque- +std::priority_queue adapting std::deque
    3. +
  3. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    4. +
  4. +rc_binomial_heap- +priority_queue + with Tag = rc_binomial_heap_tag +
    5. +
  5. +binomial_heap- +priority_queue + with Tag = binomial_heap_tag +
    6. +
  6. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    7. +
  7. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    8. +
+
+
+
+
+
+
+
+
+
+
no image
NPM: Native tree and pb ds priority queue push and pop timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_deque- +std::priority_queue adapting std::deque
    2. +
  2. +n_pq_vector- +std::priority_queue adapting std::vector
    3. +
  3. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    4. +
  4. +rc_binomial_heap- +priority_queue + with Tag = rc_binomial_heap_tag +
    5. +
  5. +binomial_heap- +priority_queue + with Tag = binomial_heap_tag +
    6. +
  6. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    7. +
  7. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    8. +
+
+
+
+
+
+
+
+
+
+
no image
NPL: Native tree and pb ds priority queue push and pop timing test - local
+
+
+
+
+
+
+
+
+
no image
NBRG: Native tree and pb ds pairing priority queue push and pop timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_vector- +std::priority_queue adapting std::vector
    2. +
  2. +n_pq_deque- +std::priority_queue adapting std::deque
    3. +
  3. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NBRM: Native tree and pb ds pairing priority queue push and pop timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_deque- +std::priority_queue adapting std::deque
    2. +
  2. +n_pq_vector- +std::priority_queue adapting std::vector
    3. +
  3. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NBRL: Native tree and pb ds pairing priority queue push and pop timing test - local
+
+
+
+
+

Observations

+

These results are very similar to Priority Queue Text + push Timing Test. As stated there, pairing heaps + (priority_queue with + Tag = pairing_heap_tag) + are most suited for push and pop sequences of + non-primitive types such as strings. Observing these two tests, + one can note that a pairing heap outperforms the others in + terms of push operations, but equals binary heaps + (priority_queue with + Tag = binary_heap_tag) if + the number of push and pop operations is + equal. As the number of pop operations is at most + equal to the number of push operations, pairing heaps + are better in this case. See Priority + Queue Random Integer push and pop Timing + Test for a case which is different.

+

Priority-Queue + Performance Tests::Observations discusses this further and + summarizes.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_pop_timing_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_pop_timing_test_gcc.png new file mode 100644 index 000000000..d4886ae59 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_pop_timing_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_pop_timing_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_pop_timing_test_local.png new file mode 100644 index 000000000..a7c5f8987 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_pop_timing_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_pop_timing_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_pop_timing_test_msvc.png new file mode 100644 index 000000000..a5720402b Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_pop_timing_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_timing_test.html new file mode 100644 index 000000000..542eb913c --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_timing_test.html @@ -0,0 +1,219 @@ + + + + + +Priority Queue Text Push Timing Test + + + +
+

Priority Queue Text push Timing Test

+

Description

+

This test inserts a number of values with keys from an + arbitrary text ([ wickland96thirty ]) into + a container using push . It measures the average time + for push as a function of the number of values + pushed.

+

(The test was executed with priority_queue_text_push_timing_test + thirty_years_among_the_dead_preproc.txt 200 200 2100)

+

Purpose

+

The test checks the effect of different underlying + data structures (see Design::Priority + Queues::Implementations).

+

Results

+

Figures NPG, NPM, and + NPL show the results for the native priority + queues and pb_ds 's priority queues in g++, msvc++, and + local, + respectively; Figures NBRG, NBRM, and NBRL shows the + results for the binary-heap based native priority queues and + pb_ds's pairing-heap priority queues in g++, msvc++, and + local, + respectively

+
+
+
+
+
no image
NPG: Native and pb ds priority queue push timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_vector- +std::priority_queue adapting std::vector
    2. +
  2. +n_pq_deque- +std::priority_queue adapting std::deque
    3. +
  3. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    4. +
  4. +rc_binomial_heap- +priority_queue + with Tag = rc_binomial_heap_tag +
    5. +
  5. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    6. +
  6. +binomial_heap- +priority_queue + with Tag = binomial_heap_tag +
    7. +
  7. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    8. +
+
+
+
+
+
+
+
+
+
+
no image
NPM: Native and pb ds priority queue push timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_deque- +std::priority_queue adapting std::deque
    2. +
  2. +rc_binomial_heap- +priority_queue + with Tag = rc_binomial_heap_tag +
    3. +
  3. +binary_heap- +priority_queue + with Tag = binary_heap_tag +
    4. +
  4. +binomial_heap- +priority_queue + with Tag = binomial_heap_tag +
    5. +
  5. +n_pq_vector- +std::priority_queue adapting std::vector
    6. +
  6. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    7. +
  7. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    8. +
+
+
+
+
+
+
+
+
+
+
no image
NPL: Native and pb ds priority queue push timing test - local
+
+
+
+
+
+
+
+
+
no image
NBRG: Native and pb ds pairing priority queue push timing test - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_vector- +std::priority_queue adapting std::vector
    2. +
  2. +n_pq_deque- +std::priority_queue adapting std::deque
    3. +
  3. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    4. +
  4. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    5. +
+
+
+
+
+
+
+
+
+
+
no image
NBRM: Native and pb ds pairing priority queue push timing test - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_pq_deque- +std::priority_queue adapting std::deque
    2. +
  2. +n_pq_vector- +std::priority_queue adapting std::vector
    3. +
  3. +pairing_heap- +priority_queue + with Tag = pairing_heap_tag +
    4. +
  4. +thin_heap- +priority_queue + with Tag = thin_heap_tag +
    5. +
+
+
+
+
+
+
+
+
+
+
no image
NBRL: Native and pb ds pairing priority queue push timing test - local
+
+
+
+
+

Observations

+

Pairing heaps (priority_queue with + Tag = pairing_heap_tag) + are the most suited for sequences of push and + pop operations of non-primitive types (e.g. +std::strings). (see also Priority Queue + Text push and pop Timing Test.) They are + less constrained than binomial heaps, e.g., and since + they are node-based, they outperform binary heaps. (See + Priority + Queue Random Integer push Timing Test for the case + of primitive types.)

+

The STL's priority queues do not seem to perform well in + this case: the std::vector implementation needs to + perform a logarithmic sequence of string operations for each + operation, and the deque implementation is possibly hampered by + its need to manipulate a relatively-complex type (deques + support a O(1) push_front, even though it is + not used by std::priority_queue.)

+

Priority-Queue + Performance Tests::Observations discusses this further and + summarizes.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_timing_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_timing_test_gcc.png new file mode 100644 index 000000000..8895f507c Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_timing_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_timing_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_timing_test_local.png new file mode 100644 index 000000000..da7297bff Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_timing_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_timing_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_timing_test_msvc.png new file mode 100644 index 000000000..ff39ca37d Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/priority_queue_text_push_timing_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/quadratic_probe_fn.html b/libstdc++-v3/doc/html/ext/pb_ds/quadratic_probe_fn.html new file mode 100644 index 000000000..00367dac8 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/quadratic_probe_fn.html @@ -0,0 +1,141 @@ + + + + + + + quadratic_probe_fn Interface + + + + +
+

quadratic_probe_fn Interface

+ +

A probe sequence policy using square increments.

+ +

Defined in: hash_policy.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+typename Size_Type 
+
+ 		+

Size type.

+ 		size_t
+ +

Public Types and + Constants

+ +

General Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+Size_Type
+
+ 		+

Size type.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + +
MethodDescription
+ 
+void
+  swap
+  (quadratic_probe_fn &other)
+
+ 		+

Swaps content.

+
+ +

Protected Methods

+ +

Offset Methods

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline size_type
+  operator()
+  (size_type i) const
+
+ 		+

Returns the i-th + offset from the hash value.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/random_int_find_find_timing_test_tree_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/random_int_find_find_timing_test_tree_gcc.png new file mode 100644 index 000000000..61962704f Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/random_int_find_find_timing_test_tree_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/random_int_find_find_timing_test_tree_local.png b/libstdc++-v3/doc/html/ext/pb_ds/random_int_find_find_timing_test_tree_local.png new file mode 100644 index 000000000..83105202a Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/random_int_find_find_timing_test_tree_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/random_int_find_find_timing_test_tree_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/random_int_find_find_timing_test_tree_msvc.png new file mode 100644 index 000000000..2206cef5a Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/random_int_find_find_timing_test_tree_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/range_invalidation_guarantee.html b/libstdc++-v3/doc/html/ext/pb_ds/range_invalidation_guarantee.html new file mode 100644 index 000000000..7bfba19e8 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/range_invalidation_guarantee.html @@ -0,0 +1,52 @@ + + + + + + + range_invalidation_guarantee Interface + + + + +
+

range_invalidation_guarantee Interface

+ +

Signifies an invalidation guarantee that includes all those + of its base, and additionally, that any range-type iterator + (including the returns of begin() and end()) is in the correct + relative positions to other range-type iterators as long as its + corresponding entry has not be erased, regardless of + modifications to the container object.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+point_invalidation_guarantee
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/rationale_null_node_updator.png b/libstdc++-v3/doc/html/ext/pb_ds/rationale_null_node_updator.png new file mode 100644 index 000000000..438748915 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/rationale_null_node_updator.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/rb_tree_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/rb_tree_tag.html new file mode 100644 index 000000000..2adbd09bf --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/rb_tree_tag.html @@ -0,0 +1,47 @@ + + + + + + + rb_tree_tag Interface + + + + +
+

rb_tree_tag Interface

+ +

Red-black tree data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+tree_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/rc_binomial_heap_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/rc_binomial_heap_tag.html new file mode 100644 index 000000000..1a4ba9f2e --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/rc_binomial_heap_tag.html @@ -0,0 +1,47 @@ + + + + + + + rc_binomial_heap_tag Interface + + + + +
+

rc_binomial_heap_tag Interface

+ +

Redundant-counter binomial-heap data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+priority_queue_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/references.html b/libstdc++-v3/doc/html/ext/pb_ds/references.html new file mode 100644 index 000000000..064e92464 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/references.html @@ -0,0 +1,258 @@ + + + + + + + References + + + + +
+

References

+ +
    +
  1. [abrahams97exception] Dave Abrahams, + STL Exception Handling Contract, + http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/1997/N1075.pdf
    2. + +
  2. [alexandrescu01modern] Andrei + Alexandrescu, Modern C++ Design: Generic Programming and + Design Patterns Applied, Addison-Wesley Publishing + Company, 2001
    3. + +
  3. [andrew04mtf] + K. Andrew and D. Gleich, "MTF, Bit, and COMB: A Guide to + Deterministic and Randomized Algorithms for the List Update + Problem"
    4. + +
  4. [austern00noset] Matthew Austern, "Why + You shouldn't use set - and What You Should Use + Instead", C++ Report, April, 2000
    5. + +
  5. [austern01htprop] Matthew Austern, "A + Proposal to Add Hashtables to the Standard Library", + http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2001/n1326l.html
    6. + +
  6. [austern98segmented] Matthew Austern, + "Segmented iterators and hierarchical algorithms", Generic + Programming, April 1998, pp. 80-90
    7. + +
  7. [boost_timer], + "Boost timer library", http://www.boost.org by Beman + Dawes
    8. + +
  8. [boost_pool], + "Boost pool library", http://www.boost.org by Stephen + Cleary
    9. + +
  9. [boost_type_traits], "Boost + type_traits library", http://www.boost.org by John + Maddock, Steve Cleary, et. al.
    10. + +
  10. [brodal96priority] Gerth Stolting + Brodal, Worst-case + efficient priority queues
    11. + +
  11. [bulka99efficient] D. Bulka, and D. + Mayhew, "Efficient C++ Programming Techniques.", + Addison-Wesley Publishing Company, Addison-Wesley, 1997
    12. + +
  12. [clrs2001] T. H. + Cormen, C. E., Leiserson, R. L. Rivest, C. and Stein, + "Introduction to Algorithms, 2nd ed.", MIT Press, 2001
    13. + +
  13. [dinkumware_stl], "Dinkumware C++ Library + Reference", http://www.dinkumware.com/htm_cpl/index.html
    14. + +
  14. [dubhashi98neg] D. Dubashi, and D. Ranjan, + "Balls and bins: A study in negative dependence.", Random + Structures and Algorithms 13, 2 (1998), 99-124
    15. + +
  15. [fagin79extendible] R. Fagin, J. + Nievergelt, N. Pippenger, and H. R. Strong, "Extendible + hashing - a fast access method for dynamic files", ACM Trans. + Database Syst. 4, 3 (1979), 315-344
    16. + +
  16. [filliatre2000ptset], J. C. + Filliatre, "Ptset: Sets of integers implemented as Patricia + trees", http://www.lri.fr/~filliatr/ftp/ocaml/misc/ptset.ml
    17. + +
  17. [fredman86pairing], M. L. Fredman, R + Sedgewick, D. D. Sleator, R. E. Tarjan, The + pairing heap: a new form of self-adjusting heap
    18. + +
  18. [gamma95designpatterns] E. Gamma, + R. Helm, R. Johnson, and J. Vlissides, "Design Patterns - + Elements of Reusable Object-Oriented Software", + Addison-Wesley Publishing Company, Addison-Wesley, 1995
    19. + +
  19. [garg86order] + A. K. Garg and C. C. Gotlieb, "Order-preserving key + transformations", Trans. Database Syst. 11, 2 (1986), + 213-234
    20. + +
  20. [hyslop02making] J. Hyslop, and H. + Sutter, "Making a real hash of things", C++ Report, May + 2002
    21. + +
  21. [jossutis01stl] N. M. Jossutis, "The C++ + Standard Library - A Tutorial and Reference", Addison-Wesley + Publishing Company, Addison-Wesley, 2001
    22. + +
  22. [kt99fat_heas] Haim Kaplan and Robert E. + Tarjan, New + Heap Data Structures
    23. + +
  23. [kleft00sets] + Klaus Kleft and Angelika Langer, "Are Set Iterators Mutable + or Immutable?", C/C++ Users Jornal, October 2000
    24. + +
  24. [knuth98sorting] D. E. Knuth, "The Art of + Computer Programming - Sorting and Searching", Addison-Wesley + Publishing Company, Addison-Wesley, 1998
    25. + +
  25. [liskov98data] B. Liskov, "Data abstraction + and hierarchy", SIGPLAN Notices 23, 5 (May 1998)
    26. + +
  26. [litwin80lh] W. + Litwin, "Linear hashing: A new tool for file and table + addressing", Proceedings of International Conference on Very + Large Data Bases (June 1980), pp. 212-223
    27. + +
  27. [maverik_lowerbounds] Maverik Woo, + + Deamortization - Part 2: Binomial Heaps
    28. + +
  28. [metrowerks_stl], "Metrowerks CodeWarrior + Pro 7 MSL C++ Reference Manual",
    29. + +
  29. [meyers96more] S. Meyers, "More Effective + C++: 35 New Ways to Improve Your Programs and Designs - 2nd + ed.", Addison-Wesley Publishing Company, Addison-Wesley, + 1996
    30. + +
  30. [meyers00nonmember] S. Meyers, "How + Non-Member Functions Improve Encapsulation", C/C++ Users + Journal, 2000
    31. + +
  31. [meyers01stl] + S. Meyers, "Effective STL: 50 Specific Ways to Improve Your + Use of the Standard Template Library", Addison-Wesley + Publishing Company, Addison-Wesley, 2001
    32. + +
  32. [meyers02both] S. Meyers, "Class Template, + Member Template - or Both?", C/C++ Users Journal, 2003
    33. + +
  33. [motwani95random] R. Motwani, and P. + Raghavan, "Randomized Algorithms", Cambridge University + Press
    34. + +
  34. [mscom] COM: Component Model Object + Technologies
    35. + +
  35. [musser95rationale], David R. Musser, + "Rationale for Adding Hash Tables to the C++ Standard + Template Library"
    36. + +
  36. [musser96stltutorial] D. R. Musser + and A. Saini, "STL Tutorial and Reference Guide", + Addison-Wesley Publishing Company, Addison-Wesley, 1996
    37. + +
  37. [nelson96stlpql] Mark Nelson, Priority + Queues and the STL, Dr. Dobbs Journal, January, 1996
    38. + +
  38. [okasaki98mereable] C. Okasaki and A. + Gill, "Fast mergeable integer maps", In Workshop on ML, pages + 77--86, September 1998. 95
    39. + +
  39. [sgi_stl] SGI, + "Standard Template Library Programmer's Guide", http://www.sgi.com/tech/stl
    40. + +
  40. [select_man] + select + man page.
    41. + +
  41. [sleator84amortized] D. D. Sleator + and R. E. Tarjan, "Amortized Efficiency of List Update + Problems", ACM Symposium on Theory of Computing, 1984
    42. + +
  42. [sleator85self] D. D. Sleator and R. E. + Tarjan, "Self-Adjusting Binary Search Trees", ACM Symposium + on Theory of Computing, 1985
    43. + +
  43. [stepanov94standard] A. A. Stepanov + and M. Lee", "The Standard Template Library"
    44. + +
  44. [stroustrup97cpp] Bjarne Stroustrup, + The C++ Programming Langugage -3rd ed., Addison-Wesley + Publishing Company,Reading, MA, USA, 1997
    45. + +
  45. [vandevoorde2002cpptemplates] + D. Vandevoorde, and N. M. Josuttis, "C++ Templates: The + Complete Guide", Addison-Wesley Publishing Company, + Addison-Wesley, 2002
    46. + +
  46. [wickland96thirty] C. A. Wickland, + "Thirty Years Among the Dead", National Psychological + Institute, Los Angeles, 1996,http://myweb.wvnet.edu/gsa00121/books/amongdead30.zip
    47. +
+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/resize_error.html b/libstdc++-v3/doc/html/ext/pb_ds/resize_error.html new file mode 100644 index 000000000..6aab88c15 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/resize_error.html @@ -0,0 +1,50 @@ + + + + + + +resize_error Interface + + + + +
+

resize_error Interface

+ +

A container cannot be resized.

+ +

Exception thrown when a size policy cannot supply an + adequate size for an external resize.

+ +

Defined in: exception.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+   resize_error
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/resize_policy_cd.png b/libstdc++-v3/doc/html/ext/pb_ds/resize_policy_cd.png new file mode 100644 index 000000000..338e33c15 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/resize_policy_cd.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/restoring_node_invariants.png b/libstdc++-v3/doc/html/ext/pb_ds/restoring_node_invariants.png new file mode 100644 index 000000000..33ba84bfe Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/restoring_node_invariants.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/sample_probe_fn.html b/libstdc++-v3/doc/html/ext/pb_ds/sample_probe_fn.html new file mode 100644 index 000000000..51dccce5c --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/sample_probe_fn.html @@ -0,0 +1,152 @@ + + + + + + + sample_probe_fn Interface + + + + +
+

sample_probe_fn Interface

+ +

A sample probe policy.

+ +

This class serves to show the interface a probe functor + needs to support.

+ +

Defined in: sample_probe_fn.hpp

+ +

Public Types and + Constants

+ +

General definitions.

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+size_t, e.g.
+
+ 		+

Size type.

+
+ +

Public Methods

+ +

Constructors, destructor, and + related.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  sample_probe_fn
+  ()
+
+ 		+

Default constructor.

+ +

Must be default constructable.

+
+ 
+  sample_probe_fn
+  (const sample_probe_fn &other)
+
+ 		+

Copy constructor.

+ +

Must be copy constructable.

+
+ 
+inline void
+  swap
+  (sample_probe_fn &other)
+
+ 		+

Swaps content.

+ +

Must be swappable (if there is such a word).

+
+ +

Protected Methods

+ +

Offset methods.

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline size_type
+  operator()
+  (const_key_reference r_key,
+    size_type i) const
+
+ 		+

Returns the i-th + offset from the hash value of some key r_key.

+ +

size_type is the size type on which the + functor operates.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/sample_range_hashing.html b/libstdc++-v3/doc/html/ext/pb_ds/sample_range_hashing.html new file mode 100644 index 000000000..85051873c --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/sample_range_hashing.html @@ -0,0 +1,172 @@ + + + + + + + sample_range_hashing Interface + + + + +
+

sample_range_hashing Interface

+ +

A sample range-hashing functor.

+ +

This class serves to show the interface a range-hashing + functor needs to support.

+ +

Defined in: sample_range_hashing.hpp

+ +

Public Types and + Constants

+ +

General definitions.

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+size_t, e.g.
+
+ 		+

Size type.

+
+ +

Public Methods

+ +

Constructors, destructor, and + related.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  sample_range_hashing
+  ()
+
+ 		+

Default constructor.

+ +

Must be default constructable.

+
+ 
+  sample_range_hashing
+  (const sample_range_hashing &other)
+
+ 		+

Copy constructor.

+ +

Must be copy constructable.

+
+ 
+inline void
+  swap
+  (sample_range_hashing &other)
+
+ 		+

Swaps content.

+ +

Must be swappable (if there is such a word).

+
+ +

Protected Methods

+ +

Notification methods.

+ + + + + + + + + + + + + +
MethodDescription
+ 
+void 
+  notify_resized
+  (size_type size)
+
+ 		+

Notifies the policy object that the container's size + has changed to size.

+
+ +

Operators.

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline size_type
+  operator()
+  (size_type hash) const
+
+ 		+

Transforms the hash value hash into a ranged-hash value.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/sample_ranged_hash_fn.html b/libstdc++-v3/doc/html/ext/pb_ds/sample_ranged_hash_fn.html new file mode 100644 index 000000000..834f49650 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/sample_ranged_hash_fn.html @@ -0,0 +1,171 @@ + + + + + + + sample_ranged_hash_fn Interface + + + + +
+

sample_ranged_hash_fn Interface

+ +

A sample ranged-hash functor.

+ +

This class serves to show the interface a ranged-hash + functor needs to support.

+ +

Defined in: sample_ranged_hash_fn.hpp

+ +

Public Types and + Constants

+ +

General definitions.

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+size_t, e.g.
+
+ 		+

Size type.

+
+ +

Public Methods

+ +

Constructors, destructor, and + related.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  sample_ranged_hash_fn
+  ()
+
+ 		+

Default constructor.

+ +

Must be default constructable.

+
+ 
+  sample_ranged_hash_fn
+  (const sample_ranged_hash_fn &other)
+
+ 		+

Copy constructor.

+ +

Must be copy constructable.

+
+ 
+inline void
+  swap
+  (sample_ranged_hash_fn &other)
+
+ 		+

Swaps content.

+ +

Must be swappable (if there is such a word).

+
+ +

Protected Methods

+ +

Notification methods.

+ + + + + + + + + + + + + +
MethodDescription
+ 
+void 
+  notify_resized
+  (size_type size)
+
+ 		+

Notifies the policy object that the container's size + has changed to size.

+
+ +

Operators.

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline size_type 
+  operator()
+  (const_key_reference r_key) const
+
+ 		+

Transforms r_key into + a position within the table.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/sample_ranged_probe_fn.html b/libstdc++-v3/doc/html/ext/pb_ds/sample_ranged_probe_fn.html new file mode 100644 index 000000000..ee1bc0664 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/sample_ranged_probe_fn.html @@ -0,0 +1,178 @@ + + + + + + + sample_ranged_probe_fn Interface + + + + +
+

sample_ranged_probe_fn Interface

+ +

A sample ranged-probe functor.

+ +

This class serves to show the interface a ranged-probe + functor needs to support.

+ +

Defined in: sample_ranged_probe_fn.hpp

+ +

Public Types and + Constants

+ +

General definitions.

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+size_t, e.g.
+
+ 		+

Size type.

+
+ +

Public Methods

+ +

Constructors, destructor, and + related.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  sample_ranged_probe_fn
+  ()
+
+ 		+

Default constructor.

+ +

Must be default constructable.

+
+ 
+  sample_ranged_probe_fn
+  (const sample_ranged_probe_fn &other)
+
+ 		+

Copy constructor.

+ +

Must be copy constructable.

+
+ 
+inline void
+  swap
+  (sample_ranged_probe_fn &other)
+
+ 		+

Swaps content.

+ +

Must be swappable (if there is such a word).

+
+ +

Protected Methods

+ +

Notification methods.

+ + + + + + + + + + + + + +
MethodDescription
+ 
+void 
+  notify_resized
+  (size_type size)
+
+ 		+

Notifies the policy object that the container's size + has changed to size.

+
+ +

Operators.

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline size_type 
+  operator()
+  (const_key_reference r_key,
+    size_t hash,
+    size_type i) const
+
+ 		+

Transforms the const key reference + r_key into the i-th position within the table. This + method is called for + each collision within the probe sequence.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/sample_resize_policy.html b/libstdc++-v3/doc/html/ext/pb_ds/sample_resize_policy.html new file mode 100644 index 000000000..61ff09ba0 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/sample_resize_policy.html @@ -0,0 +1,413 @@ + + + + + + + sample_resize_policy Interface + + + + +
+

sample_resize_policy Interface

+ +

A sample resize policy.

+ +

This class serves to show the interface a resize policy + needs to support.

+ +

Defined in: sample_resize_policy.hpp

+ +

Public Types and + Constants

+ +

General definitions.

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+size_t, e.g.
+
+ 		+

Size type.

+
+ +

Public Methods

+ +

Constructors, destructor, and + related.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  sample_resize_policy
+  ()
+
+ 		+

Default constructor.

+ +

Must be default constructable.

+
+ 
+  sample_range_hashing
+  (const sample_resize_policy &other)
+
+ 		+

Copy constructor.

+ +

Must be copy constructable.

+
+ 
+inline void
+  swap
+  (sample_resize_policy &other)
+
+ 		+

Swaps content.

+ +

Must be swappable (if there is such a word).

+
+ +

Protected Methods

+ +

Insert search + notifications.

+ +

Notifications called during an insert operation.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_insert_search_start
+  ()
+
+ 		+

Notifies a search started.

+
+ 
+inline void
+  notify_insert_search_collision
+  ()
+
+ 		+

Notifies a search encountered a collision.

+
+ 
+inline void
+  notify_insert_search_end
+  ()
+
+ 		+

Notifies a search ended.

+
+ +

Find search + notifications.

+ +

Notifications called during a find operation.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_find_search_start
+  ()
+
+ 		+

Notifies a search started.

+
+ 
+inline void
+  notify_find_search_collision
+  ()
+
+ 		+

Notifies a search encountered a collision.

+
+ 
+inline void
+  notify_find_search_end
+  ()
+
+ 		+

Notifies a search ended.

+
+ +

Erase search + notifications.

+ +

Notifications called during an insert operation.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_erase_search_start
+  ()
+
+ 		+

Notifies a search started.

+
+ 
+inline void
+  notify_erase_search_collision
+  ()
+
+ 		+

Notifies a search encountered a collision.

+
+ 
+inline void
+  notify_erase_search_end
+  ()
+
+ 		+

Notifies a search ended.

+
+ +

Content change + notifications.

+ +

Notifications called when the content of the table changes + in a way that can affect the resize policy.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_inserted
+  (size_type num_e)
+
+ 		+

Notifies an element was inserted.

+
+ 
+inline void
+  notify_erased
+  (size_type num_e)
+
+ 		+

Notifies an element was erased.

+
+ 
+void 
+  notify_cleared
+  ()
+
+ 		+

Notifies the table was cleared.

+
+ +

Size change + notifications.

+ +

Notifications called when the table changes size.

+ + + + + + + + + + + + + +
MethodDescription
+ 
+void
+  notify_resized
+  (size_type new_size)
+
+ 		+

Notifies the table was resized to new_size.

+
+ +

Queries.

+ +

Called to query whether/how to resize.

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline bool
+  is_resize_needed
+  () const
+
+ 		+

Queries whether a resize is needed.

+
+ 
+size_type
+  get_new_size
+  (size_type size, 
+    size_type num_used_e) const
+
+ 		+

Queries what the new size should be.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/sample_resize_trigger.html b/libstdc++-v3/doc/html/ext/pb_ds/sample_resize_trigger.html new file mode 100644 index 000000000..5c8173c8e --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/sample_resize_trigger.html @@ -0,0 +1,462 @@ + + + + + + + sample_resize_trigger Interface + + + + +
+

sample_resize_trigger Interface

+ +

A sample resize trigger policy.

+ +

This class serves to show the interface a trigger policy + needs to support.

+ +

Defined in: + sample_resize_trigger.hpp

+ +

Public Types and + Constants

+ +

General definitions.

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+size_t, e.g.
+
+ 		+

Size type.

+
+ +

Public Methods

+ +

Constructors, destructor, and + related.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  sample_resize_trigger
+  ()
+
+ 		+

Default constructor.

+ +

Must be default constructable.

+
+ 
+  sample_range_hashing
+  (const sample_resize_trigger &other)
+
+ 		+

Copy constructor.

+ +

Must be copy constructable.

+
+ 
+inline void
+  swap
+  (sample_resize_trigger &other)
+
+ 		+

Swaps content.

+ +

Must be swappable (if there is such a word).

+
+ +

Protected Methods

+ +

Insert search + notifications.

+ +

Notifications called during an insert operation.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_insert_search_start
+  ()
+
+ 		+

Notifies a search started.

+
+ 
+inline void
+  notify_insert_search_collision
+  ()
+
+ 		+

Notifies a search encountered a collision.

+
+ 
+inline void
+  notify_insert_search_end
+  ()
+
+ 		+

Notifies a search ended.

+
+ +

Find search + notifications.

+ +

Notifications called during a find operation.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_find_search_start
+  ()
+
+ 		+

Notifies a search started.

+
+ 
+inline void
+  notify_find_search_collision
+  ()
+
+ 		+

Notifies a search encountered a collision.

+
+ 
+inline void
+  notify_find_search_end
+  ()
+
+ 		+

Notifies a search ended.

+
+ +

Erase search + notifications.

+ +

Notifications called during an insert operation.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_erase_search_start
+  ()
+
+ 		+

Notifies a search started.

+
+ 
+inline void
+  notify_erase_search_collision
+  ()
+
+ 		+

Notifies a search encountered a collision.

+
+ 
+inline void
+  notify_erase_search_end
+  ()
+
+ 		+

Notifies a search ended.

+
+ +

Content change + notifications.

+ +

Notifications called when the content of the table changes + in a way that can affect the resize policy.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  notify_inserted
+  (size_type num_entries)
+
+ 		+

Notifies an element was inserted. the total number of + entries in the table is num_entries.

+
+ 
+inline void
+  notify_erased
+  (size_type num_entries)
+
+ 		+

Notifies an element was erased.

+
+ 
+void 
+  notify_cleared
+  ()
+
+ 		+

Notifies the table was cleared.

+
+ +

Size change + notifications.

+ +

Notifications called when the table changes size.

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+void
+  notify_resized
+  (size_type new_size)
+
+ 		+

Notifies the table was resized as a result of this + object's signifying that a resize is needed.

+
+ 
+void
+  notify_externally_resized
+  (size_type new_size)
+
+ 		+

Notifies the table was resized externally.

+
+ +

Queries.

+ +

Called to query whether/how to resize.

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline bool 
+  is_resize_needed
+  () const
+
+ 		+

Queries whether a resize is needed.

+
+ 
+inline bool
+  is_grow_needed
+  (size_type size, 
+    size_type num_entries) const
+
+ 		+

Queries whether a grow is needed.

+ +

This method is called only if this object indicated + resize is needed. The actual size of the table is size, and the number of entries in + it is num_entries.

+
+ +

Private Methods

+ +

Overrides.

+ + + + + + + + + + + + + +
MethodDescription
+ 
+virtual void
+  do_resize
+  (size_type new_size)
+
+ 		+

Resizes to new_size.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/sample_size_policy.html b/libstdc++-v3/doc/html/ext/pb_ds/sample_size_policy.html new file mode 100644 index 000000000..ebb14d30b --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/sample_size_policy.html @@ -0,0 +1,163 @@ + + + + + + + sample_size_policy Interface + + + + +
+

sample_size_policy Interface

+ +

A sample size policy.

+ +

This class serves to show the interface a size policy needs + to support.

+ +

Defined in: sample_size_policy.hpp

+ +

Public Types and + Constants

+ +

General definitions.

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+size_t, e.g.
+
+ 		+

Size type.

+
+ +

Public Methods

+ +

Constructors, destructor, and + related.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  sample_size_policy
+  ()
+
+ 		+

Default constructor.

+ +

Must be default constructable.

+
+ 
+  sample_range_hashing
+  (const sample_size_policy &other)
+
+ 		+

Copy constructor.

+ +

Must be copy constructable.

+
+ 
+inline void
+  swap
+  (sample_size_policy &other)
+
+ 		+

Swaps content.

+ +

Must be swappable (if there is such a word).

+
+ +

Protected Methods

+ +

Size methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline size_type
+  get_nearest_larger_size
+  (size_type size) const
+
+ 		+

Given a size size, + returns a size that is larger.

+
+ 
+inline size_type
+  get_nearest_smaller_size
+  (size_type size) const
+
+ 		+

Given a size size, + returns a size that is smaller.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/sample_tree_node_update.html b/libstdc++-v3/doc/html/ext/pb_ds/sample_tree_node_update.html new file mode 100644 index 000000000..aefd67056 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/sample_tree_node_update.html @@ -0,0 +1,193 @@ + + + + + + + sample_tree_node_update Interface + + + + +
+

sample_tree_node_update Interface

+ +

A sample node updater.

+ +

This class serves to show the interface a node update + functor needs to support.

+ +

Defined in: + sample_tree_node_update.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+class Const_Node_Iterator
+
+ 		+

Const node iterator type.

+ 		-
+ 
+class Node_Iterator
+
+ 		+

Node iterator type.

+ 		-
+ 
+class Cmp_Fn
+
+ 		+

Comparison functor.

+ 		-
+ 
+class Allocator
+
+ 		+

Allocator type.

+ 		-
+ +

Public Types and + Constants

+ +

Metadata definitions.

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+metadata_type
+
+ 		+ 
+size_t
+
+ 		+

Metadata type.

+ +

This can be any type; size_t is merely an example.

+
+ +

Protected Methods

+ +

Conclassors, declassor, and + related.

+ + + + + + + + + + + + + +
MethodDescription
+ 
+  sample_tree_node_update
+  ()
+
+ 		+

Default constructor.

+ +

Must be default constructable.

+
+ +

Operators.

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  operator()
+  (node_iterator node_it,
+    const_node_iterator end_nd_it) const
+
+ 		+

Updates the rank of a node through a node_iterator node_it; end_nd_it is the end node + iterator.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/sample_trie_e_access_traits.html b/libstdc++-v3/doc/html/ext/pb_ds/sample_trie_e_access_traits.html new file mode 100644 index 000000000..a46c91b1d --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/sample_trie_e_access_traits.html @@ -0,0 +1,231 @@ + + + + + + + sample_trie_e_access_traits Interface + + + + +
+

sample_trie_e_access_traits Interface

+ +

A sample trie element-access traits.

+ +

This class serves to show the interface an element- access + traits class needs to support.

+ +

Defined in: + sample_trie_e_access_traits.hpp

+ +

Public Types and + Constants

+ +

General definitions.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+size_t, e.g.
+
+ 		+

Size type.

+
+ 
+key_type
+
+ 		+ 
+std::string, e.g.
+
+ 		+

Key type.

+
+ 
+const_key_reference
+
+ 		+ 
+const string &, e.g.
+
+ 		+

Const key reference type.

+
+ +

Element definitions.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+const_iterator
+
+ 		+ 
+string::const_iterator, e.g.
+
+ 		+

Element const iterator type.

+
+ 
+e_type
+
+ 		+ 
+char, e.g.
+
+ 		+

Element type.

+
+ 
+max_size
+
+ 		+ 
+4, e.g.
+
+ 		+

Number of distinct elements.

+
+ +

Public Methods

+ +

Access methods.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline static const_iterator
+  begin
+  (const_key_reference r_key)
+
+ 		+

Returns a const_iterator to + the first element of r_key.

+
+ 
+inline static const_iterator
+  end
+  (const_key_reference r_key)
+
+ 		+

Returns a const_iterator to + the after-last element of r_key.

+
+ 
+inline static size_type
+  e_pos
+  (e_type e)
+
+ 		+

Maps an element to a + position.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/sample_trie_node_update.html b/libstdc++-v3/doc/html/ext/pb_ds/sample_trie_node_update.html new file mode 100644 index 000000000..61b6b407f --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/sample_trie_node_update.html @@ -0,0 +1,194 @@ + + + + + + + sample_trie_node_update Interface + + + + +
+

sample_trie_node_update Interface

+ +

A sample node updater.

+ +

This class serves to show the interface a node update + functor needs to support.

+ +

Defined in: + sample_trie_node_update.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+class Const_Node_Iterator
+
+ 		+

Const node iterator type.

+ 		-
+ 
+class Node_Iterator
+
+ 		+

Node iterator type.

+ 		-
+ 
+class E_Access_Traits
+
+ 		+

Comparison functor.

+ 		-
+ 
+class Allocator
+
+ 		+

Allocator type.

+ 		-
+ +

Public Types and + Constants

+ +

Metadata definitions.

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+metadata_type
+
+ 		+ 
+size_t
+
+ 		+

Metadata type.

+ +

This can be any type; size_t is merely an example.

+
+ +

Protected Methods

+ +

Conclassors, declassor, and + related.

+ + + + + + + + + + + + + +
MethodDescription
+ 
+  sample_trie_node_update
+  ()
+
+ 		+

Default constructor.

+ +

Must be default constructable.

+
+ +

Operators.

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  operator()
+  (node_iterator node_it,
+    const_node_iterator end_nd_it) const
+
+ 		+

Updates the rank of a node through a node_iterator node_it; end_nd_it is the end node + iterator.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/sample_update_policy.html b/libstdc++-v3/doc/html/ext/pb_ds/sample_update_policy.html new file mode 100644 index 000000000..8a286c74c --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/sample_update_policy.html @@ -0,0 +1,178 @@ + + + + + + + sample_update_policy Interface + + + + +
+

sample_update_policy Interface

+ +

A sample list-update policy.

+ +

This class serves to show the interface a list update + functor needs to support.

+ +

Defined in: sample_update_policy.hpp

+ +

Public Methods

+ +

Constructors, destructor, and + related.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  sample_update_policy
+  ()
+
+ 		+

Default constructor.

+ +

Must be default constructable.

+
+ 
+  sample_update_policy
+  (const sample_update_policy &other)
+
+ 		+

Copy constructor.

+ +

Must be copy constructable.

+
+ 
+inline void
+  swap
+  (sample_update_policy &other)
+
+ 		+

Swaps content.

+ +

Must be swappable (if there is such a word).

+
+ +

Protected Types and + Constants

+ +

Metadata definitions.

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+metadata_type
+
+ 		+ 
+Some metadata type.
+
+ 		+

Metadata on which this functor operates.

+ +

The class must declare the metadata + type on which it operates; the list-update based + containers will append to each node an object of this + type.

+
+ +

Protected Methods

+ +

Metadata operations.

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+metadata_type
+  operator()
+  () const
+
+ 		+

Creates a metadata object.

+ +

A list-update based container object will call this + method to create a metadata type when a node is + created.

+
+ 
+bool 
+  operator()
+  (metadata_reference r_data) const
+
+ 		+

Decides whether a metadata object should be moved to + the front of the list. A list-update based containers + object will call this method to decide whether to move a + node to the front of the list. The method should return + true if the node should be moved to the + front of the list.

+ +

metadata_reference is a reference to a + metadata_type.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/simple_list.png b/libstdc++-v3/doc/html/ext/pb_ds/simple_list.png new file mode 100644 index 000000000..9a05d3f5e Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/simple_list.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/splay_tree_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/splay_tree_tag.html new file mode 100644 index 000000000..3e6a64b1c --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/splay_tree_tag.html @@ -0,0 +1,47 @@ + + + + + + + splay_tree_tag Interface + + + + +
+

splay_tree_tag Interface

+ +

Splay tree data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+tree_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/string_trie_e_access_traits.html b/libstdc++-v3/doc/html/ext/pb_ds/string_trie_e_access_traits.html new file mode 100644 index 000000000..4ce9e864a --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/string_trie_e_access_traits.html @@ -0,0 +1,400 @@ + + + + + + + string_trie_e_access_traits Interface + + + + +
+

string_trie_e_access_traits Interface

+ +

Element access traits for string types.

+ +

Defined in: trie_policy.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+class String 
+
+ 		+

String type.

+ 		std::string
+ 
+typename String::value_type Min_E_Val 
+
+ 		+

Minimal element.

+ 		SCHAR_MIN
+ 
+typename String::value_type Max_E_Val 
+
+ 		+

Maximal element.

+ 		SCHAR_MAX
+ 
+bool Reverse 
+
+ 		+

Indicates whether reverse iteration should be + used.

+ 		false
+ 
+class Allocator 
+
+ 		+

Allocator type.

+ 		+ 
+std::allocator<char>
+
+
+ +

Public Types and + Constants

+ +

General Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+typename Allocator::size_type
+
+ 		+

Size type.

+
+ +

Key-Type Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+key_type
+
+ 		+ 
+String
+
+ 		+

Key type.

+
+ 
+const_key_reference
+
+ 		+ 
+typename Allocator::template rebind<
+    key_type>::other::const_reference
+
+ 		+

Const key reference type.

+
+ +

Element-Type + Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+reverse
+
+ 		+ 
+Reverse
+
+ 		+

Reverse + iteration indicator.

+
+ 
+const_iterator
+
+ 		+ 
+typename __gnu_pbds::detail::__conditional_type<
+    Reverse,
+    typename String::const_reverse_iterator,
+    typename String::const_iterator>::__type
+
+ 		+

Element const iterator type.

+
+ 
+e_type
+
+ 		+ 
+typename std::iterator_traits<const_iterator>::value_type
+
+ 		+

Element type.

+
+ 
+min_e_val
+
+ 		+ 
+Min_E_Val
+
+ 		+

Minimal element.

+
+ 
+max_e_val
+
+ 		+ 
+Max_E_Val
+
+ 		+

Maximal element.

+
+ 
+max_size
+
+ 		+ 
+max_e_val - min_e_val + 1
+
+ 		+

Number of distinct elements.

+
+ +

Public Methods

+ +

Access Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline static const_iterator
+  begin
+  (const_key_reference r_key)
+
+ 		+

Returns a const_iterator to + the first element of r_key.

+
+ 
+inline static const_iterator
+  end
+  (const_key_reference r_key)
+
+ 		+

Returns a const_iterator to + the after-last element of r_key.

+
+ 
+inline static size_type
+  e_pos
+  (e_type e)
+
+ 		+

Maps an eelement to a + position.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tests.html b/libstdc++-v3/doc/html/ext/pb_ds/tests.html new file mode 100644 index 000000000..ab5d54bb4 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/tests.html @@ -0,0 +1,24 @@ + + + + + + + Tests + + + + +
+

Tests

+ +

Associative-Container Tests + describes tests for associative containers; Priority-Queue Tests describes tests for + priority queues.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_hash_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_hash_gcc.png new file mode 100644 index 000000000..59247ec6a Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_hash_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_hash_local.png b/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_hash_local.png new file mode 100644 index 000000000..d85980f30 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_hash_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_hash_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_hash_msvc.png new file mode 100644 index 000000000..227164568 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_hash_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_tree_like_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_tree_like_gcc.png new file mode 100644 index 000000000..8b6c4f0f0 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_tree_like_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_tree_like_local.png b/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_tree_like_local.png new file mode 100644 index 000000000..b7fdc4746 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_tree_like_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_tree_like_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_tree_like_msvc.png new file mode 100644 index 000000000..dc82a4e7e Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/text_find_timing_test_tree_like_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/thin_heap_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/thin_heap_tag.html new file mode 100644 index 000000000..c44189664 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/thin_heap_tag.html @@ -0,0 +1,47 @@ + + + + + + + thin_heap_tag Interface + + + + +
+

thin_heap_tag Interface

+ +

Thin heap data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+priority_queue_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree.html b/libstdc++-v3/doc/html/ext/pb_ds/tree.html new file mode 100644 index 000000000..3202a6e9f --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/tree.html @@ -0,0 +1,516 @@ + + + + + + + tree Interface + + + + +
+

tree Interface

+ +

A concrete basic tree-based associative container.

+ +

Defined in: assoc_container.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+typename Key
+
+ 		+

Key type.

+ 		-
+ 
+typename Mapped
+
+ 		+

Mapped type.

+ 		-
+ 
+class Cmp_Fn 
+
+ 		+

Comparison functor.

+ 		+ 
+std::less<Key>
+
+
+ 
+class Tag 
+
+ 		+

Mapped-structure tag.

+ 		rb_tree_tag
+ 
+template< 
+  typename Const_Node_Iterator, 
+  typename Node_Iterator, 
+  class Cmp_Fn_, 
+  typename Allocator_>
+class Node_Update 
+
+ 		+

Node updater type.

+ +

Design::Tree-Based + Containers::Node Invariants explains this + concept.

+ 		null_tree_node_update
+ 
+class Allocator 
+
+ 		+

Allocator type.

+ 		+ 
+std::allocator<char>
+
+
+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+basic_tree
+
+ 		+

public

+
+ +

Public Types and + Constants

+ +

Policy Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+cmp_fn
+
+ 		+ 
+Cmp_Fn
+
+ 		+

Comparison functor type.

+
+ +

Iterator Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+const_node_iterator
+
+ 		+ 
+const_node_iterator
+
+ 		+

Const node iterator.

+
+ 
+node_iterator
+
+ 		+ 
+node_iterator
+
+ 		+

Node iterator.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  tree
+  ()
+
+ 		+

Default constructor.

+
+ 
+  tree
+  (const cmp_fn &r_cmp_fn)
+
+ 		+

Constructor taking some policy objects. r_cmp_fn will be copied by the + Cmp_Fn object of the + container object.

+
+ 
+template<
+    class It>
+  tree
+  (It first_it, 
+    It last_it)
+
+ 		+

Constructor taking iterators to a range of + value_types. The value_types between first_it and last_it will be inserted into the + container object.

+
+ 
+template<
+    class It>
+  tree
+  (It first_it, 
+    It last_it,
+    const cmp_fn &r_cmp_fn)
+
+ 		+

Constructor taking iterators to a range of value_types + and some policy objects The value_types between + first_it and + last_it will be inserted + into the container object. r_cmp_fn will be copied by the + cmp_fn object of the + container object.

+
+ 
+  tree
+  (const tree &other)
+
+ 		+

Copy constructor.

+
+ 
+virtual 
+  ~tree
+  ()
+
+ 		+

Destructor.

+
+ 
+tree &
+  operator=
+  (const tree &other)
+
+ 		+

Assignment operator.

+
+ 
+void
+  swap
+  (tree &other)
+
+ 		+

Swaps content.

+
+ +

Policy Access Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+cmp_fn &
+  get_cmp_fn
+  ()
+
+ 		+

Access to the cmp_fn object.

+
+ 
+const cmp_fn &
+  get_cmp_fn
+  () const
+
+ 		+

Const access to the cmp_fn object.

+
+ +

Node-Iteration Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+node_iterator
+  node_begin
+  ()
+
+ 		+

Returns a node_iterator + corresponding to the node at the root of the tree.

+
+ 
+const_node_iterator
+  node_begin
+  () const
+
+ 		+

Returns a const_node_iterator + corresponding to the node at the root of the tree.

+
+ 
+node_iterator
+  node_end
+  ()
+
+ 		+

Returns a node_iterator + corresponding to a node just after a leaf of the + tree.

+
+ 
+const_node_iterator
+  node_end
+  () const
+
+ 		+

Returns a const_node_iterator + corresponding to a node just after a leaf of the + tree.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_based_containers.html b/libstdc++-v3/doc/html/ext/pb_ds/tree_based_containers.html new file mode 100644 index 000000000..63c7c7482 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/tree_based_containers.html @@ -0,0 +1,358 @@ + + + + + + + Tree-Based Containers + + + + +
+

Tree Design

+ +

Overview

+ +

The tree-based container has the following declaration:

+ 
+template<
+    typename Key,
+    typename Mapped,
+    typename Cmp_Fn = std::less<Key>,
+    typename Tag = rb_tree_tag,
+    template<
+        typename Const_Node_Iterator,
+        typename Node_Iterator,
+        typename Cmp_Fn_,
+        typename Allocator_>
+    class Node_Update = null_tree_node_update,
+    typename Allocator = std::allocator<char> >
+class tree;
+
+ +

The parameters have the following meaning:

+ +
    +
  1. Key is the key type.
    2. + +
  2. Mapped is the mapped-policy.
    3. + +
  3. Cmp_Fn is a key comparison functor
    4. + +
  4. Tag specifies which underlying data structure + to use.
    5. + +
  5. Node_Update is a policy for updating node + invariants. This is described in Node + Invariants.
    6. + +
  6. Allocator is an allocator + type.
    7. +
+ +

The Tag parameter specifies which underlying + data structure to use. Instantiating it by rb_tree_tag, splay_tree_tag, or + ov_tree_tag, + specifies an underlying red-black tree, splay tree, or + ordered-vector tree, respectively; any other tag is illegal. + Note that containers based on the former two contain more types + and methods than the latter (e.g., + reverse_iterator and rbegin), and different + exception and invalidation guarantees.

+ +

Node + Invariants

+ +

Consider the two trees in Figures Some node invariants A and B. The first + is a tree of floats; the second is a tree of pairs, each + signifying a geometric line interval. Each element in a tree is refered to as a node of the tree. Of course, each of + these trees can support the usual queries: the first can easily + search for 0.4; the second can easily search for + std::make_pair(10, 41).

+ +

Each of these trees can efficiently support other queries. + The first can efficiently determine that the 2rd key in the + tree is 0.3; the second can efficiently determine + whether any of its intervals overlaps + std::make_pair(29,42) (useful in geometric + applications or distributed file systems with leases, for + example). (See tree_order_statistics.cc + and tree_intervals.cc + for examples.) It should be noted that an std::set can + only solve these types of problems with linear complexity.

+ +

In order to do so, each tree stores some metadata in + each node, and maintains node invariants clrs2001]. The first stores in + each node the size of the sub-tree rooted at the node; the + second stores at each node the maximal endpoint of the + intervals at the sub-tree rooted at the node.

+ +
+
+ +
Some node invariants.
+ +

Supporting such trees is difficult for a number of + reasons:

+ +
    +
  1. There must be a way to specify what a node's metadata + should be (if any).
    2. + +
  2. Various operations can invalidate node invariants. + E.g., Figure Invalidation of node + invariants shows how a right rotation, performed on A, + results in B, with nodes x and y having + corrupted invariants (the grayed nodes in C); Figure Invalidation of node + invariants shows how an insert, performed on D, results + in E, with nodes x and y having corrupted + invariants (the grayed nodes in F). It is not feasible to + know outside the tree the effect of an operation on the nodes + of the tree.
    3. + +
  3. The search paths of standard associative containers are + defined by comparisons between keys, and not through + metadata.
    4. + +
  4. It is not feasible to know in advance which methods trees + can support. Besides the usual find method, the + first tree can support a find_by_order method, while + the second can support an overlaps method.
    5. +
+ +
no image
+ +
Invalidation of node invariants.
+ +

These problems are solved by a combination of two means: + node iterators, and template-template node updater + parameters.

+ +

Node Iterators

+ +

Each tree-based container defines two additional iterator + types, const_node_iterator + and node_iterator. + These iterators allow descending from a node to one of its + children. Node iterator allow search paths different than those + determined by the comparison functor. tree + supports the methods:

+ 
+    const_node_iterator
+    node_begin() const;
+
+    node_iterator
+    node_begin();
+
+    const_node_iterator
+    node_end() const;
+
+    node_iterator
+    node_end(); 
+
+ +

The first pairs return node iterators corresponding to the + root node of the tree; the latter pair returns node iterators + corresponding to a just-after-leaf node.

+ +

Node Updater + (Template-Template) Parameters

+ +

The tree-based containers are parametrized by a + Node_Update template-template parameter. A tree-based + container instantiates Node_Update to some + node_update class, and publicly + subclasses node_update. Figure + A tree and its update + policy shows this scheme, as well as some predefined + policies (which are explained below).

+ +
no image
+ +
A tree and its update policy.
+ +

node_update (an instantiation of + Node_Update) must define metadata_type as + the type of metadata it requires. For order statistics, + e.g., metadata_type might be size_t. + The tree defines within each node a metadata_type + object.

+ +

node_update must also define the following method + for restoring node invariants:

+ 
+    void 
+    operator()(node_iterator nd_it, const_node_iterator end_nd_it)
+
+ +

In this method, nd_it is a node_iterator + corresponding to a node whose A) all descendants have valid + invariants, and B) its own invariants might be violated; + end_nd_it is a const_node_iterator + corresponding to a just-after-leaf node. This method should + correct the node invariants of the node pointed to by + nd_it. For example, say node x in Figure + Restoring node + invariants-A has an invalid invariant, but its' children, + y and z have valid invariants. After the + invocation, all three nodes should have valid invariants, as in + Figure Restoring node + invariants-B.

+ +
no image
+ +
Invalidation of node invariants.
+ +

When a tree operation might invalidate some node invariant, + it invokes this method in its node_update base to + restore the invariant. For example, Figure Insert update sequence diagram shows + an insert operation (point A); the tree performs some + operations, and calls the update functor three times (points B, + C, and D). (It is well known that any insert, + erase, split or join, can restore + all node invariants by a small number of node invariant updates + [clrs2001].)

+ +
+
+ +
Insert update sequence diagram.
+ +

To complete the description of the scheme, three questions + need to be answered:

+ +
    +
  1. How can a tree which supports order statistics define a + method such as find_by_order?
    2. + +
  2. How can the node updater base access methods of the + tree?
    3. + +
  3. How can the following cyclic dependency be resolved? + node_update is a base class of the tree, yet it + uses node iterators defined in the tree (its child).
    4. +
+ +

The first two questions are answered by the fact that + node_update (an instantiation of + Node_Update) is a public base class + of the tree. Consequently:

+ +
    +
  1. Any public methods of node_update are + automatically methods of the tree [alexandrescu01modern]. + Thus an order-statistics node updater, tree_order_statistics_node_update + defines the find_by_order method; any tree + instantiated by this policy consequently supports this method + as well.
    2. + +
  2. In C++, if a base class declares a method as + virtual, it is virtual in its + subclasses. If node_update needs to access one of + the tree's methods, say the member function end, it simply + declares that method as virtual + abstract.
    3. +
+ +

The cyclic dependency is solved through template-template + parameters. Node_Update is parametrized by the tree's node iterators, its comparison + functor, and its allocator type. Thus, + instantiations of Node_Update have all information required.

+ +

pb_ds assumes that constructing a metadata object and modifying it + are exception free. Suppose that during some method, say + insert, a metadata-related operation + (e.g., changing the value of a metadata) throws an + exception. Ack! Rolling back the method is unusually complex.

+ +

In Interface::Concepts::Null + Policy Classes a distinction was made between redundant + policies and null policies. Node invariants show a + case where null policies are required.

+ +

Assume a regular tree is required, one which need not + support order statistics or interval overlap queries. + Seemingly, in this case a redundant policy - a policy which + doesn't affect nodes' contents would suffice. This, would lead + to the following drawbacks:

+ +
    +
  1. Each node would carry a useless metadata object, wasting + space.
    2. + +
  2. The tree cannot know if its Node_Update policy + actually modifies a node's metadata (this is halting + reducible). In Figure Useless update path , + assume the shaded node is inserted. The tree would have to + traverse the useless path shown to the root, applying + redundant updates all the way.
    3. +
+ +
no image
+ +
Useless update path.
+ +

A null policy class, null_tree_node_update + solves both these problems. The tree detects that node + invariants are irrelevant, and defines all accordingly.

+ +

Additional + Methods

+ +

Tree-based containers support split and join methods. + It is possible to split a tree so that it passes + all nodes with keys larger than a given key to a different + tree. These methods have the following advantages over the + alternative of externally inserting to the destination + tree and erasing from the source tree:

+ +
    +
  1. These methods are efficient - red-black trees are split + and joined in poly-logarithmic complexity; ordered-vector + trees are split and joined at linear complexity. The + alternatives have super-linear complexity.
    2. + +
  2. Aside from orders of growth, these operations perform + few allocations and de-allocations. For red-black trees, allocations are not performed, + and the methods are exception-free.
    3. +
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_node_iterator.html b/libstdc++-v3/doc/html/ext/pb_ds/tree_node_iterator.html new file mode 100644 index 000000000..ba09b5b4d --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/tree_node_iterator.html @@ -0,0 +1,143 @@ + + + + + + + tree::node_iterator Interface + + + + +
+

tree::node_iterator + Interface

+ +

Node iterator.

+ +

This is an iterator to an iterator - it + iterates over nodes, and de-referencing it returns one of the + tree's iterators

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+tree::const_node_iterator
+
+ 		+

public

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline 
+  node_iterator
+  ()
+
+ 		+

Default constructor.

+
+ +

Access Methods

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline container_base::iterator
+  operator*
+  () const
+
+ 		+

Access.

+
+ +

Movement Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline node_iterator
+  get_l_child
+  () const
+
+ 		+

Returns the node iterator associated with the left + node.

+
+ 
+inline node_iterator
+  get_r_child
+  () const
+
+ 		+

Returns the node iterator associated with the right + node.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_node_updator_policy_cd.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_node_updator_policy_cd.png new file mode 100644 index 000000000..5cae5781a Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_node_updator_policy_cd.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_node_update.html b/libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_node_update.html new file mode 100644 index 000000000..f4345531f --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_node_update.html @@ -0,0 +1,678 @@ + + + + + + + tree_order_statistics_node_update Interface + + + + +
+

tree_order_statistics_node_update Interface

+ +

Functor updating ranks of entrees.

+ +

Defined in: tree_policy.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+class Const_Node_Iterator
+
+ 		+

Const node iterator type.

+ 		-
+ 
+class Node_Iterator
+
+ 		+

Node iterator type.

+ 		-
+ 
+class Cmp_Fn
+
+ 		+

Comparison functor.

+ 		-
+ 
+class Allocator
+
+ 		+

Allocator type.

+ 		-
+ +

Public Types and + Constants

+ +

Policy Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+cmp_fn
+
+ 		+ 
+Cmp_Fn
+
+ 		+

Allocator + type.

+
+ 
+allocator
+
+ 		+ 
+Allocator
+
+ 		+

Allocator + type.

+
+ +

General Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+typename allocator::size_type
+
+ 		+

Size type.

+
+ +

Key-type Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+key_type
+
+ 		+ 
+The instantiating container's key type.
+
+ 		+

Key type.

+
+ 
+const_key_reference
+
+ 		+ 
+The instantiating container's const key reference type.
+
+ 		+

Const key reference.

+
+ +

Metadata-Type + Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+metadata_type
+
+ 		+ 
+size_type
+
+ 		+

Metadata type.

+
+ +

Iterator Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+const_node_iterator
+
+ 		+ 
+Const_Node_Iterator
+
+ 		+

Const node iterator type.

+
+ 
+node_iterator
+
+ 		+ 
+Node_Iterator
+
+ 		+

Node iterator type.

+
+ 
+const_iterator
+
+ 		+ 
+typename const_node_iterator::value_type
+
+ 		+

Const iterator type.

+
+ 
+iterator
+
+ 		+ 
+typename node_iterator::value_type
+
+ 		+

Iterator type.

+
+ +

Public Methods

+ +

Find-Type Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline const_iterator
+  find_by_order
+  (size_type order) const
+
+ 		+

Finds an entry by order. Returns a const_iterator to + the entry with the order order, or a const_iterator to + the container object's end if order is at least the size of the + container object.

+
+ 
+inline iterator
+  find_by_order
+  (size_type order)
+
+ 		+

Finds an entry by order. Returns an iterator to the entry + with the order order, or + an iterator to + the container object's end if order is at least the size of the + container object.

+
+ 
+inline size_type
+  order_of_key
+  (const_key_reference r_key) const
+
+ 		+

Returns the order of a key within a sequence. For + example, if r_key is the + smallest key, this method will return 0; if r_key is a key between the smallest + and next key, this method will return 1; if r_key is a key larger than the + largest key, this method will return the size of r_c.

+
+ +

Protected Types and + Constants

+ +

Value-type + Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+const_reference
+
+ 		+ 
+The instantiating container's const reference  type.
+
+ 		+

Const reference to the container's value-type.

+
+ 
+const_pointer
+
+ 		+ 
+The instantiating container's const pointer  type.
+
+ 		+

Const pointer to the container's value-type.

+
+ 
+const_metadata_reference
+
+ 		+ 
+typename Allocator::template rebind<
+    metadata_type>::other::const_reference
+
+ 		+

Const metadata reference.

+
+ 
+metadata_reference
+
+ 		+ 
+typename Allocator::template rebind<
+    metadata_type>::other::reference
+
+ 		+

Metadata reference.

+
+ +

Protected Methods

+ +

Operators

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  operator()
+  (node_iterator node_it,
+    const_node_iterator end_nd_it) const
+
+ 		+

Updates the rank of a node through a node_iterator + node_it; end_nd_it is the end node iterator.

+
+ +

Constructors, destructor, and + related

+ + + + + + + + + + + + + +
MethodDescription
+ 
+virtual 
+  ~tree_order_statistics_node_update
+  ()
+
+ 		+

Destructor.

+
+ +

Private Methods

+ +

Overrides

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+virtual const_node_iterator
+  node_begin
+  () const = 0
+
+ 		+

Returns the const_node_iterator + associated with the tree's root node.

+
+ 
+virtual node_iterator
+  node_begin
+  () = 0
+
+ 		+

Returns the node_iterator + associated with the tree's root node.

+
+ 
+virtual const_node_iterator
+  node_end
+  () const = 0
+
+ 		+

Returns the const_node_iterator + associated with a just-after leaf node.

+
+ 
+virtual node_iterator
+  node_end
+  () = 0
+
+ 		+

Returns the node_iterator + associated with a just-after leaf node.

+
+ 
+virtual cmp_fn &
+  get_cmp_fn
+  () = 0
+
+ 		+

Access to the cmp_fn object.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_timing_test.html new file mode 100644 index 000000000..ef811613e --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_timing_test.html @@ -0,0 +1,118 @@ + + + + + +Tree Order Statistics Timing Test + + + +
+

Tree Order-Statistics Timing Test

+

Description

+

This test creates a container, inserts random integers into + the the container, and then checks the order-statistics of the + container's values. (If the container is one of pb_ds + 's trees, it does this with the order_of_key method of + tree_order_statistics_node_update + ; otherwise, it uses the find method and + std::distance .) It measures the average time for such + queries as a function of the number of values inserted.

+

(The test was executed with tree_order_statistics_timing_test + 200 200 2100)

+

Purpose

+

The test checks the performance difference of policies based + on node-invariant as opposed to a external functions. (see + Design::Associative + Containers::Tree-Based Containers::Node Invariants .)

+

Results

+

Figures NTG, NTM, and + NTL show the results for the native and + tree-based containers in g++, msvc++, and + local, + respectively.

+
+
+
+
+
no image
NTG: Native and tree-based container order-statistics queries - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_set- +std::set
    2. +
  2. +splay_tree_ost_set- +tree + with Tag = splay_tree_tag +, and Node_Update = tree_order_statistics_node_update +
    3. +
  3. +rb_tree_ost_set- +tree + with Tag = rb_tree_tag +, and Node_Update = tree_order_statistics_node_update +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NTM: Native and tree-based container order-statistics queries - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_set- +std::set
    2. +
  2. +splay_tree_ost_set- +tree + with Tag = splay_tree_tag +, and Node_Update = tree_order_statistics_node_update +
    3. +
  3. +rb_tree_ost_set- +tree + with Tag = rb_tree_tag +, and Node_Update = tree_order_statistics_node_update +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NTL: Native and tree-based container order-statistics queries - local
+
+
+
+
+

Observations

+

In this test, the native red-black tree can support + order-statistics queries only externally, by performing a + find (alternatively, lower_bound or + upper_bound ) and then using std::distance . + This is clearly linear, and it is not that surprising that the + cost is high.

+

pb_ds 's tree-based containers use in this test the + order_of_key method of tree_order_statistics_node_update. + This method has only linear complexity in the length of the + root-node path. Unfortunately, the average path of a splay tree + (tree + with Tag = splay_tree_tag ) can + be higher than logarithmic; the longest path of a red-black + tree (tree + with Tag = rb_tree_tag ) is + logarithmic in the number of elements. Consequently, the splay + tree has worse performance than the red-black tree.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_timing_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_timing_test_gcc.png new file mode 100644 index 000000000..bdb00d07a Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_timing_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_timing_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_timing_test_local.png new file mode 100644 index 000000000..2b921743f Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_timing_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_timing_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_timing_test_msvc.png new file mode 100644 index 000000000..76dcbee44 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_order_statistics_timing_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_random_int_find_find_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/tree_random_int_find_find_timing_test.html new file mode 100644 index 000000000..c34354f3e --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/tree_random_int_find_find_timing_test.html @@ -0,0 +1,160 @@ + + + + + +Tree Text Find Timing Test + + + +
+

Tree-Based and Trie-Based Text find Find Timing + Test

+

Description

+

This test inserts a number of values with keys from an + arbitrary text ([wickland96thirty]) into + a container, then performs a series of finds using + find. It measures the average time for find + as a function of the number of values inserted.

+

(The test was executed with text_find_timing_test + thirty_years_among_the_dead_preproc.txt 200 200 2100)

+

Purpose

+

The test checks the effect of different underlying + data structures.

+

Results

+

Figures NTTG, NTTM, + and NTTL show the results for the native, + tree-based, and trie-based types in g++, local, and + local, + respectively.

+
+
+
+
+
no image
NTTG: Native, tree-based, random int find timing test using find - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +splay_tree_map- +tree + with Tag = splay_tree_tag +, and Node_Update = null_tree_node_update +
    2. +
  2. +ov_tree_map- +tree + with Tag = ov_tree_tag +, and Node_Update = null_tree_node_update +
    3. +
  3. +n_map- +std::map
    4. +
  4. +rb_tree_map- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +
    5. +
+
+
+
+
+
+
+
+
no image
NTTM: Native, tree-based, random int find timing test using find - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +splay_tree_map- +tree + with Tag = splay_tree_tag +, and Node_Update = null_tree_node_update +
    2. +
  2. +ov_tree_map- +tree + with Tag = ov_tree_tag +, and Node_Update = null_tree_node_update +
    3. +
  3. +n_map- +std::map
    4. +
  4. +rb_tree_map- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +
    5. +
+
+
+
+
+
+
+
+
no image
NTTL: Native, tree-based, random int find timing test using find - local
+
+
+

Observations

+

For this setting, a splay tree (tree + with Tag = splay_tree_tag) + does not do well. This is possibly due to two + reasons:

+
    +
  1. A splay tree is not guaranteed to be balanced + [motwani95random]. + If a splay tree contains n nodes, its + average root-leaf path can be m >> + log(n).
    2. +
  2. Assume a specific root-leaf search path has + length m, and the search-target node has + distance m' from the root. A red-black + tree will require m + 1 comparisons to + find the required node; a splay tree will require + 2 m' comparisons. A splay tree, + consequently, can perform many more comparisons + than a red-black tree.
    3. +
+

An ordered-vector tree (tree + with Tag = ov_tree_tag), + a red-black tree (tree + with Tag = rb_tree_tag), + and the native red-black tree all share + approximately the same performance.

+

An ordered-vector tree is slightly slower than + red-black trees, since it requires, in order to + find a key, more math operations than they do. + Conversely, an ordered-vector tree requires far + lower space than the others. ([austern00noset], + however, seems to have an implementation that is + also faster than a red-black tree).

+

A PATRICIA trie (trie + with Tag = pat_trie_tag) + has good look-up performance, due to its large + fan-out in this case. In this setting, a PATRICIA + trie has lookup performance comparable to a hash + table (see Hash-Based + Text find Find Timing Test), but it is + order preserving. This is not that surprising, + since a large fan-out PATRICIA trie works like a + hash table with collisions resolved by a sub-trie. + A large fan-out PATRICIA trie does not do well on + modifications (see Tree-Based and + Trie-Based Text Insert Timing Test). It is + possibly beneficial to semi-static settings, + therefore.

+

+ Observations::Tree-Like-Based Container Types + summarizes some observations on tree-based and + trie-based containers.

+
+
+
+
+
+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_split_join_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/tree_split_join_timing_test.html new file mode 100644 index 000000000..9164984d1 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/tree_split_join_timing_test.html @@ -0,0 +1,143 @@ + + + + + +Tree Split Join Timing Test + + + +
+

Tree Split-Join Timing Test

+

Description

+

This test a container, inserts into a number of values, + splits the container at the median, and joins the two + containers. (If the containers are one of pb_ds 's + trees, it splits and joins with the split and + join method; otherwise, it uses the erase and + insert methods.) It measures the time for splitting + and joining the containers as a function of the number of + values inserted.

+

(The test was executed with tree_split_join_timing_test + 200 200 2100)

+

Purpose

+

The test checks the performance difference of join + as opposed to a sequence of insert operations; by + implication, this test checks the most efficient way to erase a + sub-sequence from a tree-like-based container, since this can + always be performed by a small sequence of splits and joins + (see Motivation::Associative + Containers::Slightly Different Methods::Methods Related to + Split and Join and Design::Associative + Containers::Tree-Based Containers::Additional Methods + .)

+

Results

+

Figures NTG, NTM, and + NTL show the results for the native and + tree-based containers in g++, msvc++, and + local, + respectively.

+
+
+
+
+
no image
NTG: Native and tree-based container splits and joins - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_set- +std::set
    2. +
  2. +splay_tree_set- +tree + with Tag = splay_tree_tag +, and Node_Update = null_tree_node_update +
    3. +
  3. +rb_tree_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +
    4. +
  4. +ov_tree_set- +tree + with Tag = ov_tree_tag +, and Node_Update = null_tree_node_update +
    5. +
+
+
+
+
+
+
+
+
+
+
no image
NTM: Native and tree-based container splits and joins - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_set- +std::set
    2. +
  2. +splay_tree_set- +tree + with Tag = splay_tree_tag +, and Node_Update = null_tree_node_update +
    3. +
  3. +rb_tree_set- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +
    4. +
  4. +ov_tree_set- +tree + with Tag = ov_tree_tag +, and Node_Update = null_tree_node_update +
    5. +
+
+
+
+
+
+
+
+
+
+
no image
NTL: Native and tree-based container splits and joins - local
+
+
+
+
+

Observations

+

In this test, the native red-black trees must be split and + joined externally, through a sequence of erase and + insert operations. This is clearly super-linear, and + it is not that surprising that the cost is high.

+

pb_ds 's tree-based containers use in this test the + split and join methods, which have lower + complexity: the join method of a splay tree ( tree + with Tag = splay_tree_tag ) is + quadratic in the length of the longest root-leaf path, and + linear in the total number of elements; the join + method of a red-black tree ( tree + with Tag = rb_tree_tag ) or an + ordered-vector tree ( tree + with Tag = ov_tree_tag ) is linear + in the number of elements.

+

Asides from orders of growth, pb_ds 's trees access + their allocator very little in these operations, and some of + them do not access it at all. This leads to lower constants in + their complexity, and, for some containers, to exception-free + splits and joins (which can be determined via container_traits).

+

It is important to note that split and + join are not esoteric methods - they are the most + efficient means of erasing a contiguous range of values from a + tree based container.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_split_join_timing_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_split_join_timing_test_gcc.png new file mode 100644 index 000000000..88867eca6 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_split_join_timing_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_split_join_timing_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_split_join_timing_test_local.png new file mode 100644 index 000000000..131d24a1a Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_split_join_timing_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_split_join_timing_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_split_join_timing_test_msvc.png new file mode 100644 index 000000000..37ed1b2e7 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_split_join_timing_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/tree_tag.html new file mode 100644 index 000000000..d7265ac18 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/tree_tag.html @@ -0,0 +1,47 @@ + + + + + + + tree_tag Interface + + + + +
+

tree_tag Interface

+ +

Basic tree data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+basic_tree_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_text_find_find_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_find_find_timing_test.html new file mode 100644 index 000000000..fbfdfeffa --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_find_find_timing_test.html @@ -0,0 +1,162 @@ + + + + + +Tree Text Find Timing Test + + + +
+

Tree-Based and Trie-Based Text find Find Timing + Test

+

Description

+

This test inserts a number of values with keys from an + arbitrary text ([wickland96thirty]) into + a container, then performs a series of finds using + find. It measures the average time for find + as a function of the number of values inserted.

+

(The test was executed with text_find_timing_test + thirty_years_among_the_dead_preproc.txt 200 200 2100)

+

Purpose

+

The test checks the effect of different underlying + data structures.

+

Results

+

Figures NTTG, NTTM, + and NTTL show the results for the native, + tree-based, and trie-based types in g++, local, and + local, + respectively.

+
+
+
+
+
no image
NTTG: Native, tree-based, and trie-based, text find timing test using find - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +splay_tree_map- +tree + with Tag = splay_tree_tag +, and Node_Update = null_tree_node_update +
    2. +
  2. +ov_tree_map- +tree + with Tag = ov_tree_tag +, and Node_Update = null_tree_node_update +
    3. +
  3. +rb_tree_map- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +
    4. +
  4. +n_map- +std::map
    5. +
  5. +pat_trie_map- +trie + with Tag = pat_trie_tag +, and Node_Update = null_trie_node_update +
    6. +
+
+
+
+
+
+
+
+
+
+
no image
NTTM: Native, tree-based, and trie-based, text find timing test using find - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +splay_tree_map- +tree + with Tag = splay_tree_tag +, and Node_Update = null_tree_node_update +
    2. +
  2. +ov_tree_map- +tree + with Tag = ov_tree_tag +, and Node_Update = null_tree_node_update +
    3. +
  3. +rb_tree_map- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +
    4. +
  4. +n_map- +std::map
    5. +
  5. +pat_trie_map- +trie + with Tag = pat_trie_tag +, and Node_Update = null_trie_node_update +
    6. +
+
+
+
+
+
+
+
+
+
+
no image
NTTL: Native, tree-based, and trie-based, text find timing test using find - local
+
+
+
+
+

Observations

+

For this setting, a splay tree (tree + with Tag = splay_tree_tag) does + not do well. This is possibly due to two reasons:

+
    +
  1. A splay tree is not guaranteed to be balanced [motwani95random]. If a + splay tree contains n nodes, its average root-leaf + path can be m >> log(n).
    2. +
  2. Assume a specific root-leaf search path has length + m, and the search-target node has distance m' + from the root. A red-black tree will require m + 1 + comparisons to find the required node; a splay tree will + require 2 m' comparisons. A splay tree, consequently, + can perform many more comparisons than a red-black tree.
    3. +
+

An ordered-vector tree (tree + with Tag = ov_tree_tag), a red-black + tree (tree + with Tag = rb_tree_tag), and the + native red-black tree all share approximately the same + performance.

+

An ordered-vector tree is slightly slower than red-black + trees, since it requires, in order to find a key, more math + operations than they do. Conversely, an ordered-vector tree + requires far lower space than the others. ([austern00noset], however, + seems to have an implementation that is also faster than a + red-black tree).

+

A PATRICIA trie (trie + with Tag = pat_trie_tag) has good + look-up performance, due to its large fan-out in this case. In + this setting, a PATRICIA trie has look-up performance comparable + to a hash table (see Hash-Based Text + find Find Timing Test), but it is order + preserving. This is not that surprising, since a large-fan-out + PATRICIA trie works like a hash table with collisions resolved + by a sub-trie. A large-fan-out PATRICIA trie does not do well on + modifications (see Tree-Based and Trie-Based + Text Insert Timing Test). It is possibly beneficial to + semi-static settings, therefore.

+

Observations::Tree-Like-Based + Container Types summarizes some observations on tree-based + and trie-based containers.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test.html new file mode 100644 index 000000000..a5815fb2e --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test.html @@ -0,0 +1,226 @@ + + + + + +Tree Text Insert Timing Test + + + +
+

Tree-Based and Trie-Based Text Insert Timing Test

+

Description

+

This test inserts a number of values with keys from an + arbitrary text ([ wickland96thirty ]) into + a container using insert . It measures the average + time for insert as a function of the number of values + inserted.

+

(The test was executed with tree_text_insert_timing_test + thirty_years_among_the_dead_preproc.txt 200 200 2100)

+

Purpose

+

The test checks the effect of different underlying + data structures.

+

Results

+

Figures NNTG, NVTG, + and NPTG show the results for the native + tree and pb_ds's node-based trees, the native tree and + pb_ds's vector-based trees, and the native tree + andpb_ds's PATRICIA-trie, respectively, in g++; Figures + NNTM, NVTM, and + NPTM show the same in msvc++; Figures + NNTL, NVTL, and + NPTL show the same in local.

+
+
+
+
+
no image
NNTG: Native tree and node-based trees text insert timing test using insert - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +splay_tree_map- +tree + with Tag = splay_tree_tag +, and Node_Update = null_tree_node_update +
    2. +
  2. +n_map- +std::map
    3. +
  3. +rb_tree_map- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NVTG: Native tree and vector-based tree text insert timing test using insert - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +ov_tree_map- +tree + with Tag = ov_tree_tag +, and Node_Update = null_tree_node_update +
    2. +
  2. +n_map- +std::map
    3. +
+
+
+
+
+
+
+
+
+
+
no image
NPTG: Native tree and PATRICIA trie text insert timing test using insert - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +n_map- +std::map
    2. +
  2. +pat_trie_map- +trie + with Tag = pat_trie_tag +, and Node_Update = null_trie_node_update +
    3. +
+
+
+
+
+
+
+
+
+
+
no image
NNTM: Native tree and node-based trees text insert timing test using insert - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +splay_tree_map- +tree + with Tag = splay_tree_tag +, and Node_Update = null_tree_node_update +
    2. +
  2. +n_map- +std::map
    3. +
  3. +rb_tree_map- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +
    4. +
+
+
+
+
+
+
+
+
+
+
no image
NVTM: Native tree and vector-based tree text insert timing test using insert - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +ov_tree_map- +tree + with Tag = ov_tree_tag +, and Node_Update = null_tree_node_update +
    2. +
  2. +n_map- +std::map
    3. +
+
+
+
+
+
+
+
+
+
+
no image
NPTM: Native tree and PATRICIA trie text insert timing test using insert - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +pat_trie_map- +trie + with Tag = pat_trie_tag +, and Node_Update = null_trie_node_update +
    2. +
  2. +n_map- +std::map
    3. +
+
+
+
+
+
+
+
+
+
+
no image
NNTL: Native tree and node-based trees text insert timing test using insert - local
+
+
+
+
+
+
+
+
+
no image
NVTL: Native tree and vector-based tree text insert timing test using insert - local
+
+
+
+
+
+
+
+
+
no image
NPTL: Native tree and PATRICIA trie text insert timing test using insert - local
+
+
+
+
+

Observations

+

Observing Figure NNTG , for this + setting, a splay tree, ( tree + with Tag = splay_tree_tag ) does + not do well. This was covered in Tree-Based and + Trie-Based Text find Find Timing Test . The two + red-black trees perform better.

+

Observing Figure NVTG, an ordered-vector + tree ( tree + with Tag = ov_tree_tag) performs + abysmally. Inserting into this type of tree has linear + complexity [ austern00noset].

+

Observing Figure NPTG , A PATRICIA trie + ( trie + with Tag = pat_trie_tag ) has + abysmal performance, as well. This is not that surprising, + since a large-fan-out PATRICIA trie works like a hash table with + collisions resolved by a sub-trie. Each time a collision is + encountered, a new "hash-table" is built A large fan-out + PATRICIA trie, however, doe does well in look-ups (see Tree-Based and + Trie-Based Text find Find Timing Test ). It is + possibly beneficial to semi-static settings, therefore.

+

Observations::Tree-Like-Based + Container Types summarizes some observations on tree-based + and trie-based containers.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_node_tree_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_node_tree_gcc.png new file mode 100644 index 000000000..22d8f6fc2 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_node_tree_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_node_tree_local.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_node_tree_local.png new file mode 100644 index 000000000..bb100084b Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_node_tree_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_node_tree_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_node_tree_msvc.png new file mode 100644 index 000000000..18b219851 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_node_tree_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_pat_trie_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_pat_trie_gcc.png new file mode 100644 index 000000000..5fe063e63 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_pat_trie_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_pat_trie_local.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_pat_trie_local.png new file mode 100644 index 000000000..228de1442 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_pat_trie_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_pat_trie_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_pat_trie_msvc.png new file mode 100644 index 000000000..9f13db0c0 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_pat_trie_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_vector_tree_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_vector_tree_gcc.png new file mode 100644 index 000000000..dd85dcd7c Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_vector_tree_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_vector_tree_local.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_vector_tree_local.png new file mode 100644 index 000000000..cecb8a107 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_vector_tree_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_vector_tree_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_vector_tree_msvc.png new file mode 100644 index 000000000..8c0731391 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_insert_timing_test_vector_tree_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_text_lor_find_find_timing_test.html b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_lor_find_find_timing_test.html new file mode 100644 index 000000000..c577a56db --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_lor_find_find_timing_test.html @@ -0,0 +1,126 @@ + + + + + +Tree Text Locality of Reference Find Timing Test + + + +
+

Tree-Based Locality-of-Reference Text find Find + Timing Test

+

Description

+

This test inserts a number of values with keys from an + arbitrary text ([ wickland96thirty ]) into + a container, then performs a series of finds using + find . It is different than Tree-Based and + Trie-Based Text find Find Timing Test in the + sequence of finds it performs: this test performs multiple + find s on the same key before moving on to the next + key. It measures the average time for find as a + function of the number of values inserted.

+

(The test was executed with tree_text_lor_find_timing_test + thirty_years_among_the_dead_preproc.txt 200 200 2100)

+

Purpose

+

The test checks the effect of different underlying + data structures in a locality-of-reference setting.

+

Results

+

Figures NTG, NTM, and + NTL show the results for the native and + pb_ds tree-based types in g++, msvc++ and + local, + respectively.

+
+
+
+
+
no image
NTG: Native and tree-based locality-of-reference text find timing test using find - g++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +ov_tree_map- +tree + with Tag = ov_tree_tag +, and Node_Update = null_tree_node_update +
    2. +
  2. +rb_tree_map- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +
    3. +
  3. +n_map- +std::map
    4. +
  4. +splay_tree_map- +tree + with Tag = splay_tree_tag +, and Node_Update = null_tree_node_update +
    5. +
+
+
+
+
+
+
+
+
+
+
no image
NTM: Native and tree-based locality-of-reference text find timing test using find - msvc++

In the above figure, the names in the legends have the following meaning:

+
    +
  1. +ov_tree_map- +tree + with Tag = ov_tree_tag +, and Node_Update = null_tree_node_update +
    2. +
  2. +rb_tree_map- +tree + with Tag = rb_tree_tag +, and Node_Update = null_tree_node_update +
    3. +
  3. +n_map- +std::map
    4. +
  4. +splay_tree_map- +tree + with Tag = splay_tree_tag +, and Node_Update = null_tree_node_update +
    5. +
+
+
+
+
+
+
+
+
+
+
no image
NTL: Native and tree-based locality-of-reference text find timing test using find - local
+
+
+
+
+

Observations

+

For this setting, an ordered-vector tree ( tree + with Tag = ov_tree_tag ), a + red-black tree ( tree + with Tag = rb_tree_tag ), and the + native red-black tree all share approximately the same + performance.

+

A splay tree ( tree + with Tag = splay_tree_tag ) does + much better, since each (successful) find "bubbles" the + corresponding node to the root of the tree.

+

Observations::Tree-Like-Based + Container Types summarizes some observations on tree-based + and trie-based containers.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_text_lor_find_timing_test_gcc.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_lor_find_timing_test_gcc.png new file mode 100644 index 000000000..cf5174d99 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_lor_find_timing_test_gcc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_text_lor_find_timing_test_local.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_lor_find_timing_test_local.png new file mode 100644 index 000000000..26f71510f Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_lor_find_timing_test_local.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tree_text_lor_find_timing_test_msvc.png b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_lor_find_timing_test_msvc.png new file mode 100644 index 000000000..583a027f3 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/tree_text_lor_find_timing_test_msvc.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/trie.html b/libstdc++-v3/doc/html/ext/pb_ds/trie.html new file mode 100644 index 000000000..32a2ab1b5 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/trie.html @@ -0,0 +1,489 @@ + + + + + + + trie Interface + + + + +
+

trie Interface

+ +

A concrete basic trie-based associative container.

+ +

Defined in: assoc_container.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+typename Key
+
+ 		+

Key type.

+ 		-
+ 
+typename Mapped
+
+ 		+

Mapped type.

+ 		-
+ 
+class E_Access_Traits 
+
+ 		+

Element-access traits.

+ 		-
+ 
+class Tag 
+
+ 		+

Data-structure tag.

+ 		pat_trie_tag
+ 
+template< 
+  typename Const_Node_Iterator, 
+  typename Node_Iterator, 
+  class E_Access_Traits_, 
+  typename Allocator_>
+class Node_Update 
+
+ 		+

Node updater type.

+ +

Design::Tree-Based + Containers::Node Invariants explains this + concept.

+ 		null_trie_node_update
+ 
+class Allocator 
+
+ 		+

Allocator type.

+ 		+ 
+std::allocator<char>
+
+
+ +

Public Types and + Constants

+ +

Policy Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+e_access_traits
+
+ 		+ 
+E_Access_Traits
+
+ 		+

Element access traits type.

+
+ +

Iterator Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+const_node_iterator
+
+ 		+ 
+const_node_iterator
+
+ 		+

Const node iterator.

+
+ 
+node_iterator
+
+ 		+ 
+node_iterator
+
+ 		+

Node iterator.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+  trie
+  ()
+
+ 		+

Default constructor.

+
+ 
+  trie
+  (const E_Access_Traits &r_e_access_traits)
+
+ 		+

Constructor taking some policy objects. r_e_access_traits will be copied by + the E_Access_Traits + object of the container object.

+
+ 
+template<
+    class It>
+  trie
+  (It first_it, 
+    It last_it)
+
+ 		+

Constructor taking iterators to a range of + value_types. The value_types between first_it and last_it will be inserted into the + container object.

+
+ 
+template<
+    class It>
+  trie
+  (It first_it, 
+    It last_it,
+    const E_Access_Traits &r_e_access_traits)
+
+ 		+

Constructor taking iterators to a range of value_types + and some policy objects. The value_types between + first_it and + last_it will be inserted + into the container object.

+
+ 
+  trie
+  (const trie &other)
+
+ 		+

Copy constructor.

+
+ 
+virtual 
+  ~trie
+  ()
+
+ 		+

Destructor.

+
+ 
+trie &
+  operator=
+  (const trie &other)
+
+ 		+

Assignment operator.

+
+ 
+void
+  swap
+  (trie &other)
+
+ 		+

Swaps content.

+
+ +

Policy Access Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+e_access_traits &
+  get_e_access_traits
+  ()
+
+ 		+

Access to the comb_hash_fn object.

+
+ 
+e_access_traits &
+  get_e_access_traits
+  () const
+
+ 		+

Const access to the comb_hash_fn object.

+
+ +

Node-Iteration Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+node_iterator
+  node_begin
+  ()
+
+ 		+

Returns a node_iterator + corresponding to the node at the root of the trie.

+
+ 
+const_node_iterator
+  node_begin
+  () const
+
+ 		+

Returns a const_node_iterator + corresponding to the node at the root of the trie.

+
+ 
+node_iterator
+  node_end
+  ()
+
+ 		+

Returns a node_iterator + corresponding to a node just after a leaf of the + trie.

+
+ 
+const_node_iterator
+  node_end
+  () const
+
+ 		+

Returns a const_node_iterator + corresponding to a node just after a leaf of the + trie.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/trie_based_containers.html b/libstdc++-v3/doc/html/ext/pb_ds/trie_based_containers.html new file mode 100644 index 000000000..72bdd0697 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/trie_based_containers.html @@ -0,0 +1,241 @@ + + + + + + + Trie-Based Containers + + + + +
+

Trie Design

+ +

Overview

+ +

The trie-based container has the following declaration:

+ 
+template<
+    typename Key,
+    typename Mapped,
+    typename Cmp_Fn = std::less<Key>,
+    typename Tag =  pat_trie_tag,
+    template<
+        typename Const_Node_Iterator,
+        typename Node_Iterator,
+        typename E_Access_Traits_,
+        typename Allocator_>
+    class Node_Update = null_trie_node_update,
+    typename Allocator = std::allocator<char> >
+class trie;
+
+ +

The parameters have the following meaning:

+ +
    +
  1. Key is the key type.
    2. + +
  2. Mapped is the mapped-policy, and is explained in + Tutorial::Associative + Containers::Associative Containers Others than Maps.
    3. + +
  3. E_Access_Traits is described in Element-Access Traits.
    4. + +
  4. Tag specifies which underlying data structure + to use, and is described shortly.
    5. + +
  5. Node_Update is a policy for updating node + invariants. This is described in Node + Invariants.
    6. + +
  6. Allocator is an allocator + type.
    7. +
+ +

The Tag parameter specifies which underlying + data structure to use. Instantiating it by pat_trie_tag, specifies an + underlying PATRICIA trie (explained shortly); any other tag is + currently illegal.

+
+ +

Following is a description of a (PATRICIA) trie + (pb_ds follows specifically [okasaki98mereable] and + [filliatre2000ptset]).

+ +

A (PATRICIA) trie is similar to a tree, but with the + following differences:

+ +
    +
  1. It explicitly views keys as a sequence of elements. + E.g., a trie can view a string as a sequence of + characters; a trie can view a number as a sequence of + bits.
    2. + +
  2. It is not (necessarily) binary. Each node has fan-out n + + 1, where n is the number of distinct + elements.
    3. + +
  3. It stores values only at leaf nodes.
    4. + +
  4. Internal nodes have the properties that A) each has at + least two children, and B) each shares the same prefix with + any of its descendant.
    5. +
+ +

Element-Access Traits shows + an example of such a trie.

+ +

A (PATRICIA) trie has some useful properties:

+ +
    +
  1. It can be configured to use large node fan-out, giving it + very efficient find performance (albeit at insertion + complexity and size).
    2. + +
  2. It works well for common-prefix keys.
    3. + +
  3. It can support efficiently queries such as which keys + match a certain prefix. This is sometimes useful in + file systems and routers.
    4. +
+ +

(We would like to thank Matt Austern for the suggestion to + include tries.)

+ +

Element-Access Traits

+ +

A trie inherently views its keys as sequences of elements. + For example, a trie can view a string as a sequence of + characters. A trie needs to map each of n elements to a + number in {0, n - 1}. For example, a trie can map a + character c to + static_cast<size_t>(c).

+ +

Seemingly, then, a trie can assume that its keys support + (const) iterators, and that the value_type of this + iterator can be cast to a size_t. There are several + reasons, though, to decouple the mechanism by which the trie + accesses its keys' elements from the trie:

+ +
    +
  1. In some cases, the numerical value of an element is + inappropriate. Consider a trie storing DNA strings. It is + logical to use a trie with a fan-out of 5 = 1 + |{'A', 'C', + 'G', 'T'}|. This requires mapping 'T' to 3, though.
    2. + +
  2. In some cases the keys' iterators are different than what + is needed. For example, a trie can be used to search for + common suffixes, by using strings' + reverse_iterator. As another example, a trie mapping + UNICODE strings would have a huge fan-out if each node would + branch on a UNICODE character; instead, one can define an + iterator iterating over 8-bit (or less) groups.
    3. +
+ +

trie is, + consequently, parametrized by E_Access_Traits - + traits which instruct how to access sequences' elements. + string_trie_e_access_traits + is a traits class for strings. Each such traits define some + types, e.g.,

+ 
+typename E_Access_Traits::const_iterator
+
+ +

is a const iterator iterating over a key's elements. The + traits class must also define methods for obtaining an iterator + to the first and last element of a key.

+ +

Figure A PATRICIA trie shows a + (PATRICIA) trie resulting from inserting the words: "I wish + that I could ever see a poem lovely as a trie" (which, + unfortunately, does not rhyme).

+ +

The leaf nodes contain values; each internal node contains + two typename E_Access_Traits::const_iterator + objects, indicating the maximal common prefix of all keys in + the sub-tree. For example, the shaded internal node roots a + sub-tree with leafs "a" and "as". The maximal common prefix is + "a". The internal node contains, consequently, to const + iterators, one pointing to 'a', and the other to + 's'.

+ +
no image
+ +
A PATRICIA trie.
+ +

Node + Invariants

+ +

Trie-based containers support node invariants, as do + tree-based containers (see Tree-Based + Containers::Node Invariants). There are two minor + differences, though, which, unfortunately, thwart sharing them + sharing the same node-updating policies:

+ +
    +
  1. A trie's Node_Update template-template + parameter is parametrized by E_Access_Traits, while + a tree's Node_Update template-template parameter is + parametrized by Cmp_Fn.
    2. + +
  2. Tree-based containers store values in all nodes, while + trie-based containers (at least in this implementation) store + values in leafs.
    3. +
+ +

Figure A trie and its update + policy shows the scheme, as well as some predefined + policies (which are explained below).

+ +
no image
+ +
A trie and its update policy.
+ +

pb_ds offers the following pre-defined trie node + updating policies:

+ +
    +
  1. trie_order_statistics_node_update + supports order statistics.
    2. + +
  2. trie_prefix_search_node_update + supports searching for ranges that match a given prefix. See + trie_prefix_search.cc.
    3. + +
  3. null_trie_node_update + is the null node updater.
    4. +
+ +

Additional + Methods

+ +

Trie-based containers support split and join methods; the + rationale is equal to that of tree-based containers supporting + these methods (see Tree-Based + Containers::Additional Methods).

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/trie_const_node_iterator.html b/libstdc++-v3/doc/html/ext/pb_ds/trie_const_node_iterator.html new file mode 100644 index 000000000..0869a7c2f --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/trie_const_node_iterator.html @@ -0,0 +1,478 @@ + + + + + + + trie::const_node_iterator + Interface + + + + +
+

trie::const_node_iterator + Interface

+ +

Const node iterator.

+ +

This is an "iterator to an iterator" - it iterates over + nodes, and de-referencing it returns one of the tree's const + iterators

+ +

Public Types and + Constants

+ +

General Container + Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+container_base::size_type
+
+ 		+

Size type.

+
+ +

Iterator Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+iterator_category
+
+ 		+ 
+trivial_iterator_tag
+
+ 		+

Category.

+ +

This tag identifies that the iterator has none of the + STL's iterators' movement abilities.

+
+ 
+difference_type
+
+ 		+ 
+void
+
+ 		+

Difference type.

+
+ +

Value-Type Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+value_type
+
+ 		+ 
+container_base::const_iterator
+
+ 		+

Iterator's value type.

+
+ 
+reference
+
+ 		+ 
+value_type
+
+ 		+

Iterator's reference type.

+
+ 
+const_reference
+
+ 		+ 
+value_type
+
+ 		+

Iterator's const reference type.

+
+ 
+e_access_traits
+
+ 		+ 
+trie::e_access_traits
+
+ 		+

Element access traits.

+
+ 
+const_e_iterator
+
+ 		+ 
+typename e_access_traits::const_iterator
+
+ 		+

A key's element const iterator.

+
+ +

Metadata Definitions

+ +

These are only defined if + basic_tree::Node_Update + is not null_trie_node_update

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+metadata_type
+
+ 		+ 
+typename basic_tree::Node_Update::metadata_type
+
+ 		+

Metadata type.

+
+ 
+const_metadata_reference
+
+ 		+ 
+typename Allocator::template rebind<
+    metadata_type>::other::const_reference
+
+ 		+

Const metadata reference type.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline 
+  const_node_iterator
+  ()
+
+ 		+

Default constructor.

+
+ +

Access Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline std::pair<
+    const_e_iterator,
+    const_e_iterator>
+  valid_prefix
+  () const
+
+ 		+

Subtree valid prefix.

+ +

Returns the common prefix range of all nodes in this + node's subtree.

+
+ 
+inline const_reference
+  operator*
+  () const
+
+ 		+

Const access; returns the const iterator associated + with the current leaf.

+ +

Should be called only for leaf nodes.

+
+ +

Metadata Access Methods

+ +

These are only defined if + basic_tree::Node_Update + is not null_trie_node_update

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline const_metadata_reference
+  get_metadata
+  () const
+
+ 		+

Metadata access.

+
+ +

Movement Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline size_type
+  num_children
+  () const
+
+ 		+

Returns the number of children in the corresponding + node.

+ +

If the number of children is 0, then the corresponding + node is a leaf; otherwise, it is not a leaf.

+
+ 
+const_node_iterator
+  get_child
+  (size_type i) const
+
+ 		+

Returns a const node iterator to the corresponding + node's i-th child.

+
+ +

Comparison Methods

+ + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline bool
+  operator==
+  (const const_node_iterator &other) const
+
+ 		+

Compares content to a different iterator object.

+
+ 
+inline bool
+  operator!=
+  (const const_node_iterator &other) const
+
+ 		+

Compares content (negatively) to a different iterator + object.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/trie_node_iterator.html b/libstdc++-v3/doc/html/ext/pb_ds/trie_node_iterator.html new file mode 100644 index 000000000..55029c4cb --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/trie_node_iterator.html @@ -0,0 +1,235 @@ + + + + + + + trie::node_iterator Interface + + + + +
+

trie::node_iterator + Interface

+ +

Node iterator.

+ +

This is an "iterator to an iterator" - it iterates over + nodes, and de-referencing it returns one of the tree's + iterators

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+trie::const_node_iterator
+
+ 		+

public

+
+ +

Public Types and + Constants

+ +

General Container + Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+typename trie::const_node_iterator::size_type
+
+ 		+

Size type.

+
+ +

Value-Type Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+value_type
+
+ 		+ 
+container_base::iterator
+
+ 		+

Iterator's value type.

+
+ 
+reference
+
+ 		+ 
+value_type
+
+ 		+

Iterator's reference type.

+
+ 
+const_reference
+
+ 		+ 
+value_type
+
+ 		+

Iterator's const reference type.

+
+ +

Public Methods

+ +

Constructors, Destructor, and + Related

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline 
+  pat_trie_node_it_
+  () 
+
+ 		+

Default constructor.

+
+ +

Access Methods

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline reference
+  operator*
+  () const
+
+ 		+

Access; returns the iterator associated with the + current leaf.

+ +

Should be called only for leaf nodes.

+
+ +

Movement Methods

+ + + + + + + + + + + + + +
MethodDescription
+ 
+node_iterator
+  get_child
+  (size_type i) const
+
+ 		+

Returns a node iterator to the corresponding node's + i-th child.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/trie_node_updator_policy_cd.png b/libstdc++-v3/doc/html/ext/pb_ds/trie_node_updator_policy_cd.png new file mode 100644 index 000000000..4376929ec Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/trie_node_updator_policy_cd.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/trie_order_statistics_node_update.html b/libstdc++-v3/doc/html/ext/pb_ds/trie_order_statistics_node_update.html new file mode 100644 index 000000000..66aab26d7 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/trie_order_statistics_node_update.html @@ -0,0 +1,770 @@ + + + + + + + trie_order_statistics_node_update Interface + + + + +
+

trie_order_statistics_node_update Interface

+ +

Functor updating ranks of entrees.

+ +

Defined in: trie_policy.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+class Const_Node_Iterator
+
+ 		+

Const node iterator type.

+ 		-
+ 
+class Node_Iterator
+
+ 		+

Node iterator type.

+ 		-
+ 
+class E_Access_Traits
+
+ 		+

Comparison functor.

+ 		-
+ 
+class Allocator
+
+ 		+

Allocator type.

+ 		-
+ +

Public Types and + Constants

+ +

Policy Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+e_access_traits
+
+ 		+ 
+E_Access_Traits
+
+ 		+

Element access traits.

+
+ 
+const_e_iterator
+
+ 		+ 
+typename e_access_traits::const_iterator
+
+ 		+

Const element iterator.

+
+ 
+allocator
+
+ 		+ 
+Allocator
+
+ 		+

Allocator + type.

+
+ +

General Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+typename allocator::size_type
+
+ 		+

Size type.

+
+ +

Key-Type Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+key_type
+
+ 		+ 
+The instantiating container's key type.
+
+ 		+

Key type.

+
+ 
+const_key_reference
+
+ 		+ 
+The instantiating container's const key reference type.
+
+ 		+

Const key reference.

+
+ +

Metadata-Type + Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+metadata_type
+
+ 		+ 
+size_type
+
+ 		+

Metadata type.

+
+ +

Iterator Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+const_node_iterator
+
+ 		+ 
+Const_Node_Iterator
+
+ 		+

Const node iterator type.

+
+ 
+node_iterator
+
+ 		+ 
+Node_Iterator
+
+ 		+

Node iterator type.

+
+ 
+const_iterator
+
+ 		+ 
+typename const_node_iterator::value_type
+
+ 		+

Const iterator type.

+
+ 
+iterator
+
+ 		+ 
+typename node_iterator::value_type
+
+ 		+

Iterator type.

+
+ +

Public Methods

+ +

Find-Type Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+inline const_iterator
+  find_by_order
+  (size_type order) const
+
+ 		+

Finds an entry by order. Returns a const_iterator to + the entry with the order order, or a const_iterator to + the container object's end if order is at least the size of the + container object.

+
+ 
+inline iterator
+  find_by_order
+  (size_type order)
+
+ 		+

Finds an entry by order. Returns an iterator to the entry + with the order order, or + an iterator to + the container object's end if order is at least the size of the + container object.

+
+ 
+inline size_type
+  order_of_key
+  (const_key_reference r_key) const
+
+ 		+

Returns the order of a key within a sequence. For + example, if r_key is the + smallest key, this method will return 0; if r_key is a key between the smallest + and next key, this method will return 1; if r_key is a key larger than the + largest key, this method will return the size of r_c.

+
+ 
+inline size_type
+  order_of_prefix
+  (const_e_iterator b,
+    const_e_iterator e) const
+
+ 		+

Returns the order of a prefix within a sequence. For + eexample, if [b, + e] is the smallest + prefix, this method will return 0; if r_key is a key + bbetween the smallest and + next key, this method will return 1; if r_key is a key + larger than the largest key, this method will return the + size of r_c.

+
+ +

Protected Types and + Constants

+ +

Value-Type + Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+const_reference
+
+ 		+ 
+The instantiating container's const reference  type.
+
+ 		+

Const reference to the container's value-type.

+
+ 
+const_pointer
+
+ 		+ 
+The instantiating container's const pointer  type.
+
+ 		+

Const pointer to the container's value-type.

+
+ 
+const_metadata_reference
+
+ 		+ 
+typename Allocator::template rebind<
+    metadata_type>::other::const_reference
+
+ 		+

Const metadata reference.

+
+ 
+metadata_reference
+
+ 		+ 
+typename Allocator::template rebind<
+    metadata_type>::other::reference
+
+ 		+

Metadata reference.

+
+ +

Protected Methods

+ +

Operators

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  operator()
+  (node_iterator node_it,
+    const_node_iterator end_nd_it) const
+
+ 		+

Updates the rank of a node through a node_iterator + node_it; end_nd_it is the end node iterator.

+
+ +

Constructors, destructor, and + related

+ + + + + + + + + + + + + +
MethodDescription
+ 
+virtual 
+  ~trie_order_statistics_node_update
+  ()
+
+ 		+

Destructor.

+
+ +

Private Methods

+ +

Overrides

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+virtual bool
+  empty
+  () const = 0
+
+ 		+

Returns true if the container is + empty.

+
+ 
+virtual iterator
+  begin
+  () = 0
+
+ 		+

Returns the iterator associated with + the trie's first element.

+
+ 
+virtual iterator
+  end
+  () = 0
+
+ 		+

Returns the iterator associated with + the trie's just-after-last element.

+
+ 
+virtual const_node_iterator
+  node_begin
+  () const = 0
+
+ 		+

Returns the const_node_iterator + associated with the trie's root node.

+
+ 
+virtual node_iterator
+  node_begin
+  () = 0
+
+ 		+

Returns the node_iterator + associated with the trie's root node.

+
+ 
+virtual const_node_iterator
+  node_end
+  () const = 0
+
+ 		+

Returns the const_node_iterator + associated with a just-after leaf node.

+
+ 
+virtual node_iterator
+  node_end
+  () = 0
+
+ 		+

Returns the node_iterator + associated with a just-after leaf node.

+
+ 
+virtual e_access_traits &
+  get_e_access_traits
+  () = 0
+
+ 		+

Access to the cmp_fn object.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/trie_prefix_search_node_update.html b/libstdc++-v3/doc/html/ext/pb_ds/trie_prefix_search_node_update.html new file mode 100644 index 000000000..e136495c5 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/trie_prefix_search_node_update.html @@ -0,0 +1,628 @@ + + + + + + + trie_prefix_search_node_update Interface + + + + +
+

trie_prefix_search_node_update Interface

+ +

A node updater that allows tries to be searched for the + range of values that match a certain prefix.

+ +

Defined in: trie_policy.hpp

+ +

Template Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionDefault Value
+ 
+class Const_Node_Iterator
+
+ 		+

Const node iterator type.

+ 		-
+ 
+class Node_Iterator
+
+ 		+

Node iterator type.

+ 		-
+ 
+class E_Access_Traits
+
+ 		+

Comparison functor.

+ 		-
+ 
+class Allocator
+
+ 		+

Allocator type.

+ 		-
+ +

Public Types and + Constants

+ +

Key-Type Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+key_type
+
+ 		+ 
+The instantiating container's key type.
+
+ 		+

Key type.

+
+ 
+const_key_reference
+
+ 		+ 
+The instantiating container's const key reference type.
+
+ 		+

Const key reference.

+
+ +

Policy Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+e_access_traits
+
+ 		+ 
+E_Access_Traits
+
+ 		+

Element access traits.

+
+ 
+const_e_iterator
+
+ 		+ 
+typename e_access_traits::const_iterator
+
+ 		+

Const element iterator.

+
+ 
+allocator
+
+ 		+ 
+Allocator
+
+ 		+

Allocator + type.

+
+ +

General Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+size_type
+
+ 		+ 
+typename allocator::size_type
+
+ 		+

Size type.

+
+ +

Metadata-Type + Definitions

+ + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+metadata_type
+
+ 		+ 
+__gnu_pbds::detail::null_node_metadata
+
+ 		+

Metadata type.

+
+ +

Iterator Definitions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinitionDescription
+ 
+const_node_iterator
+
+ 		+ 
+Const_Node_Iterator
+
+ 		+

Const node iterator type.

+
+ 
+node_iterator
+
+ 		+ 
+Node_Iterator
+
+ 		+

Node iterator type.

+
+ 
+const_iterator
+
+ 		+ 
+typename const_node_iterator::value_type
+
+ 		+

Const iterator type.

+
+ 
+iterator
+
+ 		+ 
+typename node_iterator::value_type
+
+ 		+

Iterator type.

+
+ +

Public Methods

+ +

Find Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+std::pair<
+    const_iterator,
+    const_iterator>
+  prefix_range
+  (const_key_reference r_key) const
+
+ 		+

Finds the const iterator range + corresponding to all values whose prefixes match + r_key.

+
+ 
+std::pair<
+    iterator,
+    iterator>
+  prefix_range
+  (const_key_reference r_key)
+
+ 		+

Finds the iterator range + corresponding to all values whose prefixes match + r_key.

+
+ 
+std::pair<
+    const_iterator,
+    const_iterator>
+  prefix_range
+  (const_e_iterator b,
+    const_e_iterator e) const
+
+ 		+

Finds the const iterator range + corresponding to all values whose prefixes match [b, + e).

+
+ 
+std::pair<
+    iterator,
+    iterator>
+  prefix_range
+  (const_e_iterator b,
+    const_e_iterator e)
+
+ 		+

Finds the iterator range + corresponding to all values whose prefixes match [b, + e).

+
+ +

Protected Methods

+ +

Operators

+ + + + + + + + + + + + + +
MethodDescription
+ 
+inline void
+  operator()
+  (node_iterator node_it,
+    const_node_iterator end_nd_it) const
+
+ 		+

Called to update a node's metadata.

+
+ +

Private Methods

+ +

Overrides

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
+ 
+virtual const_iterator
+  end
+  () const = 0
+
+ 		+

Returns the const iterator associated with + the just-after last element.

+
+ 
+virtual iterator
+  end
+  () = 0
+
+ 		+

Returns the iterator associated with + the just-after last element.

+
+ 
+virtual const_node_iterator
+  node_begin
+  () const = 0
+
+ 		+

Returns the const_node_iterator + associated with the trie's root node.

+
+ 
+virtual node_iterator
+  node_begin
+  () = 0
+
+ 		+

Returns the node_iterator + associated with the trie's root node.

+
+ 
+virtual const_node_iterator
+  node_end
+  () const = 0
+
+ 		+

Returns the const_node_iterator + associated with a just-after leaf node.

+
+ 
+virtual node_iterator
+  node_end
+  () = 0
+
+ 		+

Returns the node_iterator + associated with a just-after leaf node.

+
+ 
+virtual const e_access_traits &
+  get_e_access_traits
+  () const = 0
+
+ 		+

Access to the cmp_fn object.

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/trie_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/trie_tag.html new file mode 100644 index 000000000..62bf12454 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/trie_tag.html @@ -0,0 +1,47 @@ + + + + + + + trie_tag Interface + + + + +
+

trie_tag Interface

+ +

Basic trie data structure tag.

+ +

Defined in: tag_and_trait.hpp

+ +

Base Classes

+ + + + + + + + + + + + + +
ClassDerivation Type
+ 
+basic_tree_tag
+
+ 		+

public

+
+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/trivial_iterator_tag.html b/libstdc++-v3/doc/html/ext/pb_ds/trivial_iterator_tag.html new file mode 100644 index 000000000..1f59c5102 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/trivial_iterator_tag.html @@ -0,0 +1,25 @@ + + + + + + + trivial_iterator_tag Interface + + + + +
+

trivial_iterator_tag Interface

+ +

A \quot;trivial\quot; iterator tag. Signifies that the + iterators has none of the STL's movement abilities.

+ +

Defined in: tag_and_trait.hpp

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/tutorial.html b/libstdc++-v3/doc/html/ext/pb_ds/tutorial.html new file mode 100644 index 000000000..152cd57b1 --- /dev/null +++ b/libstdc++-v3/doc/html/ext/pb_ds/tutorial.html @@ -0,0 +1,670 @@ + + + + + + + Tutorial + + + + +
+

Short Tutorial

+ +

Following is a short tutorial illustrating the main points + of pb_ds. Concepts + describes and summarizes some concepts.

+ +

Associative + Containers

+ +

Basic Use

+ +

For the most part, pb_ds's containers have the same + interface as the STL's, except for the names used for the + container classes themselves. For example, this shows basic + operations on a collision-chaining hash-based container:

+ + 
+cc_hash_table<int, char> c;
+
+c[2] = 'b';
+
+assert(c.find(1) == c.end());
+
+ +

The container is called cc_hash_table as + opposed to unordered_map, since "unordered map" does + not necessarily mean a hash-based map (as the STL implicitly + implies). For example, list-based associative containers, which + are very useful for the construction of "multimaps" (see + Associative-Container + Performance Tests::Observations::Mapping-Semantics + Considerations), are also unordered. It is also not called + hash_map since there are more ways than one to + implement hash tables.

+ +

This snippet shows a red-black tree based container:

+ 
+tree<int, char> c;
+
+c[2] = 'b';
+
+assert(c.find(2) != c.end());
+
+ +

The container is called tree + as opposed to map, since "map" doesn't say that + much.

+ +

Most of the STL's familiar methods are unchanged. + E.g., being, end, size, + empty, and clear, do just the same as is + customary. Associative-Container + Examples::Basic use, and especially basic_map.cc, + show examples of this.

+ +

This isn't to say that things are exactly as one would expect, +given the container requirments and interfaces in the C++ +standard.

+ + +

The names of containers' policies and policy accessors are + different than those of the STL. For example, if C is + some type of hash-based container, then

+ 
+C::hash_fn
+
gives the type of its hash functor, and if c is some +hash-based container object, then + 
+c.get_hash_fn()
+
+ +

will return a reference to its hash-functor object.

+ +

Similarly, if C is some type of tree-based + container, then

+ 
+C::cmp_fn
+
gives the type of its comparison functor, and if c +is some tree-based container object, then + 
+c.get_cmp_fn()
+
+ +

will return a reference to its comparison-functor + object.

+ +

It would be nice to give names consistent with those in the + existing C++ standard (inclusive of TR1). Unfortunately, these + standard containers don't consistently name types and + methods. For example, std::tr1::unordered_map uses + hasher for the hash functor, but std::map uses + key_compare for the comparison functor. Also, we could + not find an accessor for std::tr1::unordered_map's hash + functor, but std::map uses compare for accessing + the comparison functor.

+ +

Instead, pb_ds attempts to be internally consistent, and +uses standard-derived terminology if possible. +

+ +

Another source of difference is in scope: pb_ds + contains more types of associative containers than the STL, and + more opportunities to configure these new containers, since + different types of associative containers are useful in different + settings (see Associative-Container + Performance Tests::Observations::Underlying Data-Structure + Families).

+ +

pb_ds contains different classes for hash-based containers, + tree-based containers, trie-based containers, and list-based + containers. Inteface::Containers::Associative + Containers lists the containers. Design::Associative + Containers::Hash-Based Containers, Design::Associative + Containers::Tree-Based Containers, Design::Associative + Containers::Trie-Based Containers, and Design::Associative + Containers::List-Based Containers, explain some more about + these types of containers, respectively.

+ +

Since associative containers share parts of their interface, + they are organized as a class hierarchy; it is shown in Figure + Class hierarchy.

+ +
+
+ +
Class hierarchy.
+ +

Each type or method is defined in the most-common ancestor + in which it makes sense: + basic_map.cc + shows an example of most of the associative-container + types.

+ + +

For example, all associative containers support iteration. + Consequently, container_base has the + interface:

+ 
+template<...>
+class container_base
+{
+    ...
+    
+public:
+    ...
+    
+    const_iterator
+    begin() const;
+    
+    iterator
+    begin();
+
+    const_iterator
+    end() const;
+    
+    iterator
+    end();
+        
+    ...
+};
+
+ +

and so all associative containers inherent this method. + Conversely, both collision-chaining and (general) probing + hash-based associative containers have a hash functor, so + basic_hash_table + has the interface:

+ 
+template<...>
+class basic_hash_table : public container_base
+{
+    ...
+    
+public:
+    ...
+    
+    const hash_fn&
+    get_hash_fn() const;
+        
+    hash_fn&
+    get_hash_fn();
+    ...
+};
+
+ +

and so all hash-based associative containers inherit the + same hash-functor accessor methods.

+ +

This is discussed further in Design::Associative Containers::Data-Structure + Genericity.

+ +

Configuring + Associative Containers

+ +

In general, each of pb_ds's containers is + parametrized by more policies than those of the STL's. For + example, the STL's hash-based container is parametrized as + follows:

+ 
+template<
+    typename Key,
+    typename Mapped,
+    typename Hash,
+    typename Pred,
+    typename Allocator,
+    bool Cache_Hashe_Code>
+class unordered_map;
+
+ +

and so can be configured by key type, mapped type, a functor + that translates keys to unsigned integral types, an equivalence + predicate, an allocator, and an indicator whether to store hash + values with each entry. pb_ds's collision-chaining + hash-based container is parametrized as

+ 
+template<
+    typename Key,
+    typename Mapped,
+    typename Hash_Fn,
+    typename Eq_Fn,
+    typename Comb_Hash_Fn,
+    typename Resize_Policy
+    bool Store_Hash
+    typename Allocator>
+class cc_hash_table;
+
+ +

and so can be configured by the first four types of + std::tr1::unordered_map, then a policy for translating + the key-hash result into a position within the table, then a + policy by which the table resizes, an indicator whether to + store hash values with each entry, and an allocator (which is + typically the last template parameter in STL containers).

+ +

Nearly all policy parameters have default values, so this + need not be considered for casual use. It is important to note, + however, that hash-based containers' policies can dramatically + alter their performance in different settings, and that + tree-based containers' policies can make them useful for other + purposes than just look-up.

+ +

Design::Associative + Containers::Hash-Based Containers, Design::Associative + Containers::Tree-Based Containers, Design::Associative + Containers::Trie-Based Containers, and Design::Associative + Containers::List-Based Containers, explain some more about + configuring hash based, tree based, trie based, and list base + containers, respectively. Interface::Container Policy + Classes shows the different policy classes for configuring + associative containers. Examples::Hash-Based + Containers, Examples::Tree-Like-Based + Containers, and Examples::Trie-Based + Containers show examples for this.

+ +

Determining + Containers' Attributes

+ +

Associative-containers' underlying data structures obviously + affect their performance; Unfortunately, they can also affect + their interface. When manipulating generically associative + containers, it is often useful to be able to statically + determine what they can support and what the cannot. (This was + discussed in Motivation::Associative + Containers::Data-Structure Genericity.)

+ +

Happily, the STL provides a good solution to a similar + problem - that of the different behavior of iterators. If + It is an iterator, then

+ 
+typename std::iterator_traits<It>::iterator_category
+
+ +

is one of a small number of pre-defined + structs, and,

+ 
+typename std::iterator_traits<It>::value_type
+
+ +

is the value type to which the iterator "points".

+ +

Similarly, in pb_ds, if C is an + associative container, then

+ 
+typename container_traits<C>::container_category
+
is one of a small number of pre-defined +structs, each one corresponding to a class in +Figure Class hierarchy. These tags are listed in +Interface::Associative +Containers::Data-Structure Tags and Traits::Data-Structure +Tags::Associative-Containers; + Design::Associative Containers::Data-Structure Tags and + Traits explains this further; Design::Associative + Containers::Data-Structure Tags and Traits::Data-structure tag + class hierarchy shows a class diagram. + +

In most cases, however, the exact underlying data structure + is not really important, but only one of its attributes: + whether it guarantees storing elements by key order, for + example. For this one can use

+ 
+typename container_traits<C>::order_preserving
+
+ +

This is described further in Design::Data-Structure Genericity; assoc_container_traits.cc + shows an example of querying containers' attributes.

+ +

Point-Type + and Range-Type Methods and Iterators

(This subsection + addresses points from Motivation::Associative + Containers::Differentiating between Iterator Types.) + +

pb_ds differentiates between two types of methods + and iterators: point-type, and range-type. For example, + find and insert are point-type methods, since + they each deal with a specific element; their returned + iterators are point-type iterators. begin and + end are range-type methods, since they are not used to + find a specific element, but rather to go over all elements in + a container object; their returned iterators are range-type + iterators.

+ +

Most containers store elements in an order that is + determined by their interface. Correspondingly, it is fine that + their point-type iterators are synonymous with their range-type + iterators. For example, in the following snippet

+ 
+std::for_each(c.find(1), c.find(5), foo);
+
two point-type iterators (returned by find) are used +for a range-type purpose - going over all elements whose key is +between 1 and 5. + +

Conversely, the above snippet makes no sense for + self-organizing containers - ones that order (and reorder) + their elements by implementation. It would be nice to have a + uniform iterator system that would allow the above snippet to + compile only if it made sense.

+ +

This could trivially be done by specializing + std::for_each for the case of iterators returned by + std::tr1::unordered_map, but this would only solve the + problem for one algorithm and one container. Fundamentally, the + problem is that one can loop using a self-organizing + container's point-type iterators.

+ +

pb_ds's containers define two families of + iterators: const_point_iterator and + point_iterator are the iterator types returned by + point-type methods; const_iterator and + iterator are the iterator types returned by range-type + methods.

+ 
+class <- some container ->
+{
+public:
+    ...
+
+    typedef <- something -> const_iterator;
+
+    typedef <- something -> iterator;
+
+    typedef <- something -> const_point_iterator;
+
+    typedef <- something -> point_iterator;
+ 
+    ...
+
+public:
+    ...
+
+    const_iterator begin () const;
+
+    iterator begin();
+
+    const_point_iterator find(...) const;
+
+    point_iterator find(...);
+};
+
+ +

Design::Associative + Containers::Data-Structure Genericity::Point-Type and + Range-Type Methods and Iterators discusses the relationship + between point-type and range-type iterators in general; for + containers whose interface defines sequence order, however, it + is very simple: point-type and range-type iterators are exactly + the same, which means that the above snippet will compile if it + is used for an order-preserving associative container.

+ +

For self-organizing containers, however, (hash-based + containers as a special example), the preceding snippet will + not compile, because their point-type iterators do not support + operator++.

+ +

In any case, both for order-preserving and self-organizing + containers, the following snippet will compile:

+ 
+typename Cntnr::point_iterator it = c.find(2);
+
+ +

because a range-type iterator can always be converted to a + point-type iterator.

+ +

Design::Associative + Containers::Data-Structure Genericity::Point-Type and + Range-Type Methods and Iterators discusses this + further.

+ +

Motivation::Associative + Containers::Differentiating between Iterator Types also + raised the point that a container's iterators might have + different invalidation rules concerning their de-referencing + abilities and movement abilities. This now corresponds exactly + to the question of whether point-type and range-type iterators + are valid. As explained in Determining + Containers' Attributes, container_traits allows + querying a container for its data structure attributes. The + iterator-invalidation guarantees are certainly a property of + the underlying data structure, and so

+ 
+container_traits<C>::invalidation_guarantee
+
+ +

gives one of three pre-determined types that answer this + query. This is explained further in Design::Associative + Containers::Data-Structure Genericity::Point-Type and + Range-Type Methods and Iterators.

+ +

Distinguishing between Maps and Sets

+ +

Anyone familiar with the STL knows that there are four kinds + of associative containers: maps, sets, multimaps, and + multisets. Basic Use discussed how + to use maps, i.e. containers that associate each key to + some data.

+ +

Sets are associative containers that simply store keys - + they do not map them to anything. In the STL, each map class + has a corresponding set class. E.g., + std::map<int, char> maps each + int to a char, but + std::set<int, char> simply stores + ints. In pb_ds, however, there are no + distinct classes for maps and sets. Instead, an associative + container's Mapped template parameter is a policy: if + it is instantiated by null_mapped_type, then it + is a "set"; otherwise, it is a "map". E.g.,

+ 
+cc_hash_table<int, char>
+
is a "map" mapping each int value to a + char, but + 
+cc_hash_table<int, null_mapped_type>
+
is a type that uniquely stores int values. + +

Once the Mapped template parameter is instantiated + by null_mapped_type, then + the "set" acts very similarly to the STL's sets - it does not + map each key to a distinct null_mapped_type object. Also, + , the container's value_type is essentially + its key_type - just as with the STL's sets. For a simple example, see basic_set.cc + .

+ +

The STL's multimaps and multisets allow, respectively, + non-uniquely mapping keys and non-uniquely storing keys. As + discussed in Motivation::Associative + Containers::Alternative to Multiple Equivalent Keys, the + reasons why this might be necessary are 1) that a key might be + decomposed into a primary key and a secondary key, 2) that a + key might appear more than once, or 3) any arbitrary + combination of 1)s and 2)s. Correspondingly, + one should use 1) "maps" mapping primary keys to secondary + keys, 2) "maps" mapping keys to size types, or 3) any arbitrary + combination of 1)s and 2)s. Thus, for example, an + std::multiset<int> might be used to store + multiple instances of integers, but using pb_ds's + containers, one might use

+ 
+tree<int, size_t>
+
i.e., a "map" of ints to +size_ts. + +

Associative-Container + Examples::"Multimaps" and "Multisets" shows some simple + examples.

+ +

These "multimaps" and "multisets" might be confusing to + anyone familiar with the STL's std::multimap and + std::multiset, because there is no clear + correspondence between the two. For example, in some cases + where one uses std::multiset in the STL, one might use + in pb_ds a "multimap" of "multisets" - i.e., a + container that maps primary keys each to an associative + container that maps each secondary key to the number of times + it occurs.

+ +

When one uses a "multimap," one should choose with care the + type of container used for secondary keys. This is further + explained in Associative-Container + Performance Tests::Observations::Mapping-Semantics + Considerations.

+ +
+

Priority Queues

+ +

Basic Use

+ +

pb_ds's priority_queue container is + similar to the STL's in interface. For example:

+ 
+priority_queue<int> p;
+
+p.push(2);
+p.push(4);
+p.push(1);
+
+assert(p.top() == 4);
+
+p.pop();
+
+assert(p.top() == 2);
+
+assert(p.size() == 2);
+assert(!p.empty());
+
+ +

Configuring Priority + Queues

+ +

As opposed to associative containers, priority queues have + relatively few configuration options. The priority queue is + parametrized as follows:

+ 
+template<
+    typename Value_Type,
+    typename Cmp_Fn,
+    typename Tag,
+    typename Allocator>
+class priority_queue;
+
+ +

The Value_Type, Cmp_Fn, and + Allocator parameters are the container's value type, + comparison-functor type, and allocator type, respectively; + these are very similar to the STL's priority queue. The + Tag parameter is different: there are a number of + pre-defined tag types corresponding to binary heaps, binomial + heaps, etc., and Tag should be instantiated + by one of them. Interface::Data-Structure Tags and + Traits::Data Structure Tags::Priority-Queues lists the + possible types, Priority-Queue + Design explains this further, and basic_priority_queue.cc + shows an example.

+ +

Note that as opposed to the STL's priority queue, priority_queue is not a + sequence-adapter; it is a regular container.

+ +

Supporting + More Operations

+ +

priority_queue's + push method returns a point-type iterator, which can + be used for modifying or erasing arbitrary values. For + example:

+ 
+priority_queue<int> p;
+
+priority_queue<int>::point_iterator it = p.push(3);
+
+p.modify(it, 4);
+
+ +

These types of operations are necessary for making priority + queues useful for different applications, especially graph + applications. Priority-Queue + Examples::Cross-Referencing gives some examples.

+ +

Determining Container + Attributes

+ +

Similarly to container_traits (described + in Associative Containers::Determining + Containers' Attributes), container_traits can be used to + statically determine priority-queues' attributes:

+ 
+container_traits<C>::container_category
+
is one of a small number of predefined tag structures that +identifies the underlying data structure, and + 
+container_traits<C>::invalidation_guarantee
+
+ +

is its invalidation guarantee. Invalidation guarantees are + especially important regarding priority queues, since in + pb_ds's design, iterators are practically the only way + to manipulate them.

+ +

Design::Priority + Queues::Traits discusses this further. Priority-Queue + Examples::Generics shows an example.

+
+ + diff --git a/libstdc++-v3/doc/html/ext/pb_ds/update_policy_cd.png b/libstdc++-v3/doc/html/ext/pb_ds/update_policy_cd.png new file mode 100644 index 000000000..115a751c3 Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/update_policy_cd.png differ diff --git a/libstdc++-v3/doc/html/ext/pb_ds/update_seq_diagram.png b/libstdc++-v3/doc/html/ext/pb_ds/update_seq_diagram.png new file mode 100644 index 000000000..880a50edf Binary files /dev/null and b/libstdc++-v3/doc/html/ext/pb_ds/update_seq_diagram.png differ -- cgit v1.2.3