X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Fyoink;a=blobdiff_plain;f=src%2Fstlplus%2Fcontainers%2Fntree.hpp;h=02996563809d1f8d4b9ee2a0ebd7030b5c92df35;hp=33817e2b54a816d1f77c4edfcc93f08655fc4d69;hb=4f6e4488a55f7e3ba3f7485d78177f793c0eab9a;hpb=6b0a0d0efafe34d48ab344fca3b479553bd4e62c

diff --git a/src/stlplus/containers/ntree.hpp b/src/stlplus/containers/ntree.hpp
index 33817e2..0299656 100644
--- a/src/stlplus/containers/ntree.hpp
+++ b/src/stlplus/containers/ntree.hpp
@@ -4,7 +4,7 @@
 
 //   Author:    Andy Rushton
 //   Copyright: (c) Southampton University 1999-2004
-//              (c) Andy Rushton           2004-2009
+//              (c) Andy Rushton           2004 onwards
 //   License:   BSD License, see ../docs/license.html
 
 //   A templated n-ary tree data structure. STL-like but the definition of
@@ -75,7 +75,7 @@ namespace stlplus
     friend class ntree_postfix_iterator<T,TRef,TPtr>;
 
   public:
-    // Note: I had to make this public to get round a compiler problem - it should be private
+    // Note: I had to make this public to get round a problem implementing persistence - it should be private
     // you cannot create a valid iterator except by calling an ntree method that returns one
     // constructor used by ntree to create a non-null iterator
     explicit ntree_iterator(ntree_node<T>* node);
@@ -315,38 +315,73 @@ namespace stlplus
     //////////////////////////////////////////////////////////////////////////////
     // modification
 
+    // discard previous contents and create a new root node
     iterator insert(const T&);
-
+    // add a new child inserted into the node's children at the specified place
     iterator insert(const iterator& node, unsigned child, const T&)
       throw(wrong_object,null_dereference,end_dereference,std::out_of_range);
+    // shortcut for insert at the end i.e. tree.insert(node, node.children(), value)
+    iterator insert(const iterator& node, const T&) 
+      throw(wrong_object,null_dereference,end_dereference);
+    // old name for the above
     iterator append(const iterator& node, const T&) 
       throw(wrong_object,null_dereference,end_dereference);
 
+    // discard previous contents and copy the tree
+    iterator insert(const ntree<T>&);
+    // add a copy of the tree as a new child inserted into the node's children at the specified place
     iterator insert(const iterator& node, unsigned child, const ntree<T>&)
       throw(wrong_object,null_dereference,end_dereference,std::out_of_range);
+    // shortcut for insert at the end i.e. tree.insert(node, node.children(), value)
+    iterator insert(const iterator& node, const ntree<T>&)
+      throw(wrong_object,null_dereference,end_dereference);
+    // old name for the above
     iterator append(const iterator& node, const ntree<T>&)
       throw(wrong_object,null_dereference,end_dereference);
 
+    // discard previous contents and move the tree without copying
+    // invalidates all iterators to the old tree
+    iterator move(ntree<T>&);
+    // move the tree to become the designated child
+    // invalidates all iterators to the old tree
+    iterator move(const iterator& node, unsigned child, ntree<T>&)
+      throw(wrong_object,null_dereference,end_dereference,std::out_of_range);
+    // shortcut for move to the last child i.e. node.move(node, node.children(), value)
+    iterator move(const iterator& node, ntree<T>&)
+      throw(wrong_object,null_dereference,end_dereference);
+
+    // replace the node with the new value, pushing the old node down to make it the child
+    // returns the iterator to the new, pushed node
     iterator push(const iterator& node, const T&) 
       throw(wrong_object,null_dereference,end_dereference);
+    // erases the specified child, moving its children up to become the node's children
     void pop(const iterator& node, unsigned child) 
       throw(wrong_object,null_dereference,end_dereference);
 
+    // erase the whole tree
     void erase(void);
+    // erase the node and all its children
     void erase(const iterator& node)
       throw(wrong_object,null_dereference,end_dereference);
+    // erase the specified child
     void erase(const iterator& node, unsigned child)
       throw(wrong_object,null_dereference,end_dereference,std::out_of_range);
 
+    // get a copy of the tree as a tree
     ntree<T> subtree(void);
+    // get a copy of the subtree as a tree with the specified node as root
     ntree<T> subtree(const iterator& node)
       throw(wrong_object,null_dereference,end_dereference);
+    // get a copy of the subtree as a tree with the specified child as root
     ntree<T> subtree(const iterator& node, unsigned child)
       throw(wrong_object,null_dereference,end_dereference,std::out_of_range);
 
+    // move the whole tree to make a new tree
     ntree<T> cut(void);
+    // move the subtree to make a new tree with the specified node as root
     ntree<T> cut(const iterator& node)
       throw(wrong_object,null_dereference,end_dereference);
+    // move the subtree to make a new tree with the specified child as root
     ntree<T> cut(const iterator& node, unsigned child)
       throw(wrong_object,null_dereference,end_dereference,std::out_of_range);