Garden

public static class Garden
A utility class for building various kinds of trees and twigs.

Fields

LeafSymbol

#
public const string LeafSymbol = "🍃"
The unicode emoji for Leaf<T>

MetaSymbol

#
public const string MetaSymbol = "💬"
The unicode emoji for MetaData

PearSymbol

#
public const string PearSymbol = "🍐"
The unicode emoji for IPear.

TreeSymbol

#
public const string TreeSymbol = "🌳"
The unicode emoji for ITree.

TwigSymbol

#
public const string TwigSymbol = "🌿"
The unicode emoji for ITwig.

Methods

ApplyExpression

#
public static ITree ApplyExpression(ITree tree, Expression expression, Resolver resolver, out string[] errors)
Apply an expression to an entire tree.
Parameters:
tree (ITree)Tree to modify.
expression (Expression)Expression to apply.
resolver (Resolver)A resolver for undefined expression variables.
errors (out string[])Array of errors encountered during application.
Returns: Modified tree.

ConcatenateITwigs

#
public static ITwig ConcatenateITwigs(IReadOnlyList<ITwig> twigs)
Concatenate an arbitrary number of twigs into a single twig in a single pass, avoiding the quadratic allocation cost of repeated pairwise merging.
Parameters:
twigs (IReadOnlyList<ITwig>)Twigs to concatenate in order. Null or empty twigs are skipped.

IPear

#
public static IPear IPear(object value, MetaData meta = null)
Create a pear for a value with optional meta data.
Parameters:
value (object)
meta (MetaData = null)

ITreeEmpty

#
public static ITree ITreeEmpty()
Gets a non-constraint empty tree.

ITreeFromArrays

#
public static ITree ITreeFromArrays(Array items, MetaData[][] metas = null, bool[][] nulls = null)
Create a tree from a nested array of values, with optional meta data and null flags.
Parameters:
items (Array)Jagged array of item values.
metas (MetaData[][] = null)If specified, a 1:1 bijection of items containing meta data.
nulls (bool[][] = null)If specified, a 1:1 bijection of items containing null flags. If the type constraint specifies a nullable type, the nulls array is always ignored."/>

ITreeFromArrays

#
public static ITree ITreeFromArrays(Paths paths, Array items, MetaData[][] metas = null, bool[][] nulls = null)
Create a tree from a nested array of values, with optional meta data and null flags.
Parameters:
paths (Paths)A top-level bijection of the 'items' array specifying the path for each twig. It is possible to only specify a single path as well, in which case it will automatically be incremented for each required twig.
items (Array)Jagged array of item values.
metas (MetaData[][] = null)If specified, a 1:1 bijection of items containing meta data.
nulls (bool[][] = null)If specified, a 1:1 bijection of items containing null flags. If the type constraint specifies a nullable type, the nulls array is always ignored."/>

ITreeFromILeaves

#
public static ITree ITreeFromILeaves(IEnumerable<ILeaf> leaves)
Recreate a tree from a collection of leaves.
Parameters:
leaves (IEnumerable<ILeaf>)Leaves for tree.

ITreeFromIPears

#
public static ITree ITreeFromIPears(IEnumerable<IPear> pears)
Create a tree with a single twig using a default path.
Parameters:
pears (IEnumerable<IPear>)

ITreeFromIPears

#
public static ITree ITreeFromIPears(Path path, IEnumerable<IPear> pears)
Create a tree with a single twig using a custom path.
Parameters:
path (Path)
pears (IEnumerable<IPear>)

ITreeFromITwigs

#
public static ITree ITreeFromITwigs(IEnumerable<ITwig> twigs)
Create a tree from a collection of twigs.
Parameters:
twigs (IEnumerable<ITwig>)Twig collection.

ITreeFromITwigs

#
public static ITree ITreeFromITwigs(Paths paths, IEnumerable<ITwig> twigs)
Create a tree from a matching collection of paths and twigs.
Parameters:
paths (Paths)Path collection.
twigs (IEnumerable<ITwig>)Twig collection.

ITreeFromList

#
public static ITree ITreeFromList(IEnumerable items, IEnumerable<MetaData> metas = null, IEnumerable<bool> nulls = null)
Create a tree with a single twig using a default path.
Parameters:
items (IEnumerable)
metas (IEnumerable<MetaData> = null)
nulls (IEnumerable<bool> = null)

ITwigEmpty

#
public static ITwig ITwigEmpty()
Gets a non-constraint empty twig.

ITwigFromList

