diff_match_patch v0.2.0

View Source Dmp.Cursor (diff_match_patch v0.2.0)

A container for Elixir lists, that can be used to iterate forward and backward, with a focused "current" item in the list, and "prev" and "next" lists of items that come before and after the current item.

In Elm this has been described as a "Zipper".

Link to this section Summary

Types

init_option()
init_options()

Use position: 0 for example, to set the initial position of the Cursor to the first item.

position_value()

A value used to set the Cursor position.

t()

Functions

after_last?(cursor)

Returns true if the Cursor is positioned after the last item.

before_first?(cursor)

Returns true if the Cursor is positioned before the first item.

count(cursor)

Returns the total number of items in the Cursor.

delete(cursor, count \\ 1)

Remove items at the Cursor's current position, leaving the previous items alone.

delete_before(cursor, count \\ 1)

Remove items before the Cursor's current position, leaving the current and next items alone.

empty?(cursor)

Returns true if there are no items in the Cursor.

find_back!(c, item)

Moves the position of the Cursor back through the "prev" list to the given item.

find_back(c, item)

Moves the position of the Cursor back through the "prev" list until the given item is found. Returns nil and if the item cannot be found.

find_forward(c, item)

Moves the position of the Cursor forward through the "next" list until the given item is found. Returns nil and if the item cannot be found.

from_list(items, opts \\ [])

Create a Cursor from a list of items.

from_split(prev, next, opts \\ [])

Create a Cursor from two lists.

get(cursor)

Return a 3-tuple of the previous, current, and next items relative to the Cursor's current position.

has_next?(cursor)

Returns false if the Cursor is positioned at or after the last item.

has_previous?(cursor)

Returns false if the Cursor is positioned at or before the first item.

insert(c, list)

Insert items at the Cursor's current position, leaving the previous items alone.

insert_at_head(c, items)

Insert items at the Cursor's head position, leaving the current position pointer alone.

insert_before(c, items)

Insert items before the Cursor's current position, leaving the current and next items alone.

move_back(cursor, count \\ 1)

Moves the position of the Cursor back a number of steps.

move_first(c)

Moves the position of the Cursor to the first item. An alias of Cursor.move_to(c, 0).

move_forward(cursor, count \\ 1)

Moves the position of the Cursor forward a number of steps.

move_to(c, pos)

Changes the current position of the Cursor.

new()

Create a Cursor containing no items.

position(cursor)

Returns the current position of the Cursor.

reset(c)

Resets the position of the Cursor to before the first item. An alias for Cursor.move_to(c, -1).

to_list(cursor)

Extract the list from a Cursor.

Link to this section Types

Link to this type

init_option()

View Source 
@type init_option() :: {:position, position_value()}
Link to this type

init_options()

View Source 
@type init_options() :: [init_option()]

Use position: 0 for example, to set the initial position of the Cursor to the first item.

Link to this type

position_value()

View Source 
@type position_value() :: -1 | non_neg_integer() | :last | :tail

A value used to set the Cursor position.

  • -1 means before the first item in the container.
  • 0 means at the first item.
  • :last means at the last item.
  • :tail means after the last item.
Link to this type

t()

View Source 
@type t() :: %Dmp.Cursor{current: term(), next: list(), prev: list()}

Link to this section Functions

Link to this function

after_last?(cursor)

View Source 
@spec after_last?(t()) :: boolean()

Returns true if the Cursor is positioned after the last item.

examples

 Examples 

iex> Cursor.from_list([1, 2]) |> Cursor.after_last?()
false

iex> Cursor.from_list([1, 2]) |> Cursor.move_forward(2) |> Cursor.after_last?()
false

iex> Cursor.from_list([1, 2]) |> Cursor.move_forward(3) |> Cursor.after_last?()
true
Link to this function

before_first?(cursor)

View Source 
@spec before_first?(t()) :: boolean()

Returns true if the Cursor is positioned before the first item.

examples

 Examples 

iex> Cursor.from_list([1, 2, 3]) |> Cursor.before_first?()
true

iex> Cursor.from_list([1, 2, 3]) |> Cursor.move_forward() |> Cursor.before_first?()
false
Link to this function

