aboutsummaryrefslogtreecommitdiffstats
path: root/docs/contracts
diff options
context:
space:
mode:
Diffstat (limited to 'docs/contracts')
-rw-r--r--docs/contracts/abstract-contracts.rst43
-rw-r--r--docs/contracts/events.rst161
-rw-r--r--docs/contracts/inheritance.rst299
-rw-r--r--docs/contracts/interfaces.rst36
-rw-r--r--docs/contracts/libraries.rst230
-rw-r--r--docs/contracts/using-for.rst119
6 files changed, 888 insertions, 0 deletions
diff --git a/docs/contracts/abstract-contracts.rst b/docs/contracts/abstract-contracts.rst
new file mode 100644
index 00000000..87340733
--- /dev/null
+++ b/docs/contracts/abstract-contracts.rst
@@ -0,0 +1,43 @@
+.. index:: ! contract;abstract, ! abstract contract
+
+.. _abstract-contract:
+
+******************
+Abstract Contracts
+******************
+
+Contracts are marked as abstract when at least one of their functions lacks an implementation as in the following example (note that the function declaration header is terminated by ``;``)::
+
+ pragma solidity >=0.4.0 <0.6.0;
+
+ contract Feline {
+ function utterance() public returns (bytes32);
+ }
+
+Such contracts cannot be compiled (even if they contain implemented functions alongside non-implemented functions), but they can be used as base contracts::
+
+ pragma solidity >=0.4.0 <0.6.0;
+
+ contract Feline {
+ function utterance() public returns (bytes32);
+ }
+
+ contract Cat is Feline {
+ function utterance() public returns (bytes32) { return "miaow"; }
+ }
+
+If a contract inherits from an abstract contract and does not implement all non-implemented functions by overriding, it will itself be abstract.
+
+Note that a function without implementation is different from a :ref:`Function Type <function_types>` even though their syntax looks very similar.
+
+Example of function without implementation (a function declaration)::
+
+ function foo(address) external returns (address);
+
+Example of a Function Type (a variable declaration, where the variable is of type ``function``)::
+
+ function(address) external returns (address) foo;
+
+Abstract contracts decouple the definition of a contract from its implementation providing better extensibility and self-documentation and
+facilitating patterns like the `Template method <https://en.wikipedia.org/wiki/Template_method_pattern>`_ and removing code duplication.
+Abstract contracts are useful in the same way that defining methods in an interface is useful. It is a way for the designer of the abstract contract to say "any child of mine must implement this method".
diff --git a/docs/contracts/events.rst b/docs/contracts/events.rst
new file mode 100644
index 00000000..ecb0a87f
--- /dev/null
+++ b/docs/contracts/events.rst
@@ -0,0 +1,161 @@
+.. index:: ! event
+
+.. _events:
+
+******
+Events
+******
+
+Solidity events give an abstraction on top of the EVM's logging functionality.
+Applications can subscribe and listen to these events through the RPC interface of an Ethereum client.
+
+Events are inheritable members of contracts. When you call them, they cause the
+arguments to be stored in the transaction's log - a special data structure
+in the blockchain. These logs are associated with the address of the contract,
+are incorporated into the blockchain, and stay there as long as a block is
+accessible (forever as of the Frontier and Homestead releases, but this might
+change with Serenity). The Log and its event data is not accessible from within
+contracts (not even from the contract that created them).
+
+It is possible to request a simple payment verification (SPV) for logs, so if
+an external entity supplies a contract with such a verification, it can check
+that the log actually exists inside the blockchain. You have to supply block headers
+because the contract can only see the last 256 block hashes.
+
+You can add the attribute ``indexed`` to up to three parameters which adds them
+to a special data structure known as :ref:`"topics" <abi_events>` instead of
+the data part of the log. If you use arrays (including ``string`` and ``bytes``)
+as indexed arguments, its Keccak-256 hash is stored as a topic instead, this is
+because a topic can only hold a single word (32 bytes).
+
+All parameters without the ``indexed`` attribute are :ref:`ABI-encoded <ABI>`
+into the data part of the log.
+
+Topics allow you to search for events, for example when filtering a sequence of
+blocks for certain events. You can also filter events by the address of the
+contract that emitted the event.
+
+For example, the code below uses the web3.js ``subscribe("logs")``
+`method <https://web3js.readthedocs.io/en/1.0/web3-eth-subscribe.html#subscribe-logs>`_ to filter
+logs that match a topic with a certain address value:
+
+.. code-block:: javascript
+
+ var options = {
+ fromBlock: 0,
+ address: web3.eth.defaultAccount,
+ topics: ["0x0000000000000000000000000000000000000000000000000000000000000000", null, null]
+ };
+ web3.eth.subscribe('logs', options, function (error, result) {
+ if (!error)
+ console.log(result);
+ })
+ .on("data", function (log) {
+ console.log(log);
+ })
+ .on("changed", function (log) {
+ });
+
+
+The hash of the signature of the event is one of the topics, except if you
+declared the event with the ``anonymous`` specifier. This means that it is
+not possible to filter for specific anonymous events by name.
+
+::
+
+ pragma solidity >=0.4.21 <0.6.0;
+
+ contract ClientReceipt {
+ event Deposit(
+ address indexed _from,
+ bytes32 indexed _id,
+ uint _value
+ );
+
+ function deposit(bytes32 _id) public payable {
+ // Events are emitted using `emit`, followed by
+ // the name of the event and the arguments
+ // (if any) in parentheses. Any such invocation
+ // (even deeply nested) can be detected from
+ // the JavaScript API by filtering for `Deposit`.
+ emit Deposit(msg.sender, _id, msg.value);
+ }
+ }
+
+The use in the JavaScript API is as follows:
+
+::
+
+ var abi = /* abi as generated by the compiler */;
+ var ClientReceipt = web3.eth.contract(abi);
+ var clientReceipt = ClientReceipt.at("0x1234...ab67" /* address */);
+
+ var event = clientReceipt.Deposit();
+
+ // watch for changes
+ event.watch(function(error, result){
+ // result contains non-indexed arguments and topics
+ // given to the `Deposit` call.
+ if (!error)
+ console.log(result);
+ });
+
+
+ // Or pass a callback to start watching immediately
+ var event = clientReceipt.Deposit(function(error, result) {
+ if (!error)
+ console.log(result);
+ });
+
+The output of the above looks like the following (trimmed):
+
+.. code-block:: json
+
+ {
+ "returnValues": {
+ "_from": "0x1111…FFFFCCCC",
+ "_id": "0x50…sd5adb20",
+ "_value": "0x420042"
+ },
+ "raw": {
+ "data": "0x7f…91385",
+ "topics": ["0xfd4…b4ead7", "0x7f…1a91385"]
+ }
+ }
+
+.. index:: ! log
+
+Low-Level Interface to Logs
+===========================
+
+It is also possible to access the low-level interface to the logging
+mechanism via the functions ``log0``, ``log1``, ``log2``, ``log3`` and ``log4``.
+``logi`` takes ``i + 1`` parameter of type ``bytes32``, where the first
+argument will be used for the data part of the log and the others
+as topics. The event call above can be performed in the same way as
+
+::
+
+ pragma solidity >=0.4.10 <0.6.0;
+
+ contract C {
+ function f() public payable {
+ uint256 _id = 0x420042;
+ log3(
+ bytes32(msg.value),
+ bytes32(0x50cb9fe53daa9737b786ab3646f04d0150dc50ef4e75f59509d83667ad5adb20),
+ bytes32(uint256(msg.sender)),
+ bytes32(_id)
+ );
+ }
+ }
+
+where the long hexadecimal number is equal to
+``keccak256("Deposit(address,bytes32,uint256)")``, the signature of the event.
+
+Additional Resources for Understanding Events
+==============================================
+
+- `Javascript documentation <https://github.com/ethereum/wiki/wiki/JavaScript-API#contract-events>`_
+- `Example usage of events <https://github.com/debris/smart-exchange/blob/master/lib/contracts/SmartExchange.sol>`_
+- `How to access them in js <https://github.com/debris/smart-exchange/blob/master/lib/exchange_transactions.js>`_
diff --git a/docs/contracts/inheritance.rst b/docs/contracts/inheritance.rst
new file mode 100644
index 00000000..2e94c2f9
--- /dev/null
+++ b/docs/contracts/inheritance.rst
@@ -0,0 +1,299 @@
+.. index:: ! inheritance, ! base class, ! contract;base, ! deriving
+
+***********
+Inheritance
+***********
+
+Solidity supports multiple inheritance including polymorphism.
+
+All function calls are virtual, which means that the most derived function
+is called, except when the contract name is explicitly given or the
+``super`` keyword is used.
+
+When a contract inherits from other contracts, only a single
+contract is created on the blockchain, and the code from all the base contracts
+is compiled into the created contract.
+
+The general inheritance system is very similar to
+`Python's <https://docs.python.org/3/tutorial/classes.html#inheritance>`_,
+especially concerning multiple inheritance, but there are also
+some :ref:`differences <multi-inheritance>`.
+
+Details are given in the following example.
+
+::
+
+ pragma solidity ^0.5.0;
+
+ contract owned {
+ constructor() public { owner = msg.sender; }
+ address payable owner;
+ }
+
+ // Use `is` to derive from another contract. Derived
+ // contracts can access all non-private members including
+ // internal functions and state variables. These cannot be
+ // accessed externally via `this`, though.
+ contract mortal is owned {
+ function kill() public {
+ if (msg.sender == owner) selfdestruct(owner);
+ }
+ }
+
+ // These abstract contracts are only provided to make the
+ // interface known to the compiler. Note the function
+ // without body. If a contract does not implement all
+ // functions it can only be used as an interface.
+ contract Config {
+ function lookup(uint id) public returns (address adr);
+ }
+
+ contract NameReg {
+ function register(bytes32 name) public;
+ function unregister() public;
+ }
+
+ // Multiple inheritance is possible. Note that `owned` is
+ // also a base class of `mortal`, yet there is only a single
+ // instance of `owned` (as for virtual inheritance in C++).
+ contract named is owned, mortal {
+ constructor(bytes32 name) public {
+ Config config = Config(0xD5f9D8D94886E70b06E474c3fB14Fd43E2f23970);
+ NameReg(config.lookup(1)).register(name);
+ }
+
+ // 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() public {
+ if (msg.sender == owner) {
+ Config config = Config(0xD5f9D8D94886E70b06E474c3fB14Fd43E2f23970);
+ NameReg(config.lookup(1)).unregister();
+ // It is still possible to call a specific
+ // overridden function.
+ mortal.kill();
+ }
+ }
+ }
+
+ // If a constructor takes an argument, it needs to be
+ // provided in the header (or modifier-invocation-style at
+ // the constructor of the derived contract (see below)).
+ contract PriceFeed is owned, mortal, named("GoldFeed") {
+ function updateInfo(uint newInfo) public {
+ if (msg.sender == owner) info = newInfo;
+ }
+
+ function get() public view returns(uint r) { return info; }
+
+ uint info;
+ }
+
+Note that above, we call ``mortal.kill()`` to "forward" the
+destruction request. The way this is done is problematic, as
+seen in the following example::
+
+ pragma solidity >=0.4.22 <0.6.0;
+
+ contract owned {
+ constructor() public { owner = msg.sender; }
+ address payable owner;
+ }
+
+ contract mortal is owned {
+ function kill() public {
+ if (msg.sender == owner) selfdestruct(owner);
+ }
+ }
+
+ contract Base1 is mortal {
+ function kill() public { /* do cleanup 1 */ mortal.kill(); }
+ }
+
+ contract Base2 is mortal {
+ function kill() public { /* do cleanup 2 */ mortal.kill(); }
+ }
+
+ contract Final is Base1, Base2 {
+ }
+
+A call to ``Final.kill()`` will call ``Base2.kill`` as the most
+derived override, but this function will bypass
+``Base1.kill``, basically because it does not even know about
+``Base1``. The way around this is to use ``super``::
+
+ pragma solidity >=0.4.22 <0.6.0;
+
+ contract owned {
+ constructor() public { owner = msg.sender; }
+ address payable owner;
+ }
+
+ contract mortal is owned {
+ function kill() public {
+ if (msg.sender == owner) selfdestruct(owner);
+ }
+ }
+
+ contract Base1 is mortal {
+ function kill() public { /* do cleanup 1 */ super.kill(); }
+ }
+
+
+ contract Base2 is mortal {
+ function kill() public { /* do cleanup 2 */ super.kill(); }
+ }
+
+ contract Final is Base1, Base2 {
+ }
+
+If ``Base2`` calls a function of ``super``, it does not simply
+call this function on one of its base contracts. Rather, it
+calls this function on the next base contract in the final
+inheritance graph, so it will call ``Base1.kill()`` (note that
+the final inheritance sequence is -- starting with the most
+derived contract: Final, Base2, Base1, mortal, owned).
+The actual function that is called when using super is
+not known in the context of the class where it is used,
+although its type is known. This is similar for ordinary
+virtual method lookup.
+
+.. index:: ! constructor
+
+.. _constructor:
+
+Constructors
+============
+
+A constructor is an optional function declared with the ``constructor`` keyword
+which is executed upon contract creation, and where you can run contract
+initialisation code.
+
+Before the constructor code is executed, state variables are initialised to
+their specified value if you initialise them inline, or zero if you do not.
+
+After the constructor has run, the final code of the contract is deployed
+to the blockchain. The deployment of
+the code costs additional gas linear to the length of the code.
+This code includes all functions that are part of the public interface
+and all functions that are reachable from there through function calls.
+It does not include the constructor code or internal functions that are
+only called from the constructor.
+
+Constructor functions can be either ``public`` or ``internal``. If there is no
+constructor, the contract will assume the default constructor, which is
+equivalent to ``constructor() public {}``. For example:
+
+::
+
+ pragma solidity ^0.5.0;
+
+ contract A {
+ uint public a;
+
+ constructor(uint _a) internal {
+ a = _a;
+ }
+ }
+
+ contract B is A(1) {
+ constructor() public {}
+ }
+
+A constructor set as ``internal`` causes the contract to be marked as :ref:`abstract <abstract-contract>`.
+
+.. warning ::
+ Prior to version 0.4.22, constructors were defined as functions with the same name as the contract.
+ This syntax was deprecated and is not allowed anymore in version 0.5.0.
+
+
+.. index:: ! base;constructor
+
+Arguments for Base Constructors
+===============================
+
+The constructors of all the base contracts will be called following the
+linearization rules explained below. If the base constructors have arguments,
+derived contracts need to specify all of them. This can be done in two ways::
+
+ pragma solidity >=0.4.22 <0.6.0;
+
+ contract Base {
+ uint x;
+ constructor(uint _x) public { x = _x; }
+ }
+
+ // Either directly specify in the inheritance list...
+ contract Derived1 is Base(7) {
+ constructor() public {}
+ }
+
+ // or through a "modifier" of the derived constructor.
+ contract Derived2 is Base {
+ constructor(uint _y) Base(_y * _y) public {}
+ }
+
+One way is directly in the inheritance list (``is Base(7)``). The other is in
+the way a modifier is invoked as part of
+the derived constructor (``Base(_y * _y)``). The first way to
+do it is more convenient if the constructor argument is a
+constant and defines the behaviour of the contract or
+describes it. The second way has to be used if the
+constructor arguments of the base depend on those of the
+derived contract. Arguments have to be given either in the
+inheritance list or in modifier-style in the derived constructor.
+Specifying arguments in both places is an error.
+
+If a derived contract does not specify the arguments to all of its base
+contracts' constructors, it will be abstract.
+
+.. index:: ! inheritance;multiple, ! linearization, ! C3 linearization
+
+.. _multi-inheritance:
+
+Multiple Inheritance and Linearization
+======================================
+
+Languages that allow multiple inheritance have to deal with
+several problems. One is the `Diamond Problem <https://en.wikipedia.org/wiki/Multiple_inheritance#The_diamond_problem>`_.
+Solidity is similar to Python in that it uses "`C3 Linearization <https://en.wikipedia.org/wiki/C3_linearization>`_"
+to force a specific order in the directed acyclic graph (DAG) of base classes. This
+results in the desirable property of monotonicity but
+disallows some inheritance graphs. Especially, the order in
+which the base classes are given in the ``is`` directive is
+important: You have to list the direct base contracts
+in the order from "most base-like" to "most derived".
+Note that this order is the reverse of the one used in Python.
+
+Another simplifying way to explain this is that when a function is called that
+is defined multiple times in different contracts, the given bases
+are searched from right to left (left to right in Python) in a depth-first manner,
+stopping at the first match. If a base contract has already been searched, it is skipped.
+
+In the following code, Solidity will give the
+error "Linearization of inheritance graph impossible".
+
+::
+
+ pragma solidity >=0.4.0 <0.6.0;
+
+ contract X {}
+ contract A is X {}
+ // This will not compile
+ contract C is A, X {}
+
+The reason for this is that ``C`` requests ``X`` to override ``A``
+(by specifying ``A, X`` in this order), but ``A`` itself
+requests to override ``X``, which is a contradiction that
+cannot be resolved.
+
+
+
+Inheriting Different Kinds of Members of the Same Name
+======================================================
+
+When the inheritance results in a contract with a function and a modifier of the same name, it is considered as an error.
+This error is produced also by an event and a modifier of the same name, and a function and an event of the same name.
+As an exception, a state variable getter can override a public function.
diff --git a/docs/contracts/interfaces.rst b/docs/contracts/interfaces.rst
new file mode 100644
index 00000000..b551b518
--- /dev/null
+++ b/docs/contracts/interfaces.rst
@@ -0,0 +1,36 @@
+.. index:: ! contract;interface, ! interface contract
+
+.. _interfaces:
+
+**********
+Interfaces
+**********
+
+Interfaces are similar to abstract contracts, but they cannot have any functions implemented. There are further restrictions:
+
+- They cannot inherit other contracts or interfaces.
+- All declared functions must be external.
+- They cannot declare a constructor.
+- They cannot declare state variables.
+
+Some of these restrictions might be lifted in the future.
+
+Interfaces are basically limited to what the Contract ABI can represent, and the conversion between the ABI and
+an interface should be possible without any information loss.
+
+Interfaces are denoted by their own keyword:
+
+::
+
+ pragma solidity ^0.5.0;
+
+ interface Token {
+ enum TokenType { Fungible, NonFungible }
+ struct Coin { string obverse; string reverse; }
+ function transfer(address recipient, uint amount) external;
+ }
+
+Contracts can inherit interfaces as they would inherit other contracts.
+
+Types defined inside interfaces and other contract-like structures
+can be accessed from other contracts: ``Token.TokenType`` or ``Token.Coin``.
diff --git a/docs/contracts/libraries.rst b/docs/contracts/libraries.rst
new file mode 100644
index 00000000..0cabe18a
--- /dev/null
+++ b/docs/contracts/libraries.rst
@@ -0,0 +1,230 @@
+.. index:: ! library, callcode, delegatecall
+
+.. _libraries:
+
+*********
+Libraries
+*********
+
+Libraries are similar to contracts, but their purpose is that they are deployed
+only once at a specific address and their code is reused using the ``DELEGATECALL``
+(``CALLCODE`` until Homestead)
+feature of the EVM. This means that if library functions are called, their code
+is executed in the context of the calling contract, i.e. ``this`` points to the
+calling contract, and especially the storage from the calling contract can be
+accessed. As a library is an isolated piece of source code, it can only access
+state variables of the calling contract if they are explicitly supplied (it
+would have no way to name them, otherwise). Library functions can only be
+called directly (i.e. without the use of ``DELEGATECALL``) if they do not modify
+the state (i.e. if they are ``view`` or ``pure`` functions),
+because libraries are assumed to be stateless. In particular, it is
+not possible to destroy a library.
+
+.. note::
+ Until version 0.4.20, it was possible to destroy libraries by
+ circumventing Solidity's type system. Starting from that version,
+ libraries contain a :ref:`mechanism<call-protection>` that
+ disallows state-modifying functions
+ to be called directly (i.e. without ``DELEGATECALL``).
+
+Libraries can be seen as implicit base contracts of the contracts that use them.
+They will not be explicitly visible in the inheritance hierarchy, but calls
+to library functions look just like calls to functions of explicit base
+contracts (``L.f()`` if ``L`` is the name of the library). Furthermore,
+``internal`` functions of libraries are visible in all contracts, just as
+if the library were a base contract. Of course, calls to internal functions
+use the internal calling convention, which means that all internal types
+can be passed and types :ref:`stored in memory <data-location>` will be passed by reference and not copied.
+To realize this in the EVM, code of internal library functions
+and all functions called from therein will at compile time be pulled into the calling
+contract, and a regular ``JUMP`` call will be used instead of a ``DELEGATECALL``.
+
+.. index:: using for, set
+
+The following example illustrates how to use libraries (but manual method
+be sure to check out :ref:`using for <using-for>` for a
+more advanced example to implement a set).
+
+::
+
+ pragma solidity >=0.4.22 <0.6.0;
+
+ library Set {
+ // We define a new struct datatype that will be used to
+ // hold its data in the calling contract.
+ struct Data { mapping(uint => bool) flags; }
+
+ // Note that the first parameter is of type "storage
+ // reference" and thus only its storage address and not
+ // its contents is passed as part of the call. This is a
+ // special feature of library functions. It is idiomatic
+ // to call the first parameter `self`, if the function can
+ // be seen as a method of that object.
+ function insert(Data storage self, uint value)
+ public
+ returns (bool)
+ {
+ if (self.flags[value])
+ return false; // already there
+ self.flags[value] = true;
+ return true;
+ }
+
+ function remove(Data storage self, uint value)
+ public
+ returns (bool)
+ {
+ if (!self.flags[value])
+ return false; // not there
+ self.flags[value] = false;
+ return true;
+ }
+
+ function contains(Data storage self, uint value)
+ public
+ view
+ returns (bool)
+ {
+ return self.flags[value];
+ }
+ }
+
+ contract C {
+ Set.Data knownValues;
+
+ function register(uint value) public {
+ // The library functions can be called without a
+ // specific instance of the library, since the
+ // "instance" will be the current contract.
+ require(Set.insert(knownValues, value));
+ }
+ // In this contract, we can also directly access knownValues.flags, if we want.
+ }
+
+Of course, you do not have to follow this way to use
+libraries: they can also be used without defining struct
+data types. Functions also work without any storage
+reference parameters, and they can have multiple storage reference
+parameters and in any position.
+
+The calls to ``Set.contains``, ``Set.insert`` and ``Set.remove``
+are all compiled as calls (``DELEGATECALL``) to an external
+contract/library. If you use libraries, be aware 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, because of the use of ``CALLCODE``, ``msg.sender`` and
+``msg.value`` changed, though).
+
+The following example shows how to use :ref:`types stored in memory <data-location>` and
+internal functions in libraries in order to implement
+custom types without the overhead of external function calls:
+
+::
+
+ pragma solidity >=0.4.16 <0.6.0;
+
+ library BigInt {
+ struct bigint {
+ uint[] limbs;
+ }
+
+ function fromUint(uint x) internal pure returns (bigint memory r) {
+ r.limbs = new uint[](1);
+ r.limbs[0] = x;
+ }
+
+ function add(bigint memory _a, bigint memory _b) internal pure returns (bigint memory r) {
+ r.limbs = new uint[](max(_a.limbs.length, _b.limbs.length));
+ uint carry = 0;
+ for (uint i = 0; i < r.limbs.length; ++i) {
+ uint a = limb(_a, i);
+ uint b = limb(_b, i);
+ r.limbs[i] = a + b + carry;
+ if (a + b < a || (a + b == uint(-1) && carry > 0))
+ carry = 1;
+ else
+ carry = 0;
+ }
+ if (carry > 0) {
+ // too bad, we have to add a limb
+ uint[] memory newLimbs = new uint[](r.limbs.length + 1);
+ uint i;
+ for (i = 0; i < r.limbs.length; ++i)
+ newLimbs[i] = r.limbs[i];
+ newLimbs[i] = carry;
+ r.limbs = newLimbs;
+ }
+ }
+
+ function limb(bigint memory _a, uint _limb) internal pure returns (uint) {
+ return _limb < _a.limbs.length ? _a.limbs[_limb] : 0;
+ }
+
+ function max(uint a, uint b) private pure returns (uint) {
+ return a > b ? a : b;
+ }
+ }
+
+ contract C {
+ using BigInt for BigInt.bigint;
+
+ function f() public pure {
+ BigInt.bigint memory x = BigInt.fromUint(7);
+ BigInt.bigint memory y = BigInt.fromUint(uint(-1));
+ BigInt.bigint memory z = x.add(y);
+ assert(z.limb(1) > 0);
+ }
+ }
+
+As the compiler cannot know where the library will be
+deployed at, these addresses have to be filled into the
+final bytecode by a linker
+(see :ref:`commandline-compiler` for how to use the
+commandline compiler for linking). If the addresses are not
+given as arguments to the compiler, the compiled hex code
+will contain placeholders of the form ``__Set______`` (where
+``Set`` is the name of the library). The address can be filled
+manually by replacing all those 40 symbols by the hex
+encoding of the address of the library contract.
+
+.. note::
+ Manually linking libraries on the generated bytecode is discouraged, because
+ it is restricted to 36 characters.
+ You should ask the compiler to link the libraries at the time
+ a contract is compiled by either using
+ the ``--libraries`` option of ``solc`` or the ``libraries`` key if you use
+ the standard-JSON interface to the compiler.
+
+Restrictions for libraries in comparison to contracts:
+
+- No state variables
+- Cannot inherit nor be inherited
+- Cannot receive Ether
+
+(These might be lifted at a later point.)
+
+.. _call-protection:
+
+Call Protection For Libraries
+=============================
+
+As mentioned in the introduction, if a library's code is executed
+using a ``CALL`` instead of a ``DELEGATECALL`` or ``CALLCODE``,
+it will revert unless a ``view`` or ``pure`` function is called.
+
+The EVM does not provide a direct way for a contract to detect
+whether it was called using ``CALL`` or not, but a contract
+can use the ``ADDRESS`` opcode to find out "where" it is
+currently running. The generated code compares this address
+to the address used at construction time to determine the mode
+of calling.
+
+More specifically, the runtime code of a library always starts
+with a push instruction, which is a zero of 20 bytes at
+compilation time. When the deploy code runs, this constant
+is replaced in memory by the current address and this
+modified code is stored in the contract. At runtime,
+this causes the deploy time address to be the first
+constant to be pushed onto the stack and the dispatcher
+code compares the current address against this constant
+for any non-view and non-pure function.
diff --git a/docs/contracts/using-for.rst b/docs/contracts/using-for.rst
new file mode 100644
index 00000000..ef456ff4
--- /dev/null
+++ b/docs/contracts/using-for.rst
@@ -0,0 +1,119 @@
+.. index:: ! using for, library
+
+.. _using-for:
+
+*********
+Using For
+*********
+
+The directive ``using A for B;`` can be used to attach library
+functions (from the library ``A``) to any type (``B``).
+These functions will receive the object they are called on
+as their first parameter (like the ``self`` variable in Python).
+
+The effect of ``using A for *;`` is that the functions from
+the library ``A`` are attached to *any* type.
+
+In both situations, *all* functions in the library are attached,
+even those where the type of the first parameter does not
+match the type of the object. The type is checked at the
+point the function is called and function overload
+resolution is performed.
+
+The ``using A for B;`` directive is active only within the current
+contract, including within all of its functions, and has no effect
+outside of the contract in which it is used. The directive
+may only be used inside a contract, not inside any of its functions.
+
+By including a library, its data types including library functions are
+available without having to add further code.
+
+Let us rewrite the set example from the
+:ref:`libraries` in this way::
+
+ pragma solidity >=0.4.16 <0.6.0;
+
+ // This is the same code as before, just without comments
+ library Set {
+ struct Data { mapping(uint => bool) flags; }
+
+ function insert(Data storage self, uint value)
+ public
+ returns (bool)
+ {
+ if (self.flags[value])
+ return false; // already there
+ self.flags[value] = true;
+ return true;
+ }
+
+ function remove(Data storage self, uint value)
+ public
+ returns (bool)
+ {
+ if (!self.flags[value])
+ return false; // not there
+ self.flags[value] = false;
+ return true;
+ }
+
+ function contains(Data storage self, uint value)
+ public
+ view
+ returns (bool)
+ {
+ return self.flags[value];
+ }
+ }
+
+ contract C {
+ using Set for Set.Data; // this is the crucial change
+ Set.Data knownValues;
+
+ function register(uint value) public {
+ // Here, all variables of type Set.Data have
+ // corresponding member functions.
+ // The following function call is identical to
+ // `Set.insert(knownValues, value)`
+ require(knownValues.insert(value));
+ }
+ }
+
+It is also possible to extend elementary types in that way::
+
+ pragma solidity >=0.4.16 <0.6.0;
+
+ library Search {
+ function indexOf(uint[] storage self, uint value)
+ public
+ view
+ returns (uint)
+ {
+ for (uint i = 0; i < self.length; i++)
+ if (self[i] == value) return i;
+ return uint(-1);
+ }
+ }
+
+ contract C {
+ using Search for uint[];
+ uint[] data;
+
+ function append(uint value) public {
+ data.push(value);
+ }
+
+ function replace(uint _old, uint _new) public {
+ // This performs the library function call
+ uint index = data.indexOf(_old);
+ if (index == uint(-1))
+ data.push(_new);
+ else
+ data[index] = _new;
+ }
+ }
+
+Note that all library calls are actual EVM function calls. This means that
+if you pass memory or value types, a copy will be performed, even of the
+``self`` variable. The only situation where no copy will be performed
+is when storage reference variables are used.
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-07 00:38:35 +0800