ets v0.2.0 Ets.Set View Source

Module for creating and interacting with :ets tables of the type :set and :ordered_set.

Sets contain “records” which are tuples. Sets are configured with a key position via the keypos: integer option. If not specified, the default key position is 1. The element of the tuple record at the key position is that records key. For example, setting the keypos to 2 means the key of an inserted record {:a, :b} is :b:

iex> {:ok, set} = Set.new(keypos: 2)
iex> Set.put!(set, {:a, :b})
iex> Set.get(set, :a)
{:ok, nil}
iex> Set.get(set, :b)
{:ok, {:a, :b}}

When a record is added to the table with put, it will overwrite an existing record with the same key. put_new will only put the record if a matching key doesn’t already exist.

Examples

iex> {:ok, set} = Set.new(ordered: true)
iex> Set.put_new!(set, {:a, :b, :c})
iex> Set.to_list!(set)
[{:a, :b, :c}]
iex> Set.put_new!(set, {:d, :e, :f})
iex> Set.to_list!(set)
[{:a, :b, :c}, {:d, :e, :f}]
iex> Set.put_new(set, {:a, :g, :h})
{:error, :key_already_exists}
iex> Set.to_list!(set)
[{:a, :b, :c}, {:d, :e, :f}]

To insert multiple records in an atomic an isolated manner, use put_multi or put_multi_new.

Link to this section Summary

Functions

Same as delete/1 but unwraps or raises on error

Same as delete/2 but unwraps or raises on error

Deletes specified Set

Deletes record with specified key in specified Set

Same as first/1 but unwraps or raises on error

Returns the first key in the specified Set. Set must be ordered or error is returned

Same as get/3 but unwraps or raises on error

Returns record with specified key or the provided default (nil if not specified) if no record found

Same as has_key/2 but unwraps or raises on error

Determines if specified key exists in specified set

Same as info/1 but unwraps or raises on error

Returns information on the set

Same as last/1 but unwraps or raises on error

Returns the last key in the specified Set. Set must be ordered or error is returned

Same as match/1 but unwraps or raises on error

Same as match/2 but unwraps or raises on error

Same as match/3 but unwraps or raises on error

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

Returns records in the specified Set that match the specified pattern

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

Same as new/1 but unwraps or raises on error

Creates new set module with the specified options

Same as next/1 but unwraps or raises on error

Returns the next key in the specified Set

Same as previous/1 but raises on :error

Returns the previous key in the specified Set

Same as put/3 but unwraps or raises on error

Puts record into table. Overwrites records for existing keys

Same as put_multi/2 but unwraps or raises on error

Inserts multiple records in an atomic and isolated manner. Overwrites records for existing keys

Same as put_multi_new/2 but unwraps or raises on error

Same as put_multi/2 but returns error and doesn’t insert if one of the specified keys already exists

Same as put_new/2 but unwraps or raises on error

Same as insert/2 but returns error and doesn’t insert if key already exists

Same as to_list/1 but unwraps or raises on error

Returns contents of table as a list

Same as wrap_existing/1 but unwraps or raises on error

Wraps an existing :ets :set or :ordered_set in a Set struct

Link to this section Types

Link to this type set_options() View Source
set_options() :: [Ets.Base.option() | {:ordered, boolean()}]
Link to this type t() View Source
t() :: %Ets.Set{
  info: keyword(),
  ordered: boolean(),
  table: Ets.table_reference()
}

Link to this section Functions

Same as delete/1 but unwraps or raises on error.

Link to this function delete!(set, key) View Source
delete!(Ets.Set.t(), any()) :: Ets.Set.t()

Same as delete/2 but unwraps or raises on error.

Link to this function delete(set) View Source
delete(Ets.Set.t()) :: {:ok, Ets.Set.t()} | {:error, any()}

Deletes specified Set.

Examples

iex> {:ok, set} = Set.new()
iex> {:ok, _} = Set.info(set, true)
iex> {:ok, _} = Set.delete(set)
iex> Set.info(set, true)
{:error, :table_not_found}
Link to this function delete(set, key) View Source
delete(Ets.Set.t(), any()) :: {:ok, Ets.Set.t()} | {:error, any()}

Deletes record with specified key in specified Set.

