API References

Basic Interfaces

Construct

Constructs.serialize — Function
serialize(cons::Construct, s::IO, obj; contextkw...)
serialize(T, s::IO, obj; contextkw...)
serialize(s::IO, obj; contextkw...)

Serialize an object into a stream.

Constructs.serialize — Method
serialize(cons::Construct, filename::AbstractString, obj; contextkw...)
serialize(T, filename::AbstractString, obj; contextkw...)
serialize(filename::AbstractString, obj; contextkw...)

Serialize an object to the file.

Constructs.serialize — Method
serialize(cons::Construct, obj; contextkw...) -> Vector{UInt8}
serialize(T, obj; contextkw...) -> Vector{UInt8}
serialize(obj; contextkw...) -> Vector{UInt8}

Serialize an object in memory (a byte array).

Constructs.deserialize — Function
deserialize(cons::Construct{T}, s::IO; contextkw...) -> T
deserialize(T, s::IO; contextkw...) -> T

Deserialize a stream to an object.

Constructs.deserialize — Method
deserialize(cons::Construct{T}, filename::AbstractString; contextkw...) -> T
deserialize(T, filename::AbstractString; contextkw...) -> T

Deserialize a file to an object.

Constructs.deserialize — Method
deserialize(cons::Construct{T}, bytes::AbstractVector{UInt8}; contextkw...) -> T
deserialize(T, bytes::AbstractVector{UInt8}; contextkw...) -> T

Deserialize a byte array to an object.

Constructs.estimatesize — Function
estimatesize(cons::Construct; contextkw...) -> ConstructSize
estimatesize(T; contextkw...) -> ConstructSize

Estimate the size of the type.

Constructs.default — Function
default(cons::Construct{T}; contextkw...) -> T
default(T; contextkw...) -> T

Get default value for the construct/type.

This method is usually called for anonymous fields in @construct.

Wrapper

Constructs.subcon — Function
subcon(wrapper::Wrapper{TSub, T}) -> Construct{TSub}

Get sub-construct of wrapper.

Adapter

Constructs.Adapter — Method
Adapter(T|subcon, U) -> Adapter{T, U}

Create a adapter for type U.

Arguments

  • T: the underlying data type.
  • subcon::Construct{T}: the underlying construct.
  • U: the object type.
Constructs.SymmetricAdapter — Method
Adapter(T|subcon, encode) -> SymmetricAdapter{T}
SymmetricAdapter(T|subcon, encode) -> SymmetricAdapter{T}

Create a symmetric adapter based on the encode function.

Arguments

  • subcon::Construct{T}: the underlying construct.
  • encode: the encoding function. the function should have signature like (::T; contextkw...)->T and satisfies involution (encode(encode(x)) == x).
Constructs.encode — Function
encode(adapter::Adapter{TSub, T}, obj::T; contextkw...) -> TSub

Encode the input object when serializing.

Constructs.decode — Function
decode(adapter::Adapter{TSub, T}, obj::TSub; contextkw...) -> T

Decode the output object when deserializing.

Validator

Constructs.Validator — Method
Validator(T|subcon, validate) -> Validator{T}

Create a validator based on the validate function.

Arguments

  • subcon::Construct{T}: the underlying construct.
  • validate: the validate function. the function should have signature like (::T; contextkw...)->Bool.
Constructs.validate — Function
validate(validator::Validator{T}, obj::T; contextkw...) -> Bool

Checks whether the given obj is a valid value for the validator.

Should return a Bool or throw a ValidationError.

Primitive Constructs

Constructs.PrimitiveIO — Type
PrimitiveIO(T) -> Construct{T}

Defines a primitive IO construct for type based on read and write.

This is the default construct for Bool, Char, UInt8, UInt16, UInt32, UInt64, UInt128, Int8, Int16, Int32, Int64, Int128, Float16, Float32 and Float64.

Examples

julia> serialize(PrimitiveIO(Complex{Bool}), im)
2-element Vector{UInt8}:
 0x00
 0x01
Constructs.Singleton — Type
Singleton(T) -> Construct{T}
Singleton(instance::T) -> Construct{T}

Defines an empty construct for singleton type.

This is the default constructor for Nothing and Missing.

Examples

julia> serialize(missing)
UInt8[]

julia> deserialize(Singleton(pi), UInt8[])
π = 3.1415926535897...
Constructs.RaiseError — Type
RaiseError(error::Exception) -> Construct{Union{}}
RaiseError(message::String) -> Construct{Union{}}

Raise specific error or ErrorException(message) when serializing or deserializing any data.

String

Constructs.NullTerminatedString — Type
NullTerminatedString([T], [encoding]) -> Construct{T}

