Struct pickledb::PickleDb

pub struct PickleDb { /* fields omitted */ }

A struct that represents a PickleDB object

Methods

impl PickleDb

pub fn new(location: &str, dump_policy: PickleDbDumpPolicy) -> PickleDb

Constructs a new PickleDB instance.

Arguments

• location - a path where the DB will be stored
• dump_policy - an enum value that determines the policy of dumping DB changes into the file. Please see PickleDB::load() to understand the different policy options

Examples

use pickledb::PickleDb;
 
let mut db = PickleDB::new("example.db", false);

pub fn load(     location: &str,     dump_policy: PickleDbDumpPolicy ) -> Result<PickleDb, Error>

Load a DB from a file.

This method tries to load a DB from a file. Upon success an instance of PickleDB is returned, otherwise an error is returned.

Arguments

• location - a path where the DB is loaded from
• dump_policy - an enum value that determines the policy of dumping DB changes into the file. The user can choose between the following options:
  • PickleDbDumpPolicy::NeverDump - never dump any change, file will always remain read-only. When choosing this policy even calling to dump() won't dump the data. Choosing this option is the same like calling PickleDB::load_read_only()
  • PickleDbDumpPolicy::AutoDump - every change will be dumped immediately and automatically to the file
  • PickleDbDumpPolicy::DumpUponRequest - data won't be dumped unless the user calls dump() proactively to dump the data
  • PickleDbDumpPolicy::PeriodicDump(Duration) - changes will be dumped to the file periodically, no sooner than the Duration provided by the user. The way this mechanism works is as follows: each time there is a DB change the last DB dump time is checked. If the time that has passed since the last dump is higher than Duration, changes will be dumped, otherwise changes will not be dumped.

Examples

use pickledb::PickleDb;
 
let db = PickleDB::load("example.db", PickleDbDumpPolicy::AutoDump);

pub fn load_read_only(location: &str) -> Result<PickleDb, Error>

Load a DB from a file in read-only mode.

This method is similar to the PickleDB::load() method with the only difference that the file is loaded from DB with a dump policy of PickleDbDumpPolicy::NeverDump, meaning changes will not be saved to the file, even when calling dump()

Arguments

• location - a path where the DB is loaded from

Examples

use pickledb::PickleDb;
 
let readonly_db = PickleDB::load("example.db");
 
// nothing happens by calling this method
readonly_db.dump();

pub fn dump(&mut self) -> bool

Dump the data to the file.

Calling this method is necessary only if the DB is loaded or created with auto_dump = true. Otherwise the data is dumped to the file upon every change. This method returns true if dump is successful, false otherwise.

pub fn set<V>(&mut self, key: &str, value: &V) where     V: Serialize,

Set a key-value pair.

The key has to be a string but the value can be of any type that is serializable. That includes all primitive types, vectors, tuples and every struct that has the #[derive(Serialize, Deserialize) attribute.

Arguments

• key - a string key
• value - a value of any serializable type

Examples

// set a number
db.set("key1", &100);
 
// set a floating point number
db.set("key2", &1.234);
 
// set a String
db.set("key3", &String::from("hello world"));
 
// set a Vec
db.set("key4", &vec![1,2,3]);
 
// set a struct
#[derive(Serialize, Deserialize)]
struct Coor {
    x: i32,
    y: i32,
}
let mycoor = Coor { x: 1, y : 2 };
db.set("key5", &mycoor);

pub fn get<V>(&self, key: &str) -> Option<V> where     V: DeserializeOwned,

Get a value of a key.

The key is always a string but the value can be of any type. It's the user's responsibility to know the value type and give it while calling this method. If the key doesn't exist or if the type is wrong, None will be returned. Otherwise Some(V) will be returned. Since the values are stored in a serialized way the returned object is not a reference to the value stored in a DB but actually a new instance of it

Arguments

• key - a string key

Examples

// read a num
let num = db.get::<i32>("key1").unwrap();
 
// read a floating point number
let float_num = db.get::<f32>("key2").unwrap();
 
// read a String
let my_str = db.get::<String>("key3").unwrap();
 
// read a Vec
ley vec = db.get::<Vec<i32>>("key4").unwrap();
 
// read a struct
let coor = db.get::<Coor>("key5").unwrap();

