OCArray

group OCArray

Array types and operations in OCTypes.

Typedefs

typedef const void *(*OCArrayRetainCallBack)(const void *value)

Callback to retain a value in the array.

Param value:

The value to be retained.

Return:

The retained value.

typedef void (*OCArrayReleaseCallBack)(const void *value)

Callback to release a value from the array.

Param value:

The value to be released.

typedef OCStringRef (*OCArrayCopyDescriptionCallBack)(const void *value)

Callback to copy a description string of a value.

Param value:

The value to describe.

Return:

An OCStringRef describing the value.

typedef bool (*OCArrayEqualCallBack)(const void *value1, const void *value2)

Callback to compare two values for equality.

Param value1:

First value.

Param value2:

Second value.

Return:

true if equal, false otherwise.

Functions

OCTypeID OCArrayGetTypeID(void)

Gets the OCTypeID for OCArray.

Returns:

OCTypeID value.

unsigned long OCArrayGetCount(OCArrayRef theArray)

Returns the number of elements in an array.

Parameters:

  • theArray – The array to query.

Returns:

Element count, or 0 if NULL.

OCArrayRef OCArrayCreate(const void **values, unsigned long numValues, const OCArrayCallBacks *callBacks)

Creates a new immutable array.

Parameters:

  • values – Pointer to value array.

  • numValues – Number of values.

  • callBacks – Pointer to value management callbacks.

Returns:

New OCArrayRef or NULL.

OCArrayRef OCArrayCreateCopy(OCArrayRef theArray)

Creates an immutable array copy.

Parameters:

  • theArray – Array to copy.

Returns:

New OCArrayRef or NULL.

OCMutableArrayRef OCArrayCreateMutable(unsigned long capacity, const OCArrayCallBacks *callBacks)

Creates a mutable array.

Parameters:

  • capacity – Initial capacity.

  • callBacks – Pointer to callbacks.

Returns:

New OCMutableArrayRef or NULL.

OCMutableArrayRef OCArrayCreateMutableCopy(OCArrayRef theArray)

Creates a mutable copy of an array.

Parameters:

  • theArray – The array to copy.

Returns:

New OCMutableArrayRef or NULL.

const void *OCArrayGetValueAtIndex(OCArrayRef theArray, unsigned long index)

Gets a value at a given index.

Parameters:

  • theArray – The array.

  • index – Zero-based index.

Returns:

Pointer to value or NULL.

bool OCArraySetValueAtIndex(OCMutableArrayRef theArray, OCIndex index, const void *value)

Replaces the value at the specified index in a mutable array.

Releases the existing value (if applicable) and retains the new value using the array’s callbacks.

Parameters:

  • theArray – The mutable array.

  • index – The index at which to set the value.

  • value – The new value.

Returns:

true if the operation succeeded; false if the array is NULL, the index is invalid, or memory operations failed.

bool OCArrayAppendValue(OCMutableArrayRef theArray, const void *value)

Appends a value to the end of a mutable array.

Retains the value using the array’s callbacks. Will reallocate storage if the internal capacity is exceeded.

Parameters:

  • theArray – The mutable array.

  • value – The value to append.

Returns:

true if the value was appended successfully; false if the array or value is NULL, or if allocation failed.

bool OCArrayContainsValue(OCArrayRef theArray, const void *value)

Checks whether a value is present in the array.

Uses the array’s equality callback to determine equivalence. If no callback is set, compares pointers directly. For kOCTypeArrayCallBacks, uses OCTypeEqual.

Parameters:

  • theArray – The array to check.

  • value – The value to look for.

Returns:

true if the value is found, false otherwise (including if array or value is NULL).

bool OCArrayAppendArray(OCMutableArrayRef theArray, OCArrayRef otherArray, OCRange range)

Appends a range of values from another array into a mutable array.

Each value is retained using the destination array’s callbacks.

Parameters:

  • theArray – The mutable destination array.

  • otherArray – The source array to copy from.

  • range – The range [location, location+length) of values to append from the source.

Returns:

true if all values were appended successfully; false if parameters are invalid or memory operations fail.

OCIndex OCArrayGetFirstIndexOfValue(OCArrayRef theArray, const void *value)

Finds the first index of a value in the array.

Uses the array’s equality callback to determine equivalence. If no callback is set, compares pointers directly. For kOCTypeArrayCallBacks, uses OCTypeEqual.

Parameters:

  • theArray – The array to search.

  • value – The value to search for.

Returns:

The index of the first matching value, or kOCNotFound if not found or if the array/value is NULL.

bool OCArrayRemoveValueAtIndex(OCMutableArrayRef theArray, unsigned long index)

Removes a value at a specific index from a mutable array.

The value is released using the array’s release callback. The remaining elements are shifted to fill the gap.

Parameters:

  • theArray – The mutable array.

  • index – The index of the value to remove.

Returns:

true if the value was removed successfully; false if the array is NULL or the index is out of bounds.

bool OCArrayInsertValueAtIndex(OCMutableArrayRef theArray, unsigned long index, const void *value)

Inserts a value into a mutable array at the specified index.

Shifts existing elements to make space, retains the new value using the array’s callbacks, and grows the internal buffer if needed.

Parameters:

  • theArray – The mutable array.

  • index – The index at which to insert the new value (must be ≤ count).

  • value – The value to insert.

Returns:

true if the value was inserted successfully; false on invalid input or allocation failure.

void OCArraySortValues(OCMutableArrayRef theArray, OCRange range, OCComparatorFunction comparator, void *context)

Sorts values in an array.

