4.5. General purpose serialization

The ARCHIVE module implements general-purpose serialization infrastructure. It provides the Archive type and serialize functions for reading and writing binary data. Custom types are supported by implementing serialize for each type.

All functions and symbols are in “archive” module, use require to get access to it.

require daslib/archive

To correctly support serialization of the specific type, you need to define and implement serialize method for it. For example this is how DECS implements component serialization:

def public serialize ( var arch:Archive; var src:Component )
    arch |> serialize(src.name)
    arch |> serialize(src.hash)
    arch |> serialize(src.stride)
    arch |> serialize(src.info)
    invoke(src.info.serializer, arch, src.data)

Example:

require daslib/archive

    struct Foo {
        a : float
        b : string
    }

    [export]
    def main() {
        var original = Foo(a = 3.14, b = "hello")
        var data <- mem_archive_save(original)
        var loaded : Foo
        data |> mem_archive_load(loaded)
        delete data
        print("a = {loaded.a}, b = {loaded.b}\n")
    }
    // output:
    // a = 3.14, b = hello

4.5.1. Structures

Archive

Archive is a combination of serialization stream, and state (version, and reading status).

Fields:

  • version : uint - Version of the archive format.

  • reading : bool - True if the archive is for reading, false for writing.

  • stream : Serializer? - Serialization stream.

4.5.2. Classes

Serializer

Base class for serializers.

MemSerializer : Serializer

This serializer stores data in memory (in the array<uint8>) internal data buffer current reading offset last error code

MemSerializer.write(bytes: void?; size: int): bool

Appends bytes at the end of the data.

Arguments:

  • bytes : void? implicit

  • size : int

MemSerializer.read(bytes: void?; size: int): bool

Reads bytes from data, advances the reading position.

Arguments:

  • bytes : void? implicit

  • size : int

MemSerializer.error(code: string)

Sets the last error code.

Arguments:

  • code : string

MemSerializer.OK(): bool

Implements ‘OK’ method, which returns true if the serializer is in a valid state.

MemSerializer.extractData(): array<uint8>

Extract the data from the serializer.

MemSerializer.getCopyOfData(): array<uint8>

Returns copy of the data from the serializer.

MemSerializer.getLastError(): string

Returns last serialization error.

MemSerializer(): MemSerializer

Initialize the serializer for reading or writing.

MemSerializer(from: array<uint8>): MemSerializer

Initialize the serializer for reading from the given data.

Arguments:

  • from : array<uint8>

4.5.3. Serialization

read_raw(arch: Archive; value: auto(TT)&): auto

Read raw data (straight up bytes for raw pod)

Arguments:

4.5.3.1. serialize

serialize(arch: Archive; value: array<auto(TT)>): auto

Serializes array. Bulk memcpy for raw workhorse types, element-wise otherwise.

Arguments:

  • arch : Archive

  • value : array<auto(TT)>

serialize(arch: Archive; value: auto(TT)&): auto
serialize(arch: Archive; value: auto(TT)&): auto
serialize(arch: Archive; value: auto(TT)&): auto
serialize(arch: Archive; value: auto(TT)&): auto
serialize(arch: Archive; value: auto(TT)&): auto
serialize(arch: Archive; value: auto(TT)?): auto
serialize(arch: Archive; value: auto(TT)[]): auto
serialize(arch: Archive; value: auto(TT)[][]): auto
serialize(arch: Archive; value: auto(TT)[][][]): auto
serialize(arch: Archive; value: auto(TT)[][][][]): auto
serialize(arch: Archive; value: auto(TT)[][][][][]): auto
serialize(arch: Archive; value: auto(TT)[][][][][][]): auto
serialize(arch: Archive; value: float3x3)
serialize(arch: Archive; value: float3x4)
serialize(arch: Archive; value: float4x4)
serialize(arch: Archive; value: string&)
serialize(arch: Archive; value: table<auto(KT), auto(VT)>): auto
serialize_raw(arch: Archive; value: auto(TT)&): auto

Serialize raw data (straight up bytes for raw pod)

Arguments:
write_raw(arch: Archive; value: auto(TT)&): auto

Write raw data (straight up bytes for raw pod)

Arguments:

4.5.4. Memory archive

4.5.4.1. mem_archive_load

mem_archive_load(data: array<uint8>#; t: auto&; canfail: bool = false): bool

Loads the object from a memory archive, reading from a borrowed view without cloning. data must outlive the call. Reinterprets the borrowed view as a regular array; the MemSerializer only reads and never mutates or frees it.

Arguments:

  • data : array<uint8>#

  • t : auto&

  • canfail : bool

mem_archive_load(data: array<uint8>; t: auto&; canfail: bool = false): bool
mem_archive_save(t: auto&): auto

Saves the object to a memory archive. Result is array<uint8> with the serialized data.

Arguments:

  • t : auto&