bencv2

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Apr 24, 2024 License: MIT Imports: 8 Imported by: 0

README

Logo

Go Report Card

bencv2 go

The runtime for bencv2 in Golang.
The forward and backward compatibile, lightning-fast and code-generated encoder.

Bencv2 Golang 

package data

ctr Person {
    name string @1
    age uint8 @2
}
 
person := data.Person{
    name: "Jeff",
    age: 25,
}

b, _ := benc.Encode(&person)
----------------------------------------------- ----------------------------------------------------------------

Installation

  • Install bencc
  • Add the runtime: go get github.com/bencv2/go-runtime

Documentation

Find documentation here.

Benchmarks

Find benchmarks here.

Usage

  • Generate some Go code using bencc, shown here
  • Using the generated code:
package main

import (
	"fmt"

	bencv2 "github.com/bencv2/go-runtime"
	person ".../out"
)

func main() {
	benc := bencv2.NewEncoder()

	data := person.Person{
		Age:  25,
		Name: "Jeff",
		Parents: person.Parents{
			Mother: "Janiffy",
			Father: "Johnny",
		},
		Child: person.Child{
			Age:  14,
			Name: "Lil Jeff",
			Parents: person.Parents{
				Mother: "Unknown",
				Father: "Jeff",
			},
		},
	}

	b, err := benc.Encode(&data)
	if err.IsSome() {
		panic(err)
	}

	var res person.Person

	err = benc.Decode(b, &res)
	if err.IsSome() {
		panic(err)
	}

	fmt.Println("decoded --- ", res)
	fmt.Println("original --- ", data)
}

Concurrency:

You have three options to prevent data race(s) using bencv2:

First, using the buffer, before putting it back into the buf pool:

package main

import (
	"fmt"

	bencv2 "github.com/bencv2/go-runtime"
	person "github.com/bencv2/test/out"
)

func main() {
	benc := bencv2.NewEncoder()

	data := person.Person{
		Age:  25,
		Name: "Jeff",
		Parents: person.Parents{
			Mother: "Janiffy",
			Father: "Johnny",
		},
		Child: person.Child{
			Age:  14,
			Name: "Lil Jeff",
			Parents: person.Parents{
				Mother: "Unknown",
				Father: "Jeff",
			},
		},
	}

	for i := 0; i < 10; i++ {
		go func() {
			_, _ = benc.Encode(&data, func(b []byte, err bencv2.Error[string]) {
				if err.IsSome() {
					panic(err)
				}

				fmt.Println(b[2])
			})
		}()
	}
}

Second, disabling buffer-reusing, for independent buffers in each go-routine:

package main

import (
	"fmt"

	bencv2 "github.com/bencv2/go-runtime"
	person "github.com/bencv2/test/out"
)

func main() {
	benc := bencv2.NewEncoder()
	benc.SetBufferReusing(false)

	data := person.Person{
		Age:  25,
		Name: "Jeff",
		Parents: person.Parents{
			Mother: "Janiffy",
			Father: "Johnny",
		},
		Child: person.Child{
			Age:  14,
			Name: "Lil Jeff",
			Parents: person.Parents{
				Mother: "Unknown",
				Father: "Jeff",
			},
		},
	}

	for i := 0; i < 10; i++ {
		go func() {
			b, err := benc.Encode(&data)
			if err.IsSome() {
				panic(err)
			}

			fmt.Println(b[2])
		}()
	}
}

Third, using mutex(s):

package main

import (
	"fmt"
	"sync"

	bencv2 "github.com/bencv2/go-runtime"
	person "github.com/bencv2/test/out"
)

func main() {
	benc := bencv2.NewEncoder()

	data := person.Person{
		Age:  25,
		Name: "Jeff",
		Parents: person.Parents{
			Mother: "Janiffy",
			Father: "Johnny",
		},
		Child: person.Child{
			Age:  14,
			Name: "Lil Jeff",
			Parents: person.Parents{
				Mother: "Unknown",
				Father: "Jeff",
			},
		},
	}

	mtx := sync.RWMutex{}

	for i := 0; i < 10; i++ {
		go func() {
			mtx.Lock()

			b, err := benc.Encode(&data)
			if err.IsSome() {
				panic(err)
			}

			fmt.Println(b[2])

			mtx.Unlock()
		}()
	}
}

