bencstdcompat

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: May 1, 2026 License: MIT Imports: 5 Imported by: 0

README

bencstd-compat

bencstd-compat is a compatibility-focused Go package for the std encoding used by the deneonet/benc project.

This package is based on the upstream project and preserves compatibility with the encoding used by benc v1.1.7. Its goal is to offer a small, stable API centered around Encoder and Decoder objects instead of the original function-per-call style.

Install

go get github.com/mxmauro/bencstd-compat@latest

API

The package is built around two stateful types:

  • Encoder, which writes into a caller-provided buffer.
  • Decoder, which reads from a caller-provided buffer.

Encoder keeps the current output length internally and exposes it through Len(). Decoder keeps the current read offset internally and exposes it through Offset(). Decoder.Remaining() returns the unread byte count.

Errors are sticky. Once a write or read fails, later operations do not recover silently, and Err() returns the first failure.

Values are encoded and decoded through methods on those objects. The package also provides size helpers for buffer allocation and callback-based helpers for slices and maps.

Basic example

package main

import (
	"fmt"

	bstdcompat "github.com/mxmauro/bencstd-compat"
)

func main() {
	buf := make([]byte, bstdcompat.SizeString("hello")+bstdcompat.SizeInt64())

	enc := bstdcompat.NewEncoder(buf)
	enc.String("hello")
	enc.Int64(-42)
	if enc.Err() != nil {
		panic(enc.Err())
	}

	dec := bstdcompat.NewDecoder(enc.Bytes())
	msg := dec.String()
	n := dec.Int64()
	if dec.Err() != nil {
		panic(dec.Err())
	}

	fmt.Println(msg, n)
}

Dynamic buffer example

package main

import (
	"fmt"

	bstdcompat "github.com/mxmauro/bencstd-compat"
)

func main() {
	enc := bstdcompat.NewDynamicEncoder(64)
	enc.String("hello")
	enc.Int64(-42)
	if enc.Err() != nil {
		panic(enc.Err())
	}

	fmt.Println(enc.Len(), len(enc.Bytes()))
}

License

This repository is licensed under the MIT license.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrBufTooSmall = errors.New("buffer too small")

ErrBufTooSmall reports that the provided buffer does not contain enough bytes.

View Source 
var ErrOverflow = errors.New("varint overflows a 64-bit integer")

ErrOverflow reports that a varint exceeds the supported 64-bit range.

Functions

func DecodeMap 

func DecodeMap[K comparable, V any](d *Decoder, decodeKey func(*Decoder) K, decodeValue func(*Decoder) V) map[K]V

DecodeMap reads a map using decodeKey and decodeValue for each pair.

func DecodeSlice 

func DecodeSlice[T any](d *Decoder, decode func(*Decoder) T) []T

DecodeSlice reads a slice using decode for each element.

func EncodeMap 

func EncodeMap[K comparable, V any](e *Encoder, m map[K]V, encodeKey func(*Encoder, K), encodeValue func(*Encoder, V))

EncodeMap writes a map header, key-value pairs, and sentinel terminator.

func EncodeSlice 

func EncodeSlice[T any](e *Encoder, slice []T, encode func(*Encoder, T))

EncodeSlice writes a slice header, elements, and sentinel terminator.

func SizeBool 

func SizeBool() int

SizeBool returns the encoded size of a boolean.

func SizeByte 

func SizeByte() int

SizeByte returns the encoded size of a byte.

func SizeBytes 

func SizeBytes(v []byte) int

SizeBytes returns the encoded size of a length-prefixed byte slice.

func SizeFixedSlice 

func SizeFixedSlice[T any](slice []T, elemSize int) int

SizeFixedSlice returns the encoded size of a slice with fixed-size elements.

func SizeFloat32 

func SizeFloat32() int

SizeFloat32 returns the encoded size of a 32-bit float.

func SizeFloat64 

func SizeFloat64() int

SizeFloat64 returns the encoded size of a 64-bit float.

func SizeInt 

func SizeInt(v int) int

SizeInt returns the encoded size of a zigzag-encoded signed varint.

func SizeInt16 

func SizeInt16() int

SizeInt16 returns the encoded size of a 16-bit signed integer.

func SizeInt32 

func SizeInt32() int

SizeInt32 returns the encoded size of a 32-bit signed integer.

func SizeInt64 

func SizeInt64() int

