Path

References

[IoId("00000000-4edf-4b84-8cc9-4112a11949d4")] public sealed class Path : IComparable<Path>, IEquatable<Path>, IStorable

Paths are used to identify twigs in data trees. Paths are ordered, immutable collections of non-negative integers.

Constructors

Path

public Path(IEnumerable<int> pathElements)

Create a new instance of TreePath based on a collection of indices.

Parameters:

pathElements (IEnumerable<int>)

Indices that define this path.

Path

public Path(IReader reader)

Restore this path from an IO archive.

Parameters:

reader (IReader)

Reader object.

Path

public Path(params int[] pathElements)

Create a new instance of TreePath based on a collection of indices.

Parameters:

pathElements (params int[])

Indices that define this path.

Fields

Zero

public static readonly Path Zero

Gets the single element path with a value of zero: {0}

ZeroZero

public static readonly Path ZeroZero

Gets the double element path with two zeroes: {0, 0}

Properties

LastElement

public int LastElement { get; }

Gets the last element in the path.

Length

public int Length { get; }

Gets the number of elements in this path.

OnlyZeroes

public bool OnlyZeroes { get; }

Gets whether this path contains only zeroes.

Indexers

this[]

public int this[int index] { get; }

Gets the path element at the given index.

Parameters:

index (int)

Index of element to retrieve.

Returns: The element at the given index.

Methods

AllUnique

public static bool AllUnique(IEnumerable<Path> paths)

Check whether a collection of paths has any collisions.

Parameters:

paths (IEnumerable<Path>)

Paths to test.

Returns: True if all paths are unique.

AppendElement

public Path AppendElement(int element)

Create a new path by appending a new rule to this path.

Parameters:

element (int)

Element to append.

Returns: A new path.

CompareTo

public int CompareTo(Path other)

Compare this path to another one.

Parameters:

other (Path)

Path to compare to.

Returns: Sort order for these two paths.

Contains

public bool Contains(params int[] elements)

Test to see if this path contains the specified elements.

Parameters:

elements (params int[])

Elements to test.

Returns: True if the path contains the specified elements, false if it doesn't.

CountElements

public int CountElements(int minimumValue, int maximumValue)

Count the number of times this path contains elements in the given range.

Parameters:

minimumValue (int)	Inclusive lower limit.
maximumValue (int)	Inclusive upper limit.

Returns: Number of elements in the given range.

CountElements

public int CountElements(int value)

Count the number of times this path contains the given element.

Parameters:

value (int)

Value to test.

Returns: Number of occurences of value.

CreateFromZeroes

public static Path CreateFromZeroes(int length)

Create a path filled with zeroes of a specific length.

Parameters:

length (int)

EndsWith

public bool EndsWith(params int[] elements)

Test to see if this path ends with the specified elements.

Parameters:

elements (params int[])

Elements to test.

Returns: True if the path ends with the specified elements, false if it doesn't.

Equals

public override bool Equals(object obj)

Test this path for equality with another path.

Parameters:

obj (object)

Object to compare with.

Returns: True if this path is equal to the other path.

Overrides: Object.Equals

Equals

public bool Equals(Path other)

Implementation of the IEquatable interface for Path.

Parameters:

other (Path)

Path to equate.

Returns: True if this path is equatable with the given path.

EstimateNextPath

public static Path EstimateNextPath(IEnumerable<Path> paths)

Try and estimate the most sensible addition to a list of paths.

Parameters:

paths (IEnumerable<Path>)

Collection of paths.

Returns: Path that seems to be a sensible continuation of the collection.

EstimateNextPath

public static Path EstimateNextPath(params Path[] paths)

Try and estimate the most sensible addition to a list of paths.

Parameters:

paths (params Path[])

Collection of paths.

Returns: Path that seems to be a sensible continuation of the collection.

FindReplace

public Path FindReplace(int oldValue, int newValue, out int occurences)

Replace specific elements in this path with other elements.

Parameters:

