x-i18n: generated_at: “2026-03-01T13:59:53Z” model: gemini-3-flash-preview provider: google-gemini-cli source_hash: 2588825afb8c1fa18a4ab8b4b5ba6c49976fbda23e25d304ab916576c41b63d8 source_path: ch08-03-hash-maps.md workflow: 16

在哈希映射中存储键和关联值 (Storing Keys with Associated Values in Hash Maps)

Storing Keys with Associated Values in Hash Maps

我们要介绍的最后一种常用集合是哈希映射 (hash map)。类型 HashMap<K, V> 使用一个“哈希函数 (hashing function)”来存储 K 类型的键与 V 类型的值的映射，该函数决定了它如何将这些键和值放入内存中。许多编程语言都支持这种数据结构，但它们通常使用不同的名称，例如“哈希 (hash)”、“映射 (map)”、“对象 (object)”、“哈希表 (hash table)”、“字典 (dictionary)”或“关联数组 (associative array)”，仅举几例。

The last of our common collections is the hash map. The type HashMap<K, V> stores a mapping of keys of type K to values of type V using a hashing function, which determines how it places these keys and values into memory. Many programming languages support this kind of data structure, but they often use a different name, such as hash, map, object, hash table, dictionary, or associative array, just to name a few.

当你不想像向量那样通过索引，而是想通过可以是任何类型的键来查找数据时，哈希映射非常有用。例如，在一个游戏中，你可以用哈希映射来跟踪每个队的得分，其中每个键是队名，值是每个队的得分。给定一个队名，你就可以检索到它的得分。

Hash maps are useful when you want to look up data not by using an index, as you can with vectors, but by using a key that can be of any type. For example, in a game, you could keep track of each team’s score in a hash map in which each key is a team’s name and the values are each team’s score. Given a team name, you can retrieve its score.

在本节中，我们将介绍哈希映射的基本 API，但在标准库为 HashMap<K, V> 定义的函数中还隐藏着更多的好东西。一如既往，请查看标准库文档以获取更多信息。

We’ll go over the basic API of hash maps in this section, but many more goodies are hiding in the functions defined on HashMap<K, V> by the standard library. As always, check the standard library documentation for more information.

创建新哈希映射 (Creating a New Hash Map)

Creating a New Hash Map

创建一个空哈希映射的一种方法是使用 new 及其 insert 方法来添加元素。在示例 8-20 中，我们要跟踪两个队的得分，队名分别是“Blue”和“Yellow”。Blue 队开始时得 10 分，Yellow 队开始时得 50 分。

One way to create an empty hash map is to use new and to add elements with insert. In Listing 8-20, we’re keeping track of the scores of two teams whose names are Blue and Yellow. The Blue team starts with 10 points, and the Yellow team starts with 50.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-20/src/main.rs:here}}
}

注意，我们需要首先从标准库的集合部分 use 这个 HashMap。在我们三种常用集合中，这一种是最不常用的，因此它没有包含在 prelude 中自动引入作用域的功能里。哈希映射得到的标准库支持也较少；例如，没有用于构造它们的内置宏。

Note that we need to first use the HashMap from the collections portion of the standard library. Of our three common collections, this one is the least often used, so it’s not included in the features brought into scope automatically in the prelude. Hash maps also have less support from the standard library; there’s no built-in macro to construct them, for example.

就像向量一样，哈希映射将其数据存储在堆上。这个 HashMap 的键类型为 String，值的类型为 i32。与向量一样，哈希映射是同质的：所有的键必须具有相同的类型，所有的值也必须具有相同的类型。

Just like vectors, hash maps store their data on the heap. This HashMap has keys of type String and values of type i32. Like vectors, hash maps are homogeneous: All of the keys must have the same type, and all of the values must have the same type.

访问哈希映射中的值 (Accessing Values in a Hash Map)

Accessing Values in a Hash Map

我们可以通过将键提供给 get 方法来从哈希映射中获取一个值，如示例 8-21 所示。