#
public static ITwig ITwigFromList(IEnumerable items, IEnumerable<MetaData> metas = null, IEnumerable<bool> nulls = null)
Create a twig based on a collection of values.
Parameters:
items (IEnumerable)
metas (IEnumerable<MetaData> = null)
nulls (IEnumerable<bool> = null)

ITwigFromOneValue

#
public static ITwig ITwigFromOneValue(object item)
Create a twig based on a single value. If the value provided implements IPear, it will be handled accordingly.
Parameters:
item (object)

ITwigFromPears

#
public static ITwig ITwigFromPears(IEnumerable<IPear> pears)
Create a twig from a collection of pears.
Parameters:
pears (IEnumerable<IPear>)

ITwigNulls

#
public static ITwig ITwigNulls(Type type, int count)
Create a twig of the given type containing the given amount of nulls.
Parameters:
type (Type)
count (int)

MergeITrees

#
public static ITree MergeITrees(params ITree[] trees)
Merge two or more trees of potentially different types.
Parameters:
trees (params ITree[])Trees to merge.

MergeTrees<T>

#
public static Tree<T> MergeTrees<T>(params Tree<T>[] trees)
Merge two or more trees of the same type.
Parameters:
trees (params Tree<T>[])Trees to merge.

MergeTwigs

#
public static ITwig MergeTwigs(params ITwig[] twigs)
Merge a set of twigs into one.
Parameters:
twigs (params ITwig[])

MergeTwigs<T>

#
public static Twig<T> MergeTwigs<T>(params Twig<T>[] twigs)
Merge a set of twigs into one.
Parameters:
twigs (params Twig<T>[])

PairWiseOp

#
public static ITree PairWiseOp(ITree a, ITree b, Func<dynamic, dynamic, dynamic> process, CancellationToken token = default(CancellationToken))
Perform a regular (i.e. 'longest list') operation on all value pairs in two trees. This method returns the most constrained type of Tree<T>, regardless of the specific type on which this method was invoked.
Parameters:
a (ITree)First tree.
b (ITree)Second tree.
process (Func<dynamic, dynamic, dynamic>)Process method to apply to all pairs.
token (CancellationToken = null)Cancellation token.
Returns: Tree with combined and processed values.

PairWiseOp<TA, TB, TOut>

#
public static Tree<TOut> PairWiseOp<TA, TB, TOut>(Tree<TA> a, Tree<TB> b, Func<TA, TB, TOut> process, CancellationToken token = default(CancellationToken))
Perform a regular (i.e. 'longest list') operation on all value pairs in two trees.
Parameters:
a (Tree<TA>)First tree.
b (Tree<TB>)Second tree.
process (Func<TA, TB, TOut>)Process method to apply to all pairs.
token (CancellationToken = null)Cancellatio token for the process.
Returns: Tree with combined and processed values.

Pear<T>

#
public static Pear<T> Pear<T>(T value, MetaData meta = null)
Create a pear for a value with optional meta data.
Parameters:
value (T)
meta (MetaData = null)

PearComparison

#
public static int PearComparison(IPear a, IPear b, bool includeMetaData)
Test two pears for equality.
Parameters:
a (IPear)Pear to compare to.
b (IPear)
includeMetaData (bool)If true, meta data equality will be taken into consideration.

PearEquality

#
public static bool PearEquality(IPear a, IPear b, bool includeMetaData)
Test two pears for equality.
Parameters:
a (IPear)Pear to compare to.
b (IPear)
includeMetaData (bool)If true, meta data equality will be taken into consideration.

PearWiseOp

#
public static ITree PearWiseOp(ITree tree, Func<IPear, IPear> process, CancellationToken token = default(CancellationToken))
Create a new tree by performing an operation on all the pairs on another tree.
Parameters:
tree (ITree)Tree to operate on.
process (Func<IPear, IPear>)Operation.
token (CancellationToken = null)Cancellation token.
Returns: Tree with modified pears.

PearWiseOp<T>

#
public static Tree<T> PearWiseOp<T>(Tree<T> tree, Func<Pear<T>, Pear<T>> process, CancellationToken token = default(CancellationToken))
Create a new tree by performing an operation on all the pairs on another tree.
Parameters:
tree (Tree<T>)Tree to operate on.
process (Func<Pear<T>, Pear<T>>)Operation.
token (CancellationToken = null)Cancellation token.
Returns: Tree with modified pears.

ReadITree

#
public static ITree ReadITree(IReader reader)
Deserialise a tree.
Parameters:
reader (IReader)Reader object.

ReadITwig

#
public static ITwig ReadITwig(IReader reader)
Deserialise a twig.
Parameters:
reader (IReader)Reader object to deserialise from.
Returns: Deserialised twig.

ReadPear