Make an choice, based on your requirements.

Future Plans

  • Full-featured documentation
  • Complete BENCv2-Lang Specification
  • Complete BENCv2-Format Specification
  • BCD Improvements and Updates
  • Porting the go-runtime to C++
  • A linter, a syntax-highlighter (vscode extension)
  • Support for Enums
  • Support for Slices and Maps
  • A lot more...

Authors

Documentation

Index

Constants

View Source 
const (
	Container uint8 = iota

	Varint
	LenDlm
	Fixed8
	Fixed16
	Fixed32
	Fixed64
)
View Source 
const ErrBufTooSmall = "buffer too small"

ErrBufTooSmall indicates that the buffer given is too small to decode data.

View Source 
const ErrEof = "eof"

ErrEof indicates not an error, rather indicates that no data can be decoded anymore.

View Source 
const ErrIdIsZero = "specified id cannot be 0"

ErrIdIsZero indicates that the ID may not be 0.

View Source 
const ErrInvalidType = "invalid type"

ErrInvalidType indicates that the decoded type is invalid.

View Source 
const ErrNone = ""

ErrNone indicates that no error occoured.

View Source 
const ErrOverflow = "overflow"

ErrOverflow indicates that the bytes number limit of the type was exceeded.

View Source 
const ErrReuseBufTooSmall = "reuse buffer too small"

ErrReuseBufTooSmall indicates that the buffer is too small to be reused at the specified size.

Variables

This section is empty.

Functions

func EncodeBool added in v1.0.0 

func EncodeBool(n int, b []byte, v bool, id uint16) int

EncodeBool:

Encodes the given bool at the given offset, and returns the new offset.

Important:

`id` may not be 0

Bool: 

      id         type               bool
//  uint16   byte->Fixed8     byte->1 | byte->0

func EncodeFloat32 added in v1.0.0 

func EncodeFloat32(n int, b []byte, v float32, id uint16) int

EncodeFloat32:

Encodes the given 32-bit float at the given offset, and returns the new offset.

Important:

`id` may not be 0

Float32: 

      id          type         float32
//  uint16    byte->Fixed32    4 bytes

func EncodeFloat64 added in v1.0.0 

func EncodeFloat64(n int, b []byte, v float64, id uint16) int

EncodeFloat64:

Encodes the given 64-bit float at the given offset, and returns the new offset.

Important:

`id` may not be 0

Float64: 

      id          type         float64
//  uint16    byte->Fixed64    8 bytes

func EncodeInt added in v1.0.0 

func EncodeInt(n int, b []byte, v int, id uint16) int

EncodeInt:

Encodes the given integer at the given offset, and returns the new offset.

Important:

`id` may not be 0

Int: 

      id         type          int
//  uint16   byte->Varint    []byte

func EncodeInt16 added in v1.0.0 

func EncodeInt16(n int, b []byte, v int16, id uint16) int

EncodeInt16:

Encodes the given 16-bit integer at the given offset, and returns the new offset.

Important:

`id` may not be 0

Int16: 

      id          type        int16
//  uint16   byte->Fixed16   2 bytes

func EncodeInt32 added in v1.0.0 

func EncodeInt32(n int, b []byte, v int32, id uint16) int

EncodeInt32:

Encodes the given 32-bit integer at the given offset, and returns the new offset.

Important:

`id` may not be 0

Int32: 

      id          type        int32
//  uint16   byte->Fixed32   4 bytes

func EncodeInt64 added in v1.0.0 

func EncodeInt64(n int, b []byte, v int64, id uint16) int

EncodeInt64:

Encodes the given 64-bit integer at the given offset, and returns the new offset.

