If *next is NULL, then the supplied element will be removed if it exists.
If *next is non-NULL, then the supplied element will be inserted, unless
it already exists in the tree.
@param rootp A pointer to a pointer to the root node of the tree; note that
the root node can change during insertions, this is required
to keep the tree balanced.
@param key pointer to the element key to insert in the tree
@param next Used to allocate and free AVTreeNodes. For insertion the user
must set it to an allocated and zeroed object of at least
av_tree_node_size bytes size. av_tree_insert() will set it to
NULL if it has been consumed.
For deleting elements *next is set to NULL by the user and
av_tree_insert() will set it to the AVTreeNode which was
used for the removed element.
This allows the use of flat arrays, which have
lower overhead compared to many malloced elements.
You might want to define a function like:
@code
void *tree_insert(struct AVTreeNode **rootp, void *key,
int (*cmp)(void *key, const void *b),
AVTreeNode **next)
{
if (!*next)
*next = av_mallocz(av_tree_node_size);
return av_tree_insert(rootp, key, cmp, next);
}
void *tree_remove(struct AVTreeNode **rootp, void *key,
int (*cmp)(void *key, const void *b, AVTreeNode **next))
{
av_freep(next);
return av_tree_insert(rootp, key, cmp, next);
}
@endcode
@param cmp compare function used to compare elements in the tree, API identical
to that of Standard C's qsort
@return If no insertion happened, the found element; if an insertion or
removal happened, then either key or NULL will be returned.
Which one it is depends on the tree state and the implementation. You
should make no assumptions that it's one or the other in the code.
Insert or remove an element.
If *next is NULL, then the supplied element will be removed if it exists. If *next is non-NULL, then the supplied element will be inserted, unless it already exists in the tree.
@param rootp A pointer to a pointer to the root node of the tree; note that the root node can change during insertions, this is required to keep the tree balanced. @param key pointer to the element key to insert in the tree @param next Used to allocate and free AVTreeNodes. For insertion the user must set it to an allocated and zeroed object of at least av_tree_node_size bytes size. av_tree_insert() will set it to NULL if it has been consumed. For deleting elements *next is set to NULL by the user and av_tree_insert() will set it to the AVTreeNode which was used for the removed element. This allows the use of flat arrays, which have lower overhead compared to many malloced elements. You might want to define a function like: @code void *tree_insert(struct AVTreeNode **rootp, void *key, int (*cmp)(void *key, const void *b), AVTreeNode **next) { if (!*next) *next = av_mallocz(av_tree_node_size); return av_tree_insert(rootp, key, cmp, next); } void *tree_remove(struct AVTreeNode **rootp, void *key, int (*cmp)(void *key, const void *b, AVTreeNode **next)) { av_freep(next); return av_tree_insert(rootp, key, cmp, next); } @endcode @param cmp compare function used to compare elements in the tree, API identical to that of Standard C's qsort @return If no insertion happened, the found element; if an insertion or removal happened, then either key or NULL will be returned. Which one it is depends on the tree state and the implementation. You should make no assumptions that it's one or the other in the code.