Struct hashcow::CowHashMap

pub struct CowHashMap<'a, K: ?Sized, V: ?Sized> where
    K: Hash + PartialEq + Eq + ToOwned,
    V: ToOwned,  { /* fields omitted */ }

A HashMap data-structure with copy-on-write keys and values.

Methods

impl<'a, K: ?Sized, V: ?Sized> CowHashMap<'a, K, V> where
    K: Hash + PartialEq + Eq + ToOwned,
    V: ToOwned, 

pub fn new() -> Self

Creates a new CowHashMap.

Example

use hashcow::CowHashMap;
 
let hm: CowHashMap<str, String> = CowHashMap::new();

pub fn with_capacity(capacity: usize) -> Self

Creates a new CowHashMap with the specified capacity.

Example

use hashcow::CowHashMap;
 
let hm: CowHashMap<str, String> = CowHashMap::with_capacity(5);
assert!(hm.capacity() >= 5);

pub fn capacity(&self) -> usize

Returns the number of elements the map can hold without reallocating.

This number is a lower bound; the map might be able to hold more elements, but is guaranteed to be able to hold at least this many elements.

Example

use hashcow::CowHashMap;
 
let hm: CowHashMap<str, [u8]> = CowHashMap::new();
assert_eq!(hm.capacity(), 0);

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

Reserves capacity for at least additional more elements to be inserted in the map. The collection may reserve more space to avoid frequent reallocations.

pub fn shrink_to_fit(&mut self)

Shrinks the map as much as possible while retaining the number of elements.

pub fn clear(&mut self)

Clears the map, removing all key-value pairs. Keeps the allocated memory for reuse.

pub fn is_empty(&self) -> bool

Returns true if the map contains no elements.

Example

use hashcow::CowHashMap;
 
let mut hm: CowHashMap<str, [u8]> = CowHashMap::new();
assert!(hm.is_empty());
 
hm.insert_owned("key".to_owned(), vec![1, 2, 3]);
assert!(!hm.is_empty());

pub fn insert_owned(
    &mut self,
    key: <K as ToOwned>::Owned,
    value: <V as ToOwned>::Owned
) -> Option<<V as ToOwned>::Owned>

Inserts a new key/value pair into the map with the value being in the owned form.

This function returns None if there was no value previously associated with the given key. If the key is replaced, this function returns the previous value. If the previous value is borrowed, it will be cloned and then returned.

Example

use hashcow::CowHashMap;
 
let mut hm: CowHashMap<str, [u8]> = CowHashMap::new();
hm.insert_owned("key".to_owned(), vec![1, 2, 3]);

assert_eq!(hm.len(), 1);

pub fn insert_owned_borrowed_key(
    &mut self,
    key: &'a K,
    value: <V as ToOwned>::Owned
) -> Option<<V as ToOwned>::Owned>

Inserts a new key/value pair into the map with the value being in the owned form and the key in borrowed form.

This function returns None if there was no value previously associated with the given key. If the key is replaced, this function returns the previous value. If the previous value is borrowed, it will be cloned and then returned.

Example

use hashcow::CowHashMap;
 
let mut hm: CowHashMap<str, [u8]> = CowHashMap::new();
hm.insert_owned_borrowed_key("key", vec![1, 2, 3]);

assert_eq!(hm.len(), 1);

pub fn insert_borrowed(
    &mut self,
    key: &'a K,
    value: &'a V
) -> Option<<V as ToOwned>::Owned>

Inserts a new key/value pair in to the map with the value being in borrowed form.

This function returns None if there was no value previously associated with the given key. If the key is replaced, this function returns the previous value. If the previous value is borrowed, it will be cloned and then returned.

Example

use hashcow::CowHashMap;
 
let mut hm: CowHashMap<str, [u8]> = CowHashMap::new();
hm.insert_borrowed("key", &[1, 2, 3]);

assert_eq!(hm.len(), 1);

pub fn insert_borrowed_owned_key(
    &mut self,
    key: <K as ToOwned>::Owned,
    value: &'a V
) -> Option<<V as ToOwned>::Owned>

Inserts a new key/value pair in to the map with the value being in borrowed form and the key in owned form.

This function returns None if there was no value previously associated with the given key. If the key is replaced, this function returns the previous value. If the previous value is borrowed, it will be cloned and then returned.

