class eosio::multi_index

Class List > eosio :: multi_index

Defines EOSIO Multi Index Table. More...

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
uint64_t get_scope () const
const_iterator cbegin () const
const_iterator begin () const
const_iterator cend () const
const_iterator end () const
const_reverse_iterator crbegin () const
const_reverse_iterator rbegin () const
const_reverse_iterator crend () const
const_reverse_iterator rend () const
const_iterator lower_bound (uint64_t primary) const
const_iterator upper_bound (uint64_t primary) const
uint64_t available_primary_key () const
auto get_index ()
auto get_index () const
const_iterator iterator_to (const T & obj) const
const_iterator emplace (name payer, Lambda && constructor)
void modify (const_iterator itr, name payer, Lambda && updater)
void modify (const T & obj, name payer, Lambda && updater)
const T & get (uint64_t primary, const char * error_msg = "unable to find key") const
const_iterator find (uint64_t primary) const
const_iterator require_find (uint64_t primary, const char * error_msg = "unable to find key") const
const_iterator erase (const_iterator itr)
void erase (const T & obj)

Detailed Description

EOSIO Multi-Index API provides a C++ interface to the EOSIO database. It is patterned after Boost Multi Index Container. EOSIO Multi-Index table requires exactly a uint64_t primary key. For the table to be able to retrieve the primary key, the object stored inside the table is required to have a const member function called primary_key() that returns uint64_t. EOSIO Multi-Index table also supports up to 16 secondary indices. The type of the secondary indices could be any of:

  • uint64_t
  • uint128_t
  • double
  • long double
  • eosio::checksum256

Template parameters:

  • TableName - name of the table
  • T - type of the data stored inside the table
  • Indices - secondary indices for the table, up to 16 indices is supported here

Example:

#include <eosiolib/eosio.hpp>
using namespace eosio;
class mycontract: contract {
  struct record {
    uint64_t    primary;
    uint64_t    secondary_1;
    uint128_t   secondary_2;
    checksum256 secondary_3;
    double      secondary_4;
    long double secondary_5;
    uint64_t primary_key() const { return primary; }
    uint64_t get_secondary_1() const { return secondary_1; }
    uint128_t get_secondary_2() const { return secondary_2; }
    checksum256 get_secondary_3() const { return secondary_3; }
    double get_secondary_4() const { return secondary_4; }
    long double get_secondary_5() const { return secondary_5; }
  };
  public:
    mycontract(name receiver, name code, datastream<const char*> ds):contract(receiver, code, ds){}
    void myaction() {
      auto code = _self;
      auto scope = _self;
      multi_index<"mytable"_n, record,
        indexed_by< "bysecondary1"_n, const_mem_fun<record, uint64_t, &record::get_secondary_1> >,
        indexed_by< "bysecondary2"_n, const_mem_fun<record, uint128_t, &record::get_secondary_2> >,
        indexed_by< "bysecondary3"_n, const_mem_fun<record, checksum256, &record::get_secondary_3> >,
        indexed_by< "bysecondary4"_n, const_mem_fun<record, double, &record::get_secondary_4> >,
        indexed_by< "bysecondary5"_n, const_mem_fun<record, long double, &record::get_secondary_5> >
      > table( code, scope);
    }
}
EOSIO_DISPATCH( mycontract, (myaction) )

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.

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:

Account name of the Code that owns the Primary Table.

Example:

