Add missing include <string>.

Add sample program for iterators <-> paths, and documentation for it.
Remove compiler warnings.

Author: kpeeters

ChangeLog

@@ -1,3 +1,7 @@
+2022-02-13  Kasper Peeters  <[email protected]>
+
+	* Include <string> to avoid compilation errors.
+
 2020-11-07  Kasper Peeters  <[email protected]>
 
 	* Release 3.17

doc/main.md

@@ -108,7 +108,26 @@ keep effect for a single increment or decrement of the
 iterator. Finally, whether or not an iterator is actually pointing at
 a node (i.e.~is not an "end" iterator) can be tested using the
 ``is_valid(iterator)`` member of the tree class.
-   
+
+- **Paths**:
+
+  Tree iterators, like those for all STL containers, are tied to the
+  container, and cannot simply be used to "access an element at the
+  same location in a different tree" (they are, in essence, wrappers
+  for pointers to memory locations). If you want a representation of
+  the iterator which is independent of the particular location where
+  your tree is located in memory, use the following two methods:
+  
+  ``path_from_iterator(iterator, top)``: obtain a ``path_t`` object
+  from an iterator, relative to the iterator ``top``.
+  
+  ``iterator_from_path(path, top)``: the inverse of the above, that
+  is, obtain an iterator from a ``path_t`` object.
+  
+  Paths are simply vectors of integers, indicating which child branch
+  to follow at every depth of the tree. See ``src/sample_path.cc`` for
+  an example.
+  
 
 Basic operations
 ----------------

src/.gitignore

@@ -4,3 +4,5 @@ test1
 test2
 test3
 test4
+sample_path
+test_tree

src/Makefile

@@ -13,6 +13,9 @@ test2: test2.o
 test_tree: test_tree.o
 	g++ -o test_tree test_tree.o
 
+sample_path: sample_path.o
+	g++ -o sample_path sample_path.o
+
 run_tests: test1 test1.req
 	./test1 > test1.res
 	@diff test1.res test1.req

src/sample_path.cc

@@ -0,0 +1,27 @@
+
+#include "tree.hh"
+#include <iostream>
+
+// Sample to demonstrate how to turn a tree iterator into a
+// path_t, which is a vector of integers indicating which
+// child is taken at any depth.
+
+int main(int argc, char **argv)
+   {
+   tree<std::string> tr;
+
+   tr.set_head("head");
+   auto i1 = tr.append_child(tr.begin(), "one");
+   auto i2 = tr.append_child(tr.begin(), "two");
+   auto i3 = tr.append_child(tr.begin(), "three");
+   auto i4 = tr.append_child(i2, "four");
+   auto i5 = tr.append_child(i2, "five"); 
+
+   auto path = tr.path_from_iterator(i5, tr.begin());
+   for(auto& p: path)
+      std::cerr << p << "/";
+   std::cerr << std::endl;          // prints '0/1/1/'
+
+   auto fnd = tr.iterator_from_path(path, tr.begin());
+   std::cerr << *fnd << std::endl;  // prints 'five'
+   }

src/tree.hh

@@ -9,8 +9,8 @@
 
 /** \mainpage tree.hh
     \author   Kasper Peeters
-    \version  3.17
-    \date     07-Nov-2020
+    \version  3.18
+    \date     13-Feb-2021
     \see      http://tree.phi-sci.com/
     \see      http://github.com/kpeeters/tree.hh/
 
@@ -34,7 +34,7 @@
 #include <queue>
 #include <algorithm>
 #include <cstddef>
-
+#include <string>
 
 /// A node in the tree, combining links to other nodes as well as the actual data.
 template<class T>
@@ -86,7 +86,7 @@ class navigation_error : public std::logic_error {
 //			std::cerr << boost::stacktrace::stacktrace() << std::endl;
 //			str << boost::stacktrace::stacktrace();
 //			stacktrace=str.str();
-			};
+			}
 
 //		virtual const char *what() const noexcept override
 //			{
@@ -503,7 +503,7 @@ class tree {
 		template<class StrictWeakOrdering>
 		class compare_nodes {
 			public:
-				compare_nodes(StrictWeakOrdering comp) : comp_(comp) {};
+				compare_nodes(StrictWeakOrdering comp) : comp_(comp) {}
 
 				bool operator()(const tree_node *a, const tree_node *b) 
 					{