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)