OCIndexArray

group OCIndexArray

Array types and operations for OCIndex values in OCTypes.

This group includes APIs to create, access, modify, and serialize arrays of OCIndex elements, including Base64 conversion and CF-compatible array export.

Functions

OCTypeID OCIndexArrayGetTypeID(void)

Returns the unique OCTypeID for OCIndexArray.

Returns:

The OCTypeID corresponding to OCIndexArray.

OCIndexArrayRef OCIndexArrayCreate(OCIndex *indexes, OCIndex numValues)

Creates an immutable OCIndexArray from a C array of OCIndex values.

Parameters:

• indexes – Pointer to a C array of OCIndex.

• numValues – Number of elements in the array.

Returns:

A new OCIndexArrayRef instance containing a copy of the provided values, or NULL on failure.

OCMutableIndexArrayRef OCIndexArrayCreateMutable(OCIndex capacity)

Creates a mutable OCIndexArray with the given initial capacity.

Parameters:

• capacity – Initial number of OCIndex slots to allocate.

Returns:

A new empty OCMutableIndexArrayRef, or NULL on failure.

OCIndexArrayRef OCIndexArrayCreateCopy(OCIndexArrayRef theIndexArray)

Creates a deep immutable copy of the given index array.

Parameters:

• theIndexArray – The source OCIndexArrayRef to copy.

Returns:

A new OCIndexArrayRef that is a deep copy, or NULL on failure.

OCMutableIndexArrayRef OCIndexArrayCreateMutableCopy(OCIndexArrayRef theIndexArray)

Creates a deep mutable copy of the given index array.

Parameters:

• theIndexArray – The source OCIndexArrayRef to copy.

Returns:

A new OCMutableIndexArrayRef that is a deep copy, or NULL on failure.

OCIndex OCIndexArrayGetCount(OCIndexArrayRef theIndexArray)

Returns the number of OCIndex values in the array.

Parameters:

• theIndexArray – The OCIndexArrayRef instance.

Returns:

The count of elements (OCIndex) in the array.

OCIndex *OCIndexArrayGetMutableBytes(OCIndexArrayRef theIndexArray)

Returns a pointer to the raw mutable OCIndex buffer.

Parameters:

• theIndexArray – The OCIndexArrayRef instance.

Returns:

A pointer to the internal OCIndex array. Do not modify unless it is a mutable array. Returns NULL if the array is NULL.

OCIndex OCIndexArrayGetValueAtIndex(OCIndexArrayRef theIndexArray, OCIndex index)

Retrieves the value at the specified index.

Parameters:

• theIndexArray – The OCIndexArrayRef instance.

• index – Zero-based index of the value to retrieve.

Returns:

The OCIndex value at the given index, or kOCNotFound if out of bounds.

bool OCIndexArraySetValueAtIndex(OCMutableIndexArrayRef theIndexArray, OCIndex index, OCIndex value)

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

Parameters:

• theIndexArray – The OCMutableIndexArrayRef instance.

• index – Zero-based index where the value will be set.

• value – The OCIndex value to set at the specified index.

Returns:

true if successful; false if index out of bounds or on error.

bool OCIndexArrayRemoveValueAtIndex(OCMutableIndexArrayRef theIndexArray, OCIndex index)

Removes the value at the specified index.

Parameters:

• theIndexArray – The OCMutableIndexArrayRef instance.

• index – Zero-based index of the element to remove.

Returns:

true if the element was removed; false if index is out of bounds.

void OCIndexArrayRemoveValuesAtIndexes(OCMutableIndexArrayRef theIndexArray, OCIndexSetRef theIndexSet)

Removes multiple values at indices specified in an OCIndexSet.

Parameters:

• theIndexArray – The OCMutableIndexArrayRef instance.

• theIndexSet – An OCIndexSetRef containing indices to remove. Indices outside the valid range are ignored.

bool OCIndexArrayContainsIndex(OCIndexArrayRef theIndexArray, OCIndex index)

Checks whether the array contains the specified value.

Parameters:

• theIndexArray – The OCIndexArrayRef instance.

• index – The OCIndex value to search for.

Returns:

true if the value exists in the array; false otherwise.

