[prev in list] [next in list] [prev in thread] [next in thread] 

List:       enlightenment-svn
Subject:    E SVN: caro IN trunk/eina/src: include lib
From:       "Enlightenment SVN" <no-reply () enlightenment ! org>
Date:       2009-01-29 23:16:24
Message-ID: 20090129231624.103D91183FC () e2 ! enlightenment ! org
[Download RAW message or body]

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
  */
 


------------------------------------------------------------------------------
This SF.net email is sponsored by:
SourcForge Community
SourceForge wants to tell your story.
http://p.sf.net/sfu/sf-spreadtheword
_______________________________________________
enlightenment-svn mailing list
enlightenment-svn@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-svn


[prev in list] [next in list] [prev in thread] [next in thread]