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

13 files changed, 179 insertions, 248 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 485184f2..4d22c9bd 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.1'
+version = '0.4.3'
 # The full version, including alpha/beta/rc tags.
-release = '0.4.1-develop'
+release = '0.4.3-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 ef29a686..7f8ace44 100644
--- a/docs/contracts.rst
+++ b/docs/contracts.rst
@@ -20,6 +20,9 @@ Contracts can be created "from outside" or from Solidity contracts.
 When a contract is created, its constructor (a function with the same
 name as the contract) is executed once.
 
+A constructor is optional. Only one constructor is allowed and this means
+overloading is not supported.
+
 From ``web3.js``, i.e. the JavaScript
 API, this is done as follows::
 
@@ -136,7 +139,7 @@ This means that cyclic creation dependencies are impossible.
         ) returns (bool ok) {
             // Check some arbitrary condition.
             address tokenAddress = msg.sender;
-            return (sha3(newOwner) & 0xff) == (bytes20(tokenAddress) & 0xff);
+            return (keccak256(newOwner) & 0xff) == (bytes20(tokenAddress) & 0xff);
         }
     }
 
@@ -421,9 +424,9 @@ change by overriding).
 
 .. index:: ! constant
 
-**********
-Constants
-**********
+************************
+Constant State Variables
+************************
 
 State variables can be declared as constant (this is not yet implemented
 for array and struct types and not possible for mapping types).
@@ -442,6 +445,27 @@ for these variables and every occurrence is replaced by their constant value.
 
 The value expression can only contain integer arithmetics.
 
+******************
+Constant Functions
+******************
+
+Functions can be declared constant. These functions promise not to modify the state.
+
+::
+
+    pragma solidity ^0.4.0;
+
+    contract C {
+        function f(uint a, uint b) constant returns (uint) {
+            return a * (b + 42);
+        }
+    }
+
+.. note::
+  Accessor methods are marked constant.
+
+.. warning::
+  The compiler does not enforce yet that a constant method is not modifying state.
 
 .. index:: ! fallback function, function;fallback
 
@@ -544,7 +568,7 @@ to be searched for: It is possible to filter for specific values of
 indexed arguments in the user interface.
 
 If arrays (including ``string`` and ``bytes``) are used as indexed arguments, the
-sha3-hash of it is stored as topic instead.
+Keccak-256 hash of it is stored as topic instead.
 
 The hash of the signature of the event is one of the topics except if you
 declared the event with ``anonymous`` specifier. This means that it is
@@ -622,7 +646,7 @@ as topics. The event call above can be performed in the same way as
     );
 
 where the long hexadecimal number is equal to
-``sha3("Deposit(address,hash256,uint256)")``, the signature of the event.
+``keccak256("Deposit(address,hash256,uint256)")``, the signature of the event.
 
 Additional Resources for Understanding Events
 ==============================================
@@ -976,7 +1000,7 @@ are all compiled as calls (``DELEGATECALL``) to an external
 contract/library. If you use libraries, take care that an
 actual external function call is performed.
 ``msg.sender``, ``msg.value`` and ``this`` will retain their values
-in this call, though (prior to Homestead, ``msg.sender`` and
+in this call, though (prior to Homestead, because of the use of `CALLCODE`, ``msg.sender`` and
 ``msg.value`` changed, though).
 
 The following example shows how to use memory types and
diff --git a/docs/contributing.rst b/docs/contributing.rst
index a316abd6..111fb932 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -15,7 +15,9 @@ In particular, we need help in the following areas:
   <http://ethereum.stackexchange.com/>`_ and the `Solidity Gitter
   <https://gitter.im/ethereum/solidity>`_
 * Fixing and responding to `Solidity's GitHub issues
-  <https://github.com/ethereum/solidity/issues>`_
+  <https://github.com/ethereum/solidity/issues>`_, especially those tagged as
+  `up-for-grabs <https://github.com/ethereum/solidity/issues?q=is%3Aopen+is%3Aissue+label%3Aup-for-grabs>`_ which are
+  meant as introductory issues for external contributors.
 
 How to Report Issues
 ====================
diff --git a/docs/control-structures.rst b/docs/control-structures.rst
index db24d5c3..597829d3 100644
--- a/docs/control-structures.rst
+++ b/docs/control-structures.rst
@@ -7,7 +7,7 @@ Expressions and Control Structures
 Control Structures
 ===================
 
-Most of the control structures from C/JavaScript are available in Solidity
+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
 the usual semantics known from C or JavaScript.
@@ -322,14 +322,16 @@ In the following example, we show how ``throw`` can be used to easily revert an
         }
     }
 
