Merge remote-tracking branch 'origin/develop' into release

6 files changed, 150 insertions, 13 deletions

diff --git a/docs/conf.py b/docs/conf.py
index ebc77124..e17d5fd8 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.4'
+version = '0.4.5'
 # The full version, including alpha/beta/rc tags.
-release = '0.4.4-develop'
+release = '0.4.5-develop'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/docs/control-structures.rst b/docs/control-structures.rst
index 597829d3..f57e7936 100644
--- a/docs/control-structures.rst
+++ b/docs/control-structures.rst
@@ -2,14 +2,14 @@
 Expressions and Control Structures
 ##################################
 
-.. index:: if, else, while, for, break, continue, return, switch, goto
+.. 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
 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
@@ -329,9 +329,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 +427,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 +716,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/introduction-to-smart-contracts.rst b/docs/introduction-to-smart-contracts.rst
index eeea85a7..4a3de441 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];
     }
 
diff --git a/docs/solidity-by-example.rst b/docs/solidity-by-example.rst
index 2e53b78c..915cfa76 100644
--- a/docs/solidity-by-example.rst
+++ b/docs/solidity-by-example.rst
@@ -170,6 +170,15 @@ of votes.
                 }
             }
         }
+        
+        // Calls winningProposal() function to get the index
+        // of the winner contained in the proposals array and then
+        // returns the name of the winner
+        function winnerName() constant
+                returns (bytes32 winnerName)
+        {
+            winnerName = proposals[winningProposal()].name;
+        }
     }
 
 Possible Improvements
diff --git a/docs/types.rst b/docs/types.rst
index 9e7d9b4a..b22ad7d4 100644
--- a/docs/types.rst
+++ b/docs/types.rst
@@ -234,10 +234,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 +267,128 @@ 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.
+
+Example that shows how to use internal function types::
+
+    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)
+        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) returns (uint) f
+      )
+        returns (uint r)
+      {
+        r = self[0];
+        for (uint i = 1; i < self.length; i++) {
+          r = f(r, self[i]);
+        }
+      }
+      function range(uint length) 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) return (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::
+
+    contract Oracle {
+      struct Request {
+        bytes data;
+        function(bytes) external callback;
+      }
+      Request[] requests;
+      event NewRequest(uint);
+      function query(bytes data, function(bytes) 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 = 0x1234567; // known contract
+      function buySomething() {
+        oracle.query("USD", oracleResponse);
+      }
+      function oracleResponse(bytes response) {
+        if (msg.sender != 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
diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst
index 3499bc71..dd3d4be8 100644
--- a/docs/units-and-global-variables.rst
+++ b/docs/units-and-global-variables.rst
@@ -50,7 +50,7 @@ namespace and are mainly used to provide information about the blockchain.
 Block and Transaction Properties
 --------------------------------
 
-- ``block.blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks
+- ``block.blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks excluding current
 - ``block.coinbase`` (``address``): current block miner's address
 - ``block.difficulty`` (``uint``): current block difficulty
 - ``block.gaslimit`` (``uint``): current block gaslimit