I like this idea, and the parts for SPLAY_INSERT and RB_INSERT look
fine.
SPLAY_REMOVE appears to returns the pointer it is given or NULL if the
item isn't found. I don't see what errors it could return NULL for, so I
think it would be better to say "NULL is returned if no item with that
key is found". Or at least if you can spot any errors I can't, "to
indicate an error or that the key is not found".
RB_REMOVE returns the pointer it is given whether or not the item is in
the tree (even for an empty tree). This seems unexpected, so it might be
a bug...
On Mon, May 03, 2010 at 10:05:14PM +0200, Tim van der Molen wrote:
> This diff moves the documentation of the return values of
> {RB,SPLAY}_{INSERT,REMOVE} from the NOTES section (where it is hard to
> find) to the place where each function is described. (Note that the
> RB_INSERT description already documents the return values.)
>
> Regards,
> Tim
>
> Index: tree.3
> ===================================================================
> RCS file: /cvs/src/share/man/man3/tree.3,v
> retrieving revision 1.20
> diff -u tree.3
> --- tree.3 28 Jan 2009 12:22:48 -0000 1.20
> +++ tree.3 3 May 2010 19:55:38 -0000
> @@ -258,6 +258,11 @@
> macro inserts the new element
> .Fa elm
> into the tree.
> +Upon success,
> +.Va NULL
> +is returned.
> +If a matching element already exists in the tree, the insertion is
> +aborted, and a pointer to the existing element is returned.
> .Pp
> The
> .Fn SPLAY_REMOVE
> @@ -265,6 +270,10 @@
> .Fa elm
> from the tree pointed by
> .Fa head .
> +Upon success, a pointer to the removed element is returned.
> +Otherwise,
> +.Va NULL
> +is returned to indicate an error.
> .Pp
> The
> .Fn SPLAY_FIND
> @@ -405,6 +414,10 @@
> .Fa elm
> from the tree pointed by
> .Fa head .
> +Upon success, a pointer to the removed element is returned.
> +Otherwise,
> +.Va NULL
> +is returned to indicate an error.
> .Pp
> The
> .Fn RB_FIND
> @@ -543,22 +556,5 @@
> free(var);
> }
> .Ed
> -.Pp
> -Both
> -.Fn RB_INSERT
> -and
> -.Fn SPLAY_INSERT
> -return
> -.Va NULL
> -if the element was inserted in the tree successfully, otherwise they
> -return a pointer to the element with the colliding key.
> -.Pp
> -Accordingly,
> -.Fn RB_REMOVE
> -and
> -.Fn SPLAY_REMOVE
> -return the pointer to the removed element, otherwise they return
> -.Va NULL
> -to indicate an error.
> .Sh AUTHORS
> The author of the tree macros is Niels Provos.
