Struct lending_library::LendingLibrary

pub struct LendingLibrary<K, V> where
    K: Hash + Eq + Copy,  { /* fields omitted */ }

A key-value data store that allows you to loan temporary ownership of values.

Assumptions

The store does it's best to ensure that no unsafe behaviour occurs, however as a result it may trigger several panics rather than allow an unsafe condition to arise.

The main panic condition is that a Loan object derived from the lend method on a store may never outlive the store it originated from. If this condition happens the store will generate a panic as it goes out of scope, noting the number of outstanding Loan objects.

Methods

impl<K, V> LendingLibrary<K, V> where
    K: Hash + Eq + Copy, 

pub fn new() -> LendingLibrary<K, V>

Creates a new empty LendingLibrary.

Example

use lending_library::LendingLibrary;
let mut lib: LendingLibrary<i32, i32> = LendingLibrary::new();

pub fn with_capacity(capacity: usize) -> LendingLibrary<K, V>

Creates an empty LendingLibrary with at least the specified capacity. The library will be able to hold at least capacity elements without reallocating.

Example

use lending_library::LendingLibrary;
let mut lib: LendingLibrary<i32, i32> = LendingLibrary::with_capacity(100);

pub fn capacity(&self) -> usize

Returns the number of elements the library can store without reallocating. The same bounds as HashMap::capacity() apply.

Example

use lending_library::LendingLibrary;
let mut lib: LendingLibrary<i32, i32> = LendingLibrary::with_capacity(100);
assert!(lib.capacity() >= 100);

pub fn reserve(&mut self, additional: usize)

Reserves space such that the library can store at least additional new records without reallocating.

Example

use lending_library::LendingLibrary;
let mut lib: LendingLibrary<i32, i32> = LendingLibrary::with_capacity(0);
assert_eq!(lib.capacity(), 0);
lib.reserve(10);
assert!(lib.capacity() >= 10);

pub fn shrink_to_fit(&mut self)

Reduces the stores capacity to the minimum currently required.

Example

use lending_library::LendingLibrary;
let mut lib: LendingLibrary<i32, i32> = LendingLibrary::with_capacity(10);
assert!(lib.capacity() >= 10);
lib.shrink_to_fit();
assert_eq!(lib.capacity(), 0);

Important traits for Iter<'a, K, V>

impl<'a, K, V> Iterator for Iter<'a, K, V> type Item = (&'a K, &'a V);

pub fn iter(&self) -> Iter<K, V>

An iterator visiting all key/value pairs in arbitary order. The item type is (&'a K, &'a V)

Panics

The iterator will panic if it encounters an item that is currently loaned from the store, so this should only be used where you are sure you have returned all loaned items.

Important traits for IterMut<'a, K, V>

impl<'a, K, V> Iterator for IterMut<'a, K, V> type Item = (&'a K, &'a mut V);

pub fn iter_mut(&mut self) -> IterMut<K, V>

An iterator visiting all key/value pairs in arbitary order, with mutable references to the values. The item type is (&'a K, &'a mut V)

Panics

The iterator will panic if it encounters an item that is currently loaned from the store, so this should only be used where you are sure you have returned all loaned items.

pub fn len(&self) -> usize

Returns the number of items in the store.

Example

use lending_library::LendingLibrary;
let mut lib: LendingLibrary<i32, i32> = LendingLibrary::new();
lib.insert(1, 1);
lib.insert(2, 1);
assert_eq!(lib.len(), 2);

pub fn is_empty(&self) -> bool

Returns true if the store is empty and false otherwise.

Example

use lending_library::LendingLibrary;
let mut lib: LendingLibrary<i32, i32> = LendingLibrary::new();
assert!(lib.is_empty());
lib.insert(1, 1);
lib.insert(2, 1);
assert!(!lib.is_empty());

pub fn clear(&mut self)

Removes all items from the store.

Example

use lending_library::LendingLibrary;
let mut lib: LendingLibrary<i32, i32> = LendingLibrary::new();
lib.insert(1, 1);
lib.insert(2, 1);
{
    let v = lib.lend(2).unwrap();
    assert_eq!(*v, 1);
}
lib.clear();
assert_eq!(lib.lend(1), None);

pub fn contains_key(&self, key: K) -> bool

Returns true if a record with key key exists in the store, and false otherwise.

Example

use lending_library::LendingLibrary;
let mut lib: LendingLibrary<i32, i32> = LendingLibrary::new();
assert!(!lib.contains_key(1));
lib.insert(1, 1);
assert!(lib.contains_key(1));

pub fn insert(&mut self, key: K, val: V) -> Option<V>

Inserts a new key/value pair into the store. If a pair with that key already exists, the previous values will be returned as Some(V), otherwise the method returns None.

Panics

The method will panic if you attempt to overwrite a key/value pair that is currently loaned.

Example

use lending_library::LendingLibrary;
let mut lib: LendingLibrary<i32, i32> = LendingLibrary::new();
lib.insert(1, 1);
lib.insert(2, 1);

pub fn remove(&mut self, key: K) -> bool

Removes a key/value pair from the store. Returning true if the key was present in the store and false otherwise.

Example

use lending_library::LendingLibrary;
let mut lib: LendingLibrary<i32, i32> = LendingLibrary::new();
assert!(!lib.remove(1));
lib.insert(1, 1);
assert!(lib.contains_key(1));
assert!(lib.remove(1));
assert!(!lib.contains_key(1));
assert!(!lib.remove(1));

pub fn lend(&mut self, key: K) -> Option<Loan<K, V>>

Loans a value from the library, returning Some(Loan<K, V>) if the value is present, and None if it is not.

Panics

Will panic if you try and loan a value that still has an outstanding loan.

Examples

use lending_library::LendingLibrary;
let mut lib: LendingLibrary<i32, i32> = LendingLibrary::with_capacity(0);
lib.insert(1, 1);
{
    let mut v = lib.lend(1).unwrap();
    *v += 5;
}

Trait Implementations

impl<'a, K, V> IntoIterator for &'a LendingLibrary<K, V> where
    K: Hash + Eq + Copy, 

type Item = (&'a K, &'a V)

The type of the elements being iterated over.

type IntoIter = Iter<'a, K, V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, K, V> IntoIterator for &'a mut LendingLibrary<K, V> where
    K: Hash + Eq + Copy, 

type Item = (&'a K, &'a mut V)

The type of the elements being iterated over.

type IntoIter = IterMut<'a, K, V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<K, V> Drop for LendingLibrary<K, V> where
    K: Hash + Eq + Copy, 

fn drop(&mut self)

Executes the destructor for this type.

impl<K, V> Default for LendingLibrary<K, V> where
    K: Hash + Eq + Copy, 

fn default() -> Self

Returns the "default value" for a type.