Struct SQLiteMap 

pub struct SQLiteMap<K, V>
where
    K: Type,
    V: Type,
{ /* private fields */ }

A map that stores key-value pairs with keys of type K and values of type V, backed by an SQLite in-memory database.

It serves as a drop-in replacement for HashMap.

By default, SQLiteMap<String> treats its keys as case-sensitive, but a case-insensitive variant is available. Even when using the case-sensitive map variant, for some operations a dedicated “case-insensitive” version is provided.

 

For bulk inserts or updates, it is strongly recommended to use an explicit transaction. Without one, SQLite executes each insert or update in its own transaction, which can significantly degrade performance.

Implementations

impl<K, V> SQLiteMap<K, V>

where K: Type, V: Type,

pub fn new() -> Result<Self, Error>

Creates a new, empty hash map with case-sensitive keys, backed by an in-memory SQLite database.

pub fn with_nocase() -> Result<Self, Error>

where K: CharType,

Creates a new, empty hash map with case-insensitive keys, backed by an in-memory SQLite database.

Only ASCII characters are case folded. SQLite does not attempt to do full UTF case folding!

pub fn with_file<P>(path: P) -> Result<Self, Error>

where P: AsRef<Path>,

Creates a new or re-opens an existing hash map, backed by a file-based SQLite database.

A new map is created with case-sensitive keys. However, if the database file already exists, its case-sensitivity is preserved.

pub fn with_file_nocase<P>(path: P) -> Result<Self, Error>

where K: CharType, P: AsRef<Path>,

Creates a new or re-opens an existing hash map, backed by a file-based SQLite database.

A new map is created with case-insensitive keys. However, if the database file already exists, its case-sensitivity is preserved.

Only ASCII characters are case folded. SQLite does not attempt to do full UTF case folding!

pub fn transaction(&mut self) -> Result<SQLiteMapTransaction<'_, K, V>, Error>

Starts a new SQLite transaction for this map.

Please note that using an explicit SQLite transaction allows for much more efficient bulk inserts 🚀

Returns the new SQLiteMapTransaction instance.

pub fn insert<Q, R>(&mut self, key: &Q, value: &R) -> Result<bool, Error>

where K: Borrow<Q>, Q: ?Sized + ToSql, V: Borrow<R>, R: ?Sized + ToSql,

Inserts the given key-value pair into the map, if the specified key does not exist yet.

If the map already contains the specified key, then its associated value is not changed by this operation!

Returns true, if the key-value pair was inserted; otherwise returns false.

Please use the update() function to update the value associated with a key that may already exist.

pub fn update<Q, R>(&mut self, key: &Q, value: &R) -> Result<(), Error>

where K: Borrow<Q>, Q: ?Sized + ToSql, V: Borrow<R>, R: ?Sized + ToSql,

Associates the specified value with the specified key, regardless of whether the key already exists in the map.

If the map does not already contain the specified key, then the key is inserted automatically.

Note: Due to limitations in SQLite, it is not possible to determine whether the key was inserted or updated.

pub fn contains_key<Q>(&self, key: &Q) -> Result<bool, Error>

where K: Borrow<Q>, Q: ?Sized + ToSql,

Checks whether the map contains the specified key.

For case-sensitive maps, the check is case-sensitive; for case-insensitive maps, the check is case-insensitive.

Returns true, if the map contains the key; otherwise returns false.

pub fn contains_key_nocase<Q>(&self, key: &Q) -> Result<bool, Error>

where K: Borrow<Q> + CharType, Q: ?Sized + ToSql,

This is the “case-insensitive” version of the contains() function.

The check is always performed case-insensitive.

Returns true, if the map contains the key; otherwise returns false.

pub fn get<Q>(&self, key: &Q) -> Result<Option<V>, Error>

where K: Borrow<Q>, Q: ?Sized + ToSql,

Tries to retrieve the value for the specified key.

For case-sensitive maps, the key is treated as case-sensitive; for case-insensitive maps, it is treated as case-insensitive.

Returns the Some(value), if the map contains the key; otherwise returns None.

pub fn get_nocase<Q>(&self, key: &Q) -> Result<Option<V>, Error>

