binaryutil

package
v0.3.68 Latest Latest
Warning

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

 Go to latest Published: Aug 14, 2026 License: LGPL-2.1 Imports: 12 Imported by: 3

Documentation

Overview

Package binaryutil 提供二进制读写和字节缓冲辅助工具。

这个包围绕 []byte 提供了常用的二进制序列化基础能力，包括：

  • 可顺序读写的 ByteStream
  • 可复用的字节缓冲 Bytes 与字节池
  • 各类基础类型和定长字节块的大小计算
  • 面向 io.Reader/io.Writer 的拷贝与限长写入辅助

它主要作为协议编解码和底层高性能字节处理的基础设施使用。

Index

Constants

View Source 
const (
	SizeofInt8     = 1
	SizeofInt16    = 2
	SizeofInt32    = 4
	SizeofInt64    = 8
	SizeofUint8    = 1
	SizeofUint16   = 2
	SizeofUint32   = 4
	SizeofUint64   = 8
	SizeofFloat    = 4
	SizeofDouble   = 8
	SizeofByte     = 1
	SizeofBool     = 1
	SizeofBytes16  = 16
	SizeofBytes32  = 32
	SizeofBytes64  = 64
	SizeofBytes128 = 128
	SizeofBytes160 = 160
	SizeofBytes256 = 256
	SizeofBytes512 = 512
)

SizeofInt8 至 SizeofBytes512 是对应定长编码的字节数。

Variables

View Source 
var BytesPool = bytespool.NewCapacityPools(32, math.MaxInt32)

BytesPool 按容量复用字节切片，以降低协议编解码产生的 GC 压力。

View Source 
var EmptyBytes = NewBytes(false, 0)

EmptyBytes 是不可回收的空字节缓冲区。

View Source 
var (
	// ErrInvalidSeekPos 表示读写游标的目标位置超出缓冲区。
	ErrInvalidSeekPos = errors.New("invalid seek position")
)
View Source 
var (
	// ErrLimitReached 表示写入已达到或将超过配置的字节上限。
	ErrLimitReached = errors.New("i/o limit reached")
)

Functions

func CopyToBuff added in v0.3.14 

func CopyToBuff[T io.Reader](p []byte, reader T) (int64, error)

CopyToBuff 调用 reader.Read 一次，将数据读入 p，并将 io.EOF 视为成功。 它不会循环填满 p。

func CopyToByteStream added in v0.3.14 

func CopyToByteStream[T io.Reader](bs *ByteStream, reader T) (int64, error)

CopyToByteStream 调用 reader.Read 一次，将数据读入 bs 的未写区域并推进写游标。 它不会循环填满剩余区域，并将 io.EOF 视为成功。

func SizeofBytes 

func SizeofBytes(v []byte) int

SizeofBytes 返回 WriteBytes 编码 v 所需的字节数，包括长度前缀。

func SizeofString 

func SizeofString(v string) int

SizeofString 返回 WriteString 编码 v 所需的字节数，包括长度前缀。

func SizeofUvarint 

func SizeofUvarint(v uint64) int

SizeofUvarint 返回 v 的 binary.Uvarint 编码字节数。

func SizeofVarint 

func SizeofVarint(v int64) int

SizeofVarint 返回 v 的 binary.Varint 编码字节数。

Types

type ByteStream 

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

ByteStream 在固定字节切片上维护相互独立的读游标和写游标。

ByteStream 不扩容、不复制输入，也不支持并发使用。其内部带有复制检测标记，初始化后应通过指针使用， 不应再按值复制。

func NewBigEndianStream 

func NewBigEndianStream(p []byte) ByteStream

NewBigEndianStream 创建使用大端字节序并直接读写 p 的字节流。

func NewByteStream 

func NewByteStream(p []byte, endian binary.ByteOrder) ByteStream

NewByteStream 创建直接读写 p 的字节流，读写游标均从零开始。 endian 不得为 nil，否则 panic。

