WWW-www.enlightenment.org pushed a commit to branch master.
http://git.enlightenment.org/website/www-content.git/commit/?id=d38e4e07f9e41cecc7098cd98d60fa3e337f2889
commit d38e4e07f9e41cecc7098cd98d60fa3e337f2889
Author: Nate Drake <nate.dr...@gmx.com>
Date: Fri Dec 1 07:50:53 2017 -0800
Wiki page arrays.md changed with summary [] by Nate Drake
---
pages/develop/guides/c/eina/arrays.md.txt | 36 +++++++++++++++----------------
1 file changed, 18 insertions(+), 18 deletions(-)
diff --git a/pages/develop/guides/c/eina/arrays.md.txt
b/pages/develop/guides/c/eina/arrays.md.txt
index b419825bb..790b7a2bd 100644
--- a/pages/develop/guides/c/eina/arrays.md.txt
+++ b/pages/develop/guides/c/eina/arrays.md.txt
@@ -21,9 +21,9 @@ Eina provides 2 array types: the **classic array** and an
**inline array**.
## Create and Destroy a Classic Array ##
-The ``eina_array_new()`` function creates a new array. You can store strings
or objects in the created array. The function returns a new array, or if memory
allocation fails, ``NULL``.
+The ``eina_array_new()`` function creates a new array. You can store strings
or objects within it. The function returns either a new array or if memory
allocation fails ``NULL``.
-The first parameter of the ``eina_array_new()`` function defines the size of
the array allocation step. For example, if you set it to 4, the function
returns an array of 4 elements. The next time you expand the array it increases
by 4 elements. Unless you have pushed 4 elements inside, it does not increase
in size. Once you add the 5th element however, it expands again into an array
of 8 elements. The allocation step feature is very useful for optimizing
performance and also reduces memo [...]
+The first parameter of the ``eina_array_new()`` function defines the size of
the array allocation step. For example, if you set it to 4 the function returns
an array of 4 elements. The next time you expand the array it increases by 4
elements. Unless you have pushed 4 elements inside it does not increase in
size. Once you add the 5th element however it expands again into an array of 8
elements. The allocation step feature is very useful for optimizing performance
and also reduces memory [...]
### Create an Array to Store Strings ###
@@ -54,9 +54,9 @@ for (i = 0; i < 20; i++)
[...]
```
> **NOTE:**
-> ``[...]`` in a Code Block indicates there will usually be code above and
below the shown snippet, but that it has been excluded for the sake of brevity.
There is no need to type ``[...]`` into your program.
+> ``[...]`` in a Code Block indicates there will usually be code above and
below the shown snippet but that it has been excluded for the sake of brevity.
There is no need to type ``[...]`` into your program.
-To change the allocation step, use the ``eina_array_step_set()`` function, the
first parameter is the array you want to change, the second parameter is the
size of that specific array (retrieved with the ``sizeof()`` function) and the
last parameter is the new step size.
+To change the allocation step use the function ``eina_array_step_set()``. The
first parameter is the array you want to change, the second parameter is the
size of that specific array (retrieved with the ``sizeof()`` function). The
final parameter is the new step size.
In this example the array step changes from 20 to 30:
@@ -66,7 +66,7 @@ eina_array_step_set(array, sizeof(*array), 30);
[...]
```
-When you no longer require the array, use the ``eina_array_free()`` function
to free it. This will first call the ``eina_array_flush()`` function and free
the memory of the pointer. It does not free the memory allocated for the
elements of the array. To do this, use a ``while`` statement with the
``eina_array_pop`` function:
+When you no longer require the array, use the ``eina_array_free()`` function
to free it. This will first call the ``eina_array_flush()`` function and free
the memory of the pointer. It does not free the memory allocated for the
elements of the array. To do this use a ``while`` statement with the
``eina_array_pop`` function:
```c
@@ -84,7 +84,7 @@ eina_array_free(array);
### Set the Data of an Element ###
-Use the ``eina_array_data_set()`` function to set the data of an element. The
first parameter is the array. The second parameter is the index of the element
you want to set and the final parameter is the data itself. You must first get
the related pointer if you need to free it, as this function replaces the
previously held data. Be careful, as there is no array or index check. If the
value is ``NULL`` or invalid, the application may crash.
+Use the ``eina_array_data_set()`` function to set the data of an element. The
first parameter is the array. The second parameter is the index of the element
you want to set and the final parameter is the data itself. You must first get
the related pointer if you need to free it, as this function replaces the
previously held data. Be careful as there is no array or index check. If the
value is ``NULL`` or invalid the application may crash.
```c
[...]
@@ -95,7 +95,7 @@ eina_array_data_set(array, 0, strdup(strings[3]);
### Add Elements to the End of an Array ###
-Use the ``eina_array_push()`` function. The function returns ``EINA_TRUE`` on
success, and ``EINA_FALSE`` on failure. The first parameter is the array that
will store the element. The second is the data you want to store. If you store
strings, remember to allocate the memory first. The following example uses the
``strdup`` function to duplicate the value contained in ``strings[]``. This
function allocates the memory of the returned string, so you do not have to do
it yourself:
+Use the ``eina_array_push()`` function to add elements to the end of an array.
The function returns ``EINA_TRUE`` on success and ``EINA_FALSE`` on failure.
The first parameter is the array which will store the element. The second is
the data you want to store. If you store strings, remember to allocate the
necessary memory first. The following example uses the ``strdup`` function to
duplicate the value contained in ``strings[]``. This function allocates the
memory of the returned string [...]
```c
[...]
@@ -106,7 +106,7 @@ for (i = 0; i < 20; i++)
### Remove the Last Element of an Array ###
-Use the ``eina_array_pop()`` function, which takes the array as a parameter.
If the operation is successful, it returns a pointer to the data of the removed
element:
+Use the ``eina_array_pop()`` function to remove the last element. The function
takes the array as a parameter. If the operation is successful it returns a
pointer to the data of the removed element:
```c
[...]
@@ -117,9 +117,9 @@ while (eina_array_count(array))
### Rebuild an Array by Specifying the Data to be Kept ###
-Use the ``eina_array_remove()`` function. The first parameter is the array to
be changed. The second is the function which selects the data to keep in the
rebuilt array. The final parameter is the data to pass to the selector
function, defined as the second parameter.
+Use the ``eina_array_remove()`` function to rebuild an array. The first
parameter is the array to be changed. The second is the function which selects
the data to keep in the rebuilt array. The final parameter is the data to pass
to the selector function, defined as the second parameter.
-The selector function has to return an ``Eina_Bool``, ``EINA_TRUE`` if the
element is to remain and ``EINA_FALSE`` if it has to be removed.
+The selector function has to return an ``Eina_Bool`` ``EINA_TRUE`` if the
element is to remain and ``EINA_FALSE`` if it has to be removed.
The following example shows how to remove all strings that are longer than 5
characters from an array :
@@ -165,7 +165,7 @@ eina_array_flush(array);
### Empty an Array Quickly ###
-Use the ``eina_array_clean()`` function. This function sets the counting of
elements in the array to 0. It does not free any space so use it carefully. For
performance reasons, there is no array check. If the value is ``NULL`` or
invalid the program may crash.
+Use the ``eina_array_clean()`` function to empty an array. This function sets
the elements count in the array to 0. It does not free any space so use it
carefully. For performance reasons there is no array check. If the value is
``NULL`` or invalid the program may crash.
```c
@@ -190,7 +190,7 @@ mydata = eina_array_data_get(array, 0);
### Get the Number of Elements in an Array ###
-Use the ``eina_array_count()`` function. The first parameter is a pointer to
the array variable returned by the ``eina_array_new()`` function. The function
returns the number of elements.
+Use the ``eina_array_count()`` function. The first parameter is a pointer to
the array variable returned by the ``eina_array_new()`` function. The function
returns the number of elements:
```c
[...]
@@ -205,7 +205,7 @@ You can use various methods:
#### Use the ``ITER_NEXT`` iterator ####
-You can use the iterator by calling the macro ``EINA_ARRAY_ITER_NEXT()``. It
takes the array to iterate as the first parameter, a counter for the current
index during the iteration, and a variable of the same type as the item data
and an ``Eina_Iterator``. To use it, declare an ``Eina_Iterator``, an ``int``
counter, and, for example, a ``char *`` item if your array contains strings.
+You can use the iterator by calling the macro ``EINA_ARRAY_ITER_NEXT()``. It
takes the array to iterate as the first parameter, a counter for the current
index during the iteration and a variable of the same type as the item data and
an ``Eina_Iterator``. To use it declare an ``Eina_Iterator``, an ``int``
counter, and a ``char *`` item if your array contains strings:
```c
[...]
@@ -222,7 +222,7 @@ EINA_ARRAY_ITER_NEXT(array, i, item, iterator)
The first parameter is the array to iterate, the second is a callback function
which determines whether the iteration can continue. The final parameter is the
data passed to the callback function.
-To iterate over the array and to print the data of each array element, you can
do:
+To iterate over the array and to print the data of each array element use:
```c
[...]
@@ -253,9 +253,9 @@ int iterating_array()
```
#### Use the ``eina_array_iterator_new()`` Function ####
-This function returns a newly allocated iterator associated with the array. If
the array is ``NULL`` or the count of the array elements is less than or equal
to 0, the function returns ``NULL``. If the memory cannot be allocated,
``NULL`` is returned and ``EINA_ERROR_OUT_OF_MEMORY`` is thrown. Otherwise, a
valid iterator is returned. Pass the array for which you want to create a new
iterator to this function. The iterator is used to run a sequential walk
through the array, just like the [...]
+This function returns a newly allocated iterator associated with the array. If
the array is ``NULL`` or the count of the array elements is less than or equal
to 0, the function returns ``NULL``. If the memory cannot be allocated,
``NULL`` is returned and ``EINA_ERROR_OUT_OF_MEMORY`` occurs. Otherwise, a
valid iterator is returned. Pass the array for which you want to create a new
iterator to this function. The iterator is used to run a sequential walk
through the array just like the ``ei [...]
-To create an iterator and use it to print the data of each array element, try:
+To create an iterator and use it to print the data of each array element try:
```c
[...]
@@ -292,7 +292,7 @@ int new_iterator()
This function returns a newly allocated accessor associated with the array. If
the array is ``NULL`` or the counting of array elements is less than or equal
to 0, this function returns ``NULL``. If the memory cannot be allocated,
``NULL`` is returned and ``EINA_ERROR_OUT_OF_MEMORY`` appears. Otherwise, a
valid accessor is returned.
-To use the accessor to retrieve and print the data of every other array
element, try:
+To use the accessor to retrieve and print the data of every other array
element use:
```c
[...]
@@ -328,7 +328,7 @@ int random_access()
## Create and Destroy Inline Arrays ##
-An inline array is a container that stores the data itself, not the pointers
to the data. This means there is no memory fragmentation. For small data types
such as char, short, and int this is more memory-efficient as data is stored in
the cache and is faster to access. The bigger the data gets, however, the less
efficient this becomes.
+An inline array is a container that stores the data itself, not the pointers
to it. This means there is no memory fragmentation. For small data types such
as char, short, and int this is more memory-efficient as data is stored in the
cache and is faster to access. The bigger the data gets, however, the less
efficient this becomes.
To create an inline array, use the ``eina_inarray_new()`` function. The first
parameter of this function is the size of the value. In this example, only the
characters are stored, and because of that, only ``sizeof(char)`` is passed to
the function. The second parameter defines the size of the array allocation
step. For example, if you set it to 4, the function returns an inline array of
4 elements, and the next time you grow the inline array, it grows by 4 elements
and becomes an array [...]
--