-Currently, there are six situations, where exceptions happen automatically in Solidity:
+Currently, there are situations, where exceptions happen automatically in Solidity:
 
-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.
+1. If you access an array at a too large or negative index (i.e. ``x[i]`` where ``i >= x.length`` or ``i < 0``).
+2. If you access a fixed-length ``bytesN`` at a too large or negative index.
+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.
 
 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.
 
@@ -503,7 +505,7 @@ The opcodes ``pushi`` and ``jumpdest`` cannot be used directly.
 +-------------------------+------+-----------------------------------------------------------------+
 | pc                      |      | current position in code                                        |
 +-------------------------+------+-----------------------------------------------------------------+
-| pop                     | `*`  | remove topmost stack slot                                       |
+| pop(x)                  | `-`  | remove the element pushed by x                                  |
 +-------------------------+------+-----------------------------------------------------------------+
 | dup1 ... dup16          |      | copy ith stack slot to the top (counting from top)              |
 +-------------------------+------+-----------------------------------------------------------------+
@@ -559,9 +561,9 @@ The opcodes ``pushi`` and ``jumpdest`` cannot be used directly.
 | delegatecall(g, a, in,  |      | identical to `callcode` but also keep ``caller``                |
 | insize, out, outsize)   |      | and ``callvalue``                                               |
 +-------------------------+------+-----------------------------------------------------------------+
-| return(p, s)            | `*`  | end execution, return data mem[p..(p+s))                        |
+| return(p, s)            | `-`  | end execution, return data mem[p..(p+s))                        |
 +-------------------------+------+-----------------------------------------------------------------+
-| selfdestruct(a)         | `*`  | end execution, destroy current contract and send funds to a     |
+| selfdestruct(a)         | `-`  | end execution, destroy current contract and send funds to a     |
 +-------------------------+------+-----------------------------------------------------------------+
 | log0(p, s)              | `-`  | log without topics and data mem[p..(p+s))                       |
 +-------------------------+------+-----------------------------------------------------------------+
@@ -783,7 +785,7 @@ Conventions in Solidity
 
 In contrast to EVM assembly, Solidity knows types which are narrower than 256 bits,
 e.g. ``uint24``. In order to make them more efficient, most arithmetic operations just
-treat them as 256 bit numbers and the higher-order bits are only cleaned at the
+treat them as 256-bit numbers and the higher-order bits are only cleaned at the
 point where it is necessary, i.e. just shortly before they are written to memory
 or before comparisons are performed. This means that if you access such a variable
 from within inline assembly, you might have to manually clean the higher order bits
diff --git a/docs/frequently-asked-questions.rst b/docs/frequently-asked-questions.rst
index acc0c106..43fba332 100644
--- a/docs/frequently-asked-questions.rst
+++ b/docs/frequently-asked-questions.rst
@@ -9,33 +9,12 @@ This list was originally compiled by `fivedogit <mailto:fivedogit@gmail.com>`_.
 Basic Questions
 ***************
 
-What is Solidity?
+Example contracts
 =================
 
-Solidity is the DEV-created (i.e. Ethereum Foundation-created),
-Javascript-inspired language that can be used to create smart contracts
-on the Ethereum blockchain. There are other
-languages you can use as well (LLL, Serpent, etc). The main points in
-favour of Solidity is that it is statically typed and offers many
-advanced features like inheritance, libraries, complex
-user-defined types and a bytecode optimizer.
-
-Solidity contracts can be compiled a few different ways (see below) and the
-resulting output can be cut/pasted into a geth console to deploy them to the
-Ethereum blockchain.
-
 There are some `contract examples <https://github.com/fivedogit/solidity-baby-steps/tree/master/contracts/>`_ by fivedogit and
 there should be a `test contract <https://github.com/ethereum/solidity/blob/develop/test/libsolidity/SolidityEndToEndTest.cpp>`_ for every single feature of Solidity.
 
-How do I compile contracts?
-===========================
-
-Probably the fastest way is the `online compiler <https://ethereum.github.io/browser-solidity/>`_.
-
-You can also use the ``solc`` binary which comes with cpp-ethereum to compile
-contracts or an emerging option is to use Mix, the IDE.
-
-
 Create and publish the most basic contract possible
 ===================================================
 
