Fixes

Author: Oren (electricessence)

IChild.cs

@@ -4,16 +4,28 @@ namespace Open.Hierarchy
 {
 	public interface IChild
 	{
+		/// <summary>
+		/// The parent of this child.
+		/// </summary>
 		object Parent { get; }
 	}
 
 	public interface IChild<out TParent> : IChild
 	{
+		/// <summary>
+		/// The generic parent of this child.
+		/// </summary>
 		new TParent Parent { get; }
 	}
 
 	public static class ChildExtensions
 	{
+		/// <summary>
+		/// Crawls the ancestor lineage and returns them.
+		/// </summary>
+		/// <typeparam name="TNode">The node type.</typeparam>
+		/// <param name="node">The child node to use.</param>
+		/// <returns>An enumerable of the ancestors.</returns>
 		public static IEnumerable<TNode> GetAncestors<TNode>(
 			this TNode node)
 			where TNode : IChild<TNode>
@@ -26,6 +38,12 @@ public static IEnumerable<TNode> GetAncestors<TNode>(
 			}
 		}
 
+		/// <summary>
+		/// Crawls the ancestor lineage returns the first node with no parent.
+		/// </summary>
+		/// <typeparam name="TNode">The node type.</typeparam>
+		/// <param name="node">The child node to start with.</param>
+		/// <returns>The root node.</returns>
 		public static TNode GetRoot<TNode>(
 			this TNode node)
 			where TNode : IChild<TNode>

IHaveRoot.cs

@@ -2,11 +2,17 @@
 {
 	public interface IHaveRoot
 	{
+		/// <summary>
+		/// The root of this.
+		/// </summary>
 		object Root { get; }
 	}
 
 	public interface IHaveRoot<out TRoot> : IHaveRoot
 	{
+		/// <summary>
+		/// The generic root of this.
+		/// </summary>
 		new TRoot Root { get; }
 	}
 }

IParent.cs

@@ -1,75 +1,21 @@
-using System.Collections.Generic;
-using System.Linq;
+using System.Collections.Generic;
 
 namespace Open.Hierarchy
 {
 	public interface IParent
 	{
+		/// <summary>
+		/// Read only access to the contained children.
+		/// </summary>
+		// ReSharper disable once ReturnTypeCanBeEnumerable.Global
 		IReadOnlyList<object> Children { get; }
 	}
 
 	public interface IParent<out TChild> : IParent
 	{
-		new IReadOnlyList<TChild> Children { get; }
-	}
-
-	public static class ParentExtensions
-	{
-
 		/// <summary>
-		/// Returns all descendant nodes.
+		/// Generic read only access to the contained children.
 		/// </summary>
-		/// <param name="traversal">The mode by which the tree is traversed.</param>
-		/// <returns>The enumeration of all the descendant nodes.</returns>
-		public static IEnumerable<TNode> GetDescendants<TNode>(
-			this TNode node, TraversalMode traversal = TraversalMode.BreadthFirst)
-			where TNode : IParent<TNode>
-		{
-			// Attempt to be more breadth first.
-			switch (traversal)
-			{
-				case TraversalMode.BreadthFirst:
-					foreach (var child in node.Children)
-						yield return child;
-
-					var grandchildren = node.Children.SelectMany(c => c.Children);
-					foreach (var grandchild in grandchildren)
-						yield return grandchild;
-
-					foreach (var descendant in grandchildren
-						.SelectMany(c => c.GetDescendants()))
-						yield return descendant;
-
-					break;
-
-
-				case TraversalMode.DepthFirst:
-
-					foreach (var descendant in node.Children
-						.SelectMany(c => c.GetDescendants(TraversalMode.DepthFirst)))
-						yield return descendant;
-
-					break;
-			}
-
-		}
-
-		/// <summary>
-		/// Returns all descendant nodes and includes this node.
-		/// Breadth first returns this node first.  Depth first returns this node last.
-		/// </summary>
-		/// <param name="traversal">The mode by which the tree is traversed.</param>
-		/// <returns>The enumeration of all the descendant nodes including this one.</returns>
-		public static IEnumerable<TNode> GetNodes<TNode>(
-			this TNode node, TraversalMode traversal = TraversalMode.BreadthFirst)
-			where TNode : IParent<TNode>
-		{
-			if (traversal == TraversalMode.BreadthFirst)
-				yield return node;
-			foreach (var descendant in node.GetDescendants(traversal))
-				yield return descendant;
-			if (traversal == TraversalMode.DepthFirst)
-				yield return node;
-		}
+		new IReadOnlyList<TChild> Children { get; }
 	}
-}
+}

Node.Factory.cs

