tree: new tree-begin-at function.

* tree.c (enum tree_iter_state): New iterator state
tr_find_low_prepared dedicated to the tree-begin-at traversal.
This state indicates that tree-next should visit the starting
node that it is given, and then after that, treat anything to
the left of it as having been visited. In the other states,
tree-next does not visit the node it is given but uses it as
the starting point to find the next node.
(tn_find_next): Bugfix here: when navigating the right link,
the function neglected to add the node to the path.  But the
logic for backtracking up the path expects this: it checks
whether the node from the path is the parent of a right child.
Somehow this didn't cause a problem for full traversals with
tree-begin; at least the existing test cases don't expose an
issue.  It caused a problem for tree-begin-at, though.
(tn_find_low): New static function. This finds the low-key
node in the tree, priming the iterator object with the correct
state and path content to continue the traversal from that
node on . We need the tr_find_low_prepared state in the
iterator in order to visit the low node itself that was found.
(tree_begin_at): New function.
(tree_init): Register tree-begin-at intrinsic.

* tree.h (tree_begin_at): Declared.

* tests/010/tree.tl: New test cases for tree-begin-at.

* txr.1: Documented.

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

1 files changed, 3 insertions, 2 deletions

diff --git a/share/txr/stdlib/doc-syms.tl b/share/txr/stdlib/doc-syms.tl
index 94455d7f..7527b96d 100644
--- a/share/txr/stdlib/doc-syms.tl
+++ b/share/txr/stdlib/doc-syms.tl
@@ -1078,6 +1078,7 @@
      ("del" "D-0040")
      ("cos" "D-0041")
      ("yield-from" "N-01556613")
+     ("tree-begin-at" "N-00A02578")
      ("dlvsym-checked" "N-029063A0")
      ("txr-when" "N-02311DCA")
      ("sock-accept" "N-00AF0FE8")
@@ -1398,7 +1399,7 @@
      ("itimer-virtual" "N-02B7882A")
      ("sig-stop" "N-0176430F")
      ("lazy-str-force" "N-03269DEF")
-     ("tree-begin" "N-02887FCA")
+     ("tree-begin" "N-00A02578")
      ("dt-chr" "N-02D8CAF4")
      ("buf-alloc-size" "N-013A3727")
      ("find-frames" "N-02B97226")
@@ -1509,9 +1510,9 @@
      ("veol2" "N-01812D70")
      ("f-dupfd-cloexec" "N-025E55E7")
      ("path-sock-p" "N-00198FC7")
+     ("format" "N-011ACA52")
      ("neq" "N-0216A942")
      ("ldo" "N-03EF3A27")
-     ("format" "N-011ACA52")
      ("etimedout" "N-036B1BDB")
      ("random-state-get-vec" "N-005C0F98")
      ("hash_keys" "N-01BD56A5")