From 4cc102fa61116036e0d7c811f081deecbaaf7cba Mon Sep 17 00:00:00 2001 From: Chris Ward Date: Wed, 9 Jan 2019 12:37:20 +0100 Subject: Split operators involving LValues into new doc --- docs/conf.py | 2 +- docs/types.rst | 48 +----------------------------------------------- docs/types/operators.rst | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 49 insertions(+), 48 deletions(-) create mode 100644 docs/types/operators.rst (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 342aefa9..d08a5191 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -81,7 +81,7 @@ else: # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build', 'contracts'] +exclude_patterns = ['_build', 'contracts', 'types'] # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/docs/types.rst b/docs/types.rst index 4eb1f926..61b0afc0 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -1196,53 +1196,7 @@ each ``_KeyType``, recursively. For example with a mapping: Mappings are not iterable, but it is possible to implement a data structure on top of them. For an example, see `iterable mapping `_. -.. index:: assignment, ! delete, lvalue - -Operators Involving LValues -=========================== - -If ``a`` is an LValue (i.e. a variable or something that can be assigned to), the following operators are available as shorthands: - -``a += e`` is equivalent to ``a = a + e``. The operators ``-=``, ``*=``, ``/=``, ``%=``, ``|=``, ``&=`` and ``^=`` are defined accordingly. ``a++`` and ``a--`` are equivalent to ``a += 1`` / ``a -= 1`` but the expression itself still has the previous value of ``a``. In contrast, ``--a`` and ``++a`` have the same effect on ``a`` but return the value after the change. - -delete ------- - -``delete a`` assigns the initial value for the type to ``a``. I.e. for integers it is -equivalent to ``a = 0``, but it can also be used on arrays, where it assigns a dynamic -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. - -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: - -``delete`` has no effect on mappings (as the keys of mappings may be arbitrary and are generally unknown). So if you delete a struct, it will reset all members that are not mappings and also recurse into the members unless they are mappings. However, individual keys and what they map to can be deleted: If ``a`` is a mapping, then ``delete a[x]`` will delete the value stored at ``x``. - -It is important to note that ``delete a`` really behaves like an assignment to ``a``, i.e. it stores a new object in ``a``. -This distinction is visible when ``a`` is reference variable: It will only reset ``a`` itself, not the -value it referred to previously. - -:: - - pragma solidity >=0.4.0 <0.6.0; - - contract DeleteExample { - uint data; - uint[] dataArray; - - function f() public { - uint x = data; - delete x; // sets x to 0, does not affect data - delete data; // sets data to 0, does not affect x - uint[] storage y = dataArray; - delete dataArray; // this sets dataArray.length to zero, but as uint[] is a complex object, also - // y is affected which is an alias to the storage object - // On the other hand: "delete y" is not valid, as assignments to local variables - // referencing storage objects can only be made from existing storage objects. - assert(y.length == 0); - } - } +.. include:: types/operators.rst .. index:: ! type;conversion, ! cast diff --git a/docs/types/operators.rst b/docs/types/operators.rst new file mode 100644 index 00000000..9851f214 --- /dev/null +++ b/docs/types/operators.rst @@ -0,0 +1,47 @@ +.. index:: assignment, ! delete, lvalue + +Operators Involving LValues +=========================== + +If ``a`` is an LValue (i.e. a variable or something that can be assigned to), the following operators are available as shorthands: + +``a += e`` is equivalent to ``a = a + e``. The operators ``-=``, ``*=``, ``/=``, ``%=``, ``|=``, ``&=`` and ``^=`` are defined accordingly. ``a++`` and ``a--`` are equivalent to ``a += 1`` / ``a -= 1`` but the expression itself still has the previous value of ``a``. In contrast, ``--a`` and ``++a`` have the same effect on ``a`` but return the value after the change. + +delete +------ + +``delete a`` assigns the initial value for the type to ``a``. I.e. for integers it is +equivalent to ``a = 0``, but it can also be used on arrays, where it assigns a dynamic +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. + +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: + +``delete`` has no effect on mappings (as the keys of mappings may be arbitrary and are generally unknown). So if you delete a struct, it will reset all members that are not mappings and also recurse into the members unless they are mappings. However, individual keys and what they map to can be deleted: If ``a`` is a mapping, then ``delete a[x]`` will delete the value stored at ``x``. + +It is important to note that ``delete a`` really behaves like an assignment to ``a``, i.e. it stores a new object in ``a``. +This distinction is visible when ``a`` is reference variable: It will only reset ``a`` itself, not the +value it referred to previously. + +:: + + pragma solidity >=0.4.0 <0.6.0; + + contract DeleteExample { + uint data; + uint[] dataArray; + + function f() public { + uint x = data; + delete x; // sets x to 0, does not affect data + delete data; // sets data to 0, does not affect x + uint[] storage y = dataArray; + delete dataArray; // this sets dataArray.length to zero, but as uint[] is a complex object, also + // y is affected which is an alias to the storage object + // On the other hand: "delete y" is not valid, as assignments to local variables + // referencing storage objects can only be made from existing storage objects. + assert(y.length == 0); + } + } -- cgit