Struct im_rc::OrdMap

source · [−]
pub struct OrdMap<K, V> { /* private fields */ }
Expand description

An ordered map.

An immutable ordered map implemented as a B-tree.

Most operations on this type of map are O(log n). A HashMap is usually a better choice for performance, but the OrdMap has the advantage of only requiring an Ord constraint on the key, and of being ordered, so that keys always come out from lowest to highest, where a HashMap has no guaranteed ordering.

Implementations

Construct an empty map.

Construct a map with a single mapping.

Examples
let map = OrdMap::unit(123, "onetwothree");
assert_eq!(
  map.get(&123),
  Some(&"onetwothree")
);

Test whether a map is empty.

Time: O(1)

Examples
assert!(
  !ordmap!{1 => 2}.is_empty()
);
assert!(
  OrdMap::<i32, i32>::new().is_empty()
);

Test whether two maps refer to the same content in memory.

This is true if the two sides are references to the same map, or if the two maps refer to the same root node.

This would return true if you’re comparing a map to itself, or if you’re comparing a map to a fresh clone of itself.

Time: O(1)

Get the size of a map.

Time: O(1)

Examples
assert_eq!(3, ordmap!{
  1 => 11,
  2 => 22,
  3 => 33
}.len());

Discard all elements from the map.

This leaves you with an empty map, and all elements that were previously inside it are dropped.

Time: O(n)

Examples
let mut map = ordmap![1=>1, 2=>2, 3=>3];
map.clear();
assert!(map.is_empty());

Get the largest key in a map, along with its value. If the map is empty, return None.

Time: O(log n)

Examples
assert_eq!(Some(&(3, 33)), ordmap!{
  1 => 11,
  2 => 22,
  3 => 33
}.get_max());

Get the smallest key in a map, along with its value. If the map is empty, return None.

Time: O(log n)

Examples
assert_eq!(Some(&(1, 11)), ordmap!{
  1 => 11,
  2 => 22,
  3 => 33
}.get_min());

Get an iterator over the key/value pairs of a map.

Create an iterator over a range of key/value pairs.

Get an iterator over a map’s keys.

Get an iterator over a map’s values.

Get an iterator over the differences between this map and another, i.e. the set of entries to add, update, or remove to this map in order to make it equal to the other map.

This function will avoid visiting nodes which are shared between the two maps, meaning that even very large maps can be compared quickly if most of their structure is shared.

Time: O(n) (where n is the number of unique elements across the two maps, minus the number of elements belonging to nodes shared between them)

Get the value for a key from a map.

Time: O(log n)

Examples
let map = ordmap!{123 => "lol"};
assert_eq!(
  map.get(&123),
  Some(&"lol")
);

Get the key/value pair for a key from a map.

Time: O(log n)

Examples
let map = ordmap!{123 => "lol"};
assert_eq!(
  map.get_key_value(&123),
  Some((&123, &"lol"))
);

Get the closest smaller entry in a map to a given key as a mutable reference.

If the map contains the given key, this is returned. Otherwise, the closest key in the map smaller than the given value is returned. If the smallest key in the map is larger than the given key, None is returned.

Examples
let map = ordmap![1 => 1, 3 => 3, 5 => 5];
assert_eq!(Some((&3, &3)), map.get_prev(&4));

Get the closest larger entry in a map to a given key as a mutable reference.

If the set contains the given value, this is returned. Otherwise, the closest value in the set larger than the given value is returned. If the largest value in the set is smaller than the given value, None is returned.

Examples
let map = ordmap![1 => 1, 3 => 3, 5 => 5];
assert_eq!(Some((&5, &5)), map.get_next(&4));

Test for the presence of a key in a map.

Time: O(log n)

Examples
let map = ordmap!{123 => "lol"};
assert!(
  map.contains_key(&123)
);
assert!(
  !map.contains_key(&321)
);

Test whether a map is a submap of another map, meaning that all keys in our map must also be in the other map, with the same values.

Use the provided function to decide whether values are equal.

Time: O(n log n)

Test whether a map is a proper submap of another map, meaning that all keys in our map must also be in the other map, with the same values. To be a proper submap, ours must also contain fewer keys than the other map.

Use the provided function to decide whether values are equal.

Time: O(n log n)

Test whether a map is a submap of another map, meaning that all keys in our map must also be in the other map, with the same values.

Time: O(n log n)

Examples
let map1 = ordmap!{1 => 1, 2 => 2};
let map2 = ordmap!{1 => 1, 2 => 2, 3 => 3};
assert!(map1.is_submap(map2));

Test whether a map is a proper submap of another map, meaning that all keys in our map must also be in the other map, with the same values. To be a proper submap, ours must also contain fewer keys than the other map.

Time: O(n log n)

Examples
let map1 = ordmap!{1 => 1, 2 => 2};
let map2 = ordmap!{1 => 1, 2 => 2, 3 => 3};
assert!(map1.is_proper_submap(map2));

let map3 = ordmap!{1 => 1, 2 => 2};
let map4 = ordmap!{1 => 1, 2 => 2};
assert!(!map3.is_proper_submap(map4));

