Contract functions can lack an implementation as in the following example (note that the function declaration header is terminated by `;`)::
contract feline {
function utterance() 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::
contract Cat is feline {
function utterance() 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.
..index:: ! library, callcode
.._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 `CALLCODE`
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 to way to name them, otherwise).
..index:: using for, set
The following example illustrates how to use libraries (but
be sure to check out :ref:`using for <using-for>` for a
more advanced example to implement a set).
::
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)
returns (bool)
{
if (self.flags[value])
return false; // already there
self.flags[value] = true;
return true;
}
function remove(Data storage self, uint value)
returns (bool)
{
if (!self.flags[value])
return false; // not there
self.flags[value] = false;
return true;
}
function contains(Data storage self, uint value)
returns (bool)
{
return self.flags[value];
}
}
contract C {
Set.Data knownValues;
function register(uint value) {
// The library functions can be called without a
// specific instance of the library, since the
// "instance" will be the current contract.
if (!Set.insert(knownValues, value))
throw;
}
// 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, 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 (`CALLCODE`s) to an external
contract/library. If you use libraries, take care that an
actual external function call is performed, so `msg.sender`
does not point to the original sender anymore but to the the
calling contract and also `msg.value` contains the funds
sent during the call to the library function.
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 [Using the Commandline
Compiler](#using-the-commandline-compiler) on 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.
Restrictions for libraries in comparison to contracts:
- no state variables
- cannot inherit nor be inherited
(these might be lifted at a later point)
Common pitfalls for libraries
=============================
..index:: msg;sender
The value of `msg.sender`
-------------------------
The value for `msg.sender` will be that of the contract which is calling the library function.
For example, if A calls contract B which internally calls library C, then within the function call of library C, `msg.sender` will be the address of contract B.
The reason for this is that the expression `LibraryName.functionName()`
performs an external function call using `CALLCODE`, which maps to a real EVM
call just like `otherContract.functionName()` or `this.functionName()`. This
call extends the call depth by one (limited to 1024), stores the caller (the
current contract) as `msg.sender`, and then executes the library contract's
code against the current contracts storage. This execution occurs in a
completely new memory context meaning that memory types will be copied and
cannot be passed by reference.
Transferring Ether
-------------------------
It is *in principle* possible to transfer ether using
`LibraryName.functionName.value(x)()`, but as `CALLCODE` is used, the Ether
will just end up at the current contract.
..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, even those where the
type of the first parameter does not match the type of
the object, are attached. 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 for the current
scope, which is limited to a contract for now but will
be lifted to the global scope later, so that by including
a module, 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::
// 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)
returns (bool)
{
if (self.flags[value])
return false; // already there
self.flags[value] = true;
return true;
}
function remove(Data storage self, uint value)
returns (bool)
{
if (!self.flags[value])
return false; // not there
self.flags[value] = false;
return true;
}
function contains(Data storage self, uint value)
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) {
// Here, all variables of type Set.Data have
// corresponding member functions.
// The following function call is identical to
// Set.insert(knownValues, value)
if (!knownValues.insert(value))
throw;
}
}
It is also possible to extend elementary types in that way::
library Search {
function indexOf(uint[] storage self, uint value) {
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) {
data.push(value);
}
function replace(uint _old, uint _new) {
// This performs the library function call
uint index = data.find(_old);
if (index == -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