bstd

package
v1.1.1 Latest Latest
Warning

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

 Go to latest Published: Oct 28, 2024 License: MIT Imports: 6 Imported by: 5

README

benc std

The Benc standard provides a suite of methods for raw sizing, skipping, marshalling, and unmarshalling of Go types. When I refer to "raw", it means that only the essential elements are serialized, for example, serialized data is not prefixed with their corresponding type information.

Installation

go get github.com/deneonet/benc/std

Tests

Code coverage of bstd.go is approximately 95%

Usage

Benc Standard provides four primary functions, for all of these types (string, unsafe string, slice, map, bool, byte, bytes (slice of type byte), float32, float64, int (var int), int16, int32, int64, uint (var uint), uint16, uint32, uint64):

  • Skip: Skips the requested type.
  • Size: Calculate the needed size for the requested type (and data).
  • Marshal: Marshals the requested type (and data) into the buffer at a given offset n.
  • Unmarshal: Unmarshals the requested type.

Append the type (listed above) in CamelCase to the end of each function to skip/size/marshal or unmarshal the requested type.
Exception: int and uint, the skip function for both of them is: bstd.SkipVarint

Basic Type Example

Marshaling and Unmarshalling a string:

package main

import (
	"fmt"
	"github.com/deneonet/benc/std"
)

func main() {
	mystr := "My string"

	// Calculate the size needed
	s := bstd.SizeString(mystr)

	// Create buffer
	buf := make([]byte, s)

	// Marshal the string into buffer
	_ = bstd.MarshalString(0, buf, mystr)

	// Unmarshal string
	_, deserMyStr, err := bstd.UnmarshalString(0, buf)
	if err != nil {
		panic(err)
	}
	if mystr != deserMyStr {
		panic("no match")
	}

	// Success
	fmt.Println("Marshaling and unmarshaling successful:", deserMyStr)
}

Complex Data Type Example

Complex data types, like slices and maps:

package main

import (
	"fmt"
	"reflect"

	bstd "github.com/deneonet/benc/std"
)

func main() {
	myslice := []string{"Str Element 1", "Str Element 2", "Str Element 3"}
	mymap := make(map[string]string)
	mymap["Str Key 1"] = "Str Val 1"
	mymap["Str Key 2"] = "Str Val 2"
	mymap["Str Key 3"] = "Str Val 3"

	// Calculate the size needed
	s := bstd.SizeSlice(myslice, bstd.SizeString)
	s += bstd.SizeMap(mymap, bstd.SizeString, bstd.SizeString)

	// Create buffer
	buf := make([]byte, s)

	// Marshal the slice and map into buffer
	n := bstd.MarshalSlice(0, buf, myslice, bstd.MarshalString)
	_ = bstd.MarshalMap(n, buf, mymap, bstd.MarshalString, bstd.MarshalString)

	// Unmarshal slice
	n, deserMySlice, err := bstd.UnmarshalSlice[string](0, buf, bstd.UnmarshalString)
	if err != nil {
		panic(err)
	}
	if !reflect.DeepEqual(myslice, deserMySlice) {
		panic("slice: no match")
	}

	// Unmarshal map
	_, deserMyMap, err := bstd.UnmarshalMap[string, string](n, buf, bstd.UnmarshalString, bstd.UnmarshalString)
	if err != nil {
		panic(err)
	}
	if !reflect.DeepEqual(mymap, deserMyMap) {
		panic("map: no match")
	}

	// Success
	fmt.Println("Slice marshaling and unmarshaling successful:")
	for _, str := range deserMySlice {
		fmt.Println(str)
	}

	fmt.Println("\nMap marshaling and unmarshaling successful:")
	for key, val := range deserMyMap {
		fmt.Println(key + ": " + val)
	}
}

Note: Maps and slice are able to nest, for example:

// Size
bstd.SizeSlice(myslice, func (slice []string) int {
	return bstd.SizeSlice(slice, bstd.SizeString)
})

