Struct pickledb::PickleDb

source · [−]
pub struct PickleDb { /* private fields */ }
Expand description

A struct that represents a PickleDb object

Implementations

Constructs a new PickleDb instance.

Arguments
  • db_path - 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
  • serialization_method - the serialization method to use for storing the data to memory and file
Examples
use pickledb::{PickleDb, PickleDbDumpPolicy, SerializationMethod};

let mut db = PickleDb::new("example.db", PickleDbDumpPolicy::AutoDump, SerializationMethod::Json);

Constructs a new PickleDb instance that uses JSON serialization for storing the data.

Arguments
  • db_path - 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, PickleDbDumpPolicy};

let mut db = PickleDb::new_json("example.db", PickleDbDumpPolicy::AutoDump);

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 object is returned.

Arguments
  • db_path - 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:
  • serialization_method - the serialization method used to store the data in the file
Examples
use pickledb::{PickleDb, PickleDbDumpPolicy, SerializationMethod};

let db = PickleDb::load("example.db", PickleDbDumpPolicy::AutoDump, SerializationMethod::Yaml);

Load a DB from a file stored in a Json format

This method tries to load a DB from a file serialized in Json format. Upon success an instance of PickleDb is returned, otherwise an Error object is returned.

Arguments
  • db_path - a path where the DB is loaded from
  • dump_policy - an enum value that determines the policy of dumping DB changes into the file. See PickleDb::load() for more information
Examples
use pickledb::{PickleDb, PickleDbDumpPolicy};

let db = PickleDb::load_json("example.db", PickleDbDumpPolicy::AutoDump);

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(). Upon success an instance of PickleDb is returned, otherwise an Error object is returned.

Arguments
  • db_path - a path where the DB is loaded from
  • serialization_method - the serialization method used to store the data in the file
Examples
use pickledb::{PickleDb, SerializationMethod};

let mut readonly_db = PickleDb::load_read_only("example.db", SerializationMethod::Cbor).unwrap();

// nothing happens by calling this method
readonly_db.dump();

Dump the data to the file.

Calling this method is necessary only if the DB is loaded or created with a dump policy other than PickleDbDumpPolicy::AutoDump, otherwise the data is dumped to the file upon every change.

This method returns Ok if dump is successful, Or an Err(Error) otherwise.

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, enums and every struct that has the #[derive(Serialize, Deserialize) attribute.

This method returns Ok if set is successful, Or an Err(Error) otherwise. An error is not likely to happen but may occur mostly in cases where this action triggers a DB dump (which is decided according to the dump policy)

Arguments
  • key - a string key
  • value - a value of any serializable type
Examples
// set a number
db.set("key1", &100).unwrap();

// set a floating point number
db.set("key2", &1.234).unwrap();

// set a String
db.set("key3", &String::from("hello world")).unwrap();

// set a Vec
db.set("key4", &vec![1,2,3]).unwrap();

// set a struct
#[derive(Serialize, Deserialize)]
struct Coor {
    x: i32,
    y: i32,
}
let mycoor = Coor { x: 1, y : 2 };
db.set("key5", &mycoor).unwrap();

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
let vec = db.get::<Vec<i32>>("key4").unwrap();

// read a struct
let coor = db.get::<Coor>("key5").unwrap();

Check if a key exists.

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

Arguments
  • key - the key to check

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.

Get the total number of keys in the DB.

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

This methods returns Ok(true) if the key was found in the DB or Ok(false) if it wasn’t found. It may also return Err(Error) if key was found but removal failed. Removal error is not likely to happen but may occur mostly in cases where this action triggers a DB dump (which is decided according to the dump policy)

Arguments
  • key - the key or list name to remove

Create a new list.

This method just creates a new list, it doesn’t add any elements to it. 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.

Upon success, the method returns an object of type PickleDbListExtender that enables to add items to the newly created list. Alternatively you can use ladd() or lextend() to add items to the list.

In case of a failure an Err(Error) is returned. Failures are not likely to happen but may occur mostly in cases where this action triggers a DB dump (which is decided according to the dump policy)

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

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

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.

If the item was added successfully the method returns Some(PickleDbListExtender) which enables to add more items to the list. Alternatively the method returns None if the list isn’t found in the DB or if a failure happened while extending the list. Failures are not likely to happen but may occur mostly in cases where this action triggers a DB dump (which is decided according to the dump policy)

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"]);

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.

If all items were added successfully the method returns Some(PickleDbListExtender) which enables to add more items to the list. Alternatively the method returns None if the list isn’t found in the DB or if a failure happened while extending the list. Failures are not likely to happen but may occur mostly in cases where this action triggers a DB dump (which is decided according to the dump policy)

Arguments
  • name - the list key
  • seq - an iterator containing references to 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.lextend("list1", &vec![100, 200, 300]).unwrap()

// 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"]]

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();

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

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 zero (0) is returned. In case of a failure an Err(Error) is returned. Failures are not likely to happen but may occur mostly in cases where this action triggers a DB dump (which is decided according to the dump policy)
Arguments
  • name - the list key to remove

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. None may also be returned if removing the item fails, which may happen mostly in cases where this action triggers a DB dump (which is decided according to the dump policy). 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]

Remove an item out of a list.

This method takes a list name and a reference to a value, removes the first instance of the value if it exists in the list, and returns an indication whether the item was removed or not.

If the list is not found in the DB or the given value isn’t found in the list, no item will be removed and Ok(false) will be returned. If removing the item fails, which may happen mostly in cases where this action triggers a DB dump (which is decided according to the dump policy), an Err(Error) is returned. Otherwise the item will be removed and Ok(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
  • value - 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 2
db.lrem_value("list1", &2).unwrap();

// The list now looks like this: [1, 3, 4]

// remove 3
db.lrem_value("list1", &3).unwrap();

// The list now looks like this: [1, 4]

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()),
        _ => ()
    }
}

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").unwrap()
  .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

Executes the destructor for this type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.