From 714eae1a9a3211babef880d2b017c7eb4a2d2dc1 Mon Sep 17 00:00:00 2001 From: gastal Date: Fri, 10 Jun 2011 13:42:19 +0000 Subject: [PATCH] eina: Eina_Iterator documentation. git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/eina@60193 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- src/examples/Makefile.am | 2 ++ src/examples/eina_iterator_01.c | 66 +++++++++++++++++++++++++++++++++++++++++ src/include/Eina.h | 1 + src/include/eina_iterator.h | 59 ++++++++++++++++++++++++++++++++++++ 4 files changed, 128 insertions(+) create mode 100644 src/examples/eina_iterator_01.c diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am index 3805eab..756dcff 100644 --- a/src/examples/Makefile.am +++ b/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 \ diff --git a/src/examples/eina_iterator_01.c b/src/examples/eina_iterator_01.c new file mode 100644 index 0000000..f467f90 --- /dev/null +++ b/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 + +#include + +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; +} diff --git a/src/include/Eina.h b/src/include/Eina.h index 4fcba12..67ebea4 100644 --- a/src/include/Eina.h +++ b/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. diff --git a/src/include/eina_iterator.h b/src/include/eina_iterator.h index 6358d5b..3eba53b 100644 --- a/src/include/eina_iterator.h +++ b/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" * * @{ */ -- 2.7.4