A Codec a
contains a Bytes.Decoder a
and the corresponding a -> Bytes.Encoder
.
A value that knows how to encode and decode a sequence of bytes.
Bytes.Endianness
The direction bytes are ordered in memory. Refer to the elm/bytes docs for more information.
Bytes.Encode.Encoder
Describes how to generate a sequence of bytes.
Bytes
A sequence of bytes. Refer to the elm/bytes docs for more information.
Bytes.Decode.Decoder a
Describes how to turn a sequence of bytes into a nice Elm value.
decoder : Codec a -> Decoder a
Extracts the Decoder
contained inside the Codec
.
decodeValue : Codec a -> Bytes -> Maybe a
Run a Codec
to turn a sequence of bytes into an Elm value.
encoder : Codec a -> a -> Encoder
Extracts the encoding function contained inside the Codec
.
encodeToValue : Codec a -> a -> Bytes
Convert an Elm value into a sequence of bytes.
string : Codec String
Codec
between a sequence of bytes and an Elm String
bool : Codec Basics.Bool
Codec
between a sequence of bytes and an Elm Bool
char : Codec Char
Codec
between a sequence of bytes and an Elm Char
signedInt : Codec Basics.Int
Codec
between a signed 32-bit integer and an Elm Int
.
Use this if the byte ordering and number of bytes used isn't a concern.
unsignedInt : Codec Basics.Int
Codec
between an unsigned 32-bit integer and an Elm Int
.
Use this if the byte ordering and number of bytes used isn't a concern.
float64 : Codec Basics.Float
Codec
between a 64-bit float and an Elm Float
float32 : Codec Basics.Float
Codec
between a 32-bit float and an Elm Float
.
Due to Elm Float
s being 64-bit, encoding and decoding it as a 32-bit float won't exactly equal the original value.
signedInt32 : Endianness -> Codec Basics.Int
Codec
between a signed 32-bit integer and an Elm Int
unsignedInt32 : Endianness -> Codec Basics.Int
Codec
between an unsigned 32-bit integer and an Elm Int
signedInt16 : Endianness -> Codec Basics.Int
Codec
between a signed 16-bit integer and an Elm Int
unsignedInt16 : Endianness -> Codec Basics.Int
Codec
between an unsigned 16-bit integer and an Elm Int
signedInt8 : Codec Basics.Int
Codec
between a signed 8-bit integer and an Elm Int
unsignedInt8 : Codec Basics.Int
Codec
between an unsigned 8-bit integer and an Elm Int
bytes : Codec Bytes
Codec
for Bytes
. This is useful if you wanted to include binary data that you're going to decode elsewhere such as a PNG file.
maybe : Codec a -> Codec (Maybe a)
Represents an optional value.
list : Codec a -> Codec (List a)
Codec
between a sequence of bytes and an Elm List
.
array : Codec a -> Codec (Array a)
Codec
between a sequence of bytes and an Elm Array
.
dict : Codec comparable -> Codec a -> Codec (Dict comparable a)
Codec
between a sequence of bytes and an Elm Dict
.
set : Codec comparable -> Codec (Set comparable)
Codec
between a sequence of bytes and an Elm Set
.
tuple : Codec a -> Codec b -> Codec ( a, b )
Codec
between a sequence of bytes and an Elm Tuple
.
triple : Codec a -> Codec b -> Codec c -> Codec ( a, b, c )
Codec
between a sequence of bytes and an Elm triple.
result : Codec error -> Codec value -> Codec (Result error value)
Codec
for Result
values.
A partially built Codec
for an object.
object : b -> ObjectCodec a b
Start creating a Codec
for an object. You should pass the main constructor as argument.
If you don't have one (for example it's a simple type with no name), you should pass a function that given the field values builds an object.
type alias Point =
{ x : Int
, y : Int
}
pointCodec : Codec Point
pointCodec =
Codec.object Point
|> Codec.field .x Codec.signedInt
|> Codec.field .y Codec.signedInt
|> Codec.buildObject
field : (a -> f) -> Codec f -> ObjectCodec a (f -> b) -> ObjectCodec a b
Specify how to get a value from the object we want to encode and then give a Codec
for that value.
buildObject : ObjectCodec a a -> Codec a
Create a Codec
from a fully specified ObjectCodec
.
A partially built Codec
for a custom type.
custom : match -> CustomCodec match value
Starts building a Codec
for a custom type.
You need to pass a pattern matching function, see the FAQ for details.
type Semaphore
= Red Int String Bool
| Yellow Float
| Green
semaphoreCodec : Codec Semaphore
semaphoreCodec =
Codec.custom
(\redEncoder yellowEncoder greenEncoder value ->
case value of
Red i s b ->
redEncoder i s b
Yellow f ->
yellowEncoder f
Green ->
greenEncoder
)
|> Codec.variant3 0 Red Codec.signedInt Codec.string Codec.bool
|> Codec.variant1 1 Yellow Codec.float64
|> Codec.variant0 2 Green
|> Codec.buildCustom
variant0 : Basics.Int -> v -> CustomCodec (Encoder -> a) v -> CustomCodec a v
Define a variant with 0 parameters for a custom type.
variant1 : Basics.Int -> (a -> v) -> Codec a -> CustomCodec ((a -> Encoder) -> b) v -> CustomCodec b v
Define a variant with 1 parameters for a custom type.
variant2 : Basics.Int -> (a -> b -> v) -> Codec a -> Codec b -> CustomCodec ((a -> b -> Encoder) -> c) v -> CustomCodec c v
Define a variant with 2 parameters for a custom type.
variant3 : Basics.Int -> (a -> b -> c -> v) -> Codec a -> Codec b -> Codec c -> CustomCodec ((a -> b -> c -> Encoder) -> partial) v -> CustomCodec partial v
Define a variant with 3 parameters for a custom type.
variant4 : Basics.Int -> (a -> b -> c -> d -> v) -> Codec a -> Codec b -> Codec c -> Codec d -> CustomCodec ((a -> b -> c -> d -> Encoder) -> partial) v -> CustomCodec partial v
Define a variant with 4 parameters for a custom type.
variant5 : Basics.Int -> (a -> b -> c -> d -> e -> v) -> Codec a -> Codec b -> Codec c -> Codec d -> Codec e -> CustomCodec ((a -> b -> c -> d -> e -> Encoder) -> partial) v -> CustomCodec partial v
Define a variant with 5 parameters for a custom type.
variant6 : Basics.Int -> (a -> b -> c -> d -> e -> f -> v) -> Codec a -> Codec b -> Codec c -> Codec d -> Codec e -> Codec f -> CustomCodec ((a -> b -> c -> d -> e -> f -> Encoder) -> partial) v -> CustomCodec partial v
Define a variant with 6 parameters for a custom type.
variant7 : Basics.Int -> (a -> b -> c -> d -> e -> f -> g -> v) -> Codec a -> Codec b -> Codec c -> Codec d -> Codec e -> Codec f -> Codec g -> CustomCodec ((a -> b -> c -> d -> e -> f -> g -> Encoder) -> partial) v -> CustomCodec partial v
Define a variant with 7 parameters for a custom type.
variant8 : Basics.Int -> (a -> b -> c -> d -> e -> f -> g -> h -> v) -> Codec a -> Codec b -> Codec c -> Codec d -> Codec e -> Codec f -> Codec g -> Codec h -> CustomCodec ((a -> b -> c -> d -> e -> f -> g -> h -> Encoder) -> partial) v -> CustomCodec partial v
Define a variant with 8 parameters for a custom type.
buildCustom : CustomCodec (a -> Encoder) a -> Codec a
Build a Codec
for a fully specified custom type.
map : (a -> b) -> (b -> a) -> Codec a -> Codec b
Transform a Codec
.
constant : a -> Codec a
Create a Codec
that encodes nothing and always decodes as the same value.
lazy : (() -> Codec a) -> Codec a
This is useful for recursive structures that are not easily modeled with recursive
.
type Peano
= Peano (Maybe Peano)
{-| This is the same example used in Codec.recursive but adapted for lazy.
-}
peanoCodec : Codec Peano
peanoCodec =
Codec.maybe (Codec.lazy (\() -> peanoCodec)) |> Codec.map Peano (\(Peano a) -> a)
Warning: lazy
is not stack safe!
If you have something like Peano (Just (Peano Just (...)))
nested within itself sufficiently many times and you try to use peanoCodec
on it, you'll get a stack overflow!
recursive : (Codec a -> Codec a) -> Codec a
Create a Codec
for a recursive data structure.
The argument to the function you need to pass is the fully formed Codec
, see the FAQ for details.
type Peano
= Peano (Maybe Peano)
peanoCodec : Codec Peano
peanoCodec =
Codec.recursive
(\finishedCodec ->
Codec.maybe finishedCodec
|> Codec.map Peano (\(Peano p) -> p)
)
Warning: recursive
is not stack safe!
If you have something like Peano (Just (Peano Just (...)))
nested within itself sufficiently many times and you try to use peanoCodec
on it, you'll get a stack overflow!
customWithIdCodec : Codec Basics.Int -> match -> CustomCodec match value
Same as custom
but here we can choose what codec to use for the integer id we tell apart variants with.
This is useful if, for example, you know you won't have ids outside of the range 0 - 255 and can use unsignedInt8 instead of the default signedInt32 to save some space.