encoding.binary #

Description

encoding.binary contains utility functions for converting between an array of bytes ([]u8) and unsigned integers of various widths (u16, u32, and u64).

Also, it provide functions encode_binary[T]() and decode_binary[T]() which can converting between an array of bytes ([]u8) and generic type T.

There are two ways in which bytes can be encoded:

1. Little endian: The least significant bytes are stored first, followed by the mostsignificant bytes.2. Big endian: The most significant bytes are stored first, opposite to the little endianconvention.

For example, let us take the number 0x12345678. In little endian, the bytes are extracted as 0x78, 0x56, 0x34, and 0x12. In big endian, the bytes are 0x12, 0x34, 0x56, and 0x78.

We follow a similar procedure when we want to go the other way around. Consider the second sequence of bytes in the previous example: 0x12, 0x34, 0x56, and 0x78. If we encode this sequence in little endian format, we get the integer 0x78563412. If we encode this sequence in big endian, we get 0x12345678.

Note > The functions in this module assume appropriately sized u8 arrays. If the sizes > are not valid, the functions will panic.

For generic T data encoding/decoding, you can use encode_binary[T]() and decode_binary[T]():

module main

import encoding.binary

struct MyStruct {
    g_u8 u8
}

struct ComplexStruct {
mut:
    f_u8      u8
    f_u32     u32 @[serialize: '-'] // this field will be skipped
    f_u64     u64
    f_string  string
    f_structs []MyStruct
    f_maps    []map[string]string
}

fn main() {
    a := ComplexStruct{
        f_u8:      u8(10)
        f_u32:     u32(1024)
        f_u64:     u64(2048)
        f_string:  'serialize me'
        f_structs: [
            MyStruct{
                g_u8: u8(1)
            },
            MyStruct{
                g_u8: u8(2)
            },
            MyStruct{
                g_u8: u8(3)
            },
        ]
        f_maps:    [
            {
                'abc': 'def'
            },
            {
                '123': '456'
            },
            {
                ',./': '!@#'
            },
        ]
    }

    b := binary.encode_binary(a)!
    mut c := binary.decode_binary[ComplexStruct](b)!

    // because there skipped field in `a`, a != c
    assert a != c

    c.f_u32 = u32(1024)
    assert a == c
}

fn big_endian_get_u16(v u16) []u8

big_endian_get_u16 creates u8 array from the unsigned 16-bit integer v in big endian order.

fn big_endian_get_u32(v u32) []u8

big_endian_get_u32 creates u8 array from the unsigned 32-bit integer v in big endian order.

fn big_endian_get_u64(v u64) []u8

big_endian_get_u64 creates u8 array from the unsigned 64-bit integer v in big endian order.

fn big_endian_put_u16(mut b []u8, v u16)

big_endian_put_u16 writes a u16 to the first two bytes in the array b in big endian order.

fn big_endian_put_u16_at(mut b []u8, v u16, o int)

big_endian_put_u16_at writes a u16 to the two bytes in the array b at the specified offset in big endian order.

fn big_endian_put_u16_end(mut b []u8, v u16)

big_endian_put_u16_end writes a u16 to the last two bytes in the array b in big endian order.

fn big_endian_put_u16_fixed(mut b [2]u8, v u16)

big_endian_put_u16_fixed writes a u16 to the fixed array b in big endian order.

fn big_endian_put_u32(mut b []u8, v u32)

big_endian_put_u32 writes a u32 to the first four bytes in the array b in big endian order.

fn big_endian_put_u32_at(mut b []u8, v u32, o int)

big_endian_put_u32_at writes a u32 to four bytes in the array b at the specified offset in big endian order.

fn big_endian_put_u32_end(mut b []u8, v u32)

big_endian_put_u32_end writes a u32 to the last four bytes in the array b in big endian order.

fn big_endian_put_u32_fixed(mut b [4]u8, v u32)

big_endian_put_u32_fixed writes a u32 to the fixed array b in big endian order.

fn big_endian_put_u64(mut b []u8, v u64)

big_endian_put_u64 writes a u64 to the first eight bytes in the array b in big endian order.

fn big_endian_put_u64_at(mut b []u8, v u64, o int)

big_endian_put_u64_at writes a u64 to eight bytes in the array b at the specified offset in big endian order.

fn big_endian_put_u64_end(mut b []u8, v u64)

big_endian_put_u64_end writes a u64 to the last eight bytes in the array b at the specified offset in big endian order.

fn big_endian_put_u64_fixed(mut b [8]u8, v u64)

big_endian_put_u64_fixed writes a u64 to the fixed array b in big endian order.

fn big_endian_u16(b []u8) u16

big_endian_u16 creates a u16 from the first two bytes in the array b in big endian order.

fn big_endian_u16_at(b []u8, o int) u16

big_endian_u16_at creates a u16 from two bytes in the array b at the specified offset in big endian order.

fn big_endian_u16_end(b []u8) u16

big_endian_u16_end creates a u16 from two bytes in the array b at the specified offset in big endian order.

fn big_endian_u16_fixed(b [2]u8) u16

big_endian_u16_fixed creates a u16 from the first two bytes in the fixed array b in big endian order.

fn big_endian_u32(b []u8) u32

big_endian_u32 creates a u32 from four bytes in the array b in big endian order.

fn big_endian_u32_at(b []u8, o int) u32

big_endian_u32_at creates a u32 from four bytes in the array b at the specified offset in big endian order.

