Class List > eosio :: multi_index

Classes

Type Name
struct const_iterator
struct index
struct intc
struct multi_index::index
struct item
struct item_ptr

Public Types

Type Name
typedef std::reverse_iterator< const_iterator > const_reverse_iterator
struct multi_index::const_iterator

Public Functions

Type Name
multi_index (name code, uint64_t scope)
load_object_by_primary_iterator
name get_code () const
Returns the code member property.
uint64_t get_scope () const
Returns the scope member property.
const_iterator cbegin () const
Returns an iterator pointing to the object_type with the lowest primary key value in the Multi-Index table.
const_iterator begin () const
Returns an iterator pointing to the object_type with the lowest primary key value in the Multi-Index table.
const_iterator cend () const
Returns an iterator pointing to the object_type with the highest primary key value in the Multi-Index table.
const_iterator end () const
Returns an iterator pointing to the object_type with the highest primary key value in the Multi-Index table.
const_reverse_iterator crbegin () const
Returns a reverse iterator pointing to the object_type with the highest primary key value in the Multi-Index table.
const_reverse_iterator rbegin () const
Returns a reverse iterator pointing to the object_type with the highest primary key value in the Multi-Index table.
const_reverse_iterator crend () const
Returns an iterator pointing to the object_type with the lowest primary key value in the Multi-Index table.
const_reverse_iterator rend () const
Returns an iterator pointing to the object_type with the lowest primary key value in the Multi-Index table.
const_iterator lower_bound (uint64_t primary) const
Searches for the object_type with the lowest primary key that is greater than or equal to a given primary key.
const_iterator upper_bound (uint64_t primary) const
Searches for the object_type with the highest primary key that is less than or equal to a given primary key.
uint64_t available_primary_key () const
Returns an available primary key.
auto get_index ()
Returns an appropriately typed Secondary Index.
auto get_index () const
Returns an appropriately typed Secondary Index.
const_iterator iterator_to (const T & obj) const
Returns an iterator to the given object in a Multi-Index table.
const_iterator emplace (name payer, Lambda && constructor)
Adds a new object (i.e., row) to the table.
void modify (const_iterator itr, name payer, Lambda && updater)
Modifies an existing object in a table.
void modify (const T & obj, name payer, Lambda && updater)
Modifies an existing object in a table.
const T & get (uint64_t primary, const char * error_msg = "unable to find key") const
Retrieves an existing object from a table using its primary key.
const_iterator find (uint64_t primary) const
Search for an existing object in a table using its primary key.
const_iterator require_find (uint64_t primary, const char * error_msg = "unable to find key") const
Search for an existing object in a table using its primary key.
const_iterator erase (const_iterator itr)
Remove an existing object from a table using its primary key.
void erase (const T & obj)
Remove an existing object from a table using its primary key.

Public Types Documentation

typedef const_reverse_iterator

typedef std::reverse_iterator<const_iterator> eosio::multi_index< TableName, T, Indices >::const_reverse_iterator;

struct multi_index::const_iterator

Public Functions Documentation

function multi_index

eosio::multi_index< TableName, T, Indices >::multi_index(
    name code,
    uint64_t scope
)

load_object_by_primary_iterator

Constructs an instance of a Multi-Index table. Constructs an instance of a Multi-Index table.

Parameters:

  • code - Account that owns table
  • scope - Scope identifier within the code hierarchy

Precondition:

code and scope member properties are initialized

Post

each secondary index table initialized

Post

Secondary indices are updated to refer to the newly added object. If the secondary index tables do not exist, they are created.

Post

The payer is charged for the storage usage of the new object and, if the table (and secondary index tables) must be created, for the overhead of the table creation.

Notes The template has template parameters <, where:

  • TableName is the name of the table, maximum 12 characters long, characters in the name from the set of lowercase letters, digits 1 to 5, and the "." (period) character and is converted to a eosio::raw - which wraps uint64_t;
  • T is the object type (i.e., row definition);
  • Indices is a list of up to 16 secondary indices.
  • Each must be a default constructable class or struct
  • Each must have a function call operator that takes a const reference to the table object type and returns either a secondary key type or a reference to a secondary key type
  • It is recommended to use the eosio::const_mem_fun template, which is a type alias to the boost::multi_index::const_mem_fun. See the documentation for the Boost const_mem_fun key extractor for more details.

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name self):contract(self) {}
    typedef eosio::multi_index< "address"_n, address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value); // code, scope
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function get_code

