Cbor.Encode

The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack.

Encoder

type Encoder

Describes how to encode a data structure or a type into binary CBOR

encode : Encoder -> Bytes

Turn a CBOR 'Encoder' into 'Bytes'.

import Cbor.Encode as E
import Url exposing (Url)


type alias Album =
    { artist : String
    , title : String
    , year : Int
    , tracks : List ( String, Duration )
    , links : List Url
    }


type Duration
    = Duration Int


encodeAlbum : Album -> E.Encoder
encodeAlbum { artist, title, year, tracks, links } =
    let
        link =
            Url.toString >> E.string


        track =
            E.pair E.string (\(Duration d) -> E.int d)
    in
    E.sequence
        [ E.string artist
        , E.string title
        , E.int year
        , E.list track tracks
        , E.list link links
        ]

sequence : List Encoder -> Encoder

Combine a bunch of encoders.

Primitives

bool : Bool -> Encoder

Encode booleans.

int : Int -> Encoder

Encode integers from -9007199254740992 (-2⁵³) to 9007199254740991 (2⁵³ - 1).

float : Float -> Encoder

Encode floating numbers with maximum precision (64-bit).

NOTE: This is an alias for 'float64'.

string : String -> Encoder

Encode a 'String' of fixed size.

bytes : Bytes -> Encoder

Encode raw 'Bytes' of fixed size.

null : Encoder

Create a CBOR null value. This can be decoded using maybe from the 'Cbor.Decode' module.

undefined : Encoder

Create a CBOR undefined value. This can be decoded using maybe from the Cbor.Decode module

Fancier Primitives

float16 : Float -> Encoder

Encode floating numbers with half-precision (16-bit).

float32 : Float -> Encoder

Encode floating numbers with simple precision (32-bit).

float64 : Float -> Encoder

Encode floating numbers with double precision (64-bit).

Data Structures

list : (a -> Encoder) -> List a -> Encoder

Turn a 'List' into a CBOR array

E.list E.int [1,2,3] == Bytes<0x83, 0x01, 0x02, 0x03>

dict : (k -> Encoder) -> (v -> Encoder) -> Dict k v -> Encoder

Turn a 'Dict' into a CBOR array

E.dict E.string E.int (Dict.fromList [ ( "a", 1 ), ( "b", 2 ) ])
    == Bytes<0xA2, 0x61, 0x61, 0x01, 0x61, 0x62, 0x02>

Note that in CBOR, every data-structure are mostly arrays of items. As a consequence, dictionnaries are encoded as a list of pairs (key, value).

keyValueMap : (k -> Encoder) -> (v -> Encoder) -> List ( k, v ) -> Encoder

Turn a (key, value) into a CBOR array. Note that, if keys are comparable, you should consider using a Dict instead.

pair : (a -> Encoder) -> (b -> Encoder) -> ( a, b ) -> Encoder

Turn a 2-'Tuple' into a CBOR array

E.pair E.string E.int ( "a", 14 ) == Bytes<0x61, 0x61, 0x0E>

Streaming

Four CBOR items (arrays, maps, byte strings, and text strings) can be encoded with an indefinite length. This is useful if the encoding of the item needs to begin before the number of items inside the array or map, or the total length of the string, is known. (The application of this is often referred to as "streaming" within a data item.)

NOTE:
Indefinite-length arrays and maps are dealt with differently than indefinite-length byte strings and text strings.

beginStrings : Encoder

Encode a 'String' of indefinite length. This indicates the beginning of multiple calls to 'string', followed by a 'break' to signal the end of the stream. For example:

E.sequence
    [ E.beginStrings
    , E.string "elm"
    , E.string "rocks"
    , E.string "!"
    , E.break
    ]

beginBytes : Encoder

Encode a 'Bytes' of indefinite length. This indicates the beginning of multiple calls to 'bytes', followed by a 'break' to signal the end of the stream. For example:

E.sequence
    [ E.beginBytes
    , E.bytes Bytes<0x01, 0x02>
    , E.bytes Bytes<0x03, 0x04>
    , E.break
    ]

beginList : Encoder

Encode a 'List' of indefinite length. This indicates the beginning of multiple calls for encoding elements, followed by a 'break' to signal the end of the stream. For example:

E.sequence
    [ E.beginList
    , E.string "elm"
    , E.string "rocks"
    , E.string "!"
    , E.break
    ]

beginDict : Encoder

Encode a 'Dict' of indefinite length. This indicates the beginning of multiple calls for encoding pairs of elements, followed by a 'break' to signal the end of the stream. For example:

E.sequence
    [ E.beginDict
    , E.pair E.int E.string ( 1, "elm" )
    , E.pair E.int E.string ( 2, "rocks" )
    , E.pair E.int E.string ( 3, "!" )
    , E.break
    ]

break : Encoder

Encode termination of an indefinite structure.

Tagging

Encode a particular 'Tag' to binary CBOR

tagged : Tag -> (a -> Encoder) -> a -> Encoder

Helper to quickly encode a tagged value

E.tagged t encodeA a == E.sequence [ E.tag t, encodeA a ]

Debugging

any : CborItem -> Encoder

Encode any generic CBOR item. This is particularly useful when dealing with heterogeneous data structures (e.g. tuples).

E.list E.any [ CborInt 42, CborBool True, CborString "awesome!" ]

raw : Bytes -> Encoder

Unsafe encoder to inject any arbitrary bytes into the encoding sequence. Do not use unless you know what you're doing, this may result in invalid CBOR encoding!

elm-toulouse/cbor/1.1.0