Struct std::collections::hash_map::HashMap1.0.0[−][src]

pub struct HashMap<K, V, S = RandomState> { /* fields omitted */ }
Expand description

通过二次探测和 SIMD 查找实现的 hash map。

默认情况下，HashMap 使用选择为提供对 HashDoS 攻击的抵抗力的哈希算法。 该算法是随机播种的，并且做出了合理的努力以从主机提供的高质量，安全的随机性源生成此 seed，而不会阻塞程序。 因此，seed 的随机性取决于创建 seed 时系统随机数发生器的输出质量。 特别地，当系统的熵池异常低时 (例如在系统引导期间) 生成的种子可能具有较低的质量。

当前的默认哈希算法是 SipHash 1-3，尽管它可能会在 future 的任何位置进行更改。 虽然它的性能对于中等大小的键非常有竞争力，但其他散列算法对于小键（如整数）和大键（如长字符串）的性能将优于它，尽管这些算法通常不能防止诸如 HashDoS 之类的攻击。

可以使用 default，with_hasher 和 with_capacity_and_hasher 方法在每个 HashMap 的基础上替换哈希算法。 hashing algorithms available on crates.io 有很多替代方案。

尽管通常可以通过使用 #[derive(PartialEq, Eq, Hash)] 来实现，但要求键实现 Eq 和 Hash traits。 如果您自己实现这些，那么拥有以下属性非常重要:

k1 == k2 -> hash(k1) == hash(k2)

换句话说，如果两个键相等，则它们的哈希值必须相等。

以这样一种方式修改键是一个逻辑错误，即键的散列（由 Hash 特征确定）或其相等性（由 Eq 特征确定）在更改时发生变化在 map 上。 通常只有通过 Cell，RefCell，二进制状态，I/O 或不安全代码才能实现此操作。 未指定由此类逻辑错误导致的行为，但不会导致未定义的行为。 这可能包括 panics，不正确的结果，异常终止，内存泄漏和未终止。

哈希表实现是 Google SwissTable 的 Rust 端口。 可以在 这里 找到 SwissTable 的原始 C++ 版本，而该 CppCon talk 概述了该算法的工作原理。

Examples

use std::collections::HashMap;

// 通过类型推断，我们可以省略显式类型签名 (在本示例中为 `HashMap<String, String>`)。
let mut book_reviews = HashMap::new();

// 复习一些书。
book_reviews.insert(
    "Adventures of Huckleberry Finn".to_string(),
    "My favorite book.".to_string(),
);
book_reviews.insert(
    "Grimms' Fairy Tales".to_string(),
    "Masterpiece.".to_string(),
);
book_reviews.insert(
    "Pride and Prejudice".to_string(),
    "Very enjoyable.".to_string(),
);
book_reviews.insert(
    "The Adventures of Sherlock Holmes".to_string(),
    "Eye lyked it alot.".to_string(),
);

// 检查一个特定的。
// 当集合存储拥有的值 (String) 时，仍可以使用引用 (&str) 来查询它们。
if !book_reviews.contains_key("Les Misérables") {
    println!("We've got {} reviews, but Les Misérables ain't one.",
             book_reviews.len());
}

// 糟糕，此评论有很多拼写错误，让我们删除它。
book_reviews.remove("The Adventures of Sherlock Holmes");

// 查找与某些键关联的值。
let to_find = ["Pride and Prejudice", "Alice's Adventure in Wonderland"];
for &book in &to_find {
    match book_reviews.get(book) {
        Some(review) => println!("{}: {}", book, review),
        None => println!("{} is unreviewed.", book)
    }
}

// 查找某个键的值 (如果找不到该键，则为 panic)。
println!("Review for Jane: {}", book_reviews["Pride and Prejudice"]);

// 遍历所有内容。
for (book, review) in &book_reviews {
    println!("{}: \"{}\"", book, review);
}
Run

HashMap 还实现了 Entry API，它允许使用更复杂的方法来获取，设置，更新和删除键及其值:

use std::collections::HashMap;

// 通过类型推断，我们可以省略显式类型签名 (在本示例中为 `HashMap<&str, u8>`)。
let mut player_stats = HashMap::new();

