HashMap Manual

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.
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:

Access

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

// This example creates a hash map and inserts elements in various ways.
// 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
{
entry.SetValue("Beryllium"_s);
return maxon::OK;
};
atoms.InsertLambda(4, lambda) iferr_return;
// insert data (multi-map)
if (e)
e->SetValue("Deuterium"_s);

An entry stored in the maxon::HashMap can be found using the proper 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)

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

// This example searches the entry for the given key and deletes it.
// find entry for key "1"
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:

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:

// 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:

// 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:

Further utility functions are:

Further Reading

maxon::HashMap::FindValue
V * FindValue(const KEY &key)
Definition: hashmap.h:1122
maxon::HashMap::GetKeys
KeyIterator GetKeys()
Definition: hashmap.h:2184
maxon::HashMap::Insert
ResultRef< Entry > Insert(KEY &&key, const V &value, Bool &created=BoolLValue())
Definition: hashmap.h:1358
maxon::HashMap::Entry
Definition: hashmap.h:1700
maxon::HashMap::InsertKey
ResultRef< V > InsertKey(const K &key, Bool &created=BoolLValue())
Definition: hashmap.h:1283
maxon::String
Definition: string.h:1197
maxon::HashMap::InsertLambda
Result< Entry * > InsertLambda(KEY &&key, LAMBDA &&lambda)
Definition: hashmap.h:1338
maxon::OK
return OK
Definition: apibase.h:2490
maxon::Bool
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:177
maxon::HashMap::GetValues
ValueIterator GetValues()
Definition: hashmap.h:2202
iferr_return
#define iferr_return
Definition: resultbase.h:1434
maxon::HashMap::GetTableSize
Int GetTableSize() const
Definition: hashmap.h:1001
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:168
maxon::HashMapEntryBase::GetKey
decltype(ENTRY_HANDLER::GetKey(*(V *) nullptr) GetKey)() const
Definition: hashmap.h:120
maxon::Result< void >
maxon::Int
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:184
maxon::HashMap::FindAll
MultiEntryIterator< false > FindAll(const K &key)
Definition: hashmap.h:1891
maxon::HashMap::Erase
ResultOk< void > Erase(const Entry *entry, Bool deleteEntry=true)
Definition: hashmap.h:1463
maxon::HashMap
Definition: hashmap.h:848
maxon::HashMap::GetNonEmptyBucketCount
Int GetNonEmptyBucketCount() const
Definition: hashmap.h:1030
maxon::HashMap::GetCount
Int GetCount() const
Definition: hashmap.h:992
maxon::HashMap::InsertMultiEntry
ResultRef< Entry > InsertMultiEntry(KEY &&key)
Definition: hashmap.h:1405
maxon::HashMap::Find
Entry * Find(const KEY &key)
Definition: hashmap.h:1090
maxon::HashMapEntryBase::GetValue
V & GetValue()
Definition: hashmap.h:129
maxon::HashMap::InsertEntry
ResultRef< Entry > InsertEntry(const K &key, Bool &created=BoolLValue())
Definition: hashmap.h:1241