[src/netbsd-6]: src/share/man/man3 Pull up following revision(s) (requested b...

[msaitoh <msaitoh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/a50669fd8132
branches:  netbsd-6
changeset: 776725:a50669fd8132
user:      msaitoh <msaitoh%NetBSD.org@localhost>
date:      Mon Oct 27 05:51:57 2014 +0000

description:
Pull up following revision(s) (requested by riastradh in ticket #1136):
        share/man/man3/rbtree.3: revision 1.8
Fix documentation of rbtree(3) iteration.
. Fix sense of rb_tree_iterate(rbt, NULL, ...).
. Document RB_TREE_MIN/RB_TREE_MAX to avoid relying on that sense.
. Document RB_TREE_FOREACH and RB_TREE_FOREACH_REVERSE to simplify
iteration.
Addresses PR lib/46034 and PR lib/47144.  It would have been nice to
make `x = NULL; while ((x = rb_tree_iterate(t, NULL, ...)) != NULL)'
DTRT to traverse t, but it's too much late for that now.
We probably ought to have an RB_TREE_FOREACH{,_REVERSE}_SAFE too.
ok christos

diffstat:

 share/man/man3/rbtree.3 |  50 ++++++++++++++++++++++++++++++++++++++++++++----
 1 files changed, 45 insertions(+), 5 deletions(-)

diffs (88 lines):

diff -r 7acc7ca57109 -r a50669fd8132 share/man/man3/rbtree.3
--- a/share/man/man3/rbtree.3   Mon Oct 27 05:46:27 2014 +0000
+++ b/share/man/man3/rbtree.3   Mon Oct 27 05:51:57 2014 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: rbtree.3,v 1.5.6.1 2012/09/03 18:41:15 riz Exp $
+.\"     $NetBSD: rbtree.3,v 1.5.6.2 2014/10/27 05:51:57 msaitoh Exp $
 .\"
 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd August 19, 2012
+.Dd March 13, 2013
 .Dt RBTREE 3
 .Os
 .Sh NAME
@@ -50,7 +50,13 @@
 .Ft void *
 .Fn rb_tree_find_node_leq "rb_tree_t *rbt" "const void *key"
 .Ft void *
-.Fn rb_tree_iterate "rb_tree_t *rbt" "void *rb" "const unsigned int direction"
+.Fn rb_tree_iterate "rb_tree_t *rbt" "void *rb" "unsigned int direction"
+.Ft void *
+.Fn RB_TREE_MIN "rb_tree_t *rbt"
+.Ft void *
+.Fn RB_TREE_MAX "rb_tree_t *rbt"
+.Fn RB_TREE_FOREACH "void *rb" "rb_tree_t *rbt"
+.Fn RB_TREE_FOREACH_REVERSE "void *rb" "rb_tree_t *rbt"
 .Sh DESCRIPTION
 .Nm
 provides red-black trees.
@@ -190,7 +196,7 @@
 .Fa rb
 is
 .Dv NULL ,
-return the last node in
+return the first node in
 .Fa rbt
 or, if the tree is empty, return
 .Dv NULL .
@@ -207,10 +213,44 @@
 .Fa rb
 is
 .Dv NULL ,
-return the first node in
+return the last node in
 .Fa rbt
 or, if the tree is empty, return
 .Dv NULL .
+.It Fn RB_TREE_MIN "rbt"
+Return the first node in
+.Fa rbt ,
+i.e. the node with the least key, or
+.Dv NULL
+if
+.Fa rbt
+is empty.
+.It Fn RB_TREE_MAX "rbt"
+Return the last node in
+.Fa rbt ,
+i.e. the node with the greatest key, or
+.Dv NULL
+if
+.Fa rbt
+is empty.
+.It Fn RB_TREE_FOREACH "rb" "rbt"
+.Nm RB_TREE_FOREACH
+is a macro to be used in the place of a
+.Dv for
+header preceding a statement to traverse the nodes in
+.Fa rbt
+from least to greatest, assigning
+.Fa rb
+to each node in turn and executing the statement.
+.It Fn RB_TREE_FOREACH_REVERSE "rb" "rbt"
+.Nm RB_TREE_FOREACH_REVERSE
+is a macro to be used in the place of a
+.Dv for
+header preceding a statement to traverse the nodes in
+.Fa rbt
+from greatest to least, assigning
+.Fa rb
+to each node in turn and executing the statement.
 .El
 .Sh CODE REFERENCES
 The