ets v0.1.0 Ets

Ets, an Elixir wrapper for Erlang’s :ets module.

New :ets tables can be created using the Ets.Table.New module.

All functions return {:error, :table_not_found} (or raise in bang versions) when the table does not exist.

Link to this section Summary

Functions

Deletes specified key from table

Same as delete_all/2 but raises on :error

Deletes all entries in the table

Same as first/1 but raises on :error

Looks up the first key in the specified table

Same as has_key/2 but raises on :error

Determines if specified key exists in specified table

The same as insert/3, but raises on :error

Inserts a value into the specified table with the specified key

The same as insert_multi/2, but raises on :error

Same as insert_multi/3, but raises on :error

Inserts a list of key/values pairs into specified table in an atomic and isolated manner

Inserts a list of values for the specified key into specified table in an atomic and isolated manner

Inserts a list of key/values pairs into specified table in an atomic and isolated manner

The same as insert_new/3, but raises on :error

Inserts a value into the specified table with the specified key

Same as last/1 but raises on :error

Looks up the last key in the specified table

Same as lookup/2 but raises on error

Looks up value for given key in specified table

Same as lookup_multi/2 but raises on :error

Looks up values for given key in specified table

Same as next/1 but raises on :error

Looks up the next key in the specified table

Same as previous/1 but raises on :error

Looks up the previous key in the specified table

Link to this section Types

Link to this type ets_table_reference()
ets_table_reference() :: :ets.tid()
Link to this type table_identifier()
table_identifier() :: table_name() | ets_table_reference()
Link to this type table_name()
table_name() :: atom()

Link to this section Functions

Link to this macro catch_table_already_exists(table_name, list) (macro)
Link to this function delete!(key, table)
delete!(any(), table_identifier()) :: any()
Link to this function delete(key, table)
delete(any(), table_identifier()) :: {:ok, any()} | {:error, :table_not_found}

Deletes specified key from table.

Returns :ok/:error tuple. :ok tuple contains specified key.

Examples

iex> Ets.Table.New.bag(:my_ets_table)
iex> Ets.insert(:a, :my_ets_table, :key)
iex> Ets.lookup!(:key, :my_ets_table)
:a
iex> Ets.delete(:key, :my_ets_table)
{:ok, :key}
iex> Ets.lookup!(:key, :my_ets_table)
nil
Link to this function delete_all!(table)
delete_all!(table_identifier()) :: table_identifier()

Same as delete_all/2 but raises on :error.

Returns table identifier passed to function.

Link to this function delete_all(table)
delete_all(table_identifier()) ::
  {:ok, table_identifier()} | {:error, :table_not_found}

Deletes all entries in the table.

Returns :ok/:error tuple. :ok tuple contains table identifier passed to function.

Examples

iex> Ets.Table.New.set(:my_ets_table)
iex> Ets.insert(:val, :my_ets_table, :key)
iex> Ets.delete_all(:my_ets_table)
iex> Ets.Table.to_list(:my_ets_table)
{:ok, []}
Link to this function first!(table)
first!(table_identifier()) :: any()

Same as first/1 but raises on :error

Returns first key in table.

Link to this function first(table)
first(table_identifier()) ::
  {:ok, any()} | {:error, :empty_table | :table_not_found}

Looks up the first key in the specified table.

Returns :ok/:error tuples. :ok tuple contains first key.

Examples

iex> Ets.Table.New.ordered_set(:my_ets_table)
iex> Ets.first(:my_ets_table)
{:error, :empty_table}
iex> Ets.insert(:val, :my_ets_table, :key1)
iex> Ets.insert(:val, :my_ets_table, :key2)
iex> Ets.first(:my_ets_table)
{:ok, :key1}
Link to this function has_key!(key, table)
has_key!(any(), table_identifier()) :: boolean()

Same as has_key/2 but raises on :error.

Returns boolean indicating if key was found.

Link to this function has_key(key, table)
has_key(any(), table_identifier()) ::
  {:ok, boolean()} | {:error, :table_not_found}

Determines if specified key exists in specified table.

Returns :ok/:error tuples. :ok tuple contains boolean indicating if the key was found.

Examples

iex> Ets.Table.New.set(:my_ets_table)
iex> Ets.has_key(:key, :my_ets_table)
{:ok, false}
iex> Ets.insert(:a, :my_ets_table, :key)
iex> Ets.has_key(:key, :my_ets_table)
{:ok, true}
Link to this function insert!(value, table, key)
insert!(any(), table_identifier(), any()) :: any()