count(cursor)

View Source 
@spec count(t()) :: non_neg_integer()

Returns the total number of items in the Cursor.

examples

 Examples 

iex> Cursor.from_list([1, 2, 3]) |> Cursor.count()
3
Link to this function

delete(cursor, count \\ 1)

View Source 
@spec delete(t(), integer()) :: t()

Remove items at the Cursor's current position, leaving the previous items alone.

examples

 Examples 

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.delete(1)
%Cursor{current: 4, next: [5], prev: [2, 1]}
Link to this function

delete_before(cursor, count \\ 1)

View Source 
@spec delete_before(t(), integer()) :: t()

Remove items before the Cursor's current position, leaving the current and next items alone.

examples

 Examples 

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.delete_before(1)
%Cursor{current: 3, next: [4, 5], prev: [1]}
Link to this function

empty?(cursor)

View Source 
@spec empty?(t()) :: boolean()

Returns true if there are no items in the Cursor.

examples

 Examples 

iex> Cursor.from_list([]) |> Cursor.empty?()
true

iex> Cursor.from_list([1, 2, 3]) |> Cursor.empty?()
false
Link to this function

find_back!(c, item)

View Source 
@spec find_back!(t(), term()) :: t()

Moves the position of the Cursor back through the "prev" list to the given item.

Raises if the item cannot be found.

Link to this function

find_back(c, item)

View Source 
@spec find_back(t(), term()) :: nil | t()

Moves the position of the Cursor back through the "prev" list until the given item is found. Returns nil and if the item cannot be found.

examples

 Examples 

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.find_back(1)
%Cursor{current: 1, next: [2, 3, 4, 5], prev: []}

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.find_back(5)
nil

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.find_back(3)
nil
Link to this function

find_forward(c, item)

View Source 
@spec find_forward(t(), term()) :: nil | t()

Moves the position of the Cursor forward through the "next" list until the given item is found. Returns nil and if the item cannot be found.

examples

 Examples 

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.find_forward(5)
%Cursor{current: 5, next: [], prev: [4, 3, 2, 1]}

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.find_forward(1)
nil

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.find_forward(3)
nil
Link to this function

from_list(items, opts \\ [])

View Source 
@spec from_list(list(), init_options()) :: t()

Create a Cursor from a list of items.

  • opts - The keyword :position can specify a position value, such as -1, 0, 1, :last, or tail in order to set the position of the created Cursor.

examples

 Examples 

iex> Cursor.from_list([1, 2, 3])
%Cursor{current: nil, next: [1, 2, 3], prev: []}

iex> Cursor.from_list([1, 2, 3]) |> Cursor.move_forward()
%Cursor{current: 1, next: [2, 3], prev: []}

iex> Cursor.from_list([1, 2, 3], position: 1)
%Cursor{current: 2, next: [3], prev: [1]}
Link to this function

from_split(prev, next, opts \\ [])

View Source 
@spec from_split(list(), list(), init_options()) :: t()

Create a Cursor from two lists.

  • opts - the keyword :position can specify a position value, such as -1, 0, 1, :last, or tail in order to set the position of the created Cursor.

examples

 Examples 

iex> Cursor.from_split([1, 2, 3], [4, 5, 6])
%Cursor{current: 4, next: [5, 6], prev: [3, 2, 1]}
Link to this function

get(cursor)

View Source 
@spec get(t()) :: {term(), term(), term()}

Return a 3-tuple of the previous, current, and next items relative to the Cursor's current position.

Any elements of the tuple may be nil.

examples

 Examples 

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.get()
{2, 3, 4}

iex> Cursor.from_list([]) |> Cursor.get()
{nil, nil, nil}

iex> Cursor.from_list([1, 2]) |> Cursor.get()
{nil, nil, 1}

iex> Cursor.from_list([1, 2]) |> Cursor.move_forward() |> Cursor.get()
{nil, 1, 2}

iex> Cursor.from_list([1, 2]) |> Cursor.move_forward(2) |> Cursor.get()
{1, 2, nil}

