diff options
| -rw-r--r-- | docs/types.rst | 44 |
1 files changed, 24 insertions, 20 deletions
diff --git a/docs/types.rst b/docs/types.rst index 37ccd329..de384e2f 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -971,26 +971,30 @@ assigning it to a local variable, as in Mappings ======== -Mapping types are declared as ``mapping(_KeyType => _ValueType)``. -Here ``_KeyType`` can be almost any type except for a mapping, a dynamically sized array, a contract, a function, an enum and a struct. -``_ValueType`` can actually be any type, including mappings. - -Mappings can be seen as `hash tables <https://en.wikipedia.org/wiki/Hash_table>`_ which are virtually initialized such that -every possible key exists and is mapped to a value whose byte-representation is -all zeros: a type's :ref:`default value <default-value>`. The similarity ends here, though: The key data is not actually stored -in a mapping, only its ``keccak256`` hash used to look up the value. - -Because of this, mappings do not have a length or a concept of a key or value being "set". - -Mappings are only allowed for state variables (or as storage reference types +You declare mapping types with the syntax ``mapping(_KeyType => _ValueType)``. +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 +apart from ``bytes`` and ``string`` are not allowed. +``_ValueType`` can be any type, including mappings. + +You can think of mappings as `hash tables <https://en.wikipedia.org/wiki/Hash_table>`_, which are virtually initialized +such that every possible key exists and is mapped to a value whose +byte-representation is all zeros, a type's :ref:`default value <default-value>`. The similarity ends there, the key data is not stored in a +mapping, only its ``keccak256`` hash is used to look up the value. + +Because of this, mappings do not have a length or a concept of a key or +value being set. + +Mappings are **only** allowed for state variables (or as storage reference types in internal functions). -It is possible to mark mappings ``public`` and have Solidity create a :ref:`getter <visibility-and-getters>`. -The ``_KeyType`` will become a required parameter for the getter and it will -return ``_ValueType``. - -The ``_ValueType`` can be a mapping too. The getter will have one parameter -for each ``_KeyType``, recursively. +You can mark 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``. +If ``_ValueType`` is an array or a mapping, the getter has one parameter for +each ``_KeyType``, recursively. For example with a mapping: :: @@ -1014,8 +1018,8 @@ for each ``_KeyType``, recursively. .. 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>`_. + 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>`_. .. index:: assignment, ! delete, lvalue |