fn random_stat_buff() -> u8 {
    // 实际上可以在这里返回一些随机值 - 现在让我们返回一些固定值
    42
}

// 仅在键不存在时才插入
player_stats.entry("health").or_insert(100);

// 仅当一个键不存在时，才使用提供新值的函数插入该键
player_stats.entry("defence").or_insert_with(random_stat_buff);

// 更新键，以防止键可能未被设置
let stat = player_stats.entry("attack").or_insert(100);
*stat += random_stat_buff();
Run

将 HashMap 与自定义键类型一起使用的最简单方法是派生 Eq 和 Hash。 我们还必须导出 PartialEq。

use std::collections::HashMap;

#[derive(Hash, Eq, PartialEq, Debug)]
struct Viking {
    name: String,
    country: String,
}

impl Viking {
    /// 创建一个新的 Viking。
    fn new(name: &str, country: &str) -> Viking {
        Viking { name: name.to_string(), country: country.to_string() }
    }
}

// 使用 HashMap 存储 Viking 的健康点。
let mut vikings = HashMap::new();

vikings.insert(Viking::new("Einar", "Norway"), 25);
vikings.insert(Viking::new("Olaf", "Denmark"), 24);
vikings.insert(Viking::new("Harald", "Iceland"), 12);

// 使用派生的实现来打印 Viking 的状态。
for (viking, health) in &vikings {
    println!("{:?} has {} hp", viking, health);
}
Run

具有固定元素列表的 HashMap 可以从数组中初始化:

use std::collections::HashMap;

let timber_resources: HashMap<&str, i32> = [("Norway", 100), ("Denmark", 50), ("Iceland", 10)]
    .iter().cloned().collect();
// 使用存储在 map 中的值
Run

Implementations

创建一个空的 HashMap。

哈希 map 最初创建时的容量为 0，因此只有在首次插入时才分配。

Examples

use std::collections::HashMap;
let mut map: HashMap<&str, i32> = HashMap::new();
Run

创建具有指定容量的空 HashMap。

哈希 map 将能够至少保留 capacity 个元素而无需重新分配。 如果 capacity 为 0，则不会分配哈希 map。

Examples

use std::collections::HashMap;
let mut map: HashMap<&str, i32> = HashMap::with_capacity(10);
Run

创建一个空的 HashMap，它将使用给定的哈希生成器来哈希键。

创建的 map 具有默认的初始容量。

警告: hash_builder 通常是随机生成的，旨在使 HashMaps 能够抵抗导致许多冲突和非常差的性能的攻击。 使用此函数手动设置它可能会导致 DoS 攻击 vector。

传递的 hash_builder 应该为 X0HashMap0Z 实现 BuildHasher trait 才有用，有关详细信息，请参见其文档。

Examples

use std::collections::HashMap;
use std::collections::hash_map::RandomState;

let s = RandomState::new();
let mut map = HashMap::with_hasher(s);
map.insert(1, 2);
Run

创建一个具有指定容量的空 HashMap，使用 hash_builder 对键进行散列。

哈希 map 将能够至少保留 capacity 个元素而无需重新分配。如果 capacity 为 0，则不会分配哈希 map。

警告: hash_builder 通常是随机生成的，旨在使 HashMaps 能够抵抗导致许多冲突和非常差的性能的攻击。 使用此函数手动设置它可能会导致 DoS 攻击 vector。

传递的 hash_builder 应该为 X0HashMap0Z 实现 BuildHasher trait 才有用，有关详细信息，请参见其文档。

Examples

use std::collections::HashMap;
use std::collections::hash_map::RandomState;

let s = RandomState::new();
let mut map = HashMap::with_capacity_and_hasher(10, s);
map.insert(1, 2);
Run

返回 map 无需重新分配即可容纳的元素数。

此数字是一个下限; HashMap<K, V> 可能可以容纳更多，但可以保证至少容纳这么多。

Examples

use std::collections::HashMap;
let map: HashMap<i32, i32> = HashMap::with_capacity(100);
assert!(map.capacity() >= 100);
Run

