foundationdb-haskell-0.1.0.0: FoundationDB C client bindings
Safe HaskellNone
LanguageHaskell2010

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

Documentation

data Elem Source #

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 toWords and fromWords in UUID.

CompleteVS (Versionstamp 'Complete) 
IncompleteVS (Versionstamp 'Incomplete)

This constructor is to be used in conjunction with encodeTupleElems and the setVersionstampedKey atomic operation. See encodeTupleElems for more information.

Instances

Instances details
Eq Elem Source # 
Instance details

Defined in FoundationDB.Layer.Tuple.Internal

Methods

(==) :: Elem -> Elem -> Bool #

(/=) :: Elem -> Elem -> Bool #

Ord Elem Source # 
Instance details

Defined in FoundationDB.Layer.Tuple.Internal

Methods

compare :: Elem -> Elem -> Ordering #

(<) :: Elem -> Elem -> Bool #

(<=) :: Elem -> Elem -> Bool #

(>) :: Elem -> Elem -> Bool #

(>=) :: Elem -> Elem -> Bool #

max :: Elem -> Elem -> Elem #

min :: Elem -> Elem -> Elem #

Show Elem Source # 
Instance details

Defined in FoundationDB.Layer.Tuple.Internal

Methods

showsPrec :: Int -> Elem -> ShowS #

show :: Elem -> String #

showList :: [Elem] -> ShowS #

Generic Elem Source # 
Instance details

Defined in FoundationDB.Layer.Tuple.Internal

Associated Types

type Rep Elem :: Type -> Type #

Methods

from :: Elem -> Rep Elem x #

to :: Rep Elem x -> Elem #

NFData Elem Source # 
Instance details

Defined in FoundationDB.Layer.Tuple.Internal

Methods

rnf :: Elem -> () #

type Rep Elem Source # 
Instance details

Defined in FoundationDB.Layer.Tuple.Internal

type Rep Elem = D1 ('MetaData "Elem" "FoundationDB.Layer.Tuple.Internal" "foundationdb-haskell-0.1.0.0-3SdCayabJ4FTICSdqP65r" 'False) (((C1 ('MetaCons "None" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Tuple" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 [Elem]))) :+: (C1 ('MetaCons "Bytes" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 ByteString)) :+: (C1 ('MetaCons "Text" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Text)) :+: C1 ('MetaCons "Int" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Integer))))) :+: ((C1 ('MetaCons "Float" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Float)) :+: (C1 ('MetaCons "Double" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Double)) :+: C1 ('MetaCons "Bool" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Bool)))) :+: (C1 ('MetaCons "UUID" 'PrefixI 'False) ((S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Word32) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Word32)) :*: (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Word32) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Word32))) :+: (C1 ('MetaCons "CompleteVS" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (Versionstamp 'Complete))) :+: C1 ('MetaCons "IncompleteVS" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (Versionstamp 'Incomplete)))))))

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.