Wiki page arrays.md changed with summary [] by Nate Drake

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 memory fragmentation by matching the size to array usage. If you set the step to 0 the function sets a default safe value.
+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 fragmentation by matching the size to array usage. If you set the step to 0 the function sets a default safe value.
 
 ### 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 so you do not have to do it yourself:
 
 ```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 ``eina_array_foreach()`` 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`` 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 ``eina_array_foreach()`` function.
 
-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 of 8 elements. If you set the step to 0, the function sets a default safe value. The step can be changed later on using the ``eina_inarray_step_set()`` function.