ets v0.1.0 Ets.Record

Contains advanced functions for accessing :ets tables using the tuple/record notation. This module retains most of the improvements found in the Ets module (such as improved error handling and pipeline optimized parameters), but retains the tuple/record concept.

Link to this section Summary

Functions

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

Inserts a record into the specified table

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

Inserts a list of records into specified table in an atomic and isolated manner

Inserts a list of records into specified table in an atomic and isolated manner

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

Inserts a value into the specified table with the specified key

Same as lookup/2 but raises on error

Looks up record for given key in specified table

Same as lookup_multi/2 but raises on :error

Looks up records for given key in specified table

Same as match/2 but raises on error

Same as match/3 but raises on error

Matches next set of records from a match/3 or match/1 continuation

Matches records in the specified table against the specified pattern

Same as match/2 but limits number of results to the specified limit

Link to this section Types

Link to this type match_pattern()
match_pattern() :: atom() | tuple()

Link to this section Functions

Link to this macro catch_table_already_exists(table_name, list) (macro)
Link to this function insert!(value, table)
insert!(tuple(), Ets.table_identifier()) :: any()

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

Returns inserted value.

Link to this function insert(record, table)
insert(tuple(), Ets.table_identifier()) ::
  {:ok, tuple()} | {:error, :table_not_found | :duplicate_record}

Inserts a record into the specified table.

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

Examples

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

Designed to be used in pipelines:

iex> Ets.Table.New.bag(:my_ets_table)
iex> _inserted = [1, "John", "Doe", 35, "Boston"]
iex> |> List.to_tuple()
iex> |> Ets.Record.insert(:my_ets_table)
{:ok, {1, "John", "Doe", 35, "Boston"}}
iex> Ets.Record.lookup(1, :my_ets_table)
{:ok, {1, "John", "Doe", 35, "Boston"}}
Link to this function insert_multi!(records, table)
insert_multi!([tuple()], Ets.table_identifier()) :: [{any(), any()}]

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

Returns inserted records.

Link to this function insert_multi(records, table)
insert_multi([tuple()], Ets.table_identifier()) ::
  {:ok, [{any(), any()}]} | {:error, :table_not_found}

Inserts a list of records into specified table in an atomic and isolated manner.

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

Examples

iex> Ets.Table.New.bag(:my_ets_table)
iex> [{1, "John", "Doe", 35, "Boston"}, {2, "Jim", "Smith", 27, "Austin"}]
iex> |> Ets.Record.insert_multi(:my_ets_table)
{:ok, [{1, "John", "Doe", 35, "Boston"}, {2, "Jim", "Smith", 27, "Austin"}]}
Link to this function insert_multi_new!(records, table)
insert_multi_new!([tuple()], Ets.table_identifier()) :: [tuple()]

Same as insert_multi_new/2 but raises on :error.

Returns inserted records.

Link to this function insert_multi_new(records, table)
insert_multi_new([tuple()], Ets.table_identifier()) ::
  {:error, :key_already_exists | :record_already_exists | :table_not_found}
  | {:ok, [tuple()]}

Inserts a list of records into specified table in an atomic and isolated manner.

First parameter is a list of record tuples. Returns :ok/:error tuples. :ok tuple contains inserted records. :error returned if key or record already exists.

Examples

iex> Ets.Table.New.bag(:my_ets_table)
iex> vals = [{1, "John", "Doe", 35, "Boston"}, {2, "Jim", "Smith", 27, "Austin"}]
iex> Ets.Record.insert_multi_new(vals, :my_ets_table)
{:ok, [{1, "John", "Doe", 35, "Boston"}, {2, "Jim", "Smith", 27, "Austin"}]}
iex> Ets.Record.insert_multi_new(vals, :my_ets_table)
{:error, :key_already_exists}

iex> Ets.Table.New.duplicate_bag(:my_ets_table)
iex> vals = [{1, "John", "Doe", 35, "Boston"}, {2, "Jim", "Smith", 27, "Austin"}]
iex> Ets.Record.insert_multi_new(vals, :my_ets_table)
{:ok, [{1, "John", "Doe", 35, "Boston"}, {2, "Jim", "Smith", 27, "Austin"}]}
iex> Ets.Record.insert_multi_new(vals, :my_ets_table)
{:error, :record_already_exists}
Link to this function insert_new!(record, table)
insert_new!(tuple(), Ets.table_identifier()) :: tuple()

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

Returns inserted value.

Link to this function insert_new(record, table)
insert_new(tuple(), Ets.table_identifier()) ::
  {:error, :key_already_exists | :table_not_found} | {:ok, tuple()}

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.Record.insert_new({:a, :b}, :my_ets_table)
{:ok, {:a, :b}}
iex> Ets.Record.insert_new({:a, :b}, :my_ets_table)
{:error, :key_already_exists}
Link to this function lookup!(key, table)
lookup!(any(), Ets.table_identifier()) :: tuple() | 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(), Ets.table_identifier()) ::
  {:ok, tuple() | nil} | {:error, :multi_found | :table_not_found}

Looks up record for given key in specified table.

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

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

Examples

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

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(), Ets.table_identifier()) ::
  {:ok, [tuple()]} | {:error, :table_not_found}

Looks up records for given key in specified table.

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

Examples

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

Same as match/2 but raises on error.

Returns list of matched tuple records.

Link to this function match!(pattern, table, limit)

Same as match/3 but raises on error.

Returns list of matches, each themeselves a list, and a continuation for use in match/1

Link to this function match(continuation)
match(any()) ::
  {:ok, :end_of_table | {[tuple()], any()}} | {:error, :table_not_found}

Matches next set of records from a match/3 or match/1 continuation

Returns :ok/:error tuples. :ok tuple contains :end_of_table or a list of matches, each themselves a list, and a Continuation for use in match/1

See match/3 for examples.

Link to this function match(pattern, table)
match(match_pattern(), Ets.table_identifier()) ::
  {:ok, [list()]} | {:error, :table_not_found}

Matches records in the specified table against the specified pattern.

Returns :ok/:error tuples. :ok tuple contains a list of matches, each themselves a list.

For more information on the match pattern, see the erlang documentation

Link to this function match(pattern, table, limit)
match(match_pattern(), Ets.table_identifier(), non_neg_integer()) ::
  {:ok, :end_of_table | {[tuple()], any()}} | {:error, :table_not_found}

Same as match/2 but limits number of results to the specified limit.

Returns :ok/:error tuples. :ok tuple contains :end_of_table or a list of matches, each themselves a list, and a Continuation for use in match/1

Examples

iex> Ets.Table.New.ordered_set(:my_ets_table)
iex> Ets.Record.insert_multi([{:a, :b, :c, :d}, {:e, :b, :f, :g}, {:h, :b, :i, :j}], :my_ets_table)
iex> {:ok, {records, continuation}} = Ets.Record.match({:"$1", :b, :"$2", :_}, :my_ets_table, 2)
iex> records
[[:a, :c], [:e, :f]]
iex> {:ok, {records2, continuation2}} = Ets.Record.match(continuation)
iex> records2
[[:h, :i]]
iex> continuation2
:end_of_table