iex> Cursor.from_list([1, 2]) |> Cursor.move_forward(3) |> Cursor.get()
{2, nil, nil}
Link to this function

has_next?(cursor)

View Source 
@spec has_next?(t()) :: boolean()

Returns false if the Cursor is positioned at or after the last item.

examples

 Examples 

iex> Cursor.from_list([1, 2]) |> Cursor.has_next?()
true

iex> Cursor.from_list([1, 2]) |> Cursor.move_forward(2) |> Cursor.has_next?()
false

iex> Cursor.from_list([1, 2]) |> Cursor.move_forward(3) |> Cursor.has_next?()
false
Link to this function

has_previous?(cursor)

View Source 
@spec has_previous?(t()) :: boolean()

Returns false if the Cursor is positioned at or before the first item.

examples

 Examples 

iex> Cursor.from_list([1, 2]) |> Cursor.has_previous?()
false

iex> Cursor.from_list([1, 2]) |> Cursor.move_forward() |> Cursor.has_previous?()
false

iex> Cursor.from_list([1, 2]) |> Cursor.move_forward(2) |> Cursor.has_previous?()
true

iex> Cursor.from_list([1, 2]) |> Cursor.move_forward(3) |> Cursor.has_previous?()
true
Link to this function

insert(c, list)

View Source 
@spec insert(t(), list()) :: t()

Insert items at the Cursor's current position, leaving the previous items alone.

After the insertion, the Cursor points to the first inserted item.

examples

 Examples 

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.insert([10, 11])
%Cursor{current: 10, next: [11, 3, 4, 5], prev: [2, 1]}
Link to this function

insert_at_head(c, items)

View Source 
@spec insert_at_head(t(), list()) :: t()

Insert items at the Cursor's head position, leaving the current position pointer alone.

examples

 Examples 

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.insert_at_head([10, 11])
%Cursor{current: 3, next: [4, 5], prev: [2, 1, 11, 10]}
Link to this function

insert_before(c, items)

View Source 
@spec insert_before(t(), list()) :: t()

Insert items before the Cursor's current position, leaving the current and next items alone.

examples

 Examples 

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.insert_before([10, 11])
%Cursor{current: 3, next: [4, 5], prev: [11, 10, 2, 1]}
Link to this function

move_back(cursor, count \\ 1)

View Source 
@spec move_back(t(), integer()) :: t()

Moves the position of the Cursor back a number of steps.

examples

 Examples 

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.move_back(1)
%Cursor{current: 2, next: [3, 4, 5], prev: [1]}

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.move_back(2)
%Cursor{current: 1, next: [2, 3, 4, 5], prev: []}

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.move_back(3)
%Cursor{current: nil, next: [1, 2, 3, 4, 5], prev: []}
Link to this function

move_first(c)

View Source 
@spec move_first(t()) :: t()

Moves the position of the Cursor to the first item. An alias of Cursor.move_to(c, 0).

examples

 Examples 

iex> Cursor.new() |> Cursor.move_first()
%Cursor{current: nil, next: [], prev: []}

iex> Cursor.from_list([1]) |> Cursor.move_first()
%Cursor{current: 1, next: [], prev: []}

iex> Cursor.from_list([1, 2]) |> Cursor.move_first()
%Cursor{current: 1, next: [2], prev: []}

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.move_first()
%Cursor{current: 1, next: [2, 3, 4, 5], prev: []}
Link to this function

move_forward(cursor, count \\ 1)

View Source 
@spec move_forward(t(), integer()) :: t()

Moves the position of the Cursor forward a number of steps.

examples

 Examples 

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.move_forward()
%Cursor{current: 4, next: [5], prev: [3, 2, 1]}

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.move_forward(2)
%Cursor{current: 5, next: [], prev: [4, 3, 2, 1]}

iex> Cursor.from_list([1, 2, 3, 4, 5]) |> Cursor.move_forward(3)
%Cursor{current: 3, next: [4, 5], prev: [2, 1]}

iex> Cursor.from_list([1, 2, 3, 4, 5]) |> Cursor.move_forward(5)
%Cursor{current: 5, next: [], prev: [4, 3, 2, 1]}

