View Source Trieval (trieval v1.1.0)

Trieval provides an interface for creating and managing trie data structures. A trie, also known as a prefix tree, is a type of search tree used to store associative data structures.

This module provides functions to create new tries, insert values, and perform various operations on the trie. It supports creating tries from binaries, lists of binaries, and tuples of binaries.

Summary

Functions

Returns whether or not a trie contains a given binary key.

Inserts a binary, list of binaries or tuple of binaries into an existing trie.

Collects all binaries that begin with a given prefix. Returns matching binaries, along with matching binaries' longest common prefix. Example use-case would be for auto-completion.

Returns a new trie. Providing no arguments creates an empty trie. Optionally, a binary, a list of binaries or a tuple of binaries can be passed to new/1.

Returns a new trie containing lists of binaries representing the provided values passed to new/1. Optional values are a binary, a list of binaries or a tuple of binaries can be passed to new/1.

Collects all binaries match a given pattern. Returns either a list of matches or an error in the form {:error, reason}.

Collects all binaries that begin with a given prefix.

Functions

contains?(trie, binary)

@spec contains?(Trieval.Trie.t([{:trie, map()}]), binary()) :: boolean()

Returns whether or not a trie contains a given binary key.

Examples

iex> Trieval.new(~w/apple apply ape ample/) |> Trieval.contains?("apple")
true

iex> Trieval.new(~w/apple apply ape ample/) |> Trieval.contains?("zebra")
false

insert(trie, binaries)

@spec insert(
  Trieval.Trie.t([{:trie, map()}]),
  binary() | maybe_improper_list() | {binary(), any()}
) ::
  Trieval.Trie.t([{:trie, map()}])

Inserts a binary, list of binaries or tuple of binaries into an existing trie.

Examples

iex> Trieval.new() |> Trieval.insert("apple")
%Trieval.Trie{trie: %{97 => %{112 => %{112 => %{108 => %{101 => %{mark: :mark}}}}}}}

Trieval.new(~w/apple apply ape ample/) |> Trieval.insert(~w/zebra corgi/)
%Trieval.Trie{trie: %{...}}

longest_common_prefix(trie, binary)

@spec longest_common_prefix(Trieval.Trie.t([{:trie, map()}]), binary()) ::
  {[nil | bitstring()], list()}

Collects all binaries that begin with a given prefix. Returns matching binaries, along with matching binaries' longest common prefix. Example use-case would be for auto-completion.

Examples

iex> Trieval.new(~w/apple apply ape/) |> Trieval.longest_common_prefix("a")
{"ap", ["ape", "apple", "apply"]}

iex> Trieval.new(~w/apple apply ape ample/) |> Trieval.longest_common_prefix("z")
{nil, []}

new()

@spec new() :: Trieval.Trie.t([{:trie, map()}])

Returns a new trie. Providing no arguments creates an empty trie. Optionally, a binary, a list of binaries or a tuple of binaries can be passed to new/1.

Examples

iex> Trieval.new()
%Trieval.Trie{trie: %{}}

new(binaries)

@spec new(binary() | maybe_improper_list() | {binary(), any()}) ::
  Trieval.Trie.t([{:trie, map()}])

Returns a new trie containing lists of binaries representing the provided values passed to new/1. Optional values are a binary, a list of binaries or a tuple of binaries can be passed to new/1.

Examples

iex> Trieval.new("apple")
%Trieval.Trie{trie: %{97 => %{112 => %{112 => %{108 => %{101 => %{mark: :mark}}}}}}}

iex> Trieval.new(~w/apple apply ape ample/)
%Trieval.Trie{
          trie: %{
            97 => %{
              109 => %{112 => %{108 => %{101 => %{mark: :mark}}}},
              112 => %{
                101 => %{mark: :mark},
                112 => %{
                  108 => %{
                    101 => %{mark: :mark},
                    121 => %{mark: :mark}
                  }
                }
              }
            }
          }
        }

pattern(trie, pattern)

@spec pattern(Trieval.Trie.t([{:trie, map()}]), binary()) ::
  list() | {:error, <<_::64, _::_*8>>}

Collects all binaries match a given pattern. Returns either a list of matches or an error in the form {:error, reason}.

Patterns

 `*`      - Wildcard, matches any character.

 `[...]`  - Inclusion group, matches any character between brackets.

 `[^...]` - Exclusion group, matches any character not between brackets.

 `{...}`  - Capture group, must be named and can be combined with an
            inclusion or exclusion group, otherwise treated as a wildcard.
            All future instances of same name captures are swapped with
            the value of the initial capture.

Examples

iex> Trieval.new(~w/apple apply ape ample/) |> Trieval.pattern("a{1}{1}**")
["apple", "apply"]

iex> Trieval.new(~w/apple apply ape ample/) |> Trieval.pattern("*{1[^p]}{1}**")
[]

iex> Trieval.new(~w/apple apply zebra house/) |> Trieval.pattern("[hz]****")
["house", "zebra"]

iex> Trieval.new(~w/apple apply zebra house/) |> Trieval.pattern("[hz]***[^ea]")
[]

iex> Trieval.new(~w/apple apply zebra house/) |> Trieval.pattern("[hz]***[^ea")
{:error, "Dangling group (exclusion) starting at column 8, expecting ]"}

prefix(trie, binary)

@spec prefix(Trieval.Trie.t([{:trie, map()}]), binary()) :: list()

Collects all binaries that begin with a given prefix.

Examples

iex> Trieval.new(~w/apple apply ape ample/) |> Trieval.prefix("ap")
["ape", "apple", "apply"]

iex> Trieval.new(~w/apple apply ape ample/) |> Trieval.prefix("z")
[]