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 (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
- type Versionstamp
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
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.
type Versionstamp ¶
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.
Source Files