From d35b31d0a2661b6346a1592a5eb7b70e66b2a141 Mon Sep 17 00:00:00 2001 From: Nikias Bassen Date: Mon, 27 Apr 2026 01:45:33 +0200 Subject: Add error handling to all modification functions Convert all array/dict modification functions from void to plist_err_t return type: - plist_array_set_item: replace at index n - plist_array_append_item: append to end - plist_array_insert_item: insert at position n - plist_array_remove_item: remove item at index n - plist_array_item_remove: remove item from its array parent - plist_dict_set_item: replace or insert key/value - plist_dict_remove_item: remove key/value pair - plist_dict_merge: merge source dict into target Returns: - PLIST_ERR_SUCCESS on success - PLIST_ERR_INVALID_ARG for invalid arguments (NULL, wrong type, out of range, etc.) - PLIST_ERR_NO_MEM on memory allocation failure - PLIST_ERR_UNKNOWN on unexpected internal errors Header documentation updated with full error code semantics for each function. --- include/plist/plist.h | 81 +++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 69 insertions(+), 12 deletions(-) (limited to 'include/plist') diff --git a/include/plist/plist.h b/include/plist/plist.h index 94930b8..e720aac 100644 --- a/include/plist/plist.h +++ b/include/plist/plist.h @@ -347,43 +347,77 @@ extern "C" * * @param node the node of type #PLIST_ARRAY * @param item the new item at index n. The array is responsible for freeing item when it is no longer needed. - * @param n the index of the item to get. Range is [0, array_size[. Assert if n is not in range. + * @param n the index of the item to get. Range is [0, array_size[. + * + * @return + * - PLIST_ERR_SUCCESS on success. + * - PLIST_ERR_INVALID_ARG if node is not an array, item is NULL, item is already + * attached to a parent, or n is outside the valid range. + * - PLIST_ERR_NO_MEM if replacing the item fails due to memory allocation failure + * and the original array element was restored successfully. + * - PLIST_ERR_UNKNOWN if an unexpected internal error occurred, including failure + * to restore the original array element after insertion of the replacement failed. */ - PLIST_API void plist_array_set_item(plist_t node, plist_t item, uint32_t n); + PLIST_API plist_err_t plist_array_set_item(plist_t node, plist_t item, uint32_t n); /** * Append a new item at the end of a #PLIST_ARRAY node. * * @param node the node of type #PLIST_ARRAY * @param item the new item. The array is responsible for freeing item when it is no longer needed. + * + * @return + * - PLIST_ERR_SUCCESS on success. + * - PLIST_ERR_INVALID_ARG if node is not an array, item is NULL, or item is + * already attached to a parent. + * - PLIST_ERR_NO_MEM if memory allocation failed while appending the item. + * - PLIST_ERR_UNKNOWN if an unexpected internal error occurred. */ - PLIST_API void plist_array_append_item(plist_t node, plist_t item); + PLIST_API plist_err_t plist_array_append_item(plist_t node, plist_t item); /** * Insert a new item at position n in a #PLIST_ARRAY node. * * @param node the node of type #PLIST_ARRAY * @param item the new item to insert. The array is responsible for freeing item when it is no longer needed. - * @param n The position at which the node will be stored. Range is [0, array_size[. Assert if n is not in range. + * @param n The position at which the node will be stored. Range is [0, array_size[. + * + * @return + * - PLIST_ERR_SUCCESS on success. + * - PLIST_ERR_INVALID_ARG if node is not an array, item is NULL, item is already + * attached to a parent, or n is outside the valid insertion range. + * - PLIST_ERR_NO_MEM if memory allocation failed while inserting the item. + * - PLIST_ERR_UNKNOWN if an unexpected internal error occurred. */ - PLIST_API void plist_array_insert_item(plist_t node, plist_t item, uint32_t n); + PLIST_API plist_err_t plist_array_insert_item(plist_t node, plist_t item, uint32_t n); /** * Remove an existing position in a #PLIST_ARRAY node. * Removed position will be freed using #plist_free. * * @param node the node of type #PLIST_ARRAY - * @param n The position to remove. Range is [0, array_size[. Assert if n is not in range. + * @param n The position to remove. Range is [0, array_size[. + * + * @return + * - PLIST_ERR_SUCCESS on success. + * - PLIST_ERR_INVALID_ARG if node is not an array or n is outside the valid range. + * - PLIST_ERR_UNKNOWN if an unexpected internal error occurred while removing + * the item. */ - PLIST_API void plist_array_remove_item(plist_t node, uint32_t n); + PLIST_API plist_err_t plist_array_remove_item(plist_t node, uint32_t n); /** * Remove a node that is a child node of a #PLIST_ARRAY node. * node will be freed using #plist_free. * * @param node The node to be removed from its #PLIST_ARRAY parent. + * + * @return + * - PLIST_ERR_SUCCESS on success. + * - PLIST_ERR_INVALID_ARG if item is NULL or not a child of a #PLIST_ARRAY + * - PLIST_ERR_UNKNOWN if an unexpected internal error occurred. */ - PLIST_API void plist_array_item_remove(plist_t node); + PLIST_API plist_err_t plist_array_item_remove(plist_t item); /** * Create an iterator of a #PLIST_ARRAY node. @@ -489,17 +523,32 @@ extern "C" * @param node the node of type #PLIST_DICT * @param item the new item associated to key * @param key the identifier of the item to set. + * + * @return + * - PLIST_ERR_SUCCESS on success. + * - PLIST_ERR_INVALID_ARG if node is not a dictionary, key is NULL, item is NULL, + * or item is already attached to a parent. + * - PLIST_ERR_NO_MEM if memory allocation failed while creating or inserting the + * key/value pair. + * - PLIST_ERR_UNKNOWN if an unexpected internal error occurred. */ - PLIST_API void plist_dict_set_item(plist_t node, const char* key, plist_t item); + PLIST_API plist_err_t plist_dict_set_item(plist_t node, const char* key, plist_t item); /** * Remove an existing position in a #PLIST_DICT node. * Removed position will be freed using #plist_free * * @param node the node of type #PLIST_DICT - * @param key The identifier of the item to remove. Assert if identifier is not present. + * @param key The identifier of the item to remove + * + * @return + * - PLIST_ERR_SUCCESS on success. + * - PLIST_ERR_INVALID_ARG if node is not a dictionary, key is NULL, or no item + * with the given key exists. + * - PLIST_ERR_UNKNOWN if an unexpected internal error occurred while removing + * the item. */ - PLIST_API void plist_dict_remove_item(plist_t node, const char* key); + PLIST_API plist_err_t plist_dict_remove_item(plist_t node, const char* key); /** * Merge a dictionary into another. This will add all key/value pairs @@ -508,8 +557,16 @@ extern "C" * * @param target pointer to an existing node of type #PLIST_DICT * @param source node of type #PLIST_DICT that should be merged into target + * + * @return + * - PLIST_ERR_SUCCESS on success. + * - PLIST_ERR_INVALID_ARG if target is NULL, source is NULL, source is not a + * dictionary, or *target is not NULL and does not point to a dictionary. + * - PLIST_ERR_NO_MEM if memory allocation failed while creating the target + * dictionary or copying items from source. + * - PLIST_ERR_UNKNOWN if an unexpected internal error occurred. */ - PLIST_API void plist_dict_merge(plist_t *target, plist_t source); + PLIST_API plist_err_t plist_dict_merge(plist_t *target, plist_t source); /** * Get a boolean value from a given #PLIST_DICT entry. -- cgit v1.1-32-gdbae