dream_ets/operations · dream_ets

delete

pub fn delete(
  table: table.Table(k, v),
  key: k,
) -> Result(Nil, table.EtsError)

Delete a key from the table

Removes a key-value pair from the table. If the key doesn’t exist, this is a no-op (no error).

This operation is atomic and safe for concurrent access.

Parameters

table: The table to modify
key: The key to delete

Returns

Ok(Nil): Successfully deleted (or key didn’t exist)
Error(EtsError): An error occurred

Example

import dream_ets as ets

let assert Ok(_) = ets.delete(table, "user:123")

delete_all_objects

</>

pub fn delete_all_objects(
  table: table.Table(k, v),
) -> Result(Nil, table.EtsError)

Delete all objects from the table (keeps the table)

delete_table

</>

pub fn delete_table(
  table: table.Table(k, v),
) -> Result(Nil, table.EtsError)

Delete the entire table

Permanently deletes the table and all its data. After calling this, the table cannot be used for any operations.

Parameters

table: The table to delete

Returns

Ok(Nil): Successfully deleted
Error(EtsError): An error occurred

Example

import dream_ets as ets

let assert Ok(_) = ets.delete_table(table)

get

</>

pub fn get(
  table: table.Table(k, v),
  key: k,
) -> Result(option.Option(v), table.EtsError)

Lookup a value by key

Retrieves the value associated with a key. Returns None if the key doesn’t exist, or Some(value) if it does.

This operation is atomic and safe for concurrent access.

Parameters

table: The table to query
key: The key to look up

Returns

Ok(Some(value)): Key exists, returns the value
Ok(None): Key doesn’t exist
Error(EtsError): An error occurred (decoding failure, etc.)

Example

import dream_ets as ets
import gleam/option

case ets.get(table, "user:123") {
  Ok(option.Some(name)) -> io.println("Found: " <> name)
  Ok(option.None) -> io.println("User not found")
  Error(err) -> handle_error(err)
}

insert_new

</>

pub fn insert_new(
  table: table.Table(k, v),
  key: k,
  value: v,
) -> Result(Bool, table.EtsError)

Insert only if the key doesn’t exist

Atomically inserts a key-value pair only if the key doesn’t already exist. Returns True if the key was inserted, False if it already existed.

This is useful for implementing “set if not exists” semantics.

Parameters

table: The table to modify
key: The key to insert
value: The value to associate with the key

Returns

Ok(True): Key was inserted (didn’t exist before)
Ok(False): Key already existed, no change made
Error(EtsError): An error occurred

Example

import dream_ets as ets

case ets.insert_new(table, "user:123", "Alice") {
  Ok(True) -> io.println("User created")
  Ok(False) -> io.println("User already exists")
  Error(err) -> handle_error(err)
}

keys

</>

pub fn keys(table: table.Table(k, v)) -> List(k)

Get all keys from the table

Returns a list of all keys in the table. The order is undefined and may vary between calls.

Performance Note: This function iterates the entire table, which can be slow for large tables. Consider using iteration patterns if you don’t need all keys at once.

Parameters

table: The table to get keys from

Returns

A list of all keys in the table.

Example

import dream_ets as ets

let all_keys = ets.keys(table)
list.each(all_keys, fn(key) {
  io.println("Key: " <> key)
})

load_from_file

</>

pub fn load_from_file(
  filename: String,
) -> Result(@internal EtsTableRef, table.EtsError)

Load table from file

Note: This returns a raw table reference without type information. Advanced usage only - prefer creating tables with the builder.

match

</>

pub fn match(
  table: table.Table(k, v),
  pattern: dynamic.Dynamic,
) -> List(dynamic.Dynamic)

Pattern matching - advanced ETS feature

Returns list of matches based on Erlang match pattern. This is a low-level function - most users should use get/keys/values instead.

See: https://erlang.org/doc/man/ets.html#match-2

match_object

</>

pub fn match_object(
  table: table.Table(k, v),
  pattern: dynamic.Dynamic,
) -> List(dynamic.Dynamic)

Match objects - advanced ETS feature

Returns complete objects matching the pattern. This is a low-level function - most users should use get/to_list instead.

See: https://erlang.org/doc/man/ets.html#match_object-2