The same as insert/3, but raises on :error.

Returns inserted value.

Link to this function insert(value, table, key)
insert(any(), table_identifier(), any()) ::
  {:ok, any()} | {:error, :table_not_found | :invalid_key}

Inserts a value into the specified table with the specified key.

Returns :ok or :error tuple. :ok tuple contains with inserted value.

Examples

iex> Ets.Table.New.bag(:my_ets_table)
iex> Ets.insert(:a, :my_ets_table, :my_key)
{:ok, :a}

Designed to be used in pipelines:

iex> Ets.Table.New.bag(:my_ets_table)
iex> _inserted = "myVal"
iex> |> String.to_atom()
iex> |> Ets.insert(:my_ets_table, :my_key)
{:ok, :myVal}
Link to this function insert_multi!(key_value_pairs, table)
insert_multi!([{any(), any()}], table_identifier()) :: [{any(), any()}]

The same as insert_multi/2, but raises on :error.

Returns inserted key/value pairs.

Link to this function insert_multi!(values, table, key)
insert_multi!(list(), table_identifier(), any()) :: list()

Same as insert_multi/3, but raises on :error.

Returns inserted values.

Link to this function insert_multi(key_value_pairs, table)
insert_multi([{any(), any()}], table_identifier()) ::
  {:ok, [{any(), any()}]}
  | {:error, :table_not_found | :invalid_key_value_pair}

Inserts a list of key/values pairs into specified table in an atomic and isolated manner.

First parameter is a list of two-item tuples, the first item is the key, and the second the value to insert for that key. Returns :ok/:error tuples. :ok tuple contains inserted values.

Examples

iex> Ets.Table.New.bag(:my_ets_table)
iex> [{:key1, :val1}, {:key2, :val2}]
iex> |> Ets.insert_multi(:my_ets_table)
{:ok, [{:key1, :val1}, {:key2, :val2}]}
Link to this function insert_multi(values, table, key)
insert_multi(list(), table_identifier(), any()) ::
  {:ok, list()} | {:error, :table_not_found | :invalid_key}

Inserts a list of values for the specified key into specified table in an atomic and isolated manner.

First parameter is a list of values. Returns :ok/:error tuples. :ok tuple contains inserted values.

Examples

iex> Ets.Table.New.bag(:my_ets_table)
iex> Ets.insert_multi([:val1, :val2], :my_ets_table, :key)
{:ok, [:val1, :val2]}
iex> Ets.Table.to_list(:my_ets_table)
{:ok, [{:key, :val1}, {:key, :val2}]}
Link to this function insert_multi_new!(key_value_pairs, table)
insert_multi_new!([{any(), any()}], table_identifier()) :: [{any(), any()}]

Same as insert_multi_new/2 but raises on :error.

Returns inserted key/value pairs.

Link to this function insert_multi_new(key_value_pairs, table)
insert_multi_new([{any(), {any()}}], table_identifier()) ::
  {:error, :key_already_exists | :invalid_key_value_pair | :table_not_found}
  | {:ok, [{any(), any()}]}

Inserts a list of key/values pairs into specified table in an atomic and isolated manner.

First parameter is a list of two-item tuples ({key, value}). Returns :ok/:error tuples. :ok tuple contains inserted values. :error returned if key already exists.

Examples

iex> Ets.Table.New.bag(:my_ets_table)
iex> vals = [{:key1, :val1}, {:key2, :val2}]
iex> Ets.insert_multi_new(vals, :my_ets_table)
{:ok, [{:key1, :val1}, {:key2, :val2}]}
iex> Ets.insert_multi_new(vals, :my_ets_table)
{:error, :key_already_exists}
Link to this function insert_new!(value, table, key)
insert_new!(any(), table_identifier(), any()) :: list()

The same as insert_new/3, but raises on :error.

Returns inserted value.

Link to this function insert_new(value, table, key)
insert_new(any(), table_identifier(), any()) ::
  {:error, :key_already_exists | :table_not_found | :invalid_key}
  | {:ok, any()}

Inserts a value into the specified table with the specified key.

Returns :ok or :error tuple. :ok tuple contains inserted value. Returns error if key already exists in table.

Examples

