kType.h

Go to the documentation of this file.

/** 
 * @file    kType.h
 * @brief   Declarations related to the kType system. 
 *
 * @internal
 * Copyright (C) 2005-2014 by LMI Technologies Inc.
 * Licensed under the MIT License.
 * Redistributed files must retain the above copyright notice.
 */
#include <kApi/kApiDef.h>   //--inclusion order controlled by kApiDef

#ifndef K_API_TYPE_H
#define K_API_TYPE_H

kBeginHeader()

#define kTypeName kText64       ///< Alias for type used to store a kType text name. 

/**
 * @struct  kTypeFlag
 * @extends kValue
 * @ingroup kApi  
 * @brief   Represents an enumeration of type flags. 
 * 
 * The following enumerators are defined:  
 * - #kTYPE_FLAGS_CLASS
 * - #kTYPE_FLAGS_INTERFACE
 * - #kTYPE_FLAGS_VALUE
 * - #kTYPE_FLAGS_VALUE
 * - #kTYPE_FLAGS_ENUM
 * - #kTYPE_FLAGS_BIT_ENUM
 * - #kTYPE_FLAGS_ABSTRACT
 */
typedef k32u kTypeFlags; 

#define kTYPE_FLAGS_CLASS          (0x01)       ///< Type is a class.
#define kTYPE_FLAGS_INTERFACE      (0x02)       ///< Type is an interface. 
#define kTYPE_FLAGS_VALUE          (0x04)       ///< Type is a value. 
#define kTYPE_FLAGS_ENUM           (0x08)       ///< Type is an enumeration.
#define kTYPE_FLAGS_BIT_ENUM       (0x10)       ///< Type is a bitset enumeration. 
#define kTYPE_FLAGS_ABSTRACT       (0x20)       ///< Type is an abstract class. 
#define kTYPE_FLAGS_ARRAY_VALUE    (0x40)       ///< Type is an array-based value (e.g. kText32).

/**
 * @struct  kTypeVersion
 * @ingroup kApi  
 * @brief   Represents an opaque reference to type version information (used in object serialization). 
 */
typedef kPointer kTypeVersion; 

/**
 * @class   kType
 * @extends kObject
 * @ingroup kApi
 * @brief   Represents metadata about a type (class, interface, or value). 
 * 
 * When an assembly is constructed, one kType instance is created for every type defined in the assmebly. 
 * kAssembly methods can be used to discover the types in the assembly, and kType methods can be used to 
 * learn about individual types (e.g., type name, base class). 
 * 
 * The kObject_Type method can be used to obtain type information for any object derived from kObject. 
 * The kTypeOf macro can be used to obtain type information for any class, interface, or value by 
 * compile-time type symbol. 
 * 
 * @code
 * 
 * kBool IsImageType(kObject object)
 * {
 *     kType objectType = kObject_Type(object); 
 *     kType imageType = kTypeOf(kImage);  
 *     
 *     return objectType == imageType; 
 * } 
 * 
 * @endcode
 * 
 */
//typedef kObject kType;   --forward-declared in kApiDef.x.h

/** 
 * Gets the assembly to which the type belongs. 
 *
 * @public              @memberof kType
 * @param   type        Type. 
 * @return              Assembly. 
 */
kFx(kAssembly) kType_Assembly(kType type); 

/** 
 * Gets the name of the type. 
 *
 * @public              @memberof kType
 * @param   type        Type. 
 * @return              Type name. 
 */
kFx(const kChar*) kType_Name(kType type); 

/** 
 * Determines whether a type is equivalent to another type. 
 *
 * Checks type equality, inheritance, and interfaces. 
 *
 * @public              @memberof kType
 * @param   type        Type to be compared. 
 * @param   other       Type to which type is compared. 
 * @return              kTRUE if type is equivalent. 
 */
kFx(kBool) kType_Is(kType type, kType other);

/** 
 * Determines whether a type represents a value (primitive, struct, enum). 
 *
 * @public              @memberof kType
 * @param   type        Type. 
 * @return              kTRUE if type represents a value.  
 */
kFx(kBool) kType_IsValue(kType type);

/** 
 * Determines whether a type represents a class. 
 *
 * @public              @memberof kType
 * @param   type        Type. 
 * @return              kTRUE if type represents a class.  
 */
kFx(kBool) kType_IsClass(kType type);

/** 
 * Determines whether a type represents an interface.  
 *
 * @public              @memberof kType
 * @param   type        Type. 
 * @return              kTRUE if type represents an interface. 
 */
kFx(kBool) kType_IsInterface(kType type); 

/** 
 * Determines whether a type represents a class or interface. 
 *
 * @public              @memberof kType
 * @param   type        Type. 
 * @return              kTRUE if type represents a reference. 
 */
kFx(kBool) kType_IsReference(kType type);

/** 
 * Determines whether a type represents an abstract class. 
 *
 * @public              @memberof kType
 * @param   type        Class type. 
 * @return              kTRUE if type is abstract. 
 */
kFx(kBool) kType_IsAbstract(kType type);

/** 
 * Reports whether the type is an enumeration. 
 *
 * @public          @memberof kType
 * @return          kTRUE if the type is an enumeration; otherwise, kFALSE. 
 */
kFx(kBool) kType_IsEnum(kType type);

