binary

package
v1.2.128 Latest Latest
Warning

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

 Go to latest Published: Jan 13, 2025 License: MIT Imports: 11 Imported by: 0

README

Binary marshaling utility

This utility is a set of helper functions to implement MarshalBinary() and UnmarshalBinary() methods in an easy and convenient way. Users sometime would like to implement their own manual binary serialization without using a reflection. This enables better performance (no reflection required) and smaller object size (no headers or schema is stored, only the pure data). This implementation (like protobuf) is using the actual field value to determine the size of storage int8, int16, int32, int64) to store the data. But, unlike protobuf, this implementation is using the byte size (int8) as the minimal storage unit. it will not save more than on field in a single byte to avoid BigEndian/LittleEndian encoding issues.

The current implementation does not support versioning so the user must keep the same order in the MarshalBinary() and UnmarshalBinary() methods

Marshal and Unmarshal Example

type SampleObject struct {
	Timestamp   entity.Timestamp
	IntValue    int
	Int32Value  int32
	Int64Value  int64
	IntArray    []int
	StringValue string
	StringArray []string
}

// MarshalBinary convert current structure to a minimal wire-format byte array
func (s *SampleObject) MarshalBinary() (data []byte, err error) {
    w := binary.NewWriter()
    w.Timestamp(s.Timestamp).Int(s.IntValue).Int32(s.Int32Value).Int64(s.Int64Value).IntArray(s.IntArray).String(s.StringValue).StringArray(s.StringArray)
    return w.GetBytes(), nil
}

// UnmarshalBinary reads a wire-format byte array to fill the current structure
func (s *SampleObject) UnmarshalBinary(data []byte) (e error) {
    r := binary.NewReader(data)
    if s.Timestamp, e = r.Timestamp(); e != nil {
        return e
    }
    if s.IntValue, e = r.Int(); e != nil {
        return e
    }
    if s.Int32Value, e = r.Int32(); e != nil {
        return e
    }
    if s.Int64Value, e = r.Int64(); e != nil {
        return e
    }
    if s.IntArray, e = r.IntArray(); e != nil {
        return e
    }
    if s.StringValue, e = r.String(); e != nil {
        return e
    }
    if s.StringArray, e = r.StringArray(); e != nil {
        return e
    }
    return nil
}

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrInvalidIPAddress = errors.New("invalid ip address")
View Source 
var ErrNotIPv4Address = errors.New("not an IPv4 addres")
View Source 
var ErrNotIPv6Address = errors.New("not an IPv6 addres")

Functions

func BigIntToIPv6 added in v1.2.66 

func BigIntToIPv6(ipaddr big.Int) net.IP

BigIntToIPv6 converts IP address of version 6 from big integer to net.IP representation.

func IPv4ToInt added in v1.2.66 

func IPv4ToInt(ipaddr net.IP) (uint32, error)

IPv4ToInt converts IP address of version 4 from net.IP to uint32 representation.

func IPv6ToBigInt added in v1.2.66 

func IPv6ToBigInt(ipaddr net.IP) (*big.Int, error)

IPv6ToBigInt converts IP address of version 6 from net.IP to math big integer representation.

func IPv6ToInt added in v1.2.66 

func IPv6ToInt(ipaddr net.IP) ([2]uint64, error)

IPv6ToInt converts IP address of version 6 from net.IP to uint64 array representation. Return value contains high integer value on the first place and low integer value on second place.

func IntToIPv4 added in v1.2.66 

func IntToIPv4(ipaddr uint32) net.IP

IntToIPv4 converts IP address of version 4 from integer to net.IP representation.

func IntToIPv6 added in v1.2.66 

func IntToIPv6(high, low uint64) net.IP

IntToIPv6 converts IP address of version 6 from integer (high and low value) to net.IP representation.

Types

type Reader 

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

Reader manages the reading of binary data

func NewReader 

func NewReader(data []byte) *Reader

NewReader will initialize a new instance of writer

func (*Reader) Bool 

func (r *Reader) Bool() (bool, error)

Bool read boolean value

func (*Reader) Close 

func (r *Reader) Close() (err error)

Close will close the reader

func (*Reader) Float32 

func (r *Reader) Float32() (float32, error)

Float32 read float 32 bit value (single)

func (*Reader) Float64 

func (r *Reader) Float64() (float64, error)

Float64 read float 64 bit value (double)

func (*Reader) IP added in v1.2.66 

func (r *Reader) IP() (string, error)

IP read encoded IP value that can be represented as uint32 (IPv4), bigInt (IPv6) or string (dns) In order to parse header correctly, we need to read the header first: 1: IP represented as string, 4: IP represented as IPv4 int (uint32), 6: IP represented as IPv6 bigInt (2 * uint64)

func (*Reader) IPArray added in v1.2.66 

func (r *Reader) IPArray() ([]string, error)

IPArray will encode a list of IPv4 or IPv6 to byte array, each IP is stored as defined in the IP() method

func (*Reader) Int 

func (r *Reader) Int() (int, error)

Int read integer value

func (*Reader) Int16 

func (r *Reader) Int16() (int16, error)

Int16 read int 16 bit value

func (*Reader) Int32 

func (r *Reader) Int32() (int32, error)

Int32 read int 32 bit value

func (*Reader) Int64 

func (r *Reader) Int64() (int64, error)

Int64 read int 64 bit value

func (*Reader) Int8 

func (r *Reader) Int8() (int8, error)

Int8 read int 8 bit value

func (*Reader) IntArray 

func (r *Reader) IntArray() ([]int, error)

IntArray read variable length array of int values

