diff options
Diffstat (limited to 'common/README.md')
| -rw-r--r-- | common/README.md | 140 |
1 files changed, 0 insertions, 140 deletions
diff --git a/common/README.md b/common/README.md deleted file mode 100644 index adea022b7..000000000 --- a/common/README.md +++ /dev/null @@ -1,140 +0,0 @@ -# common - -[](https://travis-ci.org/ethereum/go-ethereum) - -The common package contains the ethereum utility library. - -# Installation - -As a subdirectory the main go-ethereum repository, you get it with -`go get github.com/ethereum/go-ethereum`. - -# Usage - -## RLP (Recursive Linear Prefix) Encoding - -RLP Encoding is an encoding scheme used by the Ethereum project. It -encodes any native value or list to a string. - -More in depth information about the encoding scheme see the -[Wiki](http://wiki.ethereum.org/index.php/RLP) article. - -```go -rlp := common.Encode("doge") -fmt.Printf("%q\n", rlp) // => "\0x83dog" - -rlp = common.Encode([]interface{}{"dog", "cat"}) -fmt.Printf("%q\n", rlp) // => "\0xc8\0x83dog\0x83cat" -decoded := common.Decode(rlp) -fmt.Println(decoded) // => ["dog" "cat"] -``` - -## Patricia Trie - -Patricie Tree is a merkle trie used by the Ethereum project. - -More in depth information about the (modified) Patricia Trie can be -found on the [Wiki](http://wiki.ethereum.org/index.php/Patricia_Tree). - -The patricia trie uses a db as backend and could be anything as long as -it satisfies the Database interface found in `common/db.go`. - -```go -db := NewDatabase() - -// db, root -trie := common.NewTrie(db, "") - -trie.Put("puppy", "dog") -trie.Put("horse", "stallion") -trie.Put("do", "verb") -trie.Put("doge", "coin") - -// Look up the key "do" in the trie -out := trie.Get("do") -fmt.Println(out) // => verb - -trie.Delete("puppy") -``` - -The patricia trie, in combination with RLP, provides a robust, -cryptographically authenticated data structure that can be used to store -all (key, value) bindings. - -```go -// ... Create db/trie - -// Note that RLP uses interface slices as list -value := common.Encode([]interface{}{"one", 2, "three", []interface{}{42}}) -// Store the RLP encoded value of the list -trie.Put("mykey", value) -``` - -## Value - -Value is a Generic Value which is used in combination with RLP data or -`([])interface{}` structures. It may serve as a bridge between RLP data -and actual real values and takes care of all the type checking and -casting. Unlike Go's `reflect.Value` it does not panic if it's unable to -cast to the requested value. It simple returns the base value of that -type (e.g. `Slice()` returns []interface{}, `Uint()` return 0, etc). - -### Creating a new Value - -`NewEmptyValue()` returns a new \*Value with it's initial value set to a -`[]interface{}` - -`AppendList()` appends a list to the current value. - -`Append(v)` appends the value (v) to the current value/list. - -```go -val := common.NewEmptyValue().Append(1).Append("2") -val.AppendList().Append(3) -``` - -### Retrieving values - -`Get(i)` returns the `i` item in the list. - -`Uint()` returns the value as an unsigned int64. - -`Slice()` returns the value as a interface slice. - -`Str()` returns the value as a string. - -`Bytes()` returns the value as a byte slice. - -`Len()` assumes current to be a slice and returns its length. - -`Byte()` returns the value as a single byte. - -```go -val := common.NewValue([]interface{}{1,"2",[]interface{}{3}}) -val.Get(0).Uint() // => 1 -val.Get(1).Str() // => "2" -s := val.Get(2) // => Value([]interface{}{3}) -s.Get(0).Uint() // => 3 -``` - -## Decoding - -Decoding streams of RLP data is simplified - -```go -val := common.NewValueFromBytes(rlpData) -val.Get(0).Uint() -``` - -## Encoding - -Encoding from Value to RLP is done with the `Encode` method. The -underlying value can be anything RLP can encode (int, str, lists, bytes) - -```go -val := common.NewValue([]interface{}{1,"2",[]interface{}{3}}) -rlp := val.Encode() -// Store the rlp data -Store(rlp) -``` |