// Marshal
bstd.MarshalSlice(0, buf, mySliceSlice, func(n int, buf []byte, slice []string) int {
	return bstd.MarshalSlice(n, buf, slice, bstd.MarshalString)
})

// Unmarshal
bstd.UnmarshalSlice[[]string](0, buf, func (n int, buf []byte) (int, []string, error) {
	return bstd.UnmarshalSlice[string](n, buf, bstd.UnmarshalString)
})

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func MarshalBool 

func MarshalBool(n int, b []byte, v bool) int

Returns the new offset 'n' after marshalling the bool.

func MarshalByte 

func MarshalByte(n int, b []byte, byt byte) int

func MarshalBytes 

func MarshalBytes(n int, b []byte, bs []byte) int

func MarshalFloat32 

func MarshalFloat32(n int, b []byte, v float32) int

Returns the new offset 'n' after marshalling the 32-bit float.

func MarshalFloat64 

func MarshalFloat64(n int, b []byte, v float64) int

Returns the new offset 'n' after marshalling the 64-bit float.

func MarshalInt 

func MarshalInt(n int, b []byte, sv int) int

Returns the new offset 'n' after marshalling the integer.

!- Panics, if 'b' is too small.

func MarshalInt16 

func MarshalInt16(n int, b []byte, v int16) int

Returns the new offset 'n' after marshalling the 16-bit integer.

func MarshalInt32 

func MarshalInt32(n int, b []byte, v int32) int

Returns the new offset 'n' after marshalling the 32-bit integer.

func MarshalInt64 

func MarshalInt64(n int, b []byte, v int64) int

Returns the new offset 'n' after marshalling the 64-bit integer.

func MarshalMap 

func MarshalMap[K comparable, V any](n int, b []byte, m map[K]V, kMarshaler MarshalFunc[K], vMarshaler MarshalFunc[V]) int

func MarshalSlice 

func MarshalSlice[T any](n int, b []byte, slice []T, marshaler MarshalFunc[T]) int

func MarshalString 

func MarshalString(n int, b []byte, str string) int

func MarshalUint 

func MarshalUint(n int, b []byte, v uint) int

Returns the new offset 'n' after marshalling the unsigned integer.

!- Panics, if 'b' is too small.

func MarshalUint16 

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

Returns the new offset 'n' after marshalling the 16-bit unsigned integer.

func MarshalUint32 

func MarshalUint32(n int, b []byte, v uint32) int

Returns the new offset 'n' after marshalling the 32-bit unsigned integer.

func MarshalUint64 

func MarshalUint64(n int, b []byte, v uint64) int

Returns the new offset 'n' after marshalling the 64-bit unsigned integer.

func MarshalUnsafeString 

func MarshalUnsafeString(n int, b []byte, str string) int

func SizeBool 

func SizeBool() int

Returns the bytes needed to marshal a bool.

func SizeByte 

func SizeByte() int

func SizeBytes 

func SizeBytes(bs []byte) int

func SizeFloat32 

func SizeFloat32() int

Returns the bytes needed to marshal a 32-bit float.

func SizeFloat64 

func SizeFloat64() int

Returns the bytes needed to marshal a 64-bit float.

func SizeInt 

func SizeInt(sv int) int

Returns the bytes needed to marshal a integer.

func SizeInt16 

func SizeInt16() int

Returns the bytes needed to marshal a 16-bit integer.

func SizeInt32 

func SizeInt32() int

Returns the bytes needed to marshal a 32-bit integer.

func SizeInt64 

func SizeInt64() int

Returns the bytes needed to marshal a 64-bit integer.

func SizeMap 

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

func SizeSlice 

func SizeSlice[T any](slice []T, sizer interface{}) (s int)

func SizeString 

func SizeString(str string) int

For unsafe string too

func SizeUint 

func SizeUint(v uint) int

Returns the bytes needed to marshal a unsigned integer.

func SizeUint16 

func SizeUint16() int

Returns the bytes needed to marshal a 16-bit unsigned integer.

func SizeUint32 

