github.com/tidwall/pair@v0.0.0-20170418221434-1140497fc57a/README.md (about)

     1  Pair
     2  ====
     3  <a href="https://godoc.org/github.com/tidwall/pair"><img src="https://img.shields.io/badge/api-reference-blue.svg?style=flat-square" alt="GoDoc"></a>
     4  
     5  Pair is a Go package that provides a low memory key/value object that takes up one allocation. It's useful for in-memory key/value stores and data structures where memory space is a concern.
     6  
     7  
     8  Data structure
     9  --------------
    10  
    11  The allocation is a single packed block of bytes with the following format:
    12  
    13  | ValueSize uint32 | KeySize uint32 | Value []byte | Key []byte |
    14  |------------------|----------------|--------------|------------|
    15  
    16  Using
    17  -----
    18  
    19  To start using Pair, install Go and run `go get`:
    20  
    21  ```
    22  $ go get -u github.com/tidwall/pair
    23  ```
    24  
    25  Create a new Pair:
    26  
    27  ```go
    28  item := pair.New([]byte("user:2054:name"), []byte("Alice Tripplehorn"))
    29  ```
    30  
    31  Access the Pair data:
    32  ```go
    33  item.Key() []byte    // returns the key portion of the pair.
    34  item.Value() []byte  // returns the value portion of the pair.
    35  item.Size() int      // returns the exact in-memory size of the item.
    36  item.Zero() bool     // returns true if the pair is unallocated.
    37  ```
    38  
    39  Unsafe pointer access:
    40  ```go
    41  item.Pointer() unsafe.Pointer             // returns the base pointer
    42  pair.FromPointer(ptr unsafe.Pointer) Pair // returns a Pair with provided base pointer
    43  ```
    44  
    45  Contact
    46  -------
    47  Josh Baker [@tidwall](http://twitter.com/tidwall)
    48  
    49  License
    50  -------
    51  Pair source code is available under the MIT [License](/LICENSE).
    52