name eosio::multi_index< TableName, T, Indices >::get_code() const

Returns the code member property.

Returns the code member property.

Returns:

Account name of the Code that owns the Primary Table.

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name self):contract(self) {}
    typedef eosio::multi_index< "address"_n, address > address_index;
    void myaction() {
      address_index addresses("dan"_n, "dan"_n); // code, scope
      eosio_assert(addresses.get_code() == "dan"_n, "Codes don't match.");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function get_scope

uint64_t eosio::multi_index< TableName, T, Indices >::get_scope() const

Returns the scope member property.

Returns the scope member property.

Returns:

Scope id of the Scope within the Code of the Current Receiver under which the desired Primary Table instance can be found.

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name self):contract(self) {}
    typedef eosio::multi_index< "address"_n, address > address_index;
    void myaction() {
      address_index addresses("dan"_n, "dan"_n); // code, scope
      eosio_assert(addresses.get_code() == "dan"_n, "Scopes don't match");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function cbegin

const_iterator eosio::multi_index< TableName, T, Indices >::cbegin() const

Returns an iterator pointing to the object_type with the lowest primary key value in the Multi-Index table.

Returns an iterator pointing to the object_type with the lowest primary key value in the Multi-Index table.

Returns:

An iterator pointing to the object_type with the lowest primary key value in the Multi-Index table.

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name self):contract(self) {}
    typedef eosio::multi_index< "address"_n, address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value);  // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(_self, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      auto itr = addresses.find("dan"_n);
      eosio_assert(itr == addresses.cbegin(), "Only address is not at front.");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function begin

const_iterator eosio::multi_index< TableName, T, Indices >::begin() const

Returns an iterator pointing to the object_type with the lowest primary key value in the Multi-Index table.

Returns an iterator pointing to the object_type with the lowest primary key value in the Multi-Index table.

Returns:

An iterator pointing to the object_type with the lowest primary key value in the Multi-Index table.

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name self):contract(self) {}
    typedef eosio::multi_index< "address"_n, address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value);  // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(_self, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      auto itr = addresses.find("dan"_n);
      eosio_assert(itr == addresses.begin(), "Only address is not at front.");
    }
}
EOSIO_ABI( addressbook, (myaction) )

function cend

const_iterator eosio::multi_index< TableName, T, Indices >::cend() const

Returns an iterator pointing to the object_type with the highest primary key value in the Multi-Index table.

Returns an iterator pointing to the object_type with the highest primary key value in the Multi-Index table.

Returns:

An iterator pointing to the object_type with the highest primary key value in the Multi-Index table.

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name self):contract(self) {}
    typedef eosio::multi_index< "address"_n, address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value); // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(_self, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      auto itr = addresses.find("dan"_n);
      eosio_assert(itr != addresses.cend(), "Address for account doesn't exist");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function end

const_iterator eosio::multi_index< TableName, T, Indices >::end() const

Returns an iterator pointing to the object_type with the highest primary key value in the Multi-Index table.

Returns an iterator pointing to the object_type with the highest primary key value in the Multi-Index table.

Returns:

An iterator pointing to the object_type with the highest primary key value in the Multi-Index table.

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name self):contract(self) {}
    typedef eosio::multi_index< "address"_n, address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value);  // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(_self, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      auto itr = addresses.find("dan"_n);
      eosio_assert(itr != addresses.end(), "Address for account doesn't exist");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function crbegin

const_reverse_iterator eosio::multi_index< TableName, T, Indices >::crbegin() const

Returns a reverse iterator pointing to the object_type with the highest primary key value in the Multi-Index table.

Returns a reverse iterator pointing to the object_type with the highest primary key value in the Multi-Index table.

Returns:

A reverse iterator pointing to the object_type with the highest primary key value in the Multi-Index table.

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value);  // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "brendan"_n;
        address.first_name = "Brendan";
        address.last_name = "Blumer";
        address.street = "1 EOS Way";
        address.city = "Hong Kong";
        address.state = "HK";
      });
      auto itr = addresses.crbegin();
      eosio_assert(itr->account_name == name("dan"), "Lock arf, Incorrect Last Record ");
      itr++;
      eosio_assert(itr->account_name == name("brendan"), "Lock arf, Incorrect Second Last Record");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function rbegin

const_reverse_iterator eosio::multi_index< TableName, T, Indices >::rbegin() const

Returns a reverse iterator pointing to the object_type with the highest primary key value in the Multi-Index table.

Returns a reverse iterator pointing to the object_type with the highest primary key value in the Multi-Index table.

