From: Enlightenment S. <no-...@en...> - 2009-01-29 23:16:26
|
Log: * more doc in the tutorial of the array data type * minor formatting Author: caro Date: 2009-01-29 15:16:23 -0800 (Thu, 29 Jan 2009) New Revision: 38853 Modified: trunk/eina/src/include/eina_array.h trunk/eina/src/include/eina_inline_array.x trunk/eina/src/lib/eina_array.c Modified: trunk/eina/src/include/eina_array.h =================================================================== --- trunk/eina/src/include/eina_array.h 2009-01-29 23:01:43 UTC (rev 38852) +++ trunk/eina/src/include/eina_array.h 2009-01-29 23:16:23 UTC (rev 38853) @@ -111,10 +111,10 @@ * the following example: * * @code - * Eina_Array *array; - * char *item; - * Eina_Array_Iterator iterator; - * unsigned int i; + * Eina_Array *array; + * char *item; + * Eina_Array_Iterator iterator; + * unsigned int i; * * // array is already filled, * // its elements are just duplicated strings, Modified: trunk/eina/src/include/eina_inline_array.x =================================================================== --- trunk/eina/src/include/eina_inline_array.x 2009-01-29 23:01:43 UTC (rev 38852) +++ trunk/eina/src/include/eina_inline_array.x 2009-01-29 23:16:23 UTC (rev 38853) @@ -52,9 +52,10 @@ * * This function appends @p data to @p array. For performance * reasons, there is no check of @p array. If it is @c NULL or - * invalid, the program may crash. if an allocation is necessary and - * fails, #EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY is - * set. Otherwise, #EINA_TRUE is returned. + * invalid, the program may crash. If @p data is @c NULL, or if an + * allocation is necessary and fails, #EINA_FALSE is returned and + * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, #EINA_TRUE is + * returned. */ static inline Eina_Bool eina_array_push(Eina_Array *array, const void *data) @@ -74,10 +75,11 @@ * @param array The array. * @return The retrieved data. * - * This function removes the last data of @p array and returns it. For - * performance reasons, there is no check of @p array. If it is - * @c NULL or invalid, the program may crash. If the count member is - * less or equal than 0, @c NULL is returned. + * This function removes the last data of @p array, decreases the count + * of @p array and returns the data. For performance reasons, there + * is no check of @p array. If it is @c NULL or invalid, the program + * may crash. If the count member is less or equal than 0, @c NULL is + * returned. */ static inline void * eina_array_pop(Eina_Array *array) Modified: trunk/eina/src/lib/eina_array.c =================================================================== --- trunk/eina/src/lib/eina_array.c 2009-01-29 23:01:43 UTC (rev 38852) +++ trunk/eina/src/lib/eina_array.c 2009-01-29 23:16:23 UTC (rev 38853) @@ -60,11 +60,84 @@ * following command: * * @code - * gcc -Wall -o my_exe my_source.c `pkg-config --cflags --libs eina` + * gcc -o my_bin my_source.c `pkg-config --cflags --libs eina-0` * @endcode * - * Then, an array must created with eina_array_new(). + * Then, 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: + * + * @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_array_init()) + * { + * printf ("Error during the initialization of eina_error module\n"); + * return EXIT_FAILURE; + * } + * + * array = eina_array_new(16); + * if (!array) + * goto shutdown_array; + * + * 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_array_shutdown(); + * + * return EXIT_SUCCESS; + * + * shutdown_array: + * eina_array_shutdown(); + * + * return EXIT_FAILURE; + * } + * @endcode + * * To be continued */ |