ets v0.5.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})
iex> Set.to_list!(set)
[{:a, :b, :c}, {:d, :e, :f}]
put
and put_new
take either a single tuple or a list of tuples. When inserting multiple records,
they are inserted in an atomic an isolated manner. put_new
doesn’t insert any records if any of
the new keys already exist in the set.
To make your set ordered (which maps to the :ets
table type :ordered_set
), specify ordered: true
in the options list. An ordered set will store records in term order of the key of the record. This is
helpful when using things like first
, last
, previous
, next
, and to_list
, but comes with the penalty of
log(n) insert time vs consistent insert time of an unordered set.
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 delete_all/1
but unwraps or raises on error
Deletes all records 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 get_element/3
but unwraps or raises on error
Returns element in specified position of record with specified key
Same as get_table/1
but unwraps or raises on error
Returns underlying :ets
table reference
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/2
but unwraps or raises on error
Puts tuple record or list of tuple records into table. Overwrites records for existing key(s)
Same as put_new/2
but unwraps or raises on error
Same as put/2
but doesn’t put any records if one of the given keys already exists
Same as select/2
but unwraps or raises on error
Returns records in the specified Set that match the specified match specification
Same as select_delete/2
but unwraps or raises on error
Deletes records in the specified Set that match the specified match specification
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
set_options() :: [Ets.Base.option() | {:ordered, boolean()}]
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.
Same as delete/2
but unwraps or raises on error.
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}
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 delete_all/1
but unwraps or raises on error.
Deletes all records in specified Set.
Examples
iex> set = Set.new!()
iex> set
iex> |> Set.put!({:a, :b, :c})
iex> |> Set.put!({:b, :b, :c})
iex> |> Set.put!({:c, :b, :c})
iex> |> Set.to_list!()
[{:c, :b, :c}, {:b, :b, :c}, {:a, :b, :c}]
iex> Set.delete_all(set)
iex> Set.to_list!(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.
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}
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.
Examples
iex> Set.new!()
iex> |> Set.put!({:a, :b, :c})
iex> |> Set.put!({:d, :e, :f})
iex> |> Set.get(:d)
{:ok, {:d, :e, :f}}
get_element!(Ets.Set.t(), any(), non_neg_integer()) :: any()
Same as get_element/3
but unwraps or raises on error.
get_element(Ets.Set.t(), any(), non_neg_integer()) :: {:ok, any()} | {:error, any()}
Returns element in specified position of record with specified key.
Examples
iex> Set.new!()
iex> |> Set.put!({:a, :b, :c})
iex> |> Set.put!({:d, :e, :f})
iex> |> Set.get_element(:d, 2)
{:ok, :e}
get_table!(Ets.Set.t()) :: Ets.ets_table_reference()
Same as get_table/1
but unwraps or raises on error
get_table(Ets.Set.t()) :: {:ok, Ets.ets_table_reference()}
Returns underlying :ets
table reference.
For use in functions that are not yet implemented. If you find yourself using this, please consider
submitting a PR to add the necessary function to Ets
.
Examples
iex> set = Set.new!(name: :my_ets_table)
iex> {:ok, table} = Set.get_table(set)
iex> info = :ets.info(table)
iex> info[:name]
:my_ets_table
Same as has_key/2
but unwraps or raises on error.
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}
Same as info/1
but unwraps or raises on error.
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
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}
Same as match/1
but unwraps or raises on error.
match!(Ets.Set.t(), Ets.match_pattern()) :: [tuple()]
Same as match/2
but unwraps or raises on error.
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.
Matches next set of records from a match/3 or match/1 continuation.
Examples
iex> set = Set.new!(ordered: true)
iex> Set.put!(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
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!([{:a, :b, :c, :d}, {:e, :c, :f, :g}, {:h, :b, :i, :j}])
iex> |> Set.match({:"$1", :b, :"$2", :_})
{:ok, [[:a, :c], [:h, :i]]}
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!(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.
new(set_options()) :: {:error, any()} | {:ok, Ets.Set.t()}
Creates new set module with the specified options.
Note that the underlying :ets table will be attached to the process that calls new
and will be destroyed
if that process dies.
Possible options:
name:
when specified, creates a named table with the specified nameordered:
when true, records in set are ordered (default false)protection:
:private, :protected, :public (default :protected)heir:
:none | {heir_pid, heir_data} (default :none)keypos:
integer (default 1)read_concurrency:
boolean (default false)write_concurrency:
boolean (default false)compressed:
boolean (default false)
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
Same as next/1
but unwraps or raises on error
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}
Same as previous/1
but raises on :error
Returns previous key in table.
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/2
but unwraps or raises on error.
Puts tuple record or list of tuple records into table. Overwrites records for existing key(s).
Inserts multiple records in an atomic and isolated manner.
Examples
iex> {:ok, set} = Set.new(ordered: true)
iex> {:ok, _} = Set.put(set, [{:a, :b, :c}, {:d, :e, :f}])
iex> {:ok, _} = Set.put(set, {:g, :h, :i})
iex> {:ok, _} = Set.put(set, {:d, :x, :y})
iex> Set.to_list(set)
{:ok, [{:a, :b, :c}, {:d, :x, :y}, {:g, :h, :i}]}
Same as put_new/2
but unwraps or raises on error.
Same as put/2
but doesn’t put any records if one of the given keys already exists.
Examples
iex> set = Set.new!(ordered: true)
iex> {:ok, _} = Set.put_new(set, [{:a, :b, :c}, {:d, :e, :f}])
iex> {:ok, _} = Set.put_new(set, [{:a, :x, :y}, {:g, :h, :i}]) # skips due to duplicate :a key
iex> {:ok, _} = Set.put_new(set, {:d, :z, :zz}) # skips due to duplicate :d key
iex> Set.to_list!(set)
[{:a, :b, :c}, {:d, :e, :f}]
select!(Ets.Set.t(), Ets.match_spec()) :: [tuple()]
Same as select/2
but unwraps or raises on error.
select(Ets.Set.t(), Ets.match_spec()) :: {:ok, [tuple()]} | {:error, any()}
Returns records in the specified Set that match the specified match specification.
For more information on the match specification, see the erlang documentation
Examples
iex> Set.new!(ordered: true)
iex> |> Set.put!([{:a, :b, :c, :d}, {:e, :c, :f, :g}, {:h, :b, :i, :j}])
iex> |> Set.select([{{:"$1", :b, :"$2", :_},[],[:"$$"]}])
{:ok, [[:a, :c], [:h, :i]]}
select_delete!(Ets.Set.t(), Ets.match_spec()) :: [tuple()]
Same as select_delete/2
but unwraps or raises on error.
select_delete(Ets.Set.t(), Ets.match_spec()) :: {:ok, [tuple()]} | {:error, any()}
Deletes records in the specified Set that match the specified match specification.
For more information on the match specification, see the erlang documentation
Examples
iex> set = Set.new!(ordered: true)
iex> set
iex> |> Set.put!([{:a, :b, :c, :d}, {:e, :c, :f, :g}, {:h, :b, :c, :h}])
iex> |> Set.select_delete([{{:"$1", :b, :"$2", :_},[{:"==", :"$2", :c}],[true]}])
{:ok, 2}
iex> Set.to_list!(set)
[{:e, :c, :f, :g}]
Same as to_list/1
but unwraps or raises on error.
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}]}
wrap_existing!(Ets.table_identifier()) :: Ets.Set.t()
Same as wrap_existing/1
but unwraps or raises on error.
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