eina: Eina_Accessor documentation.

git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/eina@60284 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33

diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am
index 756dcff..fb0fa2f 100644 (file)
--- a/src/examples/Makefile.am
+++ b/src/examples/Makefile.am
@@ -11,6 +11,7 @@ LDADD = \
        $(top_builddir)/src/lib/libeina.la
 
 SRCS = \
+       eina_accessor_01.c \
        eina_array_01.c \
        eina_array_02.c \
        eina_hash_01.c \
@@ -30,6 +31,7 @@ endif
 
 if EFL_BUILD_EXAMPLES
 pkglib_PROGRAMS += \
+       eina_accessor_01 \
     eina_array_01 \
        eina_array_02 \
        eina_hash_01 \

diff --git a/src/examples/eina_accessor_01.c b/src/examples/eina_accessor_01.c
new file mode 100644 (file)
index 0000000..c48fdc6
--- /dev/null
+++ b/src/examples/eina_accessor_01.c
@@ -0,0 +1,55 @@
+//Compile with:
+//gcc -g `pkg-config --cflags --libs eina` eina_accessor_01.c -o eina_accessor_01
+
+#include <stdio.h>
+
+#include <Eina.h>
+
+int
+main(int argc, char **argv)
+{
+   const char *strings[] = {
+      "even", "odd", "even", "odd", "even", "odd", "even", "odd", "even", "odd"
+   };
+   const char *more_strings[] = {
+      "0", "1", "2", "3", "4", "5", "6", "7", "8", "9"
+   };
+   Eina_Array *array;
+   Eina_List *list = NULL;
+   Eina_Accessor *acc;
+   unsigned short int i;
+   void *data;
+
+   eina_init();
+
+   array = eina_array_new(10);
+
+   for (i = 0; i < 10; i++)
+     {
+        eina_array_push(array, strings[i]);
+        list = eina_list_append(list, more_strings[i]);
+     }
+
+   acc = eina_array_accessor_new(array);
+   for(i = 1; i < 10; i += 2)
+     {
+        eina_accessor_data_get(acc, i, &data);
+        printf("%s\n", (const char *)data);
+     }
+   eina_accessor_free(acc);
+   eina_array_free(array);
+
+   acc = eina_list_accessor_new(list);
+   for(i = 1; i < 10; i += 2)
+     {
+        eina_accessor_data_get(acc, i, &data);
+        printf("%s\n", (const char *)data);
+     }
+
+   eina_list_free(eina_accessor_container_get(acc));
+   eina_accessor_free(acc);
+
+   eina_shutdown();
+
+   return 0;
+}

diff --git a/src/include/eina_accessor.h b/src/include/eina_accessor.h
index 505efa3..1b43750 100644 (file)
--- a/src/include/eina_accessor.h
+++ b/src/include/eina_accessor.h
@@ -25,6 +25,57 @@
 #include "eina_magic.h"
 
 /**
+ * @page eina_accessor_example_01_page Eina_Accessor usage
+ * @dontinclude eina_accessor_01.c
+ *
+ * We start by including neccessary headers, declaring variables and
+ * initializing eina:
+ * @skip #include
+ * @until eina_init
+ *
+ * Next we populate our array and list:
+ * @until }
+ *
+ * Now that we have two containers populated we can actually start the example
+ * and create an accessor:
+ * @until accessor_new
+ *
+ * Once having the accessor we can use it to access certain elements in the
+ * container:
+ * @until }
+ * @note Unlike iterators accessors allow us non-linear access, which allows us
+ * to print only the odd elements in the container.
+ *
+ * As with every other resource we allocate we need to free the accessor(and the
+ * array):
+ * @until array_free
+ *
+ * Now we create another accessor, this time for the list:
+ * @until accessor_new
+ *
+ * And now the interesting bit, we use the same code we used above to print
+ * parts of the array to print parts of the list:
+ * @until }
+ *
+ * And to free the list we use a gimmick, instead of freeing @a list, we ask the
+ * accessor for it's container and free that:
+ * @until list_free
+ *
+ * Finally we shut eina down and leave:
+ * @until }
+ *
+ * The full source code can be found on the examples folder
+ * on the @ref eina_accessor_01_c "eina_accessor_01.c" file.
+ */
+
+/**
+ * @page eina_accessor_01_c Eina_Accessor usage example
+ *
+ * @include eina_accessor_01.c
+ * @example eina_accessor_01.c
+ */
+
+/**
  * @addtogroup Eina_Accessor_Group Accessor Functions
  *
  * @brief These functions manage accessor on containers.