member

</>

pub fn member(table: table.Table(k, v), key: k) -> Bool

Check if a key exists in the table

Returns True if the key exists in the table, False otherwise. This is faster than get() when you only need to check existence.

Parameters

table: The table to query
key: The key to check

Returns

True: Key exists
False: Key doesn’t exist

Example

import dream_ets as ets

if ets.member(table, "user:123") {
  io.println("User exists")
}

save_to_file

</>

pub fn save_to_file(
  table: table.Table(k, v),
  filename: String,
) -> Result(Nil, table.EtsError)

Save table to file

Persists the entire table to disk. Useful for caching across restarts.

select

</>

pub fn select(
  table: table.Table(k, v),
  match_spec: dynamic.Dynamic,
) -> List(dynamic.Dynamic)

Select with match specification - advanced ETS feature

SQL-like queries with match specifications. This is a low-level function for complex queries.

See: https://erlang.org/doc/man/ets.html#select-2

set

</>

pub fn set(
  table: table.Table(k, v),
  key: k,
  value: v,
) -> Result(Nil, table.EtsError)

Insert or update a key-value pair in the table

Sets a key-value pair in the table. If the key already exists, the value is updated. If the key doesn’t exist, it’s created.

This operation is atomic and safe for concurrent access.

Parameters

table: The table to modify
key: The key to set
value: The value to associate with the key

Returns

Ok(Nil): Successfully set the key-value pair
Error(EtsError): An error occurred (encoding failure, etc.)

Example

import dream_ets as ets

let assert Ok(_) = ets.set(table, "user:123", "Alice")
let assert Ok(_) = ets.set(table, "user:123", "Bob")  // Updates existing

size

</>

pub fn size(table: table.Table(k, v)) -> Int

Get the number of objects in the table

Returns the total number of key-value pairs in the table.

Performance Note: This implementation counts by iterating all keys, which can be slow for very large tables. For better performance with large tables, consider maintaining a counter separately.

Parameters

table: The table to count

Returns

The number of entries in the table.

Example

import dream_ets as ets

let count = ets.size(table)
io.println("Table has " <> int.to_string(count) <> " entries")

take

</>

pub fn take(
  table: table.Table(k, v),
  key: k,
) -> Result(option.Option(v), table.EtsError)

Lookup and delete a key-value pair

Atomically retrieves and removes a key-value pair. Returns Some(value) if the key existed, or None if it didn’t.

This is useful for implementing queue or cache eviction patterns.

Parameters

table: The table to modify
key: The key to take

Returns

Ok(Some(value)): Key existed, returns the value (now removed)
Ok(None): Key didn’t exist
Error(EtsError): An error occurred

Example

import dream_ets as ets
import gleam/option

case ets.take(table, "user:123") {
  Ok(option.Some(name)) -> {
    io.println("Removed user: " <> name)
    // Key is now deleted from table
  }
  Ok(option.None) -> io.println("User not found")
  Error(err) -> handle_error(err)
}

to_list

</>

pub fn to_list(table: table.Table(k, v)) -> List(#(k, v))

Convert table to a list of key-value pairs

Returns a list of all key-value pairs in the table as tuples. The order is undefined and may vary between calls.

Performance Note: This function iterates the entire table, which can be slow for large tables.

Parameters

table: The table to convert

Returns

A list of #(key, value) tuples.

Example

import dream_ets as ets

let pairs = ets.to_list(table)
list.each(pairs, fn(#(key, value)) {
  io.println(key <> " => " <> value)
})

update_element

</>

pub fn update_element(
  table: table.Table(k, v),
  key: k,
  pos: Int,
  value: dynamic.Dynamic,
) -> Result(Nil, table.EtsError)

Update an element in a tuple at the specified position

values

</>

pub fn values(table: table.Table(k, v)) -> List(v)

Get all values from the table

Returns a list of all values in the table. The order is undefined and may vary between calls.

Performance Note: This function iterates the entire table, which can be slow for large tables. Consider using iteration patterns if you don’t need all values at once.

Parameters

table: The table to get values from

Returns

A list of all values in the table.

Example

import dream_ets as ets

let all_values = ets.values(table)
list.each(all_values, fn(value) {
  process_value(value)
})