bravo - v3.2.0

bravo/dbag

This module provides functions to work with DBags

Types

DBag

opaque </>

A duplicate bag bravo. Keys may occur multiple times per table, and verbatim copies of an object can be stored.

pub opaque type DBag(t)

Functions

delete

</> 
pub fn delete(with dbag: DBag(a)) -> Bool

Deletes a DBag.

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(with dbag: DBag(a)) -> Nil

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

delete_key

</> 
pub fn delete_key(with dbag: DBag(a), at key: b) -> Nil

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

delete_object

</> 
pub fn delete_object(with dbag: DBag(a), target object: a) -> Nil

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

If there are multiple of the same object, then they will all be deleted.

file2tab

</> 
pub fn file2tab(
  from filename: String,
  verify verify: Bool,
  using decoder: fn(Dynamic) -> Result(a, b),
) -> Result(DBag(a), BravoError)

Creates a Ddbag 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.

Size-1 tuples are handled uniquely internally and are treated as non-tuples when saved to disk, so you must decode the non-tuple version of the type.

Can have error types DecodeFailure and ErlangError.

first

</> 
pub fn first(with dbag: DBag(a)) -> Option(b)

Returns the first key (not the object!) in the table, if it exists.

DBags are unordered, so the order of keys is unknown.

insert

</> 
pub fn insert(
  with dbag: DBag(a),
  insert objects: List(a),
) -> Bool

Inserts a list of tuples into a DBag.

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 DBag is greater than the object tuple size or if the input list is empty.

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

insert_new

</> 
pub fn insert_new(
  with dbag: DBag(a),
  insert objects: List(a),
) -> Bool

Inserts a list of tuples into a DBag. Unlike insert, this cannot overwrite objects and will return false if it tries to do so.

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 DBag is greater than the object tuple size or if the input list is empty.

last

</> 
pub fn last(with dbag: DBag(a)) -> Option(b)

Returns the last key (not the object!) in the table, if it exists.

DBags are unordered, so the order of keys is unknown.

lookup

</> 
pub fn lookup(with dbag: DBag(a), at key: b) -> List(a)

Gets a list of objects from a DBag.

Returns an list containing the objects, if any match.

member

</> 
pub fn member(with dbag: DBag(a), at key: b) -> Bool

Returns whether a DBag contains an object at key.

new

</> 
pub fn new(
  name name: String,
  keypos keypos: Int,
  access access: Access,
) -> Result(DBag(a), BravoError)

Creates a new ETS table configured as a duplicate bag: keys may occur multiple times per table, and verbatim copies of an object can be stored.

name: An atom representing the name of the DBag. 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 DBag.
  • Protected: Any process can read the DBag. Only the owner process can write to it.
  • Private: Only the parent process can read or write to the DBag.

Returns a result of the created DBag, which can be used by other functions in this module. Can have error types ErlangError and NonPositiveKeypos.

next

</> 
pub fn next(with dbag: DBag(a), from key: b) -> Option(b)

Given a key, returns the next key (not the object!) after it in the table, if it exists.

DBags are unordered, so the order of keys is unknown.

prev

</> 
pub fn prev(with dbag: DBag(a), from key: b) -> Option(b)

Given a key, returns the previous key (not the object!) before it in the table, if it exists.

DBags are unordered, so the order of keys is unknown.

tab2file

</> 
pub fn tab2file(
  with dbag: DBag(a),
  to filename: String,
  object_count object_count: Bool,
  md5sum md5sum: Bool,
  sync sync: Bool,
) -> Result(Nil, BravoError)

Saves a Ddbag 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.

Can have error type ErlangError.

tab2list

</> 
pub fn tab2list(with dbag: DBag(a)) -> List(a)

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

take

</> 
pub fn take(with dbag: DBag(a), at key: b) -> List(a)

Returns and removes all objects with key in the DBag, if any exist.

✨ Search Document