HashMap Manual

Table of Contents

• About
• Create
• Access
• Iterate
• Utility
• Further Reading

About

maxon::HashMap is a generic class template for a map that maps keys to values with the help of hash values. It can use data types as a key that implement a "GetHashCode" and "IsEqual" function. maxon::HashMap is based on maxon::MapBase and maxon::Collection.

Create

A new hash map object can simply be created using the class template:

    // This example creates a hash map and inserts two elements.
    // The hash map stores maxon::String values using maxon::Int keys.
 
    maxon::HashMap<maxon::Int, maxon::String> atoms;
 
    atoms.Insert(1, "Hydrogen"_s) iferr_return;
    atoms.Insert(2, "Helium"_s) iferr_return;

The data stored in a maxon::HashMap can be cleared with:

• maxon::HashMap::Reset(): Destructs all entries and frees any memory held by the map.
• maxon::HashMap::Flush(): Destructs and frees all entries, but does not free the bucket table.

Access

An entry in a maxon::HashMap is represented as a maxon::HashMap::Entry object. New entries can be inserted with:

• maxon::HashMap::Insert(): Inserts the given value using the given key.
• maxon::HashMap::InsertEntry(): Inserts a maxon::HashMap::Entry for the given key.
• maxon::HashMap::InsertKey(): Inserts an entry for the given key and returns a pointer to the stored value.
• maxon::HashMap::InsertCtor(): Inserts an entry for the given key and creates a new value using the given constructor.
• maxon::HashMap::InsertLambda(): Inserts an entry for the given key using the given lambda function.
• maxon::HashMap::InsertMultiEntry(): Inserts an entry for the given key. If an entry already exists the hash map is turned in to a multi-map.

    // This example creates a hash map and inserts elements in various ways.
 
    maxon::HashMap<maxon::Int, maxon::String> atoms;
 
    // insert data
    atoms.Insert(1, "Hydrogen"_s) iferr_return;
 
    // insert data
    maxon::Bool created = false;
    auto        e = &atoms.InsertEntry(2, created) iferr_return;
 
    if (created && e)
      e->SetValue("Helium"_s);
 
    // insert data
    maxon::String& str = atoms.InsertKey(3, created) iferr_return;
    str = "Lithium"_s;
 
    // insert data
    auto lambda = [](maxon::HashMap<maxon::Int, maxon::String>::Entry& entry) -> maxon::Result<void>
                  {
                    entry.SetValue("Beryllium"_s);
                    return maxon::OK;
                  };
 
    atoms.InsertLambda(4, lambda) iferr_return;
 
    // insert data (multi-map)
    e = &atoms.InsertMultiEntry(1) iferr_return;
    if (e)
      e->SetValue("Deuterium"_s);

An entry stored in the maxon::HashMap can be found using the proper key:

• maxon::HashMap::Find(): Returns the entry for the given key.
• maxon::HashMap::FindValue(): Returns the value stored for the given key.

    // This example gets the values for a given keys in the hash map.
 
    // find key "1"
    auto e = atoms.Find(1);
    if (e)
      DiagnosticOutput(e->GetValue());
 
    // find key "2"
    const maxon::String* const str = atoms.FindValue(2);
    if (str)
      DiagnosticOutput(*str);

An entry of the maxon::HashMap can also be deleted:

• maxon::HashMap::Erase(): Removes the given entry.
• maxon::HashMap::DeleteEntry(): Deletes an entry which has been removed previously. Only needed if Erase() was used with specific parameters.

    // This example searches the entry for the given key and deletes it.
 
    // find entry for key "1"
    maxon::HashMap<maxon::Int, maxon::String>::Entry* e = nullptr;
    e = atoms.Find(1);
    if (e)
    {
      atoms.Erase(e, true) iferr_return;
    }

It is easily possible to iterate trough all stored key and values with:

• maxon::HashMap::GetKeys(): Returns an iterator for all keys.
• maxon::HashMap::GetValues(): Returns an iterator for all stored values.
• maxon::HashMap::FindAll(): Returns an iterator for all values stored for a given key. See maxon::MultiEntryIterator<T>.

See also Iterate.

    // This example loops through all keys and value of the given hash map
    // and the multi-map values of a given key.
 
    // list all keys
    for (const maxon::Int& key : atoms.GetKeys())
      DiagnosticOutput("Key: @", key);
 
    // list all values
    for (const maxon::String& value : atoms.GetValues())
      DiagnosticOutput("Values: @", value);
 
    // list multi-map values of given key
    for (const auto& it : atoms.FindAll(1))
    {
      const auto value = it.GetValue();
      DiagnosticOutput("Value: @", value);
    }

A maxon::HashMap stores a certain number of elements and has a certain capacity to store further elements:

• maxon::HashMap::GetCount(): Returns the number of stored entries.
• maxon::HashMap::SetCapacityHint(): Ensures that the bucket table is large enough to hold at least the given number of entries.
• maxon::HashMap::ResizeTable(): Resizes the bucket table.
• maxon::HashMap::GetTableSize(): Returns the size of the bucket table.
• maxon::HashMap::GetMemorySize(): Returns the memory usage of the map if the key and value implement GetMemorySize().
• maxon::HashMap::GetNonEmptyBucketCount(): Returns the number of non-empty buckets.
• maxon::HashMap::GetNonEmptyBucket(): Returns the non-empty bucket of the given index.

    // This example reads data from the given hash map.
 
    const maxon::Int count = atoms.GetCount();
    const maxon::Int nonEmptyCount = atoms.GetNonEmptyBucketCount();
    const maxon::Int tableSize = atoms.GetTableSize();

Iterate

It is easily to iterate over all entries in the maxon::HashMap:

• maxon::HashMap::Begin(): Returns the iterator pointing at the start of the list.
• maxon::HashMap::End(): Returns the iterator pointing at the end of the list.
• maxon::HashMap::GetIterator(): Returns the iterator for the given entry.

    // This example loops through all entries of the given hash map.
 
    // loop through all key/value pairs
    for (const auto& e : atoms)
    {
      const maxon::Int&    key = e.GetKey();
      const maxon::String& value = e.GetValue();
      DiagnosticOutput("Key: @, Value: @", key, value);
    }
 
    auto e = atoms.Find(1);
    if (e)
    {
      auto it = atoms.GetIterator(e);
 
      // next element
      ++it;
 
      const maxon::Int&    key = it.GetKey();
      const maxon::String& value = it.GetValue();
      DiagnosticOutput("Key: @, Value: @", key, value);
    }

Utility

A maxon::HashMap can easily be copied:

• maxon::HashMap::CopyFrom(): Copies the data from the given maxon::HashMap.

Further utility functions are:

• maxon::HashMap::ToString(): Returns a string representation of the maxon::HashMap.

Further Reading

• Data Containers & Collections
• MAXON API Containers & Data Collections
• DataDictionary Manual