Returns:

A reverse iterator pointing to the object_type with the highest primary key value in the Multi-Index table.

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value);  // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "brendan"_n;
        address.first_name = "Brendan";
        address.last_name = "Blumer";
        address.street = "1 EOS Way";
        address.city = "Hong Kong";
        address.state = "HK";
      });
      auto itr = addresses.rbegin();
      eosio_assert(itr->account_name == name("dan"), "Lock arf, Incorrect Last Record ");
      itr++;
      eosio_assert(itr->account_name == name("brendan"), "Lock arf, Incorrect Second Last Record");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function crend

const_reverse_iterator eosio::multi_index< TableName, T, Indices >::crend() const

Returns an iterator pointing to the object_type with the lowest primary key value in the Multi-Index table.

Returns an iterator pointing to the object_type with the lowest primary key value in the Multi-Index table.

Returns:

An iterator pointing to the object_type with the lowest primary key value in the Multi-Index table.

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value);  // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "brendan"_n;
        address.first_name = "Brendan";
        address.last_name = "Blumer";
        address.street = "1 EOS Way";
        address.city = "Hong Kong";
        address.state = "HK";
      });
      auto itr = addresses.crend();
      itr--;
      eosio_assert(itr->account_name == name("brendan"), "Lock arf, Incorrect First Record ");
      itr--;
      eosio_assert(itr->account_name == name("dan"), "Lock arf, Incorrect Second Record");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function rend

const_reverse_iterator eosio::multi_index< TableName, T, Indices >::rend() const

Returns an iterator pointing to the object_type with the lowest primary key value in the Multi-Index table.

Returns an iterator pointing to the object_type with the lowest primary key value in the Multi-Index table.

Returns:

An iterator pointing to the object_type with the lowest primary key value in the Multi-Index table.

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value); // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "brendan"_n;
        address.first_name = "Brendan";
        address.last_name = "Blumer";
        address.street = "1 EOS Way";
        address.city = "Hong Kong";
        address.state = "HK";
      });
      auto itr = addresses.rend();
      itr--;
      eosio_assert(itr->account_name == name("brendan"), "Lock arf, Incorrect First Record ");
      itr--;
      eosio_assert(itr->account_name == name("dan"), "Lock arf, Incorrect Second Record");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function lower_bound

const_iterator eosio::multi_index< TableName, T, Indices >::lower_bound(
    uint64_t primary
) const

Searches for the object_type with the lowest primary key that is greater than or equal to a given primary key.

Searches for the object_type with the lowest primary key that is greater than or equal to a given primary key.

Parameters:

  • primary - Primary key that establishes the target value for the lower bound search.

Returns:

An iterator pointing to the object_type that has the lowest primary key that is greater than or equal to primary. If an object could not be found, it will return the end iterator. If the table does not exist** it will return -1.

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint32_t zip = 0;
     uint64_t primary_key() const { return account_name; }
     uint64_t by_zip() const { return zip; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address, indexed_by< name("zip"), const_mem_fun<address, uint64_t, &address::by_zip> > address_index;
    void myaction() {
      address_index addresses(_self, _self.value);  // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
        address.zip = 93446;
      });
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "brendan"_n;
        address.first_name = "Brendan";
        address.last_name = "Blumer";
        address.street = "1 EOS Way";
        address.city = "Hong Kong";
        address.state = "HK";
        address.zip = 93445;
      });
      uint32_t zipnumb = 93445;
      auto zip_index = addresses.get_index<name("zip")>();
      auto itr = zip_index.lower_bound(zipnumb);
      eosio_assert(itr->account_name == name("brendan"), "Lock arf, Incorrect First Lower Bound Record ");
      itr++;
      eosio_assert(itr->account_name == name("dan"), "Lock arf, Incorrect Second Lower Bound Record");
      itr++;
      eosio_assert(itr == zip_index.end(), "Lock arf, Incorrect End of Iterator");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function upper_bound

const_iterator eosio::multi_index< TableName, T, Indices >::upper_bound(
    uint64_t primary
) const

Searches for the object_type with the highest primary key that is less than or equal to a given primary key.

Searches for the object_type with the highest primary key that is less than or equal to a given primary key.

Parameters:

  • primary - Primary key that establishes the target value for the upper bound search

Returns:

