| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
FoundationDB.Layer.Tuple
Description
The tuple layer is the most fundamental layer shared by all language bindings. It is responsible for implementing a key encoding scheme that ensures that many common types (and tuples composed of them) can be written to FoundationDB with a sensible lexicographical ordering. This enables many powerful query patterns. See the official docs for more information.
Synopsis
- data Elem
- = None
- | Tuple [Elem]
- | Bytes ByteString
- | Text Text
- | Int Integer
- | Float Float
- | Double Double
- | Bool Bool
- | UUID Word32 Word32 Word32 Word32
- | CompleteVS (Versionstamp 'Complete)
- | IncompleteVS (Versionstamp 'Incomplete)
- encodeTupleElems :: Traversable t => t Elem -> ByteString
- encodeTupleElemsWPrefix :: Traversable t => ByteString -> t Elem -> ByteString
- decodeTupleElems :: ByteString -> Either String [Elem]
- decodeTupleElemsWPrefix :: ByteString -> ByteString -> Either String [Elem]
Documentation
Elements of tuples. A tuple is represented as a list of these. Note that a tuple may contain at most one incomplete version stamp. Future versions of this library may introduce a more strongly typed tuple representation that enforces this restriction.
Constructors
| None | Corresponds to null or nil types in other language bindings. |
| Tuple [Elem] | Nested tuples. |
| Bytes ByteString | |
| Text Text | |
| Int Integer | Variable-length integer encodings. For values that fit within a 64-bit signed integer, the standard integer encoding is used. For larger values, the provisional spec for Java and Python values is used. |
| Float Float | |
| Double Double | |
| Bool Bool | |
| UUID Word32 Word32 Word32 Word32 | Crude UUID to avoid dependency on UUID library. Interconvertible with
|
| CompleteVS (Versionstamp 'Complete) | |
| IncompleteVS (Versionstamp 'Incomplete) | This constructor is to be used in conjunction with |
Instances
encodeTupleElems :: Traversable t => t Elem -> ByteString Source #
Encodes a tuple from a list of tuple elements. Returns the encoded tuple.
Warning: this function can throw an Error with TupleIntTooLarge if you
pass an Int element that requires more than 255 bytes to serialize. Since
the smallest such number is 614 decimal digits long, we deemed this situation
unlikely enough that it wasn't worth returning a sum type from this function.
Note: this encodes to the format expected by FoundationDB as input, which
is slightly different from the format returned by FoundationDB as output. The
difference is that if the encoded bytes include an incomplete version stamp,
four bytes are appended to the end to indicate the index of the incomplete
version stamp so that FoundationDB can fill in the transaction version and
batch order when this function is used in conjunction with
setVersionstampedKey and setVersionstampedValue:
do let k = pack mySubspace [IncompleteVS (IncompleteVersionstamp 123)] atomicOp k (setVersionstampedKey "my_value")
Because FoundationDB uses two bytes at the end of the key for this, only
one IncompleteVS can be used per key.
This also means that (decodeTupleElems . encodeTupleElems) gives
strange results when an IncompleteVS is present in the input, because the
two extra bytes are interpreted as being part of the tuple.
>>>decodeTupleElems $ encodeTupleElems [IncompleteVS (IncompleteVersionstamp 1)]Right [IncompleteVS (IncompleteVersionstamp 1),Bytes "",None,None]
For this reason, decodeTupleElems should only be called on keys that have
been returned from the database, because setVersionstampedKey drops
the last two bytes when it writes the key to the database.
encodeTupleElemsWPrefix :: Traversable t => ByteString -> t Elem -> ByteString Source #
Like encodeTupleElems, but prepends a raw bytestring prefix to the
tuple. This is used by the subspace and directory layers.
decodeTupleElems :: ByteString -> Either String [Elem] Source #
Decodes a tuple, or returns a parse error. This function will never return
IncompleteVS tuple elements. See the note on encodeTupleElems for more
information.
decodeTupleElemsWPrefix Source #
Arguments
| :: ByteString | expected prefix |
| -> ByteString | encoded tuple |
| -> Either String [Elem] |
Decodes a tuple that was encoded with a given prefix. Fails if the input prefix is not actually a prefix of the encoded tuple.