tree: api: harmonize deletion with insertion.

* tree.c (tree_delete): Renamed to tree_delete_node.
(tree_delete): New function which returns element
rather than node.
(tree_root): Registered tree-delete-node intrinsic.

* txr.1: Documented.

2 files changed, 39 insertions, 5 deletions

diff --git a/tree.c b/tree.c
index 544c991d..22cac379 100644
--- a/tree.c
+++ b/tree.c
@@ -423,13 +423,19 @@ static val tree_lookup(val tree, val key)
   return if2(node, node->tn.key);
 }
 
-static val tree_delete(val tree, val key)
+static val tree_delete_node(val tree, val key)
 {
-  val self = lit("tree-delete");
+  val self = lit("tree-delete-node");
   struct tree *tr = coerce(struct tree *, cobj_handle(self, tree, tree_s));
   return tr_delete(tr, key);
 }
 
+static val tree_delete(val tree, val key)
+{
+  val node = tree_delete_node(tree, key);
+  return if2(node, node->tn.key);
+}
+
 static val tree_root(val tree)
 {
   val self = lit("tree-root");
@@ -678,6 +684,7 @@ void tree_init(void)
   reg_fun(intern(lit("tree-insert"), user_package), func_n2(tree_insert));
   reg_fun(intern(lit("tree-lookup-node"), user_package), func_n2(tree_lookup_node));
   reg_fun(intern(lit("tree-lookup"), user_package), func_n2(tree_lookup));
+  reg_fun(intern(lit("tree-delete-node"), user_package), func_n2(tree_delete_node));
   reg_fun(intern(lit("tree-delete"), user_package), func_n2(tree_delete));
   reg_fun(intern(lit("tree-root"), user_package), func_n1(tree_root));
   reg_fun(intern(lit("tree-begin"), user_package), func_n1(tree_begin));
diff --git a/txr.1 b/txr.1
index 85b2013e..ad97ed52 100644
--- a/txr.1
+++ b/txr.1
@@ -45463,13 +45463,13 @@ A possible implementation is this:
       (key node)))
 .brev
 
-.coNP Function @ tree-delete
+.coNP Function @ tree-delete-node
 .synb
-.mets (tree-delete < tree << key )
+.mets (tree-delete-node < tree << key )
 .syne
 .desc
 The
-.code tree-delete
+.code tree-delete-node
 function searches
 .meta tree
 for an element which matches
@@ -45493,6 +45493,33 @@ Otherwise, if a matching element is not found, then
 .code nil
 is returned.
 
+.coNP Function @ tree-delete
+.synb
+.mets (tree-delete < tree << key )
+.syne
+.desc
+The
+.code tree-delete
+function tries to removes from
+.meta tree
+the element which matches
+.metn key .
+
+If successful, it returns that element, otherwise it returns
+.codn nil .
+
+Note: the semantics of the
+.code tree-delete
+function can be understood in terms of
+.codn tree-delete-node .
+A possible implementation is this:
+
+.verb
+  (defun tree-delete (tree key)
+    (iflet ((node (tree-delete-node tree key)))
+      (key node)))
+.brev
+
 .coNP Function @ tree-root
 .synb
 .mets (tree-root < tree )