Important:

`id` may not be 0

Int64: 

      id          type        int64
//  uint16   byte->Fixed64   8 bytes

func EncodeInt8 added in v1.0.0 

func EncodeInt8(n int, b []byte, v int8, id uint16) int

EncodeInt8:

Encodes the given 8-bit integer at the given offset, and returns the new offset.

Important:

`id` may not be 0

Int8: 

      id         type         int8
//  uint16   byte->Fixed8     byte

func EncodeSafeString added in v1.0.0 

func EncodeSafeString(n int, b []byte, v string, id uint16) int

EncodeSafeString:

Encodes the given string at the given offset, and returns the new offset.

Important:

`id` may not be 0

String: 

      id         type        string size     string
//  uint16   byte->LenDlm       uint         []byte

func EncodeString added in v1.0.0 

func EncodeString(n int, b []byte, v string, id uint16) int

EncodeString:

Encodes the given string at the given offset, and returns the new offset.

Important:

`id` may not be 0

Uses zero-allocation string conversion, using the `unsafe` package, to do safe string conversions use `EncodeSafeString`

String: 

      id         type        string size     string
//  uint16   byte->LenDlm       uint         []byte

func EncodeUint added in v1.0.0 

func EncodeUint(n int, b []byte, v uint, id uint16) int

EncodeUint:

Encodes the given unsigned integer at the given offset, and returns the new offset.

Important:

`id` may not be 0

Uint: 

      id         type         uint
//  uint16   byte->Varint    []byte

func EncodeUint16 added in v1.0.0 

func EncodeUint16(n int, b []byte, v uint16, id uint16) int

EncodeUint16:

Encodes the given 16-bit unsigned integer at the given offset, and returns the new offset.

Important:

`id` may not be 0

Uint16: 

      id         type         uint16
//  uint16   byte->Fixed16   2 bytes

func EncodeUint32 added in v1.0.0 

func EncodeUint32(n int, b []byte, v uint32, id uint16) int

EncodeUint32:

Encodes the given 32-bit unsigned integer at the given offset, and returns the new offset.

Important:

`id` may not be 0

Uint32: 

      id         type         uint32
//  uint16   byte->Fixed32   4 bytes

func EncodeUint64 added in v1.0.0 

func EncodeUint64(n int, b []byte, v uint64, id uint16) int

EncodeUint64:

Encodes the given 64-bit unsigned integer at the given offset, and returns the new offset.

Important:

`id` may not be 0

Uint64: 

      id         type         uint64
//  uint16   byte->Fixed64   8 bytes

func EncodeUint8 added in v1.0.0 

func EncodeUint8(n int, b []byte, v uint8, id uint16) int

EncodeUint8:

Encodes the given 8-bit unsigned integer at the given offset, and returns the new offset.

Important:

`id` may not be 0

Uint8: 

      id         type       uint8
//  uint16   byte->Fixed8    byte

func SizeBool added in v1.0.0 

func SizeBool(id uint16) int

SizeBool:

Sizes the given bool and returns its size in the benc format.

Bool: 

      id         type               bool
//  uint16   byte->Fixed8     byte->1 | byte->0

func SizeContainer added in v1.0.0 

func SizeContainer(id uint16) int

SizeContainer:

Calculates and returns the size required to encode a container in the Benc format.

Returns:

The size, in bytes, needed to encode a container.

Container:

Container Structure, in the Benc format: 

	      id           type           content       END         END
    //  uint16    byte->Container     []byte      byte->1     byte->1

func SizeFloat32 added in v1.0.0 

func SizeFloat32(id uint16) int

SizeFloat32:

Sizes the given 32-bit float and returns its size in the benc format.

Float32: 

      id          type         float32
//  uint16    byte->Fixed32    4 bytes

func SizeFloat64 added in v1.0.0 

func SizeFloat64(id uint16) int

SizeFloat64:

Sizes the given 64-bit float and returns its size in the benc format.

Float64: 

      id          type         float64
