OCDictionary

group OCDictionary

Dictionary types and operations.

Functions

OCTypeID OCDictionaryGetTypeID(void)

Returns the OCTypeID for OCDictionary objects.

Returns:

Type identifier for OCDictionary.

OCDictionaryRef OCDictionaryCreate(const void **keys, const void **values, unsigned long numValues)

Creates a new dictionary with initial capacity.

Parameters:

  • keys – Array of keys.

  • values – Array of values.

  • numValues – Number of key-value pairs.

Returns:

New OCDictionaryRef or NULL on failure.

OCMutableDictionaryRef OCDictionaryCreateMutable(unsigned long capacity)

Creates a new mutable dictionary with initial capacity.

Parameters:

  • capacity – Number of key-value pairs to allocate space for initially.

Returns:

New OCMutableDictionaryRef or NULL on failure.

OCDictionaryRef OCDictionaryCreateCopy(OCDictionaryRef theDictionary)

Creates an immutable copy of a dictionary.

Parameters:

  • theDictionary – Dictionary to copy.

Returns:

New OCDictionaryRef, or NULL on failure.

OCMutableDictionaryRef OCDictionaryCreateMutableCopy(OCDictionaryRef theDictionary)

Creates a mutable copy of a dictionary.

Parameters:

  • theDictionary – Dictionary to copy.

Returns:

New OCMutableDictionaryRef, or NULL on failure.

unsigned long OCDictionaryGetCount(OCDictionaryRef theDictionary)

Gets the number of key-value pairs in a dictionary.

Parameters:

  • theDictionary – Dictionary to query.

Returns:

Count of entries.

const void *OCDictionaryGetValue(OCDictionaryRef theDictionary, OCStringRef key)

Retrieves the value for a specific key.

Parameters:

  • theDictionary – Dictionary to search.

  • key – Key to look up.

Returns:

Pointer to value, or NULL if not found.

bool OCDictionaryContainsKey(OCDictionaryRef theDictionary, OCStringRef key)

Checks if the dictionary contains the specified key.

Parameters:

  • theDictionary – Dictionary to search.

  • key – Key to test.

Returns:

true if key is found, false otherwise.

bool OCDictionaryContainsValue(OCDictionaryRef theDictionary, const void *value)

Checks if the dictionary contains the specified value.

Parameters:

  • theDictionary – Dictionary to search.

  • value – Value to look for.

Returns:

true if value is found, false otherwise.

bool OCDictionaryAddValue(OCMutableDictionaryRef theDictionary, OCStringRef key, const void *value)

Adds or replaces a key-value pair in a mutable dictionary.

Parameters:

  • theDictionary – Dictionary to modify.

  • key – Key to add or update.

  • value – Value to associate with the key.

Returns:

true on success, false on failure.

bool OCDictionarySetValue(OCMutableDictionaryRef theDictionary, OCStringRef key, const void *value)

Sets the value for a key.

If the key does not exist, this function inserts it. Equivalent to OCDictionaryAddValue().

Parameters:

  • theDictionary – Dictionary to modify.

  • key – Key to set.

  • value – Value to assign.

Returns:

true on success (inserted or updated), false on failure.

bool OCDictionaryReplaceValue(OCMutableDictionaryRef theDictionary, OCStringRef key, const void *value)

OCDictionaryReplaceValue replaces the value for an existing key.

Does nothing if the key is not present.

Parameters:

  • theDictionary – Dictionary to modify.

  • key – Key whose value is to be replaced.

  • value – New value to assign.

Returns:

true if the key existed and was replaced, false otherwise.

bool OCDictionaryRemoveValue(OCMutableDictionaryRef theDictionary, OCStringRef key)

Removes a key-value pair from the dictionary.

Parameters:

  • theDictionary – Dictionary to modify.

  • key – Key to remove.

Returns:

true if the key was found and removed, false if not found.

unsigned long OCDictionaryGetCountOfValue(OCMutableDictionaryRef theDictionary, const void *value)

Counts how many times a value appears in the dictionary.

Parameters:

  • theDictionary – Dictionary to search.

  • value – Value to count.

Returns:

Number of occurrences.

bool OCDictionaryGetKeysAndValues(OCDictionaryRef theDictionary, const void **keys, const void **values)

Retrieves all keys and values into parallel arrays.

Parameters:

  • theDictionary – Dictionary to query.

  • keys – Output array of keys (must have space for at least count entries).

  • values – Output array of values (must have space for at least count entries).

Returns:

true if keys and values were successfully written, false on error.

OCArrayRef OCDictionaryCreateArrayWithAllKeys(OCDictionaryRef theDictionary)

Creates an array containing all keys in the dictionary.

Parameters:

  • theDictionary – Dictionary to query.

Returns:

New OCArrayRef of keys, or NULL.

OCArrayRef OCDictionaryCreateArrayWithAllValues(OCDictionaryRef theDictionary)

Creates an array containing all values in the dictionary.

Parameters:

  • theDictionary – Dictionary to query.

Returns:

New OCArrayRef of values, or NULL.

OCStringRef OCDictionaryCopyFormattingDesc(OCTypeRef cf)

Returns a human-readable description of the dictionary.

Parameters:

  • cf – Dictionary to describe.

Returns:

A formatted OCStringRef (caller must release).

cJSON *OCDictionaryCopyAsJSON(OCDictionaryRef dict, bool typed, OCStringRef *outError)

Creates a JSON object representation of an OCDictionary.

This function serializes a dictionary into JSON format. When typed=false, it returns a simple JSON object with key-value pairs. When typed=true, it returns a structured JSON object with “type”: “OCDictionary” and “value”: {object with key-value pairs} fields.

Each key is serialized using its OCString value. Each value is serialized using typed or untyped JSON serialization based on the typed parameter.

Parameters:

  • dict – An OCDictionaryRef to serialize.

  • typed – If false, returns simple object; if true, returns typed object.

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

Returns:

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

OCDictionaryRef OCDictionaryCreateFromJSONTyped(cJSON *json, OCStringRef *outError)

Creates an OCDictionary from a typed cJSON object.

Parameters:

  • json – A cJSON object with “type”: “OCDictionary” and “value”: {object with key-value pairs}.

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

Returns:

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

OCDictionaryRef OCDictionaryCreateFromJSON(cJSON *json, OCStringRef *outError)

Creates an OCDictionary from an untyped cJSON object.

This function creates a dictionary from a JSON object using natural JSON type to OCType mappings: JSON strings become OCString, JSON numbers become OCNumber (double type), JSON booleans become OCBoolean, JSON arrays become OCArray (recursive), and JSON objects become OCDictionary (recursive).

Parameters:

  • json – A cJSON object containing key-value pairs.

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

Returns:

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