Clarity 智能合约开发语言｜理解并使用 Maps 映射

英文原文档： https://book.clarity-lang.org/ch04-03-maps.html

Maps 映射

数据映射也可以被称作哈希表。它是一种允许您将键映射到特定值的数据结构。与元组键不同，数据映射键不是硬编码的名称。它们被表示为特定的具体值。如果要将数据与其他数据相关联，则应使用映射。

使用 define-map 定义映射：

(define-map map-name key-type value-type)

key-type 和 value-type 都可以是任何有效的类型签名，因为它们的多功能性，也通常会使用元组

;; A map that creates a principal => uint relation.
(define-map balances principal uint)

;; Set the "balance" of the tx-sender to u500.
(map-set balances tx-sender u500)

;; Retrieve the balance.
(print (map-get? balances tx-sender))

让我们来看看我们如何使用映射来存储和读取不同订单 ID 的基本信息。我们将使用一个无符号整数作为键类型，使用一个元组作为值类型。这些虚构的订单将有一个主体用户和金额。

(define-map orders uint {maker: principal, amount: uint})

;; Set two orders.
(map-set orders u0 {maker: tx-sender, amount: u50})
(map-set orders u1 {maker: tx-sender, amount: u120})

;; retrieve order with ID u1.
(print (map-get? orders u1))

值得注意的是：映射是不可迭代的。换句话说，您不能遍历映射并检索所有的值。访问映射中的值的唯一方法是指定正确的键。

键可以像您希望的那样设置成简单或复杂：

(define-map highest-bids
    {listing-id: uint, asset: (optional principal)}
    {bid-id: uint}
)

(map-set highest-bids {listing-id: u5, asset: none} {bid-id: u20})

虽然元组使代码更具可读性，但请记住 Clarity 是解释性的语言。使用元组作为键会比使用原始类型产生更高的执行成本。如果你的元组键只有一个成员，可以考虑直接使用成员类型作为映射键类型。

设置和插入

map-set 函数将覆盖现有值，但如果指定的键已存在，则 map-insert 将执行失败。也可以使用 map-delete 删除输入。

(define-map scores principal uint)

;; Insert a value.
(map-insert scores tx-sender u100)

;; This second insert will fail because the key already exists.
(map-insert scores tx-sender u200)

;; The score for tx-sender will be u100.
(print (map-get? scores tx-sender))

;; Delete the entry for tx-sender.
(map-delete scores tx-sender)

;; Will return none because the entry got deleted.
(print (map-get? scores tx-sender))

从映射读取可能会失败

我们从前面的例子中看到的是 map-get?返回一个optional 类型。原因是如果提供的键不存在，从映射中读取会失败。当这种情况发生时，map-get ？返回一个 none 。这也意味着，如果您希望使用检索到的值，在大多数情况下您必须将其解包。

;; A map that creates a string-ascii => uint relation.
(define-map names (string-ascii 34) principal)

;; Point the name "Clarity" to the tx-sender.
(map-set names "Clarity" tx-sender)

;; Retrieve the principal related to the name "Clarity".
(print (map-get? names "Clarity"))

;; Retrieve the principal for a key that does not exist. It will return `none`.
(print (map-get? names "bogus"))

;; Unwrap a value:
(print (unwrap-panic (map-get? names "Clarity")))

你可以通过这遍章节了解更多关于unwrap 的功能。