github.com/ethereumproject/go-ethereum@v5.5.2+incompatible/common/README.md (about)

     1  # common
     2  
     3  [![Build
     4  Status](https://travis-ci.org/ethereumproject/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/ethereumproject/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  ```