eina: Eina_Iterator documentation.

SVN revision: 60193

legacy/eina/src/examples/Makefile.am

@@ -15,6 +15,7 @@ SRCS = \
 	eina_array_02.c \
 	eina_hash_01.c \
 	eina_hash_02.c \
+	eina_iterator_01.c \
 	eina_list_01.c \
 	eina_list_02.c \
 	eina_list_03.c \
@@ -33,6 +34,7 @@ pkglib_PROGRAMS += \
 	eina_array_02 \
 	eina_hash_01 \
 	eina_hash_02 \
+	eina_iterator_01 \
 	eina_list_01 \
 	eina_list_02 \
 	eina_list_03 \

legacy/eina/src/examples/eina_iterator_01.c

@@ -0,0 +1,66 @@
+//Compile with:
+//gcc -g `pkg-config --cflags --libs eina` eina_iterator_01.c -o eina_iterator_01
+
+#include <stdio.h>
+
+#include <Eina.h>
+
+static Eina_Bool
+print_one(const void *container, void *data, void *fdata)
+{
+   printf("%s\n", (char*)data);
+   return EINA_TRUE;
+}
+
+static void
+print_eina_container(Eina_Iterator *it)
+{
+   eina_iterator_foreach(it, print_one, NULL);
+   printf("\n");
+}
+
+int
+main(int argc, char **argv)
+{
+   const char *strings[] = {
+      "unintersting string", "husker", "starbuck", "husker"
+   };
+   const char *more_strings[] = {
+      "very unintersting string",
+      "what do your hear?",
+      "nothing but the rain",
+      "then grab your gun and bring the cat in"
+   };
+   Eina_Array *array;
+   Eina_List *list = NULL;
+   Eina_Iterator *it;
+   unsigned short int i;
+   char *uninteresting;
+
+   eina_init();
+
+   array = eina_array_new(4);
+
+   for (i = 0; i < 4; i++)
+      {
+        eina_array_push(array, strings[i]);
+        list = eina_list_append(list, more_strings[i]);
+      }
+
+   it = eina_array_iterator_new(array);
+   eina_iterator_next(it, &uninteresting);
+   print_eina_container(it);
+   eina_array_free(eina_iterator_container_get(it));
+   eina_iterator_free(it);
+
+   it = eina_list_iterator_new(list);
+   eina_iterator_next(it, &uninteresting);
+   print_eina_container(it);
+   eina_iterator_free(it);
+
+   eina_list_free(list);
+
+   eina_shutdown();
+
+   return 0;
+}

legacy/eina/src/include/Eina.h

@@ -71,6 +71,7 @@
  * @li @ref Eina_Hash_Group standard hash of @c void* data.
  * @li @ref Eina_Inline_List_Group list with nodes inlined into user type.
  * @li @ref Eina_List_Group standard list of @c void* data.
+ * @li @ref Eina_Iterator_Group Iterator functions.
  * @li @ref Eina_Matrixsparse_Group sparse matrix of @c void* data.
  * @li @ref Eina_Rbtree_Group red-black tree with nodes inlined into user type.
  * @li @ref Eina_String_Buffer_Group mutable string to prepend, insert or append strings to a buffer.

legacy/eina/src/include/eina_iterator.h

@@ -24,6 +24,63 @@
 #include "eina_types.h"
 #include "eina_magic.h"
 
+/**
+ * @page eina_iterator_example Eina_Iterator usage
+ * @dontinclude eina_iterator_01.c
+ *
+ * As always when using eina we need to include it:
+ * @skip #include
+ * @until Eina.h
+ *
+ * Here we a declare an unimpressive @ref Eina_Each_Cb "function" that prints
+ * some data:
+ * @until }
+ * @note Returning EINA_TRUE is important so we don't stop iterating over the
+ * container.
+ *
+ * And here a more interesting function, it uses an iterator to print the
+ * contents of a container. What's interesting about it is that it doesn't care
+ * the type of container, it works for anything that can provide an iterator:
+ * @until }
+ *
+ * And on to our main function were we declare some variables and initialize
+ * eina, nothing too special:
+ * @until eina_init
+ *
+ * Next we populate both an array and a list with our strings, for more details
+ * see @ref eina_list_01_example and @ref eina_array_01_example:
+ * @until }
+ *
+ * And now we create an array and because the first element of the container
+ * doesn't interest us we skip it:
+ * @until iterator_next
+ *
+ * Having our iterator now pointing to interesting data we go ahead and print:
+ * @until print_eina_container
+ *
+ * As always once data with a structure we free it, but just because we can we
+ * do it by asking the iterator for it's container, and then of course free the
+ * iterator itself:
+ * @until eina_iterator_free
+ *
+ * But so far you're not impressed in @ref eina_array_01_example an array is
+ * also printed, so now we go to the cool stuff and use an iterator to do same
+ * stuff to a list:
+ * @until eina_iterator_free
+ * @note The only significant diference to the block above is in the
+ * function used to create the iterator.
+ *
+ * And now we free the list and shut eina down:
+ * @until }
+ */
+
+/**
+ * @page eina_iterator_01_c Eina_Iterator usage
+ * @page eina_iterator_01_c Eina_Iterator usage
+ *
+ * @include eina_iterator_01.c
+ * @example eina_iterator_01.c
+ */
 
 /**
  * @addtogroup Eina_Iterator_Group Iterator Functions
@@ -41,6 +98,8 @@
  * eina_iterator_free(). To get the data and iterate, use
  * eina_iterator_next(). To call a function on all the elements of a
  * container, use eina_iterator_foreach().
+ * 
+ * Here an @ref eina_iterator_example "example"
  *
  * @{
  */