iex> Ets.Table.New.bag(:my_ets_table)
iex> Ets.insert_new(:a, :my_ets_table, :my_key)
{:ok, :a}
iex> Ets.insert_new(:a, :my_ets_table, :my_key)
{:error, :key_already_exists}
Link to this function last!(table)
last!(table_identifier()) :: any()

Same as last/1 but raises on :error

Returns last key in table.

Link to this function last(table)
last(table_identifier()) ::
  {:ok, any()} | {:error, :empty_table | :table_not_found}

Looks up the last key in the specified table.

Returns :ok/:error tuples. :ok tuple contains last key.

Examples

iex> Ets.Table.New.ordered_set(:my_ets_table)
iex> Ets.last(:my_ets_table)
{:error, :empty_table}
iex> Ets.insert(:val, :my_ets_table, :key1)
iex> Ets.insert(:val, :my_ets_table, :key2)
iex> Ets.last(:my_ets_table)
{:ok, :key2}
Link to this function lookup!(key, table)
lookup!(any(), table_identifier()) :: any() | nil

Same as lookup/2 but raises on error.

Returns found value or nil if not found.

Link to this function lookup(key, table)
lookup(any(), table_identifier()) ::
  {:ok, any() | nil} | {:error, :multi_found | :table_not_found}

Looks up value for given key in specified table.

Expects zero or one value found. For bag/duplicate_bag, use lookup_multi

Returns :ok/:error tuples. :ok tuple contains found value, or nil. :error returned on multiple found

Examples

iex> Ets.Table.New.bag(:my_ets_table)
iex> Ets.lookup(:key, :my_ets_table)
{:ok, nil}
iex> Ets.insert(:a, :my_ets_table, :key)
iex> Ets.lookup(:key, :my_ets_table)
{:ok, :a}
iex> Ets.insert(:b, :my_ets_table, :key)
iex> Ets.lookup(:key, :my_ets_table)
{:error, :multi_found}
Link to this function lookup_multi!(key, table)
lookup_multi!(any(), table_identifier()) :: [any()]

Same as lookup_multi/2 but raises on :error.

Returns list of found values.

Link to this function lookup_multi(key, table)
lookup_multi(any(), table_identifier()) ::
  {:ok, [any()]} | {:error, :table_not_found}

Looks up values for given key in specified table.

Returns :ok/:error tuples. :ok tuple contains list of found values. For sets, consider using lookup/2 to avoid having to unwrap list.

Examples

iex> Ets.Table.New.bag(:my_ets_table)
iex> Ets.lookup_multi(:key, :my_ets_table)
{:ok, []}
iex> Ets.insert(:a, :my_ets_table, :key)
iex> Ets.insert(:b, :my_ets_table, :key)
iex> Ets.insert(:c, :my_ets_table, :key)
iex> Ets.lookup_multi(:key, :my_ets_table)
{:ok, [:a, :b, :c]}
Link to this function next!(key, table)
next!(any(), table_identifier()) :: any()

Same as next/1 but raises on :error.

Returns next key in table.

Link to this function next(key, table)
next(any(), table_identifier()) ::
  {:ok, any()} | {:error, :end_of_table | :table_not_found}

Looks up the next key in the specified table.

Returns :ok/:error tuples. :ok tuple contains next key. {:error, :end_of_table} when end of table reached

Examples

iex> Ets.Table.New.ordered_set(:my_ets_table)
iex> Ets.insert(:val, :my_ets_table, :key1)
iex> Ets.insert(:val, :my_ets_table, :key2)
iex> Ets.next(:key1, :my_ets_table)
{:ok, :key2}
iex> Ets.next(:key2, :my_ets_table)
{:error, :end_of_table}
Link to this function previous!(key, table)
previous!(any(), table_identifier()) :: any()

Same as previous/1 but raises on :error

Returns previous key in table.

Link to this function previous(key, table)
previous(any(), table_identifier()) ::
  {:ok, any()} | {:error, :start_of_table | :table_not_found}

Looks up the previous key in the specified table.

Returns :ok/:error tuples. :ok tuple contains previous key. {:error, :start_of_table} when start of table reached.

Examples

iex> Ets.Table.New.ordered_set(:my_ets_table)
iex> Ets.insert(:val, :my_ets_table, :key1)
iex> Ets.insert(:val, :my_ets_table, :key2)
iex> Ets.previous(:key2, :my_ets_table)
{:ok, :key1}
iex> Ets.previous(:key1, :my_ets_table)
{:error, :start_of_table}