Get a mutable reference to the value for a key from a map.

Time: O(log n)

Examples
let mut map = ordmap!{123 => "lol"};
if let Some(value) = map.get_mut(&123) {
    *value = "omg";
}
assert_eq!(
  map.get(&123),
  Some(&"omg")
);

Get the closest smaller entry in a map to a given key as a mutable reference.

If the map contains the given key, this is returned. Otherwise, the closest key in the map smaller than the given value is returned. If the smallest key in the map is larger than the given key, None is returned.

Examples
let mut map = ordmap![1 => 1, 3 => 3, 5 => 5];
if let Some((key, value)) = map.get_prev_mut(&4) {
    *value = 4;
}
assert_eq!(ordmap![1 => 1, 3 => 4, 5 => 5], map);

Get the closest larger entry in a map to a given key as a mutable reference.

If the set contains the given value, this is returned. Otherwise, the closest value in the set larger than the given value is returned. If the largest value in the set is smaller than the given value, None is returned.

Examples
let mut map = ordmap![1 => 1, 3 => 3, 5 => 5];
if let Some((key, value)) = map.get_next_mut(&4) {
    *value = 4;
}
assert_eq!(ordmap![1 => 1, 3 => 3, 5 => 4], map);

Insert a key/value mapping into a map.

This is a copy-on-write operation, so that the parts of the map’s structure which are shared with other maps will be safely copied before mutating.

If the map already has a mapping for the given key, the previous value is overwritten.

Time: O(log n)

Examples
let mut map = ordmap!{};
map.insert(123, "123");
map.insert(456, "456");
assert_eq!(
  map,
  ordmap!{123 => "123", 456 => "456"}
);

Remove a key/value mapping from a map if it exists.

Time: O(log n)

Examples
let mut map = ordmap!{123 => "123", 456 => "456"};
map.remove(&123);
map.remove(&456);
assert!(map.is_empty());

Remove a key/value pair from a map, if it exists, and return the removed key and value.

Time: O(log n)

Construct a new map by inserting a key/value mapping into a map.

If the map already has a mapping for the given key, the previous value is overwritten.

Time: O(log n)

Examples
let map = ordmap!{};
assert_eq!(
  map.update(123, "123"),
  ordmap!{123 => "123"}
);

Construct a new map by inserting a key/value mapping into a map.

If the map already has a mapping for the given key, we call the provided function with the old value and the new value, and insert the result as the new value.

Time: O(log n)

Construct a new map by inserting a key/value mapping into a map.

If the map already has a mapping for the given key, we call the provided function with the key, the old value and the new value, and insert the result as the new value.

Time: O(log n)

Construct a new map by inserting a key/value mapping into a map, returning the old value for the key as well as the new map.

If the map already has a mapping for the given key, we call the provided function with the key, the old value and the new value, and insert the result as the new value.

Time: O(log n)

Update the value for a given key by calling a function with the current value and overwriting it with the function’s return value.

The function gets an Option<V> and returns the same, so that it can decide to delete a mapping instead of updating the value, and decide what to do if the key isn’t in the map.

Time: O(log n)

Remove a key/value pair from a map, if it exists.

Time: O(log n)

Remove a key/value pair from a map, if it exists, and return the removed value as well as the updated list.

Time: O(log n)

Remove a key/value pair from a map, if it exists, and return the removed key and value as well as the updated list.

Time: O(log n)

Construct the union of two maps, keeping the values in the current map when keys exist in both maps.

Time: O(n log n)

Examples
let map1 = ordmap!{1 => 1, 3 => 3};
let map2 = ordmap!{2 => 2, 3 => 4};
let expected = ordmap!{1 => 1, 2 => 2, 3 => 3};
assert_eq!(expected, map1.union(map2));

Construct the union of two maps, using a function to decide what to do with the value when a key is in both maps.

The function is called when a value exists in both maps, and receives the value from the current map as its first argument, and the value from the other map as the second. It should return the value to be inserted in the resulting map.

Time: O(n log n)

Construct the union of two maps, using a function to decide what to do with the value when a key is in both maps.

The function is called when a value exists in both maps, and receives a reference to the key as its first argument, the value from the current map as the second argument, and the value from the other map as the third argument. It should return the value to be inserted in the resulting map.

Time: O(n log n)

Examples
let map1 = ordmap!{1 => 1, 3 => 4};
let map2 = ordmap!{2 => 2, 3 => 5};
let expected = ordmap!{1 => 1, 2 => 2, 3 => 9};
assert_eq!(expected, map1.union_with_key(
    map2,
    |key, left, right| left + right
));

Construct the union of a sequence of maps, selecting the value of the leftmost when a key appears in more than one map.

Time: O(n log n)

Examples
let map1 = ordmap!{1 => 1, 3 => 3};
let map2 = ordmap!{2 => 2};
let expected = ordmap!{1 => 1, 2 => 2, 3 => 3};
assert_eq!(expected, OrdMap::unions(vec![map1, map2]));