func NewLittleEndianStream 

func NewLittleEndianStream(p []byte) ByteStream

NewLittleEndianStream 创建使用小端字节序并直接读写 p 的字节流。

func (*ByteStream) BuffRead 

func (s *ByteStream) BuffRead() []byte

BuffRead 返回读游标之前的共享切片。

func (*ByteStream) BuffUnread 

func (s *ByteStream) BuffUnread() []byte

BuffUnread 返回从读游标到缓冲区末尾的共享切片。

func (*ByteStream) BuffUnwritten 

func (s *ByteStream) BuffUnwritten() []byte

BuffUnwritten 返回从写游标到缓冲区末尾的共享切片。

func (*ByteStream) BuffWritten 

func (s *ByteStream) BuffWritten() []byte

BuffWritten 返回写游标之前的共享切片。

func (*ByteStream) BytesRead 

func (s *ByteStream) BytesRead() int

BytesRead 返回读游标之前的字节数。

func (*ByteStream) BytesUnread 

func (s *ByteStream) BytesUnread() int

BytesUnread 返回从读游标到缓冲区末尾的字节数。

func (*ByteStream) BytesUnwritten 

func (s *ByteStream) BytesUnwritten() int

BytesUnwritten 返回从写游标到缓冲区末尾的字节数。

func (*ByteStream) BytesWritten 

func (s *ByteStream) BytesWritten() int

BytesWritten 返回写游标之前的字节数。

func (*ByteStream) ReadBool 

func (s *ByteStream) ReadBool() (bool, error)

ReadBool 读取一个字节，零解码为 false，其他值解码为 true。

func (*ByteStream) ReadByte 

func (s *ByteStream) ReadByte() (byte, error)

ReadByte 读取一个字节并推进读游标。

func (*ByteStream) ReadBytes 

func (s *ByteStream) ReadBytes() ([]byte, error)

ReadBytes 读取带无符号变长整数长度前缀的字节切片，并复制载荷。 载荷不足时返回 io.ErrUnexpectedEOF，此时长度前缀已被消费。

func (*ByteStream) ReadBytes16 

func (s *ByteStream) ReadBytes16() ([16]byte, error)

ReadBytes16 读取并复制一个 16 字节定长块。

func (*ByteStream) ReadBytes32 

func (s *ByteStream) ReadBytes32() ([32]byte, error)

ReadBytes32 读取并复制一个 32 字节定长块。

func (*ByteStream) ReadBytes64 

func (s *ByteStream) ReadBytes64() ([64]byte, error)

ReadBytes64 读取并复制一个 64 字节定长块。

func (*ByteStream) ReadBytes128 

func (s *ByteStream) ReadBytes128() ([128]byte, error)

ReadBytes128 读取并复制一个 128 字节定长块。

func (*ByteStream) ReadBytes160 

func (s *ByteStream) ReadBytes160() ([160]byte, error)

ReadBytes160 读取并复制一个 160 字节定长块。

func (*ByteStream) ReadBytes256 

func (s *ByteStream) ReadBytes256() ([256]byte, error)

ReadBytes256 读取并复制一个 256 字节定长块。

func (*ByteStream) ReadBytes512 

func (s *ByteStream) ReadBytes512() ([512]byte, error)

ReadBytes512 读取并复制一个 512 字节定长块。

func (*ByteStream) ReadBytesRef 

func (s *ByteStream) ReadBytesRef() ([]byte, error)

ReadBytesRef 读取带无符号变长整数长度前缀的字节切片，并返回底层缓冲区的共享视图。 返回值仅在底层缓冲区保持有效且未被修改期间可用；载荷不足时长度前缀已被消费。

func (*ByteStream) ReadDouble 

func (s *ByteStream) ReadDouble() (float64, error)

ReadDouble 按配置字节序读取 IEEE 754 float64 位表示。

func (*ByteStream) ReadFloat 

