DataTree<T>

Implements basic Grasshopper Data Tree functionality in an easy-to-use class. This class is used primarily in Scripting components. If you're using the Grasshopper SDK you should consider using the GH_Structure<T> class instead.

Type parameters:

T	Data type of this class.

Constructors

DataTree

public DataTree()

Default constructor, create an empty data tree.

DataTree

public DataTree(DataTree<T> other, DuplicateT copyDelegate)

Create a true duplicate of another data tree.

Parameters:

other (DataTree<T>)	Tree to duplicate
copyDelegate (DataTree<T>.DuplicateT)	Delegate function used to duplicate individual items.

DataTree

public DataTree(DataTree<T> other)

Create a shallow duplicate of another data tree. This means it will create a new tree that contains the same items.

Parameters:

other (DataTree<T>)

Tree to duplicate

DataTree

public DataTree(IEnumerable<T> data, GH_Path root = null)

Create a tree with a single branch

Parameters:

data (IEnumerable<T>)	Data to append to the tree.
root (GH_Path = null)	Branch path of first branch. If Null, the default path is used.

Properties

BranchCount

public int BranchCount { get; }

Gets the number of branches defined in this tree.

Branches

public IList<List<T>> Branches { get; }

Gets a list of all the data-arrays in this tree

DataCount

public int DataCount { get; }

Gets the total number of data items (including nulls) stored in all branches.

Paths

public IList<GH_Path> Paths { get; }

Gets a list of all the branch paths in this tree.

TopologyDescription

public string TopologyDescription { get; }

Gets a description of the topology of the tree. Useful for debugging purposes.

Indexers

Item

public T this[GH_Path path, int index] { get; set; }

Gets or set the data item at the specified path and index.

Parameters:

path (GH_Path)	Path of the data branch to retrieve. Path must be defined in the tree.
index (int)	Index of item to retrieve. Index must be defined in the branch.

Exceptions:

NullReferenceException	Thrown if the path doesn't exist.
IndexOutOfRangeException	Thrown if the index does not exist within the path list.

Methods

Add

public void Add(T data, GH_Path path)

Add (append) a data item to the specified branch in the tree. If the branch doesn't exist yet, it will be created.

Parameters:

data (T)	Data to append.
path (GH_Path)	Branch path to append to.

Add

public void Add(T data)

Add (append) a data item to the last branch in the tree. If no branches exist yet, a new one will be created with [path = {0}]

Parameters:

data (T)

Data to append.

AddRange

public void AddRange(IEnumerable<T> data, GH_Path path)

Add (append) a list of data items to the specified branch in the tree. If the branch doesn't exist yet, it will be created.

Parameters:

data (IEnumerable<T>)	Data to append.
path (GH_Path)	Data path.

AddRange

public void AddRange(IEnumerable<T> data)

Add (append) a list of data items to the last branch in the tree. If no branch exists yet, a new one will be created.

Parameters:

data (IEnumerable<T>)

Data to append

AllData

public List<T> AllData()

Collects all data in the tree in a single list. Does not alter the topology of this tree.

Returns: A linear list containing all data items in all branches.

Branch

public List<T> Branch(GH_Path path)

Gets the list of data which belongs to a given Branch path.

Parameters:

path (GH_Path)

Data path to retrieve.

Branch

public List<T> Branch(int index)

Gets the list of data which belongs to the branch path at the given index.

Parameters:

index (int)

Index of data to retrieve.

Exceptions:

IndexOutOfRangeException

Thrown if the index does not represent a valid path.

Branch

public List<T> Branch(params int[] path)

Gets the list of data which belongs to a given Branch path.

Parameters:

path (params int[])

Data path to retrieve.

Clear

public void Clear()

Clears the entire tree.

ClearData

public void ClearData()

Removes all data from all branches without affecting the tree topology.

EnsurePath

public List<T> EnsurePath(GH_Path path)

Create a new branch with the specified path if it doesn't already exists.

Parameters:

path (GH_Path)

Path of the branch to ensure.

Returns: The list that belongs to the specified path.

EnsurePath

public List<T> EnsurePath(params int[] path)

Create a new branch with the specified path if it doesn't already exists.

Parameters:

path (params int[])

Path of the branch to ensure.

Returns: The list that belongs to the specified path.

Flatten

public void Flatten(GH_Path flatten_path = null)