@@ -0,0 +1,175 @@
+using Open.Disposable;
+using System;
+
+namespace Open.Hierarchy
+{
+	public sealed partial class Node<T>
+	{
+		/// <summary>
+		/// Used for mapping a tree of evaluations which do not have access to their parent nodes.
+		/// </summary>
+		public sealed class Factory : DisposableBase
+		{
+			#region Creation, Recycling, and Disposal
+			public Factory()
+			{
+				_pool = new ConcurrentQueueObjectPool<Node<T>>(
+					() => new Node<T>(), PrepareForPool, null, ushort.MaxValue);
+			}
+
+			protected override void OnDispose(bool calledExplicitly)
+			{
+				if (calledExplicitly)
+				{
+					DisposeOf(ref _pool);
+				}
+			}
+
+			ConcurrentQueueObjectPool<Node<T>> _pool;
+
+			/// <summary>
+			/// Gets a blank node.
+			/// </summary>
+			/// <returns>A blank node.</returns>
+			public Node<T> GetBlankNode()
+			{
+				AssertIsAlive();
+
+				return _pool?.Take();
+			}
+
+			/// <summary>
+			/// Recycles the node into the object pool, returning the value contained.
+			/// </summary>
+			/// <param name="n">The node to be recycled.</param>
+			/// <returns>The value contained in the node.</returns>
+			public T Recycle(Node<T> n)
+			{
+				AssertIsAlive();
+
+				return RecycleInternal(n);
+			}
+
+			internal T RecycleInternal(Node<T> n)
+			{
+				var value = n.Value;
+				var p = _pool;
+				if (p == null) n.Teardown();
+				else p.Give(n);
+				return value;
+			}
+
+			void PrepareForPool(Node<T> n)
+				=> n.Recycle(this);
+			#endregion
+
+			/// <summary>
+			/// Clones a node by recreating the tree and copying the values.
+			/// </summary>
+			/// <param name="target">The node to replicate.</param>
+			/// <param name="newParentForClone">
+			/// If a parent is specified it will use that node as its parent.
+			/// By default it ends up being detatched.
+			/// </param>
+			/// <param name="onNodeCloned">A function that recieves the old node and its clone.</param>
+			/// <returns>The copy of the tree/branch.</returns>
+			public Node<T> Clone(
+				Node<T> target,
+				Node<T> newParentForClone = null,
+				Action<Node<T>, Node<T>> onNodeCloned = null)
+			{
+				AssertIsAlive();
+
+				var clone = _pool.Take();
+				clone.Value = target.Value;
+				newParentForClone?.Add(clone);
+
+				foreach (var child in target._children)
+					clone.Add(Clone(child, clone, onNodeCloned));
+
+				onNodeCloned?.Invoke(target, clone);
+
+				return clone;
+			}
+
+
+			/// <summary>
+			/// Clones a node by recreating the tree and copying the values.
+			/// </summary>
+			/// <param name="target">The node to replicate.</param>
+			/// <param name="onNodeCloned">A function that recieves the old node and its clone.</param>
+			/// <returns>The copy of the tree/branch.</returns>
+			public Node<T> Clone(
+				Node<T> target,
+				Action<Node<T>, Node<T>> onNodeCloned)
+			{
+				return Clone(target, null, onNodeCloned);
+			}
+
+			/// <summary>
+			/// Create's a clone of the entire tree but only returns the clone of this node.
+			/// </summary>
+			/// <returns>A clone of this node as part of a newly cloned tree.</returns>
+			public Node<T> CloneTree(Node<T> target)
+			{
+				Node<T> node = null;
+				Clone(target.Root, (n, clone) =>
+				{
+					if (n == target) node = clone;
+				});
+				return node;
+			}
+
+			/// <summary>
+			/// Generates a full hierarchy if the root is an IParent and uses the root as the value of the hierarchy.
+			/// Essentially building a map of the tree.
+			/// </summary>
+			/// <typeparam name="TRoot">The type of the root.</typeparam>
+			/// <param name="root">The root instance.</param>
+			/// <returns>The full map of the root.</returns>
+			public Node<T> Map<TRoot>(TRoot root)
+				where TRoot : T
+			{
+				AssertIsAlive();
+
+				var current = _pool.Take();
+				current.Value = root;
+
+				if (!(root is IParent<T> parent)) return current;
+				foreach (var child in parent.Children)
+				{
+					current.Add(Map<T>(child));
+				}
+
+				return current;
+			}
+
+			/// <summary>
+			/// Generates a full hierarchy if the root is an IParent and uses the root as the value of the hierarchy.
+			/// Essentially building a map of the tree.
+			/// </summary>
+			/// <param name="root">The root instance.</param>
+			/// <returns>The full map of the root.</returns>
+			public Node<T> Map(T root)
+			{
+				return Map<T>(root);
+			}
+
+			/// <summary>
+			/// Generates a full hierarchy if the root of the container is an IParent and uses the root as the value of the hierarchy.
+			/// Essentially building a map of the tree.
+			/// </summary>
+			/// <typeparam name="TRoot">The type of the root.</typeparam>
+			/// <param name="container">The container of the root instance.</param>
+			/// <returns>The full map of the root.</returns>
+			public Node<T> Map<TRoot>(IHaveRoot<TRoot> container)
+				where TRoot : T
+			{
+				return Map(container.Root);
+			}
+
+		}
+
+	}
+
+}