tree: new functions for reseting iterator.

* tree.c (tree_reset, tree_reset_at): New functions.
(tree_init): tree-reset and tree-reset-at intrinsics
registered.

* tree.h (tree_reset, tree_reset_at): Declared.

* tests/010/tree.tl: New tests.

* txr.1: Documented.

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

1 files changed, 51 insertions, 0 deletions

diff --git a/txr.1 b/txr.1
index 1cc8bdc5..e556666e 100644
--- a/txr.1
+++ b/txr.1
@@ -51573,6 +51573,57 @@ function to the
 .code tree-iter
 object.
 
+.coNP Functions @ tree-reset and @ tree-reset-at
+.synb
+.mets (tree-reset < iter < tree )
+.mets (tree-reset-at < iter < tree << low-key )
+.syne
+.desc
+The
+.code tree-reset
+and
+.code tree-reset-at
+functions are closely analogous to
+.code tree-begin
+and
+.codn tree-begin-at ,
+respectively.  These functions do not create a new iterator object.
+
+The
+.meta iter
+argument must be an existing
+.code tree-iter
+object, previously returned by a call to either
+.code tree-begin
+or
+.codn tree-begin-at .
+Regardless of its current state, the
+.meta iter
+object is re-initialized to traverse the specified
+.metn tree ,
+and is then returned.
+
+The
+.code tree-reset
+function prepares
+.meta iter
+to traverse in the same manner as would new iterator returned by
+.code tree-begin
+for the
+.meta tree
+argument.
+The
+.code tree-begin-at
+function similarly prepares
+.meta iter
+to traverse in the same manner as a new iterator returned by
+.code tree-begin-at
+for the
+.meta tree
+and
+.meta low-key
+arguments.
+
 .coNP Function @ tree-next
 .synb
 .mets (tree-next < iter )