Struct bimap::BiMap

pub struct BiMap<L, R> { /* fields omitted */ }

A two-way map between left values and right values.

See the module-level documentation for more details and examples.

Methods

impl<L, R> BiMap<L, R> where
    L: Eq + Hash,
    R: Eq + Hash, 

pub fn new() -> BiMap<L, R>

Creates an empty BiMap.

Examples

use bimap::BiMap;

let mut bimap: BiMap<char, u32> = BiMap::new();

pub fn with_capacity(capacity: usize) -> BiMap<L, R>

Creates an empty BiMap with the given capacity.

Examples

use bimap::BiMap;

let mut bimap: BiMap<char, u32> = BiMap::with_capacity(5);

pub fn len(&self) -> usize

Returns the number of left-right pairs in the map.

Examples

use bimap::BiMap;

let mut bimap = BiMap::new();
bimap.insert('a', 1);
bimap.insert('b', 2);
bimap.insert('c', 3);
assert_eq!(bimap.len(), 3);

pub fn is_empty(&self) -> bool

Returns true if the map contains no left-right pairs, and false otherwise.

Examples

use bimap::BiMap;

let mut bimap = BiMap::new();
assert!(bimap.is_empty());
bimap.insert('a', 1);
assert!(!bimap.is_empty());
bimap.remove_by_right(&1);
assert!(bimap.is_empty());

pub fn clear(&mut self)

Removes all left-right pairs from the BiMap, but keeps the allocated memory for reuse.

Examples

use bimap::BiMap;

let mut bimap = BiMap::new();
bimap.insert('a', 1);
bimap.insert('b', 2);
bimap.insert('c', 3);
bimap.clear();
assert!(bimap.len() == 0);
assert!(bimap.capacity() >= 3);

pub fn capacity(&self) -> usize

Returns a lower bound on the number of left-right pairs the BiMap can store without reallocating memory.

Examples

use bimap::BiMap;

let mut bimap: BiMap<char, u32> = BiMap::with_capacity(5);
assert!(bimap.capacity() >= 5);

Important traits for Iter<'a, L, R>

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

pub fn iter<'a>(&'a self) -> Iter<'a, L, R>

Create an iterator over the left-right pairs in the BiMap in arbitrary order.

The iterator element type is (&'a L, &'a R).

Examples

use bimap::BiMap;

let mut bimap = BiMap::new();
bimap.insert('a', 1);
bimap.insert('b', 2);
bimap.insert('c', 3);

for (left, right) in bimap.iter() {
    println!("({}, {})", left, right);
}

Important traits for LeftValues<'a, L, R>

impl<'a, L, R> Iterator for LeftValues<'a, L, R> type Item = &'a L;

pub fn left_values<'a>(&'a self) -> LeftValues<'a, L, R>

Create an iterator over the left values in the BiMap in arbitrary order.

The iterator element type is &'a L.

Examples

use bimap::BiMap;

let mut bimap = BiMap::new();
bimap.insert('a', 1);
bimap.insert('b', 2);
bimap.insert('c', 3);

for char_value in bimap.left_values() {
    println!("{}", char_value);
}

Important traits for RightValues<'a, L, R>

impl<'a, L, R> Iterator for RightValues<'a, L, R> type Item = &'a R;

pub fn right_values<'a>(&'a self) -> RightValues<'a, L, R>

Create an iterator over the right values in the BiMap in arbitrary order.

The iterator element type is &'a R.

Examples

use bimap::BiMap;

let mut bimap = BiMap::new();
bimap.insert('a', 1);
bimap.insert('b', 2);
bimap.insert('c', 3);

for int_value in bimap.right_values() {
    println!("{}", int_value);
}

pub fn get_by_left(&self, left: &L) -> Option<&R>

Returns a reference to the right value corresponding to the given left value.

Examples

use bimap::BiMap;

let mut bimap = BiMap::new();
bimap.insert('a', 1);
assert_eq!(bimap.get_by_left(&'a'), Some(&1));
assert_eq!(bimap.get_by_left(&'z'), None);

pub fn get_by_right(&self, right: &R) -> Option<&L>