An iterator pointing to the object_type that has the highest primary key that is less than or equal to primary. If an object could not be found, it will return the end iterator. If the table does not exist** it will return -1.

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint32_t zip = 0;
     uint64_t liked = 0;
     uint64_t primary_key() const { return account_name; }
     uint64_t by_zip() const { return zip; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address, indexed_by< name("zip"), const_mem_fun<address, uint64_t, &address::by_zip> > address_index;
    void myaction() {
      address_index addresses(_self, _self.value);  // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
        address.zip = 93446;
      });
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "brendan"_n;
        address.first_name = "Brendan";
        address.last_name = "Blumer";
        address.street = "1 EOS Way";
        address.city = "Hong Kong";
        address.state = "HK";
        address.zip = 93445;
      });
      uint32_t zipnumb = 93445;
      auto zip_index = addresses.get_index<name("zip")>();
      auto itr = zip_index.upper_bound(zipnumb);
      eosio_assert(itr->account_name == name("dan"), "Lock arf, Incorrect First Upper Bound Record ");
      itr++;
      eosio_assert(itr == zip_index.end(), "Lock arf, Incorrect End of Iterator");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function available_primary_key

uint64_t eosio::multi_index< TableName, T, Indices >::available_primary_key() const

Returns an available primary key.

Returns an available primary key.

Returns:

An available (unused) primary key value.

Notes: Intended to be used in tables in which the primary keys of the table are strictly intended to be auto-incrementing, and thus will never be set to custom values by the contract. Violating this expectation could result in the table appearing to be full due to inability to allocate an available primary key. Ideally this method would only be used to determine the appropriate primary key to use within new objects added to a table in which the primary keys of the table are strictly intended from the beginning to be autoincrementing and thus will not ever be set to custom arbitrary values by the contract. Violating this agreement could result in the table appearing full when in reality there is plenty of space left. Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t key;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return key; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value);  // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(payer, [&](auto& address) {
        address.key = addresses.available_primary_key();
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function get_index (1/2)

template< IndexName>
auto eosio::multi_index< TableName, T, Indices >::get_index()

Returns an appropriately typed Secondary Index.

Returns an appropriately typed Secondary Index.

Template parameters:

  • IndexName - the ID of the desired secondary index

Returns:

An index of the appropriate type: Primitive 64-bit unsigned integer key (idx64), Primitive 128-bit unsigned integer key (idx128), 128-bit fixed-size lexicographical key (idx128), 256-bit fixed-size lexicographical key (idx256), Floating point key, Double precision floating point key, Long Double (quadruple) precision floating point key

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint32_t zip = 0;
     uint64_t primary_key() const { return account_name; }
     uint64_t by_zip() const { return zip; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address, indexed_by< name("zip"), const_mem_fun<address, uint64_t, &address::by_zip> > address_index;
    void myaction() {
      address_index addresses(_self, _self.value);  // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
        address.zip = 93446;
      });
      uint32_t zipnumb = 93446;
      auto zip_index = addresses.get_index<name("zip")>();
      auto itr = zip_index.find(zipnumb);
      eosio_assert(itr->account_name == name("dan"), "Lock arf, Incorrect Record ");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function get_index (2/2)

template< IndexName>
auto eosio::multi_index< TableName, T, Indices >::get_index() const

Returns an appropriately typed Secondary Index.

Returns an appropriately typed Secondary Index.

Template parameters:

  • IndexName - the ID of the desired secondary index

Returns:

An index of the appropriate type: Primitive 64-bit unsigned integer key (idx64), Primitive 128-bit unsigned integer key (idx128), 128-bit fixed-size lexicographical key (idx128), 256-bit fixed-size lexicographical key (idx256), Floating point key, Double precision floating point key, Long Double (quadruple) precision floating point key

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint32_t zip = 0;
     uint64_t primary_key() const { return account_name; }
     uint64_t by_zip() const { return zip; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address, indexed_by< name("zip"), const_mem_fun<address, uint64_t, &address::by_zip> > address_index;
    void myaction() {
      address_index addresses(_self, _self.value); // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
        address.zip = 93446;
      });
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "brendan"_n;
        address.first_name = "Brendan";
        address.last_name = "Blumer";
        address.street = "1 EOS Way";
        address.city = "Hong Kong";
        address.state = "HK";
        address.zip = 93445;
      });
      uint32_t zipnumb = 93445;
      auto zip_index = addresses.get_index<name("zip")>();
      auto itr = zip_index.upper_bound(zipnumb);
      eosio_assert(itr->account_name == name("dan"), "Lock arf, Incorrect First Upper Bound Record ");
      itr++;
      eosio_assert(itr == zip_index.end(), "Lock arf, Incorrect End of Iterator");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function iterator_to