SizeInt64 returns the encoded size of a 64-bit signed integer.

func SizeMap 

func SizeMap[K comparable, V any](m map[K]V, kSizer func(K) int, vSizer func(V) int) int

SizeMap returns the encoded size of a map.

func SizeSlice 

func SizeSlice[T any](slice []T, sizer func(T) int) int

SizeSlice returns the encoded size of a slice with dynamic element sizing.

func SizeString 

func SizeString(v string) int

SizeString returns the encoded size of a length-prefixed string.

func SizeUint 

func SizeUint(v uint) int

SizeUint returns the encoded size of an unsigned varint.

func SizeUint16 

func SizeUint16() int

SizeUint16 returns the encoded size of a 16-bit unsigned integer.

func SizeUint32 

func SizeUint32() int

SizeUint32 returns the encoded size of a 32-bit unsigned integer.

func SizeUint64 

func SizeUint64() int

SizeUint64 returns the encoded size of a 64-bit unsigned integer.

Types

type Decoder 

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

Decoder reads the compatibility wire format from a caller-owned buffer.

func NewDecoder 

func NewDecoder(buf []byte) *Decoder

NewDecoder creates a decoder that reads from buf starting at offset zero.

func (*Decoder) Bool 

func (d *Decoder) Bool() bool

Bool reads a boolean encoded as `0` or `1`.

func (*Decoder) Byte 

func (d *Decoder) Byte() byte

Byte reads a single byte.

func (*Decoder) BytesCopied 

func (d *Decoder) BytesCopied() []byte

BytesCopied reads a length-prefixed byte slice into a newly allocated buffer.

func (*Decoder) BytesCropped 

func (d *Decoder) BytesCropped() []byte

BytesCropped reads a length-prefixed byte slice as a window into the source buffer.

func (*Decoder) Err 

func (d *Decoder) Err() error

Err returns the first read error seen by the decoder.

func (*Decoder) Float32 

func (d *Decoder) Float32() float32

Float32 reads a 32-bit float in little-endian IEEE 754 form.

func (*Decoder) Float64 

func (d *Decoder) Float64() float64

Float64 reads a 64-bit float in little-endian IEEE 754 form.

func (*Decoder) Int 

func (d *Decoder) Int() int

Int reads a zigzag-encoded signed varint.

func (*Decoder) Int16 

func (d *Decoder) Int16() int16

Int16 reads a zigzag-encoded 16-bit signed integer in little-endian order.

func (*Decoder) Int32 

func (d *Decoder) Int32() int32

Int32 reads a zigzag-encoded 32-bit signed integer in little-endian order.

func (*Decoder) Int64 

func (d *Decoder) Int64() int64

Int64 reads a zigzag-encoded 64-bit signed integer in little-endian order.

func (*Decoder) Offset 

func (d *Decoder) Offset() int

Offset returns the current read offset.

func (*Decoder) Remaining 

func (d *Decoder) Remaining() int

Remaining returns the unread byte count.

func (*Decoder) SkipBool 

func (d *Decoder) SkipBool()

SkipBool advances past a boolean value.

func (*Decoder) SkipByte 

func (d *Decoder) SkipByte()

SkipByte advances past a single byte.

func (*Decoder) SkipBytes 

func (d *Decoder) SkipBytes()

SkipBytes advances past a length-prefixed byte slice.

func (*Decoder) SkipFloat32 

func (d *Decoder) SkipFloat32()

SkipFloat32 advances past a 32-bit float.

func (*Decoder) SkipFloat64 

func (d *Decoder) SkipFloat64()

SkipFloat64 advances past a 64-bit float.

func (*Decoder) SkipInt 

func (d *Decoder) SkipInt()

SkipInt advances past a signed varint value.

func (*Decoder) SkipInt16 

func (d *Decoder) SkipInt16()

SkipInt16 advances past a 16-bit signed integer.

func (*Decoder) SkipInt32 

func (d *Decoder) SkipInt32()

SkipInt32 advances past a 32-bit signed integer.

func (*Decoder) SkipInt64 

func (d *Decoder) SkipInt64()

SkipInt64 advances past a 64-bit signed integer.

func (*Decoder) SkipMap 

func (d *Decoder) SkipMap()

SkipMap advances past a map payload and sentinel terminator.

func (*Decoder) SkipSlice 

func (d *Decoder) SkipSlice()

SkipSlice advances past a slice payload and sentinel terminator.