Returns a reference to the left value corresponding to the given right value.

Examples

use bimap::BiMap;

let mut bimap = BiMap::new();
bimap.insert('a', 1);
assert_eq!(bimap.get_by_right(&1), Some(&'a'));
assert_eq!(bimap.get_by_right(&2), None);

pub fn contains_left(&self, left: &L) -> bool

Returns true if the map contains the given left value and false otherwise.

Examples

use bimap::BiMap;

let mut bimap = BiMap::new();
bimap.insert('a', 1);
assert!(bimap.contains_left(&'a'));
assert!(!bimap.contains_left(&'b'));

pub fn contains_right(&self, right: &R) -> bool

Returns true if the map contains the given right value and false otherwise.

Examples

use bimap::BiMap;

let mut bimap: BiMap<char, u32> = BiMap::new();
bimap.insert('a', 1);
assert!(bimap.contains_right(&1));
assert!(!bimap.contains_right(&2));

pub fn remove_by_left(&mut self, left: &L) -> Option<(L, R)>

Removes the left-right pair corresponding to the given left value.

Returns the previous left-right pair if the map contained the left value and None otherwise.

Examples

use bimap::BiMap;

let mut bimap = BiMap::new();
bimap.insert('a', 1);
bimap.insert('b', 2);
bimap.insert('c', 3);
assert_eq!(bimap.len(), 3);
assert_eq!(bimap.remove_by_left(&'b'), Some(('b', 2)));
assert_eq!(bimap.len(), 2);
assert_eq!(bimap.remove_by_left(&'b'), None);
assert_eq!(bimap.len(), 2);

pub fn remove_by_right(&mut self, right: &R) -> Option<(L, R)>

Removes the left-right pair corresponding to the given right value.

Returns the previous left-right pair if the map contained the right value and None otherwise.

Examples

use bimap::BiMap;

let mut bimap = BiMap::new();
bimap.insert('a', 1);
bimap.insert('b', 2);
bimap.insert('c', 3);
assert_eq!(bimap.len(), 3);
assert_eq!(bimap.remove_by_right(&2), Some(('b', 2)));
assert_eq!(bimap.len(), 2);
assert_eq!(bimap.remove_by_right(&2), None);
assert_eq!(bimap.len(), 2);

pub fn insert(&mut self, left: L, right: R) -> Overwritten<L, R>

Inserts the given left-right pair into the BiMap.

Returns an enum Overwritten representing any left-right pairs that were overwritten by the call to insert. The example below details all possible enum variants that can be returned.

Warnings

Somewhat paradoxically, calling insert() can actually reduce the size of the BiMap! This is because of the invariant that each left value maps to exactly one right value and vice versa.

Examples

use bimap::{BiMap, Overwritten};

let mut bimap = BiMap::new();
assert_eq!(bimap.len(), 0); // {}

// no values are overwritten.
assert_eq!(bimap.insert('a', 1), Overwritten::Neither);
assert_eq!(bimap.len(), 1); // {'a' <> 1}

// no values are overwritten.
assert_eq!(bimap.insert('b', 2), Overwritten::Neither);
assert_eq!(bimap.len(), 2); // {'a' <> 1, 'b' <> 2}

// ('a', 1) already exists, so inserting ('a', 4) overwrites 'a', the left value.
// the previous left-right pair ('a', 1) is returned.
assert_eq!(bimap.insert('a', 4), Overwritten::Left('a', 1));
assert_eq!(bimap.len(), 2); // {'a' <> 4, 'b' <> 2}

// ('b', 2) already exists, so inserting ('c', 2) overwrites 2, the right value
// the previous left-right pair ('b', 2) is returned.
assert_eq!(bimap.insert('c', 2), Overwritten::Right('b', 2));
assert_eq!(bimap.len(), 2); // {'a' <> 1, 'c' <> 2}

