Iterate over table

Overview

This guide provides instructions to iterate and retrieve data from a multi-index table.

Procedure

Complete the following steps to iterate, retrieve and print data from the datatable multi-index table.

1. Define The print( ) Action

Add a print action to the datatable multi-index table. The print action takes an account name as a parameter.

[[inery::action]] void print( name user );

Optionally, for ease of use add the action wrapper definition as well.

[[inery::action]] void print( name user );

+using print_action = action_wrapper<"print"_n, &multi_index_example::print>;

2. Implement The print( ) Action

Search for the user name in the multi-index table using the primary index. If found, print out the value of field datum. Otherwise raise an error with a custom message. In the contract definition add the following implementation for print action:

  [[inery::action]] void multi_index_example::print( name user ) {
    // searches for the row that corresponds to the user parameter
    auto itr = datatable.find(user.value);
    
    // asserts if the row was found for user parameter, if fails use the given message
    check( itr != datatable.end(), "user does not exist in table" );

    // prints the test_primary and datum fields stored for user parameter
    inery::print_f("Test Table : {%, %}\n", itr->test_primary, itr->datum);
}

3. Put It All Together

The full definition and implementation files for the contract should look like this:

multi_index_example.hpp

#include <inery/inery.hpp>
using namespace inery;

// multi-index example contract class
class [[inery::contract]] multi_index_example : public contract {
   public:
      using contract::contract;

      // contract class constructor
      multi_index_example( name receiver, name code, datastream<const char*> ds ) :
         // contract base class contructor
         contract(receiver, code, ds),
         // instantiate multi-index instance as data member (find it defined below)
         datatable(receiver, receiver.value)
         { }

      // the row structure of the multi-index table, that is, each row of the table
      // will contain an instance of this type of structure
      struct [[inery::table]] data_structure {
        // this data member stores a name for each row of the multi-index table
        name test_primary;
        // additional data stored in table row
        uint64_t datum;
        // mandatory definition for primary key getter
        uint64_t primary_key( ) const { return test_primary.value; }
      };

      // the multi-index type definition, for ease of use define a type alias `data_structure_t`, 
      // based on the multi_index template type, parametarized with a random name and 
      // the data_structure data structure
      typedef inery::multi_index<"datatable"_n, data_structure> data_structure_t;

      // the multi-index table instance declared as a data member of type data_structure_t
      data_structure_t datatable;

      [[inery::action]] void set( name user );
      [[inery::action]] void print( name user );

      using set_action = action_wrapper<"set"_n, &multi_index_example::set>;
      using print_action = action_wrapper<"print"_n, &multi_index_example::print>;
};

multi_index_example.cpp

#include <multi_index_example.hpp>

[[inery::action]] void multi_index_example::set( name user ) {
  // check if the user already exists
  auto itr = datatable.find(user.value);

  if ( itr == datatable.end() ) {
    // user is not found in table, use emplace to insert a new row data structure in table
    datatable.emplace( _self, [&]( auto& u ) {
      u.test_primary = user;
      u.secondary = "second"_n;
      u.datum = 0;
    });
  }
}

[[inery::action]] void multi_index_example::print( name user ) {
  // searches for the row that corresponds to the user parameter
  auto itr = datatable.find(user.value);
  
  // asserts if the row was found for user parameter, if fails use the given message
  check( itr != datatable.end(), "user does not exist in table" );

  // prints the test_primary and datum fields stored for user parameter
  inery::print_f("Test Table : {%, %}\n", itr->test_primary, itr->datum);
}

Summary

In conclusion, the above instructions show how to iterate and retrieve a multi-index table.