#
public static IPear ReadPear(IReader reader)
Deserialise a pear.
Parameters:
reader (IReader)Reader to deserialise from.

ReadPear<T>

#
public static Pear<T> ReadPear<T>(IReader reader)
Deserialise a pear.
Parameters:
reader (IReader)Reader to deserialise from.
Returns: Returns a pear on success, or null on failure.

ReadTree<T>

#
public static Tree<T> ReadTree<T>(IReader reader)
Deserialise a tree.
Parameters:
reader (IReader)Reader object.

ReadTwig<T>

#
public static Twig<T> ReadTwig<T>(IReader reader)
Deserialise a twig.
Parameters:
reader (IReader)Reader object to deserialise from.
Returns: Deserialised twig.

RemoveMeta

#
public static ITree RemoveMeta(ITree tree, params MetaName[] names)
Remove all occurences of a collection of meta names from a tree.
Parameters:
tree (ITree)Tree to operate on.
names (params MetaName[])Meta names to remove.

RemoveMeta<T>

#
public static Tree<T> RemoveMeta<T>(Tree<T> tree, params MetaName[] names)
Remove all occurences of a specific meta value from a tree.
Parameters:
tree (Tree<T>)Tree to operate on.
names (params MetaName[])Meta names to remove.

TreeEmpty<T>

#
public static Tree<T> TreeEmpty<T>()
Gets the empty tree for a specific type constraint.

TreeFromArrays<T>

#
public static Tree<T> TreeFromArrays<T>(Paths paths, T[][] items, MetaData[][] metas = null, bool[][] nulls = null)
Create a tree from a nested array of values, with optional meta data and null flags.
Parameters:
paths (Paths)A top-level bijection of the 'items' array specifying the path for each twig. It is possible to only specify a single path as well, in which case it will automatically be incremented for each required twig.
items (T[][])Jagged array of item values.
metas (MetaData[][] = null)If specified, a 1:1 bijection of items containing meta data.
nulls (bool[][] = null)If specified, a 1:1 bijection of items containing null flags. If the type constraint specifies a nullable type, the nulls array is always ignored."/>

TreeFromArrays<T>

#
public static Tree<T> TreeFromArrays<T>(T[][] items, MetaData[][] metas = null, bool[][] nulls = null)
Create a tree from a nested array of values, with optional meta data and null flags.
Parameters:
items (T[][])Jagged array of item values.
metas (MetaData[][] = null)If specified, a 1:1 bijection of items containing meta data.
nulls (bool[][] = null)If specified, a 1:1 bijection of items containing null flags. If the type constraint specifies a nullable type, the nulls array is always ignored."/>

TreeFromLeaves<T>

#
public static Tree<T> TreeFromLeaves<T>(IEnumerable<Leaf<T>> leaves)
Recreate a tree from a collection of leaves.
Parameters:
leaves (IEnumerable<Leaf<T>>)Leaves for tree.

TreeFromList<T>

#
public static Tree<T> TreeFromList<T>(IEnumerable<T> items, IEnumerable<MetaData> metas = null, IEnumerable<bool> nulls = null)
Create a tree with a single twig using a default path.
Parameters:
items (IEnumerable<T>)
metas (IEnumerable<MetaData> = null)
nulls (IEnumerable<bool> = null)

TreeFromList<T>

#
public static Tree<T> TreeFromList<T>(Path path, IEnumerable<T> items, IEnumerable<MetaData> metas = null, IEnumerable<bool> nulls = null)
Create a tree with a single twig using a custom path.
Parameters:
path (Path)
items (IEnumerable<T>)
metas (IEnumerable<MetaData> = null)
nulls (IEnumerable<bool> = null)

TreeFromPears<T>

#
public static Tree<T> TreeFromPears<T>(IEnumerable<Pear<T>> pears)
Createa tree with a single twig using a default path.
Parameters:
pears (IEnumerable<Pear<T>>)

TreeFromPears<T>

#
public static Tree<T> TreeFromPears<T>(Path path, IEnumerable<Pear<T>> pears)
Createa tree with a single twig using a custom path.
Parameters:
path (Path)
pears (IEnumerable<Pear<T>>)

TreeFromTwigs<T>

#
public static Tree<T> TreeFromTwigs<T>(IEnumerable<Twig<T>> twigs)
Create a tree from a collection of twigs.
Parameters:
twigs (IEnumerable<Twig<T>>)

TreeFromTwigs<T>

#
public static Tree<T> TreeFromTwigs<T>(Paths paths, IEnumerable<Twig<T>> twigs)
Create a tree from a collection of paths and twigs.
Parameters:
paths (Paths)
twigs (IEnumerable<Twig<T>>)