@@ -71,13 +50,6 @@ several blockchain explorers.
 Contracts on the blockchain should have their original source
 code published if they are to be used by third parties.
 
-Does ``selfdestruct()`` free up space in the blockchain?
-========================================================
-
-It removes the contract bytecode and storage from the current block
-into the future, but since the blockchain stores every single block (i.e.
-all history), this will not actually free up space on full/archive nodes.
-
 Create a contract that can be killed and return funds
 =====================================================
 
@@ -113,32 +85,6 @@ Use a non-constant function (req ``sendTransaction``) to increment a variable in
 
 See `value_incrementer.sol <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/20_value_incrementer.sol>`_.
 
-Get contract address in Solidity
-================================
-
-Short answer: The global variable ``this`` is the contract address.
-
-See `basic_info_getter <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/15_basic_info_getter.sol>`_.
-
-Long answer: ``this`` is a variable representing the current contract.
-Its type is the type of the contract. Since any contract type basically inherits from the
-``address`` type, ``this`` is always convertible to ``address`` and in this case contains
-its own address.
-
-What is the difference between a function marked ``constant`` and one that is not?
-==================================================================================
-
-``constant`` functions can perform some action and return a value, but cannot
-change state (this is not yet enforced by the compiler). In other words, a
-constant function cannot save or update any variables within the contract or wider
-blockchain. These functions are called using ``c.someFunction(...)`` from
-geth or any other web3.js environment.
-
-"non-constant" functions (those lacking the ``constant`` specifier) must be called
-with ``c.someMethod.sendTransaction({from:eth.accounts[x], gas: 1000000});``
-That is, because they can change state, they have to have a gas
-payment sent along to get the work done.
-
 Get a contract to return its funds to you (not using ``selfdestruct(...)``).
 ============================================================================
 
@@ -146,52 +92,6 @@ This example demonstrates how to send funds from a contract to an address.
 
 See `endowment_retriever <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/30_endowment_retriever.sol>`_.
 
-What is a ``mapping`` and how do we use them?
-=============================================
-
-A mapping is very similar to a K->V hashmap.
-If you have a state variable of type ``mapping (string -> uint) x;``, then you can
-access the value by ``x["somekeystring"]``.
-
-How can I get the length of a ``mapping``?
-==========================================
-
-Mappings are a rather low-level data structure. It does not store the keys
-and it is not possible to know which or how many values are "set". Actually,
-all values to all possible keys are set by default, they are just
-initialised with the zero value.
-
-In this sense, the attribute ``length`` for a mapping does not really apply.
-
-If you want to have a "sized mapping", you can use the iterable mapping
-(see below) or just a dynamically-sized array of structs.
-
-Are ``mapping``'s iterable?
-===========================
-
-Mappings themselves are not iterable, but you can use a higher-level
-datastructure on top of it, for example the `iterable mapping <https://github.com/ethereum/dapp-bin/blob/master/library/iterable_mapping.sol>`_.
-
-Can I put arrays inside of a ``mapping``? How do I make a ``mapping`` of a ``mapping``?
-=======================================================================================
-
-Mappings are already syntactically similar to arrays as they are, therefore it doesn't make much sense to store an array in them. Rather what you should do is create a mapping of a mapping.
-
-An example of this would be::
-
-    contract C {
-        struct myStruct {
-            uint someNumber;
-            string someString;
-        }
-
-        mapping(uint => mapping(string => myStruct)) myDynamicMapping;
-
-        function storeInMapping() {
-            myDynamicMapping[1]["Foo"] = myStruct(2, "Bar");
-        }
-    }
-
 Can you return an array or a ``string`` from a solidity function call?
 ======================================================================
 
@@ -223,61 +123,6 @@ Example::
         }
     }
 
