Data Manual

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.

// This example creates new maxon::Data objects with various data.
// store maxon::String
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);
}
Definition: datatypebase.h:1229
Result< void > Set(T &&data)
Definition: datatypebase.h:1378
Result< void > Init(const DataType &type)
Definition: datatypebase.h:770
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:170
#define iferr_return
Definition: resultbase.h:1524

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

// 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.");
void Reset()
Frees the wrapped data and resetd the Data object to its initial state.
Definition: datatypebase.h:1287
Bool IsEmpty() const
Definition: datatypebase.h:1264
Bool IsPopulated() const
Definition: datatypebase.h:1273
const DataType & GetType() const
Definition: datatypebase.h:1282
PyObject ** type
Definition: pycore_pyerrors.h:34

Data

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

// 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
number++;
data.Set(number) iferr_return;
DiagnosticOutput("Data: @", data);
}
Result< typename std::conditional< GetCollectionKind< T >::value==COLLECTION_KIND::ARRAY, T, typename ByValueParam< T >::type >::type > Get() const
Definition: datatypebase.h:1389
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:202
int32_t Int32
32 bit signed integer datatype.
Definition: apibase.h:190
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
// This example constructs a complex data type and sets its values.
// construct tuple data type
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
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);
#define Tuple(a0, a1, a2, a3, a4, a5, a6)
Definition: Python-ast.h:652
Definition: basearray.h:415
MAXON_ATTRIBUTE_FORCE_INLINE ResultRef< T > Append(ARG &&x)
Appends a new element at the end of the array and constructs it using the forwarded value.
Definition: basearray.h:628
TupleValue * GetTuple()
Definition: datatypebase.h:1543
Definition: datatypelib.h:861
Definition: datatype.h:1113
PyObject * tuple
Definition: abstract.h:150
Float64 Float
Definition: apibase.h:211

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);
Result< T > Convert() const
Definition: datatypebase.h:1435

Copy

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

// 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);
Result< void > CopyFrom(const Data &src)
Result< Data > GetCopy() const
Returns a copy of the data.
Definition: datatype.h:1234

Compare

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

// This example compares the two given maxon::Data objects in multiple ways.
const maxon::COMPARERESULT res = dataA.Compare(dataB);
DiagnosticOutput("Data containers are equal.");
if (dataA.IsEqual(dataB))
DiagnosticOutput("Data containers are equal.");
if (dataA == dataB)
DiagnosticOutput("Data containers are equal.");
Py_UCS4 * res
Definition: unicodeobject.h:1113
COMPARERESULT
Data type for comparison results.
Definition: compare.h:21
@ EQUAL
result is equal

Utility

Further utility functions are:

// 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);
String ToString(const FormatStatement *formatStatement=nullptr) const
Definition: string.h:1237
void * str
Definition: bytesobject.h:77

Further Reading