Examples

iex> set = Set.new!()
iex> Set.put(set, {:a, :b, :c})
iex> Set.delete(set, :a)
iex> Set.get!(set, :a)
nil

Same as first/1 but unwraps or raises on error

Link to this function first(set) View Source
first(Ets.Set.t()) :: {:ok, any()} | {:error, any()}

Returns the first key in the specified Set. Set must be ordered or error is returned.

Examples

iex> set = Set.new!(ordered: true)
iex> Set.first(set)
{:error, :empty_table}
iex> Set.put!(set, {:key1, :val})
iex> Set.put!(set, {:key2, :val})
iex> Set.first(set)
{:ok, :key1}
Link to this function get!(set, key, default \\ nil) View Source
get!(Ets.Set.t(), any(), any()) :: tuple()

Same as get/3 but unwraps or raises on error.

Link to this function get(set, key, default \\ nil) View Source
get(Ets.Set.t(), any(), any()) :: {:ok, tuple()} | {:error, any()}

Returns record with specified key or the provided default (nil if not specified) if no record found.

Examples

iex> Set.new!()
iex> |> Set.put!({:a, :b, :c})
iex> |> Set.put!({:d, :e, :f})
iex> |> Set.get(:d)
{:ok, {:d, :e, :f}}
Link to this function has_key!(set, key) View Source
has_key!(Ets.Set.t(), any()) :: boolean()

Same as has_key/2 but unwraps or raises on error.

Link to this function has_key(set, key) View Source
has_key(Ets.Set.t(), any()) :: {:ok, boolean()} | {:error, any()}

Determines if specified key exists in specified set.

Examples

iex> set = Set.new!()
iex> Set.has_key(set, :key)
{:ok, false}
iex> Set.put(set, {:key, :value})
iex> Set.has_key(set, :key)
{:ok, true}
Link to this function info!(set, force_update \\ false) View Source
info!(Ets.Set.t(), boolean()) :: keyword()

Same as info/1 but unwraps or raises on error.

Link to this function info(set, force_update \\ false) View Source
info(Ets.Set.t(), boolean()) :: {:ok, keyword()} | {:error, any()}

Returns information on the set.

Second parameter forces updated information from ets, default (false) uses in-struct cached information. Force should be used when requesting size and memory.

Examples

iex> {:ok, set} = Set.new(ordered: true, keypos: 3, read_concurrency: true, compressed: false)
iex> {:ok, info} = Set.info(set)
iex> info[:read_concurrency]
true
iex> {:ok, _} = Set.put(set, {:a, :b, :c})
iex> {:ok, info} = Set.info(set)
iex> info[:size]
0
iex> {:ok, info} = Set.info(set, true)
iex> info[:size]
1

Same as last/1 but unwraps or raises on error

Link to this function last(set) View Source
last(Ets.Set.t()) :: {:ok, any()} | {:error, any()}

Returns the last key in the specified Set. Set must be ordered or error is returned.

Examples

iex> set = Set.new!(ordered: true)
iex> Set.last(set)
{:error, :empty_table}
iex> Set.put!(set, {:key1, :val})
iex> Set.put!(set, {:key2, :val})
iex> Set.last(set)
{:ok, :key2}
Link to this function match!(continuation) View Source
match!(any()) :: {[tuple()], any() | :end_of_table}

Same as match/1 but unwraps or raises on error.

Same as match/2 but unwraps or raises on error.

Link to this function match!(set, pattern, limit) View Source
match!(Ets.Set.t(), Ets.match_pattern(), non_neg_integer()) ::
  {[tuple()], any() | :end_of_table}

Same as match/3 but unwraps or raises on error.

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

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

Examples

iex> set = Set.new!(ordered: true)
iex> Set.put_multi!(set, [{:a, :b, :c, :d}, {:e, :b, :f, :g}, {:h, :b, :i, :j}])
iex> {:ok, {results, continuation}} = Set.match(set, {:"$1", :b, :"$2", :_}, 2)
iex> results
[[:a, :c], [:e, :f]]
iex> {:ok, {records2, continuation2}} = Set.match(continuation)
iex> records2
[[:h, :i]]
iex> continuation2
:end_of_table
Link to this function match(set, pattern) View Source
match(Ets.Set.t(), Ets.match_pattern()) :: {:ok, [tuple()]} | {:error, any()}

