github.com/jonasnick/go-ethereum@v0.7.12-0.20150216215225-22176f05d387/ethutil/README.md (about)

     1  # ethutil
     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 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  ```