Merge pull request #7650 from ethereum/develop

Merge develop into develop_060

docs/types/mapping-types.rst

@@ -4,7 +4,8 @@
 Mapping Types
 =============
 
-You declare mapping types with the syntax ``mapping(_KeyType => _ValueType)``.
+Mapping types use the syntax ``mapping(_KeyType => _ValueType)`` and variables
+are declared as a mapping type using the syntax ``mapping (_KeyType => _ValueType) _VariableModifiers _VariableName``.
 The ``_KeyType`` can be any elementary type. This means it can be any of
 the built-in value types plus ``bytes`` and ``string``. User-defined
 or complex types like contract types, enums, mappings, structs and any array type
@@ -27,11 +28,16 @@ They cannot be used as parameters or return parameters
 of contract functions that are publicly visible.
 
 You can mark state variables of mapping type as ``public`` and Solidity creates a
-:ref:`getter <visibility-and-getters>` for you. The ``_KeyType`` becomes a
-parameter for the getter. If ``_ValueType`` is a value type or a struct,
-the getter returns ``_ValueType``.
+:ref:`getter <visibility-and-getters>` for you. The ``_KeyType`` becomes a parameter for the getter.
+If ``_ValueType`` is a value type or a struct, the getter returns ``_ValueType``.
 If ``_ValueType`` is an array or a mapping, the getter has one parameter for
-each ``_KeyType``, recursively. For example with a mapping:
+each ``_KeyType``, recursively.
+
+In the example below, the ``MappingExample`` contract defines a public ``balances``
+mapping, with the key type an ``address``, and a value type a ``uint``, mapping
+an Ethereum address to an unsigned integer value. As ``uint`` is a value type, the getter
+returns a value that matches the type, which you can see in the ``MappingUser``
+contract that returns the value at the specified address.
 
 ::
 
@@ -53,7 +59,146 @@ each ``_KeyType``, recursively. For example with a mapping:
         }
     }
 
+The example below is a simplified version of an `ERC20 token <https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/ERC20.sol>`_.
+``_allowances`` is an example of a mapping type inside another mapping type.
+The example below uses ``_allowances`` to record the amount someone else is allowed to withdraw from your account.
 
-.. note::
-  Mappings are not iterable, but it is possible to implement a data structure
-  on top of them. For an example, see `iterable mapping <https://github.com/ethereum/dapp-bin/blob/master/library/iterable_mapping.sol>`_.
+::
+
+    pragma solidity >=0.4.0 <0.7.0;
+
+    contract MappingExample {
+
+        mapping (address => uint256) private _balances;
+        mapping (address => mapping (address => uint256)) private _allowances;
+
+        event Transfer(address indexed from, address indexed to, uint256 value);
+        event Approval(address indexed owner, address indexed spender, uint256 value);
+
+        function allowance(address owner, address spender) public view returns (uint256) {
+            return _allowances[owner][spender];
+        }
+
+        function transferFrom(address sender, address recipient, uint256 amount) public returns (bool) {
+            _transfer(sender, recipient, amount);
+            approve(sender, msg.sender, amount);
+            return true;
+        }
+
+        function approve(address owner, address spender, uint256 amount) public returns (bool) {
+            require(owner != address(0), "ERC20: approve from the zero address");
+            require(spender != address(0), "ERC20: approve to the zero address");
+
+            _allowances[owner][spender] = amount;
+            emit Approval(owner, spender, amount);
+            return true;
+        }
+
+        function _transfer(address sender, address recipient, uint256 amount) internal {
+            require(sender != address(0), "ERC20: transfer from the zero address");
+            require(recipient != address(0), "ERC20: transfer to the zero address");
+
+            _balances[sender] -= amount;
+            _balances[recipient] += amount;
+            emit Transfer(sender, recipient, amount);
+        }
+    }
+
+
+.. index:: !iterable mappings
+.. _iterable-mappings:
+
+Iterable Mappings
+-----------------
+
+Mappings are not iterable, but it is possible to implement a data structure on
+top of them and iterate over that. For example, the code below implements an
+``IterableMapping`` library that the ``User`` contract then adds data too, and
+the ``sum`` function iterates over to sum all the values.
+
+::
+
+    pragma solidity >=0.4.0 <0.7.0;
+
+    library IterableMapping {
+
+        struct itmap {
+            mapping(uint => IndexValue) data;
+            KeyFlag[] keys;
+            uint size;
+        }
+
+        struct IndexValue { uint keyIndex; uint value; }
+        struct KeyFlag { uint key; bool deleted; }
+
+        function insert(itmap storage self, uint key, uint value) internal returns (bool replaced) {
+            uint keyIndex = self.data[key].keyIndex;
+            self.data[key].value = value;
+            if (keyIndex > 0)
+                return true;
+            else {
+                keyIndex = self.keys.length++;
+                self.data[key].keyIndex = keyIndex + 1;
+                self.keys[keyIndex].key = key;
+                self.size++;
+                return false;
+            }
+        }
+
+        function remove(itmap storage self, uint key) internal returns (bool success) {
+            uint keyIndex = self.data[key].keyIndex;
+            if (keyIndex == 0)
+                return false;
+            delete self.data[key];
+            self.keys[keyIndex - 1].deleted = true;
+            self.size --;
+        }
+
+        function contains(itmap storage self, uint key) internal view returns (bool) {
+            return self.data[key].keyIndex > 0;
+        }
+
+        function iterate_start(itmap storage self) internal view returns (uint keyIndex) {
+            return iterate_next(self, uint(-1));
+        }
+
+        function iterate_valid(itmap storage self, uint keyIndex) internal view returns (bool) {
+            return keyIndex < self.keys.length;
+        }
+
+        function iterate_next(itmap storage self, uint keyIndex) internal view returns (uint r_keyIndex) {
+            keyIndex++;
+            while (keyIndex < self.keys.length && self.keys[keyIndex].deleted)
+                keyIndex++;
+            return keyIndex;
+        }
+
+        function iterate_get(itmap storage self, uint keyIndex) internal view returns (uint key, uint value) {
+            key = self.keys[keyIndex].key;
+            value = self.data[key].value;
+        }
+    }
+
+    // How to use it
+    contract User {
+        // Just a struct holding our data.
+        IterableMapping.itmap data;
+
+        // Insert something
+        function insert(uint k, uint v) public returns (uint size) {
+            // Actually calls itmap_impl.insert, auto-supplying the first parameter for us.
+            IterableMapping.insert(data, k, v);
+            // We can still access members of the struct - but we should take care not to mess with them.
+            return data.size;
+        }
+
+        // Computes the sum of all stored data.
+        function sum() public view returns (uint s) {
+            for (uint i = IterableMapping.iterate_start(data);
+            IterableMapping.iterate_valid(data, i);
+            i = IterableMapping.iterate_next(data, i)) {
+                (, uint value) = IterableMapping.iterate_get(data, i);
+                s += value;
+            }
+        }
+    }

docs/types/operators.rst

@@ -17,7 +17,7 @@ equivalent to ``a = 0``, but it can also be used on arrays, where it assigns a d
 array of length zero or a static array of the same length with all elements set to their
 initial value. ``delete a[x]`` deletes the item at index ``x`` of the array and leaves
 all other elements and the length of the array untouched. This especially means that it leaves
-a gap in the array. If you plan to remove items, a mapping is probably a better choice.
+a gap in the array. If you plan to remove items, a :ref:`mapping <mapping-types>` is probably a better choice.
 
 For structs, it assigns a struct with all members reset. In other words, the value of ``a`` after ``delete a`` is the same as if ``a`` would be declared without assignment, with the following caveat: