Class HierarchyDecoratorExtensions

Namespace

Cuemon.Extensions.Runtime

Assembly

Cuemon.Extensions.Core.dll

Extension methods for the IHierarchy<T> interface hidden behind the IDecorator<T> interface.

public static class HierarchyDecoratorExtensions

Inheritance

object

HierarchyDecoratorExtensions

Examples

HierarchyDecoratorExtensions provides extension methods on Decorator.Enclose for navigating, replacing, and materializing hierarchy trees built from Hierarchy<T> nodes. This example builds a three-level string hierarchy (root → child-one → grandchild) and demonstrates root navigation, ancestor/descendant/sibling traversal, node replacement, and DataPair value extraction using typed formatters like UseConvertibleFormatter, UseDateTimeFormatter, and UseGuidFormatter. Key steps include using Decorator.Enclose to call methods such as Root(), AncestorsAndSelf(), Replace(), and UseCollection(). Console output confirms the root node name ("root"), ancestor chain ("root > child-one"), and typed values extracted from DataPair nodes.

using System;
using System.Collections;
using System.Collections.Generic;
using System.Linq;
using Cuemon;
using Cuemon.Extensions.Runtime;

namespace MyApp.Examples;

public static class HierarchyDecoratorExtensionsExample
{
    public static void Demonstrate()
    {
        var root = BuildStringHierarchy(out var childOne, out var grandchild, out _);

        var rootNode = Decorator.Enclose(grandchild).Root();
        var ancestors = Decorator.Enclose(grandchild).AncestorsAndSelf().Select(node => node.Instance).ToArray();
        var descendants = Decorator.Enclose(root).DescendantsAndSelf().Select(node => node.Instance).ToArray();
        var siblings = Decorator.Enclose(childOne).SiblingsAndSelf().Select(node => node.Instance).ToArray();
        var nodesAtDepth = Decorator.Enclose(grandchild).SiblingsAndSelfAt(1).Select(node => node.Instance).ToArray();
        var flattened = Decorator.Enclose(childOne).FlattenAll().Select(node => node.Instance).ToArray();
        var firstChildName = Decorator.Enclose(root).FindFirstInstance(node => node.Instance.StartsWith("child", StringComparison.Ordinal));
        var grandchildName = Decorator.Enclose(root).FindSingleInstance(node => node.Instance == "grandchild");
        var firstChildNode = Decorator.Enclose(root).FindFirst(node => node.Depth == 1);
        var grandchildNode = Decorator.Enclose(root).FindSingle(node => node.Instance == "grandchild");
        var childNames = Decorator.Enclose(root).FindInstance(node => node.Depth == 1).OrderBy(name => name).ToArray();
        var childNodes = Decorator.Enclose(root).Find(node => node.Depth == 1).ToArray();
        var indexedNode = Decorator.Enclose(root).NodeAt(2);

        Decorator.Enclose(grandchild).Replace((node, value) => node.Replace(value.ToUpperInvariant()));
        Decorator.Enclose(Decorator.Enclose(root).Find(node => node.Depth == 1)).ReplaceAll((node, value) => node.Replace(value.ToUpperInvariant()));

        var integerNode = BuildDataPairHierarchy(new DataPair(typeof(int).Name, "42", typeof(string)));
        var timestamp = new DateTime(2024, 1, 2, 3, 4, 5, DateTimeKind.Utc);
        var dateTimeNode = BuildDataPairHierarchy(new DataPair("When", timestamp, typeof(DateTime)));
        var guid = Guid.Parse("11111111-2222-3333-4444-555555555555");
        var guidNode = BuildDataPairHierarchy(new DataPair("Value", guid.ToString("D"), typeof(string)));
        var stringNode = BuildDataPairHierarchy(new DataPair("Text", "hello", typeof(string)));
        var decimalNode = BuildDataPairHierarchy(new DataPair("Amount", "42.5", typeof(string)));
        var uri = new Uri("https://example.com/path?value=42", UriKind.Absolute);
        var uriNode = BuildDataPairHierarchy(new DataPair("OriginalString", uri.OriginalString, typeof(string)));

        var typedValues = new object[]
        {
            Decorator.Enclose(integerNode).UseConvertibleFormatter(),
            Decorator.Enclose(dateTimeNode).UseDateTimeFormatter(),
            Decorator.Enclose(guidNode).UseGuidFormatter(),
            Decorator.Enclose(stringNode).UseStringFormatter(),
            Decorator.Enclose(decimalNode).UseDecimalFormatter(),
            Decorator.Enclose(uriNode).UseUriFormatter()
        };

        ICollection prices = Decorator.Enclose(BuildCollectionHierarchy(typeof(decimal), "42.5", "84.0")).UseCollection(typeof(decimal));
        IDictionary milestones = Decorator.Enclose(BuildDictionaryHierarchy(
            typeof(DateTime),
            new KeyValuePair<string, object>("created", timestamp),
            new KeyValuePair<string, object>("updated", timestamp.AddHours(2))))
            .UseDictionary(new[] { typeof(string), typeof(DateTime) });

        Console.WriteLine(rootNode.Instance);
        Console.WriteLine(string.Join(" > ", ancestors));
        Console.WriteLine(string.Join(", ", descendants));
        Console.WriteLine(string.Join(", ", siblings));
        Console.WriteLine(string.Join(", ", nodesAtDepth));
        Console.WriteLine(string.Join(", ", flattened));
        Console.WriteLine(firstChildName);
        Console.WriteLine(grandchildName);
        Console.WriteLine(firstChildNode.Instance);
        Console.WriteLine(grandchildNode.Instance);
        Console.WriteLine(string.Join(", ", childNames));
        Console.WriteLine(childNodes.Length);
        Console.WriteLine(indexedNode.Instance);
        Console.WriteLine(grandchild.Instance);
        Console.WriteLine(string.Join(", ", root.GetChildren().Select(node => node.Instance)));
        Console.WriteLine(string.Join(", ", typedValues));
        Console.WriteLine(string.Join(", ", prices.Cast<decimal>()));
        Console.WriteLine(string.Join(", ", milestones.Keys.Cast<string>()));
    }

    private static Hierarchy<string> BuildStringHierarchy(out IHierarchy<string> childOne, out IHierarchy<string> grandchild, out IHierarchy<string> childTwo)
    {
        var root = new Hierarchy<string>();
        root.Add("root");
        childOne = root.Add("child-one");
        grandchild = childOne.Add("grandchild");
        childTwo = root.Add("child-two");
        return root;
    }

    private static IHierarchy<DataPair> BuildDataPairHierarchy(DataPair pair)
    {
        var hierarchy = new Hierarchy<DataPair>();
        hierarchy.Add(pair);
        return hierarchy;
    }

    private static IHierarchy<DataPair> BuildCollectionHierarchy(Type valueType, params object[] values)
    {
        var hierarchy = new Hierarchy<DataPair>();
        hierarchy.Add(new DataPair("Items", null, typeof(List<object>)));
        foreach (var value in values)
        {
            hierarchy.Add(CreateValuePair(valueType, value));
        }

        return hierarchy;
    }

    private static IHierarchy<DataPair> BuildDictionaryHierarchy(Type valueType, params KeyValuePair<string, object>[] values)
    {
        var hierarchy = new Hierarchy<DataPair>();
        hierarchy.Add(new DataPair("Entries", null, typeof(Dictionary<string, object>)));
        foreach (var value in values)
        {
            var keyNode = hierarchy.Add(new DataPair("Key", value.Key, typeof(string)));
            keyNode.Add(CreateValuePair(valueType, value.Value));
        }

        return hierarchy;
    }

