住房和城乡建设部网站建造师网站链接分析工具

映射类型

映射类型使用语法 mapping(KeyType KeyName? => ValueType ValueName?)，映射类型的变量声明使用语法 mapping(KeyType KeyName? => ValueType ValueName?) VariableName。

KeyType 可以是任何内置值类型、bytes、string 或任何合约类型或枚举类型。其他用户定义的复杂类型，如映射、结构体或数组类型是不允许的。

ValueType 可以是任何类型，包括映射、数组和结构体。

KeyName 和 ValueName 是可选的（因此 mapping(KeyType => ValueType) 也是有效的），它们可以是任何有效的标识符，但不能是类型。

你可以将映射看作哈希表，它在内部初始化，每个可能的键都会映射到一个值，该值的字节表示是全零，即类型的默认值。相似之处仅限于此，键数据不会存储在映射中，只有它的 keccak256 哈希值用于查找值。

由于这个原因，映射没有长度或键值是否已设置的概念，因此无法在没有额外信息的情况下删除映射。

映射只能有存储数据位置，因此只能作为状态变量、作为函数中的存储引用类型，或者作为库函数的参数。它们不能作为合约函数的公共参数或返回参数。这些限制也适用于包含映射的数组和结构体。

你可以将映射类型的状态变量标记为公共的，Solidity 会为你自动创建一个 getter。KeyType 变为 getter 的一个参数，并使用 KeyName（如果指定的话）。如果 ValueType 是值类型或结构体，getter 返回与该类型匹配的 ValueType（如果指定了 ValueName）。如果 ValueType 是数组或映射，则 getter 会有一个参数对应每个 KeyType，并递归处理。

在下面的示例中，MappingExample 合约定义了一个公共的 balances 映射，键类型为 address，值类型为 uint，将以太坊地址映射到无符号整数值。由于 uint 是值类型，getter 返回一个与该类型匹配的值，在 MappingUser 合约中，你可以看到它返回指定地址的值。

// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.0 <0.9.0;// 定义一个包含地址和余额的映射的合约
contract MappingExample {// 声明一个公共的映射，address => uint，记录每个地址的余额mapping(address => uint) public balances;// 更新函数：允许发送者更新他们的余额function update(uint newBalance) public {balances[msg.sender] = newBalance;  // 将调用者的余额更新为 newBalance}
}// 定义一个合约用于与 MappingExample 合约进行交互
contract MappingUser {// 一个函数，用来调用 MappingExample 合约的 update 方法，并返回当前合约地址的余额function f() public returns (uint) {// 创建 MappingExample 合约的实例MappingExample m = new MappingExample();// 调用 update 函数，将余额设置为 100m.update(100);// 返回当前合约地址的余额return m.balances(address(this));  // 返回 MappingExample 合约中当前合约地址的余额}
}

下面的示例是一个简化版的 ERC20 代币。_allowances 是一个映射类型，嵌套在另一个映射类型内部。我们为映射提供了可选的 KeyName 和 ValueName。这不会影响合约的功能或字节码，它仅仅是在 ABI 中为映射的 getter 输入和输出设置了名称字段。

// SPDX-License-Identifier: GPL-3.0
pragma solidity ^0.8.18;// 定义一个包含映射的智能合约
contract MappingExampleWithNames {// 定义一个 public 映射，映射地址（address）到余额（uint）。映射的键为 `user`，值为 `balance`。// 这个映射会自动生成一个 getter 函数，可以根据地址（address）查询对应的余额。mapping(address user => uint balance) public balances;// 更新余额的函数，接受一个 `newBalance` 参数。// 这个函数会将调用者（msg.sender）的余额更新为 `newBalance`。function update(uint newBalance) public {// 使用调用者的地址（msg.sender）作为键，更新其对应的余额值。balances[msg.sender] = newBalance;}
}

在下面的示例中，_allowances 映射用于记录某人被授权从你的账户中提取的金额：

// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.22 <0.9.0;contract MappingExample {// 定义一个私有映射 `_balances`，将每个地址映射到一个无符号整数（余额）。mapping(address => uint256) private _balances;// 定义一个私有映射 `_allowances`，它是一个二层映射，记录每个地址（owner）允许另一个地址（spender）提取的金额。mapping(address => mapping(address => uint256)) private _allowances;// 定义事件，当转账发生时触发。event Transfer(address indexed from, address indexed to, uint256 value);// 定义事件，当批准时触发，表明某个地址被授权从另一个地址提取一定金额。event Approval(address indexed owner, address indexed spender, uint256 value);// 查询某个地址被授权的提取金额function allowance(address owner, address spender) public view returns (uint256) {return _allowances[owner][spender];}// 从一个账户向另一个账户转账，同时检查授权金额是否足够function transferFrom(address sender, address recipient, uint256 amount) public returns (bool) {// 确保 sender 允许 msg.sender（调用者）提取足够的金额require(_allowances[sender][msg.sender] >= amount, "ERC20: Allowance not high enough.");// 减少授权金额_allowances[sender][msg.sender] -= amount;// 执行转账_transfer(sender, recipient, amount);return true;}// 批准另一个地址（spender）从调用者的账户中提取指定金额（amount）function approve(address spender, uint256 amount) public returns (bool) {// 确保 spender 地址不是零地址require(spender != address(0), "ERC20: approve to the zero address");// 设置授权金额_allowances[msg.sender][spender] = amount;// 触发批准事件emit Approval(msg.sender, spender, amount);return true;}// 内部转账函数，用于更新账户余额，并触发转账事件function _transfer(address sender, address recipient, uint256 amount) internal {// 确保 sender 和 recipient 不是零地址require(sender != address(0), "ERC20: transfer from the zero address");require(recipient != address(0), "ERC20: transfer to the zero address");// 确保 sender 有足够的余额require(_balances[sender] >= amount, "ERC20: Not enough funds.");// 执行转账：从 sender 减去金额，给 recipient 增加金额_balances[sender] -= amount;_balances[recipient] += amount;// 触发转账事件emit Transfer(sender, recipient, amount);}
}