一个迭代器，以任意顺序访问所有键。 迭代器元素类型为 &'a K。

Examples

use std::collections::HashMap;

let mut map = HashMap::new();
map.insert("a", 1);
map.insert("b", 2);
map.insert("c", 3);

for key in map.keys() {
    println!("{}", key);
}
Run

一个以任意顺序访问所有值的迭代器。 迭代器元素类型为 &'a V。

Examples

use std::collections::HashMap;

let mut map = HashMap::new();
map.insert("a", 1);
map.insert("b", 2);
map.insert("c", 3);

for val in map.values() {
    println!("{}", val);
}
Run

一个迭代器，它以任意顺序可变地访问所有值。 迭代器元素类型为 &'a mut V。

Examples

use std::collections::HashMap;

let mut map = HashMap::new();

map.insert("a", 1);
map.insert("b", 2);
map.insert("c", 3);

for val in map.values_mut() {
    *val = *val + 10;
}

for val in map.values() {
    println!("{}", val);
}
Run

一个迭代器，以任意顺序访问所有键值对。 迭代器元素类型为 (&'a K, &'a V)。

Examples

use std::collections::HashMap;

let mut map = HashMap::new();
map.insert("a", 1);
map.insert("b", 2);
map.insert("c", 3);

for (key, val) in map.iter() {
    println!("key: {} val: {}", key, val);
}
Run

一个迭代器，以任意顺序访问所有键值对，并且对值进行可变引用。

迭代器元素类型为 (&'a K, &'a mut V)。

Examples

use std::collections::HashMap;

let mut map = HashMap::new();
map.insert("a", 1);
map.insert("b", 2);
map.insert("c", 3);

// 更新所有值
for (_, val) in map.iter_mut() {
    *val *= 2;
}

for (key, val) in &map {
    println!("key: {} val: {}", key, val);
}
Run

返回 map 中的元素数。

Examples

use std::collections::HashMap;

let mut a = HashMap::new();
assert_eq!(a.len(), 0);
a.insert(1, "a");
assert_eq!(a.len(), 1);
Run

如果 map 不包含任何元素，则返回 true。

Examples

use std::collections::HashMap;

let mut a = HashMap::new();
assert!(a.is_empty());
a.insert(1, "a");
assert!(!a.is_empty());
Run

清除 map，将所有键值对作为迭代器返回。 保留分配的内存以供重用。

Examples

use std::collections::HashMap;

let mut a = HashMap::new();
a.insert(1, "a");
a.insert(2, "b");

for (k, v) in a.drain().take(1) {
    assert!(k == 1 || k == 2);
    assert!(v == "a" || v == "b");
}

