View Source MPTree (MPTree v0.2.0)

base tree

Numbers are assigned such that a path can be traced around the tree, taking in every node. The path here starts at root, flowing down the left, around the bottom of the b subtree, then up to the e branch of a, and from there to the other branches of root, before flowing back to root.

Leaf nodes (those with no children) have Left and Right values immediately after each other; f, for example, is 11/12. The parent of a node has a smaller Left and a bigger Right; which can be used to trace up the tree finding parent nodes, until you hit a Left of 0 (meaning the root node).

mptree-api

MPTree API

Link to this section Summary

Types

Used by insert, update, and fetch functions to find nodes.

t()

Updates a node

Functions

Return ancestors of and the node itself matching descendent_fn.

Return ancestors of and the node itself matching descendent_fn.

Find children of the node matching parent_fn

Find children of the node matching parent_fn.

Find descendents of the node matching ancestor_fn.

Find descendents of the node matching ancestor_fn.

Find all ancestors and descendents of the node matching match_fn.

Find all ancestors and descendents of the node matching match_fn.

Return the first node matching match_fn.

Return the first node matching match_fn.

Find parent of the node matching child_fn.

Find parent of the node matching child_fn.

Get the path from a starting node to an ending node.

Get the path from a starting node to an ending node.

Create a tree from a root_node.

Insert a node or tree as a new child of the node matching parent_fn.

Insert a node or tree as a new child of the node matching parent_fn.

Get all nodes.

Link to this section Types

@type match_fn() :: (MPTree.Node.t() -> as_boolean(any()))

Used by insert, update, and fetch functions to find nodes.

Beware, this will match only the first node it finds. If there any many nodes that might possibly pass the test, the results could be unpredictable.

@type nodes() :: [MPTree.Node.t()]
@type t() :: %MPTree{nodes: [MPTree.Node.t(), ...]}
@type transition_path() :: [{:exit | :enter, MPTree.Node.t()}]
@type update_fn() :: (MPTree.Node.t() -> MPTree.Node.t())

Updates a node

Link to this section Functions

Link to this function

fetch_ancestors_and_self(tree, descendent_fn)

View Source
@spec fetch_ancestors_and_self(t(), match_fn()) :: {:ok, nodes()} | :error

Return ancestors of and the node itself matching descendent_fn.

In this example, the blue (ancestor) and red (matched) nodes are returned. ancestors and self

Returns :error if no node is found.

Link to this function

fetch_ancestors_and_self!(tree, descendent_fn)

View Source
@spec fetch_ancestors_and_self!(t(), match_fn()) :: nodes()

Return ancestors of and the node itself matching descendent_fn.

Throws if no node is found.

Link to this function

fetch_children(tree, parent_fn)

View Source
@spec fetch_children(t(), match_fn()) :: {:ok, [MPTree.Node.t()]} | :error

Find children of the node matching parent_fn

In this example, the red node matches, and the blue nodes are returned

[
  b,
  e
]

fetch_children

Returns :error if no parent is found.

Link to this function

fetch_children!(tree, parent_fn)

View Source
@spec fetch_children!(t(), match_fn()) :: [MPTree.Node.t()]

Find children of the node matching parent_fn.

Throws if no parent is found.

Link to this function

fetch_descendents(tree, ancestor_fn)

View Source
@spec fetch_descendents(t(), match_fn()) :: {:ok, [MPTree.Node.t()]} | :error

Find descendents of the node matching ancestor_fn.

In this example, diagram, the blue (descendent) nodes are returned. The red (matched) node is not returned.

descendents

Returns :error if no ancestor is found.

Link to this function

fetch_descendents!(tree, ancestor_fn)

View Source
@spec fetch_descendents!(t(), match_fn()) :: [MPTree.Node.t()]

Find descendents of the node matching ancestor_fn.

Throws if no ancestor is found.

Link to this function

fetch_family_tree(mp_tree, match_fn)

View Source
@spec fetch_family_tree(t(), match_fn()) :: {:ok, nodes()} | :error

Find all ancestors and descendents of the node matching match_fn.

In the below diagram, the red (matched node) and blue (ancestor and descendent) nodes are returned.

family tree

Returns :error if node is not found.

Link to this function

fetch_family_tree!(tree, match_fn)

View Source
@spec fetch_family_tree!(t(), match_fn()) :: nodes()

Find all ancestors and descendents of the node matching match_fn.

Throws if node is not found.

Link to this function

fetch_node(tree, match_fn)

View Source
@spec fetch_node(t(), match_fn()) :: {:ok, MPTree.Node.t()} | :error

Return the first node matching match_fn.

In this example, the red and blue nodes would all match, but only the red is returned fetch_node

Returns :error if no node is found.

Link to this function

fetch_node!(tree, match_fn)

View Source
@spec fetch_node!(t(), match_fn()) :: MPTree.Node.t()

Return the first node matching match_fn.

Throws if no node is found.

Link to this function

fetch_parent(tree, child_fn)

View Source
@spec fetch_parent(t(), match_fn()) :: {:ok, MPTree.Node.t()} | :error

Find parent of the node matching child_fn.

In this example, the blue (parent) node is returned. parent node

Returns :error if child is not found or if child is the root node.

Link to this function

fetch_parent!(tree, child_fn)

View Source
@spec fetch_parent!(t(), match_fn()) :: MPTree.Node.t()

Find parent of the node matching child_fn.

Throws if child is not found or if child is the root node.

Link to this function

fetch_transition_path(tree, start_match_fn, end_match_fn)

View Source
@spec fetch_transition_path(t(), match_fn(), match_fn()) ::
  {:ok, transition_path()} | :error

Get the path from a starting node to an ending node.

In this example, the green (starting matched), red (ending matched), and blue (path) nodes are returned in :exit or :enter tuples transition path

The above returns

[
  exit: f,
  enter: a,
  enter: b
]

Returns :error if no node is found.

Link to this function

fetch_transition_path!(tree, start_match_fn, end_match_fn)

View Source
@spec fetch_transition_path!(t(), match_fn(), match_fn()) :: transition_path()

Get the path from a starting node to an ending node.

Throws if no node is found.

@spec from_node(MPTree.Node.t()) :: t()

Create a tree from a root_node.

Link to this function

insert(tree, node_or_tree, parent_fn)

View Source
@spec insert(t(), MPTree.Node.t() | t(), match_fn()) :: {:ok, t()} | :error

Insert a node or tree as a new child of the node matching parent_fn.

In this example, the green node is about to be inserted. before insertion

Here is after the insertion.

after insertion

Returns :error if no existing node matches parent_fn

Link to this function

insert!(tree, node_or_tree, parent_fn)

View Source
@spec insert!(t(), MPTree.Node.t() | t(), match_fn()) :: t()

Insert a node or tree as a new child of the node matching parent_fn.

Throws if no existing node matches parent_fn

@spec nodes(t()) :: [MPTree.Node.t(), ...]

Get all nodes.

Link to this function

update_nodes(tree, update_fn)

View Source
@spec update_nodes(t(), update_fn()) :: t()

Apply update_fn/0 to all nodes.

Link to this function

update_nodes(tree, update_fn, match_fn)

View Source
@spec update_nodes(t(), update_fn(), match_fn()) :: t()

Apply update_fn/0 to all nodes matching the match_fn/0.