oldValue (int)	Elements to replace.
newValue (int)	Elements to use instead.
occurences (out int)	Returns the number of replacements made.

Returns: A new path with replaced elements.

FindReplace

public Path FindReplace(int oldValue, int newValue)

Replace specific elements in this path with other elements.

Parameters:

oldValue (int)	Elements to replace.
newValue (int)	Elements to use instead.

Returns: A new path with replaced elements.

FormatPathLikeString

public static string FormatPathLikeString(IEnumerable<string> elements, string pathOpenSymbol, string pathCloseSymbol, string pathSeparatorSymbol)

Format a collection of strings as a path.

Parameters:

elements (IEnumerable<string>)	Path elements to format.
pathOpenSymbol (string)	Text to use as an opening symbol. The recommended symbol is a curly opening brace.
pathCloseSymbol (string)	Text to use as a closing symbol. The recommended symbol is a curly closing brace.
pathSeparatorSymbol (string)	Text to use as a separator symbol. The recommended symbol is a semi-colon.

Returns: Formatted string.

FormatPathLikeString

public static string FormatPathLikeString(IEnumerable<string> elements)

Format a collection of strings as a path.

Parameters:

elements (IEnumerable<string>)

Path elements to format.

Returns: Formatted string.

GetHashCode

public override int GetHashCode()

Compute the hash code for this path.

Returns: The hash of this path.

Overrides: Object.GetHashCode

Increment

public Path Increment()

Increment this path by one. The rightmost non-zero value is incremented, or, if all values are zero, the rightmost value is set to 1.

Returns: Incremented path.

Increment

public Path Increment(int amount)

Increment this path by some constant. The rightmost non-zero value is incremented, or, if all values are zero, the rightmost value is set to 'amount'.

Parameters:

amount (int)

Returns: Incremented path.

IndexOf

public int IndexOf(int startIndex, params int[] elements)

Finds the first occurance of a string of integers within the path.

Parameters:

startIndex (int)	Index to start search from.
elements (params int[])	Elements to test for.

Returns: Index of first occurance, or -1 if the elements do not occur in the path.

IndexOf

public int IndexOf(params int[] elements)

Finds the first occurance of a string of integers within the path.

Parameters:

elements (params int[])

Elements to test for.

Returns: Index of first occurance, or -1 if the elements do not occur in the path.

MakeUnique

public Path MakeUnique(IEnumerable<Path> paths)

Make sure the current path is unique amongst a collection of paths.

Parameters:

paths (IEnumerable<Path>)

Paths to compare to.

Returns: Path which resembles the current path as best as possible but which is unique within the set of given paths.

Offset

public Path Offset(int index, int offset)

Offset an element in this path

Parameters:

index (int)	Element integer to offset.
offset (int)	Offset amount

Returns: A new path.

PadLeft

public Path PadLeft(int length, int element = 0)

Pad a pad on the leading edge until it reaches a certain length.

Parameters:

length (int)	Desired length.
element (int = 0)	Element to insert.

PadRight

public Path PadRight(int length, int element = 0)

Pad a pad on the trailing edge until it reaches a certain length.

Parameters:

length (int)	Desired length.
element (int = 0)	Element to insert.

ParsePattern

public static Result<(Fragments[] pathEntries, Fragments itemEntry)> ParsePattern(string text)

Try and parse a string that may represent some sort of path notation, yielding a view of each element and of the item.

Nothing is said about what the elements contain, so this reads the wildcards and expressions of path mapping as readily as it reads the whole numbers of a data path.

Parameters:

text (string)

Text to parse.

PrependElement

public Path PrependElement(int element)

Create a new path by prepending a new rule to this path.

Parameters:

element (int)

Element to prepend.

Returns: A new path.

RemoveElements

public Path RemoveElements(int minimumValue, int maximumValue)

Remove all elements that are between two extremes.

Parameters:

minimumValue (int)	Inclusive lower limit.
maximumValue (int)	Inclusive upper limit.

