Merge lp:~jamesodhunt/libnih/iterators into lp:libnih/1.0

[James Hunt]

* New functions:
  - nih_list_foreach()
  - nih_hash_foreach()
  - nih_tree_foreach()
  - nih_list_count()
  - nih_hash_count()
  - nih_tree_count()

These functions will be marginally slower to run than the corresponding NIH_LIST_FOREACH(), NIH_HASH_FOREACH() and NIH_TREE_FOREACH_*() macros, but have the advantage of being (more easily) callable from within a debugger. Additionally, trivial handlers can be created by apps using nih which also simplifies debug.

For example, we could change Upstart to include functions like this:

init/conf.c:
#ifdef DEBUG
  int conf_sources_handler (ConfSource *source, void *data)
      __attribute__((unused));

  int
  conf_sources_handler (ConfSource *source, void *data)
  {
    nih_assert (source);
    return TRUE;
  }
#endif

This minimal handler is enough such that from within gdb, we can then say:

(gdb) b conf_sources_handler
(gdb) call nih_list_foreach (conf_sources, NULL, (NihListHandler)conf_sources_handler, NULL)
(gdb) r

And then when the breakpoint is hit...

(gdb) p source

This avoids cluttering our applications source code with horrid hard-coded functions to print out data structures - we can rely on gdb to do that for us.

Unmerged revisions

1049. By James Hunt on 2011-05-08

* Changelog: Summary of new functions.
* nih/hash.c: New functions:
  - nih_hash_foreach()
  - nih_hash_count()
* nih/hash.h: Prototypes for new functions:
  - nih_hash_foreach()
  - nih_hash_count()
* nih/list.c: New functions:
  - nih_list_foreach()
  - nih_list_count()
* nih/list.h:
  - Prototypes for new functions:
    - nih_list_foreach()
    - nih_list_count()
  - New type: NihListHandler.
* nih/tree.c: New functions:
  - nih_tree_foreach()
  - nih_tree_count()
* nih/tree.h:
  - Prototypes for new functions:
    - nih_tree_foreach()
    - nih_tree_count()
  - New type: NihTreeHandler.
* nih/tests/test_hash.c:
  - New functions:
    - test_count()
    - test_foreach_func () and supporting functions:
      - hash_handler1()
      - hash_handler2()
      - hash_handler3()
  - Updated main to call test_foreach_func() and test_count().
  - Changed description for existing functions to make it clear that
    NIH_HASH_FOREACH() is a macro.
* nih/tests/test_list.c:
  - New functions:
    - test_count()
    - test_foreach_func() and supporting functions:
      - list_handler1()
      - list_handler2()
      - list_handler3()
  - Updated main to call test_foreach_func() and test_count().
  - Changed description for existing functions to make it clear that
    NIH_LIST_*() are macros.
* nih/tests/test_tree.c
  - New functions:
    - test_count()
    - test_foreach_func () and supporting functions:
      - tree_handler1()
      - tree_handler2()
      - tree_handler3()
  - Updated main to call test_foreach_func() and test_count().
  - Changed description for existing functions to make it clear that
    NIH_TREE_FOREACH_*() are macros.

=== modified file 'ChangeLog'
--- ChangeLog	2010-12-23 22:06:15 +0000
+++ ChangeLog	2011-05-08 11:56:38 +0000
@@ -1,3 +1,13 @@
[phone]  James Hunt  <[e-mail]>
+
+	* New functions:
+	  - nih_list_foreach()
+	  - nih_hash_foreach()
+	  - nih_tree_foreach()
+	  - nih_list_count()
+	  - nih_hash_count()
+	  - nih_tree_count()
+
 2010-12-23  Scott James Remnant  <[e-mail]>
 
 	* configure.ac: Bump version to 1.0.4

=== modified file 'nih/hash.c'
--- nih/hash.c	2009-06-23 09:29:37 +0000
+++ nih/hash.c	2011-05-08 11:56:38 +0000
@@ -397,3 +397,65 @@
 
 	return strcmp (key1, key2);
 }
