About

A maxon::DataDictionary is a data container that stores arbitrary MAXON API data filed under a given key. The base interface is maxon::DataDictionaryInterface.

Note: For custom interfaces inheriting maxon::DataDictionary functionality use maxon::DataDictionaryObjectInterface.

Creation

A new maxon::DataDictionary object can be created on the stack:

    // This example creates a new DataDictionary object and stores some values.
 
    maxon::DataDictionary dataDict;
 
    dataDict.Set(0, maxon::Int32(100)) iferr_return;
    dataDict.Set(1, maxon::Int32(200)) iferr_return;

Keys and Values

A DataDictionary stores data for one or many keys. Both the stored data and the key must be a registered MAXON API data type (see MAXON Data Type).

maxon::DataDictionaryInterface::Get(): Returns the data stored at the given key.
maxon::DataDictionaryInterface::Set(): Stores the given data at the given key.
maxon::DataDictionaryInterface::GetData(): Returns a maxon::Data container with the data stored at the given key.
maxon::DataDictionaryInterface::SetData(): Stores the given maxon::Data at the given key.
maxon::DataDictionaryInterface::GetCopy(): Returns a copy of the data stored at the given key.

Note: To access data with a defined type one can use resource IDs, see Resource IDs.

    // This example stores and reads values from the given DataDictionary object.
 
    // simple set
    dataDict.Set(0, maxon::Int32(100)) iferr_return;
 
    // set maxon::Data
    const maxon::Data number(maxon::Int32(123));
    dataDict.SetData(maxon::ConstDataPtr(1), std::move(number)) iferr_return;
 
    // simple get
    const maxon::Int32 value = dataDict.Get<maxon::Int32>(0) iferr_return;
    DiagnosticOutput("Value: @", value);
 
    // get maxon::Data
    const maxon::Data data = dataDict.GetData(maxon::ConstDataPtr(1)) iferr_return;
    DiagnosticOutput("Data: @", data);

The data stored in the DataDictionary can be inspected and deleted with:

maxon::DataDictionaryInterface::IsEmpty(): Returns true if the dictionary is empty.
maxon::DataDictionaryInterface::IsPopulated(): Returns true if the dictionary is not empty.
maxon::DataDictionaryInterface::Existing(): Returns true if some data is stored at the given key.
maxon::DataDictionaryInterface::Erase(): Deletes the data at the given key.
maxon::DataDictionaryInterface::EraseData(): Deletes the data at the given key.
maxon::DataDictionaryInterface::Reset(): Frees the entire dictionary.

    // This example checks if a certain key is defined in the given DataDictionary.
    // If so the value stored at the key is printed to the debug console and then deleted.
 
    const maxon::Int key = 0;
 
    if (dataDict.Contains(key))
    {
      const maxon::ConstDataPtr keyPtr = maxon::ConstDataPtr(key);
      const maxon::Data         value  = dataDict.GetData(keyPtr) iferr_return;
      DiagnosticOutput("Key: @, Value: @", key, value);
 
      // remove
      dataDict.Erase(key) iferr_return;
    }
 
    if (!dataDict.Contains(key))
      DiagnosticOutput("Key @ deleted.", key);

Iterator

Using an iterator it is simple to loop through all elements stored in the DataDictionary.

maxon::DataDictionaryInterface::Begin(): Returns the begin iterator.
maxon::DataDictionaryInterface::End(): Returns the end iterator.

    // This example loops through all values stored in the given DataDictionary.
 
    for (const auto& data : dataDict)
    {
      const maxon::Data key = data.first.GetCopy() iferr_return;
      const maxon::Data value = data.second.GetCopy() iferr_return;
      const maxon::DataType type = value.GetType();
 
      DiagnosticOutput("Key: @, Value: @ (@)", key, value, type);
    }

Utility

Further utility functions are:

maxon::DataDictionaryInterface::ToString(): Returns a maxon::String with a representation of the data stored in the dictionary.
maxon::DataDictionaryInterface::IsEqual(): Returns true if the given DataDictionary is equal.
maxon::DataDictionaryInterface::GetHashCode(): Returns a hash value.

    // This example get the maxon::String representation and a hash value
    // for the given DataDictionary and prints it to the debug console.
 
    const maxon::String str  = dataDict.ToString(nullptr);
    const maxon::UInt   hash = dataDict.GetHashCode();
 
    DiagnosticOutput("Hash: @, String: @", hash, str);

Table of Contents

About

Creation

Keys and Values

Iterator

Utility

Further Reading