About

maxon::Data is a generic container that can store any MAXON API data type (MAXON Data Type). It is typically used together with a maxon::DataDictionary which stores such maxon::Data elements, see DataDictionary Manual.

Creation

A new maxon::Data object can simply be created on the stack.

maxon::Data::Data(): Creates a new maxon::Data object.
maxon::Data::Init(): Initializes the maxon::Data object to the given maxon::DataType.

    // This example creates new maxon::Data objects with various data.
    // store maxon::String
    maxon::Data data;
    data.Set("Hello World"_s) iferr_return;
    // store maxon::Int
    const maxon::Data integerData(123);
    const maxon::DataType dataType = integerData.GetType();
    if (dataType)
      DiagnosticOutput("Type: @", dataType);
    // store maxon::Float
    const maxon::DataType floatDataType = maxon::GetDataType<maxon::Float>();
    if (floatDataType)
    {
      maxon::Data floatData;
      floatData.Init(floatDataType) iferr_return;
      DiagnosticOutput("Float Data: @", floatData);
    }

A given maxon::Data object can be inspected and reset with:

maxon::Data::IsEmpty(): Returns true if the object is empty.
maxon::Data::IsPopulated(): Returns true if the object contains data.
maxon::Data::GetType(): Returns the maxon::DataType of the stored data.
maxon::Data::Reset(): Frees and restores all internal data.

    // This example checks if the given maxon::Data object is empty.
    // If not the type of the stored data is printed to the debug console.
    // After that, it is emptied.
    if (data.IsPopulated())
    {
      // check type of the stored data
      const maxon::DataType type = data.GetType();
      if (type)
        DiagnosticOutput("Type: @", type);
    }
    // clear data
    data.Reset();
    // check if data has been cleared
    if (data.IsEmpty())
      DiagnosticOutput("Data is now empty.");

Data

The key function of maxon::Data is to store and access data stored in the object:

maxon::Data::Get(): Returns the data stored in the object.
maxon::Data::Set(): Sets the data stored in the object.
maxon::Data::GetOrNull(): Returns the data stored in the object or the maxon::NullValue of the desired data type.
maxon::Data::GetPtr(): Returns the pointer to the native data.
maxon::Data::GetTuple(): Returns the stored value as a maxon::TupleValue.

    // This example checks if the given maxon::Data object stores an maxon::Int32 value.
    // If so, the stored value is increased.
    // get maxon::Int32 type
    const maxon::DataType integerType = maxon::GetDataType<maxon::Int32>();
    if (!integerType)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
    // check if data stores maxon::Int32 data
    const maxon::DataType type = data.GetType();
    if (type == integerType)
    {
      // increment data
      maxon::Int number = data.Get<maxon::Int32>() iferr_return;
      number++;
      data.Set(number) iferr_return;
      DiagnosticOutput("Data: @", data);
    }

    // This example constructs a complex data type and sets its values.
    // construct tuple data type
    maxon::BaseArray<maxon::DataType> structTypes;
    structTypes.Append(maxon::GetDataType<maxon::Int>()) iferr_return;
    structTypes.Append(maxon::GetDataType<maxon::Float>()) iferr_return;
    const maxon::TupleDataType tupleDataType = maxon::ParametricTypes::Tuple().Instantiate(structTypes) iferr_return;
    // create data
    maxon::Data data;
    data.Init(tupleDataType) iferr_return;
    // access tuple
    maxon::TupleValue* const tuple = data.GetTuple();
    if (!tuple)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
    // fill data
    tuple->Get<maxon::Int>(0, tupleDataType) = 100;
    tuple->Get<maxon::Float>(1, tupleDataType) = 100.0_f;
    // check data
    DiagnosticOutput("Data: @", data);

The data stored within a maxon::Data object can also be converted into another data type:

maxon::Data::Convert(): Returns the data converted into the given data type.
maxon::Data::ConvertOrNull(): Returns the data converted into the given data type or the maxon::NullValue of the desired data type.

    // This example converts the stored value into a maxon::Float value.
    const maxon::Float floatData = data.Convert<maxon::Float>() iferr_return;
    DiagnosticOutput("Float value: @", floatData);

Copy

The data stored in a maxon::Data object can easily be copied to another maxon::Data object.

maxon::Data::operator=(): Copies the data into the given target maxon::Data object.
maxon::Data::GetCopy(): Creates a copy of the maxon::Data object.
maxon::Data::CopyFrom(): Copies the data from the given maxon::Data object.
maxon::Data::MoveFrom(): Moves the data.

    // This example copies the data stored in the given maxon::Data object to two new objects.
    // use CopyFrom()
    maxon::Data copy1;
    copy1.CopyFrom(data) iferr_return;
    DiagnosticOutput("Copy: @", copy1);
    // use GetCopy()
    const maxon::Data copy2 = data.GetCopy() iferr_return;
    DiagnosticOutput("Copy: @", copy2);

Compare

There are multiple ways to compare two given maxon::Data objects:

maxon::Data::Compare(): Compares the data with the given maxon::Data object and returns a maxon::COMPARERESULT.
maxon::Data::GetHashCode(): Returns a hash value.
maxon::Data::IsEqual(): Returns true if the given maxon::Data object is equal.
maxon::Data::operator==(): Returns true if the given maxon::Data object is equal.
maxon::Data::operator!=(): Returns true if the given maxon::Data object is not equal.
maxon::Data::operator<(): Returns true if the given maxon::Data object is lesser than the stored data.
maxon::Data::operator<=(): Returns true if the given maxon::Data object is lesser than or the same as the stored data.
maxon::Data::operator>(): Returns true if the given maxon::Data object is greater than the stored data.
maxon::Data::operator>=(): Returns true if the given maxon::Data object is greater than or the same as the stored data.

    // This example compares the two given maxon::Data objects in multiple ways.
    const maxon::COMPARERESULT res = dataA.Compare(dataB);
    if (res == maxon::COMPARERESULT::EQUAL)
      DiagnosticOutput("Data containers are equal.");
    if (dataA.IsEqual(dataB))
      DiagnosticOutput("Data containers are equal.");
    if (dataA == dataB)
      DiagnosticOutput("Data containers are equal.");

Utility

Further utility functions are:

maxon::Data::ToString(): Returns a maxon::String description of the stored data.

    // This example gets the maxon::String representation of the
    // stored data and prints it to the console.
    const maxon::String str = data.ToString(nullptr);
    DiagnosticOutput("String: @", str);

Table of Contents