Rework public API to make it more consistent.

1 files changed, 258 insertions, 87 deletions

diff --git a/include/plist/plist.h b/include/plist/plist.h
index 6388603..f8c5c53 100644
--- a/include/plist/plist.h
+++ b/include/plist/plist.h
@@ -65,13 +65,11 @@ extern "C" {
  * The enumeration of plist node types.
  */
         typedef enum {
-                PLIST_BOOLEAN,
-                                        /**< Boolean, scalar type */
+                PLIST_BOOLEAN,  /**< Boolean, scalar type */
                 PLIST_UINT,     /**< Unsigned integer, scalar type */
                 PLIST_REAL,     /**< Real, scalar type */
-                PLIST_STRING,
-                                        /**< ASCII string, scalar type */
-                PLIST_ARRAY,/**< Ordered array, structured type */
+                PLIST_STRING,   /**< ASCII string, scalar type */
+                PLIST_ARRAY,    /**< Ordered array, structured type */
                 PLIST_DICT,     /**< Unordered dictionary (key/value pair), structured type */
                 PLIST_DATE,     /**< Date, scalar type */
                 PLIST_DATA,     /**< Binary data, scalar type */
@@ -103,6 +101,62 @@ extern "C" {
         PLIST_API plist_t plist_new_array(void);
 
 /**
+ * Create a new plist_t type #PLIST_STRING
+ *
+ * @param val the sting value, encoded in UTF8.
+ * @return the created item
+ * @sa #plist_type
+ */
+        PLIST_API plist_t plist_new_string(const char *val);
+
+/**
+ * Create a new plist_t type #PLIST_BOOLEAN
+ *
+ * @param val the boolean value, 0 is false, other values are true.
+ * @return the created item
+ * @sa #plist_type
+ */
+        PLIST_API plist_t plist_new_bool(uint8_t val);
+
+/**
+ * Create a new plist_t type #PLIST_UINT
+ *
+ * @param val the unsigned integer value
+ * @return the created item
+ * @sa #plist_type
+ */
+        PLIST_API plist_t plist_new_uint(uint64_t val);
+
+/**
+ * Create a new plist_t type #PLIST_REAL
+ *
+ * @param val the real value
+ * @return the created item
+ * @sa #plist_type
+ */
+        PLIST_API plist_t plist_new_real(double val);
+
+/**
+ * Create a new plist_t type #PLIST_DATA
+ *
+ * @param val the binary buffer
+ * @param length the length of the buffer
+ * @return the created item
+ * @sa #plist_type
+ */
+        PLIST_API plist_t plist_new_data(const char *val, uint64_t length);
+
+/**
+ * Create a new plist_t type #PLIST_DATE
+ *
+ * @param sec the number of seconds since 01/01/2001
+ * @param usec the number of microseconds
+ * @return the created item
+ * @sa #plist_type
+ */
+        PLIST_API plist_t plist_new_date(int32_t sec, int32_t usec);
+
+/**
  * Destruct a plist_t node and all its children recursively
  *
  * @param plist the plist to free
@@ -120,139 +174,113 @@ extern "C" {
 
 /********************************************
  *                                          *
- *            Tree navigation               *
+ *            Array functions               *
  *                                          *
  ********************************************/
 
 /**
- * Get the first child of a node
+ * Get size of a #PLIST_ARRAY node.
  *
- * @param node the first child
+ * @param node the node of type #PLIST_ARRAY
+ * @return size of the #PLIST_ARRAY node
  */
-        PLIST_API plist_t plist_get_first_child(plist_t node);
-
+        PLIST_API uint32_t plist_array_get_size(plist_t node);
 
 /**
- * Get the next sibling of a node
+ * Get the nth item in a #PLIST_ARRAY node.
  *
- * @param node the next sibling
+ * @param node the node of type #PLIST_ARRAY
+ * @param n the index of the item to get. Range is [0, array_size[
+ * @return the nth item or NULL if node is not of type #PLIST_ARRAY
  */
-        PLIST_API plist_t plist_get_next_sibling(plist_t node);
-
+        PLIST_API plist_t plist_array_get_item(plist_t node, uint32_t n);
 
 /**
- * Get the previous sibling of a node
+ * Set the nth item in a #PLIST_ARRAY node.
+ * The previous item at index n will be freed using #plist_free
  *
- * @param node the previous sibling
+ * @param node the node of type #PLIST_ARRAY
+ * @param item the new item at index n
+ * @param n the index of the item to get. Range is [0, array_size[. Assert if n is not in range.
  */
-        PLIST_API plist_t plist_get_prev_sibling(plist_t node);
+        PLIST_API void plist_array_set_item(plist_t node, plist_t item, uint32_t n);
 
 /**
- * Get the parent of a node
+ * Append a new item at the end of a #PLIST_ARRAY node.
  *
- * @param node the parent (NULL if node is root)
+ * @param node the node of type #PLIST_ARRAY
+ * @param item the new item
  */
-        PLIST_API plist_t plist_get_parent(plist_t node);
+        PLIST_API void plist_array_append_item(plist_t node, plist_t item);
 
 /**
- * Get the nth child of a #PLIST_ARRAY node.
+ * Insert a new item at position n in a #PLIST_ARRAY node.
  *
  * @param node the node of type #PLIST_ARRAY
- * @param n the index of the child to get. Range is [0, array_size[
- * @return the nth children or NULL if node is not of type #PLIST_ARRAY
+ * @param item the new item to insert
+ * @param n The position at which the node will be stored. Range is [0, array_size[. Assert if n is not in range.
  */
-        PLIST_API plist_t plist_get_array_nth_el(plist_t node, uint32_t n);
+        PLIST_API void plist_array_insert_item(plist_t node, plist_t item, uint32_t n);
 
 /**
- * Get the child of a #PLIST_DICT node from the associated key value.
+ * Remove an existing position in a #PLIST_ARRAY node.
+ * Removed position will be freed using #plist_free
  *
- * @param node the node of type #PLIST_DICT
- * @param key the key associated to the requested value
- * @return the key associated value or NULL if node is not of type #PLIST_DICT
+ * @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.
  */
-        PLIST_API plist_t plist_get_dict_el_from_key(plist_t node, const char *key);
-
+        PLIST_API void plist_array_remove_item(plist_t node, uint32_t n);
 
 /********************************************
  *                                          *
- *                Setters                   *
+ *         Dictionary functions             *
  *                                          *
  ********************************************/
 
 /**
- * Add a subnode to a node. The node must be of a structured type
- * (ie #PLIST_DICT or #PLIST_ARRAY). This function fails silently
- * if subnode already has a father.
- *
- * @param node the node to add a children to
- * @param subnode the children node
- */
-        PLIST_API void plist_add_sub_node(plist_t node, plist_t subnode);
-
-/**
- * Add a subnode of type #PLIST_KEY to a node. The node must be of a structured type
- * (ie #PLIST_DICT or #PLIST_ARRAY).
- *
- * @param node the node to add a children to
- * @param val the key value encoded as an ASCII string (must be null terminated)
- */
-        PLIST_API void plist_add_sub_key_el(plist_t node, const char *val);
-
-/**
- * Add a subnode of type #PLIST_STRING to a node. The node must be of a structured type
- * (ie #PLIST_DICT or #PLIST_ARRAY).
+ * Get size of a #PLIST_DICT node.
  *
- * @param node the node to add a children to
- * @param val the string value encoded as an ASCII or UTF-8 string (must be null terminated)
+ * @param node the node of type #PLIST_DICT
+ * @return size of the #PLIST_DICT node
  */
-        PLIST_API void plist_add_sub_string_el(plist_t node, const char *val);
+        PLIST_API uint32_t plist_dict_get_size(plist_t node);
 
 /**
- * Add a subnode of type #PLIST_BOOLEAN to a node. The node must be of a structured type
- * (ie #PLIST_DICT or #PLIST_ARRAY).
+ * Get the nth item in a #PLIST_DICT node.
  *
- * @param node the node to add a children to
- * @param val the boolean value (TRUE or FALSE)
- */
-        PLIST_API void plist_add_sub_bool_el(plist_t node, uint8_t val);
-
-/**
- * Add a subnode of type #PLIST_UINT to a node. The node must be of a structured type
- * (ie #PLIST_DICT or #PLIST_ARRAY).
- *
- * @param node the node to add a children to
- * @param val the unsigned integer value
+ * @param node the node of type #PLIST_DICT
+ * @param key the identifier of the item to get.
+ * @return the item or NULL if node is not of type #PLIST_DICT
  */
-        PLIST_API void plist_add_sub_uint_el(plist_t node, uint64_t val);
+        PLIST_API plist_t plist_dict_get_item(plist_t node, const char* key);
 
 /**
- * Add a subnode of type #PLIST_REAL to a node. The node must be of a structured type
- * (ie #PLIST_DICT or #PLIST_ARRAY).
+ * Set item identified by key in a #PLIST_DICT node.
+ * The previous item at index n will be freed using #plist_free
  *
- * @param node the node to add a children to
- * @param val the real value
+ * @param node the node of type #PLIST_DICT
+ * @param item the new item associated to key
+ * @param key the identifier of the item to get. Assert if identifier is not present.
  */
-        PLIST_API void plist_add_sub_real_el(plist_t node, double val);
+        PLIST_API void plist_dict_set_item(plist_t node, plist_t item, const char* key);
 
 /**
- * Add a subnode of type #PLIST_DATA to a node. The node must be of a structured type
- * (ie #PLIST_DICT or #PLIST_ARRAY).
+ * Insert a new item at position n in a #PLIST_DICT node.
  *
- * @param node the node to add a children to
- * @param val the binary buffer
- * @param length the length of the buffer
+ * @param node the node of type #PLIST_DICT
+ * @param item the new item to insert
+ * @param key The identifier of the item to insert. Assert if identifier already present.
  */
-        PLIST_API void plist_add_sub_data_el(plist_t node, const char *val, uint64_t length);
+        PLIST_API void plist_dict_insert_item(plist_t node, plist_t item, const char* key);
 
 /**
- * Add a subnode of type #PLIST_DATE to a node. The node must be of a structured type
- * (ie #PLIST_DICT or #PLIST_ARRAY).
+ * Remove an existing position in a #PLIST_DICT node.
+ * Removed position will be freed using #plist_free
  *
- * @param node the node to add a children to
- * @param sec the number of seconds since 01/01/2001
- * @param usec the number of microseconds
+ * @param node the node of type #PLIST_DICT
+ * @param key The identifier of the item to remove. Assert if identifier is not present.
  */
-        PLIST_API void plist_add_sub_date_el(plist_t node, int32_t sec, int32_t usec);
+        PLIST_API void plist_dict_remove_item(plist_t node, const char* key);
 
 
 /********************************************
@@ -262,6 +290,13 @@ extern "C" {
  ********************************************/
 
 /**
+ * Get the parent of a node
+ *
+ * @param node the parent (NULL if node is root)
+ */
+        PLIST_API plist_t plist_get_parent(plist_t node);
+
+/**
  * Get the #plist_type of a node.
  *
  * @param node the node
@@ -454,7 +489,6 @@ extern "C" {
         PLIST_API void plist_from_bin(const char *plist_bin, uint32_t length, plist_t * plist);
 
 
-
 /********************************************
  *                                          *
  *                 Utils                    *
@@ -488,6 +522,143 @@ extern "C" {
  */
         PLIST_API char plist_compare_node_value(plist_t node_l, plist_t node_r);
 
+
+//DEPRECATED API BELOW
+
+/*@}*/
+/**
+ * \defgroup DeprecatedAPI Deprecated libplist API
+ */
+/*@{*/
+
+/********************************************
+ *                                          *
+ *            Tree navigation               *
+ *                                          *
+ ********************************************/
+
+/**
+ * Get the first child of a node
+ *
+ * @param node the first child
+ */
+        PLIST_API plist_t plist_get_first_child(plist_t node);
+
+/**
+ * Get the next sibling of a node
+ *
+ * @param node the next sibling
+ */
+        PLIST_API plist_t plist_get_next_sibling(plist_t node);
+
+/**
+ * Get the previous sibling of a node
+ *
+ * @param node the previous sibling
+ */
+        PLIST_API plist_t plist_get_prev_sibling(plist_t node);
+
+/**
+ * Get the nth child of a #PLIST_ARRAY node.
+ *
+ * @param node the node of type #PLIST_ARRAY
+ * @param n the index of the child to get. Range is [0, array_size[
+ * @return the nth children or NULL if node is not of type #PLIST_ARRAY
+ */
+        PLIST_API plist_t plist_get_array_nth_el(plist_t node, uint32_t n);
+
+/**
+ * Get the child of a #PLIST_DICT node from the associated key value.
+ *
+ * @param node the node of type #PLIST_DICT
+ * @param key the key associated to the requested value
+ * @return the key associated value or NULL if node is not of type #PLIST_DICT
+ */
+        PLIST_API plist_t plist_get_dict_el_from_key(plist_t node, const char *key);
+
+
+/********************************************
+ *                                          *
+ *                Setters                   *
+ *                                          *
+ ********************************************/
+
+/**
+ * Add a subnode to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY). This function fails silently
+ * if subnode already has a father.
+ *
+ * @param node the node to add a children to
+ * @param subnode the children node
+ */
+        PLIST_API void plist_add_sub_node(plist_t node, plist_t subnode);
+
+/**
+ * Add a subnode of type #PLIST_KEY to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY).
+ *
+ * @param node the node to add a children to
+ * @param val the key value encoded as an ASCII string (must be null terminated)
+ */
+        PLIST_API void plist_add_sub_key_el(plist_t node, const char *val);
+
+/**
+ * Add a subnode of type #PLIST_STRING to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY).
+ *
+ * @param node the node to add a children to
+ * @param val the string value encoded as an ASCII or UTF-8 string (must be null terminated)
+ */
+        PLIST_API void plist_add_sub_string_el(plist_t node, const char *val);
+
+/**
+ * Add a subnode of type #PLIST_BOOLEAN to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY).
+ *
+ * @param node the node to add a children to
+ * @param val the boolean value (TRUE or FALSE)
+ */
+        PLIST_API void plist_add_sub_bool_el(plist_t node, uint8_t val);
+
+/**
+ * Add a subnode of type #PLIST_UINT to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY).
+ *
+ * @param node the node to add a children to
+ * @param val the unsigned integer value
+ */
+        PLIST_API void plist_add_sub_uint_el(plist_t node, uint64_t val);
+
+/**
+ * Add a subnode of type #PLIST_REAL to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY).
+ *
+ * @param node the node to add a children to
+ * @param val the real value
+ */
+        PLIST_API void plist_add_sub_real_el(plist_t node, double val);
+
+/**
+ * Add a subnode of type #PLIST_DATA to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY).
+ *
+ * @param node the node to add a children to
+ * @param val the binary buffer
+ * @param length the length of the buffer
+ */
+        PLIST_API void plist_add_sub_data_el(plist_t node, const char *val, uint64_t length);
+
+/**
+ * Add a subnode of type #PLIST_DATE to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY).
+ *
+ * @param node the node to add a children to
+ * @param sec the number of seconds since 01/01/2001
+ * @param usec the number of microseconds
+ */
+        PLIST_API void plist_add_sub_date_el(plist_t node, int32_t sec, int32_t usec);
+
+
 /*@}*/