func (*Decoder) SkipString 

func (d *Decoder) SkipString()

SkipString advances past a length-prefixed string.

func (*Decoder) SkipUint 

func (d *Decoder) SkipUint()

SkipUint advances past an unsigned varint value.

func (*Decoder) SkipUint16 

func (d *Decoder) SkipUint16()

SkipUint16 advances past a 16-bit unsigned integer.

func (*Decoder) SkipUint32 

func (d *Decoder) SkipUint32()

SkipUint32 advances past a 32-bit unsigned integer.

func (*Decoder) SkipUint64 

func (d *Decoder) SkipUint64()

SkipUint64 advances past a 64-bit unsigned integer.

func (*Decoder) String 

func (d *Decoder) String() string

String reads a length-prefixed string.

func (*Decoder) Uint 

func (d *Decoder) Uint() uint

Uint reads an unsigned varint.

func (*Decoder) Uint16 

func (d *Decoder) Uint16() uint16

Uint16 reads a 16-bit unsigned integer in little-endian order.

func (*Decoder) Uint32 

func (d *Decoder) Uint32() uint32

Uint32 reads a 32-bit unsigned integer in little-endian order.

func (*Decoder) Uint64 

func (d *Decoder) Uint64() uint64

Uint64 reads a 64-bit unsigned integer in little-endian order.

func (*Decoder) UnsafeString 

func (d *Decoder) UnsafeString() string

UnsafeString reads a length-prefixed string using the package's zero-copy string conversion.

type Encoder 

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

Encoder writes the compatibility wire format into a caller-owned buffer.

func NewDynamicEncoder 

func NewDynamicEncoder(initialCapacity int) *Encoder

NewDynamicEncoder creates an encoder backed by an internal growable buffer.

func NewEncoder 

func NewEncoder(buf []byte) *Encoder

NewEncoder creates an encoder that writes into buf starting at offset zero.

func (*Encoder) Bool 

func (e *Encoder) Bool(v bool)

Bool writes a boolean as `0` or `1`.

func (*Encoder) Byte 

func (e *Encoder) Byte(v byte)

Byte writes a single byte.

func (*Encoder) Bytes 

func (e *Encoder) Bytes() []byte

Bytes returns the written prefix of the underlying buffer.

func (*Encoder) BytesValue 

func (e *Encoder) BytesValue(v []byte)

BytesValue writes a length-prefixed byte slice.

func (*Encoder) Err 

func (e *Encoder) Err() error

Err returns the first write error seen by the encoder.

func (*Encoder) Float32 

func (e *Encoder) Float32(v float32)

Float32 writes a 32-bit float in little-endian IEEE 754 form.

func (*Encoder) Float64 

func (e *Encoder) Float64(v float64)

Float64 writes a 64-bit float in little-endian IEEE 754 form.

func (*Encoder) Int 

func (e *Encoder) Int(v int)

Int writes a zigzag-encoded signed varint.

func (*Encoder) Int16 

func (e *Encoder) Int16(v int16)

Int16 writes a zigzag-encoded 16-bit signed integer in little-endian order.

func (*Encoder) Int32 

func (e *Encoder) Int32(v int32)

Int32 writes a zigzag-encoded 32-bit signed integer in little-endian order.

func (*Encoder) Int64 

func (e *Encoder) Int64(v int64)

Int64 writes a zigzag-encoded 64-bit signed integer in little-endian order.

func (*Encoder) Len 

func (e *Encoder) Len() int

Len returns the number of encoded bytes currently written.

func (*Encoder) String 

func (e *Encoder) String(v string)

String writes a length-prefixed UTF-8 string.

func (*Encoder) Uint 

func (e *Encoder) Uint(v uint)

Uint writes an unsigned varint.

func (*Encoder) Uint16 

func (e *Encoder) Uint16(v uint16)

Uint16 writes a 16-bit unsigned integer in little-endian order.

func (*Encoder) Uint32 

func (e *Encoder) Uint32(v uint32)

Uint32 writes a 32-bit unsigned integer in little-endian order.

func (*Encoder) Uint64 

func (e *Encoder) Uint64(v uint64)

Uint64 writes a 64-bit unsigned integer in little-endian order.

func (*Encoder) UnsafeString 

func (e *Encoder) UnsafeString(v string)

UnsafeString writes a length-prefixed string using the package's zero-copy string conversion.

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.