OCType

group OCType

Core type definitions and memory management functions.

Defines

IF_NO_OBJECT_EXISTS_RETURN(OBJECT, X)

Macro to check if an object is NULL and return a specified value if it is.

Parameters:

  • OBJECT – The object to check.

  • X – The value to return if OBJECT is NULL.

Typedefs

typedef void (*OCFinalizerFunc)(const void*)

Function type for finalizing an OCType-compatible object.

Enums

enum CommonConstants

Return value constants.

Values:

enumerator kOCNotFound

Value returned when an item is not found.

enum SpecialTypeIDs

Special OCTypeID constants.

Values:

enumerator kOCNotATypeID

Represents an invalid or uninitialized OCTypeID.

enum OCJSONEncoding

JSON encoding options for OCTypes serialization.

These constants control how OCTypes are encoded in JSON format:

  • OCJSONEncodingNone: Use standard JSON representation (arrays, numbers)

  • OCJSONEncodingBase64: Use base64-encoded binary representation for compactness

Values:

enumerator OCJSONEncodingNone
enumerator OCJSONEncodingBase64

Functions

OCTypeID OCRegisterType(const char *typeName, OCTypeRef (*factory)(cJSON*, OCStringRef*))

Registers a new OCType with the system and optional JSON factory.

This function registers a type name with the OCTypes system and optionally associates a JSON factory function for creating instances from typed JSON.

Parameters:

  • typeName – A null-terminated C string representing the type name.

  • factory – Optional function pointer to create instances from typed JSON.

  • typeName – A null-terminated C string representing the type name.

  • factory – Optional function pointer to create instances from typed JSON. Pass NULL if the type doesn’t support typed JSON serialization.

Returns:

The OCTypeID assigned, or kOCNotATypeID on failure.

Returns:

The OCTypeID assigned, or kOCNotATypeID on failure.

bool OCTypeEqual(const void *theType1, const void *theType2)

Compares two OCType instances for equality.

Parameters:

  • theType1 – Pointer to the first OCType.

  • theType2 – Pointer to the second OCType.

Returns:

true if equal, false otherwise.

void *OCTypeDeepCopy(const void *obj)

Performs a deep copy of an OCType object.

Allocates and returns a new immutable instance that is semantically equal to the original but independent in memory.

The returned object must be released with OCRelease().

Parameters:

  • obj – The OCType object to copy.

Returns:

A new deep-copied object, or NULL on failure.

void *OCTypeDeepCopyMutable(const void *obj)

Performs a deep copy of an OCType object, returning a mutable copy.

Allocates and returns a new mutable instance that is semantically equal to the original but allows modification and is independent in memory.

The returned object must be released with OCRelease().

Parameters:

  • obj – The OCType object to copy.

Returns:

A new mutable deep-copied object, or NULL on failure.

int OCTypeGetRetainCount(const void *ptr)

Retrieves the retain count of an OCType instance.

Parameters:

  • ptr – Pointer to the OCType instance.

Returns:

The retain count, or 0 if NULL.

void OCRelease(const void *ptr)

Releases an OCType instance by decrementing its retain count.

When the retain count reaches zero, the finalizer (if any) is invoked.

Parameters:

  • ptr – Pointer to the OCType to release.

const void *OCRetain(const void *ptr)

Retains an OCType instance by incrementing its retain count.

Ownership follows the convention:

  • Functions named with “Create” or “Copy” return owned objects (caller must release).

  • Other functions return autoreleased or borrowed objects.

Parameters:

  • ptr – Pointer to the OCType to retain.

Returns:

The same pointer, or NULL if input was NULL.

OCStringRef OCTypeCopyFormattingDesc(const void *ptr)

Returns a formatted string description of an OCType.

Parameters:

  • ptr – Pointer to the OCType instance.

Returns:

A descriptive OCStringRef or NULL.

cJSON *OCTypeCopyJSON(OCTypeRef obj, bool typed, OCStringRef *outError)

Returns a JSON representation of an OCType instance.

This function serializes the given OCType instance to a cJSON object. The behavior depends on the typed parameter and the OCType subclass:

When typed=false:

  • Returns a schema-bound JSON representation without type information

  • Assumes deserialization will occur in a context where the expected type is known

  • The resulting JSON is not self-describing

When typed=true:

  • Native JSON types (OCString, OCBoolean, OCArray, OCDictionary): Serialized as native JSON without type wrappers (e.g., strings as JSON strings, arrays as JSON arrays)

  • Non-native JSON types (OCNumber, OCData, custom types): Serialized with type information in a wrapper object containing “type” and “value” fields

  • The resulting JSON can be deserialized without external knowledge of the expected type

The returned cJSON object must be freed by the caller using cJSON_Delete().

Parameters:

  • obj – Pointer to the OCType instance. If NULL, returns a JSON null.

  • typed – If true, use self-describing format when necessary; if false, use schema-bound format.

  • outError – Optional pointer to receive an error string on failure.

Returns:

A cJSON object representing the instance, or cJSON null if obj is NULL or on error.

OCTypeRef OCTypeCreateFromJSONTyped(cJSON *json, OCStringRef *outError)

Creates an OCType instance from a self-describing JSON object.

This function deserializes a cJSON object that was created by OCTypeCopyJSON() with typed=true or follows the same self-describing format. The function handles both wrapped and unwrapped JSON based on the input:

  • Native JSON types: Directly handles JSON strings, booleans, arrays, and objects without requiring type wrappers.

  • Wrapped types: Examines the “type” field in JSON objects and dispatches to the appropriate createFromJSONTyped implementation for that type.

Note

The returned object must be released with OCRelease() when no longer needed.

Parameters:

  • json – A cJSON object that may contain self-describing type information or be a native JSON type.

Returns:

A new OCType instance with retain count 1, or NULL if deserialization fails.

OCStringRef OCCopyDescription(const void *ptr)

Returns a generic description of an OCType instance.

Parameters:

  • ptr – Pointer to the OCType instance.

Returns:

A description string.

bool OCTypeGetStaticInstance(const void *ptr)

Checks if an OCType instance is static.

Parameters:

  • ptr – Pointer to the instance.

Returns:

true if static, false otherwise.

void OCTypeSetStaticInstance(const void *ptr, bool static_instance)

Marks an OCType instance as static or non-static.

Parameters:

  • ptr – Pointer to the instance.

  • static_instance – Whether the object is static.

bool OCTypeGetFinalized(const void *ptr)

Checks if an OCType instance has been finalized.

Parameters:

  • ptr – Pointer to the instance.

Returns:

true if finalized, false otherwise.

OCTypeID OCGetTypeID(const void *ptr)

Returns the type ID of an OCType instance.

Parameters:

  • ptr – Pointer to the instance.

Returns:

A valid OCTypeID or kOCNotATypeID.

const char *OCTypeIDName(const void *ptr)

Returns the registered name of a type given an instance.

Parameters:

  • ptr – Pointer to the instance.

Returns:

Type name string.

const char *OCTypeNameFromTypeID(OCTypeID typeID)