package binary

import "git.sr.ht/~shulhan/pakakeh.go/lib/binary"

Package binary complement the standard binary package.

Index ¶

• Constants
• func DecodeString(endness Endian, bin []byte) (val string)
• func DecodeUint16(endness Endian, bin []byte) (val uint16)
• func DecodeUint32(endness Endian, bin []byte) (val uint32)
• func DecodeUint64(endness Endian, bin []byte) (val uint64)
• func EncodeString(endness Endian, val string) (bin []byte)
• func EncodeUint16(endness Endian, val uint16) (bin []byte)
• func EncodeUint32(endness Endian, val uint32) (bin []byte)
• func EncodeUint64(endness Endian, val uint64) (bin []byte)
• func SetUint16(endness Endian, bin []byte, val uint16)
• func SetUint32(endness Endian, bin []byte, val uint32)
• func SetUint64(endness Endian, bin []byte, val uint64)
• type ApoFile
• func OpenApo(name string) (apo *ApoFile, err error)
• func (apo *ApoFile) Close() (err error)
• func (apo *ApoFile) ReadAll(data any) (list []ApoMetaData, err error)
• func (apo *ApoFile) Write(meta ApoMeta, data any) (err error)
• type ApoMeta
• type ApoMetaData
• type ApoOp
• type BigEndianBuffer
• func NewBigEndianBuffer(bin []byte) *BigEndianBuffer
• func (beb *BigEndianBuffer) Bytes() []byte
• func (beb *BigEndianBuffer) Read(data any) (n int, err error)
• func (beb *BigEndianBuffer) Reset()
• func (beb *BigEndianBuffer) Seek(off int64, whence int) (ret int64, err error)
• func (beb *BigEndianBuffer) Write(data any) (n int, err error)
• type Endian

Constants ¶

const (
	ApoOpInsert  ApoOp = 0 // Default operation.
	ApoOpUpdate        = 1
	ApoOpReplace       = 2
	ApoOpDelete        = 4
)

List of possible Apo write operation.

Functions ¶

func DecodeString ¶

func DecodeString(endness Endian, bin []byte) (val string)

DecodeString convert binary to string.

func DecodeUint16 ¶

func DecodeUint16(endness Endian, bin []byte) (val uint16)

DecodeUint16 convert binary to uint16.

func DecodeUint32 ¶

func DecodeUint32(endness Endian, bin []byte) (val uint32)

DecodeUint32 convert binary to uint32.

func DecodeUint64 ¶

func DecodeUint64(endness Endian, bin []byte) (val uint64)

DecodeUint64 convert binary to uint64.

func EncodeString ¶

func EncodeString(endness Endian, val string) (bin []byte)

EncodeString convert string to binary as slice of byte. String is encoded by writing the length of string (number of bytes) and then followed by content of string in bytes.

The endian-ness does not affect on how to write the content of string.

func EncodeUint16 ¶

func EncodeUint16(endness Endian, val uint16) (bin []byte)

EncodeUint16 convert uint16 to binary as slice of byte.

func EncodeUint32 ¶

func EncodeUint32(endness Endian, val uint32) (bin []byte)

EncodeUint32 convert uint32 to binary as slice of byte.

func EncodeUint64 ¶

func EncodeUint64(endness Endian, val uint64) (bin []byte)

EncodeUint64 convert uint64 to binary as slice of byte.

func SetUint16 ¶

func SetUint16(endness Endian, bin []byte, val uint16)

SetUint16 write an uint16 value val into bin. This function assume the bin has enought storage, otherwise it would be panic.

func SetUint32 ¶

func SetUint32(endness Endian, bin []byte, val uint32)

SetUint32 write an uint32 value val into bin. This function assume the bin has enought storage, otherwise it would be panic.

func SetUint64 ¶

func SetUint64(endness Endian, bin []byte, val uint64)

SetUint64 write an uint64 value val into bin. This function assume the bin has enought storage, otherwise it would be panic.

Types ¶

type ApoFile ¶

type ApoFile struct {
	// contains filtered or unexported fields
}

ApoFile implement append-only writer that encode the data using binary.Write with binary.BigEndian order. The data to be written must support binary.Write (must contains fixed-size type). Type like string or map will not supported, so does struct with that field. To do that one need to implement io.WriterTo in the type.

The file that writen by ApoFile have the following structure,

Apohead
* ApoMeta data
Apofoot

Each data prepended by ApoMeta as metadata that contains the write operation, the time when its written, and kind of data being writen.

The ApoMeta define the operation to data:

• ApoOpInsert operation insert new data, which should be unique among others.
• ApoOpUpdate operation update indicates that the next data contains update for previous inserted data. The data being updated can be partial or all of it.
• ApoOpReplace operation replace indicated that the next data replace whole previous inserted data.
• ApoOpDelete operation delete the previous inserted data. Which record being deleted is defined inside the data (probably by using some ID).