-What are ``event``'s and why do we need them?
-=============================================
-
-Let us suppose that you need a contract to alert the outside world when
-something happens. The contract can fire an event, which can be listened to
-from web3 (inside geth or a web application). The main advantage of events
-is that they are stored in a special way on the blockchain so that it
-is very easy to search for them.
-
-What are the different function visibilities?
-=============================================
-
-The visibility specifiers do not only change the visibility but also
-the way functions can be called. In general, functions in the
-same contract can also be called internally (which is cheaper
-and allows for memory types to be passed by reference). This
-is done if you just use ``f(1,2)``. If you use ``this.f(1,2)``
-or ``otherContract.f(1,2)``, the function is called externally.
-
-Internal function calls have the advantage that you can use
-all Solidity types as parameters, but you have to stick to the
-simpler ABI types for external calls.
-
-* ``external``: all, only externally
-
-* ``public``: all (this is the default), externally and internally
-
-* ``internal``: only this contract and contracts deriving from it, only internally
-
-* ``private``: only this contract, only internally
-
-
-Do contract constructors have to be publicly visible?
-=====================================================
-
-You can use the visibility specifiers, but they do not yet have any effect.
-The constructor is removed from the contract code once it is deployed,
-
-Can a contract have multiple constructors?
-==========================================
-
-No, a contract can have only one constructor.
-
-More specifically, it can only have one function whose name matches
-that of the constructor.
-
-Having multiple constructors with different number of arguments
-or argument types, as it is possible in other languages
-is not allowed in Solidity.
-
-Is a constructor required?
-==========================
-
-No. If there is no constructor, a generic one without arguments and no actions will be used.
-
 Are timestamps (``now,`` ``block.timestamp``) reliable?
 =======================================================
 
@@ -363,14 +208,6 @@ Examples::
         C c = new C();
     }
 
-What is the ``modifier`` keyword?
-=================================
-
-Modifiers are a way to prepend or append code to a function in order
-to add guards, initialisation or cleanup functionality in a concise way.
-
-For examples, see the `features.sol <https://github.com/ethereum/dapp-bin/blob/master/library/features.sol>`_.
-
 How do structs work?
 ====================
 
@@ -590,12 +427,6 @@ The correct way to do this is the following::
         }
     }
 
-Can a regular (i.e. non-contract) ethereum account be closed permanently like a contract can?
-=============================================================================================
-
-No. Non-contract accounts "exist" as long as the private key is known by
-someone or can be generated in some way.
-
 What is the difference between ``bytes`` and ``byte[]``?
 ========================================================
 
@@ -641,16 +472,6 @@ Use the constructor. Anything inside it will be executed when the contract is fi
 
 See `replicator.sol <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/50_replicator.sol>`_.
 
-Can a contract create another contract?
-=======================================
-
-Yes, see `replicator.sol <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/50_replicator.sol>`_.
-
-Note that the full code of the created contract has to be included in the creator contract.
-This also means that cyclic creations are not possible (because the contract would have
-to contain its own code) - at least not in a general way.
-
-
 How do you create 2-dimensional arrays?
 =======================================
 
@@ -709,10 +530,12 @@ How do I initialize a contract with only a specific amount of wei?
 Currently the approach is a little ugly, but there is little that can be done to improve it.
 In the case of a ``contract A`` calling a new instance of ``contract B``, parentheses have to be used around
 ``new B`` because ``B.value`` would refer to a member of ``B`` called ``value``.
-You will need to make sure that you have both contracts aware of each other's presence.
+You will need to make sure that you have both contracts aware of each other's presence and that ``contract B`` has a ``payable`` constructor.
 In this example::
 
