tree: new tree-peek function.

* tree.c (tn_peek_next): New static function.
(tree_peek): New function.
(tree_init): Register tree-peek intrinsic.

* tree.h (tree_peek): Declared.

* txr.1: Documented.

* tests/010/tree.c: Work tree-peek into existing test case.

* share/txr/stdlib/doc-syms.tl: Updated.

1 files changed, 29 insertions, 10 deletions

diff --git a/txr.1 b/txr.1
index 69746dca..d50ecb46 100644
--- a/txr.1
+++ b/txr.1
@@ -51873,35 +51873,54 @@ and
 .meta low-key
 arguments.
 
-.coNP Function @ tree-next
+.coNP Functions @ tree-next and @ tree-peek
 .synb
 .mets (tree-next < iter )
+.mets (tree-peek < iter )
 .syne
 .desc
 The
 .code tree-next
+and
+.code tree-peek
 function returns the next node in sequence from the tree iterator
-.metn iter ,
-which must be an object of type
-.codn tree-iter .
-Note: the
+.metn iter .
+The iterator must be an object of type
+.codn tree-iter ,
+returned by the
 .code tree-begin
-function returns such a
-.code tree-iter
-object.
+or
+.code tree-begin-at
+functions.
 
-If there are no more nodes to be visited, the function returns
+If there are no more nodes to be visited, these functions
 .codn nil .
 
 If, during the traversal of a tree, nodes are inserted or deleted,
 the behavior of
 .code tree-next
+and
+.code tree-peek
 on
 .code tree-iter
-object that were obtained prior to the insertion or deletion is
+objects that were obtained prior to the insertion or deletion is
 not specified. An attempt to complete the iteration may not successfully
 visit all keys that should be visited.
 
+The
+.code tree-next
+function changes the state of the iterator. If
+.code tree-next
+is invoked repeatedly on the same iterator, it returns successive
+nodes of the tree.
+
+If
+.code tree-peek
+is invoked more than once on the same iterator without any intervening calls to
+.codn tree-next ,
+it returns the same node; it does not appear to change the state of
+the iterator and therefore does not advance through successive nodes.
+
 .coNP Special variable @ *tree-fun-whitelist*
 .desc
 The