From 42531adcf9d1ff51c5bc1b068a9c57a8a8a912a7 Mon Sep 17 00:00:00 2001
From: Kasper Peeters <kasper.peeters@phi-sci.com>
Date: Sun, 13 Feb 2022 13:05:44 +0000
Subject: [PATCH] Add missing include <string>. Add sample program for
 iterators <-> paths, and documentation for it. Remove compiler warnings.

---
 ChangeLog          |  4 ++++
 doc/main.md        | 21 ++++++++++++++++++++-
 src/.gitignore     |  2 ++
 src/Makefile       |  3 +++
 src/sample_path.cc | 27 +++++++++++++++++++++++++++
 src/tree.hh        | 10 +++++-----
 6 files changed, 61 insertions(+), 6 deletions(-)
 create mode 100644 src/sample_path.cc

diff --git a/ChangeLog b/ChangeLog
index 2dd4125..243207a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2022-02-13  Kasper Peeters  <kasper.peeters@phi-sci.com>
+
+	* Include <string> to avoid compilation errors.
+
 2020-11-07  Kasper Peeters  <kasper.peeters@phi-sci.com>
 
 	* Release 3.17
diff --git a/doc/main.md b/doc/main.md
index bcb521b..13c24e4 100644
--- a/doc/main.md
+++ b/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
 ----------------
diff --git a/src/.gitignore b/src/.gitignore
index 86400f4..1abdd01 100644
--- a/src/.gitignore
+++ b/src/.gitignore
@@ -4,3 +4,5 @@ test1
 test2
 test3
 test4
+sample_path
+test_tree
diff --git a/src/Makefile b/src/Makefile
index 6d42567..449caea 100644
--- a/src/Makefile
+++ b/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
diff --git a/src/sample_path.cc b/src/sample_path.cc
new file mode 100644
index 0000000..107c4fd
--- /dev/null
+++ b/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'
+   }
diff --git a/src/tree.hh b/src/tree.hh
index fd2c450..906cda1 100644
--- a/src/tree.hh
+++ b/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) 
 					{