github.com/jonasnick/go-ethereum@v0.7.12-0.20150216215225-22176f05d387/ethutil/README.md (about) 1 # ethutil 2 3 [](https://travis-ci.org/ethereum/go-ethereum) 5 6 The ethutil package contains the ethereum utility library. 7 8 # Installation 9 10 `go get github.com/ethereum/ethutil-go` 11 12 # Usage 13 14 ## RLP (Recursive Linear Prefix) Encoding 15 16 RLP Encoding is an encoding scheme utilized by the Ethereum project. It 17 encodes any native value or list to string. 18 19 More in depth information about the Encoding scheme see the [Wiki](http://wiki.ethereum.org/index.php/RLP) 20 article. 21 22 ```go 23 rlp := ethutil.Encode("doge") 24 fmt.Printf("%q\n", rlp) // => "\0x83dog" 25 26 rlp = ethutil.Encode([]interface{}{"dog", "cat"}) 27 fmt.Printf("%q\n", rlp) // => "\0xc8\0x83dog\0x83cat" 28 decoded := ethutil.Decode(rlp) 29 fmt.Println(decoded) // => ["dog" "cat"] 30 ``` 31 32 ## Patricia Trie 33 34 Patricie Tree is a merkle trie utilized by the Ethereum project. 35 36 More in depth information about the (modified) Patricia Trie can be 37 found on the [Wiki](http://wiki.ethereum.org/index.php/Patricia_Tree). 38 39 The patricia trie uses a db as backend and could be anything as long as 40 it satisfies the Database interface found in `ethutil/db.go`. 41 42 ```go 43 db := NewDatabase() 44 45 // db, root 46 trie := ethutil.NewTrie(db, "") 47 48 trie.Put("puppy", "dog") 49 trie.Put("horse", "stallion") 50 trie.Put("do", "verb") 51 trie.Put("doge", "coin") 52 53 // Look up the key "do" in the trie 54 out := trie.Get("do") 55 fmt.Println(out) // => verb 56 57 trie.Delete("puppy") 58 ``` 59 60 The patricia trie, in combination with RLP, provides a robust, 61 cryptographically authenticated data structure that can be used to store 62 all (key, value) bindings. 63 64 ```go 65 // ... Create db/trie 66 67 // Note that RLP uses interface slices as list 68 value := ethutil.Encode([]interface{}{"one", 2, "three", []interface{}{42}}) 69 // Store the RLP encoded value of the list 70 trie.Put("mykey", value) 71 ``` 72 73 ## Value 74 75 Value is a Generic Value which is used in combination with RLP data or 76 `([])interface{}` structures. It may serve as a bridge between RLP data 77 and actual real values and takes care of all the type checking and 78 casting. Unlike Go's `reflect.Value` it does not panic if it's unable to 79 cast to the requested value. It simple returns the base value of that 80 type (e.g. `Slice()` returns []interface{}, `Uint()` return 0, etc). 81 82 ### Creating a new Value 83 84 `NewEmptyValue()` returns a new \*Value with it's initial value set to a 85 `[]interface{}` 86 87 `AppendList()` appends a list to the current value. 88 89 `Append(v)` appends the value (v) to the current value/list. 90 91 ```go 92 val := ethutil.NewEmptyValue().Append(1).Append("2") 93 val.AppendList().Append(3) 94 ``` 95 96 ### Retrieving values 97 98 `Get(i)` returns the `i` item in the list. 99 100 `Uint()` returns the value as an unsigned int64. 101 102 `Slice()` returns the value as a interface slice. 103 104 `Str()` returns the value as a string. 105 106 `Bytes()` returns the value as a byte slice. 107 108 `Len()` assumes current to be a slice and returns its length. 109 110 `Byte()` returns the value as a single byte. 111 112 ```go 113 val := ethutil.NewValue([]interface{}{1,"2",[]interface{}{3}}) 114 val.Get(0).Uint() // => 1 115 val.Get(1).Str() // => "2" 116 s := val.Get(2) // => Value([]interface{}{3}) 117 s.Get(0).Uint() // => 3 118 ``` 119 120 ## Decoding 121 122 Decoding streams of RLP data is simplified 123 124 ```go 125 val := ethutil.NewValueFromBytes(rlpData) 126 val.Get(0).Uint() 127 ``` 128 129 ## Encoding 130 131 Encoding from Value to RLP is done with the `Encode` method. The 132 underlying value can be anything RLP can encode (int, str, lists, bytes) 133 134 ```go 135 val := ethutil.NewValue([]interface{}{1,"2",[]interface{}{3}}) 136 rlp := val.Encode() 137 // Store the rlp data 138 Store(rlp) 139 ```