Eina inline array example.

git-svn-id: http://svn.enlightenment.org/svn/e/trunk/eina@68270 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33

diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am
index 66d65a3..c8d80f9 100644 (file)
--- a/src/examples/Makefile.am
+++ b/src/examples/Makefile.am
@@ -43,7 +43,8 @@ SRCS = \
        eina_model_03.c \
        eina_value_01.c \
        eina_value_02.c \
-       eina_value_03.c
+       eina_value_03.c \
+       eina_inarray_01.c
 
 examples_PROGRAMS =
 
@@ -86,7 +87,8 @@ examples_PROGRAMS += \
        eina_model_04 \
        eina_value_01 \
        eina_value_02 \
-       eina_value_03
+       eina_value_03 \
+       eina_inarray_01
 
 eina_model_04_SOURCES = \
        eina_model_04_animal.c \

diff --git a/src/examples/eina_inarray_01.c b/src/examples/eina_inarray_01.c
new file mode 100644 (file)
index 0000000..d004c8e
--- /dev/null
+++ b/src/examples/eina_inarray_01.c
@@ -0,0 +1,49 @@
+#include <Eina.h>
+
+int
+cmp(const void *a, const void *b)
+{
+   return *(int*)a > *(int*)b;
+}
+
+int main(int argc, char **argv)
+{
+   Eina_Inarray *iarr;
+   char ch, *ch2;
+   int a, *b;
+
+   eina_init();
+   iarr = eina_inarray_new(sizeof(char), 0);
+
+   ch = 'a';
+   eina_inarray_append(iarr, &ch);
+   ch = 'b';
+   eina_inarray_append(iarr, &ch);
+   ch = 'c';
+   eina_inarray_append(iarr, &ch);
+   ch = 'd';
+   eina_inarray_append(iarr, &ch);
+
+   printf("Inline array of chars:\n");
+   EINA_INARRAY_FOREACH(iarr, ch2)
+     printf("char: %c(pointer: %p)\n", *ch2, ch2);
+
+   eina_inarray_flush(iarr);
+   eina_inarray_setup(iarr, sizeof(int), 4);
+
+   a = 97;
+   eina_inarray_append(iarr, &a);
+   a = 98;
+   eina_inarray_append(iarr, &a);
+   a = 100;
+   eina_inarray_append(iarr, &a);
+   a = 99;
+   eina_inarray_insert_sorted(iarr, &a, cmp);
+
+   printf("Inline array of integers with %d elements:\n", eina_inarray_count(iarr));
+   EINA_INARRAY_FOREACH(iarr, b)
+     printf("int: %d(pointer: %p)\n", *b, b);
+
+   eina_inarray_free(iarr);
+   eina_shutdown();
+}

diff --git a/src/include/eina_inarray.h b/src/include/eina_inarray.h
index 4a09ab6..c9114b7 100644 (file)
--- a/src/include/eina_inarray.h
+++ b/src/include/eina_inarray.h
@@ -24,6 +24,101 @@
 #include "eina_accessor.h"
 
 /**
+ * @page eina_inarray_example_01 Eina inline array usage
+ * @dontinclude eina_inarray_01.c
+ *
+ * This example will create an inline array of chars, add some elements, print
+ * it, re-purpose the array to store ints, add some elements and print that.
+ *
+ * We'll start with a function to compare ints we need this because the '>'
+ * operator is not a function and can't be used where Eina_Compare_Cb is needed.
+ * @skip int
+ * @until }
+ *
+ * And then move on to the code we actually care about, starting with variable
+ * declarations and eina initialization:
+ * @until eina_init
+ *
+ * Creating an inline array is very simple, we just need to know what type we
+ * want to store:
+ * @until inarray_new
+ * @note The second parameter(the step) is left at zero which means that eina
+ * will choose an appropriate value, this should @b only be changed if it's
+ * known, beforehand, how many elements the array will have.
+ *
+ * Once we have an array we can start adding elements to it. Because the
+ * insertion function expect a memory address we have to put the value we want
+ * to store in a variable(this should be no problem since in real world usage
+ * that's usually where the value will be anyways):
+ * @until append
+ * @note Because the inline array copies the value given to it we can later
+ * change @c ch, which we do, without affecting the contents of the array.
+ *
+ * So let's add some more elements:
+ * @until append
+ * @until append
+ * @until append
+ *
+ * We will then iterate over our array and print every position of it. The thing
+ * to note here is not so much the values which will be the expected 'a', 'b',
+ * 'c' and 'd', but rather the memory address of these values, they are
+ * sequential:
+ * @until printf
+ * @until printf
+ *
+ * We'll now use our array to store ints, so we need to first erase every member
+ * currently on the array:
+ * @until _flush
+ *
+ * And then to be able to store a different type on the same array we use the
+ * eina_array_setup() function, which is just like the eina_inarray_new()
+ * function except it receives already allocated memory. This time we're going
+ * to ask eina to use a step of size 4 because that's how many elements we'll be
+ * putting on the array:
+ * @until _setup
+ * @note Strictly speaking the reason to call eina_inarray_setup() is not
+ * because we're storing different type, but rather because our types have
+ * different sizes. Eina inline arrays don't actually know anything about types,
+ * they only deal in blocks of memory of a given size.
+ * @note Since eina_array_setup() receives already allocated memory you can(and
+ * it is in fact good practice) use inline arrays not declared as pointers:
+ * @code
+ * Eina_Inarray arr;
+ * eina_inarray_setup(&arr, sizeof(int), 4);
+ * @endcode
+ *
+ * And now to add our integer values to the array:
+ * @until append
+ * @until append
+ * @until append
+ *
+ * Just to change things up a bit we've left out the 99 value, but will still
+ * add it in such a way to keep the array ordered. There are many ways to do
+ * this, we could use eina_inarray_insert_at(), or we could change the value
+ * of the last member using eina_inarray_replace_at() and then append the values
+ * in the right order, but for no particular reason we're going to use
+ * eina_inarray_insert_sorted() instead:
+ * @until insert_sorted
+ *
+ * We then print the size of our array, and the array itself, much like last
+ * time the values are not surprising, and neither should it be that the memory
+ * addresses are contiguous:
+ * @until printf
+ * @until printf
+ *
+ * Once done we free our array and shutdown eina:
+ * @until }
+ *
+ * The source for this example: @ref eina_inarray_01_c
+ */
+
+/**
+ * @page eina_inarray_01_c eina_inarray_01.c
+ * @include eina_inarray_01.c
+ * @example eina_inarray_01.c
+ */
+
+/**
  * @addtogroup Eina_Data_Types_Group Data Types
  *
  * @since 1.2
@@ -40,6 +135,18 @@
 /**
  * @defgroup Eina_Inline_Array_Group Inline Array
  *
+ * Inline array is a container that stores the data itself not pointers to data,
+ * this means there is no memory fragmentation, also for small data types(such
+ * as char, short, int, etc.) it's more memory efficient.
+ *
+ * Usage of the inline array is very similar to that of other
+ * @ref Eina_Containers_Group, like all arrays adding elements to the beginning
+ * of the array is a lot more costly than appending, so those operations should
+ * be minimized.
+ *
+ * Example:
+ * @ref eina_inarray_example_01
+ *
  * @{
  */