fdbtuple

Documentation

Overview

Package fdbtuple provides a layer for encoding and decoding multi-element tuples into keys usable by FoundationDB. The encoded key maintains the same sort order as the original tuple: sorted first by the first element, then by the second element, etc. This makes the tuple layer ideal for building a variety of higher-level data models.

For general guidance on tuple usage, see the Tuple section of Data Modeling (https://apple.github.io/foundationdb/data-modeling.html#tuples).

FoundationDB tuples can currently encode byte and unicode strings, integers, large integers, floats, doubles, booleans, UUIDs, tuples, and NULL values. In Go these are represented as []byte, string, int64 (or int, uint, uint64), *big.Int (or big.Int), float32, float64, bool, UUID, Tuple, and nil.

Index

• type Tuple
  • func Unpack(b []byte) (Tuple, error)
  • func (t Tuple) HasIncompleteVersionstamp() (bool, error)
  • func (t Tuple) Pack() []byte
• type TupleElement
• type UUID
• type Versionstamp
  • func IncompleteVersionstamp(userVersion uint16) Versionstamp
  • func (v Versionstamp) Bytes() []byte

Types

type Tuple

type Tuple []TupleElement

Tuple is a slice of objects that can be encoded as FoundationDB tuples. If any of the TupleElements are of unsupported types, a runtime panic will occur when the Tuple is packed.

Given a Tuple T containing objects only of these types, then T will be identical to the Tuple returned by unpacking the byte slice obtained by packing T (modulo type normalization to []byte, uint64, and int64).

func Unpack

func Unpack(b []byte) (Tuple, error)

Unpack returns the tuple encoded by the provided byte slice, or an error if the key does not correctly encode a FoundationDB tuple.

func (Tuple) HasIncompleteVersionstamp

func (t Tuple) HasIncompleteVersionstamp() (bool, error)

HasIncompleteVersionstamp determines if there is at least one incomplete versionstamp in a tuple. This function will return an error this tuple has more than one versionstamp.

func (Tuple) Pack

func (t Tuple) Pack() []byte

Pack returns a new byte slice encoding the provided tuple. Pack will panic if the tuple contains an element of any type other than []byte, string, int64, int, uint64, uint, *big.Int, big.Int, float32, float64, bool, tuple.UUID, tuple.Versionstamp, nil, or a Tuple with elements of valid types. It will also panic if an integer is specified with a value outside the range [-2**2040+1, 2**2040-1]

This method will panic if it contains an incomplete Versionstamp. Use PackWithVersionstamp instead.

type TupleElement

type TupleElement interface{}

A TupleElement is one of the types that may be encoded in FoundationDB tuples. Although the Go compiler cannot enforce this, it is a programming error to use an unsupported types as a TupleElement (and will typically result in a runtime panic).

The valid types for TupleElement are []byte, string, int64 (or int, uint, uint64), *big.Int (or big.Int), float, double, bool, UUID, Tuple, and nil.

type UUID

type UUID [16]byte

UUID wraps a basic byte array as a UUID. We do not provide any special methods for accessing or generating the UUID, but as Go does not provide a built-in UUID type, this simple wrapper allows for other libraries to write the output of their UUID type as a 16-byte array into an instance of this type.

type Versionstamp

type Versionstamp struct {
	TransactionVersion [10]byte
	UserVersion        uint16
}

Versionstamp is struct for a FoundationDB verionstamp. Versionstamps are 12 bytes long composed of a 10 byte transaction version and a 2 byte user version. The transaction version is filled in at commit time and the user version is provided by the application to order results within a transaction.

func IncompleteVersionstamp

func IncompleteVersionstamp(userVersion uint16) Versionstamp

IncompleteVersionstamp is the constructor you should use to make an incomplete versionstamp to use in a tuple.

func (Versionstamp) Bytes

func (v Versionstamp) Bytes() []byte

Bytes converts a Versionstamp struct to a byte slice for encoding in a tuple.