func (s *ByteStream) ReadFloat() (float32, error)

ReadFloat 按配置字节序读取 IEEE 754 float32 位表示。

func (*ByteStream) ReadFrom 

func (s *ByteStream) ReadFrom(reader io.Reader) (int64, error)

ReadFrom 调用 reader.Read 一次，将数据读入未写区域并推进写游标；它不会循环填满缓冲区。

func (*ByteStream) ReadInt8 

func (s *ByteStream) ReadInt8() (int8, error)

ReadInt8 读取一个单字节补码整数并推进读游标。

func (*ByteStream) ReadInt16 

func (s *ByteStream) ReadInt16() (int16, error)

ReadInt16 按配置字节序读取一个 int16 并推进读游标。

func (*ByteStream) ReadInt32 

func (s *ByteStream) ReadInt32() (int32, error)

ReadInt32 按配置字节序读取一个 int32 并推进读游标。

func (*ByteStream) ReadInt64 

func (s *ByteStream) ReadInt64() (int64, error)

ReadInt64 按配置字节序读取一个 int64 并推进读游标。

func (*ByteStream) ReadString 

func (s *ByteStream) ReadString() (string, error)

ReadString 读取带无符号变长整数长度前缀的字符串，并复制字符串数据。 载荷不足时返回 io.ErrUnexpectedEOF，此时长度前缀已被消费。

func (*ByteStream) ReadStringRef 

func (s *ByteStream) ReadStringRef() (string, error)

ReadStringRef 读取带无符号变长整数长度前缀的字符串，且不复制底层字节。 返回字符串仅在底层缓冲区保持有效且未被修改期间可用；载荷不足时长度前缀已被消费。

func (*ByteStream) ReadUint8 

func (s *ByteStream) ReadUint8() (uint8, error)

ReadUint8 读取一个 uint8；数据不足时返回 io.ErrUnexpectedEOF 且不推进读游标。

func (*ByteStream) ReadUint16 

func (s *ByteStream) ReadUint16() (uint16, error)

ReadUint16 按配置字节序读取一个 uint16；数据不足时不推进读游标。

func (*ByteStream) ReadUint32 

func (s *ByteStream) ReadUint32() (uint32, error)

ReadUint32 按配置字节序读取一个 uint32；数据不足时不推进读游标。

func (*ByteStream) ReadUint64 

func (s *ByteStream) ReadUint64() (uint64, error)

ReadUint64 按配置字节序读取一个 uint64；数据不足时不推进读游标。

func (*ByteStream) ReadUvarint 

func (s *ByteStream) ReadUvarint() (uint64, error)

ReadUvarint 使用 binary.Uvarint 解码整数；编码不完整或溢出时返回 io.ErrUnexpectedEOF。

func (*ByteStream) ReadVarint 

func (s *ByteStream) ReadVarint() (int64, error)

ReadVarint 使用 binary.Varint 解码整数；编码不完整或溢出时返回 io.ErrUnexpectedEOF。

func (*ByteStream) SeekReadPos 

func (s *ByteStream) SeekReadPos(p int) error

SeekReadPos 将读游标移动到相对原始缓冲区起点的 p；越界时返回 ErrInvalidSeekPos。

func (*ByteStream) SeekWritePos 

func (s *ByteStream) SeekWritePos(p int) error

SeekWritePos 将写游标移动到相对原始缓冲区起点的 p；越界时返回 ErrInvalidSeekPos。

func (*ByteStream) WriteBool 

func (s *ByteStream) WriteBool(v bool) error

WriteBool 将 true 编码为 1、false 编码为 0。

func (*ByteStream) WriteByte 

func (s *ByteStream) WriteByte(v byte) error

WriteByte 写入一个字节并推进写游标。

func (*ByteStream) WriteBytes 

func (s *ByteStream) WriteBytes(v []byte) error

WriteBytes 以无符号变长整数长度前缀加原始字节的格式写入 v。 剩余空间不足时不写入任何数据并返回 io.ErrShortWrite。

func (*ByteStream) WriteBytes16 

func (s *ByteStream) WriteBytes16(v []byte) error

WriteBytes16 写入 16 字节定长块；v 过短时补零，过长时截断。

func (*ByteStream) WriteBytes32 

func (s *ByteStream) WriteBytes32(v []byte) error

WriteBytes32 写入 32 字节定长块；v 过短时补零，过长时截断。

func (*ByteStream) WriteBytes64 

func (s *ByteStream) WriteBytes64(v []byte) error

WriteBytes64 写入 64 字节定长块；v 过短时补零，过长时截断。

func (*ByteStream) WriteBytes128 

func (s *ByteStream) WriteBytes128(v []byte) error

WriteBytes128 写入 128 字节定长块；v 过短时补零，过长时截断。

func (*ByteStream) WriteBytes160 

func (s *ByteStream) WriteBytes160(v []byte) error

WriteBytes160 写入 160 字节定长块；v 过短时补零，过长时截断。

func (*ByteStream) WriteBytes256 

func (s *ByteStream) WriteBytes256(v []byte) error

WriteBytes256 写入 256 字节定长块；v 过短时补零，过长时截断。

func (*ByteStream) WriteBytes512 

func (s *ByteStream) WriteBytes512(v []byte) error

WriteBytes512 写入 512 字节定长块；v 过短时补零，过长时截断。

func (*ByteStream) WriteDouble 

func (s *ByteStream) WriteDouble(v float64) error

WriteDouble 按配置字节序写入 v 的 IEEE 754 位表示。

func (*ByteStream) WriteFloat 

func (s *ByteStream) WriteFloat(v float32) error

WriteFloat 按配置字节序写入 v 的 IEEE 754 位表示。

func (*ByteStream) WriteInt8 

func (s *ByteStream) WriteInt8(v int8) error

WriteInt8 按单字节补码写入 v 并推进写游标。

func (*ByteStream) WriteInt16 

func (s *ByteStream) WriteInt16(v int16) error

WriteInt16 按配置字节序写入 v 并推进写游标。

func (*ByteStream) WriteInt32 

func (s *ByteStream) WriteInt32(v int32) error

WriteInt32 按配置字节序写入 v 并推进写游标。

func (*ByteStream) WriteInt64 

func (s *ByteStream) WriteInt64(v int64) error

WriteInt64 按配置字节序写入 v 并推进写游标。

func (*ByteStream) WriteString 

func (s *ByteStream) WriteString(v string) error

WriteString 以无符号变长整数长度前缀加 UTF-8 原始字节的格式写入 v。 剩余空间不足时不写入任何数据并返回 io.ErrShortWrite。

func (*ByteStream) WriteTo 

func (s *ByteStream) WriteTo(writer io.Writer) (int64, error)

WriteTo 调用 writer.Write 一次，写出当前未读区域，并按实际写入字节数推进读游标。

func (*ByteStream) WriteUint8 

func (s *ByteStream) WriteUint8(v uint8) error

WriteUint8 写入 v 并推进写游标；空间不足时返回 io.ErrShortWrite。

func (*ByteStream) WriteUint16 

func (s *ByteStream) WriteUint16(v uint16) error

WriteUint16 按配置字节序写入 v；空间不足时返回 io.ErrShortWrite。

func (*ByteStream) WriteUint32 

func (s *ByteStream) WriteUint32(v uint32) error

WriteUint32 按配置字节序写入 v；空间不足时返回 io.ErrShortWrite。

func (*ByteStream) WriteUint64 

func (s *ByteStream) WriteUint64(v uint64) error

WriteUint64 按配置字节序写入 v；空间不足时返回 io.ErrShortWrite。

func (*ByteStream) WriteUvarint 

func (s *ByteStream) WriteUvarint(v uint64) error