//  uint16    byte->Fixed64    8 bytes

func SizeInt added in v1.0.0 

func SizeInt(v int, id uint16) int

SizeInt:

Sizes the given integer and returns its size in the benc format.

Int: 

      id         type          int
//  uint16   byte->Varint    []byte

func SizeInt16 added in v1.0.0 

func SizeInt16(id uint16) int

SizeInt16:

Sizes the given 16-bit integer and returns its size in the benc format.

Int16: 

      id          type        int16
//  uint16   byte->Fixed16   2 bytes

func SizeInt32 added in v1.0.0 

func SizeInt32(id uint16) int

SizeInt32:

Sizes the given 32-bit integer and returns its size in the benc format.

Int32: 

      id          type        int32
//  uint16   byte->Fixed32   4 bytes

func SizeInt64 added in v1.0.0 

func SizeInt64(id uint16) int

SizeInt64:

Sizes the given 64-bit integer and returns its size in the benc format.

Int64: 

      id          type        int64
//  uint16   byte->Fixed64   8 bytes

func SizeInt8 added in v1.0.0 

func SizeInt8(id uint16) int

SizeInt8:

Sizes the given 8-bit integer and returns its size in the benc format.

Int8: 

      id         type         int8
//  uint16   byte->Fixed8     byte

func SizeString added in v1.0.0 

func SizeString(v string, id uint16) int

SizeString:

Sizes the given string and returns its size in the benc format.

Note:

Also for `EncodeSafeString` and `DecodeSafeString`

String: 

      id         type        string size     string
//  uint16   byte->LenDlm       uint         []byte

func SizeUint added in v1.0.0 

func SizeUint(v uint, id uint16) int

SizeUint:

Sizes the given unsigned integer and returns its size in the benc format.

Uint: 

      id         type         uint
//  uint16   byte->Varint    []byte

func SizeUint16 added in v1.0.0 

func SizeUint16(id uint16) int

SizeUint16:

Sizes the given 16-bit unsigned integer and returns its size in the benc format.

Uint16: 

      id         type         uint16
//  uint16   byte->Fixed16   2 bytes

func SizeUint32 added in v1.0.0 

func SizeUint32(id uint16) int

SizeUint32:

Sizes the given 32-bit unsigned integer and returns its size in the benc format.

Uint32: 

      id         type         uint32
//  uint16   byte->Fixed32   4 bytes

func SizeUint64 added in v1.0.0 

func SizeUint64(id uint16) int

SizeUint64:

Sizes the given 64-bit unsigned integer and returns its size in the benc format.

Uint64: 

      id         type         uint64
//  uint16   byte->Fixed64   8 bytes

func SizeUint8 added in v1.0.0 

func SizeUint8(id uint16) int

SizeUint8:

Sizes the given 8-bit unsigned integer and returns its size in the benc format.

Uint8: 

      id         type       uint8
//  uint16   byte->Fixed8    byte

Types

type Benc 

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

Benc represents an encoder/decoder with a buffer for encoding and decoding data.

func NewEncoder 

func NewEncoder(bufSize ...int) *Benc

NewEncoder:

Creates a new encoder instance for encoding and decoding operations.

If a buffer size is provided, it allocates a buffer of the specified size. Otherwise, it allocates a buffer with a default size of 4096 bytes.

Example: 

benc := bencv2.NewEncoder(1024)

func (*Benc) Decode 

func (benc *Benc) Decode(b []byte, ctr Ctr) Error[string]

Decode:

Decodes the provided byte slice into the provided container (Ctr object).

Returns an Error[string] if decoding fails due to invalid data or buffer size limitations.

func (*Benc) Encode 

func (benc *Benc) Encode(ctr Ctr, f ...func(b []byte, err Error[string])) ([]byte, Error[string])

Encode:

Encodes the provided container (Ctr object) into a byte slice.

Returns the byte slice containing the encoded container.

Returns an Error[string] if encoding fails due to invalid data or buffer size limitations.

