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;
Definition: hashmap.h:1115
ResultRef< Entry > Insert(KEY &&key, const V &value, Bool &created=BoolLValue())
Definition: hashmap.h:1633
#define iferr_return
Definition: resultbase.h:1524

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);
Definition: hashmap.h:1985
Result< Entry * > InsertLambda(KEY &&key, LAMBDA &&lambda, Bool &created=BoolLValue())
Definition: hashmap.h:1614
ResultRef< Entry > InsertMultiEntry(KEY &&key)
Definition: hashmap.h:1680
ResultRef< V > InsertKey(const K &key, Bool &created=BoolLValue())
Definition: hashmap.h:1555
ResultRef< Entry > InsertEntry(const K &key, Bool &created=BoolLValue())
Definition: hashmap.h:1513
Definition: string.h:1237
void * str
Definition: bytesobject.h:77
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:195
return OK
Definition: apibase.h:2735
Py_ssize_t * e
Definition: longobject.h:89

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)
Opt< V & > FindValue(const KEY &key)
Definition: hashmap.h:1368
Entry * Find(const KEY &key)
Definition: hashmap.h:1336
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:170

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;
}
ResultOk< void > Erase(const Entry *entry, Bool deleteEntry=true)
Definition: hashmap.h:1738

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);
}
PyObject * value
Definition: abstract.h:715
PyObject * key
Definition: abstract.h:289
KeyIterator GetKeys()
Definition: hashmap.h:2455
MultiEntryIterator< false > FindAll(const K &key)
Definition: hashmap.h:2162
ValueIterator GetValues()
Definition: hashmap.h:2473
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:202

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();
Py_ssize_t count
Definition: abstract.h:640
Int GetCount() const
Definition: hashmap.h:1238
Int GetNonEmptyBucketCount() const
Definition: hashmap.h:1276
Int GetTableSize() const
Definition: hashmap.h:1247

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