Struct pickledb::PickleDb[−][src]

pub struct PickleDb { /* fields omitted */ }

A struct that represents a PickleDb object

Implementations

impl PickleDb[src]

pub fn new<P: AsRef<Path>>(
    db_path: P,
    dump_policy: PickleDbDumpPolicy,
    serialization_method: SerializationMethod
) -> PickleDb[src]

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

pub fn new_json<P: AsRef<Path>>(
    db_path: P,
    dump_policy: PickleDbDumpPolicy
) -> PickleDb[src]

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

pub fn new_bin<P: AsRef<Path>>(
    db_path: P,
    dump_policy: PickleDbDumpPolicy
) -> PickleDb[src]

Constructs a new PickleDb instance that uses Bincode 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_bin("example.db", PickleDbDumpPolicy::AutoDump);

pub fn new_yaml<P: AsRef<Path>>(
    db_path: P,
    dump_policy: PickleDbDumpPolicy
) -> PickleDb[src]

Constructs a new PickleDb instance that uses YAML 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_yaml("example.db", PickleDbDumpPolicy::AutoDump);

pub fn new_cbor<P: AsRef<Path>>(
    db_path: P,
    dump_policy: PickleDbDumpPolicy
) -> PickleDb[src]

Constructs a new PickleDb instance that uses CBOR 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_cbor("example.db", PickleDbDumpPolicy::AutoDump);

pub fn load<P: AsRef<Path>>(
    db_path: P,
    dump_policy: PickleDbDumpPolicy,
    serialization_method: SerializationMethod
) -> Result<PickleDb>[src]

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

pub fn load_json<P: AsRef<Path>>(
    db_path: P,
    dump_policy: PickleDbDumpPolicy
) -> Result<PickleDb>[src]

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

pub fn load_bin<P: AsRef<Path>>(
    db_path: P,
    dump_policy: PickleDbDumpPolicy
) -> Result<PickleDb>[src]

Load a DB from a file stored in Bincode format

This method tries to load a DB from a file serialized in Bincode 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_bin("example.db", PickleDbDumpPolicy::AutoDump);

pub fn load_yaml<P: AsRef<Path>>(
    db_path: P,
    dump_policy: PickleDbDumpPolicy
) -> Result<PickleDb>[src]

Load a DB from a file stored in Yaml format

This method tries to load a DB from a file serialized in Yaml 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_yaml("example.db", PickleDbDumpPolicy::AutoDump);

pub fn load_cbor<P: AsRef<Path>>(
    db_path: P,
    dump_policy: PickleDbDumpPolicy
) -> Result<PickleDb>[src]

Load a DB from a file stored in Cbor format

This method tries to load a DB from a file serialized in Cbor 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_cbor("example.db", PickleDbDumpPolicy::AutoDump);

pub fn load_read_only<P: AsRef<Path>>(
    db_path: P,
    serialization_method: SerializationMethod
) -> Result<PickleDb>[src]

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

pub fn dump(&mut self) -> Result<()>[src]

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.

pub fn set<V>(&mut self, key: &str, value: &V) -> Result<()> where
    V: Serialize, [src]

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

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

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

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

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>[src]

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[src]

Get the total number of keys in the DB.

pub fn rem(&mut self, key: &str) -> Result<bool>[src]

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

pub fn lcreate(&mut self, name: &str) -> Result<PickleDbListExtender<'_>>[src]

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

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

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, [src]

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

pub fn lextend<'a, V, I>(
    &mut self,
    name: &str,
    seq: I
) -> Option<PickleDbListExtender<'_>> where
    V: 'a + Serialize,
    I: IntoIterator<Item = &'a V>, [src]

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

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

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[src]

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) -> Result<usize>[src]

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

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

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]

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

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]

pub fn iter(&self) -> PickleDbIterator<'_>ⓘ

Notable traits for PickleDbIterator<'a>

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

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

pub fn liter(&self, name: &str) -> PickleDbListIterator<'_>ⓘ

Notable traits for PickleDbListIterator<'a>

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

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

impl Drop for PickleDb[src]

Auto Trait Implementations

impl RefUnwindSafe for PickleDb

impl Send for PickleDb

impl Sync for PickleDb

impl Unpin for PickleDb

impl UnwindSafe for PickleDb

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized, [src]

impl<T> Borrow<T> for T where
    T: ?Sized, [src]

impl<T> BorrowMut<T> for T where
    T: ?Sized, [src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, [src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, [src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, [src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.