import stlplus 3.7

[chaz/yoink] / src / stlplus / containers / ntree.hpp

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