bool OCIndexArrayAppendValue(OCMutableIndexArrayRef theIndexArray, OCIndex index)

Appends a single value to the mutable array.

Parameters:

• theIndexArray – The OCMutableIndexArrayRef instance.

• index – The OCIndex value to append.

Returns:

true if the value was appended; false on allocation failure.

bool OCIndexArrayAppendValues(OCMutableIndexArrayRef theIndexArray, OCIndexArrayRef arrayToAppend)

Appends the contents of another array to the mutable array.

Parameters:

• theIndexArray – The OCMutableIndexArrayRef instance.

• arrayToAppend – An OCIndexArrayRef whose elements will be appended.

Returns:

true if successful; false on allocation failure.

OCStringRef OCIndexArrayCreateBase64String(OCIndexArrayRef theIndexArray, OCNumberType integerType)

Converts the array to a Base64-encoded OCString using the given numeric type.

Parameters:

• theIndexArray – The OCIndexArrayRef instance.

• integerType – A OCNumberType indicating how to encode OCIndex values.

Returns:

A new OCStringRef containing the Base64 representation, or NULL on error.

OCArrayRef OCIndexArrayCreateCFNumberArray(OCIndexArrayRef theIndexArray)

Converts the array to a CFNumber-based OCArray.

Parameters:

• theIndexArray – The OCIndexArrayRef instance.

Returns:

A new OCArrayRef containing CFNumber objects, or NULL on error.

OCDictionaryRef OCIndexArrayCreateDictionary(OCIndexArrayRef theIndexArray)

Serializes the array to a plist-compatible OCDictionary.

Parameters:

• theIndexArray – The OCIndexArrayRef instance.

Returns:

A new OCDictionaryRef representing the array, or NULL on error.

OCIndexArrayRef OCIndexArrayCreateFromDictionary(OCDictionaryRef dictionary)

Reconstructs an OCIndexArray from a plist-compatible OCDictionary.

Parameters:

• dictionary – An OCDictionaryRef previously returned by OCIndexArrayCreateDictionary().

Returns:

A new OCIndexArrayRef populated from the dictionary, or NULL on error.

OCIndexArrayRef OCIndexArrayCreateFromJSON(cJSON *json, OCStringRef *outError)

Creates an OCIndexArray from a cJSON array.

Parameters:

• json – A cJSON array containing numeric values.

• outError – Optional pointer to receive error information if deserialization fails.

Returns:

A new OCIndexArrayRef, or NULL on failure. The caller is responsible for releasing the returned array.

cJSON *OCIndexArrayCopyAsJSON(OCIndexArrayRef array, bool typed, OCStringRef *outError)

Creates a JSON representation of an OCIndexArray.

For untyped serialization (typed=false), creates a JSON array of numeric values. Note that this loses type information and the index array will be indistinguishable from a regular array upon deserialization.

For typed serialization (typed=true), creates a JSON object with “type”: “OCIndexArray” and “value” array containing the numeric indices.

Parameters:

• array – A valid OCIndexArrayRef.

• typed – Whether to include type information in the serialization.

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

Returns:

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

void OCIndexArrayShow(OCIndexArrayRef theIndexArray)

Logs the contents of the array to stderr, for debugging.

Parameters:

• theIndexArray – The OCIndexArrayRef instance.

OCJSONEncoding OCIndexArrayCopyEncoding(OCIndexArrayRef array)

Returns a copy of the JSON encoding preference for an OCIndexArray.

The encoding determines how the array is serialized to JSON:

• OCJSONEncodingBase64: Binary encoding for compact representation

• OCJSONEncodingNone: Standard JSON array format

• NULL: Use default encoding behavior

Parameters:

• array – The OCIndexArrayRef instance.

Returns:

The encoding value.

void OCIndexArraySetEncoding(OCMutableIndexArrayRef array, OCJSONEncoding encoding)

Sets the JSON encoding preference for a mutable OCIndexArray.

The encoding controls JSON serialization behavior:

• OCJSONEncodingBase64: Serialize as base64-encoded binary data

• OCJSONEncodingNone: Serialize as standard JSON array

Parameters:

• array – The OCMutableIndexArrayRef instance.

• encoding – The encoding value to set.