-    contract B {}
+    contract B {
+        function B() payable {}
+    }
 
 
     contract A {
diff --git a/docs/index.rst b/docs/index.rst
index 4cf75282..3b47ce78 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,8 +1,12 @@
 Solidity
 ========
 
-Solidity is a high-level language whose syntax is similar to that of JavaScript
-and it is designed to compile to code for the Ethereum Virtual Machine.
+Solidity is a contract-oriented, high-level language whose syntax is similar to that of JavaScript
+and it is designed to target the Ethereum Virtual Machine.
+
+Solidity is statically typed, supports inheritance, libraries and complex
+user-defines types among other features.
+
 As you will see, it is possible to create contracts for voting,
 crowdfunding, blind auctions, multi-signature wallets and more.
 
@@ -16,7 +20,7 @@ Useful links
 
 * `Ethereum <https://ethereum.org>`_
 
-* `Changelog <https://github.com/ethereum/wiki/wiki/Solidity-Changelog>`_
+* `Changelog <https://github.com/ethereum/solidity/blob/develop/Changelog.md>`_
 
 * `Story Backlog <https://www.pivotaltracker.com/n/projects/1189488>`_
 
diff --git a/docs/installing-solidity.rst b/docs/installing-solidity.rst
index ebb7537b..44ee34f4 100644
--- a/docs/installing-solidity.rst
+++ b/docs/installing-solidity.rst
@@ -9,7 +9,7 @@ Installing Solidity
 Versioning
 ==========
 
-Solidity versions follow `semantic versioning <https://semver.org>` and in addition to
+Solidity versions follow `semantic versioning <https://semver.org>`_ and in addition to
 releases, **nightly development builds** are also made available.  The nightly builds
 are not guaranteed to be working and despite best efforts they might contain undocumented
 and/or broken changes. We recommend to use the latest release. Package installers below
@@ -205,10 +205,11 @@ to semver and the severity of the change. Finally, a release is always made with
 of the current nightly build, but without the ``prerelease`` specifier.
 
 Example:
-- 0) the 0.4.0 release is made
-- 1) nightly build has a version of 0.4.1 from now on
-- 2) non-breaking changes are introduced - no change in version
-- 3) a breaking change is introduced - version is bumped to 0.5.0
-- 4) the 0.5.0 release is made
+
+0. the 0.4.0 release is made
+1. nightly build has a version of 0.4.1 from now on
+2. non-breaking changes are introduced - no change in version
+3. a breaking change is introduced - version is bumped to 0.5.0
+4. the 0.5.0 release is made
 
 This behaviour works well with the version pragma.
diff --git a/docs/introduction-to-smart-contracts.rst b/docs/introduction-to-smart-contracts.rst
index 922056ec..eeea85a7 100644
--- a/docs/introduction-to-smart-contracts.rst
+++ b/docs/introduction-to-smart-contracts.rst
@@ -348,10 +348,12 @@ storage. A contract can neither read nor write to any storage apart
 from its own.
 
 The second memory area is called **memory**, of which a contract obtains
-a freshly cleared instance for each message call. Memory can be
-addressed at byte level, but read and written to in 32 byte (256-bit)
-chunks. Memory is more costly the larger it grows (it scales
-quadratically).
+a freshly cleared instance for each message call. Memory is linear and can be
+addressed at byte level, but reads are limited to a width of 256 bits, while writes
+can be either 8 bits or 256 bits wide. Memory is expanded by a word (256-bit), when
+accessing (either reading or writing) a previously untouched memory word (ie. any offset
+within a word). At the time of expansion, the cost in gas must be paid. Memory is more
+costly the larger it grows (it scales quadratically).
 
 The EVM is not a register machine but a stack machine, so all
 computations are performed on an area called the **stack**. It has a maximum size of
@@ -453,13 +455,19 @@ receives the address of the new contract on the stack.
 
 .. index:: selfdestruct
 
-``selfdestruct``
-================
+Self-destruct
+=============
 
 The only possibility that code is removed from the blockchain is
 when a contract at that address performs the ``selfdestruct`` operation.
 The remaining Ether stored at that address is sent to a designated
-target and then the storage and code is removed.
+target and then the storage and code is removed from the state.
+
+.. warning:: Even if a contract's code does not contain a call to ``selfdestruct``,
+  it can still perform that operation using ``delegatecall`` or ``callcode``.
+
+.. note:: The pruning of old contracts may or may not be implemented by Ethereum
+  clients. Additionally, archive nodes could choose to keep the contract storage
+  and code indefinitely.
 