+
+/**
+ * nih_hash_foreach:
+ *
+ * @hash: hash,
+ * @len: optional output parameter that will contain count of hash entries,
+ * @handler: optional function called for each hash entry,
+ * @data: optional data to pass to handler along with hash entry.
+ *
+ * Iterate over specified hash.
+ *
+ * One of @len or @handler may be NULL.
+ * If @handler is NULL, count of hash entries will still be returned in @len.
+ * If @handler returns 1, @len will be set to the number of hash entries
+ * processed successfully up to that point.
+ *
+ * Returns 0 on success (and when both @len and @handler are NULL),
+ * or -1 if handler returns an error.
+ **/
+int
+nih_hash_foreach (const NihHash *hash, size_t *len,
+	NihListHandler handler, void *data)
+{
+	int ret;
+
+	nih_assert (hash);
+
+	if (len) *len = 0;
+
+	if (!len && !handler) return 0;
+
+	NIH_HASH_FOREACH (hash, iter) {
+		if (handler) {
+			ret = handler (iter, data);
+			if (ret == FALSE) return -1;
+		}
+		if (len) ++*len;
+	}
+
+	return 0;
+}
+
+/**
+ * nih_hash_count:
+ *
+ * @hash: hash.
+ * 
+ * Returns count of number of entries in @hash.
+ **/
+size_t
+nih_hash_count (const NihHash *hash)
+{
+	size_t len = 0;
+	int ret;
+
+	nih_assert (hash);
+
+	ret = nih_hash_foreach (hash, &len, NULL, NULL);
+
+	return (ret == -1 ? 0 : len);
+}
+

=== modified file 'nih/hash.h'
--- nih/hash.h	2011-01-06 09:28:39 +0000
+++ nih/hash.h	2011-05-08 11:56:38 +0000
@@ -217,6 +217,13 @@
 uint32_t    nih_hash_string_hash  (const char *key);
 int         nih_hash_string_cmp   (const char *key1, const char *key2);
 
+int         nih_hash_foreach      (const NihHash *hash, size_t *len,
+                                   NihListHandler handler, void *data)
+	__attribute__((unused));
+
+size_t      nih_hash_count        (const NihHash *hash)
+	__attribute__((warn_unused_result, unused));
+
 NIH_END_EXTERN
 
 #endif /* NIH_HASH_H */

=== modified file 'nih/list.c'
--- nih/list.c	2009-06-23 09:29:37 +0000
+++ nih/list.c	2011-05-08 11:56:38 +0000
@@ -249,3 +249,62 @@
 
 	return 0;
 }
+
+/**
+ * nih_list_foreach:
+ * @list: list,
+ * @len: optional output parameter that will contain length of list,
+ * @handler: optional function called for each list entry,
+ * @data: optional data to pass to handler along with list entry.
+ *
+ * Iterate over specified list.
+ *
+ * One of @len or @handler may be NULL.
+ * If @handler is NULL, list length will still be returned in @len.
+ * If @handler returns 1, @len will be set to the number of list entries
+ * processed successfully up to that point.
+ *
+ * Returns 0 on success (and when both @len and @handler are NULL),
+ * or -1 if handler returns an error.
+ **/
+int
+nih_list_foreach (const NihList *list, size_t *len,
+	NihListHandler handler, void *data)
+{
+	int ret;
+
+	nih_assert (list);
+
+	if (len) *len = 0;
+
+	if (!len && !handler) return 0;
+
+	NIH_LIST_FOREACH (list, iter) {
+		if (handler) {
+			ret = handler (iter, data);
+			if (ret == FALSE) return -1;
+		}
+		if (len) ++*len;
+	}
+
+	return 0;
+}
+
+/**
+ * nih_list_count:
+ * @list: list.
+ * 
+ * Returns count of number of entries in @list.
+ **/
+size_t
+nih_list_count (const NihList *list)
+{
+	size_t len = 0;
+	int ret;
+
+	nih_assert (list);
+
+	ret = nih_list_foreach (list, &len, NULL, NULL);
+
+	return (ret == -1 ? 0 : len);
+}

=== modified file 'nih/list.h'
--- nih/list.h	2011-01-06 09:28:39 +0000
+++ nih/list.h	2011-05-08 11:56:38 +0000
@@ -110,6 +110,17 @@
 	};
 } NihListEntry;
 