Construct the union of a sequence of maps, using a function to decide what to do with the value when a key is in more than one map.

The function is called when a value exists in multiple maps, and receives the value from the current map as its first argument, and the value from the next map as the second. It should return the value to be inserted in the resulting map.

Time: O(n log n)

Construct the union of a sequence of maps, using a function to decide what to do with the value when a key is in more than one map.

The function is called when a value exists in multiple maps, and receives a reference to the key as its first argument, the value from the current map as the second argument, and the value from the next map as the third argument. It should return the value to be inserted in the resulting map.

Time: O(n log n)

Construct the symmetric difference between two maps by discarding keys which occur in both maps.

This is an alias for the symmetric_difference method.

Time: O(n log n)

Examples
let map1 = ordmap!{1 => 1, 3 => 4};
let map2 = ordmap!{2 => 2, 3 => 5};
let expected = ordmap!{1 => 1, 2 => 2};
assert_eq!(expected, map1.difference(map2));

Construct the symmetric difference between two maps by discarding keys which occur in both maps.

Time: O(n log n)

Examples
let map1 = ordmap!{1 => 1, 3 => 4};
let map2 = ordmap!{2 => 2, 3 => 5};
let expected = ordmap!{1 => 1, 2 => 2};
assert_eq!(expected, map1.symmetric_difference(map2));

Construct the symmetric difference between two maps by using a function to decide what to do if a key occurs in both.

This is an alias for the symmetric_difference_with method.

Time: O(n log n)

Construct the symmetric difference between two maps by using a function to decide what to do if a key occurs in both.

Time: O(n log n)

Construct the symmetric difference between two maps by using a function to decide what to do if a key occurs in both. The function receives the key as well as both values.

This is an alias for the symmetric_difference_with_key method.

Time: O(n log n)

Examples
let map1 = ordmap!{1 => 1, 3 => 4};
let map2 = ordmap!{2 => 2, 3 => 5};
let expected = ordmap!{1 => 1, 2 => 2, 3 => 9};
assert_eq!(expected, map1.difference_with_key(
    map2,
    |key, left, right| Some(left + right)
));

Construct the symmetric difference between two maps by using a function to decide what to do if a key occurs in both. The function receives the key as well as both values.

Time: O(n log n)

Examples
let map1 = ordmap!{1 => 1, 3 => 4};
let map2 = ordmap!{2 => 2, 3 => 5};
let expected = ordmap!{1 => 1, 2 => 2, 3 => 9};
assert_eq!(expected, map1.symmetric_difference_with_key(
    map2,
    |key, left, right| Some(left + right)
));

Construct the relative complement between two maps by discarding keys which occur in other.

Time: O(m log n) where m is the size of the other map

Examples
let map1 = ordmap!{1 => 1, 3 => 4};
let map2 = ordmap!{2 => 2, 3 => 5};
let expected = ordmap!{1 => 1};
assert_eq!(expected, map1.relative_complement(map2));

Construct the intersection of two maps, keeping the values from the current map.

Time: O(n log n)

Examples
let map1 = ordmap!{1 => 1, 2 => 2};
let map2 = ordmap!{2 => 3, 3 => 4};
let expected = ordmap!{2 => 2};
assert_eq!(expected, map1.intersection(map2));

Construct the intersection of two maps, calling a function with both values for each key and using the result as the value for the key.

Time: O(n log n)

Construct the intersection of two maps, calling a function with the key and both values for each key and using the result as the value for the key.

Time: O(n log n)

Examples
let map1 = ordmap!{1 => 1, 2 => 2};
let map2 = ordmap!{2 => 3, 3 => 4};
let expected = ordmap!{2 => 5};
assert_eq!(expected, map1.intersection_with_key(
    map2,
    |key, left, right| left + right
));

Split a map into two, with the left hand map containing keys which are smaller than split, and the right hand map containing keys which are larger than split.

The split mapping is discarded.

Split a map into two, with the left hand map containing keys which are smaller than split, and the right hand map containing keys which are larger than split.

Returns both the two maps and the value of split.

Construct a map with only the n smallest keys from a given map.

Construct a map with the n smallest keys removed from a given map.

Remove the smallest key from a map, and return its value as well as the updated map.

Remove the smallest key from a map, and return that key, its value as well as the updated map.

Remove the largest key from a map, and return its value as well as the updated map.

Remove the largest key from a map, and return that key, its value as well as the updated map.

Get the Entry for a key in the map for in-place manipulation.

Time: O(log n)

Trait Implementations

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

Converts this type into a shared reference of the (usually inferred) input type.

Clone a map.

Time: O(1)

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Extends a collection with the contents of an iterator. Read more

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements. Read more

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Creates a value from an iterator. Read more

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

The returned type after indexing.

Performs the indexing (container[index]) operation. Read more

Performs the mutable indexing (container[index]) operation. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

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

This method tests for !=.

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

Method which takes an iterator and generates Self from the elements by “summing up” the items. 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.

Should always be Self

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

Uses borrowed data to replace owned data, usually by cloning. Read more

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.