Documentation

A RoseTrie is just a newtype around a pair of two elements forming a node, the first being the leaf of the node, and the second being the branches of the node. The leaf may or may not exist, so it is wrapped in a Maybe data structure.

When you associate an object o at a path [p], a walk is performed, with each segment of the path [p] selecting a branch that contains another sub-node. When the path [p] is empty, the walk stops and the object o is placed into the current sub-node.

This class provides fromRoseTrie, which generates a data structure of type d from a RoseTrie of type RoseTrie p o, similar to how the Read class can generate a data structure from a String.

This class provides fromRoseTrie, which generates a RoseTrie of type RoseTrie p o from a data type of type d, similar to how the Show class can generate a String from a data structure.

This data type controls algorithms like mergeWithKeyM where monadic evaluation needs to occur in a certain order. This simple operation code decides whether evaluation of leaves happens before evaluation of sub-RoseTries (BreadthFirst) or whether evaluation of leaves happens after evaluation of sub-RoseTries (DepthFirst).

Like RunRoseTrie, but pairs the RunRoseTrie value with the RoseTrie data type itself. This is used to instantiate Foldable and Traversable, which means in order to use foldr or traverse, it is first necessary to store the tree in this data type along with the RunRoseTrie operator indicating the order in which the leaf objects o will be retrieved.

The empty RoseTrie.

Since RoseTrie does not directly instantiate Monoid, it cannot be used with the new function. So the newTrie function is provided which behaves similarly. In other words, this function takes a list of transfomration functions that modify a RoseTrie, and starting with an empty RoiseTrie, applies each transformation in order to build the RoseTrie.

This is a focusing lens that focuses on a RoseTrie node at a given path [p], rather than an element at the given path.

Focuses on an individual leaf at the given path.

This function merges two trees together, given a leaf-merging function that can optionally create or remove leaves based on whether or not leaves exist on the left and right at any given point in the path [p].

Also required are two RoseTrie functions: a function that can convert the first (left) RoseTrie parameter to a RoseTrie of the resultant type, and a function that can convert the second (right) RoseTrie parameter to a RoseTrie of the resultant type. These functions are used for when leaves exist only on the left RoseTrie, or for when leaves only exist on the right RoseTrie.

The given leaf-merging function is called for every single sub-RoseTrie node where the path [p] exists in both the overlay and target RoseTries. Each sub-RoseTrie node may or may not have a Leaf.

• If the RoseTrie node for the overlay RoseTrie and the target RoseTrie are both without leaves, the merging function is passed Nothing as both arguments to the updating function.
• If only the target RoseTrie has a Leaf, the overlay Leaf as passed with Just as the first (left) argument to the updating function, and Nothing is passed as the second (right) argument.
• If only the overlay RoseTrie has a leaf, Nothing is passed as the first (left) argument to the merging function, and the overlay Leaf is passed with Just as the second (right) argument.
• If both the target and the overlay RoseTries have Leafs, both Leafs are passed with Just to the merging function.

Also, it is necessary to specify (as the first parameter to this function) the RunRoseTrie type, which indicates DepthFirst or BreadthFirst evaluation.

Insert a leaf at a given address, updating it with the combining function if it already exist.

Insert a leaf at a given address.

Update a leaf at a given address.

Delete a leaf or Branch at a given address.

Create a RoseTrie from a list of associationes, the fst element containing the branches, the snd element containing the leaf value. This is the inverse operation of assocs.

Like fromListWith but called with (flip const).

Create a RoseTrie with () nodes. This is useful for times when the structure of the tree is all you need.

Create a RoseTrie containing only a single path to a single element.

This function analogous to the lookup function, which returns a value stored in a leaf, or nothing if there is no leaf at the given path.

This function works like lookup, but takes a key predicate to match keys of the tree, rather than using (==). This means the efficient O(log n) Map lookup function in the Data.Map module cannot be used, each key must be inspected one-by-one making this algorithm O(n^2). This also means multiple values may match the given key predicate. Lookups are always performed in DepthFirst order, this helps improve efficiency a little bit, as the matches nearest the beggining of each list of assocs are chosen first, and lazily taking only the first few matches will save us from searching the entire tree.