func (*Benc) SetBufferReusing added in v0.0.4 

func (benc *Benc) SetBufferReusing(v bool)

SetBufferReusing:

Sets whether buffer reusing is active or not.

type Ctr added in v1.0.0 

type Ctr interface {
	// Size returns the size of the encoded container.
	Size(id uint16) int
	// Encode encodes the container into a byte slice.
	Encode(n int, b []byte, id uint16) (int, Error[string])
	// Decode decodes the container from a byte slice.
	Decode(n int, b []byte, id uint16) (int, Error[string])
}

Ctr is an interface for encoding and decoding containers.

type Error added in v1.0.0 

type Error[T ~string] string

func DecodeBool added in v1.0.0 

func DecodeBool(n int, b []byte, r []uint16, id uint16) (int, bool, Error[string])

DecodeBool:

Decodes a encoded bool at the given offset, returns the decoded bool and the new offset.

Bool: 

      id         type               bool
//  uint16   byte->Fixed8     byte->1 | byte->0

func DecodeContainer added in v1.0.0 

func DecodeContainer(n int, b []byte, r []uint16, id uint16, dec func(n int) (int, Error[string])) (int, Error[string])

DecodeContainer:

Decodes a container in the Benc format.

r: A slice of reserved IDs.

dec: A function that decodes the content from the container.

Returns:

The new offset after decoding the container or an Error[string] if decoding fails.

Container:

Container Structure, in the Benc format: 

	      id           type           content       END         END
    //  uint16    byte->Container     []byte      byte->1     byte->1

func DecodeFloat32 added in v1.0.0 

func DecodeFloat32(n int, b []byte, r []uint16, id uint16) (int, float32, Error[string])

DecodeFloat32:

Decodes a encoded 32-bit float at the given offset, returns the decoded 32-bit float and the new offset.

Float32: 

      id          type         float32
//  uint16    byte->Fixed32    4 bytes

func DecodeFloat64 added in v1.0.0 

func DecodeFloat64(n int, b []byte, r []uint16, id uint16) (int, float64, Error[string])

DecodeFloat64:

Decodes a encoded 64-bit float at the given offset, returns the decoded 64-bit float and the new offset.

Float64: 

      id          type         float64
//  uint16    byte->Fixed64    8 bytes

func DecodeInt added in v1.0.0 

func DecodeInt(n int, b []byte, r []uint16, id uint16) (int, int, Error[string])

DecodeInt:

Decodes a encoded integer at the given offset, returns the decoded integer and the new offset.

Int: 

      id         type          int
//  uint16   byte->Varint    []byte

func DecodeInt16 added in v1.0.0 

func DecodeInt16(n int, b []byte, r []uint16, id uint16) (int, int16, Error[string])

DecodeInt16:

Decodes a encoded 16-bit integer at the given offset, returns the decoded 16-bit integer and the new offset.

Int16: 

      id          type        int16
//  uint16   byte->Fixed16   2 bytes

func DecodeInt32 added in v1.0.0 

func DecodeInt32(n int, b []byte, r []uint16, id uint16) (int, int32, Error[string])

DecodeInt32:

Decodes a encoded 32-bit integer at the given offset, returns the decoded 32-bit integer and the new offset.

Int32: 

      id          type        int32
//  uint16   byte->Fixed32   4 bytes

func DecodeInt64 added in v1.0.0 

func DecodeInt64(n int, b []byte, r []uint16, id uint16) (int, int64, Error[string])

DecodeInt64:

Decodes a encoded 64-bit integer at the given offset, returns the decoded 64-bit integer and the new offset.

Int64: 

      id          type        int64
//  uint16   byte->Fixed64   8 bytes

func DecodeInt8 added in v1.0.0 

func DecodeInt8(n int, b []byte, r []uint16, id uint16) (int, int8, Error[string])

DecodeInt8:

Decodes a encoded 8-bit integer at the given offset, returns the decoded 8-bit integer and the new offset.

Int8: 

      id         type       int8
