hashtable

using xtd::collections::hashtable = typedef generic::dictionary<xtd::any_object, xtd::any_object>

Represents a collection of key/value pairs that are organized based on the hash code of the key.

using hashtable = xtd::collections::generic::dictionary<std::any, std::any>

Header

#include <xtd/collections/hashtable>

Namespace

xtd::collections

Library

xtd.core

Remarks

Each element is a key/value pair stored in a xtd::collections::dictionary_entry object. A key cannot be null, but a value can be.

The objects used as keys by a xtd::collections::hashtable are required to override the xtd::object::get_hash_code method (or the xtd::ihash_code_provider interface) and the xtd::object::equals method (or the xtd::icomparer interface). The implementation of both methods and interfaces must handle case sensitivity the same way; otherwise, the xtd::collections::hashtable might behave incorrectly. For example, when creating a xtd::collections::hashtable, you must use the xtd::case_insensitive_hash_code_provider class (or any case-insensitive xtd::ihash_code_provider implementation) with the xtd::case_insensitive_comparer class (or any case-insensitive xtd::icComparer implementation).

Furthermore, these methods must produce the same results when called with the same parameters while the key exists in the xtd::collections::hashtable. An alternative is to use a xtd::collections::hashtable constructor with an xtd::iequality_comparer parameter. If key equality were simply reference equality, the inherited implementation of xtd::object::get_hash_code and xtd::object::equals would suffice.

Key objects must be immutable as long as they are used as keys in the xtd::collections::hashtable.

When an element is added to the xtd::collections::hashtable, the element is placed into a bucket based on the hash code of the key. Subsequent lookups of the key use the hash code of the key to search in only one particular bucket, thus substantially reducing the number of key comparisons required to find an element.

The load factor of a xtd::collections::hashtable determines the maximum ratio of elements to buckets. Smaller load factors cause faster average lookup times at the cost of increased memory consumption. The default load factor of 1.0 generally provides the best balance between speed and size. A different load factor can also be specified when the xtd::collections::hashtable is created.

As elements are added to a xtd::collections::hashtable, the actual load factor of the xtd::collections::hashtable increases. When the actual load factor reaches the specified load factor, the number of buckets in the xtd::collections::hashtable is automatically increased to the smallest prime number that is larger than twice the current number of xtd::collections::hashtable buckets.

Each key object in the xtd::collections::hashtable must provide its own hash function, which can be accessed by calling GetHash. However, any object implementing IHashCodeProvider can be passed to a xtd::collections::hashtable constructor, and that hash function is used for all objects in the table

The capacity of a xtd::collections::hashtable is the number of elements the xtd::collections::hashtable can hold. As elements are added to a xtd::collections::hashtable, the capacity is automatically increased as required through reallocation.

The foreach statement returns an object of the type of the elements in the collection. Since each element of the xtd::collections::hashtable is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is xtd::collections::dictionary_entry. For example:

for (xtd::collections::dictionary_entry de : my_hashtable) {
  // ...
}

The foreach statement is a wrapper around the enumerator, which only allows reading from, not writing to, the collection.

Because serializing and deserializing an enumerator for a xtd::collections::hashtable can cause the elements to become reordered, it is not possible to continue enumeration without calling the Reset method.

Note

Because keys can be inherited and their behavior changed, their absolute uniqueness cannot be guaranteed by comparisons using the Equals method.

Exemples

The following example shows how to create, initialize and perform various functions to a xtd::collections::hashtable and how to print out its keys and values.

#include <xtd/collections/hashtable>
#include <xtd/console>
 
using namespace xtd;
using namespace xtd::collections;
 
auto main() -> int {
  // Create a new hash table.
  //
  hashtable open_with;
  
  // Add some elements to the hash table. There are no
  // duplicate keys, but some of the values are duplicates.
  open_with["txt"] = "notepad.exe";
  open_with["bmp"] = "paint.exe";
  open_with["dib"] = "paint.exe";
  open_with["rtf"] = "wordpad.exe";
  
  // The Item property is the default property, so you
  // can omit its name when accessing elements.
  console::write_line("For key = \"rtf\", value = {0}.", open_with["rtf"]);
  
  // The default Item property can be used to change the value
  // associated with a key.
  open_with["rtf"] = "winword.exe";
  console::write_line("For key = \"rtf\", value = {0}.", open_with["rtf"]);
  
  // If a key does not exist, setting the default Item property
  // for that key adds a new key/value pair.
  open_with["doc"] = "winword.exe";
  
  // contains can be used to test keys before inserting
  // them.
  if (!open_with.contains("ht")) {
    open_with["ht"] = "hypertrm.exe";
    console::write_line("Value added for key = \"ht\": {0}", open_with["ht"]);
  }
  
  // When you use foreach to enumerate hash table elements,
  // the elements are retrieved as xtd::collections::generic::key_value_pair objects.
  console::write_line();
  for (auto de : open_with)
    console::write_line("Key = {0}, Value = {1}", de.first, de.second);
    
  // Use the Remove method to remove a key/value pair.
  console::write_line("\nerase(\"doc\")");
  open_with.erase("doc");
  
  if (!open_with.contains("doc"))
    console::write_line("Key \"doc\" is not found.");
}
 
// This code produces the following output :
//
// For key = "rtf", value = wordpad.exe.
// For key = "rtf", value = winword.exe.
// Value added for key = "ht": hypertrm.exe
//
// Key = ht, Value = hypertrm.exe
// Key = doc, Value = winword.exe
// Key = bmp, Value = paint.exe
// Key = rtf, Value = winword.exe
// Key = dib, Value = paint.exe
// Key = txt, Value = notepad.exe
//
// erase("doc")
// Key "doc" is not found.