OCIndexPairSet

group OCIndexPairSet

APIs for sets of OCIndex–OCIndex pairs (OCIndexPairSet and mutable variant).

This group includes types and functions to create, query, modify, and serialize collections of index-value pair structures, where each pair holds an index and its associated value.

Functions

OCTypeID OCIndexPairSetGetTypeID(void)

Returns the unique OCTypeID for OCIndexPairSet.

Returns:: The OCTypeID corresponding to OCIndexPairSet.

OCIndexPairSetRef OCIndexPairSetCreate(void)

Creates an empty immutable OCIndexPairSet.

Returns:: A new OCIndexPairSetRef, or NULL on allocation failure.

OCMutableIndexPairSetRef OCIndexPairSetCreateMutable(void)

Creates an empty mutable OCIndexPairSet.

Returns:: A new OCMutableIndexPairSetRef, or NULL on allocation failure.

OCIndexPairSetRef OCIndexPairSetCreateCopy(OCIndexPairSetRef source)

Creates a deep immutable copy of the given set.

Parameters:

source – The OCIndexPairSetRef to copy.

Returns:

A new OCIndexPairSetRef that is a deep copy of source, or NULL on error.

OCMutableIndexPairSetRef OCIndexPairSetCreateMutableCopy(OCIndexPairSetRef source)

Creates a deep mutable copy of the given set.

Parameters:

source – The OCIndexPairSetRef to copy.

Returns:

A new OCMutableIndexPairSetRef that is a deep copy of source, or NULL on error.

OCMutableIndexPairSetRef OCIndexPairSetCreateMutableWithIndexArray(OCIndexArrayRef indexArray)

Creates a mutable index-pair set from an OCIndexArray.

Each element in indexArray becomes a pair (index = position, value = element).

Parameters:

indexArray – An OCIndexArrayRef whose elements supply values; indices are 0-based.

Returns:

A new OCMutableIndexPairSetRef, or NULL on error.

OCIndexPairSetRef OCIndexPairSetCreateWithIndexPairArray(OCIndexPair *array, int count)

Creates an immutable set from a C array of OCIndexPair.

Parameters:

array – Pointer to a C array of OCIndexPair structures.
count – Number of elements in the array.

Returns:

A new OCIndexPairSetRef containing those pairs, or NULL on error.

OCIndexPairSetRef OCIndexPairSetCreateWithIndexPair(OCIndex index, OCIndex value)

Creates an immutable set with a single index–value pair.

Parameters:

index – The index (key) for the pair.
value – The value associated with index.

Returns:

A new OCIndexPairSetRef containing that single pair, or NULL on error.

OCIndexPairSetRef OCIndexPairSetCreateWithTwoIndexPairs(OCIndex index1, OCIndex value1, OCIndex index2, OCIndex value2)

Creates an immutable set with two index–value pairs.

Parameters:

index1 – The first pair’s index (key).
value1 – The first pair’s value.
index2 – The second pair’s index (key).
value2 – The second pair’s value.

Returns:

A new OCIndexPairSetRef containing both pairs, or NULL on error.

OCDataRef OCIndexPairSetGetIndexPairs(OCIndexPairSetRef set)

Returns the backing OCDataRef that holds all index pairs.

Parameters:

set – The OCIndexPairSetRef instance.

Returns:

An OCDataRef containing a contiguous buffer of OCIndexPair structs; caller must release. Returns NULL if set is NULL.

OCIndex OCIndexPairSetGetCount(OCIndexPairSetRef set)

Returns the number of pairs in the set.

Parameters:

set – The OCIndexPairSetRef instance.

Returns:

The count of OCIndexPair elements, or 0 if set is NULL.

OCIndexPair *OCIndexPairSetGetBytesPtr(OCIndexPairSetRef set)

Returns a pointer to the internal OCIndexPair array.

Parameters:

set – The OCIndexPairSetRef instance.

Returns:

Pointer to an array of OCIndexPair; do not modify if set is immutable. Returns NULL if set is NULL.

OCIndex OCIndexPairSetValueForIndex(OCIndexPairSetRef set, OCIndex index)

Retrieves the value associated with a given index.

Parameters:

set – The OCIndexPairSetRef instance.
index – The index (key) to look up.

Returns:

The associated OCIndex value, or kOCNotFound if index is not present.

OCIndexArrayRef OCIndexPairSetCreateIndexArrayOfValues(OCIndexPairSetRef set)

Returns an OCIndexArray of all values in the set.

Parameters:

set – The OCIndexPairSetRef instance.

Returns:

A new OCIndexArrayRef containing all values (in ascending index order), or NULL on error.

OCIndexSetRef OCIndexPairSetCreateIndexSetOfIndexes(OCIndexPairSetRef set)

Returns an OCIndexSet containing all of the keys (indexes) in the set.

Parameters:

set – The OCIndexPairSetRef instance to query.

Returns:

A new OCIndexSetRef with every pair’s .index member, in ascending order; or NULL if set is NULL or on allocation failure.

OCIndexPair OCIndexPairSetFirstIndex(OCIndexPairSetRef set)

Returns the first index–value pair in the set.

Parameters:

set – The OCIndexPairSetRef instance.

Returns:

The OCIndexPair for the smallest index, or {kOCNotFound, kOCNotFound} if empty.

OCIndexPair OCIndexPairSetLastIndex(OCIndexPairSetRef set)