Flattens the entire tree into a single path.

Parameters:

flatten_path (GH_Path = null)

The path of the flattened data. If null, the path will be {0}

Graft

public void Graft(bool skip_nulls = false)

Graft all paths in this tree. "Grafting" means appending a new branch for every item in an existing branch.

Parameters:

skip_nulls (bool = false)

If true, null items in the grafted path will not be included in the new tree.

Graft

public void Graft(GH_Path path, bool skip_nulls = false)

Graft a single path in the tree. "Grafting" means appending a new branch for every item in an existing branch.

Parameters:

path (GH_Path)	Path to graft.
skip_nulls (bool = false)	If true, null items in the grafted path will not be included in the new tree.

Insert

public void Insert(T data, GH_Path path, int index)

Insert a data item to the specified branch in the tree. If the branch doesn't exist yet, it will be created.

Parameters:

data (T)	Data to insert.
path (GH_Path)	Branch path to insert into.
index (int)	Insertion index.

ItemExists

public bool ItemExists(GH_Path path, int index)

Test if the specified path + item index are defined inside the tree.

Parameters:

path (GH_Path)	Path to test for.
index (int)	Item index to test.

Returns: True if the specified path exists and contains the specified index.

MergeStructure

public void MergeStructure(IGH_Structure structure, IGH_TypeHint hint)

Merge a Grasshopper parameter structure into this DataTree. Expert user function. If you don't know what a GH_Structure(Of T) is you don't have to worry about this method.

Remarks: Expert user function, don't go near GH_Structures if you're not intimately familiar with the Grasshopper SDK.

Parameters:

structure (IGH_Structure)	Parameter data structure to merge.
hint (IGH_TypeHint)	Type hint converter to use during merging.

MergeTree

public void MergeTree(DataTree<T> other)

Merges two trees together. Data inside similar branches will be merged into single lists and unique paths will be appended. The other tree will not be altered, so beware that data is now shared among both trees.

Parameters:

other (DataTree<T>)

Tree to merge with.

Exceptions:

ArgumentNullException

Thrown if other is a null reference.

MergeWithParameter

public bool MergeWithParameter(IGH_Param param)

Utility function for assigning Script Data Trees to output parameters. Expert user function, don't worry your pretty little head about this one.

Parameters:

param (IGH_Param)

Parameter to merge with.

Returns: True on success, false on failure.

Implements: MergeWithParameter

Path

public GH_Path Path(int index)

Gets the data path at the specified index.

Parameters:

index (int)

Index of path to retrieve.

Exceptions:

IndexOutOfRangeException

Thrown if the index does not represent a valid path.

PathExists

public bool PathExists(GH_Path path)

Test if the specified path is already defined inside the tree.

Parameters:

path (GH_Path)

The branch path to search for

Returns: True if the path already exists, false if it doesn't.

PathExists

public bool PathExists(params int[] path)

Test if the specified path is already defined inside the tree.

Parameters:

path (params int[])

The branch path to search for.

Returns: True if the path already exists, false if it doesn't.

RemovePath

public void RemovePath(GH_Path path)

Removes a path and all associated data from the structure. If the path doesn't exist, nothing will happen.

Parameters:

path (GH_Path)

Path to remove.

RemovePath

public void RemovePath(params int[] path)

Removes a path and all associated data from the structure. If the path doesn't exist, nothing will happen.

Parameters:

path (params int[])

Path to remove.

RenumberPaths

public void RenumberPaths()

Renumber all paths in this data tree, using a single incrementing path index.

RenumberPaths

public void RenumberPaths(string mask)

Renumber all paths in this data tree, using a single incrementing path index.

Parameters:

mask (string)

String formatting mask for paths. Use semi-colons for path index separators and "{i}" as a path index placeholder. Examples:

"{i}" -> {i}

"0;{i}" -> {0;i}

"{i};0;0" -> {i;0;0}

SimplifyPaths

public void SimplifyPaths()

Simplify the branches in this tree by removing all identical path entries. The length of the shortest path will be indicative of the similarity search depth. If this tree only contains a single branch, the branch wil be simplified to its last index.

ToString

public override string ToString()

Creates a brief description of the tree.

Returns: A String representing the current state of the data tree.

Overrides: Object.ToString

TrimExcess

public void TrimExcess()

Trims the excess allocated memory in all branches