int
main(int argc, char **argv)
{
+ const char* strs[] = {
+ "one", "two", "three", "four", "five", "six", "seven", "eight", "nine",
+ "ten", "eleven", "twelve", "thirteen", "fourtenn", "fifteen", "sixteen",
+ "seventeen", "eighteen", "nineteen", "twenty"
+ };
const char* strings[] = {
"helo", "hera", "starbuck", "kat", "boomer",
"hotdog", "longshot", "jammer", "crashdown", "hardball",
eina_init();
- array = eina_array_new(20);
+ array = eina_array_new(10);
+
+ for (i = 0; i < 20; i++)
+ eina_array_push(array, strs[i]);
+ eina_array_clean(array);
for (i = 0; i < 20; i++)
eina_array_push(array, strings[i]);
+ eina_array_data_set(array, 17, "flattop");
+
eina_array_remove(array, keep, NULL);
EINA_ARRAY_ITER_NEXT(array, i, item, iterator)
printf("item #%d: %s\n", i, item);
* @skip #include
* @until Eina.h
*
+ * Here we have a callback that prints the element given to it:
+ * @until }
+ *
* 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:
+ * So now to actually creating our array. The only interesting thing here is the
+ * argument given to the eina_array_new() function, this argument sets how fast
+ * the array grows.
* @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.
+ * step to that. In our case we can set it to the number of string we have and
+ * since we didn't do that in the eina_array_new() we can do it now:
+ * @until array_step_set
*
* Now let us populate our array with some strings:
* @until push
* 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
+ * And now we call a function on every member of our array to print it:
+ * @until foreach
*
* 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:
* difference of not using strdup:
* @until array_push
*
+ * So we have added all our elements to the array, but it turns out that is not
+ * the elements we wanted, so let's empty the array and add the correct strings:
+ * @until array_push
+ *
+ * It seems we made a little mistake in one of our strings so we need to replace
+ * it, here is how:
+ * @until data_set
+ *
* Now that there is a populated array we can remove elements from it easily:
* @until array_remove
*
* eina_array_data_get(). The number of elements can be retrieved with
* eina_array_count_get().
*
+ * Eina_Array is different from a conventional C array in a number of ways, most
+ * importantly they grow and shrink dynamically, this means that if you add an
+ * element to a full array it grows and that when you remove an element from an
+ * array it @b may shrink.
+ *
+ * When the array needs to grow it allocates memory not just for the element
+ * currently being added since that would mean allocating memory(which is
+ * computationally expensive) often, instead it grows to be able to hold @p step
+ * more elements. Similarly if you remove elements in such a way that that the
+ * array is left holding its capacity - @p step elements it will shrink.
+ *
+ * Eina_Array only stores pointers but it can store data of any type in the form
+ * of void pointers.
+ *
* See here some examples:
* @li @ref array_01_example_page
* @li @ref array_02_example_page
*
* This function creates a new array. When adding an element, the array
* allocates @p step elements. When that buffer is full, then adding
- * another element will increase the buffer of @p step elements again.
+ * another element will increase the buffer by @p step elements again.
*
* This function return a valid array on success, or @c NULL if memory
* allocation fails. In that case, the error is set to
*
* This function sets the step of @p array to @p step. For performance
* reasons, there is no check of @p array. If it is @c NULL or
- * invalid, the program may crash. This function should be called when
- * the array is not initialized.
+ * invalid, the program may crash.
+ *
+ * @warning This function can @b only be called on uninitialized arrays.
*/
EAPI void eina_array_step_set(Eina_Array *array,
unsigned int sizeof_eina_array,
unsigned int step) EINA_ARG_NONNULL(1);
+/**
+ * @brief Clean an array.
+ *
+ * @param array The array to clean.
+ *
+ * This function sets the count member of @p array to 0, however it doesn't free
+ * any space. This is particularly usefull if you need to empty the array and
+ * add lots of elements quickly. For performance reasons, there is no check of
+ * @p array. If it is @c NULL or invalid, the program may crash.
+ */
static inline void eina_array_clean(Eina_Array *array) EINA_ARG_NONNULL(1);
/**
static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1);
static inline void *eina_array_data_get(const Eina_Array *array,
unsigned int idx) EINA_ARG_NONNULL(1);
+/**
+ * @brief Set the data at a given position in an array.
+ *
+ * @param array The array.
+ * @param idx The potition of the data to set.
+ * @param data The data to set.
+ *
+ * This function sets the data at the position @p idx in @p
+ * array to @p data, this effectively replaces the previously held data, you
+ * must therefore get a pointer to it first if you need to free it. For
+ * performance reasons, there is no check of @p array or @p idx. If it is @c
+ * NULL or invalid, the program may crash.
+*/
static inline void eina_array_data_set(const Eina_Array *array,
unsigned int idx,
const void *data) EINA_ARG_NONNULL(1);
* set. Otherwise, a valid accessor is returned.
*/
EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
+/**
+ * @brief Provide a safe way to iterate over an array
+ *
+ * @param array The array to iterate over.
+ * @param cb The callback to call for each item.
+ * @param fdata The user data to pass to the callback.
+ * @return EINA_TRUE if it successfully iterate all items of the array.
+ *
+ * This function provide a safe way to iterate over an array. @p cb should
+ * return EINA_TRUE as long as you want the function to continue iterating,
+ * by returning EINA_FALSE it will stop and return EINA_FALSE as a result.
+ */
static inline Eina_Bool eina_array_foreach(Eina_Array *array,
Eina_Each_Cb cb,
void *data);
return array->data[idx];
}
-/**
- * @brief Set the data at a given position in an array.
- *
- * @param array The array.
- * @param idx The potition of the data to set.
- * @param data The data to set.
- *
- * This function sets the data at the position @p idx in @p
- * array. For performance reasons, there is no check of @p array or @p
- * idx. If it is @c NULL or invalid, the program may crash.
- */
static inline void
eina_array_data_set(const Eina_Array *array, unsigned int idx, const void *data)
{
return array->count;
}
-/**
- * @brief Provide a safe way to iterate over an array
- *
- * @param array The array to iterate over.
- * @param cb The callback to call for each item.
- * @param fdata The user data to pass to the callback.
- * @return EINA_TRUE if it successfully iterate all items of the array.
- *
- * This function provide a safe way to iterate over an array. @p cb should
- * return EINA_TRUE as long as you want the function to continue iterating,
- * by returning EINA_FALSE it will stop and return EINA_FALSE as a result.
- */
static inline Eina_Bool
eina_array_foreach(Eina_Array *array, Eina_Each_Cb cb, void *fdata)
{
return ret;
}
-/**
- * @brief Clean an array.
- *
- * @param array The array to clean.
- *
- * This function sets the count member of @p array to 0. For
- * performance reasons, there is no check of @p array. If it is
- * @c NULL or invalid, the program may crash.
- */
static inline void
eina_array_clean(Eina_Array *array)
{
projects / platform / upstream / efl.git / commitdiff