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.

1 files changed, 69 insertions, 12 deletions

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.