bravo/bag

This module provides functions to work with Bags

Types

Bag

opaque </>

A bag table. Keys may occur multiple times per table, but objects cannot be copied verbatim.

pub opaque type Bag(t)

Functions

delete

</>

pub fn delete(bag: Bag(a)) -> Bool

Deletes a Bag.

Table lifetime is static, and memory is only freed when the owner process is killed! Don’t forget to call this function!

delete_all_objects

</>

pub fn delete_all_objects(bag: Bag(a)) -> Nil

Deletes all objects in the Bag. This is atomic and isolated.

delete_key

</>

pub fn delete_key(bag: Bag(a), key: b) -> Nil

Deletes all objects addressed by key, if any exist. If nothing does, this does nothing.

delete_object

</>

pub fn delete_object(bag: Bag(a), object: a) -> Nil

Deletes a specific object in the Bag. Other objects with the same key are unaffected.

file2tab

</>

pub fn file2tab(
  filename: String,
  verify: Bool,
  decoder: fn(Dynamic) -> Result(a, b),
) -> Option(Bag(a))

Creates a Bag from file filename that was previously created by tab2file.

For type safety reasons, a dynamic decoder must be provided, and the decoder must not fail for all objects in the table.

If the flag verify is set, then checks are performed to ensure the data is correct. This can be slow if tab2file was ran with md5sum enabled.

insert

</>

pub fn insert(bag: Bag(a), objects: List(a)) -> Bool

Inserts a list of tuples into a Bag.

Returns a Bool representing if the inserting succeeded.

If True, all objects in the list were inserted.
If False, none of the objects in the list were inserted. This may occur if the keypos of the Bag is greater than the object tuple size.

If an object with the same key already exists, then the old object will be overwritten with the new one.

lookup

</>

pub fn lookup(bag: Bag(a), key: b) -> List(a)

Gets a list of objects from a Bag.

Returns an list containing the objects, if any match.

new

</>

pub fn new(
  name: String,
  keypos: Int,
  access: Access,
) -> Result(Bag(a), Option(ErlangError))

Creates a new ETS table configured as a bag: keys may only occur multiple times per table, but objects cannot be copied verbatim.

name: An atom representing the name of the Bag. There may only be one ETS table associated with an atom. keypos: The index (1-indexed) that represents the key position of the object. This function fails if this is less than 1. access: Determines how visible the table is to other processes.

Public: Any process can read or write to the Bag.
Protected: Any process can read the Bag. Only the owner process can write to it.
Private: Only the parent process can read or write to the Bag.

Returns a result of the created Bag, which can be used by other functions in this module. If this function errors with None, then you likely put in an illegal keypos value. Otherwise, something went wrong in the FFI layer and an error occured in Erlang land.

tab2file

</>

pub fn tab2file(
  bag: Bag(a),
  filename: String,
  object_count: Bool,
  md5sum: Bool,
  sync: Bool,
) -> Bool

Saves a Bag as file filename that can later be read back into memory using file2tab.

There are three configuration flags with this function:

object_count: Stores the number of objects in the table in the footer. This can detect truncation.
md5sum: Stores a md5 checksum of the table and its objects. This can detect even single bitflips, but is computationally expensive.
sync: Blocks the process until the file has been successfully written.

tab2list

</>

pub fn tab2list(bag: Bag(a)) -> List(a)

Returns a list containing all of the objects in the Bag.