binny

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 14, 2023 License: Apache-2.0 Imports: 13 Imported by: 2

README

binny.v2 GoDoc Status Build Status

Extremely simple binary Marshaler/Unmarshaler.

Due to the nature of the format, it supports streaming very well as long as both machines support the same endianness.

Usage

Encoding:
val := SomeStruct{.........}

enc := binny.NewEncoder(w)
if err := enc.Encode(&val); err != nil {
	// handle err
}
enc.Flush() // Flush is needed since we use `bufio.Writer` internally.

// or

data, err := binny.Marshal(val)

Decoding

var val SomeStruct

dec := binny.NewDecoder(r)
if err := dec.Decode(&val); err != nil {
	// handle err
}

// or

err := binny.Unmarshal(bytes, &val)

TODO

  • Allow generic decoding, (aka var v interface{}; Unmarshal(b, &v)), like JSON.
  • Optimize Marshal/Unmarshal and use a pool.
  • More tests, specifically for decoding.
  • Make this readme actually readable by humans.
  • Clean up the tests.
  • Drop unsafe operations with numbers once 1.7 gets released.

Format

type size (bytes)
complex128 16
int, uint 1-8
float32 4
float64, complex64 8
bool, struct{} 1
varint, varuint 1-10 
entry = [field-type][value]

switch(field-type) {
	case string, []byte, [...]byte:
		value = [len(v)][bytes-of-v]
	case map:
		value = [len(v)][entry(key0)][entry(v0)]...[entry(keyN)][entry(vN)][EOV]
	case slice:
		value = [len(v)][entry(idx0)]...[entry(idxN)]EOV
	case struct:
		// fields with default value / nil are omited,
		// keep that in mind if you marshal a struct and unmarshal it to a map
		value = [stringEntry(field0Name)][entry(field0Value)]...[stringEntry(fieldNameN)][entry(fieldValueN)][EOV]
	case int*, uint*:
		field-type = [smallest type to fit the value]
		value = [the value in machine-dependent-format, most likely will change to LE at one point]
}

Documentation

Index

Constants

View Source 
const DefaultDecoderBufferSize = 4096
View Source 
const DefaultEncoderBufferSize = 4096

Variables

View Source 
var (
	// ErrNoPointer gets returned if the user passes a non-pointer to Decode
	ErrNoPointer = errors.New("can't decode to a non-pointer")
)
View Source 
var (
	ErrUnsupportedType = errors.New("unsupported encoding type")
)

Functions

func Marshal 

func Marshal(v interface{}) ([]byte, error)

