--- /dev/null
+//Compile with:
+//gcc -g `pkg-config --cflags --libs eina` eina_array_01.c -o eina_array_01
+
+#include <stdio.h>
+#include <string.h>
+
+#include <Eina.h>
+
+int
+main(int argc, char **argv)
+{
+ const char* strings[] = {
+ "helo", "hera", "starbuck", "kat", "boomer",
+ "hotdog", "longshot", "jammer", "crashdown", "hardball",
+ "duck", "racetrack", "apolo", "husker", "freaker",
+ "skulls", "bulldog", "flat top", "hammerhead", "gonzo"
+ };
+ Eina_Array *array;
+ Eina_Array_Iterator iterator;
+ char *item;
+ unsigned int i;
+
+ eina_init();
+
+ array = eina_array_new(20);
+
+ for (i = 0; i < 20; i++)
+ eina_array_push(array, strdup(strings[i]));
+
+ printf("array count: %d\n", eina_array_count_get(array));
+ EINA_ARRAY_ITER_NEXT(array, i, item, iterator)
+ printf("item #%d: %s\n", i, item);
+
+ printf("Top gun: %s\n", (char*)eina_array_data_get(array, 2));
+
+ while (eina_array_count_get(array))
+ free(eina_array_pop(array));
+
+ eina_array_free(array);
+
+ eina_shutdown();
+
+ return 0;
+}
--- /dev/null
+//Compile with:
+//gcc -g `pkg-config --cflags --libs eina` eina_array_02.c -o eina_array_02
+
+#include <stdio.h>
+#include <string.h>
+
+#include <Eina.h>
+
+Eina_Bool keep(void *data, void *gdata)
+{
+ if (strlen((const char*)data) <= 5)
+ return EINA_TRUE;
+ return EINA_FALSE;
+}
+
+int
+main(int argc, char **argv)
+{
+ const char* strings[] = {
+ "helo", "hera", "starbuck", "kat", "boomer",
+ "hotdog", "longshot", "jammer", "crashdown", "hardball",
+ "duck", "racetrack", "apolo", "husker", "freaker",
+ "skulls", "bulldog", "flat top", "hammerhead", "gonzo"
+ };
+ Eina_Array *array;
+ Eina_Array_Iterator iterator;
+ const char *item;
+ unsigned int i;
+
+ eina_init();
+
+ array = eina_array_new(20);
+
+ for (i = 0; i < 20; i++)
+ eina_array_push(array, strings[i]);
+
+ eina_array_remove(array, keep, NULL);
+ EINA_ARRAY_ITER_NEXT(array, i, item, iterator)
+ printf("item #%d: %s\n", i, item);
+
+ eina_array_free(array);
+
+ eina_shutdown();
+
+ return 0;
+}
/**
- * @page tutorial_array_page Array Tutorial
- *
- * The Array data type is allow the storage of data like a C array.
- * It is designed such that the access to its element is very fast.
- * But the addition or removal can be done only at the end of the
- * array. To add or remove an element at any location, the Eina
- * @ref Eina_List_Group is the correct container is the correct one.
- *
- * @section tutorial_error_basic_usage Basic Usage
- *
- * An array must created with eina_array_new(). That function
- * takes an integer as parameter, which is the count of pointers to
- * add when increasing the array size. Once the array is not used
- * anymore, it must be destroyed with eina_array_free().
- *
- * To append data at the end of the array, the function
- * eina_array_push() must be used. To remove the data at the end of
- * the array, eina_array_pop() must be used. Once the array is filled,
- * one can check its elements by iterating over it. A while loop and
- * eina_array_data_get() can be used, or else one can use the
- * predefined macro EINA_ARRAY_ITER_NEXT(). To free all the elements,
- * a while loop can be used with eina_array_count_get(). Here is an
- * example of use:
+ * @page array_01_example_page Basic array usage
+ * @dontinclude eina_array_01.c
*
- * @code
- * #include <stdlib.h>
- * #include <stdio.h>
- * #include <string.h>
- *
- * #include <eina_array.h>
- *
- * int main(void)
- * {
- * const char *strings[] = {
- * "first string",
- * "second string",
- * "third string",
- * "fourth string"
- * };
- * Eina_Array *array;
- * char *item;
- * Eina_Array_Iterator iterator;
- * unsigned int i;
- *
- * if (!eina_init())
- * {
- * printf ("Error during the initialization of eina\n");
- * return EXIT_FAILURE;
- * }
- *
- * array = eina_array_new(16);
- * if (!array)
- * goto shutdown;
- *
- * for (i = 0; i < 4; i++)
- * {
- * eina_array_push(array, strdup(strings[i]));
- * }
- *
- * printf("array count: %d\n", eina_array_count_get(array));
- * EINA_ARRAY_ITER_NEXT(array, i, item, iterator)
- * {
- * printf("item #%d: %s\n", i, item);
- * }
- *
- * while (eina_array_count_get(array))
- * {
- * void *data;
- *
- * data = eina_array_pop(array);
- * free(data);
- * }
- *
- * eina_array_free(array);
- * eina_shutdown();
- *
- * return EXIT_SUCCESS;
- *
- * shutdown:
- * eina_shutdown();
- *
- * return EXIT_FAILURE;
- * }
- * @endcode
+ * For this example we add stdlib.h, stdio.h and string.h for some
+ * convenience functions. The first thing to do to be able to use an
+ * @ref Eina_Array is to include Eina.h:
+ * @skip #include
+ * @until Eina.h
+ *
+ * Now we create our entry point and declare some variables, nothing especial:
+ * @until unsigned
+ *
+ * Before we can start using any array function we need to initialize eina:
+ * @until eina_init
+ *
+ * So now to actually creating our array:
+ * @until array_new
+ * The only interesting thing here is the argument given to the
+ * @ref eina_array_new function, this argument sets how fast the array grows.
+ * If you know before hand how big the array will need to be you should set the
+ * step to that. In our case we can set it to the number of string we have.
+ *
+ * Now let us populate our array with some strings:
+ * @until push
+ * @note Notice we use strdup, so we will have to free that memory later on.
+ *
+ * Now lets check the size of the array:
+ * @until printf
+ *
+ * And now we iterate over the array printing the index and it's value:
+ * @until printf
+ *
+ * One of the strenghts of @ref Eina_Array over @ref Eina_List is that it has
+ * very fast random access to elements, so this is very efficient:
+ * @until printf
+ *
+ * And now we free up the memory allocated with the strdup()s:
+ * @until free
+ *
+ * And the array memory itself:
+ * @until array_free
+ *
+ * And finally shutdown eina and exit:
+ * @until }
+ *
+ * The full source code can be found on the examples folder
+ * on the @ref eina_array_01_c "eina_array_01.c" file.
+ */
+
+/**
+ * @page eina_array_01_c Basic array usage example
+ *
+ * @include eina_array_01.c
+ * @example eina_array_01.c
+ */
+
+/**
+ * @page array_02_example_page Removing array elements
+ * @dontinclude eina_array_02.c
+ *
+ * Just the usual includes:
+ * @skip #include
+ * @until Eina.h
+ *
+ * This the callback we are going to use to decide which strings stay on the
+ * array and which will be removed, we use something simple, but this can be as
+ * complex as you like:
+ * @until }
+ *
+ * This is the same code we used before to populate the list with the slight
+ * difference of not using strdup:
+ * @until array_push
+ *
+ * Now that there is a populated array we can remove elements from it easily:
+ * @until array_remove
+ *
+ * And check that the elements were actually removed:
+ * @until printf
+ *
+ * Since this time we didn't use strdup we don't need to free each string:
+ * @until }
+ *
+ * The full source code can be found on the examples folder
+ * on the @ref eina_array_02_c "eina_array_02.c" file.
+ */
+
+/**
+ * @page eina_array_02_c Basic array usage example
*
- * To be continued
+ * @include eina_array_02.c
+ * @example eina_array_02.c
*/
/**
*
* @brief These functions provide array management.
*
- * The Array data type in Eina is designed to have a very fast access to
+ * The Array data type in Eina is designed to have very fast access to
* its data (compared to the Eina @ref Eina_List_Group). On the other hand,
* data can be added or removed only at the end of the array. To insert
* data at any place, the Eina @ref Eina_List_Group is the correct container
* to use.
*
* To use the array data type, eina_init() must be called before any
- * other array functions. When eina is no more array function is used,
+ * other array functions. When no more eina array functions are used,
* eina_shutdown() must be called to free all the resources.
*
- * An array must be created with eina_array_new(). It allocated all
+ * An array must be created with eina_array_new(). It allocates all
* the necessary data for an array. When not needed anymore, an array
* is freed with eina_array_free(). This function does not free any
* allocated memory used to store the data of each element. For that,
* that is by using #EINA_ARRAY_ITER_NEXT. An example of code is given
* in the description of this macro.
*
- * @warning All the other functions do not check if the used array is
- * valid or not. It's up to the user to be sure of that. It is
- * designed like that for performance reasons.
+ * @warning Functions do not check if the used array is valid or not. It's up to
+ * the user to be sure of that. It is designed like that for performance
+ * reasons.
*
* The usual features of an array are classic ones: to append an
* element, use eina_array_push() and to remove the last element, use
* eina_array_data_get(). The number of elements can be retrieved with
* eina_array_count_get().
*
- * For more information, you can look at the @ref tutorial_array_page.
+ * See here some examples:
+ * @li @ref array_01_example_page
+ * @li @ref array_02_example_page
*
* @{
*/
* @param gdata The data to pass to the function keep.
* @return #EINA_TRUE on success, #EINA_FALSE oterwise.
*
- * This function rebuilds @p array be specifying the elements to keep
- * with the function @p keep. @p gdata is an additional data to pass
- * to @p keep. For performance reasons, there is no check of @p
- * array. If it is @c NULL or invalid, the program may crash.
+ * This function rebuilds @p array be specifying the elements to keep with the
+ * function @p keep. No empty/invalid fields are left in the array. @p gdata is
+ * an additional data to pass to @p keep. For performance reasons, there is no
+ * check of @p array. If it is @c NULL or invalid, the program may crash.
*
- * This function always return a valid array. If it wasn't able to
- * remove items due to an allocation failure, it will return #EINA_FALSE
- * and the error is set to #EINA_ERROR_OUT_OF_MEMORY.
+ * If it wasn't able to remove items due to an allocation failure, it will
+ * return #EINA_FALSE and the error is set to #EINA_ERROR_OUT_OF_MEMORY.
*/
EAPI Eina_Bool eina_array_remove(Eina_Array * array,
Eina_Bool (*keep)(void *data, void *gdata),
projects / framework / uifw / eina.git / commitdiff