diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 4 | ||||
| -rw-r--r-- | docs/contracts.rst | 6 | ||||
| -rw-r--r-- | docs/control-structures.rst | 81 | ||||
| -rw-r--r-- | docs/installing-solidity.rst | 15 | ||||
| -rw-r--r-- | docs/introduction-to-smart-contracts.rst | 6 | ||||
| -rw-r--r-- | docs/miscellaneous.rst | 11 | ||||
| -rw-r--r-- | docs/types.rst | 164 |
7 files changed, 261 insertions, 26 deletions
diff --git a/docs/conf.py b/docs/conf.py index e17d5fd8..2bc79fd9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -56,9 +56,9 @@ copyright = '2016, Ethereum' # built documents. # # The short X.Y version. -version = '0.4.5' +version = '0.4.7' # The full version, including alpha/beta/rc tags. -release = '0.4.5-develop' +release = '0.4.7-develop' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/contracts.rst b/docs/contracts.rst index 7f8ace44..e82b7495 100644 --- a/docs/contracts.rst +++ b/docs/contracts.rst @@ -721,8 +721,10 @@ Details are given in the following example. NameReg(config.lookup(1)).register(name); } - // Functions can be overridden, both local and - // message-based function calls take these overrides + // Functions can be overridden by another function with the same name and + // the same number/types of inputs. If the overriding function has different + // types of output parameters, that causes an error. + // Both local and message-based function calls take these overrides // into account. function kill() { if (msg.sender == owner) { diff --git a/docs/control-structures.rst b/docs/control-structures.rst index 597829d3..974a093f 100644 --- a/docs/control-structures.rst +++ b/docs/control-structures.rst @@ -2,21 +2,81 @@ Expressions and Control Structures ################################## -.. index:: if, else, while, for, break, continue, return, switch, goto +.. index:: ! parameter, parameter;input, parameter;output + +Input Parameters and Output Parameters +====================================== + +As in Javascript, functions may take parameters as input; +unlike in Javascript and C, they may also return arbitrary number of +parameters as output. + +Input Parameters +---------------- + +The input parameters are declared the same way as variables are. As an +exception, unused parameters can omit the variable name. +For example, suppose we want our contract to +accept one kind of external calls with two integers, we would write +something like:: + + contract Simple { + function taker(uint _a, uint _b) { + // do something with _a and _b. + } + } + +Output Parameters +----------------- + +The output parameters can be declared with the same syntax after the +``returns`` keyword. For example, suppose we wished to return two results: +the sum and the product of the two given integers, then we would +write:: + + contract Simple { + function arithmetics(uint _a, uint _b) returns (uint o_sum, uint o_product) { + o_sum = _a + _b; + o_product = _a * _b; + } + } + +The names of output parameters can be omitted. +The output values can also be specified using ``return`` statements. +The ``return`` statements are also capable of returning multiple +values, see :ref:`multi-return`. +Return parameters are initialized to zero; if they are not explicitly +set, they stay to be zero. + +Input parameters and output parameters can be used as expressions in +the function body. There, they are also usable in the left-hand side +of assignment. + +.. index:: if, else, while, do/while, for, break, continue, return, switch, goto Control Structures =================== -Most of the control structures from C or JavaScript are available in Solidity +Most of the control structures from JavaScript are available in Solidity except for ``switch`` and ``goto``. So -there is: ``if``, ``else``, ``while``, ``for``, ``break``, ``continue``, ``return``, ``? :``, with +there is: ``if``, ``else``, ``while``, ``do``, ``for``, ``break``, ``continue``, ``return``, ``? :``, with 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. Note that there is no type conversion from non-boolean to boolean types as -there is in C and JavaScript, so ``if (1) { ... }`` is *not* valid Solidity. +there is in C and JavaScript, so ``if (1) { ... }`` is *not* valid +Solidity. + +.. _multi-return: + +Returning Multiple Values +------------------------- + +When a function has multiple output parameters, ``return (v0, v1, ..., +vn)`` can return multiple values. The number of components must be +the same as the number of output parameters. .. index:: ! function;call, function;internal, function;external @@ -329,9 +389,10 @@ Currently, there are situations, where exceptions happen automatically in Solidi 3. If you call a function via a message call but it does not finish properly (i.e. it runs out of gas, has no matching function, or throws an exception itself), except when a low level operation ``call``, ``send``, ``delegatecall`` or ``callcode`` is used. The low level operations never throw exceptions but indicate failures by returning ``false``. 4. If you create a contract using the ``new`` keyword but the contract creation does not finish properly (see above for the definition of "not finish properly"). 5. If you divide or modulo by zero (e.g. ``5 / 0`` or ``23 % 0``). -6. If you perform an external function call targeting a contract that contains no code. -7. If your contract receives Ether via a public function without ``payable`` modifier (including the constructor and the fallback function). -8. If your contract receives Ether via a public accessor function. +6. If you convert a value too big or negative into an enum type. +7. If you perform an external function call targeting a contract that contains no code. +8. If your contract receives Ether via a public function without ``payable`` modifier (including the constructor and the fallback function). +9. If your contract receives Ether via a public accessor function. 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. @@ -426,7 +487,7 @@ these curly braces, the following can be used (see the later sections for more d - 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 - - opcodes in functional style, e.g. ``add(1, mlod(0))`` + - opcodes in functional style, e.g. ``add(1, mload(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`` @@ -715,6 +776,10 @@ will have a wrong impression about the stack height at label ``two``: three: } +.. note:: + + ``invalidJumpLabel`` is a pre-defined label. Jumping to this location will always + result in an invalid jump, effectively aborting execution of the code. Declaring Assembly-Local Variables ---------------------------------- diff --git a/docs/installing-solidity.rst b/docs/installing-solidity.rst index ec40e822..ef38705c 100644 --- a/docs/installing-solidity.rst +++ b/docs/installing-solidity.rst @@ -44,6 +44,21 @@ To install it, simply use Details about the usage of the Node.js package can be found in the `solc-js repository <https://github.com/ethereum/solc-js>`_. +Docker +====== + +We provide up to date docker builds for the compiler. The ``stable`` +repository contains released versions while the ``nightly`` +repository contains potentially unstable changes in the develop branch. + +.. code:: bash + + docker run ethereum/solc:stable solc --version + +Currenty, the docker image only contains the compiler executable, +so you have to do some additional work to link in the source and +output directories. + Binary Packages =============== diff --git a/docs/introduction-to-smart-contracts.rst b/docs/introduction-to-smart-contracts.rst index eeea85a7..aee1e03b 100644 --- a/docs/introduction-to-smart-contracts.rst +++ b/docs/introduction-to-smart-contracts.rst @@ -25,7 +25,7 @@ Storage storedData = x; } - function get() constant returns (uint retVal) { + function get() constant returns (uint) { return storedData; } } @@ -136,7 +136,7 @@ like this one. The accessor function created by the ``public`` keyword is a bit more complex in this case. It roughly looks like the following:: - function balances(address _account) returns (uint balance) { + function balances(address _account) returns (uint) { return balances[_account]; } @@ -433,7 +433,7 @@ Logs ==== It is possible to store data in a specially indexed data structure -that maps all they way up to the block level. This feature called **logs** +that maps all the way up to the block level. This feature called **logs** is used by Solidity in order to implement **events**. Contracts cannot access log data after it has been created, but they can be efficiently accessed from outside the blockchain. diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index 0b3eed38..15ff374d 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -74,6 +74,17 @@ Solidity always places new objects at the free memory pointer and memory is neve .. index: memory layout +******************* +Layout of Call Data +******************* + +When a Solidity contract is deployed and when it is called from an +account, the input data is assumed to be in the format in `the ABI +specification +<https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI>`_. The +ABI specification requires arguments to be padded to multiples of 32 +bytes. The internal function calls use a different convention. + ***************** Esoteric Features ***************** diff --git a/docs/types.rst b/docs/types.rst index 9e7d9b4a..0436fc70 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -169,9 +169,10 @@ Fixed Point Numbers Rational and Integer Literals ----------------------------- -All number literals retain arbitrary precision until they are converted to a non-literal type (i.e. by -using them together with a non-literal type). This means that computations do not overflow but also -divisions do not truncate. +Number literal expressions retain arbitrary precision until they are converted to a non-literal type (i.e. by +using them together with a non-literal expression). +This means that computations do not overflow and divisions do not truncate +in number literal expressions. For example, ``(2**800 + 1) - 2**800`` results in the constant ``1`` (of type ``uint8``) although intermediate results would not even fit the machine word size. Furthermore, ``.5 * 8`` results @@ -185,12 +186,20 @@ In ``var x = 1/4;``, ``x`` will receive the type ``ufixed0x8`` while in ``var x the type ``ufixed0x256`` because ``1/3`` is not finitely representable in binary and will thus be approximated. -Any operator that can be applied to integers can also be applied to literal expressions as +Any operator that can be applied to integers can also be applied to number literal expressions as long as the operands are integers. If any of the two is fractional, bit operations are disallowed and exponentiation is disallowed if the exponent is fractional (because that might result in a non-rational number). .. note:: + Solidity has a number literal type for each rational number. + Integer literals and rational number literals belong to number literal types. + Moreover, all number literal expressions (i.e. the expressions that + contain only number literals and operators) belong to number literal + types. So the number literal expressions `1 + 2` and `2 + 1` both + belong to the same number literal type for the rational number three. + +.. note:: Most finite decimal fractions like ``5.3743`` are not finitely representable in binary. The correct type for ``5.3743`` is ``ufixed8x248`` because that allows to best approximate the number. If you want to use the number together with types like ``ufixed`` (i.e. ``ufixed128x128``), you have to explicitly @@ -200,7 +209,7 @@ a non-rational number). Division on integer literals used to truncate in earlier versions, but it will now convert into a rational number, i.e. ``5 / 2`` is not equal to ``2``, but to ``2.5``. .. note:: - Literal expressions are converted to a permanent type as soon as they are used with other + Number literal expressions are converted into a non-literal type as soon as they are used with non-literal expressions. Even though we know that the value of the expression assigned to ``b`` in the following example evaluates to an integer, it still uses fixed point types (and not rational number literals) in between and so the code @@ -216,7 +225,7 @@ a non-rational number). String Literals --------------- -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 are written with either double or single-quotes (``"foo"`` or ``'bar'``). They do not imply trailing zeroes as in C; `"foo"`` represents three bytes not four. 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. @@ -234,10 +243,11 @@ Hexademical Literals behave like String Literals and have the same convertibilit .. _enums: Enums -===== +----- Enums are one way to create a user-defined type in Solidity. They are explicitly convertible -to and from all integer types but implicit conversion is not allowed. +to and from all integer types but implicit conversion is not allowed. The explicit conversions +check the value ranges at runtime and a failure causes an exception. Enums needs at least one member. :: @@ -266,6 +276,138 @@ to and from all integer types but implicit conversion is not allowed. } } +.. index:: ! function type, ! type; function + +.. _function_types: + +Function Types +-------------- + +Function types are the types of functions. Variables of function type +can be assigned from functions and function parameters of function type +can be used to pass functions to and return functions from function calls. +Function types come in two flavours - *internal* and *external* functions: + +Internal functions can only be used inside the current contract (more specifically, +inside the current code unit, which also includes internal library functions +and inherited functions) because they cannot be executed outside of the +context of the current contract. Calling an internal function is realized +by jumping to its entry label, just like when calling a function of the current +contract internally. + +External functions consist of an address and a function signature and they can +be passed via and returned from external function calls. + +Function types are notated as follows:: + + function (<parameter types>) {internal|external} [constant] [payable] [returns (<return types>)] + +In contrast to the parameter types, the return types cannot be empty - if the +function type should not return anything, the whole ``returns (<return types>)`` +part has to be omitted. + +By default, function types are internal, so the ``internal`` keyword can be +omitted. + +There are two ways to access a function in the current contract: Either directly +by its name, ``f``, or using ``this.f``. The former will result in an internal +function, the latter in an external function. + +If a function type variable is not initialized, calling it will result +in an exception. The same happens if you call a function after using ``delete`` +on it. + +If external function types are used outside of the context of Solidity, +they are treated as the ``function`` type, which encodes the address +followed by the function identifier together in a single ``bytes24`` type. + +Note that public functions of the current contract can be used both as an +internal and as an external function. To use ``f`` as an internal function, +just use ``f``, if you want to use its external form, use ``this.f``. + +Example that shows how to use internal function types:: + + pragma solidity ^0.4.5; + + library ArrayUtils { + // internal functions can be used in internal library functions because + // they will be part of the same code context + function map(uint[] memory self, function (uint) returns (uint) f) + internal + returns (uint[] memory r) + { + r = new uint[](self.length); + for (uint i = 0; i < self.length; i++) { + r[i] = f(self[i]); + } + } + function reduce( + uint[] memory self, + function (uint x, uint y) returns (uint) f + ) + internal + returns (uint r) + { + r = self[0]; + for (uint i = 1; i < self.length; i++) { + r = f(r, self[i]); + } + } + function range(uint length) internal returns (uint[] memory r) { + r = new uint[](length); + for (uint i = 0; i < r.length; i++) { + r[i] = i; + } + } + } + + contract Pyramid { + using ArrayUtils for *; + function pyramid(uint l) returns (uint) { + return ArrayUtils.range(l).map(square).reduce(sum); + } + function square(uint x) internal returns (uint) { + return x * x; + } + function sum(uint x, uint y) internal returns (uint) { + return x + y; + } + } + +Another example that uses external function types:: + + pragma solidity ^0.4.5; + + contract Oracle { + struct Request { + bytes data; + function(bytes memory) external callback; + } + Request[] requests; + event NewRequest(uint); + function query(bytes data, function(bytes memory) external callback) { + requests.push(Request(data, callback)); + NewRequest(requests.length - 1); + } + function reply(uint requestID, bytes response) { + // Here goes the check that the reply comes from a trusted source + requests[requestID].callback(response); + } + } + + contract OracleUser { + Oracle constant oracle = Oracle(0x1234567); // known contract + function buySomething() { + oracle.query("USD", this.oracleResponse); + } + function oracleResponse(bytes response) { + if (msg.sender != address(oracle)) throw; + // Use the data + } + } + +Note that lambda or inline functions are planned but not yet supported. + .. index:: ! type;reference, ! reference type, storage, memory, location, array, struct Reference Types @@ -606,9 +748,9 @@ assigning it to a local variable, as in Mappings ======== -Mapping types are declared as ``mapping _KeyType => _ValueType``, where -``_KeyType`` can be almost any type except for a mapping and ``_ValueType`` -can actually be any type, including 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, an enum and a struct. +``_ValueType`` can actually be any type, including mappings. Mappings can be seen as hashtables which are virtually initialized such that every possible key exists and is mapped to a value whose byte-representation is |