    private static DataPair CreateValuePair(Type valueType, object value)
    {
        if (valueType.IsPrimitive)
        {
            return new DataPair(valueType.Name, value, value.GetType());
        }

        if (valueType == typeof(Uri))
        {
            return new DataPair("OriginalString", value, typeof(string));
        }

        if (valueType == typeof(DateTime))
        {
            return new DataPair("When", value, typeof(DateTime));
        }

        return new DataPair("Value", value, value?.GetType() ?? typeof(object));
    }
}

Methods

AncestorsAndSelf<T>(IDecorator<IHierarchy<T>>)

Gets all ancestors (parent, grandparent, etc.) and self of the specified decorator in the hierarchical structure.

public static IEnumerable<IHierarchy<T>> AncestorsAndSelf<T>(this IDecorator<IHierarchy<T>> decorator)

Parameters

decorator IDecorator<IHierarchy<T>>

The IDecorator{IHierarchy{T}} to extend.

Returns

IEnumerable<IHierarchy<T>>

An IEnumerable<T> sequence equal to ancestors and self of the specified decorator.

Type Parameters

T

The type of the instance represented by the specified decorator in the hierarchical structure.

Exceptions

ArgumentNullException

decorator is null.

DescendantsAndSelf<T>(IDecorator<IHierarchy<T>>)

Gets all descendants (children, grandchildren, etc.) anf self of the current decorator in the hierarchical structure.

public static IEnumerable<IHierarchy<T>> DescendantsAndSelf<T>(this IDecorator<IHierarchy<T>> decorator)

Parameters

decorator IDecorator<IHierarchy<T>>

The IDecorator{IHierarchy{T}} to extend.

Returns

IEnumerable<IHierarchy<T>>

An IEnumerable<T> sequence equal to the descendants and self of the specified decorator.

Type Parameters

T

The type of the instance represented by the specified decorator in the hierarchical structure.

Exceptions

ArgumentNullException

decorator is null.

FindFirstInstance<T>(IDecorator<IHierarchy<T>>, Func<IHierarchy<T>, bool>)

Returns the first node instance that match the conditions defined by the function delegate match, or a default value if no node is found.

public static T FindFirstInstance<T>(this IDecorator<IHierarchy<T>> decorator, Func<IHierarchy<T>, bool> match)

Parameters

decorator IDecorator<IHierarchy<T>>

The IDecorator{IHierarchy{T}} to extend.

match Func<IHierarchy<T>, bool>

The function delegate that defines the conditions of the nodes to search for.

Returns

T

An Instance that match the conditions defined by the function delegate match, or a default value if no node is found.

Type Parameters

T

The type of the instance that this node represents.

FindFirst<T>(IDecorator<IHierarchy<T>>, Func<IHierarchy<T>, bool>)

Returns the first node that match the conditions defined by the function delegate match, or a default value if no node is found.

public static IHierarchy<T> FindFirst<T>(this IDecorator<IHierarchy<T>> decorator, Func<IHierarchy<T>, bool> match)

Parameters

decorator IDecorator<IHierarchy<T>>

The IDecorator{IHierarchy{T}} to extend.

match Func<IHierarchy<T>, bool>

The function delegate that defines the conditions of the nodes to search for.

Returns

IHierarchy<T>

An IHierarchy<T> node that match the conditions defined by the function delegate match, or a default value if no node is found.

Type Parameters

T

The type of the instance that this node represents.

FindInstance<T>(IDecorator<IHierarchy<T>>, Func<IHierarchy<T>, bool>)

Retrieves all node instances that match the conditions defined by the function delegate match.

public static IEnumerable<T> FindInstance<T>(this IDecorator<IHierarchy<T>> decorator, Func<IHierarchy<T>, bool> match)

Parameters

decorator IDecorator<IHierarchy<T>>

The IDecorator{IHierarchy{T}} to extend.

match Func<IHierarchy<T>, bool>

The function delegate that defines the conditions of the nodes to search for.

Returns