Parameters:

  • theArray – The array to sort.

  • range – Range of values to sort.

  • comparator – Comparison function.

  • context – User-defined data.

int64_t OCArrayBSearchValues(OCArrayRef array, OCRange range, const void *value, OCComparatorFunction comparator, void *context)

Performs a binary search on a sorted array.

Parameters:

  • array – The array to search.

  • range – Range to search.

  • value – The value to find.

  • comparator – Comparison function.

  • context – User-defined context.

Returns:

Index or kOCNotFound.

OCArrayRef OCArrayCreateWithArray(OCArrayRef array)

Creates a new immutable array from an existing one.

Parameters:

  • array – The source array.

Returns:

New OCArrayRef or NULL.

bool OCArrayIsHomogeneous(OCArrayRef array)

Checks if an array contains homogeneous OCNumber elements.

Determines if all elements in the array are OCNumbers of the same type. This is useful for optimizing JSON serialization and other operations that can benefit from type uniformity.

Parameters:

  • array – The array to check.

Returns:

1 if array is homogeneous (all same OCNumber type), 0 otherwise. Returns 0 for empty arrays, NULL arrays, or arrays with mixed types.

OCStringRef OCArrayCopyHomogeneousElementTypeName(OCArrayRef array)

Copy the element type name for a homogeneous array.

Returns the type name of elements in a homogeneous array. Should only be called after verifying homogeneity with OCArrayIsHomogeneous().

Parameters:

  • array – The homogeneous array to query.

Returns:

OCString describing the element type, or NULL if not homogeneous. Caller is responsible for releasing the returned string.

cJSON *OCArrayCopyAsJSON(OCArrayRef array, bool typed, OCStringRef *outError)

Serializes an OCArray to JSON format with homogeneous optimization.

TYPED MODE (typed=true):

  • Always uses individual element serialization to preserve type information

  • Format: [{“type”: “OCNumber”, “numeric_type”: “…”, “value”: …}, …]

  • Each element maintains its complete type metadata

UNTYPED MODE (typed=false):

  • Uses homogeneous array optimization when all elements are the same OCNumber type

  • Homogeneous complex arrays: r0,i0,r1,i1,r2,i2,…

  • Homogeneous real arrays: [v0,v1,v2,…] (direct values)

  • Mixed type arrays: Error - not supported in untyped mode

  • Size efficiency: 57% reduction for homogeneous complex arrays

Arrays are native JSON types, so they are not wrapped in type information even when typed=true.

Parameters:

  • array – A valid OCArrayRef.

  • typed – If true, use typed serialization; if false, use homogeneous optimization.

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

Returns:

A new cJSON array on success, or cJSON null on failure. The caller is responsible for managing the returned cJSON object.

OCArrayRef OCArrayCreateFromJSONTyped(cJSON *json, OCStringRef *outError)

Create an OCArrayRef from a JSON array with typed element deserialization.

Parses a native JSON array and deserializes each element using typed deserialization. Arrays are native JSON types, so the input is still a native JSON array, not a wrapped object.

Parameters:

  • json – A cJSON array.

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

Returns:

A newly allocated OCArrayRef, or NULL on failure.

OCArrayRef OCArrayCreateFromJSON(cJSON *json, OCStringRef *outError)

Create an OCArrayRef from untyped JSON with auto-detection.

Parses homogeneous array formats by auto-detecting the element type:

  • Complex arrays: [r0,i0,r1,i1,…] → Array of complex128 numbers

  • Real arrays: [v0,v1,v2,…] → Array of double numbers

  • String arrays: [“str1”,”str2”,…] → Array of OCStrings

  • Boolean arrays: [true,false,…] → Array of OCBooleans

  • Mixed arrays: Error - not supported in untyped deserialization

This function automatically detects the homogeneous type from the JSON content. Only supports homogeneous arrays (all elements must be the same JSON type).

Parameters:

  • json – A cJSON array in homogeneous format.

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

Returns:

A newly allocated OCArrayRef, or NULL on failure.

OCArrayRef OCArrayOfNumbersCreateFromJSON(cJSON *json, OCNumberType numberType, OCStringRef *outError)

Creates an OCArray of OCNumbers from JSON with explicit type specification.

This function creates an OCArray containing only OCNumber objects from a JSON array, with each number created using the specified OCNumberType. This is designed for use with optimized OCArray serialization where all numbers have the same type.

For complex number types, the JSON array should contain flattened real/imaginary pairs: [real0, imag0, real1, imag1, …]. For real number types, the JSON array contains the values directly: [value0, value1, value2, …].

Parameters:

  • json – A cJSON array containing numeric values.

  • numberType – The OCNumberType to use for all created OCNumber objects.

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

Returns:

A newly allocated OCArrayRef containing OCNumber objects, or NULL on failure.

const OCArrayCallBacks *OCArrayGetCallBacks(OCArrayRef array)

Returns the callback structure associated with the array.

Parameters:

  • array – The array.

Returns:

Pointer to the array’s OCArrayCallBacks, or NULL if not available.

Variables

const OCArrayCallBacks kOCTypeArrayCallBacks

Predefined callbacks for arrays of OCTypeRef objects.

struct OCArrayCallBacks
#include <OCArray.h>

Struct defining callbacks for array value management.

Public Members

int64_t version

Structure version (should be 0).

OCArrayRetainCallBack retain

Retain callback.

OCArrayReleaseCallBack release

Release callback.

OCArrayCopyDescriptionCallBack copyDescription

Description callback.

OCArrayEqualCallBack equal

Equality comparison callback.