-Note that even if a contract's code does not contain a call to ``selfdestruct``,
-it can still perform that operation using ``delegatecall`` or ``callcode``.
+.. note:: Currently **external accounts** cannot be removed from the state.
diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst
index 7d4cedb6..0b3eed38 100644
--- a/docs/miscellaneous.rst
+++ b/docs/miscellaneous.rst
@@ -34,17 +34,17 @@ Statically-sized variables (everything except mapping and dynamically-sized arra
 
 The elements of structs and arrays are stored after each other, just as if they were given explicitly.
 
-Due to their unpredictable size, mapping and dynamically-sized array types use a ``sha3``
+Due to their unpredictable size, mapping and dynamically-sized array types use a Keccak-256 hash
 computation to find the starting position of the value or the array data. These starting positions are always full stack slots.
 
 The mapping or the dynamic array itself
 occupies an (unfilled) slot in storage at some position ``p`` according to the above rule (or by
 recursively applying this rule for mappings to mappings or arrays of arrays). For a dynamic array, this slot stores the number of elements in the array (byte arrays and strings are an exception here, see below). For a mapping, the slot is unused (but it is needed so that two equal mappings after each other will use a different hash distribution).
-Array data is located at ``sha3(p)`` and the value corresponding to a mapping key
-``k`` is located at ``sha3(k . p)`` where ``.`` is concatenation. If the value is again a
-non-elementary type, the positions are found by adding an offset of ``sha3(k . p)``.
+Array data is located at ``keccak256(p)`` and the value corresponding to a mapping key
+``k`` is located at ``keccak256(k . p)`` where ``.`` is concatenation. If the value is again a
+non-elementary type, the positions are found by adding an offset of ``keccak256(k . p)``.
 
-``bytes`` and ``string`` store their data in the same slot where also the length is stored if they are short. In particular: If the data is at most ``31`` bytes long, it is stored in the higher-order bytes (left aligned) and the lowest-order byte stores ``length * 2``. If it is longer, the main slot stores ``length * 2 + 1`` and the data is stored as usual in ``sha3(slot)``.
+``bytes`` and ``string`` store their data in the same slot where also the length is stored if they are short. In particular: If the data is at most ``31`` bytes long, it is stored in the higher-order bytes (left aligned) and the lowest-order byte stores ``length * 2``. If it is longer, the main slot stores ``length * 2 + 1`` and the data is stored as usual in ``keccak256(slot)``.
 
 So for the following contract snippet::
 
@@ -54,7 +54,25 @@ So for the following contract snippet::
       mapping(uint => mapping(uint => s)) data;
     }
 
-The position of ``data[4][9].b`` is at ``sha3(uint256(9) . sha3(uint256(4) . uint256(1))) + 1``.
+The position of ``data[4][9].b`` is at ``keccak256(uint256(9) . keccak256(uint256(4) . uint256(1))) + 1``.
+
+****************
+Layout in Memory
+****************
+
+Solidity reserves three 256-bit slots:
+
+-  0 - 64: scratch space for hashing methods
+- 64 - 96: currently allocated memory size (aka. free memory pointer)
+
+Scratch space can be used between statements (ie. within inline assembly).
+
+Solidity always places new objects at the free memory pointer and memory is never freed (this might change in the future).
+
+.. warning::
+  There are some operations in Solidity that need a temporary memory area larger than 64 bytes and therefore will not fit into the scratch space. They will be placed where the free memory points to, but given their short lifecycle, the pointer is not updated. The memory may or may not be zeroed out. Because of this, one shouldn't expect the free memory to be zeroed out.
+
+.. index: memory layout
 
 *****************
 Esoteric Features
@@ -281,7 +299,7 @@ The following is the order of precedence for operators, listed in order of evalu
 | *16*       | Comma operator                      | ``,``                                      |
 +------------+-------------------------------------+--------------------------------------------+
 
-.. index:: block, coinbase, difficulty, number, block;number, timestamp, block;timestamp, msg, data, gas, sender, value, now, gas price, origin, sha3, ripemd160, sha256, ecrecover, addmod, mulmod, cryptography, this, super, selfdestruct, balance, send
+.. index:: block, coinbase, difficulty, number, block;number, timestamp, block;timestamp, msg, data, gas, sender, value, now, gas price, origin, keccak256, ripemd160, sha256, ecrecover, addmod, mulmod, cryptography, this, super, selfdestruct, balance, send
 
 Global Variables
 ================
@@ -299,7 +317,8 @@ Global Variables
 - ``now`` (``uint``): current block timestamp (alias for ``block.timestamp``)
 - ``tx.gasprice`` (``uint``): gas price of the transaction
 - ``tx.origin`` (``address``): sender of the transaction (full call chain)
-- ``sha3(...) returns (bytes32)``: compute the Ethereum-SHA-3 (KECCAK-256) hash of the (tightly packed) arguments
+- ``keccak256(...) returns (bytes32)``: compute the Ethereum-SHA-3 (Keccak-256) hash of the (tightly packed) arguments
+- ``sha3(...) returns (bytes32)``: an alias to `keccak256()`
 - ``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, return zero on error
@@ -338,3 +357,16 @@ Modifiers
 - ``anonymous`` for events: Does not store event signature as topic.
 - ``indexed`` for event parameters: Stores the parameter as topic.
 - ``payable`` for functions: Allows them to receive Ether together with a call.
