#[derive(Clone, Debug)]
pub enum Bound<'a, K: PrimaryKey<'a>> {
  Inclusive((K, PhantomData<&'a bool>)),
  Exclusive((K, PhantomData<&'a bool>)),
  InclusiveRaw(Vec<u8>),
  ExclusiveRaw(Vec<u8>),
}

为了更好地理解API，请查看以下示例

#[derive(Serialize, Deserialize, PartialEq, Debug, Clone)]
struct Data {
    pub name: String,
    pub age: i32,
}

const PEOPLE: Map<&str, Data> = Map::new("people");
const ALLOWANCE: Map<(&str, &str), u64> = Map::new("allow");

fn demo() -> StdResult<()> {
    let mut store = MockStorage::new();

    // save and load on two keys
    let data = Data { name: "John".to_string(), age: 32 };
    PEOPLE.save(&mut store, "john", &data)?;
    let data2 = Data { name: "Jim".to_string(), age: 44 };
    PEOPLE.save(&mut store, "jim", &data2)?;

    // iterate over them all
    let all: StdResult<Vec<_>> = PEOPLE
        .range(&store, None, None, Order::Ascending)
        .collect();
    assert_eq!(
        all?,
        vec![("jim".to_vec(), data2), ("john".to_vec(), data.clone())]
    );

    // or just show what is after jim
    let all: StdResult<Vec<_>> = PEOPLE
        .range(
            &store,
            Some(Bound::exclusive("jim")),
            None,
            Order::Ascending,
        )
        .collect();
    assert_eq!(all?, vec![("john".to_vec(), data)]);

    // save and load on three keys, one under different owner
    ALLOWANCE.save(&mut store, ("owner", "spender"), &1000)?;
    ALLOWANCE.save(&mut store, ("owner", "spender2"), &3000)?;
    ALLOWANCE.save(&mut store, ("owner2", "spender"), &5000)?;

    // get all under one key
    let all: StdResult<Vec<_>> = ALLOWANCE
        .prefix("owner")
        .range(&store, None, None, Order::Ascending)
        .collect();
    assert_eq!(
        all?,
        vec![("spender".to_vec(), 1000), ("spender2".to_vec(), 3000)]
    );

    // Or ranges between two items (even reverse)
    let all: StdResult<Vec<_>> = ALLOWANCE
        .prefix("owner")
        .range(
            &store,
            Some(Bound::exclusive("spender")),
            Some(Bound::inclusive("spender2")),
            Order::Descending,
        )
        .collect();
    assert_eq!(all?, vec![("spender2".to_vec(), 3000)]);

    Ok(())
}

注意：关于在MultiIndex上定义和使用类型安全的界限，请参阅下文中的类型安全的MultiIndex界限。

IndexedMap

让我们通过一个例子来查看IndexedMap的定义和使用，这个例子最初来自cw721-base合约。

定义

pub struct TokenIndexes<'a> {
  pub owner: MultiIndex<'a, Addr, TokenInfo, String>,
}

impl<'a> IndexList<TokenInfo> for TokenIndexes<'a> {
  fn get_indexes(&'_ self) -> Box<dyn Iterator<Item = &'_ dyn Index<TokenInfo>> + '_> {
    let v: Vec<&dyn Index<TokenInfo>> = vec![&self.owner];
    Box::new(v.into_iter())
  }
}

pub fn tokens<'a>() -> IndexedMap<'a, &'a str, TokenInfo, TokenIndexes<'a>> {
  let indexes = TokenIndexes {
    owner: MultiIndex::new(
      |d: &TokenInfo| d.owner.clone(),
      "tokens",
      "tokens__owner",
    ),
  };
  IndexedMap::new("tokens", indexes)
}

让我们逐一讨论

pub struct TokenIndexes<'a> {
  pub owner: MultiIndex<'a, Addr, TokenInfo, String>,
}

这些是索引定义。这里只有一个索引，称为owner。可能会有更多，作为TokenIndexes结构体的公共成员。我们看到owner索引是一个MultiIndex。多索引可以作为键值重复。主键在内部作为多索引键的最后一个元素使用，以区分重复的索引值。正如其名所示，这是一个按所有者对代币进行索引的索引。鉴于一个所有者可以有多个代币，我们需要一个MultiIndex来列出/遍历他拥有的所有代币。

TokenInfo数据最初将按token_id（这是一个字符串值）存储。您可以在创建代币的代码中看到这一点

    tokens().update(deps.storage, &msg.token_id, |old| match old {
        Some(_) => Err(ContractError::Claimed {}),
        None => Ok(token),
    })?;

（顺便提一下，这里使用update而不是save，以避免覆盖已存在的代币）。

由于token_id是一个字符串值，我们指定String作为MultiIndex定义的最后一个参数。这样，主键的反序列化将完成到正确的类型（一个拥有字符串）。

注意：在特定情况下，对于MultiIndex和类型安全界限的最新实现，最后一个类型参数的定义对于正确使用类型安全界限至关重要。请参阅下文中的类型安全的MultiIndex界限。

然后，此TokenInfo数据将通过代币所有者owner（这是一个Addr）进行索引。这样我们就可以列出所有者拥有的所有代币。这就是为什么owner索引键是Addr的原因。

这里另一个重要的事情是，键（及其组件，在复合键的情况下）必须实现PrimaryKey特质。您可以看到Addr实现了PrimaryKey

impl<'a> PrimaryKey<'a> for Addr {
  type Prefix = ();
  type SubPrefix = ();
  type Suffix = Self;
  type SuperSuffix = Self;

  fn key(&self) -> Vec<Key> {
    // this is simple, we don't add more prefixes
    vec![Key::Ref(self.as_bytes())]
  }
}

现在我们可以通过查看剩余的代码来了解它是如何工作的

impl<'a> IndexList<TokenInfo> for TokenIndexes<'a> {
    fn get_indexes(&'_ self) -> Box<dyn Iterator<Item = &'_ dyn Index<TokenInfo>> + '_> {
        let v: Vec<&dyn Index<TokenInfo>> = vec![&self.owner];
        Box::new(v.into_iter())
    }
}

这为TokenIndexes实现了IndexList特质。

注意：此代码几乎是模板化的，并且对于内部需要。不要尝试自定义此代码；只需返回所有索引的列表。实现此特质有两个目的（实际上是一个目的）：它允许通过get_indexes查询索引，并允许TokenIndexes被视为一个IndexList。这样，它就可以在IndexedMap构造函数下作为参数传递

pub fn tokens<'a>() -> IndexedMap<'a, &'a str, TokenInfo, TokenIndexes<'a>> {
    let indexes = TokenIndexes {
        owner: MultiIndex::new(
            |d: &TokenInfo| d.owner.clone(),
            "tokens",
            "tokens__owner",
        ),
    };
    IndexedMap::new("tokens", indexes)
}

在这里tokens()只是一个辅助函数，它简化了我们的IndexedMap构造。首先创建索引（es），然后创建并返回IndexedMap。

在创建索引的过程中，我们必须为每个索引提供一个索引函数

        owner: MultiIndex::new(|d: &TokenInfo| d.owner.clone(),

这是将原始映射的值取出并从中创建索引键的那个。当然，这要求索引键所需元素必须存在于值中。除了索引函数外，我们还必须提供pk的命名空间和新的索引的命名空间。

之后，我们只需创建并返回 IndexedMap

    IndexedMap::new("tokens", indexes)

当然，这里的pk命名空间必须与创建索引时使用的命名空间相匹配。此外，我们将我们的 TokenIndexes（作为 IndexList-类型参数）作为第二个参数传递。以这种方式连接底层 Map 的pk，与定义的索引。

因此，IndexedMap（以及其他 Indexed* 类型）只是 Map 的包装/扩展，提供了一些索引函数和命名空间来在原始 Map 数据上创建索引。它还实现了在值存储/更新/删除期间调用这些索引函数，这样您就可以忘记它，只需使用索引数据。

用法

使用示例，其中 owner 是作为参数传递的 String 值，而 start_after 和 limit 可选地定义了分页范围

注意这里使用了 prefix()，如上文所述的 Map 部分。

    let limit = limit.unwrap_or(DEFAULT_LIMIT).min(MAX_LIMIT) as usize;
    let start = start_after.map(Bound::exclusive);
    let owner_addr = deps.api.addr_validate(&owner)?;

    let res: Result<Vec<_>, _> = tokens()
        .idx
        .owner
        .prefix(owner_addr)
        .range(deps.storage, start, None, Order::Ascending)
        .take(limit)
        .collect();
    let tokens = res?;

现在 tokens 包含了给定 owner 的 (token_id, TokenInfo) 对。在 range_raw() 的情况下，pk值是 Vec<u8>，但将使用 range() 反序列化为正确的类型；前提是pk反序列化类型（在本例中是 String）已在 MultiIndex 定义中正确指定（见下文 索引键反序列化）。

另一个类似的示例，但只返回（原始）token_id，使用 keys_raw() 方法

    let pks: Vec<_> = tokens()
        .idx
        .owner
        .prefix(owner_addr)
        .keys_raw(
            deps.storage,
            start,
            None,
            Order::Ascending,
        )
        .take(limit)
        .collect();

现在 pks 包含了给定 owner 的 token_id 值（作为原始 Vec<u8>）。通过使用 keys，可以获取反序列化的键，如下一节所述。

索引键反序列化

对于 UniqueIndex 和 MultiIndex，需要指定主键（PK）类型，以便将主键反序列化到它。此 PK 类型指定对于 MultiIndex 类型安全的范围也很重要，因为主键是多索引键的一部分。参见下一节，多索引的类型安全范围。

注意：此规范仍然是一个手动（因此容易出错）的过程/设置，将来（如果可能）将自动化（https://github.com/CosmWasm/cw-plus/issues/531）。

多索引的类型安全范围

在MultiIndex的特定情况下，主键（PK）类型参数也定义了索引键（即与主键对应的部分）的（部分）边界类型。因此，为了正确使用多索引范围的类型安全边界，确保这个PK类型被正确定义是至关重要的，使其与主键类型或其（通常是拥有的）反序列化变体相匹配。

Deque

Deque的使用相当直接。从概念上讲，它类似于Rust std的存储后端版本的Deque，可以用作队列或栈。它允许你在两端推送和弹出元素，也可以读取第一个或最后一个元素而不修改deque。你还可以直接读取特定索引。

示例用法

#[derive(Serialize, Deserialize, PartialEq, Debug, Clone)]
struct Data {
    pub name: String,
    pub age: i32,
}

const DATA: Deque<Data> = Deque::new("data");

fn demo() -> StdResult<()> {
    let mut store = MockStorage::new();

    // read methods return a wrapped Option<T>, so None if the deque is empty
    let empty = DATA.front(&store)?;
    assert_eq!(None, empty);

    // some example entries
    let p1 = Data {
        name: "admin".to_string(),
        age: 1234,
    };
    let p2 = Data {
        name: "user".to_string(),
        age: 123,
    };

    // use it like a queue by pushing and popping at opposite ends
    DATA.push_back(&mut store, &p1)?;
    DATA.push_back(&mut store, &p2)?;

    let admin = DATA.pop_front(&mut store)?;
    assert_eq!(admin.as_ref(), Some(&p1));
    let user = DATA.pop_front(&mut store)?;
    assert_eq!(user.as_ref(), Some(&p2));

    // or push and pop at the same end to use it as a stack
    DATA.push_back(&mut store, &p1)?;
    DATA.push_back(&mut store, &p2)?;

    let user = DATA.pop_back(&mut store)?;
    assert_eq!(user.as_ref(), Some(&p2));
    let admin = DATA.pop_back(&mut store)?;
    assert_eq!(admin.as_ref(), Some(&p1));

    // you can also iterate over it
    DATA.push_front(&mut store, &p1)?;
    DATA.push_front(&mut store, &p2)?;

    let all: StdResult<Vec<_>> = DATA.iter(&store)?.collect();
    assert_eq!(all?, [p2, p1]);

    // or access an index directly
    assert_eq!(DATA.get(&store, 0)?, Some(p2));
    assert_eq!(DATA.get(&store, 1)?, Some(p1));
    assert_eq!(DATA.get(&store, 3)?, None);

    Ok(())
}