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 from_file<P>( path: P, readonly: bool, can_create: bool, ) -> Result<Self, Error>

where P: AsRef<Path>,

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

If readonly is true, the database file is opened in “read-only” mode.

If can_create is true (and if readonly is false), a new empty database file is created, if the file does not exist yet.

Returns Error::InvalidSchema, if the database file already exists but its schema does not match the schema expected by this type of map. This means that you must re-open a database file with the same type of map that was used to create it.

pub fn from_file_nocase<P>( path: P, readonly: bool, can_create: bool, ) -> Result<Self, Error>

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

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

If readonly is true, the database file is opened in “read-only” mode.

If can_create is true (and if readonly is false), a new empty database file is created if the file does not exist yet.

Returns Error::InvalidSchema, if the database file already exists but its schema does not match the schema expected by this type of map. This means that you must re-open a database file with the same type of map that was used to create it.

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<Action, 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.

Provided that the hooks feature is enabled, the function returns either Action::Insert or Action::Update, depending on whether a new key-value pair was inserted or the associated value of an existing key was updated

If hooks is not enabled, the function always returns Action::Unknown, but, apart from that, it works identically 😊

pub fn union( &mut self, other: &Self, update: bool, ) -> Result<Option<(Size, Size)>, Error>

Inserts all key-value pairs from another map into this map.

If update is true, this function updates the values associated with existing keys in this map using the corresponding values from the other map. Otherwise, the values associated with existing keys are not changed.

Returns Some((inserted, updated)), i.e., the number of new keys inserted and existing keys updated, respectively.

If hooks is not enabled and if update is true, the function always returns None, though 😅

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.

pub fn to_set(&mut self) -> Result<SQLiteSet<K>, Error>

Creates a new SQLiteSet that contains all keys contained in this map.

The created set is case-sensitive.

pub fn to_set_nocase(&mut self) -> Result<SQLiteSet<K>, Error>

where K: CharType,

Creates a new SQLiteSet that contains all keys contained in this map.

The created set is case-insensitive.

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

pub fn to_file<P>(&self, path: P) -> Result<(), Error>

where P: AsRef<Path>,

Available on crate feature backup only.

Stores all contents of this map in the specified database file.

The file will be replaced, if it already exists!

Trait Implementations

impl<K, V> TryClone for SQLiteMap<K, V>

where K: Type, V: Type,

fn try_clone(&self) -> Result<Self, Self::Error>

Creates an exact, independent copy of the given map instance.

This function fails with Error::Unsupported, if the optional backup feature is not enabled 😥

type Error = Error

The error type to be returned by try_clone().