binio

README

binio

Package binio simplifies io error handling by chain multiple operations together.

go get github.com/humuzhu/binio

Usage

w := binio.NewWriter(writer, binary.BigEndian)
n, err := w.
    WriteByte(req.Version).
    WriteByte(req.NUsername).
    WriteString(req.Username).
    Write(req.Var).
    WriteByte(0x00).
    Reset()

r := binio.NewReader(reader, binary.BigEndian)
n, err := r.
    ReadByte(&req.Version).
    ReadByte(&req.NUsername).
    ReadStringFull(&req.Username, int(req.NUsername)).
    ReadUntil(&req.Var, 0x00, 256).
    Reset()

Documentation

Overview

Package binio simplifies error handling of binary io operations by chain multiple operations together.

Binary Reader Usage

Snippets

r := binio.NewReader(reader, binary.BigEndian)
n, err := r.
	ReadByte(&req.Version).
	ReadByte(&req.NUsername).
	ReadStringFull(&req.Username, int(req.NUsername)).
	ReadUntil(&req.Var, 0x00, 256).
	Reset()

Binary Writer

Snippets

w := binio.NewWriter(writer, binary.BigEndian)
n, err := w.
	WriteByte(req.Version).
	WriteByte(req.NUsername).
	WriteString(req.Username).
	Write(req.Var).
	WriteByte(0x00).
	Reset()

open example for detail usages.

Example

package main

import (
	"bytes"
	"encoding/binary"
	"fmt"
	"io"
	"reflect"

	"github.com/humuzhu/binio"
)

type HandshakeRequest struct {
	Version   byte
	NUsername byte
	Username  string
	Var       []byte // null terminating
}

func (req *HandshakeRequest) WriteTo(writer io.Writer) (int, error) {
	w := binio.NewWriter(writer, binary.BigEndian)
	return w.
		WriteByte(req.Version).
		WriteByte(req.NUsername).
		WriteString(req.Username).
		Write(req.Var).
		WriteByte(0x00).
		Reset()
}

func (req *HandshakeRequest) ReadFrom(reader io.Reader) (int, error) {
	r := binio.NewReader(reader, binary.BigEndian)
	return r.
		ReadByte(&req.Version).
		ReadByte(&req.NUsername).
		ReadStringFull(&req.Username, int(req.NUsername)).
		ReadUntil(&req.Var, 0x00, 256).
		Reset()
}

func main() {
	buf := &bytes.Buffer{}

	req := &HandshakeRequest{
		Version:   0x1,
		NUsername: 5,
		Username:  "binio",
		Var:       []byte{1, 2, 3, 4, 5, 6, 7},
	}
	req.WriteTo(buf)

	cloned := &HandshakeRequest{}
	cloned.ReadFrom(buf)

	fmt.Println(reflect.DeepEqual(req, cloned))
}

Index

• type BinaryReader
  • func NewReader(r io.Reader, order binary.ByteOrder) *BinaryReader
  • func (b *BinaryReader) Accumulate(n int, err error) *BinaryReader
  • func (b *BinaryReader) Err() error
  • func (b *BinaryReader) ReadAll(p *[]byte, max int) *BinaryReader
  • func (b *BinaryReader) ReadAllString(p *string, max int) *BinaryReader
  • func (b *BinaryReader) ReadByte(p *byte) *BinaryReader
  • func (b *BinaryReader) ReadFull(p *[]byte, n int) *BinaryReader
  • func (b *BinaryReader) ReadStringFull(p *string, n int) *BinaryReader
  • func (b *BinaryReader) ReadStringUntil(p *string, delim byte, max int) *BinaryReader
  • func (b *BinaryReader) ReadUint16(p *uint16) *BinaryReader
  • func (b *BinaryReader) ReadUint32(p *uint32) *BinaryReader
  • func (b *BinaryReader) ReadUint64(p *uint64) *BinaryReader
  • func (b *BinaryReader) ReadUntil(p *[]byte, delim byte, max int) *BinaryReader
  • func (b *BinaryReader) Reset() (int, error)
  • func (b *BinaryReader) Size() int
• type BinaryWriter
  • func NewWriter(w io.Writer, order binary.ByteOrder) *BinaryWriter
  • func (b *BinaryWriter) Accumulate(n int, err error) *BinaryWriter
  • func (b *BinaryWriter) Err() error
  • func (b *BinaryWriter) Reset() (int, error)
  • func (b *BinaryWriter) Size() int
  • func (b *BinaryWriter) Write(bs []byte) *BinaryWriter
  • func (b *BinaryWriter) WriteByte(v byte) *BinaryWriter
  • func (b *BinaryWriter) WriteString(s string) *BinaryWriter
  • func (b *BinaryWriter) WriteUint16(v uint16) *BinaryWriter
  • func (b *BinaryWriter) WriteUint32(v uint32) *BinaryWriter
  • func (b *BinaryWriter) WriteUint64(v uint64) *BinaryWriter

Examples

• Package

Types

type BinaryReader

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

BinaryReader is a reader for reading binary data from streams. It has a series of method that can be chained to effectivelly read lots of value. Using the reading chain, you can handle io error without efforts.

func NewReader

func NewReader(r io.Reader, order binary.ByteOrder) *BinaryReader

NewReader creates an BinaryReader to use.

func (*BinaryReader) Accumulate

func (b *BinaryReader) Accumulate(n int, err error) *BinaryReader

Accumulate increments read size and set error state after single read operation.

Accumulate can also be used to accumulate external read operation, for instance, when reads struct with sub struct field, sub struct field may have it's own reading schema. See example for details usage.

func (*BinaryReader) Err

func (b *BinaryReader) Err() error

Err returns the error occurred in previous reading ops. After a read error, any read operation will be skipped until Reset() be called.

func (*BinaryReader) ReadAll

func (b *BinaryReader) ReadAll(p *[]byte, max int) *BinaryReader

ReadAll reads all bytes from reader until io.EOF occured and return those bytes to the location of the pointer and return the BinaryReader instance. If it reached the max size limit, an error io.ErrShortBuffer will be saved to internal state.

func (*BinaryReader) ReadAllString

func (b *BinaryReader) ReadAllString(p *string, max int) *BinaryReader

ReadAllString reads all bytes as string from reader. See ReadAll for details.

func (*BinaryReader) ReadByte

func (b *BinaryReader) ReadByte(p *byte) *BinaryReader

ReadByte reads a byte to the location of the pointer and return the BinaryReader instance.

func (*BinaryReader) ReadFull

func (b *BinaryReader) ReadFull(p *[]byte, n int) *BinaryReader

ReadFull reads a byte slice of size n to the location of the pointer and return the BinaryReader instance. The slice returned is acquired from pool, you may release it to the pool after using or not.

func (*BinaryReader) ReadStringFull

func (b *BinaryReader) ReadStringFull(p *string, n int) *BinaryReader

ReadStringFull reads a string of bytes size n to the location of the pointer and return the BinaryReader instance.

func (*BinaryReader) ReadStringUntil

func (b *BinaryReader) ReadStringUntil(p *string, delim byte, max int) *BinaryReader

ReadStringUntil continue read bytes until meet the delim and return the bytes as string to the location of the pointer and return the BinaryReader instance.

The delim will be dropped in the result.

If it reached the max size limit, an error io.ErrShortBuffer will be saved to internal state.

Note that this function read bytes one by one, hopefully you may use a buffered reader underlying.

https://github.com/humuzhu/bufiopool has a buffered reader pool you can use.

func (*BinaryReader) ReadUint16

func (b *BinaryReader) ReadUint16(p *uint16) *BinaryReader

ReadUint16 reads a uint16 to the location of the pointer and return the BinaryReader instance.

func (*BinaryReader) ReadUint32

func (b *BinaryReader) ReadUint32(p *uint32) *BinaryReader

ReadUint32 reads a uint32 to the location of the pointer and return the BinaryReader instance.

func (*BinaryReader) ReadUint64

func (b *BinaryReader) ReadUint64(p *uint64) *BinaryReader

ReadUint64 reads a uint64 to the location of the pointer and return the BinaryReader instance.

func (*BinaryReader) ReadUntil

func (b *BinaryReader) ReadUntil(p *[]byte, delim byte, max int) *BinaryReader

ReadUntil continue read bytes until meet the delim and return the bytes to the location of the pointer and return the BinaryReader instance.

The delim will be dropped in the result.

If it reached the max size limit, an error io.ErrShortBuffer will be saved to internal state.

Note that this function read bytes one by one, hopefully you may use a buffered reader underlying.

https://github.com/humuzhu/bufiopool has a buffered reader pool you can use.

The slice returned is acquired from pool, you may release it to the pool after using or not.

func (*BinaryReader) Reset

func (b *BinaryReader) Reset() (int, error)

Reset resets read size and error state, and return old state. Generally speaking, you call Reset() at the end of chain.

func (*BinaryReader) Size

func (b *BinaryReader) Size() int

Size returns how many bytes readed before error occurs.

type BinaryWriter

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

BinaryWriter is a writer for writing binary data to streams. It has a series of method that can be chained to effectivelly write lots of value. Using the writing chain, you can handle io error without efforts.

To write effectively, you may use an bufferd writer underlying. https://github.com/humuzhu/bufiopool has a buffered writer pool you can use.

func NewWriter

func NewWriter(w io.Writer, order binary.ByteOrder) *BinaryWriter

NewWriter creates an BinaryWriter to use.

func (*BinaryWriter) Accumulate

func (b *BinaryWriter) Accumulate(n int, err error) *BinaryWriter

Accumulate increments written size and set error state after single write operation.

Accumulate can also be used to accumulate external write operation, for instance, when writes struct with sub struct field, sub struct field may have it's own writing schema. See example for details usage.

func (*BinaryWriter) Err

func (b *BinaryWriter) Err() error

Err returns the error occurred in previous writing ops. After a write error, any write operation will be skipped until Reset() be called.

func (*BinaryWriter) Reset

func (b *BinaryWriter) Reset() (int, error)

Reset resets written size and error state, and return old state. Generally speaking, you call Reset() at the end of chain.

func (*BinaryWriter) Size

func (b *BinaryWriter) Size() int

Size returns how many bytes written before error occurs.

func (*BinaryWriter) Write

func (b *BinaryWriter) Write(bs []byte) *BinaryWriter

Write write a byte slice to the underlying writer and return the BinaryWriter instance.

func (*BinaryWriter) WriteByte

func (b *BinaryWriter) WriteByte(v byte) *BinaryWriter

WriteByte write a byte to the underlying writer and return the BinaryWriter instance.

func (*BinaryWriter) WriteString

func (b *BinaryWriter) WriteString(s string) *BinaryWriter

WriteString write a string to the underlying writer and return the BinaryWriter instance.

func (*BinaryWriter) WriteUint16

func (b *BinaryWriter) WriteUint16(v uint16) *BinaryWriter

WriteUint16 write a uint16 to the underlying writer and return the BinaryWriter instance.

func (*BinaryWriter) WriteUint32

func (b *BinaryWriter) WriteUint32(v uint32) *BinaryWriter

WriteUint32 write a uint32 to the underlying writer and return the BinaryWriter instance.

func (*BinaryWriter) WriteUint64

func (b *BinaryWriter) WriteUint64(v uint64) *BinaryWriter

WriteUint64 write a uint64 to the underlying writer and return the BinaryWriter instance.