EOS智能合约-多索引表篇

EOS-多索引表

---

• 简介

  EOSIO Multi-Index API为EOSIO数据库提供C ++接口。源码文件路径：eos/contracts/eosiolib/multi_index.hpp。其内部使用的是 C 的 Ddatabase_api 来操作数据库，文件路径：eos/contracts/eosiolib/wasm_interface.cpp。表对象的创建和修改都需要花费RAM，删除则会返回RAM到账户中。

• 命名规则

  结构名称	解释说明
  合约帐号名称	只能包含字符.abcdefghijklmnopqrstuvwxyz12345。a-z（小写）1-5和.（之间）必须是12个字符
  表名	最多只能包含12个字母字符
  结构	最多只能包含12个字母字符
  代币符号	必须是A和Z之间的大写字母字符必须是7个字符或更少

• 使用教程

  定义存储结构

  创建一个 EOSIO Multi-Index 表必需要一个uint64_t 主键。为了使表能够检索主键，存储在表中的对象需要具有名为 primary_key() 的 const 成员函数，该函数返回 uint64_t 。EOSIO Multi-Index表还支持最多16个二级索引.索引支持的格式如下：

  • uint64_t
  • uint128_t
  • uint256_t
  • double
  • long double

  1.创建表

  typedef eosio::multi_index table_name(code,scope);

  参数	参数说明
  TableName	表的名称
  T	表中存储的数据类型
  Indices	表的二级索引，此处支持最多16个索引
  code	拥有表的帐户
  scope	数据所属的账户
  table_name	存在在内存中的表名称

  scope 负责新对象的存储使用，如果必须创建表（和二级索引表），则 scope 支付表创建的 RAM 开销。

  2.表的操作

  • 按二级索引排序

    auto expidx = orders.get_index();
    
    print("Items sorted by expiration:\n");
    
    for( const auto& item : expidx ) {
      print(" ID=", item.id, ", expiration=", item.expiration, ",                 owner=", name{item.owner}, "\n");
    }
    

  • 添加多索引表(emplace)

    添加一个新的对象到表中

      orders.emplace( payer, [&]( auto& o ) {
        o.id = 1;
        o.expiration = 300;
        o.owner = N(dan);
      });
    

    参数	说明
    payer	付款账号消耗RAM
    constructor	用于对要在表中创建的对象进行就地初始化返回值

    返回值：新创建的对象的主键迭代器

  • 更新多索引表(modify)

    在Multi-Index表中创建一个新对象，该对象具有唯一的主键（在对象中指定）。该对象被序列化并写入表中。如果该表不存在，则创建该表。付款人负责新对象的存储使用，如果必须创建表（和二级索引表），则为表创建的开销。更新辅助索引以引用新添加的对象。如果辅助索引表不存在，则创建它们。更新多索引表(modify)在表中修改一个已经存在的对象

    print("Modifying expiration of order with ID=2 to 400.\n");
    
    orders.modify( order2, payer, [&]( auto& o ) {
        o.expiration = 400;
    });
    

    参数	说明
    order2	指向要更新的对象的迭代器
    payer	更新行的存储使用情况的付款人的帐户名称
    updater	更新目标对象的lambda 函数

    已修改的对象已序列化，然后替换表中的现有对象。
    付款人需要为更新对象的存储使用付费。
    如果付款人与现有付款人相同，则付款人仅支付现有和更新对象之间的使用差异（如果此差异为负，则退款）。
    如果付款人与现有付款人不同，则现有付款人将退还现有对象的存储使用情况。

    无返回值

  • erase(删)

    使用主键删除一个表中已经存在的对象

    addresses.erase(itr);

    参数	说明
    itr	指向要删除的对象的迭代器

    该对象将从表中删除，并回收所有关联的存储。
    对于对象的存储使用的现有支付者，删除的对象的表和二级索引使用，以及如果移除表和索 引，相关的开销将退还。在删除所有行后，表将自动删除。

    返回: 返回指向删除对象后面的对象的指针。

  • find(查)

    在表中根据主键查找已经存在的对象

      auto itr = addresses.find(N(dan));
    

    参数	说明
    primary	对象的主键值

    返回值：返回一个查询到的对象的迭代器；
    如果没有查询到指定对象，返回一个end迭代器。