rasa/table

Type-safe key-value tables backed by Erlang’s ETS. Tables are configured using a builder pattern, where you specify the table type (Set or OrderedSet) and access level (Public, Protected, or Private) before creating the table.

Requires OTP 27 or later.

Types

Access

</>

The access level of an ETS table. Public allows any process to read and write. Protected allows any process to read but only the owner to write. Private restricts both reads and writes to the owning process.

pub type Access {
  Public
  Protected
  Private
}

Constructors

```
Public
```
```
Protected
```
```
Private
```

Builder

opaque </>

A Table builder. Defaults to Set and Protected, matching the defaults specified by the erlang ets module.

pub opaque type Builder

Kind

</>

The type of ETS table. Set tables have unordered keys. OrderedSet tables maintain keys in sorted order.

pub type Kind {
  Set
  OrderedSet
}

Constructors

```
Set
```
```
OrderedSet
```

Table

opaque </>

An ETS table for storing key/value pairs

pub opaque type Table(a, b)

Values

access

</>

pub fn access(table: Table(a, b)) -> Result(Access, Nil)

Returns the table’s Access level (Public, Protected, or Private).

build

</>

pub fn build(builder: Builder) -> Table(a, b)

Returns a new ETS table configured according to the provided Builder.

delete

</>

pub fn delete(table: Table(a, b), key: a) -> Result(Nil, Nil)

Removes a key and its value from the table. Succeeds even if the key does not exist in the table.

delete_first

</>

pub fn delete_first(table: Table(a, b)) -> Result(#(a, b), Nil)

Removes and returns the first key-value pair from the table. Returns Error(Nil) if the table is empty. The order is guaranteed only for OrderedSet tables.

For Public tables accessed from multiple processes, if another process deletes the first entry between the lookup and the removal, the operation retries from the new first entry.

delete_last

</>

pub fn delete_last(table: Table(a, b)) -> Result(#(a, b), Nil)

Removes and returns the last key-value pair from the table. Returns Error(Nil) if the table is empty. The order is guaranteed only for OrderedSet tables.

For Public tables accessed from multiple processes, if another process deletes the last entry between the lookup and the removal, the operation retries from the new last entry.

drop

</>

pub fn drop(table: Table(a, b)) -> Result(Nil, Nil)

Deletes the table.

first

</>

pub fn first(table: Table(a, b)) -> Result(#(a, b), Nil)

Returns the first key-value pair in the table without removing it from the table. The order is guaranteed only for OrderedSet tables. See the ets docs for more details.

insert

</>

pub fn insert(
  table: Table(a, b),
  key: a,
  value: b,
) -> Result(Nil, Nil)

Inserts a key and value into the table. If the key already exists, its value is replaced with the new one.

insert_new

</>

pub fn insert_new(
  table: Table(a, b),
  key: a,
  value: b,
) -> Result(Nil, Nil)

Inserts a key and value into the table only if the key does not already exist. Returns Error(Nil) if the key is already present.

is_empty

</>

pub fn is_empty(table: Table(a, b)) -> Bool

Determines whether or not the table is empty. Returns True if the table does not exist.

kind

</>

pub fn kind(table: Table(a, b)) -> Result(Kind, Nil)

Returns the table’s Kind (Set or OrderedSet).

last

</>

pub fn last(table: Table(a, b)) -> Result(#(a, b), Nil)

Returns the last key-value pair in the table without removing it from the table. The order is guaranteed only for OrderedSet tables. See the ets docs for more details.

lookup

</>

pub fn lookup(table: Table(a, b), key: a) -> Result(b, Nil)

Returns the value associated with the given key, or Error(Nil) if the key does not exist.

member

</>

pub fn member(table: Table(a, b), key: a) -> Result(Bool, Nil)

Returns Ok(True) if the table contains the given key, Ok(False) if it does not, or Error(Nil) if the table does not exist.

new

</>

pub fn new() -> Builder

Returns a Builder. Defaults to Set and Protected.

size

</>

pub fn size(table: Table(a, b)) -> Result(Int, Nil)

Returns the size of the table.

to_list

</>

pub fn to_list(table: Table(a, b)) -> Result(List(#(a, b)), Nil)

Returns all entries in the table as a list of key-value tuples. The order is guaranteed only for OrderedSet tables.

with_access

</>

pub fn with_access(builder: Builder, access: Access) -> Builder

Sets the access level on the builder.

with_kind

</>

pub fn with_kind(builder: Builder, kind: Kind) -> Builder

Sets the table type on the builder.