+/**
+ * NihListHandler:
+ * @entry: list entry being visited,
+ * @data: data pointer.
+ *
+ * A list handler is a function called for each list entry
+ * when iterating over a list.
+ *
+ * Returns: TRUE if list entry process correctly, else FALSE.
+ **/
+typedef int (*NihListHandler) (NihList *entry, void *data);
 
 /**
  * NIH_LIST_EMPTY:
@@ -208,6 +219,13 @@
 NihList *     nih_list_remove    (NihList *entry);
 int           nih_list_destroy   (NihList *entry);
 
+int           nih_list_foreach   (const NihList *list, size_t *len,
+                                  NihListHandler handler, void *data)
+	__attribute__((unused));
+
+size_t        nih_list_count     (const NihList *list)
+	__attribute__((warn_unused_result, unused));
+
 NIH_END_EXTERN
 
 #endif /* NIH_LIST_H */

=== modified file 'nih/tests/test_hash.c'
--- nih/tests/test_hash.c	2009-06-23 09:29:37 +0000
+++ nih/tests/test_hash.c	2011-05-08 11:56:38 +0000
@@ -25,6 +25,11 @@
 #include <nih/alloc.h>
 #include <nih/list.h>
 #include <nih/hash.h>
+#include <nih/string.h>
+
+#define HASH_HANDLER_DATA_VALUE 42
+#define LIST_ENTRIES             4
+#define ERROR_ON_ENTRY           3
 
 
 typedef struct hash_entry {
@@ -514,7 +519,7 @@
 	 * in the hash in the order we expect them to come out in, but add
 	 * them in a different order for sanity.
 	 */
-	TEST_FUNCTION ("NIH_HASH_FOREACH");
+	TEST_FUNCTION ("NIH_HASH_FOREACH macro");
 	hash = nih_hash_string_new (NULL, 0);
 	entry0 = entry[2] = new_entry (hash, "entry 1");
 	entry1 = entry[1] = new_entry (hash, "entry 2");
@@ -542,6 +547,173 @@
 	nih_free (hash);
 }
 
