1.1 --- a/ucx/avl.h Mon Mar 06 16:22:42 2017 +0100
1.2 +++ b/ucx/avl.h Sat Jul 15 19:20:06 2017 +0200
1.3 @@ -164,6 +164,68 @@
1.4 void *ucx_avl_get(UcxAVLTree *tree, intptr_t key);
1.5
1.6 /**
1.7 + * A mode for #ucx_avl_find_node() with the same behavior as
1.8 + * #ucx_avl_get_node().
1.9 + */
1.10 +#define UCX_AVL_FIND_EXACT 0
1.11 +/**
1.12 + * A mode for #ucx_avl_find_node() finding the node whose key is at least
1.13 + * as large as the specified key.
1.14 + */
1.15 +#define UCX_AVL_FIND_LOWER_BOUNDED 1
1.16 +/**
1.17 + * A mode for #ucx_avl_find_node() finding the node whose key is at most
1.18 + * as large as the specified key.
1.19 + */
1.20 +#define UCX_AVL_FIND_UPPER_BOUNDED 2
1.21 +/**
1.22 + * A mode for #ucx_avl_find_node() finding the node with a key that is as close
1.23 + * to the specified key as possible. If the key is present, the behavior is
1.24 + * like #ucx_avl_get_node(). This mode only returns <code>NULL</code> on
1.25 + * empty trees.
1.26 + */
1.27 +#define UCX_AVL_FIND_CLOSEST 3
1.28 +
1.29 +/**
1.30 + * Finds a node within the tree. The following modes are supported:
1.31 + * <ul>
1.32 + * <li>#UCX_AVL_FIND_EXACT: the same behavior as #ucx_avl_get_node()</li>
1.33 + * <li>#UCX_AVL_FIND_LOWER_BOUNDED: finds the node whose key is at least
1.34 + * as large as the specified key</li>
1.35 + * <li>#UCX_AVL_FIND_UPPER_BOUNDED: finds the node whose key is at most
1.36 + * as large as the specified key</li>
1.37 + * <li>#UCX_AVL_FIND_CLOSEST: finds the node with a key that is as close to
1.38 + * the specified key as possible. If the key is present, the behavior is
1.39 + * like #ucx_avl_get_node(). This mode only returns <code>NULL</code> on
1.40 + * empty trees.</li>
1.41 + * </ul>
1.42 + *
1.43 + * The distance function provided MUST agree with the compare function of
1.44 + * the AVL tree.
1.45 + *
1.46 + * @param tree the UcxAVLTree
1.47 + * @param key the key
1.48 + * @param dfnc the distance function
1.49 + * @param mode the find mode
1.50 + * @return the node (or <code>NULL</code>, if no node can be found)
1.51 + */
1.52 +UcxAVLNode *ucx_avl_find_node(UcxAVLTree *tree, intptr_t key,
1.53 + distance_func dfnc, int mode);
1.54 +
1.55 +/**
1.56 + * Finds a value within the tree.
1.57 + * See #ucx_avl_find_node() for details.
1.58 + *
1.59 + * @param tree the UcxAVLTree
1.60 + * @param key the key
1.61 + * @param dfnc the distance function
1.62 + * @param mode the find mode
1.63 + * @return the value (or <code>NULL</code>, if no value can be found)
1.64 + */
1.65 +void *ucx_avl_find(UcxAVLTree *tree, intptr_t key,
1.66 + distance_func dfnc, int mode);
1.67 +
1.68 +/**
1.69 * Puts a key/value pair into the tree.
1.70 *
1.71 * Attention: use this function only, if a possible old value does not need
1.72 @@ -196,7 +258,7 @@
1.73 *
1.74 * Note: the specified node is logically removed. The tree implementation
1.75 * decides which memory area is freed. In most cases the here provided node
1.76 - * is freed, so it's further use is generally undefined.
1.77 + * is freed, so its further use is generally undefined.
1.78 *
1.79 * @param tree the UcxAVLTree
1.80 * @param node the node to remove