We can get a value out of the hash map by providing its key to the get method, as shown in Listing 8-21.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-21/src/main.rs:here}}
}

在这里，score 将获得与 Blue 队关联的值，结果将是 10。get 方法返回一个 Option<&V>；如果哈希映射中没有该键的值，get 将返回 None。此程序通过调用 copied 来处理 Option，以获得一个 Option<i32> 而不是 Option<&i32>，然后使用 unwrap_or，如果 scores 中没有该键的条目，则将 score 设置为零。

Here, score will have the value that’s associated with the Blue team, and the result will be 10. The get method returns an Option<&V>; if there’s no value for that key in the hash map, get will return None. This program handles the Option by calling copied to get an Option rather than an Option<&i32>, then unwrap_or to set score to zero if scores doesn’t have an entry for the key.

我们可以像遍历向量那样，使用 for 循环遍历哈希映射中的每个键值对：

We can iterate over each key-value pair in a hash map in a similar manner as we do with vectors, using a for loop:

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/no-listing-03-iterate-over-hashmap/src/main.rs:here}}
}

这段代码将以任意顺序打印每一对：

This code will print each pair in an arbitrary order:

Yellow: 50
Blue: 10

哈希映射中的所有权管理 (Managing Ownership in Hash Maps)

Managing Ownership in Hash Maps

对于像 i32 这样实现了 Copy 特征的类型，其值会被拷贝进哈希映射。对于像 String 这样的拥有所有权的值，其值将被移动，哈希映射将成为这些值的所有者，如示例 8-22 所示。

For types that implement the Copy trait, like i32, the values are copied into the hash map. For owned values like String, the values will be moved and the hash map will be the owner of those values, as demonstrated in Listing 8-22.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-22/src/main.rs:here}}
}

在通过调用 insert 将变量 field_name 和 field_value 移动到哈希映射中之后，我们将无法再使用它们。

We aren’t able to use the variables field_name and field_value after they’ve been moved into the hash map with the call to insert.

如果我们向哈希映射插入值的引用，那么这些值将不会被移动。引用所指向的值必须在哈希映射有效期间保持有效。我们将在第 10 章的“使用生命周期验证引用”部分详细讨论这些问题。

If we insert references to values into the hash map, the values won’t be moved into the hash map. The values that the references point to must be valid for at least as long as the hash map is valid. We’ll talk more about these issues in “Validating References with Lifetimes” in Chapter 10.

更新哈希映射 (Updating a Hash Map)

Updating a Hash Map

尽管键值对的数量是可以增长的，但每个唯一的键在同一时间只能关联一个值（但反之则不然：例如，Blue 队和 Yellow 队都可以在 scores 哈希映射中存储值 10）。

Although the number of key and value pairs is growable, each unique key can only have one value associated with it at a time (but not vice versa: For example, both the Blue team and the Yellow team could have the value 10 stored in the scores hash map).

当你想要更改哈希映射中的数据时，必须决定如何处理键已经分配了值的情况。你可以用新值替换旧值，完全不顾旧值。你可以保留旧值并忽略新值，只有在键“还没有”关联值时才添加新值。或者你可以将旧值和新值结合起来。让我们看看如何执行这其中的每一种操作！

When you want to change the data in a hash map, you have to decide how to handle the case when a key already has a value assigned. You could replace the old value with the new value, completely disregarding the old value. You could keep the old value and ignore the new value, only adding the new value if the key doesn’t already have a value. Or you could combine the old value and the new value. Let’s look at how to do each of these!

覆盖一个值 (Overwriting a Value)

Overwriting a Value

如果我们向哈希映射插入一个键和一个值，然后再次插入同一个键但带有一个不同的值，那么与该键关联的值将被替换。即使示例 8-23 中的代码调用了两次 insert，哈希映射也只会包含一个键值对，因为两次我们都是在为 Blue 队的键插入值。

