diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/common-patterns.rst | 8 | ||||
| -rw-r--r-- | docs/contracts.rst | 40 | ||||
| -rw-r--r-- | docs/control-structures.rst | 77 | ||||
| -rw-r--r-- | docs/frequently-asked-questions.rst | 10 | ||||
| -rw-r--r-- | docs/index.rst | 3 | ||||
| -rw-r--r-- | docs/installing-solidity.rst | 2 | ||||
| -rw-r--r-- | docs/miscellaneous.rst | 5 | ||||
| -rw-r--r-- | docs/style-guide.rst | 14 | ||||
| -rw-r--r-- | docs/types.rst | 21 | ||||
| -rw-r--r-- | docs/units-and-global-variables.rst | 6 |
10 files changed, 148 insertions, 38 deletions
diff --git a/docs/common-patterns.rst b/docs/common-patterns.rst index 12c6f20c..74f9c078 100644 --- a/docs/common-patterns.rst +++ b/docs/common-patterns.rst @@ -186,13 +186,13 @@ restrictions highly readable. // refunded, but only after the function body. // This is dangerous, because if the function // uses `return` explicitly, this will not be - // done! + // done! This behavior will be fixed in Version 0.4.0. modifier costs(uint _amount) { if (msg.value < _amount) throw; _ if (msg.value > _amount) - msg.sender.send(_amount - msg.value); + msg.sender.send(msg.value - _amount); } function forceOwnerChange(address _newOwner) @@ -267,7 +267,9 @@ function finishes. the code in the transitionNext modifier can be skipped if the function itself uses return. If you want to do that, make sure - to call nextStage manually from those functions. + to call nextStage manually from those functions. + With version 0.4.0 (unreleased), modifier code + will run even if the function explicitly returns. :: diff --git a/docs/contracts.rst b/docs/contracts.rst index 3d592ecf..5f370951 100644 --- a/docs/contracts.rst +++ b/docs/contracts.rst @@ -314,14 +314,40 @@ inheritable properties of contracts and may be overridden by derived contracts. } } + contract Mutex { + bool locked; + modifier noReentrancy() { + if (locked) throw; + locked = true; + _ + locked = false; + } + + /// This function is protected by a mutex, which means that + /// reentrant calls from within msg.sender.call cannot call f again. + /// The `return 7` statement assigns 7 to the return value but still + /// executes the statement `locked = false` in the modifier. + function f() noReentrancy returns (uint) { + if (!msg.sender.call()) throw; + return 7; + } + } + Multiple modifiers can be applied to a function by specifying them in a -whitespace-separated list and will be evaluated in order. Explicit returns from -a modifier or function body immediately leave the whole function, while control -flow reaching the end of a function or modifier body continues after the "_" in -the preceding modifier. Arbitrary expressions are allowed for modifier -arguments and in this context, all symbols visible from the function are -visible in the modifier. Symbols introduced in the modifier are not visible in -the function (as they might change by overriding). +whitespace-separated list and will be evaluated in order. + +.. warning:: + In an earlier version of Solidity, ``return`` statements in functions + having modifiers behaved differently. + +Explicit returns from a modifier or function body only leave the current +modifier or function body. Return variables are assigned and +control flow continues after the "_" in the preceding modifier. + +Arbitrary expressions are allowed for modifier arguments and in this context, +all symbols visible from the function are visible in the modifier. Symbols +introduced in the modifier are not visible in the function (as they might +change by overriding). .. index:: ! constant diff --git a/docs/control-structures.rst b/docs/control-structures.rst index 9d7ebeac..73b0131f 100644 --- a/docs/control-structures.rst +++ b/docs/control-structures.rst @@ -10,7 +10,7 @@ Control Structures Most of the control structures from C/JavaScript are available in Solidity except for ``switch`` and ``goto``. So there is: ``if``, ``else``, ``while``, ``for``, ``break``, ``continue``, ``return``, ``? :``, with -the usual semantics known from C / JavaScript. +the usual semantics known from C or JavaScript. Parentheses can *not* be omitted for conditionals, but curly brances can be omitted around single-statement bodies. @@ -69,6 +69,10 @@ this does not execute a constructor. We could also have used ``function setFeed( only (locally) sets the value and amount of gas sent with the function call and only the parentheses at the end perform the actual call. +Function calls cause exceptions if the called contract does not exist (in the +sense that the account does not contain code) or if the called contract itself +throws an exception or goes out of gas. + .. warning:: Any interaction with another contract imposes a potential danger, especially if the source code of the contract is not known in advance. The current @@ -82,13 +86,15 @@ parentheses at the end perform the actual call. that the called contract can change state variables of the calling contract via its functions. Write your functions in a way that, for example, calls to external functions happen after any changes to state variables in your contract - so your contract is not vulnerable to a recursive call exploit. + so your contract is not vulnerable to a reentrancy exploit. Named Calls and Anonymous Function Parameters --------------------------------------------- -Function call arguments can also be given by name, in any order, and the names -of unused parameters (especially return parameters) can be omitted. +Function call arguments can also be given by name, in any order, +if they are enclosed in ``{ }`` as can be seen in the following +example. The argument list has to coincide by name with the list of +parameters from the function declaration, but can be in arbitrary order. :: @@ -99,12 +105,60 @@ of unused parameters (especially return parameters) can be omitted. // named arguments f({value: 2, key: 3}); } + } + +Omitted Function Parameter Names +-------------------------------- + +The names of unused parameters (especially return parameters) can be omitted. +Those names will still be present on the stack, but they are inaccessible. + +:: - // omitted parameters + contract C { + // omitted name for parameter function func(uint k, uint) returns(uint) { return k; } } + + +.. index:: ! new, contracts;creating + +.. _creating-contracts: + +Creating Contracts via new +========================== + +A contract can create a new contract using the ``new`` keyword. The full +code of the contract to be created has to be known and thus recursive +creation-dependencies are now possible. + +:: + + contract D { + uint x; + function D(uint a) { + x = a; + } + } + contract C { + D d = new D(4); // will be executed as part of C's constructor + + function createD(uint arg) { + D newD = new D(arg); + } + + function createAndEndowD(uint arg, uint amount) { + // Send ether along with the creation + D newD = (new D).value(amount)(arg); + } + } + +As seen in the example, it is possible to forward Ether to the creation, +but it is not possible to limit the amount of gas. If the creation fails +(due to out-of-stack, not enough balance or other problems), an exception +is thrown. Order of Evaluation of Expressions ================================== @@ -245,11 +299,14 @@ In the following example, we show how ``throw`` can be used to easily revert an } } -Currently, there are three situations, where exceptions happen automatically in Solidity: +Currently, there are six situations, where exceptions happen automatically in Solidity: -1. If you access an array beyond its length (i.e. ``x[i]`` where ``i >= x.length``) +1. If you access an array beyond its length (i.e. ``x[i]`` where ``i >= x.length``). 2. If a function called via a message call does not finish properly (i.e. it runs out of gas or throws an exception itself). 3. If a non-existent function on a library is called or Ether is sent to a library. +4. If you divide or modulo by zero (e.g. ``5 / 0`` or ``23 % 0``). +5. If you perform an external function call targeting a contract that contains no code. +6. If a contract-creation call using the ``new`` keyword fails. Internally, Solidity performs an "invalid jump" when an exception is thrown and thus causes the EVM to revert all changes made to the state. The reason for this is that there is no safe way to continue execution, because an expected effect did not occur. Because we want to retain the atomicity of transactions, the safest thing to do is to revert all changes and make the whole transaction (or at least call) without effect. @@ -337,9 +394,9 @@ Inline assembly parses comments, literals and identifiers exactly as Solidity, s usual ``//`` and ``/* */`` comments. Inline assembly is initiated by ``assembly { ... }`` and inside these curly braces, the following can be used (see the later sections for more details) - - literals, i.e. ``0x123``, ``42`` or ``"abc"`` (strings up to 32 characters) + - literals, e.g. ``0x123``, ``42`` or ``"abc"`` (strings up to 32 characters) - opcodes (in "instruction style"), e.g. ``mload sload dup1 sstore``, for a list see below - - opcode in functional style, e.g. ``add(1, mlod(0))`` + - opcodes in functional style, e.g. ``add(1, mlod(0))`` - labels, e.g. ``name:`` - variable declarations, e.g. ``let x := 7`` or ``let x := add(y, 3)`` - identifiers (externals, labels or assembly-local variables), e.g. ``jump(name)``, ``3 x add`` @@ -354,7 +411,7 @@ This document does not want to be a full description of the Ethereum virtual mac following list can be used as a reference of its opcodes. If an opcode takes arguments (always from the top of the stack), they are given in parentheses. -Note that the order of arguments can be seed to be reversed in non-functional style (explained below). +Note that the order of arguments can be seen as being reversed compared to the instructional style (explained below). Opcodes marked with ``-`` do not push an item onto the stack, those marked with ``*`` are special and all others push exactly one item onte the stack. diff --git a/docs/frequently-asked-questions.rst b/docs/frequently-asked-questions.rst index b3667a11..c28b4ab7 100644 --- a/docs/frequently-asked-questions.rst +++ b/docs/frequently-asked-questions.rst @@ -399,7 +399,7 @@ What character set does Solidity use? ===================================== Solidity is character set agnostic concerning strings in the source code, although -utf-8 is recommended. Identifiers (variables, functions, ...) can only use +UTF-8 is recommended. Identifiers (variables, functions, ...) can only use ASCII. What are some examples of basic string manipulation (``substring``, ``indexOf``, ``charAt``, etc)? @@ -741,15 +741,15 @@ see a 32-byte hex value, this is just ``"stringliteral"`` in hex. The type ``bytes`` is similar, only that it can change its length. Finally, ``string`` is basically identical to ``bytes`` only that it is assumed -to hold the utf-8 encoding of a real string. Since ``string`` stores the -data in utf-8 encoding it is quite expensive to compute the number of +to hold the UTF-8 encoding of a real string. Since ``string`` stores the +data in UTF-8 encoding it is quite expensive to compute the number of characters in the string (the encoding of some characters takes more than a single byte). Because of that, ``string s; s.length`` is not yet supported and not even index access ``s[2]``. But if you want to access the low-level byte encoding of the string, you can use ``bytes(s).length`` and ``bytes(s)[2]`` which will result in the number -of bytes in the utf-8 encoding of the string (not the number of -characters) and the second byte (not character) of the utf-8 encoded +of bytes in the UTF-8 encoding of the string (not the number of +characters) and the second byte (not character) of the UTF-8 encoded string, respectively. diff --git a/docs/index.rst b/docs/index.rst index 555ffaa7..a330172e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -56,6 +56,9 @@ Available Solidity Integrations * `Vim Solidity <https://github.com/tomlion/vim-solidity/>`_ Plugin for the Vim editor providing syntax highlighting. +* `Vim Syntastic <https://github.com/scrooloose/syntastic>`_ + Plugin for the Vim editor providing compile checking. + Discontinued: * `Mix IDE <https://github.com/ethereum/mix/>`_ diff --git a/docs/installing-solidity.rst b/docs/installing-solidity.rst index a98a1ade..16a02310 100644 --- a/docs/installing-solidity.rst +++ b/docs/installing-solidity.rst @@ -61,7 +61,7 @@ Set up Homebrew: brew upgrade brew install boost --c++11 # this takes a while - brew install cmake cryptopp gmp + brew install cmake cryptopp gmp jsoncpp Ubuntu Trusty (14.04) --------------------- diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index 304fce14..804d69ef 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -228,7 +228,7 @@ The following is the order of precedence for operators, listed in order of evalu + +-------------------------------------+--------------------------------------------+ | | Unary plus and minus | ``+``, ``-`` | + +-------------------------------------+--------------------------------------------+ -| | Unary operations | ``after``, ``delete`` | +| | Unary operations | ``delete`` | + +-------------------------------------+--------------------------------------------+ | | Logical NOT | ``!`` | + +-------------------------------------+--------------------------------------------+ @@ -286,7 +286,7 @@ Global Variables - ``sha3(...) returns (bytes32)``: compute the Ethereum-SHA-3 (KECCAK-256) hash of the (tightly packed) arguments - ``sha256(...) returns (bytes32)``: compute the SHA-256 hash of the (tightly packed) arguments - ``ripemd160(...) returns (bytes20)``: compute the RIPEMD-160 hash of the (tightly packed) arguments -- ``ecrecover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) returns (address)``: recover address associated with the public key from elliptic curve signature +- ``ecrecover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) returns (address)``: recover address associated with the public key from elliptic curve signature, return zero on error - ``addmod(uint x, uint y, uint k) returns (uint)``: compute ``(x + y) % k`` where the addition is performed with arbitrary precision and does not wrap around at ``2**256`` - ``mulmod(uint x, uint y, uint k) returns (uint)``: compute ``(x * y) % k`` where the multiplication is performed with arbitrary precision and does not wrap around at ``2**256`` - ``this`` (current contract's type): the current contract, explicitly convertible to ``address`` @@ -321,4 +321,3 @@ Modifiers - ``constant`` for functions: Disallows modification of state - this is not enforced yet. - ``anonymous`` for events: Does not store event signature as topic. - ``indexed`` for event parameters: Stores the parameter as topic. - diff --git a/docs/style-guide.rst b/docs/style-guide.rst index c509a9d4..c7b13efa 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -118,7 +118,7 @@ Source File Encoding UTF-8 or ASCII encoding is preferred. Imports -========== +======= Import statements should always be placed at the top of the file. @@ -519,6 +519,18 @@ No:: Other Recommendations ===================== +* Strings should be quoted with double-quotes instead of single-quotes. + +Yes:: + + str = "foo"; + str = "Hamlet says, 'To be or not to be...'"; + +No:: + + str = 'bar'; + str = '"Be yourself; everyone else is already taken." -Oscar Wilde'; + * Surround operators with a single space on either side. Yes:: diff --git a/docs/types.rst b/docs/types.rst index 0c5aaf1b..d6445ed9 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -57,6 +57,8 @@ Operators: Division always truncates (it just maps to the DIV opcode of the EVM), but it does not truncate if both operators are :ref:`literals<rational_literals>` (or literal expressions). +Division by zero and modulus with zero throws an exception. + .. index:: address, balance, send, call, callcode, delegatecall .. _address: @@ -147,10 +149,10 @@ Dynamically-sized byte array ``bytes``: Dynamically-sized byte array, see :ref:`arrays`. Not a value-type! ``string``: - Dynamically-sized UTF8-encoded string, see :ref:`arrays`. Not a value-type! + Dynamically-sized UTF-8-encoded string, see :ref:`arrays`. Not a value-type! As a rule of thumb, use ``bytes`` for arbitrary-length raw byte data and ``string`` -for arbitrary-length string (utf-8) data. If you can limit the length to a certain +for arbitrary-length string (UTF-8) data. If you can limit the length to a certain number of bytes, always use one of ``bytes1`` to ``bytes32`` because they are much cheaper. .. index:: ! ufixed, ! fixed, ! fixed point number @@ -214,9 +216,18 @@ a non-rational number). String Literals --------------- -String Literals are written with double quotes (``"abc"``). As with integer literals, their type can vary, but they are implicitly convertible to ``bytes1``, ..., ``bytes32`` if they fit, to ``bytes`` and to ``string``. +String literals are written with either double or single-quotes (``"foo"`` or ``'bar'``). As with integer literals, their type can vary, but they are implicitly convertible to ``bytes1``, ..., ``bytes32``, if they fit, to ``bytes`` and to ``string``. + +String literals support escape characters, such as ``\n``, ``\xNN`` and ``\uNNNN``. ``\xNN`` takes a hex value and inserts the appropriate byte, while ``\uNNNN`` takes a Unicode codepoint and inserts an UTF-8 sequence. + +.. index:: literal, bytes + +Hexadecimal Literals +-------------------- + +Hexademical Literals are prefixed with the keyword ``hex`` and are enclosed in double or single-quotes (``hex"001122FF"``). Their content must be a hexadecimal string and their value will be the binary representation of those values. -String Literals support escape characters, such as ``\n``, ``\xNN`` and ``\uNNNN``. ``\xNN`` takes a hex value and inserts the appropriate byte, while ``\uNNNN`` takes a Unicode codepoint and inserts an UTF8 sequence. +Hexademical Literals behave like String Literals and have the same convertibility restrictions. .. index:: enum @@ -353,7 +364,7 @@ So ``bytes`` should always be preferred over ``byte[]`` because it is cheaper. .. note:: If you want to access the byte-representation of a string ``s``, use ``bytes(s).length`` / ``bytes(s)[7] = 'x';``. Keep in mind - that you are accessing the low-level bytes of the utf-8 representation, + that you are accessing the low-level bytes of the UTF-8 representation, and not the individual characters! .. index:: ! array;allocating, new diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index 8b8f4daa..d1d578ed 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -7,14 +7,14 @@ Units and Globally Available Variables Ether Units =========== -A literal number can take a suffix of ``wei``, ``finney``, ``szabo`` or ``ether`` to convert between the subdenominations of Ether, where Ether currency numbers without a postfix are assumed to be "wei", e.g. ``2 ether == 2000 finney`` evaluates to ``true``. +A literal number can take a suffix of ``wei``, ``finney``, ``szabo`` or ``ether`` to convert between the subdenominations of Ether, where Ether currency numbers without a postfix are assumed to be Wei, e.g. ``2 ether == 2000 finney`` evaluates to ``true``. .. index:: time, seconds, minutes, hours, days, weeks, years Time Units ========== -Suffixes of ``seconds``, ``minutes``, ``hours``, ``days``, ``weeks`` and +Suffixes like ``seconds``, ``minutes``, ``hours``, ``days``, ``weeks`` and ``years`` after literal numbers can be used to convert between units of time where seconds are the base unit and units are considered naively in the following way: @@ -95,7 +95,7 @@ Mathematical and Cryptographic Functions ``ripemd160(...) returns (bytes20)``: compute RIPEMD-160 hash of the (tightly packed) arguments ``ecrecover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) returns (address)``: - recover the address associated with the public key from elliptic curve signature + recover the address associated with the public key from elliptic curve signature or return zero on error In the above, "tightly packed" means that the arguments are concatenated without padding. This means that the following are all identical:: |