Returns the last index–value pair in the set.

Parameters:

set – The OCIndexPairSetRef instance.

Returns:

The OCIndexPair for the largest index, or {kOCNotFound, kOCNotFound} if empty.

OCIndexPair OCIndexPairSetIndexPairLessThanIndexPair(OCIndexPairSetRef set, OCIndexPair target)

Returns the pair immediately before the given target, by index.

Parameters:

set – The OCIndexPairSetRef instance.
target – An OCIndexPair whose index field specifies the search target.

Returns:

The OCIndexPair whose index is the greatest value less than target.index, or {kOCNotFound, kOCNotFound} if none exists.

bool OCIndexPairSetContainsIndex(OCIndexPairSetRef set, OCIndex index)

Checks if the set contains a given index (key).

Parameters:

set – The OCIndexPairSetRef instance.
index – The index (key) to check.

Returns:

true if the index exists; false otherwise.

bool OCIndexPairSetContainsIndexPair(OCIndexPairSetRef set, OCIndexPair pair)

Checks if the set contains the exact index–value pair.

Parameters:

set – The OCIndexPairSetRef instance.
pair – The OCIndexPair to check for existence.

Returns:

true if the pair exists (both index and value match); false otherwise.

bool OCIndexPairSetAddIndexPair(OCMutableIndexPairSetRef set, OCIndex index, OCIndex value)

Adds a new index–value pair to a mutable set if the index is not already present.

Parameters:

set – The OCMutableIndexPairSetRef instance.
index – The index (key) to add.
value – The value associated with index.

Returns:

true on success; false if index already exists or on allocation failure.

bool OCIndexPairSetRemoveIndexPairWithIndex(OCMutableIndexPairSetRef set, OCIndex index)

Removes the pair with the given index from a mutable set.

Parameters:

set – The OCMutableIndexPairSetRef instance.
index – The index (key) whose pair will be removed.

Returns:

true if the pair was found and removed; false otherwise.

OCDataRef OCIndexPairSetCreateData(OCIndexPairSetRef set)

Returns an OCDataRef representing the internal contiguous OCIndexPair buffer.

Parameters:

set – The OCIndexPairSetRef instance.

Returns:

A new OCDataRef containing the raw pair buffer; caller must release.

OCIndexPairSetRef OCIndexPairSetCreateWithData(OCDataRef data)

Creates an OCIndexPairSet using an existing OCDataRef as backing storage.

Parameters:

data – An OCDataRef containing a sequence of OCIndexPair structures.

Returns:

A new OCIndexPairSetRef using the provided data, or NULL on error.

OCDictionaryRef OCIndexPairSetCopyAsDictionary(OCIndexPairSetRef set)

Serializes the index pair set to an OCDictionary for plist compatibility.

Parameters:

set – The OCIndexPairSetRef instance.

Returns:

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

OCIndexPairSetRef OCIndexPairSetCreateWithDictionary(OCDictionaryRef dictionary)

Reconstructs an OCIndexPairSet from a plist-compatible OCDictionary.

Parameters:

dictionary – An OCDictionaryRef previously returned by OCIndexPairSetCopyAsDictionary().

Returns:

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

cJSON *OCIndexPairSetCopyAsJSON(OCIndexPairSetRef set, bool typed, OCStringRef *outError)

Creates a JSON representation of an OCIndexPairSet.

For untyped serialization (typed=false), creates a JSON array where each pair is serialized as a 2-element JSON array: [index, value]. Note that this loses type information and the index pair set will be indistinguishable from a regular array upon deserialization.

For typed serialization (typed=true), creates a JSON object with “type”: “OCIndexPairSet” and “value” array containing the index-value pairs.

Parameters:

set – An OCIndexPairSetRef to serialize.
typed – Whether to include type information in the serialization.

Returns:

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

OCIndexPairSetRef OCIndexPairSetCreateFromJSON(cJSON *json, OCStringRef *outError)

Creates an OCIndexPairSet from a JSON array of index-value pairs.

Each item in the JSON array must be a 2-element array: [index, value].

Parameters:

json – A cJSON array of index pairs.
outError – Optional pointer to receive error information if deserialization fails.

Returns:

A new OCIndexPairSetRef on success, or NULL on failure. Caller is responsible for releasing the returned set.

void OCIndexPairSetShow(OCIndexPairSetRef set)

Logs the contents of the index-pair set to stderr for debugging.

Parameters:

set – The OCIndexPairSetRef instance.

OCJSONEncoding OCIndexPairSetCopyEncoding(OCIndexPairSetRef set)

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

The encoding determines how the pair set is serialized to JSON:

OCJSONEncodingBase64: Binary encoding for compact representation
OCJSONEncodingNone: Standard JSON array format (CSDM flat array)
NULL: Use default encoding behavior

Parameters:

set – The OCIndexPairSetRef instance.

Returns:

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

void OCIndexPairSetSetEncoding(OCMutableIndexPairSetRef set, OCJSONEncoding encoding)

Sets the JSON encoding preference for a mutable OCIndexPairSet.

The encoding controls JSON serialization behavior:

OCJSONEncodingBase64: Serialize as base64-encoded binary data
OCJSONEncodingNone: Serialize as CSDM flat array [index1,value1,index2,value2,…]
NULL: Clear encoding preference (use default)

Parameters:

set – The OCMutableIndexPairSetRef instance.
encoding – The encoding string to set, or NULL to clear.