From owner-svn-src-all@FreeBSD.ORG Sun Nov 10 19:41:05 2013 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id 5558EE7A; Sun, 10 Nov 2013 19:41:05 +0000 (UTC) (envelope-from bms@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 28FB12D2B; Sun, 10 Nov 2013 19:41:05 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id rAAJf5Tb009339; Sun, 10 Nov 2013 19:41:05 GMT (envelope-from bms@svn.freebsd.org) Received: (from bms@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id rAAJf4MB009338; Sun, 10 Nov 2013 19:41:04 GMT (envelope-from bms@svn.freebsd.org) Message-Id: <201311101941.rAAJf4MB009338@svn.freebsd.org> From: Bruce M Simpson Date: Sun, 10 Nov 2013 19:41:04 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r257921 - head/share/man/man3 X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 10 Nov 2013 19:41:05 -0000 Author: bms Date: Sun Nov 10 19:41:04 2013 New Revision: 257921 URL: http://svnweb.freebsd.org/changeset/base/257921 Log: Document the RB_FOREACH_FROM() and RB_FOREACH_REVERSE_FROM() macros. These are largely syntactic sugar. However, they improve code readability where an RB_FOREACH() or RB_FOREACH_REVERSE() traversal has been interrupted and must be resumed. Performance is improved by avoiding unnecessary traversal from the head node. Modified: head/share/man/man3/tree.3 Modified: head/share/man/man3/tree.3 ============================================================================== --- head/share/man/man3/tree.3 Sun Nov 10 18:46:59 2013 (r257920) +++ head/share/man/man3/tree.3 Sun Nov 10 19:41:04 2013 (r257921) @@ -30,7 +30,7 @@ .\" .\" $FreeBSD$ .\" -.Dd November 4, 2013 +.Dd November 10, 2013 .Dt TREE 3 .Os .Sh NAME @@ -70,8 +70,10 @@ .Nm RB_RIGHT , .Nm RB_PARENT , .Nm RB_FOREACH , +.Nm RB_FOREACH_FROM , .Nm RB_FOREACH_SAFE , .Nm RB_FOREACH_REVERSE , +.Nm RB_FOREACH_REVERSE_FROM , .Nm RB_FOREACH_REVERSE_SAFE , .Nm RB_INIT , .Nm RB_INSERT , @@ -137,8 +139,10 @@ .Ft "struct TYPE *" .Fn RB_PARENT "struct TYPE *elm" "RB_ENTRY NAME" .Fn RB_FOREACH VARNAME NAME "RB_HEAD *head" +.Fn RB_FOREACH_FROM "VARNAME" "NAME" "RB_HEAD *head" "POS_VARNAME" .Fn RB_FOREACH_SAFE "VARNAME" "NAME" "RB_HEAD *head" "TEMP_VARNAME" .Fn RB_FOREACH_REVERSE VARNAME NAME "RB_HEAD *head" +.Fn RB_FOREACH_REVERSE_FROM "VARNAME" "NAME" "RB_HEAD *head" "POS_VARNAME" .Fn RB_FOREACH_REVERSE_SAFE "VARNAME" "NAME" "RB_HEAD *head" "TEMP_VARNAME" .Ft void .Fn RB_INIT "RB_HEAD *head" @@ -470,6 +474,15 @@ they permit both the removal of np as well as freeing it from within the loop safely without interfering with the traversal. .Pp +Both +.Fn RB_FOREACH_FROM +and +.Fn RB_FOREACH_REVERSE_FROM +may be used to continue an interrupted traversal +in a forward or reverse direction respectively. +The resume point should be passed as their last argument, +and will be overwritten to provide safe traversal. +.Pp The .Fn RB_EMPTY macro should be used to check whether a red-black tree is empty.