Example

use hashcow::CowHashMap;
 
let mut hm: CowHashMap<str, [u8]> = CowHashMap::new();
hm.insert_borrowed_owned_key("key".to_owned(), &[1, 2, 3]);

assert_eq!(hm.len(), 1);

pub fn get(&self, key: &K) -> Option<&V>

Attempts to retrieve a reference to an item stored in the map.

Example

use hashcow::CowHashMap;
 
let mut hm: CowHashMap<str, [u8]> = CowHashMap::new();
hm.insert_borrowed("key1", &[1, 2, 3]);
hm.insert_owned("key2".to_owned(), vec![4, 5, 6]);

assert_eq!(hm.len(), 2);
assert_eq!(hm.get(&"key1").unwrap(), &[1, 2, 3]);
assert_eq!(hm.get(&"key2").unwrap(), &[4, 5, 6]);

pub fn get_mut(&mut self, key: &K) -> Option<&mut <V as ToOwned>::Owned>

Attempts to retrieve a mutable reference to the owned form of an item stored in the map.

If the stored entry is in the borrowed form, this function will clone the underlying data.

Example

use hashcow::{Form, CowHashMap};
 
let mut hm: CowHashMap<str, [u8]> = CowHashMap::new();
hm.insert_borrowed("key1", &[1, 2, 3]);
 
assert_eq!(hm.entry_form(&"key1").unwrap(), Form::Borrowed);
 
{
    // This will clone the entry stored at this key
    let entry = hm.get_mut(&"key1").unwrap();
    assert_eq!(entry, &mut vec![1, 2, 3]);
     
    *entry = vec![4, 5, 6];
}

assert_eq!(hm.entry_form(&"key1").unwrap(), Form::Owned);
assert_eq!(hm.get(&"key1").unwrap(), &[4, 5, 6]);

pub fn keys(&self) -> impl Iterator<Item = &K>

Returns an iterator over the keys of the map.

Example

use hashcow::CowHashMap;
 
let mut hm: CowHashMap<str, [u8]> = CowHashMap::new();
hm.insert_borrowed("key1", &[1, 2, 3]);
hm.insert_owned("key2".to_owned(), vec![4, 5, 6]);
 
let keys: HashSet<&str> = hm.keys().collect();
assert_eq!(keys, set!["key1", "key2"]);

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

Makes a specific value in the map owned, if it isn't so already.

This function does not do anything if the value is already in owned form.

pub fn len(&self) -> usize

Returns the number of elements that are currently in the map.

pub fn entry_form(&self, key: &K) -> Option<Form>

If an entry with the given key exists, this function returns the underlying form in which it is stored in the map.

Can be either Form::Borrowed or Form::Owned.

pub fn borrow_fields(&'a self) -> Self

Returns a cloned version of the map but with the entries in borrowed form.

Example

use hashcow::{Form, CowHashMap};
 
let mut hm: CowHashMap<str, [u8]> = CowHashMap::new();
hm.insert_owned("key".to_owned(), vec![1, 2, 3]);
 
assert_eq!(hm.entry_form(&"key").unwrap(), Form::Owned);
 
let hm_clone = hm.borrow_fields();
assert_eq!(hm_clone.entry_form(&"key").unwrap(), Form::Borrowed);

pub fn iter(&self) -> impl Iterator<Item = (&K, &V)>

An iterator visiting all key-value pairs in arbitrary order.

Example

use hashcow::CowHashMap;
 
let mut hm: CowHashMap<str, [u8]> = CowHashMap::new();
hm.insert_borrowed("key1", &[1, 2, 3]);
hm.insert_owned("key2".to_owned(), vec![4, 5, 6]);
 
for (key, val) in hm.iter() {
    // ...
}

pub fn remove(&mut self, key: &K) -> Option<<V as ToOwned>::Owned>

Removes a key from the map, returning the value at the key if the key was previously in the map.

Example

use hashcow::CowHashMap;
 
let mut hm: CowHashMap<str, [u8]> = CowHashMap::new();
assert!(hm.remove(&"key1").is_none());
 
hm.insert_borrowed("key1", &[1, 2, 3]);
assert_eq!(hm.remove(&"key1").unwrap(), vec![1, 2, 3]);