doxy
[ffmpeg.git] / libavutil / tree.h
index 7c0c57c..36897ef 100644 (file)
 #define TREE_H
 
 struct AVTreeNode;
-void *av_tree_find(const struct AVTreeNode *t, void *key, int (*cmp)(void *key, const void *b), void *next[2]);
-void *av_tree_insert(struct AVTreeNode **tp, void *key, int (*cmp)(void *key, const void *b));
+
+/**
+ * Finds an element.
+ * @param root a pointer to the root node of the tree
+ * @param next if next is not NULL then next[0] will contain the previous element and
+ *             next[1] the next element if either doesnt exist then the corresponding
+ *             entry in next is unchanged
+ * @return an element with cmp(key, elem)==0 or NULL if no such element exists in
+ *         the tree
+ */
+void *av_tree_find(const struct AVTreeNode *root, void *key, int (*cmp)(void *key, const void *b), void *next[2]);
+
+/**
+ * Finds a element for which cmp(key, elem)==0, if no such element is found key
+ * is inserted into the tree.
+ * @param rootp a pointer to a pointer to the root node of the tree note the
+ *              root node can change during insertions, this is required to
+ *              keep the tree balanced
+ *
+ * @return if no insertion happened, the found element
+ *         if a insertion happened, then either key or NULL is returned (which it is
+ *         depends on the tree state and the implemenattion, you should make no
+ *         asumtations that its one or the other in code)
+ */
+void *av_tree_insert(struct AVTreeNode **rootp, void *key, int (*cmp)(void *key, const void *b));
 void av_tree_destroy(struct AVTreeNode *t);
 
 #endif /* TREE_H */