pub fn exists(&self, key: &str) -> bool

Check if a key exists.

This method returns true if the key exists and false otherwise.

Arguments

• key - the key to check

pub fn get_all(&self) -> Vec<String>

Get a vector of all the keys in the DB.

The keys returned in the vector are not references to the actual key string objects but rather a clone of them.

pub fn total_keys(&self) -> usize

Get the total number of keys in the DB.

pub fn rem(&mut self, key: &str) -> bool

Remove a key-value pair or a list from the DB.

This methods returns true if the key was found in the DB or false if it wasn't found

Arguments

• key - the key or list name to remove

pub fn lcreate(&mut self, name: &str) -> PickleDbListExtender

Create a new list.

This method just creates a new list, it doesn't add any elements to it. For adding elements to the list please call ladd() or lextend(). If another list or value is already set under this key, they will be overridden, meaning the new list will override the old list or value. The method returns an object of type PickleDbListExtender that enables to add items to the newly created list

Arguments

• name - the key of the list that will be created

pub fn lexists(&self, name: &str) -> bool

Check if a list exists.

This method returns true if the list name exists and false otherwise. The difference between this method and exists() is that this methods checks only for lists with that name (key) and exists() checks for both values and lists.

Arguments

• name - the list key to check

pub fn ladd<V>(&mut self, name: &str, value: &V) -> Option<PickleDbListExtender> where     V: Serialize,

Add a single item to an existing list.

As mentioned before, the lists are heterogeneous, meaning a single list can contain items of different types. That means that the item can be of any type that is serializable. That includes all primitive types, vectors, tuples and every struct that has the #[derive(Serialize, Deserialize) attribute. The method returns a Some(PickleDbListExtender) object that enables to add more items to the list if the item was added successfully or None if the list name isn't found in the DB.

Arguments

• name - the list key
• value - a reference of the item to add to the list

Examples

// create a new list
db.lcreate("list1");
 
// add items of different types to the list
db.ladd("list1", &100).unwrap()
  .ladd(&String::from("my string"))
  .ladd(&vec!["aa", "bb", "cc"]);

pub fn lextend<V>(     &mut self,     name: &str,     seq: &Vec<V> ) -> Option<PickleDbListExtender> where     V: Serialize,

Add multiple items to an existing list.

As mentioned before, the lists are heterogeneous, meaning a single list can contain items of different types. That means that the item can be of any type that is serializable. That includes all primitive types, vectors, tuples and every struct that has the #[derive(Serialize, Deserialize) attribute. This method adds multiple items to the list, but since they're in a vector that means all of them are of the same type. Of course it doesn't mean that the list cannot contain items of other types as well, as you can see in the example below. The method return Some(PickleDbListExtender) that enables to add more items to the list if all items were added successfully or None if the list name isn't found in the DB.

Arguments

• name - the list key
• seq - a vector containing the new items to add to the list

Examples

// create a new list
db.lcreate("list1");
 
// add a bunch of numbers to the list
db.lextends("list1", &vec![100, 200, 300])
 
// add a String item to the list
  .ladd(&String::from("my string"))
 
// add a vector item to the list
  .ladd(&vec!["aa", "bb", "cc"]);
 
// now the list contains 5 items and looks like this: [100, 200, 300, "my string", ["aa, "bb", "cc"]]

pub fn lget<V>(&self, name: &str, pos: usize) -> Option<V> where     V: DeserializeOwned,

Get an item of of a certain list in a certain position.

This method takes a list name and a position inside the list and retrieves the item in this position. It's the user's responsibility to know what is the correct type of the item and give it while calling this method. Since the item in the lists are stored in a serialized way the returned object is not a reference to the item stored in a DB but actually a new instance of it. If the list is not found in the DB or the given position is out of bounds of the list None will be returned. Otherwise Some(V) will be returned.

Arguments

• name - the list key
• pos - the position of the item inside the list. Expected value is >= 0

Examples

// create a list
db.lcreate("list1");
 
// add a number to list1
db.ladd("list1", &100));
 
// add a string to list1
db.ladd("list1", &String::from("my string"));
 
// read the first item in the list - int
let x = db.lget::<i32>("list1", 0).unwrap();
 