// This assumes the code from the constructor example. Replace myaction() {...}

    void myaction() {
      address_index addresses("dan"_n, "dan"_n.value); // code, scope
      eosio::check(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:

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

Example:

// This assumes the code from the constructor example. Replace myaction() {...}

    void myaction() {
      address_index addresses("dan"_n, "dan"_n.value); // code, scope
      eosio::check(addresses.get_scope() == "dan"_n.value, "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.

Example:

// This assumes the code from the constructor example. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example below
      // add dan account to table           - see emplace example below

      auto itr = addresses.find("dan"_n);
      eosio::check(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.

Example:

// This assumes the code from the constructor example. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example below
      // add dan account to table           - see emplace example below

      auto itr = addresses.find("dan"_n);
      eosio::check(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 referring to the past-the-end element in the multi index container. The past-the-end element is the theoretical element that would follow the last element in the vector. It does not point to any element, and thus shall not be dereferenced.

Returns:

An iterator referring to the past-the-end element in the multi index container.

Example:

// This assumes the code from the constructor example. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example below
      // add dan account to table           - see emplace example below

      auto itr = addresses.find("dan"_n);
      eosio::check(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 referring to the past-the-end element in the multi index container. The past-the-end element is the theoretical element that would follow the last element in the vector. It does not point to any element, and thus shall not be dereferenced.

Returns:

An iterator referring to the past-the-end element in the multi index container.

Example:

// This assumes the code from the constructor example. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example below
      // add dan account to table           - see emplace example below

      auto itr = addresses.find("dan"_n);
      eosio::check(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.

Example:

// This assumes the code from the constructor example. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example below
      // add dan account to table           - see emplace example below
      // add additional account - brendan

      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::check(itr->account_name == name("dan"), "Lock arf, Incorrect Last Record ");
      itr++;
      eosio::check(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.

Example:

// This assumes the code from the constructor example. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example below
      // add dan account to table           - see emplace example below
      // add additional account - brendan

      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::check(itr->account_name == name("dan"), "Lock arf, Incorrect Last Record ");
      itr++;
      eosio::check(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.

Example:

// This assumes the code from the constructor example. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example below
      // add dan account to table           - see emplace example below
      // add additional account - brendan

      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::check(itr->account_name == name("brendan"), "Lock arf, Incorrect First Record ");
      itr--;
      eosio::check(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.

Example:

// This assumes the code from the constructor example. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example below
      // add dan account to table           - see emplace example below
      // add additional account - brendan

      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::check(itr->account_name == name("brendan"), "Lock arf, Incorrect First Record ");
      itr--;
      eosio::check(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.

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, or if the table does not exist**, it will return the end iterator.

Example:

// This assumes the code from the get_index() example below. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example below
      // add dan account to table           - see emplace example below
      // add additional account - brendan

      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::check(itr->account_name == name("brendan"), "Lock arf, Incorrect First Lower Bound Record ");
      itr++;
      eosio::check(itr->account_name == name("dan"), "Lock arf, Incorrect Second Lower Bound Record");
      itr++;
      eosio::check(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 lowest primary key that is greater than 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 lowest primary key that is greater than a given primary key. If an object could not be found, or if the table does not exist**, it will return the end iterator.

Example:

// This assumes the code from the get_index() example below. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example below
      // add dan account to table           - see emplace example below
      // add additional account - brendan

      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::check(itr->account_name == name("dan"), "Lock arf, Incorrect First Upper Bound Record ");
      itr++;
      eosio::check(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 (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:

// This assumes the code from the constructor example. Replace myaction() {...}

    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.

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() {
      // create reference to address_index  - see emplace example below
      // add dan account to table           - see emplace example below
      uint32_t zipnumb = 93446;
      auto zip_index = addresses.get_index<name("zip")>();
      auto itr = zip_index.find(zipnumb);
      eosio::check(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.

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:

// This assumes the code from the get_index() example. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example below
      // add dan account to table           - see emplace example below
      // add additional account - brendan

      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::check(itr->account_name == name("dan"), "Lock arf, Incorrect First Upper Bound Record ");
      itr++;
      eosio::check(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.

Parameters:

  • obj - A reference to the desired object

Returns:

An iterator to the given object

Example:

// This assumes the code from the get_index() example. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example below
      // add dan account to table           - see emplace example below
      // add additional account - brendan

      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::check(iterator_to(user) == itr, "Invalid iterator");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

Warning: the interator_to can have undefined behavior if the caller passes in a reference to a stack-allocated object rather than the reference returned by get or by dereferencing a const_iterator.

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.

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:

// This assumes the code from the constructor example. Replace myaction() {...}

    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.

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:

// This assumes the code from the constructor example. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example
      // add dan account to table           - see emplace example

      auto itr = addresses.find("dan"_n);
      eosio::check(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.

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:

// This assumes the code from the constructor example. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example
      // add dan account to table           - see emplace example

      auto itr = addresses.find("dan"_n);
      eosio::check(itr != addresses.end(), "Address for account not found");
      addresses.modify( *itr, payer, [&]( auto& address ) {
        address.city = "San Luis Obispo";
        address.state = "CA";
      });
      eosio::check(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.

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:

// This assumes the code from the constructor example. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example
      // add dan account to table           - see emplace example

      auto& user = addresses.get("dan"_n);
      eosio::check(user.first_name == "Daniel", "Couldn't get him.");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

Warning: Avoid the common pitfall of copy-assigning the T& reference returned to a stack-allocated local variable and then passing that into modify of the multi-index. The most common mistake is when the local variable is defined as auto typename, instead it should be of type auto& or decltype(auto).

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.

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:

// This assumes the code from the constructor example. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example
      // add dan account to table           - see emplace example

      auto itr = addresses.find("dan"_n);
      eosio::check(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.

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.

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:

// This assumes the code from the constructor example. Replace myaction() {...}

    void myaction() {
      // create reference to address_index  - see emplace example
      // add dan account to table           - see emplace example

      auto itr = addresses.find("dan"_n);
      eosio::check(itr != addresses.end(), "Address for account not found");
      addresses.erase( itr );
      eosio::check(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.

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:

// This assumes the code from the constructor example. Replace myaction() {...}

    void myaction() {
      auto itr = addresses.find("dan"_n);
      eosio::check(itr != addresses.end(), "Record is not found");
      addresses.erase(*itr);
      itr = addresses.find("dan"_n);
      eosio::check(itr == addresses.end(), "Record is not deleted");
    }
}
EOSIO_DISPATCH( addressbook, (myaction) )

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