func SizeUint32() int

Returns the bytes needed to marshal a 32-bit unsigned integer.

func SizeUint64 

func SizeUint64() int

Returns the bytes needed to marshal a 64-bit unsigned integer.

func SkipBool 

func SkipBool(n int, b []byte) (int, error)

Returns the new offset 'n' after skipping the marshalled bool.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to skip the marshalled bool.

If a error is returned, n (the int returned) equals zero ( 0 ).

func SkipByte 

func SkipByte(n int, b []byte) (int, error)

func SkipBytes 

func SkipBytes(n int, b []byte) (int, error)

SkipBytes = SkipString

func SkipFloat32 

func SkipFloat32(n int, b []byte) (int, error)

Returns the new offset 'n' after skipping the marshalled 32-bit float.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to skip the marshalled 32-bit float.

If a error is returned, n (the int returned) equals zero ( 0 ).

func SkipFloat64 

func SkipFloat64(n int, b []byte) (int, error)

Returns the new offset 'n' after skipping the marshalled 64-bit float.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to skip the marshalled 64-bit float.

If a error is returned, n (the int returned) equals zero ( 0 ).

func SkipInt16 

func SkipInt16(n int, b []byte) (int, error)

Returns the new offset 'n' after skipping the marshalled 16-bit integer.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to skip the marshalled 16-bit integer.

If a error is returned, n (the int returned) equals zero ( 0 ).

func SkipInt32 

func SkipInt32(n int, b []byte) (int, error)

Returns the new offset 'n' after skipping the marshalled 32-bit integer.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to skip the marshalled 32-bit integer.

If a error is returned, n (the int returned) equals zero ( 0 ).

func SkipInt64 

func SkipInt64(n int, b []byte) (int, error)

Returns the new offset 'n' after skipping the marshalled 64-bit integer.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to skip the marshalled 64-bit integer.

If a error is returned, n (the int returned) equals zero ( 0 ).

func SkipMap 

func SkipMap(n int, b []byte) (int, error)

SkipMap = SkipSlice

func SkipSlice 

func SkipSlice(n int, b []byte) (int, error)

func SkipString 

func SkipString(n int, b []byte) (int, error)

For unsafe string too

func SkipUint16 

func SkipUint16(n int, b []byte) (int, error)

Returns the new offset 'n' after skipping the marshalled 16-bit unsigned integer.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to skip the marshalled 16-bit unsigned integer.

If a error is returned, n (the int returned) equals zero ( 0 ).

func SkipUint32 

func SkipUint32(n int, b []byte) (int, error)

Returns the new offset 'n' after skipping the marshalled 32-bit unsigned integer.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to skip the marshalled 32-bit unsigned integer.

If a error is returned, n (the int returned) equals zero ( 0 ).

func SkipUint64 

func SkipUint64(n int, b []byte) (int, error)

Returns the new offset 'n' after skipping the marshalled 64-bit unsigned integer.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to skip the marshalled 64-bit unsigned integer.

If a error is returned, n (the int returned) equals zero ( 0 ).

func SkipVarint 

func SkipVarint(n int, buf []byte) (int, error)

Returns the new offset 'n' after skipping the marshalled varint.

Possible errors returned:

  • benc.ErrOverflow - varint overflowed a N-bit unsigned integer.
  • benc.ErrBufTooSmall - 'buf' was too small to skip the marshalled varint.

If a error is returned, n (the int returned) equals zero ( 0 ).

func UnmarshalBool 

func UnmarshalBool(n int, b []byte) (int, bool, error)

Returns the new offset 'n', as well as the bool, that got unmarshalled.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to unmarshal the bool.

If a error is returned, n (the int returned) equals zero ( 0 ).

func UnmarshalByte 

func UnmarshalByte(n int, b []byte) (int, byte, error)

func UnmarshalBytes 

func UnmarshalBytes(n int, b []byte) (int, []byte, error)

func UnmarshalFloat32 

func UnmarshalFloat32(n int, b []byte) (int, float32, error)