String ending in a terminating null character.

This is the default construct for the subtypes of AbstractString.

Arguments

  • T<:AbstractString: the underlying string type.
  • encoding::Union{Encoding, String}: the string encoding.
Constructs.PaddedString — Type
PaddedString([T], n, [encoding]) -> Construct{T}

String padded to n bytes.

Arguments

  • T<:AbstractString: the underlying string type.
  • n::Integer: the size of the string in bytes.
  • encoding::Union{Encoding, String}: the string encoding.
Constructs.PrefixedString — Type
PrefixedString([T], S|size, [encoding]) -> Construct{T}

String with the size in the header.

Arguments

  • T<:AbstractString: the underlying string type.
  • S<:Integer: the typeof the string size.
  • size::Construct{S}: the construct of the string size (in bytes).
  • encoding::Union{Encoding, String}: the string encoding.

Endianness Adapters

Constructs.LittleEndian — Type
LittleEndian(T) -> Construct{T}

Defines the little endian format T.

Examples

julia> deserialize(LittleEndian(UInt16), b"\x12\x34")
0x3412
Constructs.BigEndian — Type
BigEndian(T) -> Construct{T}

Defines the big endian format T.

Examples

julia> deserialize(BigEndian(UInt16), b"\x12\x34")
0x1234

Enums

Constructs.IntEnum — Method
IntEnum([T|subcon], E) -> Construct{E}

Defines the (exhaustive) enumeration based on integer type T.

This is the default constructor for Base.Enum{T}.

Arguments

  • T<:Integer: the underly integer type, default is the base type of E.
  • subcon::Construct{T}: the underly integer construct.
  • E<:Base.Enum: the enum type.

Examples

julia> @enum Fruit::UInt8 apple=1 banana=2 orange=3

julia> deserialize(IntEnum(Fruit), b"\x02")
banana::Fruit = 0x02

julia> deserialize(IntEnum(Fruit), b"\x04")
ERROR: ArgumentError: invalid value for Enum Fruit: 4
[...]

julia> serialize(IntEnum(UInt16le, Fruit), orange)
2-element Vector{UInt8}:
 0x03
 0x00
Constructs.IntEnum — Method
IntEnum{EnumNonExhaustive}([T|subcon], E) -> Construct{E}

Defines the non-exhaustive enumeration based on integer type T.

Arguments

  • T<:Integer: the underly integer type, default is the base type of E.
  • subcon::Construct{T}: the underly integer construct.
  • E<:Base.Enum: the enum type.

Examples

julia> @enum Fruit::UInt8 apple=1 banana=2 orange=3

julia> deserialize(IntEnum{EnumNonExhaustive}(Fruit), b"\x04")
<invalid #4>::Fruit = 0x04

Sequence

Constructs.Sequence — Type
Sequence(Ts|elements...) -> Construct{Tuple{Ts...}}

Defines the sequence of construct data based on elements.

This is the default constructor for Tuple{Ts...}.

Examples

julia> serialize((true, 0x23))
2-element Vector{UInt8}:
 0x01
 0x23

julia> deserialize(Sequence(Bool, UInt8), b"\xab\xcd")
(true, 0xcd)

Known problems

In Julia 1.6, if the number of Sequence elements is greater than 9, @construct cannot deduce the field type correctly.

Repeaters

Constructs.SizedArray — Type
SizedArray([TA], T|element, size...) -> Construct{TA}

Defines an array with specific size and element.

Arguments

  • TA<:AbstractArray{T}: the target array type, the default is Array{T, N}.
  • T: the type of elements.
  • element::Construct{T}: the construct of elements.
  • size: the size of the array.
Constructs.PrefixedArray — Function
PrefixedArray([TA], S|size, T|element) -> Construct{TA}

Defines an array with its size in the header.

Arguments

  • TA<:AbstractArray{T, N}: the target array type, the default is Array{T, N}.
  • S<:Union{Integer, NTuple{N, Integer}}: the type of the size in the header.
  • T: the type of elements.
  • size::Construct{S}: the construct of size.
  • element::Construct{T}: the construct of elements.
Constructs.GreedyVector — Type
GreedyVector(T|element) -> Construct{Vector{T}}

Defines an unknown-sized vector, which will deserialize elements as much as possible.

Arguments

  • T: the type of elements.
  • element::Construct{T}: the construct of elements.

Conditional

Constructs.Optional — Type
Optional(T|subcon, [default = nothing]) -> Construct{Union{T, TV}}
Optional{TU}(T|subcon, [default = nothing]) -> Construct{TU}

Optional construct with a default value.