// both ('a', 4) and ('c', 2) already exist, so inserting ('a', 2) overwrites both.
// ('a', 4) has the overwritten left value ('a'), so it's the first tuple returned.
// ('c', 2) has the overwritten right value (2), so it's the second tuple returned.
assert_eq!(bimap.insert('a', 2), Overwritten::Both(('a', 4), ('c', 2)));
assert_eq!(bimap.len(), 1); // {'a' <> 2} // bimap is smaller than before!

// ('a', 2) already exists, so inserting ('a', 2) overwrites the pair.
// the previous left-right pair ('a', 2) is returned.
assert_eq!(bimap.insert('a', 2), Overwritten::Pair('a', 2));
assert_eq!(bimap.len(), 1); // {'a' <> 2}

pub fn insert_no_overwrite(&mut self, left: L, right: R) -> bool

Inserts the given left-right pair into the BiMap without overwriting any existing values.

Returns a boolean representing if the pair was successfully inserted into the BiMap. If either value exists in the map, false is returned and the map is unchanged. Otherwise, the pair is inserted and true is returned.

Examples

use bimap::BiMap;

let mut bimap = BiMap::new();
assert!(bimap.insert_no_overwrite('a', 1));
assert!(bimap.insert_no_overwrite('b', 2));
assert!(!bimap.insert_no_overwrite('a', 3));
assert!(!bimap.insert_no_overwrite('c', 2));

pub fn retain<F>(&mut self, f: F) where
    F: FnMut(&L, &R) -> bool, 

Retains only the elements specified by the predicate.

In other words, remove all pairs (l, r) such that f(&l, &r) returns false.

This is called for both internal HashMaps.

Examples

use bimap::BiMap;

let mut bimap = BiMap::new();
bimap.insert('a', 1);
bimap.insert('b', 2);
bimap.insert('c', 3);
bimap.retain(|&l, &r| r >= 2);
assert_eq!(bimap.len(), 2);
assert_eq!(bimap.get_by_left(&'b'), Some(&2));
assert_eq!(bimap.get_by_left(&'c'), Some(&3));
assert_eq!(bimap.get_by_left(&'a'), None);

Trait Implementations

impl<L, R> Clone for BiMap<L, R> where
    L: Eq + Hash + Clone,
    R: Eq + Hash + Clone, 

fn clone(&self) -> BiMap<L, R>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<L, R> Debug for BiMap<L, R> where
    L: Eq + Hash + Debug,
    R: Eq + Hash + Debug, 

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<L, R> Default for BiMap<L, R> where
    L: Eq + Hash,
    R: Eq + Hash, 

fn default() -> BiMap<L, R>

Returns the "default value" for a type.

impl<L, R> Eq for BiMap<L, R> where
    L: Eq + Hash,
    R: Eq + Hash, 

impl<L, R> FromIterator<(L, R)> for BiMap<L, R> where
    L: Eq + Hash,
    R: Eq + Hash, 

fn from_iter<I>(iter: I) -> BiMap<L, R> where
    I: IntoIterator<Item = (L, R)>, 

Creates a value from an iterator.

impl<'a, L, R> IntoIterator for &'a BiMap<L, R> where
    L: Eq + Hash,
    R: Eq + Hash, 

type Item = (&'a L, &'a R)

The type of the elements being iterated over.

type IntoIter = Iter<'a, L, R>

Which kind of iterator are we turning this into?

Important traits for Iter<'a, L, R>

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

fn into_iter(self) -> Iter<'a, L, R>

Creates an iterator from a value.

impl<L, R> IntoIterator for BiMap<L, R> where
    L: Eq + Hash,
    R: Eq + Hash, 

type Item = (L, R)

The type of the elements being iterated over.

type IntoIter = IntoIter<L, R>

Which kind of iterator are we turning this into?

Important traits for IntoIter<L, R>

impl<L, R> Iterator for IntoIter<L, R> type Item = (L, R);

fn into_iter(self) -> IntoIter<L, R>

Creates an iterator from a value.

impl<L, R> PartialEq for BiMap<L, R> where
    L: Eq + Hash,
    R: Eq + Hash, 

fn eq(&self, other: &BiMap<L, R>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<L: Send, R: Send> Send for BiMap<L, R>

impl<L: Sync, R: Sync> Sync for BiMap<L, R>