+int
+hash_handler1 (NihList *entry, int *data)
+{
+	TEST_NE_P (entry, NULL);
+	TEST_NE_P (data, NULL);
+
+	TEST_EQ (*data, HASH_HANDLER_DATA_VALUE);
+
+	return TRUE;
+}
+
+int
+hash_handler2 (NihList *entry, int *data)
+{
+	static size_t i = 0;
+
+	TEST_NE_P (entry, NULL);
+	TEST_NE_P (data, NULL);
+
+	++i;
+	*data = i;
+
+	return TRUE;
+}
+
+int
+hash_handler3 (NihList *entry, void *data)
+{
+	static size_t i = 0;
+
+	TEST_NE_P (entry, NULL);
+	TEST_NE_P (data, NULL);
+
+	++i;
+	*(int *)data = i;
+
+	if (i == ERROR_ON_ENTRY)
+		return FALSE;
+
+	return TRUE;
+}
+
+void
+test_foreach_func (void)
+{
+	NihHash *hash;
+	NihList *entry[LIST_ENTRIES];
+	NihList *entry0, *entry1, *entry2, *entry3;
+	size_t   len   = 0;
+	int      data1 = HASH_HANDLER_DATA_VALUE;
+	size_t   data2 = 0;
+	int      ret;
+
+	TEST_FUNCTION ("nih_hash_foreach");
+
+	hash = nih_hash_string_new (NULL, 0);
+	TEST_NE_P (hash, NULL);
+
+
+	TEST_FEATURE ("with no handler, length or data params");
+	TEST_EQ (nih_hash_foreach (hash, NULL, NULL, NULL), 0);
+
+
+	TEST_FEATURE ("with length param, but no handler");
+
+	ret = nih_hash_foreach (hash, &len, NULL, NULL);
+	TEST_EQ (ret, 0);
+	TEST_EQ (len, 0);
+
+
+	TEST_FEATURE ("with data and handler reading a value, but no len");
+
+	entry0 = entry[0] = new_entry (hash, "entry 1");
+	entry1 = entry[1] = new_entry (hash, "entry 2");
+	entry2 = entry[2] = new_entry (hash, "entry 3");
+	entry3 = entry[3] = new_entry (hash, "entry 4");
+
+	nih_hash_add (hash, entry0);
+	nih_hash_add (hash, entry1);
+	nih_hash_add (hash, entry2);
+	nih_hash_add (hash, entry3);
+
+	ret = nih_hash_foreach (hash, NULL,
+		(NihListHandler)hash_handler1, &data1);
+
+	TEST_EQ (ret, 0);
+	TEST_EQ (data1, HASH_HANDLER_DATA_VALUE);
+
+
+	TEST_FEATURE ("with len, data and handler reading a value");
+
+	ret = nih_hash_foreach (hash, &len,
+		(NihListHandler)hash_handler1, &data1);
+
+	TEST_EQ (ret, 0);
+	TEST_EQ (data1, HASH_HANDLER_DATA_VALUE);
+	TEST_EQ (len, LIST_ENTRIES);
+
+
+	TEST_FEATURE ("with len, data and hander changing a value");
+
+	len = 0;
+	data2 = 0;
+	ret = nih_hash_foreach (hash, &len,
+		(NihListHandler)hash_handler2, &data2);
+
+	TEST_EQ (ret, 0);
+	TEST_EQ (len, LIST_ENTRIES);
+	TEST_EQ (data2, LIST_ENTRIES);
+
+
+	TEST_FEATURE ("with handler returning error");
+
+	len = 0;
+	data2 = 0;
+	ret = nih_hash_foreach (hash, &len,
+		(NihListHandler)hash_handler3, &data2);
+	TEST_EQ (ret, -1);
+	TEST_EQ (len, ERROR_ON_ENTRY-1);
+}
+
+void
+test_count (void)
+{
+	NihHash        *hash;
+	NihList        *entry[LIST_ENTRIES];
+	nih_local char *key;
+	NihList        *e;
+	size_t          i;
+
+	TEST_FUNCTION ("nih_hash_count");
+
+	hash = nih_hash_string_new (NULL, 0);
+	TEST_NE_P (hash, NULL);
+
+	i = 0;
+	TEST_FEATURE ("with no initial entries");
+	TEST_EQ (nih_hash_count (hash), i);
+
+	entry[0] = new_entry (hash, "entry 1");
+	entry[1] = new_entry (hash, "entry 2");
+	entry[2] = new_entry (hash, "entry 3");
+	entry[3] = new_entry (hash, "entry 4");
+
+	TEST_FEATURE ("with increasing number of entries");
+
+	for (i=0; i < LIST_ENTRIES; ++i) {
+		nih_hash_add (hash, entry[i]);
+		TEST_EQ (nih_hash_count (hash), i+1);
+	}
+
+	TEST_FEATURE ("with decreasing number of entries");
+
+	for (i=LIST_ENTRIES; i > 0; --i) {
+		key = nih_sprintf (NULL, "entry %d", i);
+		TEST_NE_P (key, NULL);
+
+		e = nih_hash_lookup (hash, key);
+		TEST_NE_P (e, NULL);
+		nih_free (nih_list_remove (e));
+		TEST_EQ (nih_hash_count (hash), i-1);
+	}
+
+	TEST_FEATURE ("with no entries");
+	TEST_EQ (nih_hash_count (hash), 0);
+}
+
 void
 test_foreach_safe (void)
 {
@@ -553,7 +725,7 @@
 	 * order, visiting each entry in each bin; and that it's safe to
 	 * remove the entries while doing so.
 	 */
-	TEST_FUNCTION ("NIH_HASH_FOREACH_SAFE");
+	TEST_FUNCTION ("NIH_HASH_FOREACH_SAFE macro");
 	hash = nih_hash_string_new (NULL, 0);
 	entry0 = entry[2] = new_entry (hash, "entry 1");
 	entry1 = entry[1] = new_entry (hash, "entry 2");
@@ -619,6 +791,8 @@
 	test_lookup ();
 	test_foreach ();
 	test_foreach_safe ();
+	test_foreach_func ();
+	test_count ();
 	test_string_key ();
 
 	return 0;

=== modified file 'nih/tests/test_list.c'
--- nih/tests/test_list.c	2009-06-23 09:29:37 +0000
+++ nih/tests/test_list.c	2011-05-08 11:56:38 +0000
@@ -25,6 +25,9 @@
 #include <nih/alloc.h>
 #include <nih/list.h>
 
+#define LIST_HANDLER_DATA_VALUE 42
+#define LIST_ENTRIES             3
+#define ERROR_ON_ENTRY           2
 
 void
 test_init (void)
@@ -251,7 +254,7 @@
 {
 	NihList *list, *entry;
 
-	TEST_FUNCTION ("NIH_LIST_EMPTY");
+	TEST_FUNCTION ("NIH_LIST_EMPTY macro");
 
 	/* Check that NIH_LIST_EMPTY is TRUE on an empty list */
 	TEST_FEATURE ("with empty list");
@@ -281,7 +284,7 @@
 	/* Check that NIH_LIST_FOREACH iterates the list correctly in
 	 * order, visiting each entry.
 	 */
-	TEST_FUNCTION ("NIH_LIST_FOREACH");
+	TEST_FUNCTION ("NIH_LIST_FOREACH macro");
 	list = nih_list_new (NULL);
 	entry[0] = nih_list_add (list, nih_list_new (NULL));
 	entry[1] = nih_list_add (list, nih_list_new (NULL));
@@ -306,13 +309,159 @@
 	nih_free (entry[2]);
 }
 
+int
+list_handler1 (NihList *entry, int *data)
+{
+	TEST_NE_P (entry, NULL);
+	TEST_NE_P (data, NULL);
+
+	TEST_EQ (*data, LIST_HANDLER_DATA_VALUE);
+
+	return TRUE;
+}
+
+int
+list_handler2 (NihList *entry, int *data)
+{
+	static size_t i = 0;
+
+	TEST_NE_P (entry, NULL);
+	TEST_NE_P (data, NULL);
+
+	++i;
+	*data = i;
+
+	return TRUE;
+}
+
+int
+list_handler3 (NihList *entry, void *data)
+{
+	static size_t i = 0;
+
+	TEST_NE_P (entry, NULL);
+	TEST_NE_P (data, NULL);
+
+	++i;
+	*(int *)data = i;
+
+	if (i == ERROR_ON_ENTRY)
+		return FALSE;
+
+	return TRUE;
+}
+
+void
+test_foreach_func (void)
+{
+	NihList *list, *entry[LIST_ENTRIES];
+	size_t   len   = 0;
+	int      data1 = LIST_HANDLER_DATA_VALUE;
+	size_t   data2 = 0;
+	int      ret;
+
+	TEST_FUNCTION ("nih_list_foreach");
+
+	list = nih_list_new (NULL);
+	TEST_NE_P (list, NULL);
+
+
+	TEST_FEATURE ("with no handler, length or data params");
+
+	ret = nih_list_foreach (list, NULL, NULL, NULL);
+	TEST_EQ (ret, 0);
+
+	TEST_FEATURE ("with length param, but no handler");
+	ret = nih_list_foreach (list, &len, NULL, NULL);
+	TEST_EQ (ret, 0);
+	TEST_EQ (len, 0);
+
+
+	TEST_FEATURE ("with data and handler reading a value, but no len");
+
+	entry[0] = nih_list_add (list, nih_list_new (NULL));
+	entry[1] = nih_list_add (list, nih_list_new (NULL));
+	entry[2] = nih_list_add (list, nih_list_new (NULL));
+
+	ret = nih_list_foreach (list, NULL,
+		(NihListHandler)list_handler1, &data1);
+
+	TEST_EQ (ret, 0);
+	TEST_EQ (data1, LIST_HANDLER_DATA_VALUE);
+
+
+	TEST_FEATURE ("with len, data and handler reading a value");
+
+	ret = nih_list_foreach (list, &len,
+		(NihListHandler)list_handler1, &data1);
+
+	TEST_EQ (ret, 0);
+	TEST_EQ (len, LIST_ENTRIES);
+	TEST_EQ (data1, LIST_HANDLER_DATA_VALUE);
+
+
+	TEST_FEATURE ("with len, data and hander changing a value");
+
+	len = 0;
+	data2 = 0;
+	ret = nih_list_foreach (list, &len,
+		(NihListHandler)list_handler2, &data2);
+	TEST_EQ (ret, 0);
+	TEST_EQ (len, LIST_ENTRIES);
+	TEST_EQ (data2, LIST_ENTRIES);
+
+
+	TEST_FEATURE ("with handler returning error");
+
+	len = 0;
+	data2 = 0;
+	ret = nih_list_foreach (list, &len,
+		(NihListHandler)list_handler3, &data2);
+	TEST_EQ (ret, -1);
+	TEST_EQ (len, ERROR_ON_ENTRY-1);
+}
+
+void
+test_count (void)
+{
+	NihList *list, *entry[3];
+	size_t   i;
+
+	TEST_FUNCTION ("nih_list_count");
+
+	list = nih_list_new (NULL);
+	TEST_NE_P (list, NULL);
+
+	TEST_FEATURE ("with no initial entries");
+	TEST_EQ (nih_list_count (list), 0);
+	TEST_EQ (NIH_LIST_EMPTY (list), TRUE);
+
+	TEST_FEATURE ("with increasing number of entries");
+	for (i=0; i < LIST_ENTRIES; ++i) {
+		entry[i] = nih_list_add (list, nih_list_new (NULL));
+		TEST_EQ (nih_list_count (list), i+1);
+	}
+
+	TEST_FEATURE ("with decreasing number of entries");
+
+	for (i=LIST_ENTRIES; i > 0; --i) {
+		nih_free (nih_list_remove (list->next));
+		TEST_EQ (nih_list_count (list), i-1);
+	}
+
+	TEST_FEATURE ("with no entries");
+	TEST_EQ (nih_list_count (list), 0);
+	TEST_EQ (NIH_LIST_EMPTY (list), TRUE);
+
+}
+
 void
 test_foreach_safe (void)
 {
 	NihList *list, *entry[3];
 	int      i;
 
-	TEST_FUNCTION ("NIH_LIST_FOREACH_SAFE");
+	TEST_FUNCTION ("NIH_LIST_FOREACH_SAFE macro");
 
 	/* Check that NIH_LIST_FOREACH_SAFE iterates the list correctly in
 	 * order, visiting each entry.
@@ -503,6 +652,8 @@
 	test_empty ();
 	test_foreach ();
 	test_foreach_safe ();
+	test_foreach_func ();
+	test_count ();
 	test_remove ();
 	test_destroy ();
 

=== modified file 'nih/tests/test_tree.c'
--- nih/tests/test_tree.c	2009-06-23 09:29:37 +0000
+++ nih/tests/test_tree.c	2011-05-08 11:56:38 +0000
@@ -25,6 +25,9 @@
 #include <nih/alloc.h>
 #include <nih/tree.h>
 
+#define TREE_HANDLER_DATA_VALUE 42
+#define NODE_COUNT               4
+#define ERROR_ON_NODE            3
 
 void
 test_init (void)
@@ -508,7 +511,7 @@
 	NihTree *node[12], *expect[13];
 	int      i;
 
-	TEST_FUNCTION ("NIH_TREE_FOREACH");
+	TEST_FUNCTION ("NIH_TREE_FOREACH macro");
 	for (i = 0; i < 12; i++)
 		node[i] = nih_tree_new (NULL);
 
@@ -589,6 +592,170 @@
 		nih_free (node[i]);
 }
 
+int
+tree_handler1 (NihTree *node, void *data)
+{
+	TEST_NE_P (node, NULL);
+	TEST_NE_P (data, NULL);
+
+	TEST_EQ (*(int *)data, TREE_HANDLER_DATA_VALUE);
+
+	return TRUE;
+}
+
+int
+tree_handler2 (NihTree *node, void *data)
+{
+	static size_t count = 0;
+
+	TEST_NE_P (node, NULL);
+	TEST_NE_P (data, NULL);
+
+	++count;
+	*(int *)data = count;
+
+	return TRUE;
+}
+
+int
+tree_handler3 (NihTree *node, void *data)
+{
+	static size_t i = 0;
+
+	TEST_NE_P (node, NULL);
+	TEST_NE_P (data, NULL);
+
+	++i;
+	*(int *)data = i;
+
+	if (i == ERROR_ON_NODE)
+		return FALSE;
+
+	return TRUE;
+}
+
+void
+test_foreach_func (void)
+{
+	NihTree *tree, *node1, *node2, *node3;
+	int      data1 = TREE_HANDLER_DATA_VALUE;
+	size_t   data2 = 0;
+	int      ret;
+	size_t   len;
+
+	TEST_FUNCTION ("nih_tree_foreach function");
+
+	tree = nih_tree_new (NULL);
+
+
+	TEST_FEATURE ("with no handler, length or data params");
+	TEST_EQ (nih_tree_foreach (tree, NULL, NULL, NULL), 0);
+
+
+	TEST_FEATURE ("with length param, but no handler");
+
+	ret = nih_tree_foreach (tree, &len, NULL, NULL);
+	TEST_EQ (ret, 0);
+	TEST_EQ (len, 1);
+
+	node1 = nih_tree_new (tree);
+	node2 = nih_tree_new (tree);
+	node3 = nih_tree_new (tree);
+
+	nih_tree_add (tree, node1, NIH_TREE_LEFT);
+	ret = nih_tree_foreach (tree, &len, NULL, NULL);
+	TEST_EQ (ret, 0);
+	TEST_EQ (len, 2);
+
+	nih_tree_add (tree, node2, NIH_TREE_RIGHT);
+	ret = nih_tree_foreach (tree, &len, NULL, NULL);
+	TEST_EQ (ret, 0);
+	TEST_EQ (len, 3);
+
+	nih_tree_add (node1, node3, NIH_TREE_RIGHT);
+
+	ret = nih_tree_foreach (tree, &len, NULL, NULL);
+	TEST_EQ (ret, 0);
+	TEST_EQ (len, 4);
+
+
+	TEST_FEATURE ("with data and handler reading a value, but no len");
+
+	ret = nih_tree_foreach (tree, NULL,
+			(NihTreeHandler)tree_handler1, &data1);
+
+	TEST_EQ (ret, 0);
+	TEST_EQ (data1, TREE_HANDLER_DATA_VALUE);
+
+	TEST_FEATURE ("with len, data and handler reading a value");
+
+	ret = nih_tree_foreach (tree, &len,
+			(NihTreeHandler)tree_handler1, &data1);
+
+	TEST_EQ (ret, 0);
+	TEST_EQ (data1, TREE_HANDLER_DATA_VALUE);
+	TEST_EQ (len, NODE_COUNT);
+
+	TEST_FEATURE ("with len, data and handler changing a value");
+
+	data2 = 0;
+	ret = nih_tree_foreach (tree, &len,
+			(NihTreeHandler)tree_handler2, &data2);
+
+	TEST_EQ (ret, 0);
+	TEST_EQ (len, NODE_COUNT);
+	TEST_EQ (data2, NODE_COUNT);
+
+	TEST_FEATURE ("with handler returning error");
+
+	len = 0;
+	data2 = 0;
+	ret = nih_tree_foreach (tree, &len,
+			(NihTreeHandler)tree_handler3, &data2);
+
+	TEST_EQ (ret, -1);
+	TEST_EQ (len, ERROR_ON_NODE-1);
+}
+
+void
+test_count (void)
+{
+	NihTree *tree, *node1, *node2, *node3;
+
+	TEST_FUNCTION ("nih_tree_count");
+
+	tree  = nih_tree_new (NULL);
+	node1 = nih_tree_new (tree);
+	node2 = nih_tree_new (tree);
+	node3 = nih_tree_new (tree);
+
+	TEST_FEATURE ("with one initial entry");
+	TEST_EQ (nih_tree_count (tree), 1);
+
+	TEST_FEATURE ("with increasing number of entries");
+
+	nih_tree_add (tree, node1, NIH_TREE_LEFT);
+	TEST_EQ (nih_tree_count (tree), 2);
+
+	nih_tree_add (tree, node2, NIH_TREE_RIGHT);
+	TEST_EQ (nih_tree_count (tree), 3);
+
+	nih_tree_add (node1, node3, NIH_TREE_RIGHT);
+	TEST_EQ (nih_tree_count (tree), 4);
+
+	TEST_FEATURE ("with decreasing number of entries");
+	nih_tree_remove (node3);
+	TEST_EQ (nih_tree_count (tree), 3);
+
+	nih_tree_remove (node2);
+	TEST_EQ (nih_tree_count (tree), 2);
+
+	nih_tree_remove (node1);
+
+	TEST_FEATURE ("with one final entry");
+	TEST_EQ (nih_tree_count (tree), 1);
+}
+
 void
 test_prev (void)
 {
@@ -2214,6 +2381,8 @@
 	test_destroy ();
 	test_next ();
 	test_foreach ();
+	test_foreach_func ();
+	test_count ();
 	test_prev ();
 	test_next_pre ();
 	test_foreach_pre ();

=== modified file 'nih/tree.c'
--- nih/tree.c	2009-06-23 09:29:37 +0000
+++ nih/tree.c	2011-05-08 11:56:38 +0000
@@ -619,3 +619,65 @@
 		prev = tmp;
 	}
 }
+
+/**
+ * nih_tree_foreach:
+ *
+ * @tree: tree,
+ * @len: optional output parameter that will contain count of tree nodes,
+ * @handler: optional function called for each tree node,
+ * @data: optional data to pass to handler along with tree node.
+ *
+ * Iterate over specified tree.
+ *
+ * One of @len or @handler may be NULL.
+ * If @handler is NULL and @len is non-NULL, count of tree nodes will
+ * still be returned in @len.
+ * If @handler returns 1, @len will be set to the number of tree nodes
+ * processed successfully up to that point.
+ *
+ * Returns 0 on success (and when both @len and @handler are NULL),
+ * or -1 if handler returns an error.
+ **/
+int
+nih_tree_foreach (NihTree *tree, size_t *len,
+	NihTreeHandler handler, void *data)
+{
+	int ret;
+
+	nih_assert (tree);
+
+	if (len) *len = 0;
+
+	if (!len && !handler) return 0;
+
+	NIH_TREE_FOREACH_FULL (tree, iter, NULL, data) {
+		if (handler) {
+			ret = handler (iter, data);
+			if (!ret) return -1;
+		}
+		if (len) ++*len;
+	}
+
+	return 0;
+}
+
+/**
+ * nih_tree_count:
+ *
+ * @tree: tree.
+ * 
+ * Returns count of number of entries in @tree.
+ **/
+size_t
+nih_tree_count (NihTree *tree)
+{
+	size_t len = 0;
+	int ret;
+
+	nih_assert (tree);
+
+	ret = nih_tree_foreach (tree, &len, NULL, NULL);
+
+	return (ret == -1 ? 0 : len);
+}

=== modified file 'nih/tree.h'
--- nih/tree.h	2009-06-23 09:29:37 +0000
+++ nih/tree.h	2011-05-08 11:56:38 +0000
@@ -138,6 +138,17 @@
  **/
 typedef int (*NihTreeFilter) (void *data, NihTree *node);
 
+/**
+ * NihTreeHandler:
+ * @node: tree entry being visited,
+ * @data: data pointer.
+ *
+ * A tree handler is a function called for each tree node
+ * when iterating over a tree.
+ *
+ * Returns: TRUE if tree entry process correctly, else FALSE.
+ **/
+typedef int (*NihTreeHandler) (NihTree *node, void *data);
 
 /**
  * NIH_TREE_FOREACH_FULL:
@@ -370,6 +381,13 @@
 NihTree *     nih_tree_prev_post_full (NihTree *tree, NihTree *node,
 				       NihTreeFilter filter, void *data);
 
+int           nih_tree_foreach        (NihTree *tree, size_t *len,
+				       NihTreeHandler handler, void *data)
+	__attribute__((unused));
+
+size_t        nih_tree_count          (NihTree *tree)
+	__attribute__((warn_unused_result, unused));
+
 NIH_END_EXTERN
 
 #endif /* NIH_TREE_H */

=== modified file 'po/libnih.pot'
--- po/libnih.pot	2010-12-23 22:04:08 +0000
+++ po/libnih.pot	2011-05-08 11:56:38 +0000
@@ -6,9 +6,9 @@
 #, fuzzy
 msgid ""
 msgstr ""
-"Project-Id-Version: libnih 1.0.3\n"
+"Project-Id-Version: libnih 1.0.4\n"
 "Report-Msgid-Bugs-To: [e-mail]\n"
-"POT-Creation-Date: 2010-12-23 21:53+0000\n"
+"POT-Creation-Date: 2011-05-08 12:30+0100\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <[e-mail]>\n"