The update and replace may seems duplicate. The update operation is provided to help the writer to write partial data when needed.

func OpenApo ¶

func OpenApo(name string) (apo *ApoFile, err error)

OpenApo open file for writing in append mode. If the file does not exist, it will be created. Once the file is opened it is ready for write-only.

To open a file for reading use [ReadAofile].

func (*ApoFile) Close ¶

func (apo *ApoFile) Close() (err error)

Close the file.

func (*ApoFile) ReadAll ¶

func (apo *ApoFile) ReadAll(data any) (list []ApoMetaData, err error)

ReadAll read all meta and data from file where all data has the same type. If data implement io.ReaderFrom it will use io.ReaderFrom.ReadForm, otherwise it will use binary.Read.

func (*ApoFile) Write ¶

func (apo *ApoFile) Write(meta ApoMeta, data any) (err error)

Write the meta and data into file. If the data is a type with non-fixed size, like slice, string, or map (or struct with non-fixed size field); it should implement io.WriterTo, otherwise the write will fail.

type ApoMeta ¶

type ApoMeta struct {
	// At contains the timestamp with nanoseconds, in UTC timezone, when
	// Write called.
	At int64

	// Kind define the type of data.
	// The value of this field is defined by user, to know type of data
	// stored for reading later.
	Kind int32

	// Op define the write operation, including: insert, update,
	// replace, or delete.
	Op ApoOp
}

ApoMeta define the metadata for each data.

type ApoMetaData ¶

type ApoMetaData struct {
	Data any
	Meta ApoMeta
}

ApoMetaData contains the meta and data stored on the file.

type ApoOp ¶

type ApoOp byte

ApoOp define the write operation of data.

type BigEndianBuffer ¶

type BigEndianBuffer struct {
	// contains filtered or unexported fields
}

BigEndianBuffer provides backing storage for writing (most of) Go native types into binary in big-endian order. The zero value of BigEndianBuffer is ready to use.

The following basic types are supported for Write and Read: bool, byte, int, float, complex, and string. The slice and array are also supported as long as the slice's element type is one of basic types.

For the string, slice, and array, the Write operation write the dynamic length first as 4 bytes of uint32 and then followed by its content.

For struct, each exported field is written in order. Field with type pointer have single byte flag to indicate whether the value is nil during write or not. If pointer field is nil, the flag will be set to 0, otherwise it will be set to 1.

func NewBigEndianBuffer ¶

func NewBigEndianBuffer(bin []byte) *BigEndianBuffer

NewBigEndianBuffer creates and initializes a new BigEndianBuffer using bin as its initial contents. The new BigEndianBuffer takes control of the bin and the caller should not use bin after this call.

func (*BigEndianBuffer) Bytes ¶

func (beb *BigEndianBuffer) Bytes() []byte

Bytes return the backing storage.

func (*BigEndianBuffer) Read ¶

func (beb *BigEndianBuffer) Read(data any) (n int, err error)

Read the binary value into data by its type.

Like any function that needs to set any type, the instance of parameter data must be passed as pointer, including for slice, excepts as noted below.

Slice with length can be read without passing it as pointer,

s := make([]int, 5)
Read(s)  // OK.

But array with size cannot be read without passing it as pointer,

a := [5]int{}
Read(a)   // Fail, panic: reflect.Value.Addr of unaddressable value.
Read(&a)  // OK.

func (*BigEndianBuffer) Reset ¶

func (beb *BigEndianBuffer) Reset()

Reset the internal storage, start from empty again.

func (*BigEndianBuffer) Seek ¶

func (beb *BigEndianBuffer) Seek(off int64, whence int) (ret int64, err error)

Seek move the write and read position to the offset off. It will return an error if the offset out of range.

func (*BigEndianBuffer) Write ¶

func (beb *BigEndianBuffer) Write(data any) (n int, err error)

Write any data to binary format. The following type of data are ignored: Invalid, Uintptr, Chan, Func, Interface, Map; and will return with (0, nil).

type Endian ¶

type Endian = byte

Endian define the byte order to convert data to binary and vice versa.

const (
	// EndianBig define big-endian order, where bytes stored in
	// left-to-right.
	// For example int16=32767 {0x7F 0xFF} will be stored as is.
	EndianBig Endian = 1

	// EndianLittle define little-endian order, where byte stored in
	// right-to-left.
	// For example int16=32767 {0x7F 0xFF} will be stored as {0xFF 0x7F}
	EndianLitte = 2
)

Source Files ¶

apo_file.go apo_footer.go apo_header.go apo_meta.go apo_meta_data.go big_endian_buffer.go binary.go storage.go