If we insert a key and a value into a hash map and then insert that same key with a different value, the value associated with that key will be replaced. Even though the code in Listing 8-23 calls insert twice, the hash map will only contain one key-value pair because we’re inserting the value for the Blue team’s key both times.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-23/src/main.rs:here}}
}

这段代码将打印 {"Blue": 25}。原来的值 10 已经被覆盖了。

This code will print {"Blue": 25}. The original value of 10 has been overwritten.

仅在键不存在时添加键和值 (Adding a Key and Value Only If a Key Isn’t Present)

通常需要检查某个特定键是否已存在于哈希映射中并具有值，然后采取以下行动：如果该键确实存在，则现有值应保持不变；如果该键不存在，则将其连同其值一起插入。

It’s common to check whether a particular key already exists in the hash map with a value and then to take the following actions: If the key does exist in the hash map, the existing value should remain the way it is; if the key doesn’t exist, insert it and a value for it.

哈希映射为此提供了一个名为 entry 的特殊 API，它接收你想要检查的键作为参数。entry 方法的返回值是一个名为 Entry 的枚举，代表可能存在也可能不存在的值。假设我们要检查 Yellow 队的键是否有关联值。如果没有，我们想插入值 50；Blue 队也是如此。使用 entry API，代码如示例 8-24 所示。

Hash maps have a special API for this called entry that takes the key you want to check as a parameter. The return value of the entry method is an enum called Entry that represents a value that might or might not exist. Let’s say we want to check whether the key for the Yellow team has a value associated with it. If it doesn’t, we want to insert the value 50, and the same for the Blue team. Using the entry API, the code looks like Listing 8-24.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-24/src/main.rs:here}}
}

Entry 上的 or_insert 方法被定义为：如果对应的 Entry 键存在，则返回该键值的可变引用；如果不存在，则将参数作为该键的新值插入，并返回新值的可变引用。这种技术比我们自己编写逻辑要整洁得多，此外，它与借用检查器配合得更好。

The or_insert method on Entry is defined to return a mutable reference to the value for the corresponding Entry key if that key exists, and if not, it inserts the parameter as the new value for this key and returns a mutable reference to the new value. This technique is much cleaner than writing the logic ourselves and, in addition, plays more nicely with the borrow checker.

运行示例 8-24 中的代码将打印 {"Yellow": 50, "Blue": 10}。对 entry 的第一次调用将为 Yellow 队插入键及其值 50，因为 Yellow 队目前还没有值。第二次对 entry 的调用不会更改哈希映射，因为 Blue 队已经有了值 10。

Running the code in Listing 8-24 will print {"Yellow": 50, "Blue": 10}. The first call to entry will insert the key for the Yellow team with the value 50 because the Yellow team doesn’t have a value already. The second call to entry will not change the hash map, because the Blue team already has the value 10.

根据旧值更新值 (Updating a Value Based on the Old Value)

Updating a Value Based on the Old Value

哈希映射的另一个常见用例是查找一个键的值，然后根据其旧值对其进行更新。例如，示例 8-25 显示了统计某段文本中每个单词出现次数的代码。我们使用哈希映射，将单词作为键，并递增值来跟踪我们见过该单词的次数。如果是第一次见到某个单词，我们将首先插入值 0。

Another common use case for hash maps is to look up a key’s value and then update it based on the old value. For instance, Listing 8-25 shows code that counts how many times each word appears in some text. We use a hash map with the words as keys and increment the value to keep track of how many times we’ve seen that word. If it’s the first time we’ve seen a word, we’ll first insert the value 0.

