plist: Add iterator for #PLIST_ARRAY nodes

Similar to #PLIST_DICT, an iterator can now be used for #PLIST_ARRAY
nodes. Get an iterator with plist_array_new_iter() and use
plist_array_next_item() to iterate over the elements.

1 files changed, 37 insertions, 9 deletions

diff --git a/include/plist/plist.h b/include/plist/plist.h
index e817b4b..707460e 100644
--- a/include/plist/plist.h
+++ b/include/plist/plist.h
@@ -3,7 +3,8 @@
  * @brief Main include of libplist
  * \internal
  *
- * Copyright (c) 2008 Jonathan Beck All Rights Reserved.
+ * Copyright (c) 2012-2019 Nikias Bassen, All Rights Reserved.
+ * Copyright (c) 2008-2009 Jonathan Beck, All Rights Reserved.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -90,7 +91,12 @@ extern "C"
     /**
      * The plist dictionary iterator.
      */
-    typedef void *plist_dict_iter;
+    typedef void* plist_dict_iter;
+
+    /**
+     * The plist array iterator.
+     */
+    typedef void* plist_array_iter;
 
     /**
      * The enumeration of plist node types.
@@ -281,6 +287,27 @@ extern "C"
      */
     void plist_array_remove_item(plist_t node, uint32_t n);
 
+    /**
+     * Create an iterator of a #PLIST_ARRAY node.
+     * The allocated iterator should be freed with the standard free function.
+     *
+     * @param node The node of type #PLIST_ARRAY
+     * @param iter Location to store the iterator for the array.
+     */
+    void plist_array_new_iter(plist_t node, plist_array_iter *iter);
+
+    /**
+     * Increment iterator of a #PLIST_ARRAY node.
+     *
+     * @param node The node of type #PLIST_ARRAY.
+     * @param iter Iterator of the array
+     * @param item Location to store the item. The caller must *not* free the
+     *          returned item. Will be set to NULL when no more items are left
+     *          to iterate.
+     */
+    void plist_array_next_item(plist_t node, plist_array_iter iter, plist_t *item);
+
+
     /********************************************
      *                                          *
      *         Dictionary functions             *
@@ -299,20 +326,21 @@ extern "C"
      * Create an iterator of a #PLIST_DICT node.
      * The allocated iterator should be freed with the standard free function.
      *
-     * @param node the node of type #PLIST_DICT
-     * @param iter iterator of the #PLIST_DICT node
+     * @param node The node of type #PLIST_DICT.
+     * @param iter Location to store the iterator for the dictionary.
      */
     void plist_dict_new_iter(plist_t node, plist_dict_iter *iter);
 
     /**
      * Increment iterator of a #PLIST_DICT node.
      *
-     * @param node the node of type #PLIST_DICT
-     * @param iter iterator of the dictionary
-     * @param key a location to store the key, or NULL. The caller is responsible
+     * @param node The node of type #PLIST_DICT
+     * @param iter Iterator of the dictionary
+     * @param key Location to store the key, or NULL. The caller is responsible
      *          for freeing the the returned string.
-     * @param val a location to store the value, or NULL. The caller should *not*
-     *          free the returned value.
+     * @param val Location to store the value, or NULL. The caller must *not*
+     *          free the returned value. Will be set to NULL when no more
+     *          key/value pairs are left to iterate.
      */
     void plist_dict_next_item(plist_t node, plist_dict_iter iter, char **key, plist_t *val);