/**
* @addtogroup Eina_Rbtree_Group Red-Black tree
*
- * @brief These functions provide Red-Black trees management.
+ * @brief These functions provide Red-Black tree management.
*
* For a brief description look at http://en.wikipedia.org/wiki/Red-black_tree .
* This code is largely inspired from a tutorial written by Julienne Walker at :
* http://eternallyconfuzzled.com/tuts/datastructures/jsw_tut_rbtree.aspx . The
- * main difference is that this set of function never allocate any data, making
+ * main difference is that this set of functions never allocate any data, making
* them particularly useful for memory management.
*/
/**
* @def EINA_RBTREE_CONTAINER_GET
- * find back the container of an red black tree.
+ * find back the container of a red black tree.
*/
#define EINA_RBTREE_CONTAINER_GET(Ptr, Type) ((Type *)((char *)Ptr - offsetof(Type, __rbtree)))
/**
* @typedef Eina_Rbtree_Cmp_Node_Cb
- * Function used compare two nodes and see which direction to navigate.
+ * Function used to compare two nodes and see which direction to navigate.
*/
typedef Eina_Rbtree_Direction (*Eina_Rbtree_Cmp_Node_Cb)(const Eina_Rbtree *left, const Eina_Rbtree *right, void *data);
* Function used compare node with a given key of specified length.
*/
typedef int (*Eina_Rbtree_Cmp_Key_Cb)(const Eina_Rbtree *node, const void *key, int length, void *data);
+
/**
* @def EINA_RBTREE_CMP_KEY_CB
* Cast using #Eina_Rbtree_Cmp_Key_Cb
/**
* @typedef Eina_Rbtree_Free_Cb
- * Function used free a node.
+ * Function used to free a node.
*/
typedef void (*Eina_Rbtree_Free_Cb)(Eina_Rbtree *node, void *data);
+
/**
* @def EINA_RBTREE_FREE_CB
* Cast using #Eina_Rbtree_Free_Cb
*/
#define EINA_RBTREE_FREE_CB(Function) ((Eina_Rbtree_Free_Cb)Function)
-
/**
* @brief Inserts a new node inside an existing red black tree.
*
* @param data Private data to help the compare function.
* @return The new root of the red black tree.
*
- * This function insert a new node in a valid red black tree. @c NULL is
+ * This function inserts a new node in a valid red black tree. @c NULL is
* an empty valid red black tree. The resulting new tree is a valid red
* black tree. This function doesn't allocate any data.
*/
* @param data Private data to help the compare function.
* @return The new root of the red black tree.
*
- * This function remove a new node in a valid red black tree that should
+ * This function removes a new node in a valid red black tree that should
* contain the node that you are removing. This function will return @c NULL
* when the red black tree got empty. This function doesn't free any data.
*/
/**
- * @brief Returns a new prefix iterator associated to a rbtree.
+ * @brief Returns a new prefix iterator associated with a rbtree.
*
* @param root The root of rbtree.
* @return A new iterator.
*
- * This function returns a newly allocated iterator associated to @p
+ * This function returns a newly allocated iterator associated with @p
* root. It will iterate the tree using prefix walk. If @p root is @c
* NULL, this function still returns a 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 rbtree structure changes then the iterator becomes
EAPI Eina_Iterator *eina_rbtree_iterator_prefix(const Eina_Rbtree *root) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Returns a new prefix iterator associated to a rbtree.
+ * @brief Returns a new prefix iterator associated with a rbtree.
*
* @param root The root of rbtree.
* @return A new iterator.
*
- * This function returns a newly allocated iterator associated to @p
+ * This function returns a newly allocated iterator associated with @p
* root. It will iterate the tree using infix walk. If @p root is @c
* NULL, this function still returns a 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 rbtree structure changes then the iterator becomes
EAPI Eina_Iterator *eina_rbtree_iterator_infix(const Eina_Rbtree *root) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Returns a new prefix iterator associated to a rbtree.
+ * @brief Returns a new prefix iterator associated with a rbtree.
*
* @param root The root of rbtree.
* @return A new iterator.
*
- * This function returns a newly allocated iterator associated to @p
+ * This function returns a newly allocated iterator associated with @p
* root. It will iterate the tree using postfix walk. If @p root is @c
* NULL, this function still returns a 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 rbtree structure changes then the iterator becomes
/**
* @typedef Eina_Rectangle_Outside
- * Enumeration gives the positions where a rectangle can be outside a other rectangle
+ * Enumeration gives the positions where a rectangle can be outside another rectangle
* @since 1.19
*/
typedef enum {
* @param l2 The length of the second span.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
- * This function returns #EINA_TRUE if the given spans intersect, #EINA_FALSE
+ * This function returns #EINA_TRUE if the given spans intersect, #EINA_FALSE
* otherwise.
*/
static inline int eina_spans_intersect(int c1, int l1, int c2, int l2) EINA_WARN_UNUSED_RESULT;
static inline Eina_Bool eina_rectangles_intersect(const Eina_Rectangle *r1, const Eina_Rectangle *r2) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Checks if the given x-coordinate is in the rectangle .
+ * @brief Checks if the given x-coordinate is in the rectangle.
*
* @param r The rectangle.
* @param x The x coordinate.
static inline Eina_Bool eina_rectangle_xcoord_inside(const Eina_Rectangle *r, int x) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Checks if the given y-coordinate is in the rectangle .
+ * @brief Checks if the given y-coordinate is in the rectangle.
*
* @param r The rectangle.
* @param y The y coordinate.
static inline Eina_Bool eina_rectangle_ycoord_inside(const Eina_Rectangle *r, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Checks if the given point is in the rectangle .
+ * @brief Checks if the given point is in the rectangle.
*
* @param r The rectangle.
* @param x The x coordinate of the point.
* @param dst The first rectangle.
* @param src The second rectangle.
*
- * This function get the union of the rectangles @p dst and @p src. The
+ * This function gets the union of the rectangles @p dst and @p src. The
* result is stored in @p dst. No check is done on @p dst or @p src,
* so they must be valid rectangles.
*/
* @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE
* otherwise.
*
- * This function get the intersection of the rectangles @p dst and
+ * This function gets the intersection of the rectangles @p dst and
* @p src. The result is stored in @p dst. No check is done on @p dst
* or @p src, so they must be valid rectangles.
*/
static inline void eina_rectangle_rescale_out(const Eina_Rectangle *out, const Eina_Rectangle *in, Eina_Rectangle *res) EINA_ARG_NONNULL(1, 2, 3);
/**
- *
* @brief Tells whether a rectangle is valid or not.
*
* @param r The rectangle
static inline Eina_Bool eina_rectangle_is_valid(const Eina_Rectangle *r) EINA_ARG_NONNULL(1);
/**
- *
* @brief Gives the rectangle maximum x coordinate.
*
* @param thiz The rectangle
static inline int eina_rectangle_max_x(Eina_Rectangle *thiz) EINA_ARG_NONNULL(1);
/**
- *
* @brief Gives the rectangle maximum y coordinate.
*
* @param thiz The rectangle
static inline int eina_rectangle_max_y(Eina_Rectangle *thiz) EINA_ARG_NONNULL(1);
/**
- *
* @brief Slices a rectangle vertically into two subrectangles starting from left edge.
*
* @param thiz The rectangle to slice
* Use this function if we must cut a rectangle vertically. The @p amount
* parameter defines the x inner coordinate where to do the cut, starting from
* the left edge of the rectangle. If the @p amount value is greater than the
- * rectangle width, there will be not cut possible and #EINA_FALSE will be
+ * rectangle width, there will be no cut possible and #EINA_FALSE will be
* returned.
*/
static inline Eina_Bool eina_rectangle_x_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1);
/**
- *
* @brief Slices a rectangle horizontally into two subrectangles starting from bottom edge
*
* @param thiz The rectangle to slice
* Use this function if we must cut a rectangle horizontally. The @p amount
* parameter defines the y inner coordinate where to do the cut, starting from
* the bottom edge of the rectangle. If the @p amount value is greater than the
- * rectangle width, there will be not cut possible and #EINA_FALSE will be
+ * rectangle width, there will be no cut possible and #EINA_FALSE will be
* returned.
*/
static inline Eina_Bool eina_rectangle_y_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1);
/**
- *
* @brief Slices a rectangle vertically starting from right edge
*
* @param thiz The rectangle to slice
* Use this function if we must cut a rectangle vertically. The @p amount
* parameter defines the inner x coordinate where to do the cut, starting from
* the right edge of the rectangle. If the @p amount value is greater than the
- * rectangle width, there will be not cut possible and #EINA_FALSE will be
+ * rectangle width, there will be no cut possible and #EINA_FALSE will be
* returned.
*/
static inline Eina_Bool eina_rectangle_width_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1);
/**
- *
* @brief Slices a rectangle horizontally starting from top edge
*
* @param thiz The rectangle to slice
* Use this function if we must cut a rectangle horizontally. The @p amount
* parameter defines the inner y coordinate where to do the cut, starting from
* the top edge of the rectangle. If the @p amount value is greater than the
- * rectangle width, there will be not cut possible and #EINA_FALSE will be
+ * rectangle width, there will be no cut possible and #EINA_FALSE will be
* returned.
*/
static inline Eina_Bool eina_rectangle_height_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1);
* @param h The height of the rectangle to request.
* @return The requested rectangle on success, @c NULL otherwise.
*
- * This function retrieve from @p pool the rectangle of width @p w and
+ * This function retrieves from @p pool the rectangle of width @p w and
* height @p h. If @p pool is @c NULL, or @p w or @p h are non-positive,
* the function returns @c NULL. If @p w or @p h are greater than the
* pool size, the function returns @c NULL. On success, the function
* @param h The height of the rectangle.
* @return The new rectangle on success, @ NULL otherwise.
*
- * This function creates a rectangle which top left corner has the
+ * This function creates a rectangle whose top left corner has the
* coordinates (@p x, @p y), with height @p w and height @p h and adds
* it to the rectangles pool. No check is done on @p w and @p h. This
* function returns a new rectangle on success, @c NULL otherwise.
* @param rect1 The rect to use as anchor
* @param rect2 The rect to look for outside positions
*
- * @return A or'ed map of Eina_Rectangle_Outside values
+ * @return An OR'd map of Eina_Rectangle_Outside values
* @since 1.19
*/
EAPI Eina_Rectangle_Outside eina_rectangle_outside_position(Eina_Rectangle *rect1, Eina_Rectangle *rect2);