Returns records in the specified Set that match the specified pattern.

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

Examples

iex> Set.new!(ordered: true)
iex> |> Set.put_multi!([{:a, :b, :c, :d}, {:e, :c, :f, :g}, {:h, :b, :i, :j}])
iex> |> Set.match({:"$1", :b, :"$2", :_})
{:ok, [[:a, :c], [:h, :i]]}
Link to this function match(set, pattern, limit) View Source
match(Ets.Set.t(), Ets.match_pattern(), non_neg_integer()) ::
  {:ok, {[tuple()], any() | :end_of_table}} | {:error, any()}

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

Examples

iex> set = Set.new!(ordered: true)
iex> Set.put_multi!(set, [{:a, :b, :c, :d}, {:e, :b, :f, :g}, {:h, :b, :i, :j}])
iex> {:ok, {results, _continuation}} = Set.match(set, {:"$1", :b, :"$2", :_}, 2)
iex> results
[[:a, :c], [:e, :f]]

Same as new/1 but unwraps or raises on error.

Link to this function new(opts \\ []) View Source
new(set_options()) :: {:error, any()} | {:ok, Ets.Set.t()}

Creates new set module with the specified options.

Possible options:

  • name: when specified, creates a named table with the specified name
  • ordered: when true, creates :ordered_set, false creates :set. Defaults to false.
  • protection: :private, :protected, :public
  • heir: :none | {heir_pid, heir_data}
  • keypos: integer
  • read_concurrency: boolean
  • write_concurrency: boolean
  • compressed: boolean

Examples

iex> {:ok, set} = Set.new(ordered: true, keypos: 3, read_concurrency: true, compressed: false)
iex> Set.info!(set)[:read_concurrency]
true

# Named :ets tables via the name keyword
iex> {:ok, set} = Set.new(name: :my_ets_table)
iex> Set.info!(set)[:name]
:my_ets_table
Link to this function next!(set, key) View Source
next!(Ets.Set.t(), any()) :: any()

Same as next/1 but unwraps or raises on error

Link to this function next(set, key) View Source
next(Ets.Set.t(), any()) :: {:ok, any()} | {:error, any()}

Returns the next key in the specified Set.

The given key does not need to exist in the set. The key returned will be the first key that exists in the set which is subsequent in term order to the key given.

Set must be ordered or error is returned.

Examples

iex> set = Set.new!(ordered: true)
iex> Set.put!(set, {:key1, :val})
iex> Set.put!(set, {:key2, :val})
iex> Set.put!(set, {:key3, :val})
iex> Set.first(set)
{:ok, :key1}
iex> Set.next(set, :key1)
{:ok, :key2}
iex> Set.next(set, :key2)
{:ok, :key3}
iex> Set.next(set, :key3)
{:error, :end_of_table}
iex> Set.next(set, :a)
{:ok, :key1}
iex> Set.next(set, :z)
{:error, :end_of_table}
Link to this function previous!(set, key) View Source
previous!(Ets.Set.t(), any()) :: any()

Same as previous/1 but raises on :error

Returns previous key in table.

Link to this function previous(set, key) View Source
previous(Ets.Set.t(), any()) :: {:ok, any()} | {:error, any()}

Returns the previous key in the specified Set.

The given key does not need to exist in the set. The key returned will be the first key that exists in the set which is previous in term order to the key given.

Set must be ordered or error is returned.

Examples

iex> set = Set.new!(ordered: true)
iex> Set.put!(set, {:key1, :val})
iex> Set.put!(set, {:key2, :val})
iex> Set.put!(set, {:key3, :val})
iex> Set.last(set)
{:ok, :key3}
iex> Set.previous(set, :key3)
{:ok, :key2}
iex> Set.previous(set, :key2)
{:ok, :key1}
iex> Set.previous(set, :key1)
{:error, :start_of_table}
iex> Set.previous(set, :a)
{:error, :start_of_table}
iex> Set.previous(set, :z)
{:ok, :key3}

Same as put/3 but unwraps or raises on error.

Link to this function put(set, record) View Source
put(Ets.Set.t(), tuple()) :: {:ok, Ets.Set.t()} | {:error, any()}