Take note of the different types p and b. This means the path p you use to search the RoseTrie need not be the same type as the branches b of the RoseTrie, and what is returned are the actual branches b that matched the path p, not the path p itself.

This function calls slowLookup and returns only the first result. This can be used to take advantage of Haskell's laziness and save time by halting the search for matching paths as soon as the first match is found.

Get all items and their associated path.

Like assocs but restricts the resulting list of associations to only include elements that lie along a given path. This function walks through the tree with the given path, and collects every leaf along the way. Where there is a leaf, the path is partitioned into the path up to the leaf and the path after the leaf. The list of returned values are these partitioned paths paired with their associated leaves.

Like partitions, but allows you to use a matching function that other than (==). The matching function should return Nothing for non-matching path elements, and a Just containing a path element that may have been transformed by the matching function.

Like partitionsWith but uses a monadic matching function.

Apply map snd to the result of assocs, behaves just like how elems or elems works.

Counts the number of *nodes*, which includes the number of Branches and Leafs. Remember that nodes that contain branches may not necessarily contain leaf elements.

Counts the number of leafs only.

Counts the number of branches only, not leaves.

Since this function does not merge trees monadically, it is not important whether merging happens in DepthFirst or BreadthFirst order.

This function computes the cartesian of two trees. For example, if the assocs of two trees are:

-- tree X              tree Y
[( [a, b, c], t ),  [( [b, c], w ),
 ( [a, b   ], u ),   ( [a   ], x )]
 ( [b      ], v )]

Then the product of these two trees X and Y is the evaluation of fromList on:

[( [a, b, c] ++ [b, c], t<>w ),
 ( [a, b, c] ++ [a   ], t<>x ),
 ( [a, b,  ] ++ [b, c], u<>w ),
 ( [a, b,  ] ++ [a,  ], u<>x ),
 ( [b,     ] ++ [b, c], v<>w ),
 ( [b,     ] ++ [a   ], v<>x )]

Like productWith but uses mappend as the function that computes the product of each element.

If you have read the chapter about zippers in the book "Learn You a Haskell for Great Good", you might appreciate that a zipper is provided for RoseTrie in this module, and a number of useful Control.Monad.Stateful APIs are also provided, namely goto and back.

Although it should be noted usually, Lenses, folds, traversals, and mergeWithKeyM are all you will need.

A monadic function type that keeps the ZipRoseTrie in a StateT for you, and instantiates MonadState such that get and put operate on leaves of the RoseTrie. Use goto, back, and home to navigate the RoseTrie.

Run the UpdateRoseTrieT function, returning the modified RoseTrie and the last result returned by the UpdateRoseTrieT function.

Analogous to execStateT, does the same thing as runUpdateRoseTrieT but disgards the final return value of the UpdateRoseTrieT function.

Analogous to execStateT, does the same thing as runUpdateRoseTrieT but disgards the updated RoseTrie and only keeps the last return value of the UpdateRoseTrieT function.

Go to the node with the given path. If the path does not exist, it is created.

Go up one level in the tree, storing the current sub-tree into the upper tree, unless the current tree is Void, in which case it is deleted from the upper tree. Returns False if we are already at the root of the RoseTrie and could not go back.

Returns True if we are at the top level of the tree.

Go back to the top level of the tree.

Return the current path.

This data type lets you store a "diff", that is a structure tracking the differences, between two RoseTries. This is essentially the result of a mergeWithKeyM operation tracking all of the changes that would happen in a data structure without actually applying the changes. Traversing over the RoseTrie of RoseTrieDiffs with traverse to actually convert the RoseTrieDiffs would then apply the changes.

Produce a difference report of two trees with the given comparison predicate. If the predicate returns True, the node does not appear in the resultant RoseTrie. If there is a difference, the difference is recored into a node in the resultant RoseTrie.

Call treeDiffWith using 'Prelude.(==)' as the comparison predicate.

Call treeDiffWith using 'Prelude.(==)' as the comparison predicate.