//  uint16   byte->Fixed8   byte

func DecodeSafeString added in v1.0.0 

func DecodeSafeString(n int, b []byte, r []uint16, id uint16) (int, string, Error[string])

DecodeSafeString:

Decodes a encoded string at the given offset, returns the decoded string and the new offset.

String: 

      id         type        string size     string
//  uint16   byte->LenDlm       uint         []byte

func DecodeString added in v1.0.0 

func DecodeString(n int, b []byte, r []uint16, id uint16) (int, string, Error[string])

DecodeString:

Decodes a encoded string at the given offset, returns the decoded string and the new offset.

String: 

      id         type        string size     string
//  uint16   byte->LenDlm       uint         []byte

func DecodeUint added in v1.0.0 

func DecodeUint(n int, b []byte, r []uint16, id uint16) (int, uint, Error[string])

DecodeUint:

Decodes a encoded unsigned integer at the given offset, returns the decoded unsigned integer and the new offset.

Uint: 

      id         type         uint
//  uint16   byte->Varint    []byte

func DecodeUint16 added in v1.0.0 

func DecodeUint16(n int, b []byte, r []uint16, id uint16) (int, uint16, Error[string])

DecodeUint16:

Decodes a encoded 16-bit unsigned integer at the given offset, returns the decoded 16-bit unsigned integer and the new offset.

Uint16: 

      id         type         uint16
//  uint16   byte->Fixed16   2 bytes

func DecodeUint32 added in v1.0.0 

func DecodeUint32(n int, b []byte, r []uint16, id uint16) (int, uint32, Error[string])

DecodeUint32:

Decodes a encoded 32-bit unsigned integer at the given offset, returns the decoded 32-bit unsigned integer and the new offset.

Uint32: 

      id         type         uint32
//  uint16   byte->Fixed32   4 bytes

func DecodeUint64 added in v1.0.0 

func DecodeUint64(n int, b []byte, r []uint16, id uint16) (int, uint64, Error[string])

DecodeUint64:

Decodes a encoded 64-bit unsigned integer at the given offset, returns the decoded 64-bit unsigned integer and the new offset.

Uint64: 

      id         type         uint64
//  uint16   byte->Fixed64   8 bytes

func DecodeUint8 added in v1.0.0 

func DecodeUint8(n int, b []byte, r []uint16, id uint16) (int, uint8, Error[string])

DecodeUint8:

Decodes a encoded 8-bit unsigned integer at the given offset, returns the decoded 8-bit unsigned integer and the new offset.

Uint8: 

      id         type       uint8
//  uint16   byte->Fixed8    byte

func EncodeContainer added in v1.0.0 

func EncodeContainer(n int, b []byte, id uint16, enc func(n int) (_ int, err Error[string])) (int, Error[string])

EncodeContainer:

Encodes a container in the Benc format. If the container is the entry point, the ID has to be 0.

enc: A function that encodes the content of the message.

Returns:

The new offset after encoding the message.

Container:

Container Structure, in the Benc format: 

	      id           type           content       END         END
    //  uint16    byte->Container     []byte      byte->1     byte->1

func NewErr added in v1.0.0 

func NewErr[T ~string](format T, values ...any) Error[T]

func NewNoneErr added in v1.0.0 

func NewNoneErr[T ~string]() Error[T]

func SkipEncodedValueByType added in v1.0.0 

func SkipEncodedValueByType(n int, b []byte, typ uint8) (int, Error[string])

SkipEncodedValueByType:

Skips the encoding of a value based on its data type.

func (Error[T]) Into added in v1.0.0 

func (self Error[T]) Into() T

func (Error[T]) Is added in v1.0.0 

func (self Error[T]) Is(v T) bool

func (Error[T]) IsNone added in v1.0.0 

func (self Error[T]) IsNone() bool

func (Error[T]) IsSome added in v1.0.0 

func (self Error[T]) IsSome() bool

func (Error[T]) Panic added in v1.0.0 

func (self Error[T]) Panic()

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.