OCIndexSet

group OCIndexSet

APIs for immutable and mutable collections of OCIndex values.

This group includes functions to create, query, modify, and serialize sets of OCIndex. Underlying storage is a sorted OCIndex array, and serialization integrates with OCData and OCDictionary for plist support.

Functions

OCTypeID OCIndexSetGetTypeID(void)

OCIndexSetRef OCIndexSetCreate(void)

Creates an empty, immutable OCIndexSet.

Returns:

A new OCIndexSetRef with no indices, or NULL on allocation failure.

OCMutableIndexSetRef OCIndexSetCreateMutable(void)

Creates an empty, mutable OCIndexSet.

Returns:

A new OCMutableIndexSetRef with no indices, or NULL on allocation failure.

OCIndexSetRef OCIndexSetCreateCopy(OCIndexSetRef theIndexSet)

Creates an immutable copy of the provided index set.

Parameters:

• theIndexSet – The source OCIndexSetRef to copy.

Returns:

A new OCIndexSetRef that is a deep copy, or NULL if the source is NULL or on error.

OCMutableIndexSetRef OCIndexSetCreateMutableCopy(OCIndexSetRef theIndexSet)

Creates a mutable copy of the provided index set.

Parameters:

• theIndexSet – The source OCIndexSetRef to copy.

Returns:

A new OCMutableIndexSetRef that is a deep copy, or NULL if the source is NULL or on error.

OCIndexSetRef OCIndexSetCreateWithIndex(OCIndex index)

Creates an OCIndexSet containing exactly one index.

Parameters:

• index – The single OCIndex to include.

Returns:

A new OCIndexSetRef with that index, or NULL on allocation failure.

OCIndexSetRef OCIndexSetCreateWithIndexesInRange(OCIndex location, OCIndex length)

Creates an OCIndexSet containing all indices in [location, location + length).

Parameters:

• location – The starting OCIndex (inclusive).

• length – The number of consecutive indices.

Returns:

A new OCIndexSetRef with indices location through (location + length - 1), or NULL on error (e.g., invalid range or allocation failure).

OCDataRef OCIndexSetGetIndexes(OCIndexSetRef theIndexSet)

Retrieves the underlying OCData buffer holding sorted indices.

Parameters:

• theIndexSet – The OCIndexSetRef instance.

Returns:

A new OCDataRef containing the contiguous OCIndex array; caller must release. Returns NULL if theIndexSet is NULL.

OCIndex *OCIndexSetGetBytesPtr(OCIndexSetRef theIndexSet)

Returns a pointer to the internal OCIndex array.

Parameters:

• theIndexSet – The OCIndexSetRef instance.

Returns:

A pointer to the sorted OCIndex array for direct access. Do not modify if the set is immutable. Returns NULL if theIndexSet is NULL.

OCIndex OCIndexSetGetCount(OCIndexSetRef theIndexSet)

Returns the number of indices in the set.

Parameters:

• theIndexSet – The OCIndexSetRef instance.

Returns:

The count of OCIndex values, or 0 if theIndexSet is NULL.

OCIndex OCIndexSetFirstIndex(OCIndexSetRef theIndexSet)

Returns the smallest (first) index in the set.

Parameters:

• theIndexSet – The OCIndexSetRef instance.

Returns:

The first OCIndex, or kOCNotFound if the set is empty or NULL.

OCIndex OCIndexSetLastIndex(OCIndexSetRef theIndexSet)

Returns the largest (last) index in the set.

Parameters:

• theIndexSet – The OCIndexSetRef instance.

Returns:

The last OCIndex, or kOCNotFound if the set is empty or NULL.

OCIndex OCIndexSetIndexLessThanIndex(OCIndexSetRef theIndexSet, OCIndex index)

Finds the largest index smaller than the given one.

Parameters:

• theIndexSet – The OCIndexSetRef instance.

• index – The OCIndex to compare.

Returns:

The greatest OCIndex < index, or kOCNotFound if none exists or on error.

OCIndex OCIndexSetIndexGreaterThanIndex(OCIndexSetRef theIndexSet, OCIndex index)

Finds the smallest index greater than the given one.

Parameters:

• theIndexSet – The OCIndexSetRef instance.

• index – The OCIndex to compare.

Returns:

The least OCIndex > index, or kOCNotFound if none exists or on error.