IEnumerable<T>

An IEnumerable<T> sequence containing all node instances that match the conditions defined by the specified predicate, if found.

Type Parameters

T

The type of the instance that this node represents.

FindSingleInstance<T>(IDecorator<IHierarchy<T>>, Func<IHierarchy<T>, bool>)

Returns the only node that match the conditions defined by the function delegate match, or a default value if no node instance is found; this method throws an exception if more than one node is found.

public static T FindSingleInstance<T>(this IDecorator<IHierarchy<T>> decorator, Func<IHierarchy<T>, bool> match)

Parameters

decorator IDecorator<IHierarchy<T>>

The IDecorator{IHierarchy{T}} to extend.

match Func<IHierarchy<T>, bool>

The function delegate that defines the conditions of the nodes to search for.

Returns

T

An Instance node that match the conditions defined by the function delegate match, or a default value if no node instance is found.

Type Parameters

T

The type of the instance that this node represents.

FindSingle<T>(IDecorator<IHierarchy<T>>, Func<IHierarchy<T>, bool>)

Returns the only node that match the conditions defined by the function delegate match, or a default value if no node is found; this method throws an exception if more than one node is found.

public static IHierarchy<T> FindSingle<T>(this IDecorator<IHierarchy<T>> decorator, Func<IHierarchy<T>, bool> match)

Parameters

decorator IDecorator<IHierarchy<T>>

The IDecorator{IHierarchy{T}} to extend.

match Func<IHierarchy<T>, bool>

The function delegate that defines the conditions of the nodes to search for.

Returns

IHierarchy<T>

An IHierarchy<T> node that match the conditions defined by the function delegate match, or a default value if no node is found.

Type Parameters

T

The type of the instance that this node represents.

Find<T>(IDecorator<IHierarchy<T>>, Func<IHierarchy<T>, bool>)

Retrieves all nodes that match the conditions defined by the function delegate match.

public static IEnumerable<IHierarchy<T>> Find<T>(this IDecorator<IHierarchy<T>> decorator, Func<IHierarchy<T>, bool> match)

Parameters

decorator IDecorator<IHierarchy<T>>

The IDecorator{IHierarchy{T}} to extend.

match Func<IHierarchy<T>, bool>

The function delegate that defines the conditions of the nodes to search for.

Returns

IEnumerable<IHierarchy<T>>

An IEnumerable<T> sequence containing all nodes that match the conditions defined by the specified predicate, if found.

Type Parameters

T

The type of the instance that this node represents.

FlattenAll<T>(IDecorator<IHierarchy<T>>)

Flattens the entirety of a hierarchical structure representation into an IEnumerable<T> sequence of nodes.

public static IEnumerable<IHierarchy<T>> FlattenAll<T>(this IDecorator<IHierarchy<T>> decorator)

Parameters

decorator IDecorator<IHierarchy<T>>

The IDecorator{IHierarchy{T}} to extend.

Returns

IEnumerable<IHierarchy<T>>

An IEnumerable<T> sequence of IHierarchy<T> all nodes represented by the hierarchical structure.

Type Parameters

T

The type of the instance represented by the specified decorator in the hierarchical structure.

Exceptions

ArgumentNullException

decorator is null.

NodeAt<T>(IDecorator<IHierarchy<T>>, int)

Returns the node at the specified index of a hierarchical structure.

public static IHierarchy<T> NodeAt<T>(this IDecorator<IHierarchy<T>> decorator, int index)

Parameters

decorator IDecorator<IHierarchy<T>>

The IDecorator{IHierarchy{T}} to extend.

index int

The zero-based index at which a node should be retrieved in the hierarchical structure.

Returns

IHierarchy<T>

The node at the specified index in the hierarchical structure.

Type Parameters

T

The type of the instance represented by the specified decorator in the hierarchical structure.

Exceptions

ArgumentNullException

decorator is null.

ArgumentOutOfRangeException

