class arisen::multi_index

Classes

Type

Name

struct

const_iterator

struct

index

struct

intc
struct multi_index::index

struct

item

struct

item_ptr

Public Functions Documentation

function multi_index

arisen::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 arisen::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.

#include <arisenlib/arisen.hpp>
using namespace arisen;
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
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function get_code

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

Returns the code member property.

Returns:

Account name of the Code that owns the Primary Table.

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

    void myaction() {
      address_index addresses("dan"_n, "dan"_n); // code, scope
      arisen::check(addresses.get_code() == "dan"_n, "Codes don't match.");
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function get_scope

uint64_t arisen::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); // code, scope
      arisen::check(addresses.get_code() == "dan"_n, "Scopes don't match");
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function cbegin

const_iterator arisen::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);
      arisen::check(itr == addresses.cbegin(), "Only address is not at front.");
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function begin

const_iterator arisen::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);
      arisen::check(itr == addresses.begin(), "Only address is not at front.");
    }
}
ARISEN_ABI( addressbook, (myaction) )

function cend

const_iterator arisen::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.

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);
      arisen::check(itr != addresses.cend(), "Address for account doesn't exist");
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function end

const_iterator arisen::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.

// 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);
      arisen::check(itr != addresses.end(), "Address for account doesn't exist");
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function crbegin

const_reverse_iterator arisen::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 RIX Way";
        address.city = "Hong Kong";
        address.state = "HK";
      });
      auto itr = addresses.crbegin();
      arisen::check(itr->account_name == name("dan"), "Lock arf, Incorrect Last Record ");
      itr++;
      arisen::check(itr->account_name == name("brendan"), "Lock arf, Incorrect Second Last Record");
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function rbegin

const_reverse_iterator arisen::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 RIX Way";
        address.city = "Hong Kong";
        address.state = "HK";
      });
      auto itr = addresses.rbegin();
      arisen::check(itr->account_name == name("dan"), "Lock arf, Incorrect Last Record ");
      itr++;
      arisen::check(itr->account_name == name("brendan"), "Lock arf, Incorrect Second Last Record");
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function rend

const_reverse_iterator arisen::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 RIX Way";
        address.city = "Hong Kong";
        address.state = "HK";
      });
      auto itr = addresses.rend();
      itr--;
      arisen::check(itr->account_name == name("brendan"), "Lock arf, Incorrect First Record ");
      itr--;
      arisen::check(itr->account_name == name("dan"), "Lock arf, Incorrect Second Record");
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function lower_bound

const_iterator arisen::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, it will return the end iterator. If the table does not exist** it will return -1.

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);
      arisen::check(itr->account_name == name("brendan"), "Lock arf, Incorrect First Lower Bound Record ");
      itr++;
      arisen::check(itr->account_name == name("dan"), "Lock arf, Incorrect Second Lower Bound Record");
      itr++;
      arisen::check(itr == zip_index.end(), "Lock arf, Incorrect End of Iterator");
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function upper_bound

const_iterator arisen::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 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.

// 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);
      arisen::check(itr->account_name == name("dan"), "Lock arf, Incorrect First Upper Bound Record ");
      itr++;
      arisen::check(itr == zip_index.end(), "Lock arf, Incorrect End of Iterator");
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function available_primary_key

uint64_t arisen::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 RIX Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function get_index (1/2)

template< IndexName>
auto arisen::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 <arisenlib/arisen.hpp>
using namespace arisen;
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 arisen::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);
      arisen::check(itr->account_name == name("dan"), "Lock arf, Incorrect Record ");
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function get_index (2/2)

template< IndexName>
auto arisen::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 RIX 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);
      arisen::check(itr->account_name == name("dan"), "Lock arf, Incorrect First Upper Bound Record ");
      itr++;
      arisen::check(itr == zip_index.end(), "Lock arf, Incorrect End of Iterator");
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function iterator_to

const_iterator arisen::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 RIX Way";
        address.city = "Hong Kong";
        address.state = "HK";
        address.zip = 93445;
      });
      auto user = addresses.get("dan"_n);
      auto itr = address.find("dan"_n);
      arisen::check(iterator_to(user) == itr, "Invalid iterator");
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function emplace

template<typename Lambda>
const_iterator arisen::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

/ 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 RIX Way";
        address.city = "Blacksburg";
        address.state = "VA";
      });
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

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

function modify (1/2)

template<typename Lambda>
void arisen::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:

template<typename Lambda>
void arisen::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);
      arisen::check(itr != addresses.end(), "Address for account not found");
      addresses.modify( *itr, payer, [&]( auto& address ) {
        address.city = "San Luis Obispo";
        address.state = "CA";
      });
      arisen::check(itr->city == "San Luis Obispo", "Lock arf, Address not modified");
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function get

// 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);
      arisen::check(user.first_name == "Daniel", "Couldn't get him.");
    }
}
ARISEN_DISPATCH( addressbook, (myaction) )

function find

const_iterator arisen::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: