Bytes.Decode

Bytes

Turn Bytes into Selm values.

BEAM-target decoders for OTP binaries.

Types

Decoder

type Decoder a = Decoder

A recipe for reading a value of type a from a byte sequence.

Examples

decode unsignedInt8 (Bytes.Encode.encode (Bytes.Encode.unsignedInt8 7)) == Just 7

Step

type Step state a
= Loop state
| Done a

Control value for loop: keep going with a new state, or finish.

Examples

-- Loop remainingCount keeps reading; Done xs finishes with the list

Values

decode

decode : Decoder a -> Bytes -> Maybe a

Run a decoder. Returns Nothing when there are not enough bytes (or the decoder fails).

Examples

decode (unsignedInt16 BE) (Bytes.Encode.encode (Bytes.Encode.unsignedInt16 BE 7))
    == Just 7

decode (unsignedInt16 LE) (Bytes.Encode.encode (Bytes.Encode.unsignedInt16 LE 7))
    == Just 7

decode (unsignedInt32 BE) (Bytes.Encode.encode (Bytes.Encode.unsignedInt16 BE 7))
    == Nothing

signedInt8

signedInt8 : Decoder Int

Decode one byte as a signed integer (-128…127).

Examples

decode signedInt8 (Bytes.Encode.encode (Bytes.Encode.signedInt8 -5)) == Just -5

signedInt16

signedInt16 : Endianness -> Decoder Int

Decode two bytes as a signed integer.

Examples

decode (signedInt16 BE) (Bytes.Encode.encode (Bytes.Encode.signedInt16 BE -5))
    == Just -5

signedInt32

signedInt32 : Endianness -> Decoder Int

Decode four bytes as a signed integer.

Examples

decode (signedInt32 BE) (Bytes.Encode.encode (Bytes.Encode.signedInt32 BE -5))
    == Just -5

unsignedInt8

unsignedInt8 : Decoder Int

Decode one byte as an unsigned integer (0…255).

Examples

decode unsignedInt8 (Bytes.Encode.encode (Bytes.Encode.unsignedInt8 255)) == Just 255

unsignedInt16

unsignedInt16 : Endianness -> Decoder Int

Decode two bytes as an unsigned integer.

Examples

decode (unsignedInt16 BE) (Bytes.Encode.encode (Bytes.Encode.unsignedInt16 BE 7))
    == Just 7

unsignedInt32

unsignedInt32 : Endianness -> Decoder Int

Decode four bytes as an unsigned integer.

Examples

decode (unsignedInt32 BE) (Bytes.Encode.encode (Bytes.Encode.unsignedInt32 BE 7))
    == Just 7

float32

float32 : Endianness -> Decoder Float

Decode four bytes as a float.

Examples

Bytes.width (Bytes.Encode.encode (Bytes.Encode.float32 BE 1.5)) == 4
decode (float32 BE) (Bytes.Encode.encode (Bytes.Encode.float32 BE 1.5)) == Just 1.5

float64

float64 : Endianness -> Decoder Float

Decode eight bytes as a float.

Examples

Bytes.width (Bytes.Encode.encode (Bytes.Encode.float64 BE 1.5)) == 8
decode (float64 BE) (Bytes.Encode.encode (Bytes.Encode.float64 BE 1.5)) == Just 1.5

string

string : Int -> Decoder String

Decode n UTF-8 bytes as a string.

Most protocols store the width of the string right before the content:

Examples

sizedString : Decoder String
sizedString =
    unsignedInt32 BE
        |> andThen string

decode (string 2) (Bytes.Encode.encode (Bytes.Encode.string "hi")) == Just "hi"

bytes

bytes : Int -> Decoder Bytes

Copy n bytes into a new Bytes value.

Examples

decode (bytes 2) (Bytes.Encode.encode (Bytes.Encode.string "hi"))
    |> Maybe.map Bytes.width == Just 2

map

map : (a -> b) -> Decoder a -> Decoder b

Transform a decoded value.

Examples

negativeInt8 : Decoder Int
negativeInt8 =
    map negate unsignedInt8

map2

map2 : (a -> b -> result) -> Decoder a -> Decoder b -> Decoder result

Combine two decoders.

Examples

type alias Point =
    { x : Float
    , y : Float
    }

point : Decoder Point
point =
    map2 (\x y -> { x = x, y = y })
        (float32 BE)
        (float32 BE)

map3

map3 : (a -> b -> c -> result) -> Decoder a -> Decoder b -> Decoder c -> Decoder result

Combine three decoders.

Examples

map3 (\a b c -> (a, b, c))
    unsignedInt8
    unsignedInt8
    unsignedInt8

map4

map4 : (a -> b -> c -> d -> result) -> Decoder a -> Decoder b -> Decoder c -> Decoder d -> Decoder result

Combine four decoders.

Examples

map4 (\a b c d -> (a, b, c, d))
    unsignedInt8
    unsignedInt8
    unsignedInt8
    unsignedInt8

map5

map5 : (a -> b -> c -> d -> e -> result) -> Decoder a -> Decoder b -> Decoder c -> Decoder d -> Decoder e -> Decoder result

Combine five decoders.

Examples

map5 (\a b c d e -> (a, b, c, d, e))
    unsignedInt8
    unsignedInt8
    unsignedInt8
    unsignedInt8
    unsignedInt8

andThen

andThen : (a -> Decoder b) -> Decoder a -> Decoder b

Decode a value, then choose the next decoder.

Examples

sizedString : Decoder String
sizedString =
    unsignedInt32 BE
        |> andThen string

succeed

succeed : a -> Decoder a

Always succeed with a value (consume no bytes).

Examples

maybe : Decoder a -> Decoder (Maybe a)
maybe decoder =
    let
        helper n =
            if n == 0 then
                succeed Nothing
            else
                map Just decoder
    in
    unsignedInt8
        |> andThen helper

fail

fail : Decoder a

Always fail.

Examples

pickDecoder : Int -> Decoder Distance
pickDecoder tag =
    case tag of
        0 ->
            map Yards (float32 BE)

        1 ->
            map Meters (float32 BE)

        _ ->
            fail

loop

loop : state -> (state -> Decoder (Step state a)) -> Decoder a

Decode with a stateful loop. The callback returns a decoder for a Step: Loop continues with an updated state; Done yields the final value.

Examples

list : Decoder a -> Decoder (List a)
list decoder =
    unsignedInt32 BE
        |> andThen (\len -> loop (len, []) (listStep decoder))

listStep : Decoder a -> (Int, List a) -> Decoder (Step (Int, List a) (List a))
listStep decoder (n, xs) =
    if n <= 0 then
        succeed (Done xs)
    else
        map (\x -> Loop (n - 1, x :: xs)) decoder