/** 
 * Reports whether the type is an enumeration bitset. 
 *
 * @public          @memberof kType
 * @return          kTRUE if the type is an enumeration bitset; otherwise, kFALSE. 
 */
kFx(kBool) kType_IsBitEnum(kType type);

/** 
 * Reports whether the type is an 'array-value' type (e.g., kText32)
 *
 * @public          @memberof kType
 * @return          kTRUE if the type is an 'array-value' type; otherwise, kFALSE. 
 */
kFx(kBool) kType_IsArrayValue(kType type);

/** 
 * Determines whether a type implements a specific interface.  
 *
 * @public                  @memberof kType
 * @param   type            Type. 
 * @param   interfaceType   Interface type. 
 * @return                  kTRUE if type implements interface. 
 */
kFx(kBool) kType_Implements(kType type, kType interfaceType);

/** 
 * Determines whether a type extends another type. 
 *
 * @public                  @memberof kType
 * @param   type            Type. 
 * @param   baseType        Base type. 
 * @return                  kTRUE if type extends base type.
 */
kFx(kBool) kType_Extends(kType type, kType baseType);

/** 
 * Gets the base of a class or interface. 
 *
 * @public                  @memberof kType
 * @param   type            Type.
 * @return                  Base type (or kNULL if none). 
 */
kFx(kType) kType_Base(kType type); 

/** 
 * Gets the external size of a type. 
 *
 * The external size of a value type reflects the size of the struct, value or enum. The external size of a reference 
 * type is equal to the size of a pointer. 
 *
 * @public                  @memberof kType
 * @return                  Type size. 
 */
kFx(kSize) kType_Size(kType type);

/** 
 * Gets the internal size of a type. 
 *
 * The internal size of a value type reflects the size of the struct, value or enum. The internal size of a reference 
 * type is equal to the size of its class structure. 
 *
 * @public                  @memberof kType
 * @return                  Type size. 
 */
kFx(kSize) kType_InnerSize(kType type);

/** 
 * Gets a pointer to the type's primary virtual method table. 
 *
 * @public          @memberof kType
 * @return          Virtual table pointer.
 */
kFx(kFunction*) kType_VTable(kType type);

/** 
 * Gets a pointer to the type's virtual method table corresponding to the specified interface type. 
 *
 * @public          @memberof kType
 * @return          Interface virtual table pointer.
 */
kFx(kFunction*) kType_IVTable(kType type, kType interfaceType);

/** 
 * Gets a pointer to the type's static data structure. 
 *
 * @public          @memberof kType
 * @return          Pointer to static data. 
 */
kFx(void*) kType_Static(kType type);

/** 
 * Reports whether the type's static data structure has been successfully initialized. 
 * 
 * This function can be helpful during startup, to determine whether the static data for a particular type 
 * has been initialized. This function is not thread-safe.
 *
 * @public          @memberof kType
 * @return          kTRUE if static data has been initialized; otherwise, kFALSE. 
 */
kFx(kBool) kType_StaticInitialized(kType type); 

#define kType_Assembly_(TYPE)           kxType_Assembly_(TYPE)                  ///< Macro version of kType_Assembly. 
#define kType_Is_(TYPE, OTHER)          kxType_Is_(TYPE, OTHER)                 ///< Macro version of kType_Is. 
#define kType_IsValue_(TYPE)            kxType_IsValue_(TYPE)                   ///< Macro version of kType_IsValue. 
#define kType_IsClass_(TYPE)            kxType_IsClass_(TYPE)                   ///< Macro version of kType_IsClass. 
#define kType_IsInterface_(TYPE)        kxType_IsInterface_(TYPE)               ///< Macro version of kType_IsInterface. 
#define kType_IsAbstract_(TYPE)         kxType_IsAbstract_(TYPE)                ///< Macro version of kType_IsAbstract. 
#define kType_IsReference_(TYPE)        kxType_IsReference_(TYPE)               ///< Macro version of kType_IsReference.
#define kType_IsEnum_(TYPE)             kxType_IsEnum_(TYPE)                    ///< Macro version of kType_IsEnum. 
#define kType_IsBitEnum_(TYPE)          kxType_IsBitEnum_(TYPE)                 ///< Macro version of kType_IsBitEnum. 
#define kType_IsArrayValue_(TYPE)       kxType_IsArrayValue_(TYPE)              ///< Macro version of kType_IsArrayValue. 
#define kType_Implements_(TYPE, IFACE)  kxType_Implements_(TYPE, IFACE)         ///< Macro version of kType_Implements. 
#define kType_Extends_(TYPE, BASE)      kxType_Extends_(TYPE, BASE)             ///< Macro version of kType_Extends. 
#define kType_Base_(TYPE)               kxType_Base_(TYPE)                      ///< Macro version of kType_Base. 
#define kType_Size_(TYPE)               kxType_Size_(TYPE)                      ///< Macro version of kType_Size. 
#define kType_InnerSize_(TYPE)          kxType_InnerSize_(TYPE)                 ///< Macro version of kType_InnerSize. 
#define kType_VTable_(TYPE)             kxType_VTable_(TYPE)                    ///< Macro version of kType_VTable. 
#define kType_Static_(TYPE)             kxType_Static_(TYPE)                    ///< Macro version of kType_Static. 

kEndHeader()

#include <kApi/kType.x.h>

#endif