Puts record into table. Overwrites records for existing keys

Examples

iex> {:ok, set} = Set.new(ordered: true)
iex> {:ok, _} = Set.put(set, {:a, :b, :c})
iex> {:ok, _} = Set.put(set, {:d, :e, :f})
iex> {:ok, _} = Set.put(set, {:d, :e, :f})
iex> Set.to_list(set)
{:ok, [{:a, :b, :c}, {:d, :e, :f}]}
Link to this function put_multi!(set, records) View Source
put_multi!(Ets.Set.t(), [tuple()]) :: Ets.Set.t()

Same as put_multi/2 but unwraps or raises on error.

Link to this function put_multi(set, records) View Source
put_multi(Ets.Set.t(), [tuple()]) :: {:ok, Ets.Set.t()} | {:error, any()}

Inserts multiple records in an atomic and isolated manner. Overwrites records for existing keys.

Examples

iex> {:ok, set} = Set.new(ordered: true)
iex> {:ok, _} = Set.put_multi(set, [{:a, :b, :c}, {:d, :e, :f}, {:d, :e, :f}])
iex> Set.to_list(set)
{:ok, [{:a, :b, :c}, {:d, :e, :f}]}
Link to this function put_multi_new!(set, records) View Source
put_multi_new!(Ets.Set.t(), [tuple()]) :: Ets.Set.t()

Same as put_multi_new/2 but unwraps or raises on error.

Link to this function put_multi_new(set, records) View Source
put_multi_new(Ets.Set.t(), [tuple()]) :: {:ok, Ets.Set.t()} | {:error, any()}

Same as put_multi/2 but returns error and doesn’t insert if one of the specified keys already exists.

Examples

iex> {:ok, set} = Set.new(ordered: true)
iex> {:ok, _} = Set.put_multi_new(set, [{:a, :b, :c}, {:d, :e, :f}, {:d, :e, :f}])
iex> {:error, :key_already_exists} = Set.put_multi_new(set, [{:a, :b, :c}, {:d, :e, :f}, {:d, :e, :f}])
iex> Set.to_list(set)
{:ok, [{:a, :b, :c}, {:d, :e, :f}]}
Link to this function put_new!(set, record) View Source
put_new!(Ets.Set.t(), tuple()) :: Ets.Set.t()

Same as put_new/2 but unwraps or raises on error.

Link to this function put_new(set, record) View Source
put_new(Ets.Set.t(), tuple()) :: {:ok, Ets.Set.t()} | {:error, any()}

Same as insert/2 but returns error and doesn’t insert if key already exists.

Examples

iex> {:ok, set} = Set.new(ordered: true)
iex> {:ok, _} = Set.put_new(set, {:a, :b, :c})
iex> {:ok, _} = Set.put_new(set, {:d, :e, :f})
iex> Set.put_new(set, {:d, :e, :f})
{:error, :key_already_exists}
Link to this function to_list!(set) View Source
to_list!(Ets.Set.t()) :: [tuple()]

Same as to_list/1 but unwraps or raises on error.

Link to this function to_list(set) View Source
to_list(Ets.Set.t()) :: {:ok, [tuple()]} | {:error, any()}

Returns contents of table as a list.

Examples

iex> Set.new!(ordered: true) iex> |> Set.put!({:a, :b, :c}) iex> |> Set.put!({:d, :e, :f}) iex> |> Set.put!({:d, :e, :f}) iex> |> Set.to_list() {:ok, [{:a, :b, :c}, {:d, :e, :f}]}

Link to this function wrap_existing!(table_identifier) View Source
wrap_existing!(Ets.table_identifier()) :: Ets.Set.t()

Same as wrap_existing/1 but unwraps or raises on error.

Link to this function wrap_existing(table_identifier) View Source
wrap_existing(Ets.table_identifier()) :: {:ok, Ets.Set.t()} | {:error, any()}

Wraps an existing :ets :set or :ordered_set in a Set struct.

Examples

iex> :ets.new(:my_ets_table, [:set, :named_table])
iex> {:ok, set} = Set.wrap_existing(:my_ets_table)
iex> Set.info!(set)[:name]
:my_ets_table