index is less than zero - or - index exceeded the count of nodes in the hierarchical structure.

ReplaceAll<T>(IDecorator<IEnumerable<IHierarchy<T>>>, Action<IHierarchy<T>, T>)

Replace all instances of the decorator with a replacer delegate.

public static void ReplaceAll<T>(this IDecorator<IEnumerable<IHierarchy<T>>> decorator, Action<IHierarchy<T>, T> replacer)

Parameters

decorator IDecorator<IEnumerable<IHierarchy<T>>>

The IDecorator{IEnumerable{IHierarchy{T}}} to extend.

replacer Action<IHierarchy<T>, T>

The delegate that will replace all wrapped instances of the decorator.

Type Parameters

T

The type of the instance that these nodes represents.

Replace<T>(IDecorator<IHierarchy<T>>, Action<IHierarchy<T>, T>)

Replace the instance of the decorator with a replacer delegate.

public static void Replace<T>(this IDecorator<IHierarchy<T>> decorator, Action<IHierarchy<T>, T> replacer)

Parameters

decorator IDecorator<IHierarchy<T>>

The IDecorator{IHierarchy{T}} to extend.

replacer Action<IHierarchy<T>, T>

The delegate that will replace the wrapped instance of the decorator.

Type Parameters

T

The type of the instance that this node represents.

Root<T>(IDecorator<IHierarchy<T>>)

Returns the root node of the specified decorator in the hierarchical structure.

public static IHierarchy<T> Root<T>(this IDecorator<IHierarchy<T>> decorator)

Parameters

decorator IDecorator<IHierarchy<T>>

The IDecorator{IHierarchy{T}} to extend.

Returns

IHierarchy<T>

An IHierarchy<T> node that represents the root of the specified decorator.

Type Parameters

T

The type of the instance represented by the specified decorator in the hierarchical structure.

Exceptions

ArgumentNullException

decorator is null.

SiblingsAndSelfAt<T>(IDecorator<IHierarchy<T>>, int)

Gets all siblings and self after the current decorator in the hierarchical structure.

public static IEnumerable<IHierarchy<T>> SiblingsAndSelfAt<T>(this IDecorator<IHierarchy<T>> decorator, int depth)

Parameters

decorator IDecorator<IHierarchy<T>>

The IDecorator{IHierarchy{T}} to extend.

depth int

The depth in the hierarchical structure from where to locate the siblings and self nodes.

Returns

IEnumerable<IHierarchy<T>>

An IEnumerable<T> sequence equal to the siblings and self of the specified decorator.

Type Parameters

T

The type of the instance represented by the specified decorator in the hierarchical structure.

Exceptions

ArgumentNullException

decorator is null.

ArgumentOutOfRangeException

depth is less than zero.

SiblingsAndSelf<T>(IDecorator<IHierarchy<T>>)

Gets all siblings and self after the current decorator in the hierarchical structure.

public static IEnumerable<IHierarchy<T>> SiblingsAndSelf<T>(this IDecorator<IHierarchy<T>> decorator)

Parameters

decorator IDecorator<IHierarchy<T>>

The IDecorator{IHierarchy{T}} to extend.

Returns

IEnumerable<IHierarchy<T>>

An IEnumerable<T> sequence equal to the siblings and self of the specified decorator.

Type Parameters

T

The type of the instance represented by the specified decorator in the hierarchical structure.

Exceptions

ArgumentNullException

decorator is null.

UseCollection(IDecorator<IHierarchy<DataPair>>, Type)

A formatter implementation that resolves a ICollection.

public static ICollection UseCollection(this IDecorator<IHierarchy<DataPair>> decorator, Type valueType)

Parameters

decorator IDecorator<IHierarchy<DataPair>>

The IDecorator{IHierarchy{DataPair}} to extend.

valueType Type

The type of the objects in the collection.

Returns

ICollection