fn big_endian_u32_end(b []u8) u32

big_endian_u32_end creates a u32 from the last four bytes in the array b in big endian order.

fn big_endian_u32_fixed(b [4]u8) u32

big_endian_u32_fixed creates a u32 from four bytes in the fixed array b in big endian order.

fn big_endian_u64(b []u8) u64

big_endian_u64 creates a u64 from the first eight bytes in the array b in big endian order.

fn big_endian_u64_at(b []u8, o int) u64

big_endian_u64_at creates a u64 from eight bytes in the array b at the specified offset in big endian order.

fn big_endian_u64_end(b []u8) u64

big_endian_u64_end creates a u64 from the last eight bytes in the array b in big endian order.

fn big_endian_u64_fixed(b [8]u8) u64

big_endian_u64_fixed creates a u64 from the fixed array b in big endian order.

fn decode_binary[T](b []u8, config DecodeConfig) !T

decode_binary decode a u8 array into T type data. for decoding struct, you can use @[serialize: '-'] to skip field.

fn encode_binary[T](obj T, config EncodeConfig) ![]u8

encode_binary encode a T type data into u8 array. for encoding struct, you can use @[serialize: '-'] to skip field.

fn little_endian_f32_at(b []u8, o int) f32

fn little_endian_get_u16(v u16) []u8

little_endian_get_u16 creates u8 array from the unsigned 16-bit integer v in little endian order.

fn little_endian_get_u32(v u32) []u8

little_endian_get_u32 creates u8 array from the unsigned 32-bit integer v in little endian order.

fn little_endian_get_u64(v u64) []u8

little_endian_get_u64 creates u8 array from the unsigned 64-bit integer v in little endian order.

fn little_endian_put_u16(mut b []u8, v u16)

little_endian_put_u16 writes a u16 to the first two bytes in the array b in little endian order.

fn little_endian_put_u16_at(mut b []u8, v u16, o int)

little_endian_put_u16_at writes a u16 to the two bytes in the array b at the specified offset in little endian order.

fn little_endian_put_u16_end(mut b []u8, v u16)

little_endian_put_u16_end writes a u16 to the last two bytes of the array b in little endian order.

fn little_endian_put_u16_fixed(mut b [2]u8, v u16)

little_endian_put_u16_fixed writes a u16 to the fixed array b in little endian order.

fn little_endian_put_u32(mut b []u8, v u32)

little_endian_put_u32 writes a u32 to the first four bytes in the array b in little endian order.

fn little_endian_put_u32_at(mut b []u8, v u32, o int)

little_endian_put_u32_at writes a u32 to the four bytes in the array b at the specified offset in little endian order.

fn little_endian_put_u32_end(mut b []u8, v u32)

little_endian_put_u32_end writes a u32 to the last four bytes in the array b in little endian order.

fn little_endian_put_u32_fixed(mut b [4]u8, v u32)

little_endian_put_u32_fixed writes a u32 to the fixed array b in little endian order.

fn little_endian_put_u64(mut b []u8, v u64)

little_endian_put_u64 writes a u64 to the first eight bytes in the array b in little endian order.

fn little_endian_put_u64_at(mut b []u8, v u64, o int)

little_endian_put_u64_at writes a u64 to the eight bytes in the array b at the specified offset in little endian order.

fn little_endian_put_u64_end(mut b []u8, v u64)

little_endian_put_u64_end writes a u64 to the last eight bytes in the array b at in little endian order.

fn little_endian_put_u64_fixed(mut b [8]u8, v u64)

little_endian_put_u64_fixed writes a u64 to the fixed array b in little endian order.

fn little_endian_u16(b []u8) u16

little_endian_u16 creates a u16 from the first two bytes in the array b in little endian order.

fn little_endian_u16_at(b []u8, o int) u16

little_endian_u16_at creates a u16 from two bytes in the array b at the specified offset in little endian order.

fn little_endian_u16_end(b []u8) u16

little_endian_u16_end creates a u16 from the last two bytes of the array b in little endian order.

fn little_endian_u16_fixed(b [2]u8) u16

little_endian_u16_fixed creates a u16 from the fixed array b in little endian order.

fn little_endian_u32(b []u8) u32

little_endian_u32 creates a u32 from the first four bytes in the array b in little endian order.

fn little_endian_u32_at(b []u8, o int) u32

little_endian_u32_at creates a u32 from four bytes in the array b at the specified offset in little endian order.

fn little_endian_u32_end(b []u8) u32

little_endian_u32_end creates a u32 from the last four bytes in the array b in little endian order.

fn little_endian_u32_fixed(b [4]u8) u32

little_endian_u32_fixed creates a u32 from the fixed array b in little endian order.

fn little_endian_u64(b []u8) u64

little_endian_u64 creates a u64 from the first eight bytes in the array b in little endian order.

fn little_endian_u64_at(b []u8, o int) u64

little_endian_u64_at creates a u64 from eight bytes in the array b at the specified offset in little endian order.

fn little_endian_u64_end(b []u8) u64

little_endian_u64_end creates a u64 from the last eight bytes in the array b in little endian order.

fn little_endian_u64_fixed(b [8]u8) u64

little_endian_u64_fixed creates a u64 from the fixed array b in little endian order.

struct DecodeConfig {
pub mut:
	buffer_len int = 1024
	big_endian bool // use big endian decode the data
}

struct EncodeConfig {
pub mut:
	buffer_len int = 1024
	big_endian bool // use big endian encoding the data
}