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, floats, doubles, booleans, UUIDs, tuples, and NULL values. In Go these are represented as []byte (or fdb.KeyConvertible), string, int64 (or 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) Pack() []byte
• type TupleElement
• type UUID

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 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) 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, float32, float64, bool, tuple.UUID, nil, or a Tuple with elements of valid types.

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.

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), 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.