Object Interface

Table of Contents

• About
• Methods
• Functions
• Internal
• Implementation
• Usage
• Further Reading

About

The maxon::ObjectInterface interface is the base of all interfaces. It defines the most basic functionality of all interface based objects. A custom implementation can (re)implement the methods of this interface.

Note

Every component can also implement various basic functions, see Default Functions.

Methods

These functions of the maxon::ObjectInterface interface are marked with MAXON_METHOD. They can be implemented in any interface based on maxon::ObjectInterface and are added to the reference class.

General Functions:

• maxon::ObjectInterface::InitObject(): Initializes the object. It is called after InitComponent().
• maxon::ObjectInterface::ToString(): Returns a readable string of the content. See FormatStatement Manual.

Comparison and Identity:

• maxon::ObjectInterface::IsEqual(): Returns true if the given object is equal.
• maxon::ObjectInterface::Compare(): Compares the object with the given object and returns a maxon::COMPARERESULT.
• maxon::ObjectInterface::GetHashCode(): Returns a hash value of the content.

Note

The hash values returned by maxon::ObjectInterface::GetHashCode() should be used for hash tables etc. They should not be used for security related tasks e.g. storing password hashes.

For interfaces of the type MAXON_REFERENCE_NORMAL the hash value is based on the pointer; the method is not called. Only for copy-on-write interfaces the method is called.

It is advised to call the super function within maxon::ObjectInterface::IsEqual() etc. since a component may be reused in an unpredicted context.

Functions

These function are marked with MAXON_FUNCTION. They cannot be implemented in a component but can be used in an implementation and in the reference class.

Component classes and interfaces:

• maxon::ObjectInterface::GetClass(): Returns the component class of the object.
• maxon::ObjectInterface::GetClassInfo(): Returns the class information of this object.
• maxon::ObjectInterface::HasSameClass(): Returns true if the given object has the same class.
• maxon::ObjectInterface::IsInstanceOf(): Returns true if the object is an instance of the given interface.

Utility:

• maxon::ObjectInterface::Clone(): Creates a clone of the object.

Internal

This function can only be used inside an implementation:

• maxon::ObjectInterface::GetComponentInfoOfSuper(): Returns the maxon::ComponentInfo iterator for all included components.

Implementation

// This example shows the implementation of basic maxon::ObjectInterface methods.
 
// implementation of AtomInterface
class AtomImpl : public maxon::Component<AtomImpl, AtomInterface>
{
  MAXON_COMPONENT();
 
public:
  // AtomInterface methods
 
  MAXON_METHOD maxon::Result<void> SetAtomData(maxon::Int protonCnt, maxon::Int neutronCnt, maxon::Int electronCnt)
  {
    _protonCnt = protonCnt; _neutronCnt = neutronCnt; _electronCnt = electronCnt;
    return maxon::OK;
  }
  MAXON_METHOD maxon::Result<void> GetAtomData(maxon::Int& protonCnt, maxon::Int& neutronCnt, maxon::Int& electronCnt) const
  {
    protonCnt = _protonCnt; neutronCnt = _neutronCnt; electronCnt = _electronCnt;
    return maxon::OK;
  }
 
  // maxon::ObjectInterface methods
 
  MAXON_METHOD maxon::Result<void> InitObject(const void* argument)
  {
    // every new atom should be hydrogen by default
    _protonCnt = 1;
    _electronCnt = 1;
    _neutronCnt  = 0;
 
    return maxon::OK;
  }
 
  MAXON_METHOD maxon::COMPARERESULT Compare(const maxon::ObjectInterface* other) const
  {
    const maxon::COMPARERESULT superCompare = super.Compare(other);
    if (superCompare != maxon::COMPARERESULT::EQUAL)
      return superCompare;
 
    const AtomImpl* const atom = GetOrNull(other);
    if (!atom)
      return maxon::COMPARERESULT::INCOMPARABLE;
 
    const maxon::Int sum = _protonCnt
                           + _neutronCnt
                           + _electronCnt;
 
    const maxon::Int sumOther = atom->_protonCnt
                                + atom->_neutronCnt
                                + atom->_electronCnt;
 
    if (sum < sumOther)
      return maxon::COMPARERESULT::LESS;
 
    if (sum > sumOther)
      return maxon::COMPARERESULT::GREATER;
 
    return maxon::COMPARERESULT::EQUAL;
  }
 
  MAXON_METHOD maxon::String ToString(const maxon::FormatStatement* formatStatement) const
  {
    return FormatString("Protons: @, Neutrons: @, Electrons: @", _protonCnt, _neutronCnt, _electronCnt);
  }
 