const_iterator eosio::multi_index< TableName, T, Indices >::iterator_to(
    const T & obj
) const

Returns an iterator to the given object in a Multi-Index table.

Returns an iterator to the given object in a Multi-Index table.

Parameters:

  • obj - A reference to the desired object

Returns:

An iterator to the given object

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint32_t zip = 0;
     uint64_t primary_key() const { return account_name; }
     uint64_t by_zip() const { return zip; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address, indexed_by< name("zip"), const_mem_fun<address, uint64_t, &address::by_zip> > address_index;
    void myaction() {
      address_index addresses(_self, _self.value); // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
        address.zip = 93446;
      });
      addresses.emplace(payer, [&](auto& address) {
        address.account_name = "brendan"_n;
        address.first_name = "Brendan";
        address.last_name = "Blumer";
        address.street = "1 EOS Way";
        address.city = "Hong Kong";
        address.state = "HK";
        address.zip = 93445;
      });
      auto user = addresses.get("dan"_n);
      auto itr = address.find("dan"_n);
      eosio_assert(iterator_to(user) == itr, "Invalid iterator");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function emplace

template<typename Lambda>
const_iterator eosio::multi_index< TableName, T, Indices >::emplace(
    name payer,
    Lambda && constructor
)

Adds a new object (i.e., row) to the table.

Adds a new object (i.e., row) to the table.

Parameters:

  • payer - Account name of the payer for the Storage usage of the new object
  • constructor - Lambda function that does an in-place initialization of the object to be created in the table

Precondition:

A multi index table has been instantiated

Post

A new object is created in the Multi-Index table, with a unique primary key (as specified in the object). The object is serialized and written to the table. If the table does not exist, it is created.

Post

Secondary indices are updated to refer to the newly added object. If the secondary index tables do not exist, they are created.

Post

The payer is charged for the storage usage of the new object and, if the table (and secondary index tables) must be created, for the overhead of the table creation.

Returns:

A primary key iterator to the newly created object

Exception - The account is not authorized to write to the table. Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value); // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(_self, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function modify (1/2)

template<typename Lambda>
void eosio::multi_index< TableName, T, Indices >::modify(
    const_iterator itr,
    name payer,
    Lambda && updater
)

Modifies an existing object in a table.

Modifies an existing object in a table.

Parameters:

  • itr - an iterator pointing to the object to be updated
  • payer - account name of the payer for the Storage usage of the updated row
  • updater - lambda function that updates the target object

Precondition:

itr points to an existing element

Precondition:

payer is a valid account that is authorized to execute the action and be billed for storage usage.

Post

The modified object is serialized, then replaces the existing object in the table.

Post

Secondary indices are updated; the primary key of the updated object is not changed.

Post

The payer is charged for the storage usage of the updated object.

Post

If payer is the same as the existing payer, payer only pays for the usage difference between existing and updated object (and is refunded if this difference is negative).

Post

If payer is different from the existing payer, the existing payer is refunded for the storage usage of the existing object.

Exceptions: If called with an invalid precondition, execution is aborted. Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value); // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(_self, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      auto itr = addresses.find("dan"_n);
      eosio_assert(itr != addresses.end(), "Address for account not found");
      addresses.modify( itr, account payer, [&]( auto& address ) {
        address.city = "San Luis Obispo";
        address.state = "CA";
      });
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function modify (2/2)

template<typename Lambda>
void eosio::multi_index< TableName, T, Indices >::modify(
    const T & obj,
    name payer,
    Lambda && updater
)

Modifies an existing object in a table.

Modifies an existing object in a table.

Parameters:

  • obj - a reference to the object to be updated
  • payer - account name of the payer for the Storage usage of the updated row
  • updater - lambda function that updates the target object

Precondition:

obj is an existing object in the table

Precondition:

payer is a valid account that is authorized to execute the action and be billed for storage usage.

Post

The modified object is serialized, then replaces the existing object in the table.

Post

Secondary indices are updated; the primary key of the updated object is not changed.

Post

The payer is charged for the storage usage of the updated object.

Post

If payer is the same as the existing payer, payer only pays for the usage difference between existing and updated object (and is refunded if this difference is negative).

Post

If payer is different from the existing payer, the existing payer is refunded for the storage usage of the existing object.

