common/README.md

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