Returns the new offset 'n', as well as the 32-bit float, that got unmarshalled.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to unmarshal the 32-bit float.

If a error is returned, n (the int returned) equals zero ( 0 ).

func UnmarshalFloat64 

func UnmarshalFloat64(n int, b []byte) (int, float64, error)

Returns the new offset 'n', as well as the 64-bit float, that got unmarshalled.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to unmarshal the 64-bit float.

If a error is returned, n (the int returned) equals zero ( 0 ).

func UnmarshalInt 

func UnmarshalInt(n int, buf []byte) (int, int, error)

Returns the new offset 'n', as well as the integer, that got unmarshalled.

Possible errors returned:

  • benc.ErrOverflow - varint overflowed a N-bit integer.
  • benc.ErrBufTooSmall - 'buf' was too small to skip the unmarshal the integer.

If a error is returned, n (the int returned) equals zero ( 0 ).

func UnmarshalInt16 

func UnmarshalInt16(n int, b []byte) (int, int16, error)

Returns the new offset 'n', as well as the 16-bit integer, that got unmarshalled.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to unmarshal the 16-bit integer.

If a error is returned, n (the int returned) equals zero ( 0 ).

func UnmarshalInt32 

func UnmarshalInt32(n int, b []byte) (int, int32, error)

Returns the new offset 'n', as well as the 32-bit integer, that got unmarshalled.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to unmarshal the 32-bit integer.

If a error is returned, n (the int returned) equals zero ( 0 ).

func UnmarshalInt64 

func UnmarshalInt64(n int, b []byte) (int, int64, error)

Returns the new offset 'n', as well as the 64-bit integer, that got unmarshalled.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to unmarshal the 64-bit integer.

If a error is returned, n (the int returned) equals zero ( 0 ).

func UnmarshalMap 

func UnmarshalMap[K comparable, V any](n int, b []byte, kUnmarshaler interface{}, vUnmarshaler interface{}) (int, map[K]V, error)

func UnmarshalSlice 

func UnmarshalSlice[T any](n int, b []byte, unmarshaler interface{}) (int, []T, error)

func UnmarshalString 

func UnmarshalString(n int, b []byte) (int, string, error)

func UnmarshalUint 

func UnmarshalUint(n int, buf []byte) (int, uint, error)

Returns the new offset 'n', as well as the unsigned integer, that got unmarshalled.

Possible errors returned:

  • benc.ErrOverflow - varint overflowed a N-bit unsigned integer
  • benc.ErrBufTooSmall - 'buf' was too small to skip the unmarshal the unsigned integer//

If a error is returned, n (the int returned) equals zero ( 0 ).

func UnmarshalUint16 

func UnmarshalUint16(n int, b []byte) (int, uint16, error)

Returns the new offset 'n', as well as the 16-bit unsigned integer, that got unmarshalled.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to unmarshal the 16-bit unsigned integer.

If a error is returned, n (the int returned) equals zero ( 0 ).

func UnmarshalUint32 

func UnmarshalUint32(n int, b []byte) (int, uint32, error)

Returns the new offset 'n', as well as the 32-bit unsigned integer, that got unmarshalled.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to unmarshal the 32-bit unsigned integer.

If a error is returned, n (the int returned) equals zero ( 0 ).

func UnmarshalUint64 

func UnmarshalUint64(n int, b []byte) (int, uint64, error)

Returns the new offset 'n', as well as the 64-bit unsigned integer, that got unmarshalled.

Possible errors returned:

  • benc.ErrBufTooSmall - 'b' was too small to unmarshal the 64-bit unsigned integer.

If a error is returned, n (the int returned) equals zero ( 0 ).

func UnmarshalUnsafeString 

func UnmarshalUnsafeString(n int, b []byte) (int, string, error)

Types

type MarshalFunc 

type MarshalFunc[T any] func(n int, b []byte, t T) int

type StringHeader 

type StringHeader struct {
	Data *byte
	Len  int
}

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.