Returns: Path without specified elements or {0} if the path ends up being empty.

RemoveElements

public Path RemoveElements(int value)

Remove all elements that have a specific value.

Parameters:

value (int)

Value to remove.

Returns: Path without specified elements or {0} if the path ends up being empty.

RemoveFirstElement

public Path RemoveFirstElement(int count = 1)

Create a new path by removing the first element from this path.

Parameters:

count (int = 1)

Returns: A new path or null if this path only contains a single rule.

RemoveLastElement

public Path RemoveLastElement()

Create a new path by removing the last rule from this path.

Returns: A new path or null if this path only contains a single rule.

Replace

public Path Replace(int index, int element)

Replace a specific element in this path with another.

Parameters:

index (int)
element (int)

ReplaceLastElement

public Path ReplaceLastElement(int newValue)

Replaces the last element in this path with a different value.

Parameters:

newValue (int)

New value.

Returns: Adjusted path.

StartsWith

public bool StartsWith(params int[] elements)

Test to see if this path starts with the specified elements.

Parameters:

elements (params int[])

Elements to test.

Returns: True if the path starts with the specified elements, false if it doesn't.

Store

public void Store(IWriter writer)

Store this path in an IO archive.

Parameters:

writer (IWriter)

Writer object.

Implements: Store

SubPath

public Path SubPath(int start, int length)

Create a path that is a subset of this path.

Parameters:

start (int)	First element index to include.
length (int)	Number of elements to include.

Returns: A new path that is a subset of this path.

SwapElements

public Path SwapElements(int first, int second)

Create a new path by swapping two elements in this path.

Parameters:

first (int)	Index of first element.
second (int)	Index of second element.

Returns: A new path with swapped elements.

ToArray

public int[] ToArray()

Get a copy of the elements in this path.

Returns: An array containing all the elements in this path.

ToString

public override string ToString()

Get the string representation of this path.

Returns: A string describing the path.

Overrides: Object.ToString

ToString

public string ToString(string pathOpenSymbol, string pathCloseSymbol, string pathSeparatorSymbol)

Get the string representation of this path.

Parameters:

pathOpenSymbol (string)	Symbol representing the path start. Curly open bracket is recommended for consistency.
pathCloseSymbol (string)	Symbol representing the path end. Curly close bracket is recommended for consistency.
pathSeparatorSymbol (string)	Symbol to be inserted in between path elements. Semi-colon is recommended for consistency.

Returns: A string representation of this path.

TryParse

public static Result<Path> TryParse(string text)

Parse a string for path notation. This method throws no exceptions, but instead returns error messages via the message argument.

Parameters:

text (string)

Text to parse.

Returns: The path represented by the text or null on failure.

Operators

Operation			Result	Description
int	+	Path	Path	Prepend an item to a path.
Path	+	Path	Path	Combine two paths.
Path	+	int	Path	Append an item to a path.
Path	==	Path	bool	Compare two Path instances for equality.
Path	>	Path	bool	Test whether A is larger than B.
Path	>=	Path	bool	Test whether A is larger than or equal to B.
Path	!=	Path	bool	Compare two Path instances for inequality.
Path	<	Path	bool	Test whether A is smaller than B.
Path	<=	Path	bool	Test whether A is smaller than or equal to B.
Path	*	int	Path	Multiply each index in this path by the given factor.

Convertors

		Result	Description
implicit	Path	int[]	Convert a path to an integer array.
implicit	(int a, int b, int c, int d, int e, int f)	Path	Create a path from a tuple with six elements.
implicit	(int a, int b, int c, int d, int e)	Path	Create a path from a tuple with five elements.
implicit	(int a, int b, int c, int d)	Path	Create a path from a tuple with four elements.
implicit	(int a, int b, int c)	Path	Create a path from a tuple with three elements.
implicit	(int a, int b)	Path	Create a path from a tuple with two elements.
implicit	int	Path	Create a path from a single integer.