DataType Manual

Table of Contents

• About
• Creation
• Conversion
• DataType Comparison
• Value Comparison
• Construct
• Interfaces
• Disc I/O
• Properties
• Further Reading

About

A maxon::DataType object represents a registered data type of the MAXON API. It is used to check the type of some given data at run time or to write generic template code.

Creation

The maxon::DataType object representing a specific data type can be accessed with maxon::GetDataType():

• maxon::GetDataType(): Returns the maxon::DataType object representing the given data type.

    // This example gets the maxon::DataType for the given type.
 
    const maxon::DataType dt = maxon::GetDataType<maxon::Int32>();
    DiagnosticOutput("DataType: @", dt);

Note

Further utility functions can be found in the maxon::DataTypeLib.

Conversion

The maxon::DataType object is used to register and apply specific conversions from and to the defined data type.

• maxon::DataType::AddConversion(): Registers a conversion delegate function from the source type to this maxon::DataType.
• maxon::DataType::Convert(): Converts the source value to the target value.
• maxon::DataType::IsCastableFrom(): Returns true if the given maxon::DataType can be cast into the data type.
• maxon::DataType::IsCastableTo(): Returns true if the data type can be cast in to the given maxon::DataType.

Available conversion types are:

• maxon::CONVERSION_FLAGS::IDENTITY: The conversion contains an identity conversion such as from Vector to Color.
• maxon::CONVERSION_FLAGS::NARROWING: The conversion is a narrowing conversion. The conversion may not always be possible (such as converting a negative maxon::Int to a maxon::UInt), then it returns an error.
• maxon::CONVERSION_FLAGS::WIDENING_LOSSY: The conversion is a widening conversion which is always possible, but it might result in loss of precision (a maxon::Float64 can't represent all bits of an maxon::Int64).
• maxon::CONVERSION_FLAGS::WIDENING_LOSSLESS: The conversion is a lossless widening conversion.
• maxon::CONVERSION_FLAGS::EXPANDING: The conversion contains a expanding conversion such as from a scalar to a vector.
• maxon::CONVERSION_FLAGS::REDUCING: The conversion contains a reducing conversion such as from a vector to a scalar.

    // This example adds a conversion for a custom data type and uses it to convert it into a maxon::Vector.
 
    // add conversion
 
    maxon::DataType::AddConversion<maxon::Vector, IntegerTriplet>(
      maxon::CONVERSION_FLAGS::WIDENING_LOSSY,
      [](maxon::Vector& dest, const IntegerTriplet& src) -> maxon::Result<void>
      {
        dest.x = maxon::Float(src._a);
        dest.y = maxon::Float(src._b);
        dest.z = maxon::Float(src._c);
 
        return maxon::OK;
      }) iferr_return;
 
    // convert
 
    // prepare data
    IntegerTriplet triplet;
    triplet._a = 10; triplet._b = 20; triplet._c = 30;
 
    // get DataType
    const maxon::DataType dt = maxon::GetDataType<maxon::Vector>();
 
    if (dt)
    {
      // convert
      maxon::Vector                 vec;
      maxon::Generic* const         generic = reinterpret_cast<maxon::Generic*>(&vec);
      const maxon::ConstDataPtr     ptr = maxon::ConstDataPtr(triplet);
      const maxon::CONVERSION_FLAGS ignore = maxon::CONVERSION_FLAGS::NONE;
 
      dt.Convert(*generic, ptr, ignore) iferr_return;
      DiagnosticOutput("Vector: @", vec);
    }

DataType Comparison

Two maxon:DataType objects can be compared using the "==" operator or with some more sophisticated functions:

• maxon::DataType::IsBaseOfOrSame(): Returns true if this type is a base type of the given maxon::DataType.
• maxon::DataType::IsSimilar(): Returns true if this type is similar to the given maxon::DataType.

Value Comparison

Using the maxon::DataType object it is also possible two compare two object of this data type:

• maxon::DataType::IsEqual(): Returns true if the two given objects are equal.
• maxon::DataType::Compare(): Returns the compare result of the two given objects.
• maxon::DataType::GetHashCode(): Returns a hash value for the given object.

// This example shows a template function that compares two values
// of the given type and prints the result to the debug console.
 
template <typename T> static maxon::Result<void> CompareAndPrint(T a, T b)
{
  const maxon::DataType dt = maxon::GetDataType<T>();
  if (!dt)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Unknown data type."_s);
 
  if (!dt->IsEqual(&a, &b, maxon::EQUALITY::DEEP))
  {
    const maxon::COMPARERESULT res = dt->Compare(&a, &b);
    DiagnosticOutput("Compare result: @", res);
  }
  else
  {
    DiagnosticOutput("Values are equal.");
  }
 
  return maxon::OK;
}

Construct

The maxon::DataType object can be used to create new object instances of the define type:

• maxon::DataType::Create(): Returns a new instance of the type.
• maxon::DataType::Construct(): Creates multiple instances of the type.
• maxon::DataType::MoveConstruct(): Moves constructs multiple instances of the type.
• maxon::DataType::Destruct(): Destroys multiple instances of the type.
• maxon::DataType::MoveFrom(): Moves multiple instances of the type to a target location.
• maxon::DataType::CopyFrom(): Copies multiple instances of the type to the target location.

// This example shows a template function that will only work if used with a certain type.
 
template <typename T> static maxon::Result<void> FillIntNumbers(void* mem, maxon::Int count)
{
  // get data type
  const maxon::DataType dt = maxon::GetDataType<T>();
  if (!dt)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Unknown data type."_s);
 
  // compare to legit data types
 
  const maxon::DataType int_dt   = maxon::GetDataType<maxon::Int>();
  const maxon::DataType uint_dt  = maxon::GetDataType<maxon::UInt>();
 
  const maxon::Bool isIntDataType  = dt == int_dt;
  const maxon::Bool isUIntDataType = dt == uint_dt;
 
  if (!(isIntDataType || isUIntDataType))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Template function used with invalid type."_s);
 
  // create numbers
  dt->Construct(mem, 0, count);
 
  return maxon::OK;
}

Interfaces

Also interfaces are registered as a maxon::DataType.

• maxon::DataType::GetImplementation(): Returns the interface implementation of this type.
• maxon::DataType::GetInterfaces(): Returns the interfaces of this object type.

Disc I/O

Data stored in an object of a given maxon::DataType can be written to a file. How this is done is described by a maxon::DataSerializeInterface object.

• maxon::DataType::DescribeIO(): Describes all elements of this data type for I/O operations.

Properties

The maxon::DataType object gives access to various properties of the described data type:

• maxon::DataType::ToString(): Returns a maxon::String of the data type name.
• maxon::DataType::GetId(): Returns the unique maxon::Id for the data type.

    // This example gets a maxon::String and a maxon::Id of the given maxon::DataType.
 
    const maxon::String name = dt.ToString(nullptr);
    const maxon::Id     id = dt.GetId();
 
    DiagnosticOutput("Data Type @, (@)", name, id);

The maxon::DataType object also provides information on the type of data:

• maxon::DataType::GetSize(): Returns the size of values of the data type.
• maxon::DataType::GetAlignment(): Returns the alignment of values of the data type.
• maxon::DataType::GetValueKind(): Returns the kind of values of this data type. See maxon::VALUEKIND.
• maxon::DataType::CheckValueKind(): Returns true if the data type is of the given maxon::VALUEKIND.

    // This example accesses basic information on the given maxon::DataType and prints it to the debug console.
 
    const maxon::Int size = dt.GetSize();
    const maxon::Int alignment = dt.GetAlignment();
    DiagnosticOutput("Size @, Alignment @", size, alignment);
 
    const maxon::VALUEKIND valueKind = dt->GetValueKind();
    DiagnosticOutput("Type settings: @", valueKind);

It is possible to register a data type using MAXON_DATATYPE_REGISTER_STRUCT. This will inform Cinema 4D about public members of the type. The maxon::DataType object can be used to list these public members.

• maxon::DataType::GetTupleType(): Returns the underlying tuple type of this data type.
• maxon::DataType::GetTypeArguments(): Returns the member names for the underlying structure type.

See also maxon::TypeArguments and maxon::Member.

    // This example accesses and loops through all registered named members
    // of the given maxon::DataType.
 
    const maxon::VALUEKIND kind = dt.GetValueKind();
 
    // check if structure
    if (kind & maxon::VALUEKIND::STRUCT)
    {
      const maxon::TupleDataType tupleData = dt.GetTupleType();
      if (tupleData)
      {
        const maxon::TypeArguments& args = tupleData.GetTypeArguments();
 
        // loop through all members
        for (maxon::Int i = 0; i < args.count; ++i)
        {
          const maxon::Member    member = args.args[i];
          const maxon::Id        memberName = member.name;
          const maxon::DataType  memberType = member.type;
 
          DiagnosticOutput("Member @ (@)", memberName, memberType);
        }
      }
    }

Further Reading

• Data & Algorithms
• MAXON Data Type
• Data Manual