Marshal is an alias for (sync.Pool'ed) NewEncoder(bytes.NewBuffer()).Encode(v)

func Unmarshal 

func Unmarshal(b []byte, v interface{}) error

Unmarshal is an alias for (sync.Pool'ed) NewDecoder(bytes.NewReader(b)).Decode(v)

Types

type Decoder 

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

A Decoder reads binary data from an input stream, it also does a little bit of buffering.

func NewDecoder 

func NewDecoder(r io.Reader) *Decoder

NewDecoder is an alias for NewDecoder(r, DefaultDecoderBufferSize)

func NewDecoderSize 

func NewDecoderSize(r io.Reader, sz int) *Decoder

NewDecoder returns a new decoder that reads from r with specific buffer size.

The decoder introduces its own buffering and may read data from r beyond the requested values.

func (*Decoder) Decode 

func (dec *Decoder) Decode(v interface{}) (err error)

Decode reads the next binny-encoded value from its input and stores it in the value pointed to by v.

func (*Decoder) Read 

func (dec *Decoder) Read(p []byte) (int, error)

Read allows the Decoder to be used as an io.Reader, note that internally this calls io.ReadFull().

func (*Decoder) ReadBinary 

func (dec *Decoder) ReadBinary(v encoding.BinaryUnmarshaler) error

ReadBinary decodes and reads an object that implements the `encoding.BinaryUnmarshaler` interface.

func (*Decoder) ReadBool 

func (dec *Decoder) ReadBool() (bool, error)

ReadBool returns a bool or an error.

func (*Decoder) ReadBytes 

func (dec *Decoder) ReadBytes() ([]byte, error)

ReadBytes returns a byte slice.

func (*Decoder) ReadComplex128 

func (dec *Decoder) ReadComplex128() (complex128, error)

ReadComplex128 returns a complex128 or an error.

func (*Decoder) ReadComplex64 

func (dec *Decoder) ReadComplex64() (complex64, error)

ReadComplex64 returns a complex64 or an error.

func (*Decoder) ReadFloat32 

func (dec *Decoder) ReadFloat32() (float32, error)

ReadFloat32 returns a float32 or an error.

func (*Decoder) ReadFloat64 

func (dec *Decoder) ReadFloat64() (float64, error)

ReadFloat64 returns a float64 or an error.

func (*Decoder) ReadGob 

func (dec *Decoder) ReadGob(v gob.GobDecoder) error

ReadGob decodes and reads an object that implements the `gob.GobDecoder` interface.

func (*Decoder) ReadInt 

func (dec *Decoder) ReadInt() (int64, uint8, error)

ReadInt retruns an int/varint value and the size of it (8, 16, 32, 64) or an error.

func (*Decoder) ReadInt16 

func (dec *Decoder) ReadInt16() (int16, error)

func (*Decoder) ReadInt32 

func (dec *Decoder) ReadInt32() (int32, error)

func (*Decoder) ReadInt64 

func (dec *Decoder) ReadInt64() (int64, error)

func (*Decoder) ReadInt8 

func (dec *Decoder) ReadInt8() (int8, error)

func (*Decoder) ReadString 

func (dec *Decoder) ReadString() (string, error)

ReadBytes returns a string.

func (*Decoder) ReadUint 

func (dec *Decoder) ReadUint() (v uint64, sz uint8, err error)

ReadUint retruns an uint/varuint value and the size of it (8, 16, 32, 64) or an error.

func (*Decoder) ReadUint16 

func (dec *Decoder) ReadUint16() (uint16, error)

func (*Decoder) ReadUint32 

func (dec *Decoder) ReadUint32() (uint32, error)

func (*Decoder) ReadUint64 

func (dec *Decoder) ReadUint64() (uint64, error)

func (*Decoder) ReadUint8 

func (dec *Decoder) ReadUint8() (uint8, error)

func (*Decoder) ReadVarInt 

func (dec *Decoder) ReadVarInt() (int64, error)

func (*Decoder) ReadVarUint 

func (dec *Decoder) ReadVarUint() (uint64, error)

func (*Decoder) Reset 

func (dec *Decoder) Reset(r io.Reader)

Reset discards any buffered data, resets all state, and switches the buffered reader to read from r.

type DecoderTypeError 

type DecoderTypeError struct {
	Expected string
	Actual   Type
}

func (DecoderTypeError) Error 

func (dte DecoderTypeError) Error() string

type Encoder 

type Encoder struct {
	NoAutoFlushOnEncode bool // Do not auto flush after calling .Encode.
	// contains filtered or unexported fields
}

func NewEncoder 

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new encoder with the DefaultEncoderBufferSize

func NewEncoderSize 

func NewEncoderSize(w io.Writer, sz int) *Encoder

NewEncoder returns a new encoder with the specific buffer size, minimum is 24 bytes.

func (*Encoder) Encode 

func (enc *Encoder) Encode(v interface{}) (err error)

func (*Encoder) Flush 

func (enc *Encoder) Flush() error

Flush writes any buffered data to the underlying io.Writer.

func (*Encoder) Reset 

func (enc *Encoder) Reset(w io.Writer)

Reset discards any unflushed buffered data, clears any error, and resets b to write its output to w.

func (*Encoder) Write 

func (enc *Encoder) Write(p []byte) (n int, err error)

Write writes the contents of p into the buffer. It allows the Encoder to be used as a regular io.Writer since it takes control of the original w.

func (*Encoder) WriteBinary 

func (enc *Encoder) WriteBinary(v encoding.BinaryMarshaler) error

func (*Encoder) WriteBool 

func (enc *Encoder) WriteBool(v bool) error

func (*Encoder) WriteByte 

func (enc *Encoder) WriteByte(v byte) (err error)

func (*Encoder) WriteBytes 

func (enc *Encoder) WriteBytes(v []byte) error

func (*Encoder) WriteComplex128 

func (enc *Encoder) WriteComplex128(v complex128) error

func (*Encoder) WriteComplex64 

func (enc *Encoder) WriteComplex64(v complex64) error

func (*Encoder) WriteFloat32 

func (enc *Encoder) WriteFloat32(v float32) error

func (*Encoder) WriteFloat64 

func (enc *Encoder) WriteFloat64(v float64) error

func (*Encoder) WriteGob 

func (enc *Encoder) WriteGob(v gob.GobEncoder) error

func (*Encoder) WriteInt 

func (enc *Encoder) WriteInt(v int64) error

WriteInt writes u in the smallest possible native size

func (*Encoder) WriteInt16 

func (enc *Encoder) WriteInt16(v int16) error

func (*Encoder) WriteInt32 

func (enc *Encoder) WriteInt32(v int32) error

func (*Encoder) WriteInt64 

func (enc *Encoder) WriteInt64(v int64) error

func (*Encoder) WriteInt8 

func (enc *Encoder) WriteInt8(v int8) (err error)

func (*Encoder) WriteString 

func (enc *Encoder) WriteString(v string) error

func (*Encoder) WriteUint 

func (enc *Encoder) WriteUint(v uint64) error

WriteUint writes v in the smallest possible native size

func (*Encoder) WriteUint16 

func (enc *Encoder) WriteUint16(v uint16) error

func (*Encoder) WriteUint32 

func (enc *Encoder) WriteUint32(v uint32) error

func (*Encoder) WriteUint64 

func (enc *Encoder) WriteUint64(v uint64) error

func (*Encoder) WriteUint8 

func (enc *Encoder) WriteUint8(v uint8) (err error)

func (*Encoder) WriteVarInt 

func (enc *Encoder) WriteVarInt(x int64) error

func (*Encoder) WriteVarUint 

func (enc *Encoder) WriteVarUint(x uint64) error

type Marshaler 

type Marshaler interface {
	MarshalBinny(enc *Encoder) error
}

Marshaler is the interface implemented by objects that can marshal themselves into a binary representation. Implementing this bypasses reflection and is generally faster but not nessecery optimized.

type Type 

type Type byte

Type represents the field type 

const (
	Nil         Type   = iota // nil/empty type
	BoolTrue                  // true
	BoolFalse                 // false
	EmptyStruct               // struct{}
	VarInt                    // Varint 1-10 bytes
	Int8                      //
	Int16                     //
	Int32                     //
	Int64                     //
	VarUint                   // VarUint 1-10 bytes
	Uint8                     //
	Uint16                    //
	Uint32                    //
	Uint64                    //
	Float32                   //
	Float64                   //
	Complex64                 //
	Complex128                //
	String                    //
	ByteSlice                 // []byte
	Struct                    //
	Map                       //
	Slice                     // or array
	Interface                 // interface{}
	Binary                    // encoding BinaryMarshaler/BinaryUnmarshaler
	Gob                       // encoding/gob GobEncoder/GobDecoder
	EOV         = ^Nil        // end-of-value, *any* new types must be added before this line.
)

func (Type) String 

func (i Type) String() string

type Unmarshaler 

type Unmarshaler interface {
	UnmarshalBinny(dec *Decoder) error
}

Unmarshaler is the interface implemented by objects that can unmarshal a binary representation of themselves. Implementing this bypasses reflection and is generally faster.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.