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 ALIASES. 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