iex> Cursor.from_list([1, 2, 3, 4, 5]) |> Cursor.move_forward(6)
%Cursor{current: nil, next: [], prev: [5, 4, 3, 2, 1]}

iex> %Cursor{current: {:delete, "abc"}, next: [{:equal, "xxx"}, {:insert, "def"}], prev: []} |> Cursor.move_forward(1)
%Cursor{current: {:equal, "xxx"}, next: [{:insert, "def"}], prev: [{:delete, "abc"}]}

iex> %Cursor{current: {:delete, "abc"}, next: [{:equal, "xxx"}, {:insert, "def"}], prev: []} |> Cursor.move_forward(2)
%Cursor{current: {:insert, "def"}, next: [], prev: [{:equal, "xxx"}, {:delete, "abc"}]}

iex> %Cursor{current: {:delete, "abc"}, next: [{:equal, "xxx"}, {:insert, "def"}], prev: []} |> Cursor.move_forward(3)
%Cursor{current: nil, next: [], prev: [{:insert, "def"}, {:equal, "xxx"}, {:delete, "abc"}]}
Link to this function

move_to(c, pos)

View Source 
@spec move_to(t(), position_value()) :: t()

Changes the current position of the Cursor.

  • pos - The desired position.

  • -1 means the Cursor is positioned before the first item.

  • 0 means the Cursor is positioned at the first item (if it is not empty).

  • :last means the Cursor is positioned at the last item (if it is not empty).

  • :tail means the Cursor is positioned after the last item.

examples

 Examples 

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.move_to(-1)
%Cursor{current: nil, next: [1, 2, 3, 4, 5], prev: []}

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.move_to(0)
%Cursor{current: 1, next: [2, 3, 4, 5], prev: []}

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.move_to(1)
%Cursor{current: 2, next: [3, 4, 5], prev: [1]}

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.move_to(:last)
%Cursor{current: 5, next: [], prev: [4, 3, 2, 1]}

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.move_to(:tail)
%Cursor{current: nil, next: [], prev: [5, 4, 3, 2, 1]}
Link to this function

new()

View Source 
@spec new() :: t()

Create a Cursor containing no items.

examples

 Examples 

iex> Cursor.new()
%Cursor{current: nil, next: [], prev: []}
Link to this function

position(cursor)

View Source 
@spec position(t()) :: integer()

Returns the current position of the Cursor.

A return value of -1 means the Cursor is positioned before the first item. A return value of Cursor.count(c) means the Cursor is positioned after the last item.

examples

 Examples 

iex> Cursor.from_list([1, 2]) |> Cursor.position()
-1

iex> Cursor.from_list([1, 2]) |> Cursor.move_forward() |> Cursor.position()
0

iex> Cursor.from_list([1, 2]) |> Cursor.move_forward(2) |> Cursor.position()
1

iex> Cursor.from_list([1, 2]) |> Cursor.move_forward(3) |> Cursor.position()
2

iex> Cursor.from_list([1, 2]) |> Cursor.move_forward(4) |> Cursor.position()
2
Link to this function

reset(c)

View Source

Resets the position of the Cursor to before the first item. An alias for Cursor.move_to(c, -1).

examples

 Examples 

iex> Cursor.new() |> Cursor.reset()
%Cursor{current: nil, next: [], prev: []}

iex> Cursor.from_list([1]) |> Cursor.move_forward() |> Cursor.reset()
%Cursor{current: nil, next: [1], prev: []}

iex> Cursor.from_list([1, 2]) |> Cursor.move_forward() |> Cursor.reset()
%Cursor{current: nil, next: [1, 2], prev: []}

iex> %Cursor{current: 3, next: [4, 5], prev: [2, 1]} |> Cursor.reset()
%Cursor{current: nil, next: [1, 2, 3, 4, 5], prev: []}
Link to this function

to_list(cursor)

View Source 
@spec to_list(t()) :: list()

Extract the list from a Cursor.

examples

 Examples 

iex> Cursor.from_list([1, 2, 3]) |> Cursor.to_list()
[1, 2, 3]