#![allow(unused)]
fn main() {
{{#rustdoc_include ../listings/ch08-common-collections/listing-08-25/src/main.rs:here}}
}

这段代码将打印 {"world": 2, "hello": 1, "wonderful": 1}。你可能会看到相同的键值对以不同的顺序打印出来：回想“访问哈希映射中的值”部分，遍历哈希映射是以任意顺序发生的。

This code will print {"world": 2, "hello": 1, "wonderful": 1}. You might see the same key-value pairs printed in a different order: Recall from “Accessing Values in a Hash Map” that iterating over a hash map happens in an arbitrary order.

split_whitespace 方法会在 text 的值上返回一个由空白字符分隔的子切片迭代器。or_insert 方法返回指向指定键值的可变引用 (&mut V)。在这里，我们将该可变引用存储在 count 变量中，因此为了给该值赋值，必须首先使用星号 (*) 对 count 进行解引用。可变引用在 for 循环结束时超出作用域，因此所有这些更改都是安全的，并且符合借用规则。

The split_whitespace method returns an iterator over subslices, separated by whitespace, of the value in text. The or_insert method returns a mutable reference (&mut V) to the value for the specified key. Here, we store that mutable reference in the count variable, so in order to assign to that value, we must first dereference count using the asterisk (*). The mutable reference goes out of scope at the end of the for loop, so all of these changes are safe and allowed by the borrowing rules.

哈希函数 (Hashing Functions)

Hashing Functions

默认情况下，HashMap 使用一种名为 SipHash 的哈希函数，它可以抵御涉及哈希表的拒绝服务 (DoS) 攻击¹。这并不是目前最快的哈希算法，但其性能下降所换取的更好的安全性是值得的。如果你通过分析代码发现默认的哈希函数对你的用途来说太慢，你可以通过指定一个不同的 hasher 来切换到另一个函数。Hasher 是实现 BuildHasher 特征的类型。我们将在第 10 章讨论特征以及如何实现它们。你不必非得从头开始实现自己的 hasher；crates.io 上有其他 Rust 用户分享的库，提供了实现许多常见哈希算法的 hasher。

By default, HashMap uses a hashing function called SipHash that can provide resistance to denial-of-service (DoS) attacks involving hash tables¹. This is not the fastest hashing algorithm available, but the trade-off for better security that comes with the drop in performance is worth it. If you profile your code and find that the default hash function is too slow for your purposes, you can switch to another function by specifying a different hasher. A hasher is a type that implements the BuildHasher trait. We’ll talk about traits and how to implement them in Chapter 10. You don’t necessarily have to implement your own hasher from scratch; crates.io has libraries shared by other Rust users that provide hashers implementing many common hashing algorithms.

总结 (Summary)

Summary

向量、字符串和哈希映射提供了程序中存储、访问和修改数据所需的各种功能。这里有一些你现在应该具备能力解决的练习：

Vectors, strings, and hash maps will provide a large amount of functionality necessary in programs when you need to store, access, and modify data. Here are some exercises you should now be equipped to solve:

1. 给定一个整数列表，使用向量并返回列表的中位数（排序后位于中间位置的值）和众数（出现次数最多的值；哈希映射在这里会很有用）。
2. 将字符串转换为 Pig Latin。每个单词的第一个辅音字母被移到单词末尾，并添加 ay，所以 first 变成 irst-fay。以元音字母开头的单词则在末尾添加 hay（apple 变成 apple-hay）。请记住关于 UTF-8 编码的细节！
3. 使用哈希映射和向量，创建一个文本界面，允许用户将员工姓名添加到公司的部门中；例如，“Add Sally to Engineering” 或 “Add Amir to Sales”。然后，让用户检索部门中所有人员的列表，或按部门排序的公司中所有人员的列表，按字母顺序排列。

标准库 API 文档描述了向量、字符串和哈希映射所拥有的方法，这些方法对这些练习很有帮助！

The standard library API documentation describes methods that vectors, strings, and hash maps have that will be helpful for these exercises!

我们正在进入更复杂的程序，在这些程序中操作可能会失败，所以现在是讨论错误处理的最佳时机。我们接下来就讨论它！

We’re getting into more complex programs in which operations can fail, so it’s a perfect time to discuss error handling. We’ll do that next!

1. https://zh.wikipedia.org/wiki/SipHash ↩ ↩2