+
+Reserved Keywords
+=================
+
+These keywords are reserved in Solidity. They might become part of the syntax in the future:
+
+``abstract``, ``after``, ``case``, ``catch``, ``final``, ``in``, ``inline``, ``interface``, ``let``, ``match``,
+``of``, ``pure``, ``relocatable``, ``static``, ``switch``, ``try``, ``type``, ``typeof``, ``view``.
+
+Language Grammar
+================
+
+The entire language grammar is `available here <https://github.com/ethereum/solidity/blob/release/libsolidity/grammar.txt>`_.
diff --git a/docs/security-considerations.rst b/docs/security-considerations.rst
index a2f4ec4c..77e1bf08 100644
--- a/docs/security-considerations.rst
+++ b/docs/security-considerations.rst
@@ -123,7 +123,7 @@ Sending and Receiving Ether
   ``addr.call.value(x)()``. This is essentially the same as ``addr.send(x)``,
   only that it forwards all remaining gas and opens up the ability for the
   recipient to perform more expensive actions. This might include calling back
-  into the sending contract or other state changes you might not have though of.
+  into the sending contract or other state changes you might not have thought of.
   So it allows for great flexibility for honest users but also for malicious actors.
 
 - If you want to send Ether using ``address.send``, there are certain details to be aware of:
@@ -207,7 +207,7 @@ Minor Details
   You can craft transactions that call a function ``f(uint8 x)`` with a raw byte argument
   of ``0xff000001`` and with ``0x00000001``. Both are fed to the contract and both will
   look like the number ``1`` as far as ``x`` is concerned, but ``msg.data`` will
-  be different, so if you use ``sha3(msg.data)`` for anything, you will get different results.
+  be different, so if you use ``keccak256(msg.data)`` for anything, you will get different results.
 
 ***************
 Recommendations
diff --git a/docs/solidity-by-example.rst b/docs/solidity-by-example.rst
index 9d3dd6f6..2e53b78c 100644
--- a/docs/solidity-by-example.rst
+++ b/docs/solidity-by-example.rst
@@ -415,7 +415,7 @@ high or low invalid bids.
             revealEnd = biddingEnd + _revealTime;
         }
 
-        /// Place a blinded bid with `_blindedBid` = sha3(value,
+        /// Place a blinded bid with `_blindedBid` = keccak256(value,
         /// fake, secret).
         /// The sent ether is only refunded if the bid is correctly
         /// revealed in the revealing phase. The bid is valid if the
@@ -459,7 +459,7 @@ high or low invalid bids.
                 var bid = bids[msg.sender][i];
                 var (value, fake, secret) =
                         (_values[i], _fake[i], _secret[i]);