func (*Reader) Object 

func (r *Reader) Object() (result []byte, err error)

Object read an arbitrary byte array representing an object

func (*Reader) ObjectArray 

func (r *Reader) ObjectArray() ([][]byte, error)

ObjectArray read variable length array of arbitrary objects

func (*Reader) String 

func (r *Reader) String() (string, error)

String read string value

func (*Reader) StringArray 

func (r *Reader) StringArray() ([]string, error)

StringArray read array of strings

func (*Reader) Timestamp 

func (r *Reader) Timestamp() (entity.Timestamp, error)

Timestamp read int 64 bit value and return it as timestamp

func (*Reader) Uint 

func (r *Reader) Uint() (uint, error)

Uint read unsigned int value

func (*Reader) Uint16 

func (r *Reader) Uint16() (uint16, error)

Uint16 read unsigned int 16 bit value

func (*Reader) Uint32 

func (r *Reader) Uint32() (uint32, error)

Uint32 read unsigned int 32 bit value

func (*Reader) Uint64 

func (r *Reader) Uint64() (v uint64, err error)

Uint64 read unsigned int 64 bit value

func (*Reader) Uint8 

func (r *Reader) Uint8() (uint8, error)

Uint8 read unsigned int 8 bit value

type Writer 

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

Writer manages the writing of the output

func NewWriter 

func NewWriter() *Writer

NewWriter will initialize a new instance of writer

func (*Writer) Bool 

func (w *Writer) Bool(v bool) *Writer

Bool will encode a boolean value

func (*Writer) Close 

func (w *Writer) Close() (err error)

Close will close the writer

func (*Writer) Float32 

func (w *Writer) Float32(v float32) *Writer

Float32 will encode float 32 bit value (single)

func (*Writer) Float32Array 

func (w *Writer) Float32Array(v []float32) *Writer

Float32Array will encode variable length array of float32 values

func (*Writer) Float64 

func (w *Writer) Float64(v float64) *Writer

Float64 will encode float 64 bit value (double)

func (*Writer) Float64Array 

func (w *Writer) Float64Array(v []float64) *Writer

Float64Array will encode variable length array of float64 values

func (*Writer) GetBytes 

func (w *Writer) GetBytes() []byte

GetBytes will expose the underlying bytes

func (*Writer) IP added in v1.2.66 

func (w *Writer) IP(v string) *Writer

IP will encode an IPv4 or IPv6 to byte array, to distinguish between IP types, we need a small uint8 header: 1: IP represented as string, 4: IP represented as IPv4 int (uint32), 6: IP represented as IPv6 bigInt (2 * uint64)

func (*Writer) IPArray added in v1.2.66 

func (w *Writer) IPArray(v []string) *Writer

IPArray will encode a list of IPv4 or IPv6 to byte array, each IP is stored as defined in the IP() method

func (*Writer) Int 

func (w *Writer) Int(v int) *Writer

Int will encode int value

func (*Writer) Int16 

func (w *Writer) Int16(v int16) *Writer

Int16 will encode int 16 bit value (-32,768 .. 32,767)

func (*Writer) Int32 

func (w *Writer) Int32(v int32) *Writer

Int32 will encode int 32 bit value (-2,147,483,648 .. 2,147,483,647)

func (*Writer) Int64 

func (w *Writer) Int64(v int64) *Writer

Int64 will encode int 64 bit value (-9,223,372,036,854,775,808 .. 9,223,372,036,854,775,807)

func (*Writer) Int8 

func (w *Writer) Int8(v int8) *Writer

Int8 will encode unsigned int 8 bit value (-128 .. 127)

func (*Writer) IntArray 

func (w *Writer) IntArray(v []int) *Writer

IntArray will encode variable length array of int values

func (*Writer) Object 

func (w *Writer) Object(v *[]byte) *Writer

Object will encode an arbitrary object represented as variable length byte array

func (*Writer) ObjectArray 

func (w *Writer) ObjectArray(v *[][]byte) *Writer

ObjectArray will encode variable length array of arbitrary objects

func (*Writer) Reset 

func (w *Writer) Reset()

Reset will reset the underlying bytes of the Encoder

func (*Writer) String 

func (w *Writer) String(v string) *Writer

String will encode a variable length string

func (*Writer) StringArray 

func (w *Writer) StringArray(v []string) *Writer

StringArray will encode variable length array of strings

func (*Writer) Timestamp 

func (w *Writer) Timestamp(v entity.Timestamp) *Writer

Timestamp will encode a timestamp (int64) type

func (*Writer) Uint 

func (w *Writer) Uint(v uint) *Writer

Uint will encode unsigned int value

func (*Writer) Uint16 

func (w *Writer) Uint16(v uint16) *Writer

Uint16 will encode unsigned int 16 bit value (0 .. 65,535)

func (*Writer) Uint32 

func (w *Writer) Uint32(v uint32) *Writer

Uint32 will encode unsigned int 32 bit value (0 .. 4,294,967,295)

func (*Writer) Uint64 

func (w *Writer) Uint64(v uint64) *Writer

Uint64 will encode unsigned int 64 bits value (0 .. 18,446,744,073,709,551,615)

func (*Writer) Uint8 

func (w *Writer) Uint8(v uint8) *Writer

Uint8 will encode unsigned int 8 bit value (0 .. 255)

func (*Writer) WriteTo 

func (w *Writer) WriteTo(dest io.Writer) (int64, error)

WriteTo will write to an io.Writer

func (*Writer) Written 

func (w *Writer) Written() int64

Written will return the total number of bytes written

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.