@spec current_focus(t()) :: ExRoseTree.t()

Returns the current focus of the Zipper.

examples

Examples

iex> tree = ExRoseTree.new(5)
...> z = ExRoseTree.Zipper.new(tree)
...> ExRoseTree.Zipper.current_focus(z)
%ExRoseTree{term: 5, children: []}

@spec depth_of_focus(t()) :: non_neg_integer()

Returns the depth (as zero-based index) of the current focus.

examples

Examples

iex> loc_trees = for n <- [4,3,2,1], do: ExRoseTree.new(n)
...> locs = for n <- loc_trees, do: ExRoseTree.Zipper.Location.new(n)
...> tree = ExRoseTree.new(5)
...> z = ExRoseTree.Zipper.new(tree, path: locs)
...> ExRoseTree.Zipper.depth_of_focus(z)
4

@spec empty() :: t()

Returns an empty Zipper.

examples

Examples

iex> ExRoseTree.Zipper.empty()
%ExRoseTree.Zipper{
  focus: %ExRoseTree{term: nil, children: []},
  prev: [],
  next: [],
  path: []
}

@spec focused_children(t()) :: [ExRoseTree.t()]

Returns the children of the Zipper's current focus.

A shortcut to ExRoseTree.get_children/1.

examples

Examples

iex> tree = ExRoseTree.new(5, [1,2,3,4])
...> z = ExRoseTree.Zipper.new(tree)
...> ExRoseTree.Zipper.focused_children(z)
[
  %ExRoseTree{term: 1, children: []},
  %ExRoseTree{term: 2, children: []},
  %ExRoseTree{term: 3, children: []},
  %ExRoseTree{term: 4, children: []}
]

@spec focused_term(t()) :: term()

Returns the term of the current focus of the Zipper.

A shortcut to using ExRoseTree.get_term/1.

examples

Examples

iex> tree = ExRoseTree.new(5)
...> z = ExRoseTree.Zipper.new(tree)
...> ExRoseTree.Zipper.focused_term(z)
5

@spec from_locations([ExRoseTree.Zipper.Location.t()]) :: t()

Builds a new Zipper from a list of ExRoseTree.Zipper.Locations.

examples

Examples

iex> locs = for loc <- [3,2,1], do: ExRoseTree.Zipper.Location.new(loc)
...> ExRoseTree.Zipper.from_locations(locs)
%ExRoseTree.Zipper{
  focus: %ExRoseTree{term: 3, children: []},
  prev: [],
  next: [],
  path: [
    %ExRoseTree.Zipper.Location{
      prev: [],
      term: 2,
      next: []
    },
    %ExRoseTree.Zipper.Location{
      prev: [],
      term: 1,
      next: []
    }
  ]
}

@spec index_of_focus(t()) :: non_neg_integer()

Returns the index (zero-based) of the current focus with respect to any potential siblings it may have.

examples

Examples

iex> prev = for n <- [1,2,3,4], do: ExRoseTree.new(n)
...> tree = ExRoseTree.new(5)
...> z = ExRoseTree.Zipper.new(tree, prev: prev)
...> ExRoseTree.Zipper.index_of_focus(z)
4

@spec map_focus(t(), (ExRoseTree.t() -> ExRoseTree.t())) :: t()

Applies the given function to the current focus.

examples

Examples

iex> tree = ExRoseTree.new(5)
...> z = ExRoseTree.Zipper.new(tree)
...> map_fn = &ExRoseTree.set_children(&1, [6,7,8,9])
...> ExRoseTree.Zipper.map_focus(z, &map_fn.(&1))
%ExRoseTree.Zipper{
  focus: %ExRoseTree{term: 5, children: [
    %ExRoseTree{term: 6, children: []},
    %ExRoseTree{term: 7, children: []},
    %ExRoseTree{term: 8, children: []},
    %ExRoseTree{term: 9, children: []},
  ]},
  prev: [],
  next: [],
  path: []
}

@spec map_focused_children(t(), (ExRoseTree.t() -> ExRoseTree.t())) :: t()

Applies the given function to the focused children of the current focus.

A shortcut to ExRoseTree.map_children/2 and set_focus/2.

examples

Examples

iex> tree = ExRoseTree.new(5, [1,2,3,4])
...> z = ExRoseTree.Zipper.new(tree)
...> map_fn = &ExRoseTree.map_term(&1, fn x -> x * 2 end)
...> ExRoseTree.Zipper.map_focused_children(z, map_fn)
%ExRoseTree.Zipper{
  focus: %ExRoseTree{term: 5, children: [
    %ExRoseTree{term: 2, children: []},
    %ExRoseTree{term: 4, children: []},
    %ExRoseTree{term: 6, children: []},
    %ExRoseTree{term: 8, children: []}
  ]},
  prev: [],
  next: [],
  path: []
}