WriteUvarint 使用 binary.PutUvarint 编码 v；空间不足时返回 io.ErrShortWrite。

func (*ByteStream) WriteVarint 

func (s *ByteStream) WriteVarint(v int64) error

WriteVarint 使用 binary.PutVarint 编码 v；空间不足时返回 io.ErrShortWrite。

type Bytes added in v0.3.68 

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

Bytes 表示一个可切片、可选池化的字节缓冲区视图。

Bytes 及其 Slice 结果可能共享底层存储。对于可回收缓冲区，所有共享视图只能由其所有者 调用一次 Release；释放后所有视图及 Payload 返回的切片均不得再使用。

func CloneBytes added in v0.3.68 

func CloneBytes(recyclable bool, buff []byte) Bytes

CloneBytes 复制 buff 并创建独立缓冲区。 recyclable 为 true 时缓冲区取自 BytesPool，调用方使用完后必须调用 Release。

func NewBytes added in v0.3.68 

func NewBytes(recyclable bool, size int) Bytes

NewBytes 创建长度为 size 的零值字节缓冲区；负数 size 按零处理。 recyclable 为 true 时缓冲区取自 BytesPool，调用方使用完后必须调用 Release。

func RefBytes added in v0.3.68 

func RefBytes(buff []byte) Bytes

RefBytes 创建直接引用 buff 的不可回收缓冲区，不复制数据。

func (Bytes) Payload added in v0.3.68 

func (bs Bytes) Payload() []byte

Payload 返回当前视图的可修改切片；返回值与 Bytes 共享底层存储。

func (Bytes) Recyclable added in v0.3.68 

func (bs Bytes) Recyclable() bool

Recyclable 报告底层切片是否应归还 BytesPool。

func (Bytes) Release added in v0.3.68 

func (bs Bytes) Release()

Release 将可回收缓冲区归还 BytesPool；不可回收缓冲区调用此方法无效果。 可回收缓冲区释放后及其所有共享视图均不得再使用，也不得重复释放。

func (Bytes) SameRef added in v0.3.68 

func (bs Bytes) SameRef(other Bytes) bool

SameRef 报告两个缓冲区是否具有相同的底层切片起始地址。

func (Bytes) Slice added in v0.3.68 

func (bs Bytes) Slice(low, high int) Bytes

Slice 返回当前视图区间 [low, high) 的共享视图。 索引越界或区间无效时 panic；返回值不会获得独立的 Release 责任。

type BytesWriter 

type BytesWriter struct {
	N     int    // 已写入的字节数。
	Bytes []byte // 目标字节切片。
}

BytesWriter 将数据顺序写入固定字节切片，且不允许一次写入越过剩余空间。

func NewBytesWriter 

func NewBytesWriter(bs []byte) *BytesWriter

NewBytesWriter 创建从 bs 起始位置写入的固定缓冲区 writer。

func (*BytesWriter) Write 

func (l *BytesWriter) Write(p []byte) (int, error)

Write 将 p 完整写入剩余空间；空间不足时不写入任何数据并返回 ErrLimitReached。

type LimitWriter 

type LimitWriter struct {
	Limit int       // 允许写入的总字节数。
	N     int       // 底层 writer 已接受的累计字节数。
	W     io.Writer // 接收数据的底层 writer。
}

LimitWriter 限制写入底层 writer 的累计字节数，并保证超限的单次写入不会触达底层 writer。

func NewLimitWriter 

func NewLimitWriter(w io.Writer, n int) *LimitWriter

NewLimitWriter 创建累计写入上限为 n 的 writer；负数 n 按零处理。

func (*LimitWriter) Write 

func (l *LimitWriter) Write(p []byte) (int, error)

Write 将 p 交给底层 writer；若 p 会使累计字节数超过 Limit，则不写入并返回 ErrLimitReached。 底层 writer 的短写和错误会原样返回，N 按其实际返回的字节数增加。

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.