Module ets

A limited implementation of the Erlang/OTP ets module.

Data Types

access_type()


access_type() = private | protected | public

option()


option() = table_type() | {keypos, non_neg_integer()} | access_type()

options()


options() = [option()]

table()

abstract datatype: table()

table_type()


table_type() = set | bag | duplicate_bag

update_op()


update_op() = {pos_integer(), integer()} | {pos_integer(), integer(), integer(), integer()}

Function Index

delete/1Delete an ets table.
delete/2Delete all entries with the given key from an ets table.
delete_object/2Delete a specific object from an ets table.
insert/2Insert an entry into an ets table.
insert_new/2Insert an entry into an ets table only if the key does not already exist.
lookup/2Look up an entry in an ets table.
lookup_element/3Look up an element from an entry in an ets table.
lookup_element/4Look up an element from an entry in an ets table with a default value.
member/2Check if a key exists in an ets table.
new/2Create a new ets table.
take/2Return and delete all entries with the given key from an ets table.
update_counter/3Updates one or more counter values at Key in the table.
update_counter/4Updates one or more counter values at Key in the table.
update_element/3Update one or more elements of an existing entry in an ets table.
update_element/4Update one or more elements of an existing entry, inserting Default if missing.

Function Details

delete/1


delete(Table::table()) -> true

Table: a reference to the ets table

returns: true;

Delete an ets table.

delete/2


delete(Table::table(), Key::term()) -> true

Table: a reference to the ets table
Key: the key used to lookup one or more entries to delete

returns: true; otherwise, an error is raised if arguments are bad

Delete all entries with the given key from an ets table.

delete_object/2


delete_object(Table::table(), Object::tuple()) -> true

Table: a reference to the ets table
Object: the exact object to delete

returns: true; otherwise, an error is raised if arguments are bad

Delete a specific object from an ets table.

Unlike delete/2, which deletes all entries matching a key, this function deletes only entries that exactly match the given object. For bag tables, other objects sharing the same key are left intact. For duplicate_bag tables, all instances of the identical object are removed.

insert/2


insert(Table::table(), Entry::tuple() | [tuple()]) -> true

Table: a reference to the ets table
Entry: the entry or list of entries to insert

returns: true; otherwise, an error is raised if arguments are bad

Insert an entry into an ets table.

For set tables, an existing entry with the same key is overwritten. For bag tables, the object is added unless an identical object already exists. For duplicate_bag tables, the object is always added. The operation is atomic.

insert_new/2


insert_new(Table::table(), Entry::tuple() | [tuple()]) -> boolean()

Table: a reference to the ets table
Entry: the entry or list of entries to insert

returns: true if all entries were inserted; false if any key already exists

Insert an entry into an ets table only if the key does not already exist.

lookup/2


lookup(Table::table(), Key::term()) -> [tuple()]

Table: a reference to the ets table
Key: the key used to lookup one or more entries

returns: a list of matching tuples, or an empty list if none found

Look up an entry in an ets table.

For set tables, returns at most one element. For bag and duplicate_bag tables, returns all objects with the matching key.

lookup_element/3


lookup_element(Table::table(), Key::term(), Pos::pos_integer()) -> term() | [term()]

Table: a reference to the ets table
Key: the key used to lookup one or more entries
Pos: index of the element to retrieve (1-based)

returns: the element at position Pos from the matching tuple, or a list of such elements if the table is of type bag or duplicate_bag

Look up an element from an entry in an ets table.

lookup_element/4


lookup_element(Table::table(), Key::term(), Pos::pos_integer(), Default::term()) -> term() | [term()]

Table: a reference to the ets table
Key: the key used to lookup one or more entries
Pos: index of the element to retrieve (1-based)
Default: value returned if the key does not exist

returns: the element at position Pos from the matching tuple, or a list of such elements if the table is of type bag or duplicate_bag, or Default if the key does not exist

Look up an element from an entry in an ets table with a default value.

Unlike lookup_element/3, returns Default instead of raising badarg when the key does not exist.

member/2


member(Table::table(), Key::term()) -> boolean()

Table: a reference to the ets table
Key: the key to check for existence

returns: true if the key exists in the table; false otherwise

Check if a key exists in an ets table.

new/2


new(Name::atom(), Options::options()) -> table()

Name: the ets table name
Options: the options used to create the table

returns: A new ets table

Create a new ets table.

Supported table types are set, bag, and duplicate_bag. The ordered_set type is not currently supported.

take/2


take(Table::table(), Key::term()) -> [tuple()]

Table: a reference to the ets table
Key: the key used to look up and remove entries

returns: a list of the removed objects, or an empty list if none found

Return and delete all entries with the given key from an ets table.

update_counter/3


update_counter(Table::table(), Key::term(), Params::integer() | update_op() | [update_op()]) -> integer() | [integer()]

Table: a reference to the ets table
Key: the key used to look up the entry expecting to contain a tuple of integers or a single integer
Params: an integer increment, a single update operation, or a list of update operations. An update operation is a tuple{Pos, Increment} or {Pos, Increment, Threshold, SetValue}, where Pos is a 1-based index.

returns: the new counter value, or a list of new values when Params is a list

Updates one or more counter values at Key in the table.

update_counter/4


update_counter(Table::table(), Key::term(), Params::integer() | update_op() | [update_op()], Default::tuple()) -> integer() | [integer()]

Table: a reference to the ets table
Key: the key used to look up the entry expecting to contain a tuple of integers or a single integer
Params: an integer increment, a single update operation, or a list of update operations (see update_counter/3 for the format)
Default: a default object (tuple) to insert if the key does not exist, after which the update operation is applied to it

returns: the new counter value, or a list of new values when Params is a list

Updates one or more counter values at Key in the table.

Equivalent to update_counter/3, but inserts Default as a new entry if no object with Key exists, then performs the counter update on it.

update_element/3


update_element(Table::table(), Key::term(), ElementSpec::{pos_integer(), term()} | [{pos_integer(), term()}]) -> boolean()

Table: a reference to the ets table
Key: the key used to look up the entry to update
ElementSpec: a tuple {Pos, Value} or a list of such tuples, specifying the position(s) (1-based) and new value(s) to set

returns: true if the entry was updated; false if the key does not exist

Update one or more elements of an existing entry in an ets table.

The key field itself cannot be updated. Returns false if no entry with the given key exists.

update_element/4


update_element(Table::table(), Key::term(), ElementSpec::{pos_integer(), term()} | [{pos_integer(), term()}], Default::tuple()) -> boolean()

Table: a reference to the ets table
Key: the key used to look up the entry to update
ElementSpec: a tuple {Pos, Value} or a list of such tuples, specifying the position(s) (1-based) and new value(s) to set
Default: a default tuple to insert if the key does not exist

returns: true if the entry was updated or inserted; false if insertion failed

Update one or more elements of an existing entry, inserting Default if missing.

If no entry with the given key exists, inserts Default into the table, then applies the element updates.