* @brief Asks the OS to populate or otherwise pages of memory in file mapping.
* @details This advises the operating system as to what to do with the memory mapped
* to the given @p file. This affects a specific range of memory and may not
- * be honoured if the system chooses to ignore the request.
+ * be honored if the system chooses to ignore the request.
*
* @param[in] file The file handle from which the map comes
* @param[in] rule The rule to apply to the mapped memory
* However, @ref eina_hash_string_small_new still uses the same hash calculation
* function that @ref eina_hash_string_superfast_new, which is more complex than
* @ref eina_hash_string_djb2_new. The latter has a faster hash computation
- * function, but that will imply on a not so good distribution. But if just a
+ * function, but that will imply a not so good distribution. But if just a
* few keys are being added, this is not a problem, it will still have not many
* collisions and be faster to calculate the hash than in a hash created with
* @ref eina_hash_string_small_new and @ref eina_hash_string_superfast_new.
int buckets_power_size) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(2, 3);
/**
- * @brief Redefines the callback that clean the data of a hash.
+ * @brief Redefines the callback that cleans the data of a hash.
*
* @param hash The given hash table
* @param data_free_cb The function called on each value when the hash
* @return The new hash table.
*
* This function creates a new hash table optimized for stringshared
- * values. Values CAN NOT be looked up with pointers not
+ * values. Values CANNOT be looked up with pointers not
* equal to the original key pointer that was used to add a value. On failure,
* this function returns @c NULL.
*
/**
* @brief Adds an entry to the given hash table without duplicating the string.
- * key.
*
* @param hash The given hash table. Cannot be @c NULL.
* @param key A unique key. Cannot be @c NULL.
* This function removes the entry identified by @p key or @p data
* from @p hash. If a free function was given to the
* callback on creation, it will be called for the data being
- * deleted. If @p hash is @c NULL, the functions returns immediately #EINA_FALSE.
+ * deleted. If @p hash is @c NULL, the function returns immediately #EINA_FALSE.
* If @p key is @c NULL, then @p data is used to find the a
* match to remove, otherwise @p key is used and @p data is not
* required and can be @c NULL. This function returns #EINA_FALSE if
* @param hash The hash table to be freed.
*
* This function frees up all the memory allocated to storing @p hash,
- * and call the free callback if it has been passed to the hash table
+ * and calls the free callback if it has been passed to the hash table
* at creation time. If no free callback has been passed, any entries
* in the table that the program has no more pointers for elsewhere
* may now be lost, so this should only be called if the program has
* @param hash The given hash table. Cannot be @c NULL.
* @param key The key. Cannot be @c NULL.
* @param key_length The length of the key.
- * @param key_hash The hash that always match the key.
+ * @param key_hash The hash that always matches the key.
* @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
*
* This function removes the entry identified by @p key and
* callback on creation, it will be called for the data being
* deleted. Do not forget to count '\\0' for string when setting the
* value of @p key_length. If @p hash or @p key are @c NULL, the
- * functions returns immediately #EINA_FALSE. This function
+ * function returns immediately #EINA_FALSE. This function
* returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
*
* @note If you don't have the key_hash, use eina_hash_del_by_key() instead.
*
* This function removes the entry identified by @p key from @p
* hash. The key length and hash will be calculated automatically by
- * using function provided to has creation function. If a free
+ * using function provided to hash creation function. If a free
* function was given to the callback on creation, it will be called
* for the data being deleted. If @p hash or @p key are @c NULL, the
- * functions returns immediately #EINA_FALSE. This function
+ * function returns immediately #EINA_FALSE. This function
* returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
*
* @note If you already have the key_hash, use eina_hash_del_by_key_hash()
* This function removes the entry identified by @p data from @p
* hash. If a free function was given to the callback on creation, it
* will be called for the data being deleted. If @p hash or @p data
- * are @c NULL, the functions returns immediately #EINA_FALSE. This
+ * are @c NULL, the function returns immediately #EINA_FALSE. This
* function returns #EINA_FALSE if an error occurred, #EINA_TRUE
* otherwise.
*
* This function removes the entry identified by @p key and
* @p key_hash, or @p data, from @p hash. If a free function was given to
* the callback on creation, it will be called for the data being
- * deleted. If @p hash is @c NULL, the functions returns immediately #EINA_FALSE.
+ * deleted. If @p hash is @c NULL, the function returns immediately #EINA_FALSE.
* If @p key is @c NULL, then @p key_length and @p key_hash
* are ignored and @p data is used to find a match to remove,
* otherwise @p key and @p key_hash are used and @p data is not
* valid iterator that will always return false on
* eina_iterator_next(), thus keeping API sane.
*
- * If the memory can not be allocated, @c NULL is returned.
+ * If the memory cannot be allocated, @c NULL is returned.
* Otherwise, a valid iterator is returned.
*
* @warning if the hash structure changes then the iterator becomes
* @dontinclude eina_inarray_01.c
*
* This example creates an inline array of chars, adds some elements, prints
- * them, re-purposes the array to store ints, adds some elements and print that.
+ * them, re-purposes the array to store ints, adds some elements and prints that.
*
* We are going to start with a function to compare ints. We need this because the '>'
* operator is not a function and can't be used where Eina_Compare_Cb is needed.
*
* Once we have an array we can start adding elements to it. Because the
* insertion function expects a memory address we have to put the value we want
- * to store in a variable(this should be no problem since in the real world usage
+ * to store in a variable (this should be no problem since in the real world usage
* that's usually where the value is anyways):
* @until push
* @note Because the inline array copies the value given to it we can later
* because we're storing a different type, but because our types have
* different sizes. Eina inline arrays don't actually know anything about types,
* they only deal with blocks of memory of a given size.
- * @note Since eina_inarray_step_set() receives already allocated memory, you can(and
+ * @note Since eina_inarray_step_set() receives already allocated memory, you can (and
* it is in fact a good practice) use inline arrays that are not declared as pointers:
* @code
* Eina_Inarray arr;
* We then create the array much like we did on @ref eina_inarray_example_01 :
* @until inarray_new
*
- * We then add element using eina_inarray_insert and print. Then remove that
- * element and add again using eina_inarray_insert_sorted and prints. This
- * shows the 2 different positions the element gets added. Then searches an
+ * We then add an element using eina_inarray_insert and print. Then remove that
+ * element and add it again using eina_inarray_insert_sorted and print. This
+ * shows the 2 different positions the element gets added. Then search for an
* element in the unsorted array using eina_inarray_search, then sorts the
* array and then searches the same element using eina_inarray_search_sorted.
* @until }
*
* @brief Inline array is a container that stores the data itself, not the pointers to the data.
*
- * This means there is no memory fragmentation, also for small data types(such
+ * This means there is no memory fragmentation, also for small data types (such
* as char, short, int, and so on) it's more memory efficient.
*
* Usage of the inline array is very similar to that of other
* @image rtf eina_inlist-node_eg2-my-struct.png
* @image latex eina_inlist-node_eg2-my-struct.eps
*
- * Now we need some pointers and auxiliar variables that will help us iterate on
+ * Now we need some pointers and auxiliary variables that will help us iterate on
* the lists:
*
* @skip struct
* @return A list pointer.
* @since 1.1.0
*
- * This function inserts item into a linked list assuming @p state match
- * the exact content order of the list. It use @p state to do a fast
+ * This function inserts item into a linked list assuming @p state matches
+ * the exact content order of the list. It uses @p state to do a fast
* first step dichotomic search before starting to walk the inlist itself.
- * This make this code much faster than eina_inlist_sorted_insert() as it
+ * This makes this code much faster than eina_inlist_sorted_insert() as it
* doesn't need to walk the list at all. The result is of course a sorted
- * list with an updated state.. If @p list is @c NULLL, item
+ * list with an updated state. If @p list is @c NULL, item
* is returned. On success, a new list pointer that should be
* used in place of the one given to this function is
* returned. Otherwise, the old pointer is returned.
* @note O(log2(n)) comparisons (calls to @p func) average/worst case
* performance. As said in eina_list_search_sorted_near_list(),
* lists do not have O(1) access time, so walking to the correct node
- * can be costly, but this version try to minimize that by making it a
- * O(log2(n)) for number small number. After n == 256, it start to add a
+ * can be costly, but this version tries to minimize that by making it a
+ * O(log2(n)) for number small number. After n == 256, it starts to add a
* linear cost again. Consider worst case to be almost O(n) pointer
* dereference (list walk).
*/
*/
EAPI Eina_Inlist *eina_inlist_sort(Eina_Inlist *head, Eina_Compare_Cb func);
-/* This two macros are helpers for the _FOREACH ones, don't use them */
+/* These two macros are helpers for the _FOREACH ones, don't use them */
/**
* @def _EINA_INLIST_OFFSET
* @param ref The reference to be used.
/**
* @def EINA_INLIST_REVERSE_FOREACH
- * @param list The list to traversed in reverse order.
+ * @param list The list to traverse in reverse order.
* @param it The pointer to the list item, i.e. a pointer to each item
* that is part of the list.
*/
/**
* @def EINA_INLIST_REVERSE_FOREACH_FROM
- * @param list The last list to traversed in reverse order.
+ * @param list The last list to traverse in reverse order.
* @param it The pointer to the list item, i.e. a pointer to each item
* that is part of the list.
* @see EINA_INLIST_REVERSE_FOREACH()
* @note Returning EINA_TRUE is important so we don't stop iterating over the
* container.
*
- * And here a more interesting function, it uses an iterator to print the
+ * And here's a more interesting function, it uses an iterator to print the
* contents of a container. What's interesting about it is that it doesn't care
* the type of container, it works for anything that can provide an iterator:
* @until }
*
* @brief These functions manage iterators on containers.
*
- * These functions allow to access elements of a container in a
+ * These functions allow accessing elements of a container in a
* generic way, without knowing which container is used (a bit like
- * iterators in the C++ STL). Iterators only allows sequential access
- * (that is, from an element to the next one). For random access, see
+ * iterators in the C++ STL). Iterators only allow sequential access
+ * (that is, from one element to the next one). For random access, see
* @ref Eina_Accessor_Group.
*
* Getting an iterator to access elements of a given container is done through
* the functions of that particular container. There is no function to create
* a generic iterator as iterators absolutely depend on the container. This
- * means you won't find iterator creation function here, those can be found on
+ * means you won't find an iterator creation function here, those can be found with
* the documentation of the container type you're using. Though created with
* container specific functions iterators are always deleted with the same
* function: eina_iterator_free().
* @param fdata The data passed to the callback.
*
* This function iterates over the elements pointed by @p iterator,
- * beginning from the current element. For Each element, the callback
+ * beginning with the current element. For each element, the callback
* @p cb is called with the data @p fdata. If @p iterator is @c NULL,
* the function returns immediately. Also, if @p cb returns #EINA_FALSE,
* the iteration stops at that point, if @p cb returns #EINA_TRUE
EAPI Eina_Iterator* eina_carray_iterator_new(void** array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Creates a new iterator which which iterates throuw all elements with are accepted by the filter callback
+ * @brief Creates a new iterator which which iterates through all elements with are accepted by the filter callback
*
* @param original the iterator the use as original set
* @param filter if the callback returns true the element from the original set is taken into the the new set.
* @param free_cb when the iterator is gone this callback will be called with data as argument
* @param data the data which is passed to the filter callback
*
- * The iterator is filtered while it is beeing iterated.
+ * The iterator is filtered while it is being iterated.
* The original iterator you pass in here is is then owned and will be freed once the the new iterator is freed.
*
* @since 1.19
* @skip #include
* @until Eina.h
*
- * Just some boilerplate code, declaring some variable and initializing eina.
+ * Just some boilerplate code, declaring some variables and initializing eina.
* @until eina_init
* Here we add a sequence of elements to our list. By using append we add
* elements to the end of the list, so the list will look like this:@n
* accomplished using @ref eina_list_append_relative() and
* @ref eina_list_append_relative_list():
* @until zarek
- * First @a "cain" is added after the second element(remember that indexes are
+ * First @a "cain" is added after the second element (remember that indexes are
* 0 based) and then we add @a "zarek" after @a "cain".
*
* @ref Eina_List also has prepend analogs to append functions we have used so
* @until sagitarius
*
* To replace an element in the list it is not necessary to remove it and then
- * add with the new value, it is possible to just change the value of a node:
+ * re-add with the new value, it is possible to just change the value of a node:
* @until aquarius
*
* We will now take a peek to see if the list still has the right number of
* @p relative is not in the list, @p data is appended to the end of
* the list. If @p list is @c NULL, a new list is returned. If there
* are multiple instances of @p relative in the list, @p data is
- * inserted after the first instance.On success, a new list pointer
+ * inserted after the first instance. On success, a new list pointer
* that should be used in place of the one given to this function is
* returned. Otherwise, the old pointer is returned.
*
/**
- * @brief Returns node nearest to data is in the sorted list.
+ * @brief Returns node nearest to data from the sorted list.
*
* @param list The list to search for data, @b must be sorted.
* @param func A function pointer that can handle comparing the list data nodes.
*
* If @a cmp_result is 0 the element is already in the list and we need not
* insert it, if @a cmp_result is greater than zero @a "my @a data" needs to
- * come after @a l(the nearest node present), if less than zero before.
+ * come after @a l (the nearest node present), if less than zero before.
*
* @note O(log2(n)) average/worst case performance, for 1,000,000
* elements it will do a maximum of 20 comparisons. This is much
* @param data The data member to the list node.
* @return The previous data value.
*
- * This function set the data member @p data of the specified list node
+ * This function sets the data member @p data of the specified list node
* @p list. It returns the previous data of the node. If @p list is
* @c NULL, this function returns @c NULL.
*
* This function returns a newly allocated accessor associated to
* @p list. If @p list is @c NULL or the count member of @p list is
* less or equal than 0, this function returns @c NULL. If the memory can
- * not be allocated, @c NULL is returned Otherwise, a valid accessor is
+ * not be allocated, @c NULL is returned; otherwise, a valid accessor is
* returned.
*
* @warning @p list must be a pointer to the first element of the list.
EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Finds the member of the list and return the index.
+ * @brief Finds the member of the list and returns the index.
*
* @param list The list.
* @param data The data member.
* deleting the current node and continuing looping is safe.
*
* The following diagram illustrates this macro iterating over a list of four
- * elements("one", "two", "three" and "four"):
+ * elements ("one", "two", "three" and "four"):
* @htmlonly
* <img src="eina-list-foreach-safe.png" style="max-width: 100%;" />
* <a href="eina-list-foreach-safe.png">Full-size</a>
* deleting the current node and continuing looping is safe.
*
* The following diagram illustrates this macro iterating over a list of four
- * elements("one", "two", "three" and "four"):
+ * elements ("one", "two", "three" and "four"):
* @htmlonly
* <img src="eina-list-reverse-foreach-safe.png" style="max-width: 100%;" />
* <a href="eina-list-reverse-foreach-safe.png">Full-size</a>
* the data contained in the current node in @p data.
*
* The following diagram illustrates this macro iterating over a list of four
- * elements("one", "two", "three" and "four"):
+ * elements ("one", "two", "three" and "four"):
* @htmlonly
* <img src="eina-list-free.png" style="max-width: 100%;" />
* <a href="eina-list-free.png">Full-size</a>
* @ingroup Eina_Tools_Group
* @brief This group provides thread locking and synchronization capabilities.
*
- * Similar to POISIX threads (pthreads), but it takes care of the platform specific
+ * Similar to POSIX threads (pthreads), but it takes care of the platform specific
* details so you don't have to.
*
* If you know how @c pthreads work, this library will look familiar to you.
*
* @return Returns #EINA_LOCK_SUCCEED on success, #EINA_LOCK_FAIL on failure.
*
- * @note This function never return #EINA_LOCK_DEADLOCK.
+ * @note This function never returns #EINA_LOCK_DEADLOCK.
*
* @see eina_rwlock_release()
*/
*
* @return Returns #EINA_LOCK_SUCCEED on success, #EINA_LOCK_FAIL on failure.
*
- * @note This function never return #EINA_LOCK_DEADLOCK.
+ * @note This function never returns #EINA_LOCK_DEADLOCK.
*
* @see eina_rwlock_release()
*/
projects / platform / upstream / efl.git / commitdiff