-                if (bid.blindedBid != sha3(value, fake, secret)) {
+                if (bid.blindedBid != keccak256(value, fake, secret)) {
                     // Bid was not actually revealed.
                     // Do not refund deposit.
                     continue;
diff --git a/docs/types.rst b/docs/types.rst
index 9d7ebec9..9e7d9b4a 100644
--- a/docs/types.rst
+++ b/docs/types.rst
@@ -106,7 +106,7 @@ the function ``call`` is provided which takes an arbitrary number of arguments o
 
     address nameReg = 0x72ba7d8e73fe8eb666ea66babc8116a41bfb10e2;
     nameReg.call("register", "MyName");
-    nameReg.call(bytes4(sha3("fun(uint256)")), a);
+    nameReg.call(bytes4(keccak256("fun(uint256)")), a);
 
 ``call`` returns a boolean indicating whether the invoked function terminated (``true``) or caused an EVM exception (``false``). It is not possible to access the actual data returned (for this we would need to know the encoding and size in advance).
 
@@ -186,7 +186,7 @@ the type ``ufixed0x256`` because ``1/3`` is not finitely representable in binary
 approximated.
 
 Any operator that can be applied to integers can also be applied to literal expressions as
-long as the operators are integers. If any of the two is fractional, bit operations are disallowed
+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).
 
@@ -371,6 +371,9 @@ So ``bytes`` should always be preferred over ``byte[]`` because it is cheaper.
     that you are accessing the low-level bytes of the UTF-8 representation,
     and not the individual characters!
 
+It is possible to mark arrays ``public`` and have Solidity create an accessor.
+The numeric index will become a required parameter for the accessor.
+
 .. index:: ! array;allocating, new
 
 Allocating Memory Arrays
@@ -610,13 +613,43 @@ 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
 all zeros: a type's :ref:`default value <default-value>`. The similarity ends here, though: The key data is not actually stored
-in a mapping, only its ``sha3`` hash used to look up the value.
+in a mapping, only its ``keccak256`` hash used to look up the value.
 
 Because of this, mappings do not have a length or a concept of a key or value being "set".
 
 Mappings are only allowed for state variables (or as storage reference types
 in internal functions).
 
+It is possible to mark mappings ``public`` and have Solidity create an accessor.
+The ``_KeyType`` will become a required parameter for the accessor and it will
+return ``_ValueType``.
+
+The ``_ValueType`` can be a mapping too. The accessor will have one parameter
+for each ``_KeyType``, recursively.
+
+::
+
+    pragma solidity ^0.4.0;
+
+    contract MappingExample {
+        mapping(address => uint) public balances;
+
+        function update(uint newBalance) {
+            balances[msg.sender] = newBalance;
+        }
+    }
+
+    contract MappingUser {
+        function f() returns (uint) {
+            return MappingExample(<address>).balances(this);
+        }
+    }
+
+
+.. note::
+  Mappings are not iterable, but it is possible to implement a data structure on top of them.
+  For an example, see `iterable mapping <https://github.com/ethereum/dapp-bin/blob/master/library/iterable_mapping.sol>`_.
+
 .. index:: assignment, ! delete, lvalue
 
 Operators Involving LValues
diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst
index 9ee334cf..3499bc71 100644
--- a/docs/units-and-global-variables.rst
+++ b/docs/units-and-global-variables.rst
@@ -79,7 +79,7 @@ Block and Transaction Properties
     You can only access the hashes of the most recent 256 blocks, all other
     values will be zero.
 
-.. index:: sha3, ripemd160, sha256, ecrecover, addmod, mulmod, cryptography, this, super, selfdestruct, balance, send
+.. index:: keccak256, ripemd160, sha256, ecrecover, addmod, mulmod, cryptography, this, super, selfdestruct, balance, send
 
 Mathematical and Cryptographic Functions
 ----------------------------------------
@@ -88,8 +88,10 @@ Mathematical and Cryptographic Functions
     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``.
+``keccak256(...) returns (bytes32)``:
+    compute the Ethereum-SHA-3 (Keccak-256) hash of the (tightly packed) arguments
 ``sha3(...) returns (bytes32)``:
-    compute the Ethereum-SHA-3 (KECCAK-256) hash of the (tightly packed) arguments
+    alias to `keccak256()`
 ``sha256(...) returns (bytes32)``:
     compute the SHA-256 hash of the (tightly packed) arguments
 ``ripemd160(...) returns (bytes20)``:
@@ -100,18 +102,18 @@ Mathematical and Cryptographic Functions
 In the above, "tightly packed" means that the arguments are concatenated without padding.
 This means that the following are all identical::
 
-    sha3("ab", "c")
-    sha3("abc")
-    sha3(0x616263)
-    sha3(6382179)
-    sha3(97, 98, 99)
+    keccak256("ab", "c")
+    keccak256("abc")
+    keccak256(0x616263)
+    keccak256(6382179)
+    keccak256(97, 98, 99)
 
-If padding is needed, explicit type conversions can be used: ``sha3("\x00\x12")`` is the
-same as ``sha3(uint16(0x12))``.
+If padding is needed, explicit type conversions can be used: ``keccak256("\x00\x12")`` is the
+same as ``keccak256(uint16(0x12))``.
 
 Note that constants will be packed using the minimum number of bytes required to store them.
-This means that, for example, ``sha3(0) == sha3(uint8(0))`` and
-``sha3(0x12345678) == sha3(uint32(0x12345678))``.
+This means that, for example, ``keccak256(0) == keccak256(uint8(0))`` and
+``keccak256(0x12345678) == keccak256(uint32(0x12345678))``.
 
 It might be that you run into Out-of-Gas for ``sha256``, ``ripemd160`` or ``ecrecover`` on a *private blockchain*. The reason for this is that those are implemented as so-called precompiled contracts and these contracts only really exist after they received the first message (although their contract code is hardcoded). Messages to non-existing contracts are more expensive and thus the execution runs into an Out-of-Gas error. A workaround for this problem is to first send e.g. 1 Wei to each of the contracts before you use them in your actual contracts. This is not an issue on the official or test net.