Bytes.Decode.Extra

Helpers for working with Bytes.Decoders.

list : Int -> Decoder a -> Decoder (List a)

Run a decoder a set amount of times, and collect the result in a list.

import Bytes.Decode
import Bytes.Extra exposing (fromByteValues)




fromByteValues (List.range 0 20)
    |> Bytes.Decode.decode (Bytes.Decode.Extra.list 21 Bytes.Decode.unsignedInt8)
--> Just (List.range 0 20)

byteValues : Int -> Decoder (List Int)

Before the release of [elm/bytes], many packages would use List Int to represent bytes. byteValues aids interaciton between those packages and Bytes.

import Bytes exposing (Bytes)
import Bytes.Decode
import Bytes.Extra exposing (fromByteValues)


input : Bytes
input =
    fromByteValues [ 0x32, 0xFF, 0x53, 0x54, 0x55 ]


Bytes.Decode.decode (byteValues 3) input
--> Just [ 0x32, 0xFF, 0x53 ]

24-bit Integers

One notable use of 24-bit integers is in 24-bit color, a.k.a. "True color".

unsignedInt24 : Endianness -> Decoder Int

Decode three bytes into an integer from 0 to 16777215.

signedInt24 : Endianness -> Decoder Int

Decode three bytes into an integer from -8388608 to 8388607.

Pipeline-style

Json.Decode.Pipeline provides a neat, scalable way for decoding JSON. This module provides a few helpers for adopting a similar style when decoding Bytes.

It is important to note that decoding bytes poses more restrictions than decoding JSON, as bytes are consumed in order, and a maximum of one time. This makes an equivalent to Json.Decode.Pipeline.optional difficult to impossible.

import Bytes exposing (Endianness(..))
import Bytes.Decode exposing (Decoder, succeed, andThen, unsignedInt32, string, float64, decode)
import Bytes.Extra exposing (fromByteValues)


type Status = Downloaded | LocallyGenerated


type alias MyData =
  { id: Int
  , status : Status
  , name: String
  , value: Float
  }


myDataDecoder : Decoder MyData
myDataDecoder =
    succeed MyData
        |> andMap (unsignedInt32 BE)
        |> hardcoded Downloaded
        |> andMap (unsignedInt32 BE |> andThen string)
        |> andMap (float64 BE)




decode myDataDecoder (fromByteValues [0,0,0,252,0,0,0,8,116,104,101,95,110,97,109,101,63,224,0,0,0,0,0,0])
--> Just
-->     { id = 252
-->     , status = Downloaded
-->     , name = "the_name"
-->     , value = 0.5
-->     }

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

andMap behaves in a similar way to Json.Decode.Pipeline.required. It is named andMap to match the naming of similar functions in other packages, and because this package does not provide an equivalent to Json.Decode.Pipeline.optional.

modelDecoder : Decoder Model
modelDecoder =
    succeed Model
        |> andMap (unsignedInt32 BE)
        |> andMap (unsignedInt32 BE |> andThen string)
        |> andMap myCustomTypeDecoder
        |> andMap myCustomBooleanDecoder

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

A neat way to fill in predetermined information that's not part of the data being decoded, similar to Json.Decode.Pipeline.hardcoded.

modelDecoder : Decoder Model
modelDecoder =
    succeed Model
        |> andMap (unsignedInt32 BE)
        |> andMap (unsignedInt32 BE |> andThen string)
        |> hardcoded []
        |> andMap myCustomBooleanDecoder
        |> hardcoded SubModel.default

Skipping bytes

withOffset : Int -> Decoder a -> Decoder a

Sometimes the value you need to decode is preceded by a bunch of bytes you just don't need.

import Bytes exposing (Endianness(..))
import Bytes.Decode exposing (decode, unsignedInt16)
import Bytes.Extra exposing (fromByteValues)


fromByteValues [ 0xff, 0xff, 0xff, 0x21, 0x30 ]
    |> decode (withOffset 3 (unsignedInt16 BE))
--> Just 8496

Extra maps

map6 :

(a -> b -> c -> d -> e -> f -> result)

-> Decoder a

-> Decoder b

-> Decoder c

-> Decoder d

-> Decoder e

-> Decoder f

-> Decoder result

map7 :

(a -> b -> c -> d -> e -> f -> g -> result)

-> Decoder a

-> Decoder b

-> Decoder c

-> Decoder d

-> Decoder e

-> Decoder f

-> Decoder g

-> Decoder result

map8 :

(a -> b -> c -> d -> e -> f -> g -> h -> result)

-> Decoder a

-> Decoder b

-> Decoder c

-> Decoder d

-> Decoder e

-> Decoder f

-> Decoder g

-> Decoder h

-> Decoder result

map9 :

(a -> b -> c -> d -> e -> f -> g -> h -> i -> result)

-> Decoder a

-> Decoder b

-> Decoder c

-> Decoder d

-> Decoder e

-> Decoder f

-> Decoder g

-> Decoder h

-> Decoder i

-> Decoder result

map16 :

(a -> b -> c -> d -> e -> f -> g -> h -> i -> j -> k -> l -> m -> n -> o -> p -> result)

-> Decoder a

-> Decoder b

-> Decoder c

-> Decoder d

-> Decoder e

-> Decoder f

-> Decoder g

-> Decoder h

-> Decoder i

-> Decoder j

-> Decoder k

-> Decoder l

-> Decoder m

-> Decoder n

-> Decoder o

-> Decoder p

-> Decoder result

Working with Results and Maybes

onlyOks : Decoder (Result err a) -> Decoder a

Take a Decoder (Result err a) and make it fail if it decodes an Err.

onlyJusts : Decoder (Maybe a) -> Decoder a

Take a Decoder (Maybe a) and make it fail if it decodes to Nothing.

import Bytes.Extra exposing (fromByteValues)
import Bytes.Decode exposing (decode, map, string)


fromByteValues [ 0x30, 0x30, 0x30, 0x31, 0x30 ] -- "00010"
    |> decode (onlyJusts (map String.toInt (string 5)))
--> Just 10

TSFoster/elm-bytes-extra/1.3.0

Bytes.Decode.Extra

24-bit Integers

Pipeline-style

Skipping bytes

Extra maps

Working with Results and Maybes

Modules