Exceptions: If called with an invalid precondition, execution is aborted. Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value); // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(_self, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      auto itr = addresses.find("dan"_n);
      eosio_assert(itr != addresses.end(), "Address for account not found");
      addresses.modify( *itr, payer, [&]( auto& address ) {
        address.city = "San Luis Obispo";
        address.state = "CA";
      });
      eosio_assert(itr->city == "San Luis Obispo", "Lock arf, Address not modified");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function get

const T& eosio::multi_index< TableName, T, Indices >::get(
    uint64_t primary,
    const char * error_msg = "unable to find key"
) const

Retrieves an existing object from a table using its primary key.

Retrieves an existing object from a table using its primary key.

Parameters:

  • primary - Primary key value of the object

Returns:

A constant reference to the object containing the specified primary key.

Exception - No object matches the given key Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value); // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(_self, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      auto user = addresses.get("dan"_n);
      eosio_assert(user.first_name == "Daniel", "Couldn't get him.");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function find

const_iterator eosio::multi_index< TableName, T, Indices >::find(
    uint64_t primary
) const

Search for an existing object in a table using its primary key.

Search for an existing object in a table using its primary key.

Parameters:

  • primary - Primary key value of the object

Returns:

An iterator to the found object which has a primary key equal to primary OR the end iterator of the referenced table if an object with primary key primary is not found.

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value); // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(_self, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      auto itr = addresses.find("dan"_n);
      eosio_assert(itr != addresses.end(), "Couldn't get him.");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

function require_find

const_iterator eosio::multi_index< TableName, T, Indices >::require_find(
    uint64_t primary,
    const char * error_msg = "unable to find key"
) const

Search for an existing object in a table using its primary key.

Search for an existing object in a table using its primary key.

Parameters:

  • primary - Primary key value of the object
  • error_msg - error message if an object with primary key primary is not found.

Returns:

An iterator to the found object which has a primary key equal to primary OR throws an exception if an object with primary key primary is not found.

function erase (1/2)

const_iterator eosio::multi_index< TableName, T, Indices >::erase(
    const_iterator itr
)

Remove an existing object from a table using its primary key.

Remove an existing object from a table using its primary key.

Parameters:

  • itr - An iterator pointing to the object to be removed

Precondition:

itr points to an existing element

Post

The object is removed from the table and all associated storage is reclaimed.

Post

Secondary indices associated with the table are updated.

Post

The existing payer for storage usage of the object is refunded for the table and secondary indices usage of the removed object, and if the table and indices are removed, for the associated overhead.

Returns:

For the signature with , returns a pointer to the object following the removed object.

Exceptions: The object to be removed is not in the table. The action is not authorized to modify the table. The given iterator is invalid. Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value); // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(_self, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      auto itr = addresses.find("dan"_n);
      eosio_assert(itr != addresses.end(), "Address for account not found");
      addresses.erase( itr );
      eosio_assert(itr != addresses.end(), "Everting lock arf, Address not erased properly");
    }
}
EOSIO_ABI( addressbook, (myaction) )

function erase (2/2)

void eosio::multi_index< TableName, T, Indices >::erase(
    const T & obj
)

Remove an existing object from a table using its primary key.

Remove an existing object from a table using its primary key.

Parameters:

  • obj - Object to be removed

Precondition:

obj is an existing object in the table

Post

The object is removed from the table and all associated storage is reclaimed.

Post

Secondary indices associated with the table are updated.

Post

The existing payer for storage usage of the object is refunded for the table and secondary indices usage of the removed object, and if the table and indices are removed, for the associated overhead.

Exceptions: The object to be removed is not in the table. The action is not authorized to modify the table. The given iterator is invalid. Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
using namespace std;
class addressbook: contract {
  struct address {
     uint64_t account_name;
     string first_name;
     string last_name;
     string street;
     string city;
     string state;
     uint64_t primary_key() const { return account_name; }
  };
  public:
    addressbook(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds) {}
    typedef eosio::multi_index< name("address"), address > address_index;
    void myaction() {
      address_index addresses(_self, _self.value); // code, scope
      // add to table, first argument is account to bill for storage
      addresses.emplace(_self, [&](auto& address) {
        address.account_name = "dan"_n;
        address.first_name = "Daniel";
        address.last_name = "Larimer";
        address.street = "1 EOS Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
      auto itr = addresses.find("dan"_n);
      eosio_assert(itr != addresses.end(), "Record is not found");
      addresses.erase(*itr);
      itr = addresses.find("dan"_n);
      eosio_assert(itr == addresses.end(), "Record is not deleted");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

The documentation for this class was generated from the following file: libraries/eosiolib/multi\_index.hpp