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 | 66 | ||||
| -rw-r--r-- | docs/installing-solidity.rst | 15 | ||||
| -rw-r--r-- | docs/introduction-to-smart-contracts.rst | 2 | ||||
| -rw-r--r-- | docs/miscellaneous.rst | 11 | ||||
| -rw-r--r-- | docs/types.rst | 53 |
7 files changed, 132 insertions, 25 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 7e1c690d..974a093f 100644 --- a/docs/control-structures.rst +++ b/docs/control-structures.rst @@ -2,12 +2,62 @@ Expressions and Control Structures ################################## +.. 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``, ``do``, ``for``, ``break``, ``continue``, ``return``, ``? :``, with the usual semantics known from C or JavaScript. @@ -16,7 +66,17 @@ Parentheses can *not* be omitted for conditionals, but curly brances can be omit 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 @@ -427,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`` 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 4a3de441..aee1e03b 100644 --- a/docs/introduction-to-smart-contracts.rst +++ b/docs/introduction-to-smart-contracts.rst @@ -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 b22ad7d4..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. @@ -312,12 +321,19 @@ 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); @@ -327,8 +343,9 @@ Example that shows how to use internal function types:: } function reduce( uint[] memory self, - function (uint) returns (uint) f + function (uint x, uint y) returns (uint) f ) + internal returns (uint r) { r = self[0]; @@ -336,7 +353,7 @@ Example that shows how to use internal function types:: r = f(r, self[i]); } } - function range(uint length) returns (uint[] memory r) { + function range(uint length) internal returns (uint[] memory r) { r = new uint[](length); for (uint i = 0; i < r.length; i++) { r[i] = i; @@ -346,7 +363,7 @@ Example that shows how to use internal function types:: contract Pyramid { using ArrayUtils for *; - function pyramid(uint l) return (uint) { + function pyramid(uint l) returns (uint) { return ArrayUtils.range(l).map(square).reduce(sum); } function square(uint x) internal returns (uint) { @@ -359,14 +376,16 @@ Example that shows how to use internal function types:: Another example that uses external function types:: + pragma solidity ^0.4.5; + contract Oracle { struct Request { bytes data; - function(bytes) external callback; + function(bytes memory) external callback; } Request[] requests; event NewRequest(uint); - function query(bytes data, function(bytes) external callback) { + function query(bytes data, function(bytes memory) external callback) { requests.push(Request(data, callback)); NewRequest(requests.length - 1); } @@ -377,12 +396,12 @@ Another example that uses external function types:: } contract OracleUser { - Oracle constant oracle = 0x1234567; // known contract + Oracle constant oracle = Oracle(0x1234567); // known contract function buySomething() { - oracle.query("USD", oracleResponse); + oracle.query("USD", this.oracleResponse); } function oracleResponse(bytes response) { - if (msg.sender != oracle) throw; + if (msg.sender != address(oracle)) throw; // Use the data } } @@ -729,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 |