bool OCIndexSetContainsIndex(OCIndexSetRef theIndexSet, OCIndex index)

Checks if the set contains a given index.

Parameters:

• theIndexSet – The OCIndexSetRef instance.

• index – The OCIndex to check.

Returns:

true if index is present; false otherwise or if theIndexSet is NULL.

bool OCIndexSetAddIndex(OCMutableIndexSetRef theIndexSet, OCIndex index)

Inserts a new index into the mutable set.

Parameters:

• theIndexSet – The OCMutableIndexSetRef instance.

• index – The OCIndex to add.

Returns:

true if inserted (or already present); false on allocation failure or if theIndexSet is NULL.

bool OCIndexSetEqual(OCIndexSetRef input1, OCIndexSetRef input2)

Compares two index sets for equality.

Parameters:

• input1 – The first OCIndexSetRef.

• input2 – The second OCIndexSetRef.

Returns:

true if both sets contain the same indices; false otherwise or if either is NULL.

OCArrayRef OCIndexSetCreateOCNumberArray(OCIndexSetRef theIndexSet)

Converts the index set into an OCArray of OCNumber objects.

Parameters:

• theIndexSet – The OCIndexSetRef instance.

Returns:

A new OCArrayRef whose elements are OCNumberRef wrapping each index; caller must release. Returns NULL on error.

OCDictionaryRef OCIndexSetCreateDictionary(OCIndexSetRef theIndexSet)

Serializes the set to an OCDictionary for plist compatibility.

Parameters:

• theIndexSet – The OCIndexSetRef instance.

Returns:

A new OCDictionaryRef representing the index set, or NULL on error.

OCIndexSetRef OCIndexSetCreateFromDictionary(OCDictionaryRef dictionary)

Reconstructs an OCIndexSet from a plist-compatible OCDictionary.

Parameters:

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

Returns:

A new OCIndexSetRef populated from dictionary, or NULL on error.

OCDataRef OCIndexSetCreateData(OCIndexSetRef theIndexSet)

Creates an OCData snapshot of the current set.

Parameters:

• theIndexSet – The OCIndexSetRef instance.

Returns:

A new OCDataRef containing the sorted OCIndex array; caller must release. Returns NULL if theIndexSet is NULL or on error.

OCIndexSetRef OCIndexSetCreateWithData(OCDataRef data)

Creates an OCIndexSet using the bytes from an existing OCData object.

Parameters:

• data – An OCDataRef containing a contiguous OCIndex array.

Returns:

A new OCIndexSetRef using data as backing storage, or NULL on error.

OCIndexSetRef OCIndexSetCreateFromJSON(cJSON *json, OCStringRef *outError)

Creates an OCIndexSet from a JSON array.

This function expects a cJSON array node containing numeric values. Each number is cast to an OCIndex and added to the resulting OCIndexSet.

Parameters:

• json – A cJSON array node containing numeric values.

Returns:

A new OCIndexSetRef on success, or NULL on failure. The caller is responsible for releasing the returned OCIndexSet.

cJSON *OCIndexSetCopyAsJSON(OCIndexSetRef set, bool typed, OCStringRef *outError)

Creates a JSON representation of an OCIndexSet.

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

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

Parameters:

• set – An OCIndexSetRef to serialize. Must not be NULL.

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

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

Returns:

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

void OCIndexSetShow(OCIndexSetRef theIndexSet)

Logs the contents of the set to stderr for debugging.

Parameters:

• theIndexSet – The OCIndexSetRef instance.

OCJSONEncoding OCIndexSetCopyEncoding(OCIndexSetRef set)

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

The encoding determines how the set is serialized to JSON:

• OCJSONEncodingBase64: Binary encoding for compact representation

• OCJSONEncodingNone: Standard JSON array format

• NULL: Use default encoding behavior

Parameters:

• set – The OCIndexSetRef instance.

Returns:

A copy of the encoding string, or NULL if no encoding is set. Caller is responsible for releasing the returned string.

void OCIndexSetSetEncoding(OCMutableIndexSetRef set, OCJSONEncoding encoding)

Sets the JSON encoding preference for a mutable OCIndexSet.

The encoding controls JSON serialization behavior:

• OCJSONEncodingBase64: Serialize as base64-encoded binary data

• OCJSONEncodingNone: Serialize as standard JSON array

Parameters:

• set – The OCMutableIndexSetRef instance.

• encoding – The encoding value to set.