A ICollection of valueType from the enclosed IHierarchy{DataPair} of the decorator.

Exceptions

ArgumentNullException

decorator cannot be null.

UseConvertibleFormatter(IDecorator<IHierarchy<DataPair>>)

A formatter implementation that resolves a IConvertible.

public static IConvertible UseConvertibleFormatter(this IDecorator<IHierarchy<DataPair>> decorator)

Parameters

decorator IDecorator<IHierarchy<DataPair>>

The IDecorator{IHierarchy{DataPair}} to extend.

Returns

IConvertible

A IConvertible from the enclosed IHierarchy{DataPair} of the decorator.

Exceptions

ArgumentNullException

decorator cannot be null.

UseDateTimeFormatter(IDecorator<IHierarchy<DataPair>>)

A formatter implementation that resolves a DateTime.

public static DateTime UseDateTimeFormatter(this IDecorator<IHierarchy<DataPair>> decorator)

Parameters

decorator IDecorator<IHierarchy<DataPair>>

The IDecorator{IHierarchy{DataPair}} to extend.

Returns

DateTime

A DateTime from the enclosed IHierarchy{DataPair} of the decorator.

UseDecimalFormatter(IDecorator<IHierarchy<DataPair>>)

A formatter implementation that resolves a decimal.

public static decimal UseDecimalFormatter(this IDecorator<IHierarchy<DataPair>> decorator)

Parameters

decorator IDecorator<IHierarchy<DataPair>>

The IDecorator{IHierarchy{DataPair}} to extend.

Returns

decimal

A decimal from the enclosed IHierarchy{DataPair} of the decorator.

Exceptions

ArgumentNullException

decorator cannot be null.

UseDictionary(IDecorator<IHierarchy<DataPair>>, Type[])

A formatter implementation that resolves a IDictionary.

public static IDictionary UseDictionary(this IDecorator<IHierarchy<DataPair>> decorator, Type[] valueTypes)

Parameters

decorator IDecorator<IHierarchy<DataPair>>

The IDecorator{IHierarchy{DataPair}} to extend.

valueTypes Type[]

The value types that forms a KeyValuePair<TKey, TValue>.

Returns

IDictionary

A IDictionary with KeyValuePair<TKey, TValue> of valueTypes from the enclosed IHierarchy{DataPair} of the decorator.

Exceptions

ArgumentNullException

decorator cannot be null.

UseGuidFormatter(IDecorator<IHierarchy<DataPair>>)

A formatter implementation that resolves a Guid.

public static Guid UseGuidFormatter(this IDecorator<IHierarchy<DataPair>> decorator)

Parameters

decorator IDecorator<IHierarchy<DataPair>>

The IDecorator{IHierarchy{DataPair}} to extend.

Returns

Guid

A Guid from the enclosed IHierarchy{DataPair} of the decorator.

Exceptions

ArgumentNullException

decorator cannot be null.

UseStringFormatter(IDecorator<IHierarchy<DataPair>>)

A formatter implementation that resolves a string.

public static string UseStringFormatter(this IDecorator<IHierarchy<DataPair>> decorator)

Parameters

decorator IDecorator<IHierarchy<DataPair>>

The IDecorator{IHierarchy{DataPair}} to extend.

Returns

string

A string from the enclosed IHierarchy{DataPair} of the decorator.

Exceptions

ArgumentNullException

decorator cannot be null.

UseUriFormatter(IDecorator<IHierarchy<DataPair>>)

A formatter implementation that resolves a Uri.

public static Uri UseUriFormatter(this IDecorator<IHierarchy<DataPair>> decorator)

Parameters

decorator IDecorator<IHierarchy<DataPair>>

The IDecorator{IHierarchy{DataPair}} to extend.

Returns

Uri

A Uri from the enclosed IHierarchy{DataPair} of the decorator.

Exceptions

ArgumentNullException

decorator cannot be null.

See Also

IDecorator<T>

Decorator<T>