// read the second item in the list - string
let s = db.lget::<String>("list1", 1).unwrap();

pub fn llen(&self, name: &str) -> usize

Get the length of a list.

If the list is empty or if it doesn't exist the value of 0 is returned.

Arguments

• name - the list key

pub fn lrem_list(&mut self, name: &str) -> usize

Remove a list.

This method is somewhat similar to rem() but with 2 small differences:

• This method only removes lists and not key-value pairs
• The return value of this method is the number of items that were in the list that was removed. If the list doesn't exist a value of 0 is returned

Arguments

• name - the list key to remove

pub fn lpop<V>(&mut self, name: &str, pos: usize) -> Option<V> where     V: DeserializeOwned,

Pop an item out of a list.

This method takes a list name and a position inside the list, removes the item in this position and returns it to the user. It's the user's responsibility to know what is the correct type of the item and give it while calling this method. Since the item in the lists are stored in a serialized way the returned object is not a reference to the item stored in a DB but actually a new instance of it. If the list is not found in the DB or the given position is out of bounds no item will be removed and None will be returned. Otherwise the item will be removed and Some(V) will be returned. This method is very similar to lrem_value(), the only difference is that this methods returns the value and lrem_value() returns only an indication whether the item was removed or not.

Arguments

• name - the list key
• pos - the position of the item to remove

Examples

// create a list
db.lcreate("list1");
 
// add 4 items to the list
db.lextend("list1", &vec![1,2,3,4]);
 
// remove item in position 2
let item2 = db.lpop::<i32>("list1", 2);
 
// item2 contains 3 and the list now looks like this: [1, 2, 4]
 
// remove item in position 1
let item1 = db.lpop::<i32>("list1", 1);
 
// item1 contains 2 and the list now looks like this: [1, 4]

pub fn lrem_value<V>(&mut self, name: &str, value: &V) -> bool where     V: Serialize,

Remove an item out of a list.

This method takes a list name and a position inside the list, removes the item in this position and returns an indication whether the item was removed or not. If the list is not found in the DB or the given position is out of bounds no item will be removed and false will be returned. Otherwise the item will be removed and true will be returned. This method is very similar to lpop(), the only difference is that this methods returns an indication and lpop() returns the actual item that was removed.

Arguments

• name - the list key
• pos - the position of the item to remove

Examples

// create a list
db.lcreate("list1");
 
// add 4 items to the list
db.lextend("list1", &vec![1,2,3,4]);
 
// remove item in position 2
db.lrem_value("list1", 2);
 
// The list now looks like this: [1, 2, 4]
 
// remove item in position 1
db.lrem_value("list1", 1);
 
// The list now looks like this: [1, 4]

Important traits for PickleDbIterator<'a>

impl<'a> Iterator for PickleDbIterator<'a> type Item = PickleDbIteratorItem<'a>;

pub fn iter(&self) -> PickleDbIterator

Return an iterator over the keys and values in the DB.

Examples

// iterate over all keys and values in the db
for kv in db.iter() {
    match kv.get_key() {
        "key1" => println!("Value of {} is: {}", kv.get_key(), kv.get_value::<String>().unwrap()),
        "key2" => println!("Value of {} is: {}", kv.get_key(), kv.get_value::<String>().unwrap()),
        "key3" => println!("Value of {} is: {:?}", kv.get_key(), kv.get_value::<Vec<i32>>().unwrap()),
        "key4" => println!("Value of {} is: {}", kv.get_key(), kv.get_value::<Rectangle>().unwrap()),
        _ => ()
    }
}

Important traits for PickleDbListIterator<'a>

impl<'a> Iterator for PickleDbListIterator<'a> type Item = PickleDbListIteratorItem<'a>;

pub fn liter(&self, name: &str) -> PickleDbListIterator

Return an iterator over the items in certain list.

Arguments

• name - the list name. If the list doesn't exist an exception is thrown

Examples

// create a new list
db.lcreate("list1")
  .lextend(&vec![1,2,3,4]);
 
// iterate over the items in list1
for item_iter in db.liter("list1") {
    println!("Current item is: {}", item_iter.get_item::<i32>().unwrap());
}

Trait Implementations

impl Drop for PickleDb

fn drop(&mut self)

Executes the destructor for this type.