@spec map_focused_term(t(), (term() -> term())) :: t()

Applies the given function to the term of the current focus.

A shortcut to using ExRoseTree.map_term/2 with set_focus/2.

examples

Examples

iex> tree = ExRoseTree.new(5)
...> z = ExRoseTree.Zipper.new(tree)
...> map_fn = fn term -> term * 2 end
...> ExRoseTree.Zipper.map_focused_term(z, &map_fn.(&1))
%ExRoseTree.Zipper{
  focus: %ExRoseTree{term: 10, children: []},
  prev: [],
  next: [],
  path: []
}

@spec map_path(
  t(),
  (ExRoseTree.Zipper.Location.t() -> ExRoseTree.Zipper.Location.t())
) :: t()

Applies the given function to path of ExRoseTree.Zipper.Locations from the current focus back to the root without moving the Zipper.

examples

Examples

iex> path = for n <- [4,3,2,1], do: ExRoseTree.Zipper.Location.new(n)
...> tree = ExRoseTree.new(5)
...> z = ExRoseTree.Zipper.new(tree, path: path)
...> map_fn = &ExRoseTree.Zipper.Location.map_term(&1, fn term -> term * 2 end)
...> ExRoseTree.Zipper.map_path(z, &map_fn.(&1))
%ExRoseTree.Zipper{
  focus: %ExRoseTree{term: 5, children: []},
  prev: [],
  next: [],
  path: [
    %ExRoseTree.Zipper.Location{prev: [], term: 8, next: []},
    %ExRoseTree.Zipper.Location{prev: [], term: 6, next: []},
    %ExRoseTree.Zipper.Location{prev: [], term: 4, next: []},
    %ExRoseTree.Zipper.Location{prev: [], term: 2, next: []}]
}

@spec new(
  ExRoseTree.t(),
  keyword()
) :: t()

Returns a new Zipper with its focus on the given ExRoseTree. Optionally take a list of previous and next sibling trees when using the :prev and :next keyword options.

Note that a Zipper maintains the list of previous siblings in reverse order internally, and this function performs that reversal itself, so do not pre-reverse your list of previous siblings when using that option!

examples

Examples

iex> tree = ExRoseTree.new(5)
...> ExRoseTree.Zipper.new(tree)
%ExRoseTree.Zipper{
  focus: %ExRoseTree{term: 5, children: []},
  prev: [],
  next: [],
  path: []
}

iex> prev = for n <- [1,2,3,4], do: ExRoseTree.new(n)
...> tree = ExRoseTree.new(5)
...> ExRoseTree.Zipper.new(tree, prev: prev)
%ExRoseTree.Zipper{
  focus: %ExRoseTree{term: 5, children: []},
  prev: [
    %ExRoseTree{term: 4, children: []},
    %ExRoseTree{term: 3, children: []},
    %ExRoseTree{term: 2, children: []},
    %ExRoseTree{term: 1, children: []}
  ],
  next: [],
  path: []
}

iex> loc_trees = for n <- [4,3,2,1], do: ExRoseTree.new(n)
...> locs = for n <- loc_trees, do: ExRoseTree.Zipper.Location.new(n)
...> tree = ExRoseTree.new(5)
...> ExRoseTree.Zipper.new(tree, path: locs)
%ExRoseTree.Zipper{
  focus: %ExRoseTree{term: 5, children: []},
  prev: [],
  next: [],
  path: [
    %ExRoseTree.Zipper.Location{prev: [], term: 4, next: []},
    %ExRoseTree.Zipper.Location{prev: [], term: 3, next: []},
    %ExRoseTree.Zipper.Location{prev: [], term: 2, next: []},
    %ExRoseTree.Zipper.Location{prev: [], term: 1, next: []}
  ]
}

@spec new_location(t()) :: ExRoseTree.Zipper.Location.t()

Builds a new ExRoseTree.Zipper.Location out of the current Zipper.

examples

Examples

iex> next = for n <- [6,7,8,9], do: ExRoseTree.new(n)
...> tree = ExRoseTree.new(5)
...> z = ExRoseTree.Zipper.new(tree, next: next)
...> ExRoseTree.Zipper.new_location(z)
%ExRoseTree.Zipper.Location{
  prev: [],
  term: 5,
  next: [
    %ExRoseTree{term: 6, children: []},
    %ExRoseTree{term: 7, children: []},
    %ExRoseTree{term: 8, children: []},
    %ExRoseTree{term: 9, children: []}
  ]
}

@spec remove_focus(t()) :: {t(), ExRoseTree.t() | nil}

Removes the current focus and then moves the focus to one of three places:

1. the next sibling, if one exists,
2. else the previous sibling, if one exists,
3. else the parent, if one exists