Arguments

  • TU: the common type of the construct and the default value.
  • T<:TU: the type of the sub construct.
  • TV<:TU: the type of the default value.
  • subcon::Construct{T}: the sub construct.
  • default::TV: the default value.
Constructs.Try — Type
Try(T1|subcon1, T2|subcon2, ...) -> Construct{Union{T1, T2, ...}}
Try{TU}(T1|subcon1, T2|subcon2, ...) -> Construct{TU}

Try each subcon and use the first successful one.

Examples

Another non-exhaustive enum:

julia> @enum Fruit::UInt8 apple=1 banana=2 orange=3

julia> deserialize(Try(Fruit, UInt8), b"\x02")
banana::Fruit = 0x02

julia> deserialize(Try(Fruit, UInt8), b"\x04")
0x04

Padded

Constructs.Padded — Type
Padded([T|subcon = Nothing], n) -> Construct{T}

Create n-bytes padded data from subcon.

Arguments

  • subcon::Construct{T}: the construct to be padded.
  • n::Integer: the size in bytes after padded.

Examples

julia> deserialize(Padded(Int8, 2), b"\x01\xfc")
1

julia> serialize(Padded(Int8, 2), Int8(1))
2-element Vector{UInt8}:
 0x01
 0x00

Others

Constructs.Const — Type
Const([T|subcon], value::T) -> Construct{T}

Defines a constant value, usually used for file headers.

Arguments

  • subcon::Construct{T}: the underlying construct.
  • value::T: the expected value.

Examples

julia> serialize(Const(0x01), 0x01)
1-element Vector{UInt8}:
 0x01

julia> deserialize(Const(0x01), b"\x01")
0x01
julia> serialize(Const(0x01), 0x03)
ERROR: ValidationError: 3 mismatch the const value 1.
[...]

julia> deserialize(Const(0x01), b"\x02")
ERROR: ValidationError: 2 mismatch the const value 1.
[...]
Constructs.Overwrite — Type
Overwrite(T, value::T) -> Construct{T}
Overwrite(T, getter) -> Construct{T}
Overwrite(subcon::Construct{T}, value::T) -> Construct{T}
Overwrite(subcon::Construct{T}, getter) -> Construct{T}

Overwrite the value when serializing from getter/value. Deserialization simply passes down.

Arguments

  • subcon::Construct{T}: the underlying construct.
  • value::T: the value to overwrite when serializing.
  • getter: the function to overwrite when serializing. the function should have signature like (::T; contextkw...) and satisfies idempotence (getter(getter(x)) == getter(x)).

Examples

julia> serialize(Overwrite(UInt8, 0x01), 2)
1-element Vector{UInt8}:
 0x01

julia> serialize(Overwrite(Int8, abs), -2)
1-element Vector{UInt8}:
 0x02

julia> deserialize(Overwrite(UInt8, 0x01), b"\x05")
0x05

@construct Macro

Constructs.@construct — Macro
@construct [ConstructName] structdefinition

Generate a Construct subtype with ConstructName for the given struct.

Examples

julia> @construct struct Bitmap
           ::Const(b"BMP")
           width::UInt16le
           height::UInt16le
           pixel::SizedArray(UInt8, this.height, this.width)
       end

julia> deserialize(Bitmap, b"BMP\x03\x00\x02\x00\x01\x02\x03\x04\x05\x06")
Bitmap(0x0003, 0x0002, UInt8[0x01 0x03 0x05; 0x02 0x04 0x06])

julia> serialize(Bitmap(2, 3, UInt8[1 2; 4 6; 8 9]))
13-element Vector{UInt8}:
 0x42
 0x4d
 0x50
 0x02
 0x00
 0x03
 0x00
 0x01
 0x04
 0x08
 0x02
 0x06
 0x09

julia> estimatesize(Bitmap)
UnboundedSize(0x0000000000000007)
Constructs.Container — Type
Container{T}

Intermediate container for a struct object when serializing/deserializing it.

Container{T}()

Create an uninitialized container for T.

Examples

julia> Container{Complex{Int64}}()
Container{Complex{Int64}}:
  re: Int64 = #undef
  im: Int64 = #undef
Constructs.Container — Method
Container(object)

Create a container from object.

Examples

julia> Container(3+4im)
Container{Complex{Int64}}:
  re: Int64 = 3
  im: Int64 = 4

Construct Sizes

Constructs.ExactSize — Type
ExactSize(value)

Exact construct size (upper bound and lower bound are same).

Errors

Constructs.PaddedError — Type
PaddedError(msg)

Error thrown when the encoded string or bytes takes more bytes than padding allows, or the pad value is improper.