aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/eina/eina_rbtree.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/eina/eina_rbtree.h')
-rw-r--r--src/lib/eina/eina_rbtree.h203
1 files changed, 103 insertions, 100 deletions
diff --git a/src/lib/eina/eina_rbtree.h b/src/lib/eina/eina_rbtree.h
index 6a4d764299..e37d1f06b5 100644
--- a/src/lib/eina/eina_rbtree.h
+++ b/src/lib/eina/eina_rbtree.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2008 Cedric Bail
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -26,38 +26,23 @@
#include "eina_iterator.h"
/**
- * @addtogroup Eina_Rbtree_Group Red-Black tree
+ * @defgroup Eina_Rbtree_Group Red-Black tree
+ * @ingroup Eina_Containers_Group
*
- * @brief These functions provide Red-Black trees management.
+ * @brief This group discusses the functions that provide Red-Black trees 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.
- */
-
-/**
- * @addtogroup Eina_Data_Types_Group Data Types
- *
- * @{
- */
-
-/**
- * @addtogroup Eina_Containers_Group Containers
- *
- * @{
- */
-
-/**
- * @defgroup Eina_Rbtree_Group Red-Black tree
*
* @{
*/
/**
* @typedef Eina_Rbtree_Color
- * node color.
+ * @brief Enumeration of the node color.
*/
typedef enum {
EINA_RBTREE_RED,
@@ -66,7 +51,7 @@ typedef enum {
/**
* @typedef Eina_Rbtree_Direction
- * walk direction.
+ * @brief Enumeration of the walk direction.
*/
typedef enum {
EINA_RBTREE_LEFT = 0,
@@ -75,19 +60,19 @@ typedef enum {
/**
* @typedef Eina_Rbtree
- * Type for a Red-Black tree node. It should be inlined into user's type.
+ * @brief The structure type for a Red-Black tree node. It should be inlined into the user type.
*/
typedef struct _Eina_Rbtree Eina_Rbtree;
struct _Eina_Rbtree
{
Eina_Rbtree *son[2];
- unsigned int color : 1;
+ Eina_Rbtree_Color color : 1;
};
/**
* @def EINA_RBTREE
- * recommended way to declare the inlined Eina_Rbtree in your type.
+ * @brief Definition of the recommended way to declare the inlined Eina_Rbtree for your type.
*
* @code
* struct my_type {
@@ -103,87 +88,101 @@ struct _Eina_Rbtree
/**
* @def EINA_RBTREE_GET
- * access the inlined node if it was created with #EINA_RBTREE.
+ *
+ * @since_tizen 2.3
+ *
+ * @brief Definition to access the inlined node if it is created with #EINA_RBTREE.
*/
#define EINA_RBTREE_GET(Rbtree) (&((Rbtree)->__rbtree))
/**
* @def EINA_RBTREE_CONTAINER_GET
- * find back the container of an red black tree.
+ *
+ * @since_tizen 2.3
+ *
+ * @brief Definition to 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.
+ * @brief Compares two nodes and decides which direction to navigate.
*/
typedef Eina_Rbtree_Direction (*Eina_Rbtree_Cmp_Node_Cb)(const Eina_Rbtree *left, const Eina_Rbtree *right, void *data);
/**
* @def EINA_RBTREE_CMP_NODE_CB
- * Cast using #Eina_Rbtree_Cmp_Node_Cb
+ * @brief Definition of the cast using #Eina_Rbtree_Cmp_Node_Cb.
*/
#define EINA_RBTREE_CMP_NODE_CB(Function) ((Eina_Rbtree_Cmp_Node_Cb)Function)
/**
* @typedef Eina_Rbtree_Cmp_Key_Cb
- * Function used compare node with a given key of specified length.
+ * @brief Compares a node with the given key of the 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
+ * @brief Definition of the cast using #Eina_Rbtree_Cmp_Key_Cb.
*/
#define EINA_RBTREE_CMP_KEY_CB(Function) ((Eina_Rbtree_Cmp_Key_Cb)Function)
/**
* @typedef Eina_Rbtree_Free_Cb
- * Function used free a node.
+ * @brief Called 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
+ * @brief Definition of the cast using #Eina_Rbtree_Free_Cb.
*/
#define EINA_RBTREE_FREE_CB(Function) ((Eina_Rbtree_Free_Cb)Function)
/**
- * @brief Insert a new node inside an existing red black tree.
+ * @brief Inserts a new node inside an existing red black tree.
*
- * @param root The root of an exisiting valid red black tree.
- * @param node The new node to insert.
- * @param cmp The callback that is able to compare two nodes.
- * @param data Private data to help the compare function.
- * @return The new root of the red black tree.
+ * @details This function inserts a new node into 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.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] root The root of an existing valid red black tree
+ * @param[in] node The new node to insert
+ * @param[in] cmp The callback that is able to compare two nodes
+ * @param[in] data The 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
- * an empty valid red black tree. The resulting new tree is a valid red
- * black tree. This function doesn't allocate any data.
*/
EAPI Eina_Rbtree *eina_rbtree_inline_insert(Eina_Rbtree *root, Eina_Rbtree *node, Eina_Rbtree_Cmp_Node_Cb cmp, const void *data) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Remove a node from an existing red black tree.
+ * @brief Removes a node from an existing red black tree.
+ *
+ * @details This function removes a new node from a valid red black tree that should
+ * contain the node that you are removing. This function returns @c NULL
+ * when the red black tree becomes empty. This function doesn't free any data.
*
- * @param root The root of a valid red black tree.
- * @param node The node to remove from the tree.
- * @param cmp The callback that is able to compare two nodes.
- * @param data Private data to help the compare function.
- * @return The new root of the red black tree.
+ * @since_tizen 2.3
+ *
+ * @param[in] root The root of a valid red black tree
+ * @param[in] node The node to remove from the tree
+ * @param[in] cmp The callback that is able to compare two nodes
+ * @param[in] data The 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
- * 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.
*/
EAPI Eina_Rbtree *eina_rbtree_inline_remove(Eina_Rbtree *root, Eina_Rbtree *node, Eina_Rbtree_Cmp_Node_Cb cmp, const void *data) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Delete all nodes from a valid red black tree.
+ * @brief Deletes all the nodes from a valid red black tree.
+ *
+ * @since_tizen 2.3
*
- * @param root The root of a valid red black tree.
- * @param func The callback that will free each node.
- * @param data Private data to help the compare function.
+ * @param[in] root The root of a valid red black tree
+ * @param[in] func The callback that frees each node
+ * @param[in] data The private data to help the compare function
*
*/
EAPI void eina_rbtree_delete(Eina_Rbtree *root, Eina_Rbtree_Free_Cb func, void *data) EINA_ARG_NONNULL(2);
@@ -192,62 +191,74 @@ static inline Eina_Rbtree *eina_rbtree_inline_lookup(const Eina_Rbtree *root, co
/**
- * @brief Returned a new prefix iterator associated to a rbtree.
+ * @brief Returns a new prefix iterator associated to an rbtree.
*
- * @param root The root of rbtree.
- * @return A new iterator.
+ * @details This function returns a newly allocated iterator associated to
+ * @a root. It iterates the tree using prefix walk. If @a root is
+ * @c NULL, this function still returns a valid iterator that always
+ * returns @c false on eina_iterator_next(), thus keeping the API sane.
*
- * This function returns a newly allocated iterator associated to @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.
+ * @since_tizen 2.3
*
- * If the memory can not be allocated, @c NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @remarks If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
+ * returned.
+ *
+ * @remarks If the rbtree structure changes then the iterator becomes
+ * invalid. That is, if you add or remove nodes this iterator's
+ * behavior is undefined and your program may crash.
+ *
+ * @param[in] root The root of the rbtree
+ * @return A new iterator
*
- * @warning if the rbtree structure changes then the iterator becomes
- * invalid! That is, if you add or remove nodes this iterator
- * behavior is undefined and your program may crash!
*/
EAPI Eina_Iterator *eina_rbtree_iterator_prefix(const Eina_Rbtree *root) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Returned a new prefix iterator associated to a rbtree.
+ * @brief Returns a new prefix iterator associated to an rbtree.
+ *
+ * @details This function returns a newly allocated iterator associated to
+ * @a root. It iterates the tree using infix walk. If @a root is
+ * @c NULL, this function still returns a valid iterator that always
+ * returns @c false on eina_iterator_next(), thus keeping the API sane.
*
- * @param root The root of rbtree.
- * @return A new iterator.
+ * @since_tizen 2.3
*
- * This function returns a newly allocated iterator associated to @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.
+ * @remarks If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
+ * returned.
*
- * If the memory can not be allocated, @c NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @remarks If the rbtree structure changes then the iterator becomes
+ * invalid. That is, if you add or remove nodes this iterator's
+ * behavior is undefined and your program may crash.
+ *
+ * @param[in] root The root of the rbtree
+ * @return A new iterator
*
- * @warning if the rbtree structure changes then the iterator becomes
- * invalid! That is, if you add or remove nodes this iterator
- * behavior is undefined and your program may crash!
*/
EAPI Eina_Iterator *eina_rbtree_iterator_infix(const Eina_Rbtree *root) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Returned a new prefix iterator associated to a rbtree.
+ * @brief Returns a new prefix iterator associated to an rbtree.
+ *
+ * @details This function returns a newly allocated iterator associated to
+ * @a root. It iterates the tree using postfix walk. If @a root is
+ * @c NULL, this function still returns a valid iterator that always
+ * returns @c false on eina_iterator_next(), thus keeping the API sane.
*
- * @param root The root of rbtree.
- * @return A new iterator.
+ * @since_tizen 2.3
*
- * This function returns a newly allocated iterator associated to @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.
+ * @remarks If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
+ * returned.
*
- * If the memory can not be allocated, @c NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @remarks If the rbtree structure changes then the iterator becomes
+ * invalid. That is, if you add or remove nodes this iterator's
+ * behavior is undefined and your program may crash.
+ *
+ * @param[in] root The root of the rbtree
+ * @return A new iterator
*
- * @warning if the rbtree structure changes then the iterator becomes
- * invalid! That is, if you add or remove nodes this iterator
- * behavior is undefined and your program may crash!
*/
EAPI Eina_Iterator *eina_rbtree_iterator_postfix(const Eina_Rbtree *root) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
@@ -257,12 +268,4 @@ EAPI Eina_Iterator *eina_rbtree_iterator_postfix(const Eina_Rbtree *root)
* @}
*/
-/**
- * @}
- */
-
-/**
- * @}
- */
-
#endif