TreeFromUnchecked<T>

#
public static Tree<T> TreeFromUnchecked<T>(IEnumerable<Path> paths, IEnumerable<Twig<T>> twigs)
Create a tree from unchecked paths and twigs. Paths need not be sorted or unique. Twigs associated with identical paths will be merged.
Parameters:
paths (IEnumerable<Path>)
twigs (IEnumerable<Twig<T>>)

TryCast<T>

#
public static bool TryCast<T>(Array source, out T[] target)
Attempt to cast an array of vague providence to a specific type. This will only work if the source array *is* of the correct type, or if all its elements are compatible with the target type.
Parameters:
source (Array)
target (out T[])

TryCast<T>

#
public static bool TryCast<T>(ITwig source, out Twig<T> target)
Attempt to cast a twig of vague providence to a specific type. This will only work if the source twig *is* of the correct type, or if all its elements are compatible with the target type.
Parameters:
source (ITwig)
target (out Twig<T>)

TryCreateDeepCopy

#
public static ITree TryCreateDeepCopy(ITree tree)
Attempt to create a copy of a tree by duplicating all the values. Values which are value types or otherwise known to be immutable will not be copied. Copying to mutable reference types will occur via type assistants. There is no guarantee that duplication was successful in all cases.
Parameters:
tree (ITree)
Returns: A new tree with duplicated values.

TwigEmpty<T>

#
public static Twig<T> TwigEmpty<T>()
Gets the empty twig for a specific type constraint.

TwigFromList<T>

#
public static Twig<T> TwigFromList<T>(IEnumerable<T> items, IEnumerable<MetaData> metas = null, IEnumerable<bool> nulls = null)
Create a twig based on a collection of values.
Parameters:
items (IEnumerable<T>)
metas (IEnumerable<MetaData> = null)
nulls (IEnumerable<bool> = null)

TwigFromOneValue<T>

#
public static Twig<T> TwigFromOneValue<T>(Pear<T> pear)
Create a twig based on a single value.
Parameters:
pear (Pear<T>)

TwigFromOneValue<T>

#
public static Twig<T> TwigFromOneValue<T>(T item)
Create a twig based on a single value.
Parameters:
item (T)

TwigFromPears<T>

#
public static Twig<T> TwigFromPears<T>(IEnumerable<Pear<T>> pears)
Create a twig from a collection of pears.
Parameters:
pears (IEnumerable<Pear<T>>)

TwigFromValues<T>

#
public static Twig<T> TwigFromValues<T>(params T[] items)
Create a twig based on a collection of values. No meta data or nulls can be set.
Parameters:
items (params T[])

TwigNulls<T>

#
public static Twig<T> TwigNulls<T>(int count)
Create a twig which contains only null values.
Parameters:
count (int)Amount of nulls.
Returns: Twig with only nulls.

WriteITree

#
public static (int successes, int failures) WriteITree(IWriter writer, ITree tree)
Serialise an ITree.
Parameters:
writer (IWriter)Writer object to serialise to.
tree (ITree)Tree to serialise.
Returns: Number of successful and failed writes. Ideally, the number of successes equals the tree item count while the failures equal zero. Nulls are not counted as either successes or failures.

WriteITwig

#
public static (int successes, int failures) WriteITwig(IWriter writer, ITwig twig)
Serialise a twig.
Parameters:
writer (IWriter)Writer object to serialise to.
twig (ITwig)Twig to serialise.
Returns: Number of successful and failed writes. Ideally, the number of successes equals the twig item count while the failures equal zero. Nulls are not counted as either successes or failures.

WritePear

#
public static bool WritePear(IWriter writer, IPear pear)
Serialise a pear.
Parameters:
writer (IWriter)Object to write to.
pear (IPear)Pear to serialise.
Returns: True on success.

WriteTree<T>

#
public static (int successes, int failures) WriteTree<T>(IWriter writer, Tree<T> tree)
Serialise a Tree.
Parameters:
writer (IWriter)Writer object to serialise to.
tree (Tree<T>)Tree to serialise.
Returns: Number of successful and failed writes. Ideally, the number of successes equals the tree item count while the failures equal zero. Nulls are not counted as either successes or failures.

WriteTwig<T>

#
public static (int successes, int failures) WriteTwig<T>(IWriter writer, Twig<T> twig)
Serialise a twig.
Parameters:
writer (IWriter)Writer object to serialise to.
twig (Twig<T>)Twig to serialise.
Returns: Number of successful and failed writes. Ideally, the number of successes equals the twig item count while the failures equal zero. Nulls are not counted as either successes or failures.