Document how to properly use multi_index::get and deprecate related methods that take a reference

[arhag]

We need clear documentation on how to use multi_index::get so that contract developers avoid the common pitfall of copy assigning the reference returned from multi_index::get to a stack-allocated local variable and then passing that into multi_index::modify.

The most common mistake is that users use auto as the typename for the local variable when they should be using auto& or decltype(auto).

Also, because this is a common mistake contract developers make which could lead to undefined behavior, we should deprecate the overloads of modify and erase methods in multi_index that take a reference, and encourage them to use the versions that take const_iterator instead which are much safer.

We should also provide warnings in the documentation about using iterator_to which can have similar undefined behavior if the developer passes in a reference to a stack-allocated object rather than the reference returned by get or by dereferencing a const_iterator. Perhaps we can also provide a safer overload of iterator_to that takes a const_iterator.

Along with deprecating multi_index::get, we should also make sure we do not actually use it in any of the contracts in our repository. Instead we could use multi_index::require_find from EOSIO/eos#4227.

[dixia]

@arhag I feel this issue is better documented in eosio.cdt repo. BTW I could no longer find this member function (get). Did it get rename?

[lparisc]

@arhag this is an old issue when eosiolib (now on eosio.cdt) used to be on eos. If still applicable, please move issue to eosio.cdt, then close here regardless.

[lparisc]

Prospective places to add the suggested explainers:

• https://developers.eos.io/manuals/eosio.cdt/latest/how-to-guides/multi-index/
• https://developers.eos.io/manuals/eosio.cdt/latest/best-practices/

@iamveritas

[iamveritas]

multi index get reference doc: https://developers.eos.io/manuals/eosio.cdt/latest/structeosio_1_1multi__index_1_1index/#function-get-12