tuple

Documentation

Overview

Package tuple 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 (or fdb.KeyConvertible), 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) FDBKey() fdb.Key
  • func (t Tuple) FDBRangeKeySelectors() (fdb.Selectable, fdb.Selectable)
  • func (t Tuple) FDBRangeKeys() (fdb.KeyConvertible, fdb.KeyConvertible)
  • func (t Tuple) HasIncompleteVersionstamp() (bool, error)
  • func (t Tuple) Pack() []byte
  • func (t Tuple) PackWithVersionstamp(prefix []byte) ([]byte, error)
  • func (tuple Tuple) String() string
• type TupleElement
• type UUID
  • func (uuid UUID) String() string
• type Versionstamp
  • func IncompleteVersionstamp(userVersion uint16) Versionstamp
  • func (v Versionstamp) Bytes() []byte
  • func (vs Versionstamp) String() string

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) FDBKey

func (t Tuple) FDBKey() fdb.Key

FDBKey returns the packed representation of a Tuple, and allows Tuple to satisfy the fdb.KeyConvertible interface. FDBKey will panic in the same circumstances as Pack.

func (Tuple) FDBRangeKeySelectors

func (t Tuple) FDBRangeKeySelectors() (fdb.Selectable, fdb.Selectable)

FDBRangeKeySelectors allows Tuple to satisfy the fdb.Range interface. The range represents all keys that encode tuples strictly starting with a Tuple (that is, all tuples of greater length than the Tuple of which the Tuple is a prefix).

func (Tuple) FDBRangeKeys

func (t Tuple) FDBRangeKeys() (fdb.KeyConvertible, fdb.KeyConvertible)

FDBRangeKeys allows Tuple to satisfy the fdb.ExactRange interface. The range represents all keys that encode tuples strictly starting with a Tuple (that is, all tuples of greater length than the Tuple of which the Tuple is a prefix).

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, fdb.KeyConvertible, 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]

Tuple satisfies the fdb.KeyConvertible interface, so it is not necessary to call Pack when using a Tuple with a FoundationDB API function that requires a key.

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

func (Tuple) PackWithVersionstamp

func (t Tuple) PackWithVersionstamp(prefix []byte) ([]byte, error)

PackWithVersionstamp packs the specified tuple into a key for versionstamp operations. See Pack for more information. This function will return an error if you attempt to pack a tuple with more than one versionstamp. This function will return an error if you attempt to pack a tuple with a versionstamp position larger than an uint16 if the API version is less than 520.

func (Tuple) String

func (tuple Tuple) String() string

String implements the fmt.Stringer interface and returns human-readable string representation of this tuple. For most elements, we use the object's default string representation.

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 (or fdb.KeyConvertible), 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.

func (UUID) String

func (uuid UUID) String() string

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.

func (Versionstamp) String

func (vs Versionstamp) String() string

Returns a human-readable string for this Versionstamp.