where K: Borrow<Q> + CharType, Q: ?Sized + ToSql,

This is the “case-insensitive” version of the get() function.

The key is always treated as case-insensitive.

Returns the Some(value), if the map contains the key; otherwise returns None.

pub fn remove<Q>(&mut self, key: &Q) -> Result<bool, Error>

where K: Borrow<Q>, Q: ?Sized + ToSql,

Removes the specified key from the map, if present.

For case-sensitive maps, the key is treated as case-sensitive; for case-insensitive maps, it is treated as case-insensitive.

Returns true, if the map contained the key; otherwise returns false.

pub fn remove_nocase<Q>(&mut self, key: &Q) -> Result<bool, Error>

where K: Borrow<Q> + CharType, Q: ?Sized + ToSql,

This is the “case-insensitive” version of the remove() function.

The key is always treated as case-insensitive.

Returns true, if the map contained the key; otherwise returns false.

pub fn for_each_key<F>(&self, callback: F) -> Result<(), Error>

where F: FnMut(K),

Invokes the given callback function for each key that is currently contained in the map.

This function does not guarantee a specific iteration order.

pub fn for_each_entry<F>(&self, callback: F) -> Result<(), Error>

where F: FnMut(K, V),

Invokes the given callback function for each key-value pair that is currently contained in the map.

This function does not guarantee a specific iteration order.

pub fn find_key<P>(&self, predicate: P) -> Result<Option<K>, Error>

where P: Fn(&K) -> bool,

Searches the map for the first key that satisfies the given predicate.

Returns the first key that satisfies the given predicate, or None if none satisfies the predicate or the map is empty.

This function does not guarantee a specific iteration order.

Also, the predicate is not always tested on all keys, because the function returns at the first match.

pub fn find_entry<P>(&self, predicate: P) -> Result<Option<(K, V)>, Error>

where P: Fn(&K, &V) -> bool,

Searches the map for the first key-value pair that satisfies the given predicate.

Returns the first key-value pair that satisfies the given predicate, or None if none satisfies the predicate or the map is empty.

This function does not guarantee a specific iteration order.

Also, the predicate is not always tested on all key-value pairs, because the function returns at the first match.

pub fn glob_keys<F, Q>( &self, invert: bool, pattern: &Q, callback: F, ) -> Result<(), Error>

where F: FnMut(K), K: Borrow<Q> + CharType, Q: ?Sized + ToSql,

Invokes the given callback function for each key that matches the given pattern.

The pattern string is interpreted according to the UNIX globbing rules. Specifically, a ? character (not between brackets) matches any single character, and a * character (not between brackets) matches any string, including the empty string. Additionally, an expression […] where the first character after the leading [ is not an ! matches a single character that can be any of the characters enclosed by the brackets; and an expression [!…] matches a single character that is not matched by the expression.

This function is case-sensitive and does not guarantee a specific iteration order.

If invert is true, returns all keys that do not match the pattern; otherwise the matching keys are returned.

pub fn glob_entries<F, Q>( &self, invert: bool, pattern: &Q, callback: F, ) -> Result<(), Error>

where F: FnMut(K, V), K: Borrow<Q> + CharType, Q: ?Sized + ToSql,

Invokes the given callback function for each key-value pair whose key matches the given pattern.

The pattern string is interpreted according to the UNIX globbing rules. Specifically, a ? character (not between brackets) matches any single character, and a * character (not between brackets) matches any string, including the empty string. Additionally, an expression […] where the first character after the leading [ is not an ! matches a single character that can be any of the characters enclosed by the brackets; and an expression [!…] matches a single character that is not matched by the expression.

This function is case-sensitive and does not guarantee a specific iteration order.

If invert is true, returns all key-value pairs that do not match the pattern; otherwise the matching pairs are returned.

pub fn len(&self) -> Result<Size, Error>

Returns the number of unique keys in the map.

pub fn is_empty(&self) -> Result<bool, Error>

Returns true if the map contains no keys; otherwise returns false.

pub fn clear(&mut self) -> Result<(), Error>

Removes all keys from the map.