assert!(a.is_empty());
Run
🔬 This is a nightly-only experimental API. (hash_drain_filter #59618)

创建一个迭代器，该迭代器使用闭包确定是否应删除元素。

如果闭包返回 true，则将元素从 map 中移除并产生。 如果闭包返回 false 或 panics，则该元素保留在 map 中，并且不会产生。

请注意，无论选择保留还是删除 drain_filter，您都可以对过滤器闭包中的每个值进行可变的。

如果迭代器仅被部分使用或完全不使用，则其余所有元素仍将受到闭包的处理，如果返回 true，则将其删除并丢弃。

如果在闭包中出现 panic，或者在丢弃元素时发生 panic，或者 DrainFilter 值泄漏，将有多少个元素受到该闭包的影响，这是不确定的。

Examples

将 map 分为偶数和奇数键，重新使用原始的 map:

#![feature(hash_drain_filter)]
use std::collections::HashMap;

let mut map: HashMap<i32, i32> = (0..8).map(|x| (x, x)).collect();
let drained: HashMap<i32, i32> = map.drain_filter(|k, _v| k % 2 == 0).collect();

let mut evens = drained.keys().copied().collect::<Vec<_>>();
let mut odds = map.keys().copied().collect::<Vec<_>>();
evens.sort();
odds.sort();

assert_eq!(evens, vec![0, 2, 4, 6]);
assert_eq!(odds, vec![1, 3, 5, 7]);
Run

清除 map，删除所有键值对。 保留分配的内存以供重用。

Examples

use std::collections::HashMap;

let mut a = HashMap::new();
a.insert(1, "a");
a.clear();
assert!(a.is_empty());
Run

返回 map 的 BuildHasher 的引用。

Examples

use std::collections::HashMap;
use std::collections::hash_map::RandomState;

let hasher = RandomState::new();
let map: HashMap<i32, i32> = HashMap::with_hasher(hasher);
let hasher: &RandomState = map.hasher();
Run

保留至少 additional 个要插入 HashMap 中的更多元素的容量。 该集合可以保留更多空间，以避免频繁的重新分配。

Panics

如果新的分配大小溢出 usize，则为 Panics。

Examples

use std::collections::HashMap;
let mut map: HashMap<&str, i32> = HashMap::new();
map.reserve(10);
Run
🔬 This is a nightly-only experimental API. (try_reserve #48043)

new API

尝试为给 HashMap<K, V> 至少插入 additional 个元素保留容量。 该集合可以保留更多空间，以避免频繁的重新分配。

Errors

如果容量溢出，或者分配器报告失败，则返回错误。

Examples

#![feature(try_reserve)]
use std::collections::HashMap;

let mut map: HashMap<&str, isize> = HashMap::new();
map.try_reserve(10).expect("why is the test harness OOMing on 10 bytes?");
Run

尽可能缩小 map 的容量。 它会在保持内部规则的同时尽可能地丢弃，并可能根据调整大小策略留出一些空间。

Examples

use std::collections::HashMap;

let mut map: HashMap<i32, i32> = HashMap::with_capacity(100);
map.insert(1, 2);
map.insert(3, 4);
assert!(map.capacity() >= 100);
map.shrink_to_fit();
assert!(map.capacity() >= 2);
Run
🔬 This is a nightly-only experimental API. (shrink_to #56431)

new API

降低 map 的容量。 它将降低不低于提供的限制，同时保持内部规则，并可能根据调整大小策略留下一些空间。

如果当前容量小于下限，则为无操作。

Examples

#![feature(shrink_to)]
use std::collections::HashMap;

let mut map: HashMap<i32, i32> = HashMap::with_capacity(100);
map.insert(1, 2);
map.insert(3, 4);
assert!(map.capacity() >= 100);
map.shrink_to(10);
assert!(map.capacity() >= 10);
map.shrink_to(0);
assert!(map.capacity() >= 2);
Run

在 map 中获取给定键的对应项，以进行就地操作。

Examples

use std::collections::HashMap;

let mut letters = HashMap::new();

for ch in "a short treatise on fungi".chars() {
    let counter = letters.entry(ch).or_insert(0);
    *counter += 1;
}

assert_eq!(letters[&'s'], 2);
assert_eq!(letters[&'t'], 3);
assert_eq!(letters[&'u'], 1);
assert_eq!(letters.get(&'y'), None);
Run

返回与键对应的值的引用。

键可以是 map 键类型的任何借用形式，但是借用形式上的 [’Hash] 和 [Eq`] 必须与键的类型匹配。

Examples

use std::collections::HashMap;

let mut map = HashMap::new();
map.insert(1, "a");
assert_eq!(map.get(&1), Some(&"a"));
assert_eq!(map.get(&2), None);
Run

返回与提供的键相对应的键值对。

提供的键可以是 map 的键类型的任何借用形式，但是借用形式上的 Hash 和 Eq 必须与该键的类型匹配。

Examples

use std::collections::HashMap;

let mut map = HashMap::new();
map.insert(1, "a");
assert_eq!(map.get_key_value(&1), Some((&1, &"a")));
assert_eq!(map.get_key_value(&2), None);
Run

如果 map 包含指定键的值，则返回 true。

键可以是 map 键类型的任何借用形式，但是借用形式上的 [’Hash] 和 [Eq`] 必须与键的类型匹配。

Examples

use std::collections::HashMap;

let mut map = HashMap::new();
map.insert(1, "a");
assert_eq!(map.contains_key(&1), true);
assert_eq!(map.contains_key(&2), false);
Run

返回与键对应的值的可变引用。

键可以是 map 键类型的任何借用形式，但是借用形式上的 [’Hash] 和 [Eq`] 必须与键的类型匹配。

Examples

use std::collections::HashMap;

let mut map = HashMap::new();
map.insert(1, "a");
if let Some(x) = map.get_mut(&1) {
    *x = "b";
}
assert_eq!(map[&1], "b");
Run

将键值对插入 map。

如果 map 不存在此键，则返回 None。

如果 map 确实存在此键，则更新值，并返回旧值。 但是，键不会更新。对于不能相同的 == 类型来说，这一点很重要。

有关更多信息，请参见 module-level documentation。

Examples

use std::collections::HashMap;

let mut map = HashMap::new();
assert_eq!(map.insert(37, "a"), None);
assert_eq!(map.is_empty(), false);

map.insert(37, "b");
assert_eq!(map.insert(37, "c"), Some("b"));
assert_eq!(map[&37], "c");
Run
🔬 This is a nightly-only experimental API. (map_try_insert #82766)

尝试将键值对插入到 map 中，并向条目中的值返回变量引用。

如果 map 已经存在此键，则不进行任何更新，并返回包含占用项和值的错误。

Examples

基本用法:

#![feature(map_try_insert)]

use std::collections::HashMap;

let mut map = HashMap::new();
assert_eq!(map.try_insert(37, "a").unwrap(), &"a");

let err = map.try_insert(37, "b").unwrap_err();
assert_eq!(err.entry.key(), &37);
assert_eq!(err.entry.get(), &"a");
assert_eq!(err.value, "b");
Run

从 map 中删除一个键，如果该键以前在 map 中，则返回该键的值。

键可以是 map 键类型的任何借用形式，但是借用形式上的 [’Hash] 和 [Eq`] 必须与键的类型匹配。

Examples

use std::collections::HashMap;

let mut map = HashMap::new();
map.insert(1, "a");
assert_eq!(map.remove(&1), Some("a"));
assert_eq!(map.remove(&1), None);
Run

pub fn remove_entry<Q: ?Sized>(&mut self, k: &Q) -> Option<(K, V)> where
    K: Borrow<Q>,
    Q: Hash + Eq, 

1.27.0[src]

从 map 中删除一个键，如果该键以前在 map 中，则返回存储的键和值。

键可以是 map 键类型的任何借用形式，但是借用形式上的 [’Hash] 和 [Eq`] 必须与键的类型匹配。

Examples

use std::collections::HashMap;

let mut map = HashMap::new();
map.insert(1, "a");
assert_eq!(map.remove_entry(&1), Some((1, "a")));
assert_eq!(map.remove(&1), None);
Run

仅保留谓词指定的元素。

换句话说，删除所有对 (k, v)，以使 f(&k, &mut v) 返回 false。 元素以未排序 (和未指定) 的顺序访问。

Examples

use std::collections::HashMap;

let mut map: HashMap<i32, i32> = (0..8).map(|x| (x, x*10)).collect();
map.retain(|&k, _| k % 2 == 0);
assert_eq!(map.len(), 4);
Run

创建一个消费迭代器，以任意顺序访问所有键。 调用后不能使用 map。 迭代器元素类型为 K。

Examples

use std::collections::HashMap;

let mut map = HashMap::new();
map.insert("a", 1);
map.insert("b", 2);
map.insert("c", 3);

let vec: Vec<&str> = map.into_keys().collect();
Run

创建一个消费迭代器，以任意顺序访问所有值。 调用后不能使用 map。 迭代器元素类型为 V。

Examples

use std::collections::HashMap;

let mut map = HashMap::new();
map.insert("a", 1);
map.insert("b", 2);
map.insert("c", 3);

let vec: Vec<i32> = map.into_values().collect();
Run

pub fn raw_entry_mut(&mut self) -> RawEntryBuilderMut<'_, K, V, S>

[src]
🔬 This is a nightly-only experimental API. (hash_raw_entry #56167)

为 HashMap 创建原始条目构建器。

原始条目为搜索和操作 map 提供了最低级别的控制。必须使用哈希将其手动初始化，然后进行手动搜索。 此后，插入空条目仍然需要提供一个拥有的键。

原始条目对于以下特殊情况很有用:

  • 哈希记忆
  • 推迟创建拥有的键，直到知道它是必需的为止
  • 使用不适用于借用 trait 的搜索键
  • 在不使用 newtype 包装器的情况下使用自定义比较逻辑

因为原始条目提供了更多的灵活控制，所以将 HashMap 置于不一致状态要容易得多，这虽然具有内存安全性，但会导致 map 产生看似随机的结果。 如果可能，应首选更高级别且更简单的 API，例如 entry。

特别是，用于初始化原始条目的哈希必须仍然与最终存储在条目中的键的哈希保持一致。 这是因为 HashMap 的实现在调整大小时可能需要重新计算哈希，此时只有键可用。

原始条目为变量提供了可变的访问权限。 这不能用于修改键的比较或散列方式，因为映射不会重新评估键应该去的位置，这意味着如果它们的位置不反映它们的状态，它们可能会丢失。

例如，如果您更改一个键以使 map 现在包含比较相等的键，则搜索可能会开始不规律地进行，两个键彼此相互掩盖。 实现可以自由地假设不会发生这种情况 (在内存安全性的范围内)。

pub fn raw_entry(&self) -> RawEntryBuilder<'_, K, V, S>

[src]
🔬 This is a nightly-only experimental API. (hash_raw_entry #56167)

为 HashMap 创建一个原始的不可变条目构建器。

原始条目为搜索和操作 map 提供了最低级别的控制。 必须使用哈希将其手动初始化，然后进行手动搜索。

这对于

  • 哈希记忆
  • 使用不适用于借用 trait 的搜索键
  • 在不使用 newtype 包装器的情况下使用自定义比较逻辑

除非您处于这种情况下，否则应首选更高级别且更简单的 API，例如 get。

不可变的原始条目用途非常有限; 您可能需要 raw_entry_mut。

Trait Implementations

返回值的副本。 Read more

从 source 执行复制分配。 Read more

使用给定的格式化程序格式化该值。 Read more

创建一个空的 HashMap<K, V, S>，其哈希值为 Default。

用迭代器的内容扩展集合。 Read more

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

用一个元素扩展一个集合。

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

在集合中为给定数量的附加元素保留容量。 Read more

插入迭代器中的所有新键值，并用迭代器返回的新值替换现有键中的值。

用迭代器的内容扩展集合。 Read more

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

用一个元素扩展一个集合。

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

在集合中为给定数量的附加元素保留容量。 Read more

从迭代器创建一个值。 Read more

返回与提供的键对应的值的引用。

Panics

如果键不在 HashMap 中，则会 panic。

索引后返回的类型。

被迭代的元素的类型。

我们将其变成哪种迭代器?

从一个值创建一个迭代器。 Read more

被迭代的元素的类型。

我们将其变成哪种迭代器?

从一个值创建一个迭代器。 Read more

创建一个消耗迭代器，即一个将任意键值对以任意顺序移出 map 的迭代器。 调用后不能使用 map。

Examples

use std::collections::HashMap;

let mut map = HashMap::new();
map.insert("a", 1);
map.insert("b", 2);
map.insert("c", 3);

// .iter() 无法使用
let vec: Vec<(&str, i32)> = map.into_iter().collect();
Run

被迭代的元素的类型。

我们将其变成哪种迭代器?

此方法测试 self 和 other 值是否相等，并由 == 使用。 Read more

此方法测试 !=。

Auto Trait Implementations

Blanket Implementations

获取 self 的 TypeId。 Read more

从拥有的值中一成不变地借用。 Read more

从拥有的值中借用。 Read more

执行转换。

执行转换。

获得所有权后的结果类型。

通常通过克隆从借用数据中创建拥有的数据。 Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into #41263)

recently added

使用借来的数据来替换拥有的数据，通常是通过克隆。 Read more

发生转换错误时返回的类型。

执行转换。

发生转换错误时返回的类型。

执行转换。