  // implementing maxon::ComponentRoot::CopyFrom()
  maxon::Result<void> CopyFrom(const AtomImpl& atom)
  {
    _protonCnt   = atom._protonCnt;
    _neutronCnt  = atom._neutronCnt;
    _electronCnt = atom._electronCnt;
 
    return maxon::OK;
  }
 
private:
  maxon::Int _protonCnt   = 0;  
  maxon::Int _neutronCnt  = 0;  
  maxon::Int _electronCnt = 0;  
};

In a copy-on-write interface also maxon::ObjectInterface::GetHashCode() can be implemented.

// This example shows an implementation of a COW interface. It implements GetHashCodeImpl().
 
// implementation of ErrorCodeInterface
class ErrorCodeImp : public maxon::Component<ErrorCodeImp, ErrorCodeInterface>
{
  MAXON_COMPONENT();
 
public:
  // ErrorCodeInterface methods
 
  MAXON_METHOD void SetErrorCode(maxon::Int errorCode) { _error = errorCode; }
  MAXON_METHOD maxon::Int GetErrorCode() const { return _error; }
  MAXON_METHOD void SetTimestamp(maxon::UInt timestamp) { _timestamp = timestamp; }
  MAXON_METHOD maxon::UInt GetTimeStamp() const { return _timestamp; }
 
  // maxon::ObjectInterface methods
 
  MAXON_METHOD maxon::Bool IsEqual(const maxon::ObjectInterface* other) const
  {
    const maxon::Bool superEqual = super.IsEqual(other);
    if (!superEqual)
      return false;
 
    const ErrorCodeImp* const error = GetOrNull(other);
    if (!error)
      return false;
 
    if (_error != error->_error)
      return false;
    if (_timestamp != error->_timestamp)
      return false;
 
    return true;
  }
 
  MAXON_METHOD maxon::UInt GetHashCodeImpl() const
  {
    // from maxon/crc32c.h
    maxon::Crc32C crc;
 
    const maxon::UInt superHash = super.GetHashCodeImpl();
 
    crc.UpdateUInt(superHash);
    crc.UpdateInt(_error);
    crc.UpdateUInt(_timestamp);
 
    return crc.GetCrc();
  }
 
  // implementing maxon::ComponentRoot::CopyFrom()
  maxon::Result<void> CopyFrom(const ErrorCodeImp& error)
  {
    _error = error._error;
    _timestamp = error._timestamp;
 
    return maxon::OK;
  }
 
private:
  maxon::Int  _error = 0;       
  maxon::UInt _timestamp = 0;   
};

Usage

Basic methods of maxon::ObjectInterface are simply used with the reference object:

  // This example shows how to use basic maxon::ObjectInterface functions.
 
  const AtomRef hydrogen = componentClass.Create() iferr_return;
 
  // use ToString()
  DiagnosticOutput("Hydrogen: @", hydrogen);
 
  const AtomRef oxygen = componentClass.Create() iferr_return;
  oxygen.SetAtomData(8, 8, 8) iferr_return;
 
  // use ToString()
  DiagnosticOutput("Oxygen: @", oxygen);
 
  // compare
 
  if (hydrogen.IsEqual(oxygen) == false)
    DiagnosticOutput("The atoms are not equal!");
 
  const maxon::UInt hashHydrogen = hydrogen.GetHashCode();
  const maxon::UInt hashOxygen = oxygen.GetHashCode();
 
  DiagnosticOutput("Hashes: @, @", hashHydrogen, hashOxygen);
 
  // use Object::IsInstanceOf()
  if (!hydrogen.IsInstanceOf<AtomInterface>())
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // use Object::Clone()
  const AtomRef clone = hydrogen.Clone() iferr_return;
  DiagnosticOutput(clone.ToString(nullptr));

References of a copy-on-write interface are used like this:

  // This example shows how to use COW objects and when data will be copied.
 
  ErrorCode error = ErrorComponentClass.Create() iferr_return;
 
  error.SetErrorCode(100) iferr_return;
  error.SetTimestamp(10000) iferr_return;
 
  ErrorCode copy = error;
 
  // GetHashCodeImpl() of the implementation is called
  maxon::UInt hashA = error.GetHashCode();
  maxon::UInt hashB = copy.GetHashCode();
 
  DiagnosticOutput("Hashes: @, @", hashA, hashB);
 
  // this will call CopyFrom() to create a new instance
  copy.SetErrorCode(200) iferr_return;
 
  hashA = error.GetHashCode();
  hashB = copy.GetHashCode();
 
  DiagnosticOutput("Hashes: @, @", hashA, hashB);

Further Reading

• Base Interfaces
• Interface Basics
• Interface Declaration
• Using Interfaces
• Interface Implementation
• Interface Inheritance
• Interface Methods