可迭代映射

你不能直接迭代映射，即不能枚举它们的键。不过，你可以在其基础上实现一个数据结构并对其进行迭代。例如，下面的代码实现了一个 IterableMapping 库，User 合约将数据添加到该库中，并且 sum 函数会迭代这个数据结构以求和所有值。

// SPDX-License-Identifier: GPL-3.0
pragma solidity ^0.8.8;// 定义 IndexValue 结构体，用于存储每个键对应的索引和数值
struct IndexValue { uint keyIndex; // 键的索引位置uint value;    // 键对应的值
}// 定义 KeyFlag 结构体，用于标记键是否被删除
struct KeyFlag { uint key;      // 键的值bool deleted;  // 是否已删除标志
}// 定义 itmap 结构体，包含了一个映射和一个存储键的数组，以及当前大小
struct itmap {mapping(uint => IndexValue) data; // 存储键值对的映射KeyFlag[] keys;                   // 存储键的数组uint size;                         // 数据大小
}// 定义一个类型 Iterator，实质上是 uint 类型，用于遍历
type Iterator is uint;// 定义 IterableMapping 库，提供操作 itmap 类型数据的函数
library IterableMapping {// 插入数据到 itmap 中，如果已存在则更新数据function insert(itmap storage self, uint key, uint value) internal returns (bool replaced) {uint keyIndex = self.data[key].keyIndex; // 获取当前键的索引self.data[key].value = value;            // 更新该键对应的值if (keyIndex > 0) {return true; // 如果键已经存在，返回 true，表示数据已替换} else {// 如果键不存在，分配一个新的索引keyIndex = self.keys.length;self.keys.push(); // 在数组末尾添加一个新元素self.data[key].keyIndex = keyIndex + 1; // 设置新键的索引self.keys[keyIndex].key = key; // 将键添加到键数组中self.size++; // 增加数据大小return false; // 返回 false，表示插入了新的键值对}}// 从 itmap 中删除指定的键function remove(itmap storage self, uint key) internal returns (bool success) {uint keyIndex = self.data[key].keyIndex; // 获取该键的索引if (keyIndex == 0) {return false; // 如果键不存在，返回 false}delete self.data[key]; // 删除数据映射中的键值对self.keys[keyIndex - 1].deleted = true; // 将对应的 KeyFlag 标记为已删除self.size--; // 减小数据大小return true; // 返回 true，表示删除成功}// 检查 itmap 中是否包含指定的键function contains(itmap storage self, uint key) internal view returns (bool) {return self.data[key].keyIndex > 0; // 如果该键存在，返回 true}// 初始化遍历，返回一个迭代器function iterateStart(itmap storage self) internal view returns (Iterator) {return iteratorSkipDeleted(self, 0); // 跳过已删除的项，返回起始迭代器}// 检查当前迭代器是否有效function iterateValid(itmap storage self, Iterator iterator) internal view returns (bool) {return Iterator.unwrap(iterator) < self.keys.length; // 如果迭代器位置小于键数组长度，则有效}// 获取下一个迭代器，跳过已删除的项function iterateNext(itmap storage self, Iterator iterator) internal view returns (Iterator) {return iteratorSkipDeleted(self, Iterator.unwrap(iterator) + 1); // 跳到下一个有效项}// 获取当前迭代器对应的键和值function iterateGet(itmap storage self, Iterator iterator) internal view returns (uint key, uint value) {uint keyIndex = Iterator.unwrap(iterator); // 获取迭代器的索引key = self.keys[keyIndex].key;             // 获取键value = self.data[key].value;              // 获取值}// 跳过已删除的项，返回有效的迭代器位置function iteratorSkipDeleted(itmap storage self, uint keyIndex) private view returns (Iterator) {while (keyIndex < self.keys.length && self.keys[keyIndex].deleted) // 如果该项被标记为删除，则跳过keyIndex++;return Iterator.wrap(keyIndex); // 返回跳过已删除项后的迭代器}
}// User 合约使用 IterableMapping 库进行数据操作
contract User {itmap data; // 声明一个 itmap 类型的变量来保存数据// 使用 IterableMapping 库来操作 itmap 类型的数据using IterableMapping for itmap;// 插入数据到 itmap 中function insert(uint k, uint v) public returns (uint size) {// 调用 IterableMapping 库的 insert 函数插入数据data.insert(k, v);// 返回当前数据的大小return data.size;}// 计算所有存储数据的总和function sum() public view returns (uint s) {// 遍历 itmap 中的所有数据并计算总和for (Iterator i = data.iterateStart(); // 初始化迭代器data.iterateValid(i); // 检查迭代器是否有效i = data.iterateNext(i) // 获取下一个有效项) {(, uint value) = data.iterateGet(i); // 获取当前项的值s += value; // 将当前值累加到总和}}
}