If none of those conditions exist, it will return an empty Zipper. In any case, the new Zipper will be returned as the first item in a tuple, while the removed focus will be returned as the second item.

examples

Examples

iex> tree = ExRoseTree.new(5)
...> prev_siblings = for n <- [3,4], do: ExRoseTree.new(n)
...> next_siblings = for n <- [6,7], do: ExRoseTree.new(n)
...> z = ExRoseTree.Zipper.new(tree, prev: prev_siblings, next: next_siblings)
...> ExRoseTree.Zipper.remove_focus(z)
{%ExRoseTree.Zipper{
  focus: %ExRoseTree{term: 6, children: []},
  prev: [
    %ExRoseTree{term: 4, children: []},
    %ExRoseTree{term: 3, children: []}
  ],
  next: [
    %ExRoseTree{term: 7, children: []}
  ],
  path: []
},
%ExRoseTree{term: 5, children: []}}

@spec root?(t()) :: boolean()

Returns whether or not the current Zipper is at the root of the tree. A Zipper is considered at the root when it has no ExRoseTree.Zipper.Locations in its path.

examples

Examples

iex> tree = ExRoseTree.new(5)
...> z = ExRoseTree.Zipper.new(tree)
...> ExRoseTree.Zipper.root?(z)
true

@spec set_focus(t(), ExRoseTree.t()) :: t()

Sets the current focus of the Zipper to the given ExRoseTree.

examples

Examples

iex> tree = ExRoseTree.new(5)
...> z = ExRoseTree.Zipper.empty()
...> ExRoseTree.Zipper.set_focus(z, tree)
%ExRoseTree.Zipper{
  focus: %ExRoseTree{term: 5, children: []},
  prev: [],
  next: [],
  path: []
}

@spec set_focused_children(t(), [ExRoseTree.t()]) :: t()

Sets the focused children to the given list of rose trees.

A shortcut to ExRoseTree.set_children/2 and set_focus/2.

examples

Examples

iex> tree = ExRoseTree.new(5, [1,2,3,4])
...> z = ExRoseTree.Zipper.new(tree)
...> new_children = for t <- [6,7,8,9], do: ExRoseTree.new(t)
...> ExRoseTree.Zipper.set_focused_children(z, new_children)
%ExRoseTree.Zipper{
  focus: %ExRoseTree{term: 5, children: [
    %ExRoseTree{term: 6, children: []},
    %ExRoseTree{term: 7, children: []},
    %ExRoseTree{term: 8, children: []},
    %ExRoseTree{term: 9, children: []}
  ]},
  prev: [],
  next: [],
  path: []
}

@spec set_focused_term(t(), term()) :: t()

Sets the term of the current focus of the Zipper.

A shortcut to using ExRoseTree.set_term/2 with set_focus/2.

examples

Examples

iex> tree = ExRoseTree.new(5)
...> z = ExRoseTree.Zipper.new(tree)
...> ExRoseTree.Zipper.set_focused_term(z, 10)
%ExRoseTree.Zipper{
  focus: %ExRoseTree{term: 10, children: []},
  prev: [],
  next: [],
  path: []
}

@spec to_forest(t()) :: {[ExRoseTree.t()], [ExRoseTree.t()]}

Moves a Zipper back to the root and returns a 2-tuple containing first, a list containing the previous siblings to the original root and second, a list containing the original root followed by its next siblings.

examples

Examples

iex> tree = ExRoseTree.new(3, [6])
...> prev_trees = for t <- [1,2], do: ExRoseTree.new(t)
...> next_trees = for t <- [4,5], do: ExRoseTree.new(t)
...> z = ExRoseTree.Zipper.new(tree, prev: prev_trees, next: next_trees)
...> z = Zipper.last_child(z)
...> Zipper.to_forest(z)
{
  [
    %ExRoseTree{term: 1, children: []},
    %ExRoseTree{term: 2, children: []}
  ],
  [
    %ExRoseTree{term: 3, children: [%ExRoseTree{term: 6, children: []}]},
    %ExRoseTree{term: 4, children: []},
    %ExRoseTree{term: 5, children: []}
  ]
}

@spec to_tree(t()) :: ExRoseTree.t()

Moves a Zipper back to the root and returns the current focus, the root ExRoseTree.

examples

Examples

iex> tree = ExRoseTree.new(5, [1,2,3,4])
...> z = ExRoseTree.Zipper.new(tree)
...> z = Zipper.last_child(z)
...> Zipper.to_tree(z)
%ExRoseTree{
  term: 5,
  children: [
    %ExRoseTree{term: 1, children: []},
    %ExRoseTree{term: 2, children: []},
    %ExRoseTree{term: 3, children: []},
    %ExRoseTree{term: 4, children: []},
  ]
}