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://foundationdb.com/documentation/data-modeling.html#data-modeling-tuples).

FoundationDB tuples can currently encode byte and unicode strings, integers and NULL values. In Go these are represented as []byte, string, int64 and nil.

Index

• type Element
• type Tuple
  • func Unpack(b []byte) (Tuple, error)
  • func (t Tuple) LexKey() lex.Key
  • func (t Tuple) LexRangeKeySelectors() (lex.Selectable, lex.Selectable)
  • func (t Tuple) LexRangeKeys() (lex.KeyConvertible, lex.KeyConvertible)
  • func (t Tuple) Pack() []byte

Types

type Element

type Element interface{}

A Element 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 Element (and will typically result in a runtime panic).

The valid types for Element are []byte (or lex.KeyConvertible), string, int64 (or int), and nil.

type Tuple

type Tuple []Element

Tuple is a slice of objects that can be encoded as FoundationDB tuples. If any of the Elements 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) LexKey

func (t Tuple) LexKey() lex.Key

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

func (Tuple) LexRangeKeySelectors

func (t Tuple) LexRangeKeySelectors() (lex.Selectable, lex.Selectable)

LexRangeKeySelectors allows Tuple to satisfy the lex.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) LexRangeKeys

func (t Tuple) LexRangeKeys() (lex.KeyConvertible, lex.KeyConvertible)

LexRangeKeys allows Tuple to satisfy the lex.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, lex.KeyConvertible, string, int64, int or nil.

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