bsonproto

Documentation

Overview

Package bsonproto provides primitives for encoding and decoding of BSON.

Index

• Constants
• Variables
• func Decode[T ScalarType](b []byte, v *T) error
• func DecodeAny(b []byte, v any) error
• func DecodeBool(b []byte) (bool, error)
• func DecodeCString(b []byte) (string, error)
• func DecodeFloat64(b []byte) (float64, error)
• func DecodeInt32(b []byte) (int32, error)
• func DecodeInt64(b []byte) (int64, error)
• func DecodeString(b []byte) (string, error)
• func DecodeTime(b []byte) (time.Time, error)
• func Encode[T ScalarType](b []byte, v T)
• func EncodeAny(b []byte, v any)
• func EncodeBinary(b []byte, v Binary)
• func EncodeBool(b []byte, v bool)
• func EncodeCString(b []byte, v string)
• func EncodeDecimal128(b []byte, v Decimal128)
• func EncodeFloat64(b []byte, v float64)
• func EncodeInt32(b []byte, v int32)
• func EncodeInt64(b []byte, v int64)
• func EncodeObjectID(b []byte, v ObjectID)
• func EncodeRegex(b []byte, v Regex)
• func EncodeString(b []byte, v string)
• func EncodeTime(b []byte, v time.Time)
• func EncodeTimestamp(b []byte, v Timestamp)
• func Size[T ScalarType](v T) int
• func SizeAny(v any) int
• func SizeBinary(v Binary) int
• func SizeCString(v string) int
• func SizeRegex(v Regex) int
• func SizeString(v string) int
• type Binary
  • func DecodeBinary(b []byte) (Binary, error)
• type BinarySubtype
  • func (i BinarySubtype) String() string
• type Decimal128
  • func DecodeDecimal128(b []byte) (Decimal128, error)
• type NullType
• type ObjectID
  • func DecodeObjectID(b []byte) (ObjectID, error)
• type Regex
  • func DecodeRegex(b []byte) (Regex, error)
• type ScalarType
• type Timestamp
  • func DecodeTimestamp(b []byte) (Timestamp, error)

Constants

const (
	// BinaryGeneric represents a BSON Binary generic subtype.
	BinaryGeneric = BinarySubtype(0x00) // generic

	// BinaryFunction represents a BSON Binary function subtype
	BinaryFunction = BinarySubtype(0x01) // function

	// BinaryGenericOld represents a BSON Binary generic-old subtype.
	BinaryGenericOld = BinarySubtype(0x02) // generic-old

	// BinaryUUIDOld represents a BSON Binary UUID old subtype.
	BinaryUUIDOld = BinarySubtype(0x03) // uuid-old

	// BinaryUUID represents a BSON Binary UUID subtype.
	BinaryUUID = BinarySubtype(0x04) // uuid

	// BinaryMD5 represents a BSON Binary MD5 subtype.
	BinaryMD5 = BinarySubtype(0x05) // md5

	// BinaryEncrypted represents a BSON Binary encrypted subtype.
	BinaryEncrypted = BinarySubtype(0x06) // encrypted

	// BinaryUser represents a BSON Binary user-defined subtype.
	BinaryUser = BinarySubtype(0x80) // user
)

const SizeBool = 1

SizeBool is a size of the encoding of bool in bytes.

const SizeDecimal128 = 16

SizeDecimal128 is a size of the encoding of Decimal128 in bytes.

const SizeFloat64 = 8

SizeFloat64 is a size of the encoding of float64 in bytes.

const SizeInt32 = 4

SizeInt32 is a size of the encoding of int32 in bytes.

const SizeInt64 = 8

SizeInt64 is a size of the encoding of int64 in bytes.

const SizeObjectID = 12

SizeObjectID is a size of the encoding of ObjectID in bytes.

const SizeTime = 8

SizeTime is a size of the encoding of time.Time in bytes.

const SizeTimestamp = 8

SizeTimestamp is a size of the encoding of Timestamp in bytes.

Variables

var (
	// ErrDecodeShortInput is returned wrapped by Decode functions if the input bytes slice is too short.
	ErrDecodeShortInput = errors.New("bsonproto: short input")

	// ErrDecodeInvalidInput is returned wrapped by Decode functions if the input bytes slice is invalid.
	ErrDecodeInvalidInput = errors.New("bsonproto: invalid input")
)

var Null = NullType{}

Null represents BSON scalar value null.

Functions

func Decode

func Decode[T ScalarType](b []byte, v *T) error

Decode decodes value from b into v.

If there is not enough bytes, Decode will return a wrapped ErrDecodeShortInput. If the input is otherwise invalid, a wrapped ErrDecodeInvalidInput is returned.

func DecodeAny

func DecodeAny(b []byte, v any) error

DecodeAny decodes value from b into v.

If there is not enough bytes, DecodeAny will return a wrapped ErrDecodeShortInput. If the input is otherwise invalid, a wrapped ErrDecodeInvalidInput is returned.

It panics if v is not a pointer to ScalarType (including CString).

func DecodeBool

func DecodeBool(b []byte) (bool, error)

DecodeBool decodes bool value from b.

If there is not enough bytes, DecodeBool will return a wrapped ErrDecodeShortInput.

func DecodeCString

func DecodeCString(b []byte) (string, error)

DecodeCString decodes cstring value from b.

If there is not enough bytes, DecodeCString will return a wrapped ErrDecodeShortInput. If the input is otherwise invalid, a wrapped ErrDecodeInvalidInput is returned.

func DecodeFloat64

func DecodeFloat64(b []byte) (float64, error)

DecodeFloat64 decodes float64 value from b.

If there is not enough bytes, DecodeFloat64 will return a wrapped ErrDecodeShortInput.

Infinities, NaNs, negative zeros are preserved.

func DecodeInt32

func DecodeInt32(b []byte) (int32, error)

DecodeInt32 decodes int32 value from b.

If there is not enough bytes, DecodeInt32 will return a wrapped ErrDecodeShortInput.

func DecodeInt64

func DecodeInt64(b []byte) (int64, error)

DecodeInt64 decodes int64 value from b.

If there is not enough bytes, DecodeInt64 will return a wrapped ErrDecodeShortInput.

func DecodeString

func DecodeString(b []byte) (string, error)

DecodeString decodes string value from b.

If there is not enough bytes, DecodeString will return a wrapped ErrDecodeShortInput. If the input is otherwise invalid, a wrapped ErrDecodeInvalidInput is returned.

func DecodeTime

func DecodeTime(b []byte) (time.Time, error)

DecodeTime decodes time.Time value from b.

If there is not enough bytes, DecodeTime will return a wrapped ErrDecodeShortInput.

func Encode

func Encode[T ScalarType](b []byte, v T)

Encode encodes value v into b.

b must be at least Size(v) bytes long; otherwise, Encode will panic. Only b[0:Size(v)] bytes are modified.

func EncodeAny

func EncodeAny(b []byte, v any)

EncodeAny encodes value v into b.

b must be at least Size(v) bytes long; otherwise, EncodeAny will panic. Only b[0:Size(v)] bytes are modified.

It panics if v is not a ScalarType (including CString).

func EncodeBinary

func EncodeBinary(b []byte, v Binary)

EncodeBinary encodes Binary value v into b.

b must be at least len(v.B)+5 (SizeBinary) bytes long; otherwise, EncodeBinary will panic. Only b[0:len(v.B)+5] bytes are modified.

func EncodeBool

func EncodeBool(b []byte, v bool)

EncodeBool encodes bool value v into b.

b must be at least 1 (SizeBool) byte long; otherwise, EncodeBool will panic. Only b[0] is modified.

func EncodeCString

func EncodeCString(b []byte, v string)

EncodeCString encodes cstring value v into b.

b must be at least len(v)+1 (SizeCString) bytes long; otherwise, EncodeString will panic. Only b[0:len(v)+1] bytes are modified.

func EncodeDecimal128

func EncodeDecimal128(b []byte, v Decimal128)

EncodeDecimal128 encodes Decimal128 value v into b.

b must be at least 16 (SizeDecimal128) bytes long; otherwise, EncodeDecimal128 will panic. Only b[0:16] bytes are modified.

func EncodeFloat64

func EncodeFloat64(b []byte, v float64)

EncodeFloat64 encodes float64 value v into b.

b must be at least 8 (SizeFloat64) bytes long; otherwise, EncodeFloat64 will panic. Only b[0:8] bytes are modified.

Infinities, NaNs, negative zeros are preserved.

func EncodeInt32

func EncodeInt32(b []byte, v int32)

EncodeInt32 encodes int32 value v into b.

b must be at least 4 (SizeInt32) bytes long; otherwise, EncodeInt32 will panic. Only b[0:4] bytes are modified.

func EncodeInt64

func EncodeInt64(b []byte, v int64)

EncodeInt64 encodes int64 value v into b.

b must be at least 8 (SizeInt64) bytes long; otherwise, EncodeInt64 will panic. Only b[0:8] bytes are modified.

func EncodeObjectID

func EncodeObjectID(b []byte, v ObjectID)

EncodeObjectID encodes ObjectID value v into b.

b must be at least 12 (SizeObjectID) bytes long; otherwise, EncodeObjectID will panic. Only b[0:12] bytes are modified.

func EncodeRegex

func EncodeRegex(b []byte, v Regex)

EncodeRegex encodes Regex value v into b.

b must be at least len(v.Pattern)+len(v.Options)+2 (SizeRegex) bytes long; otherwise, EncodeRegex will panic. Only b[0:len(v.Pattern)+len(v.Options)+2] bytes are modified.

func EncodeString

func EncodeString(b []byte, v string)

EncodeString encodes string value v into b.

b must be at least len(v)+5 (SizeString) bytes long; otherwise, EncodeString will panic. Only b[0:len(v)+5] bytes are modified.

func EncodeTime

func EncodeTime(b []byte, v time.Time)

EncodeTime encodes time.Time value v into b.

b must be at least 8 (SizeTime) byte long; otherwise, EncodeTime will panic. Only b[0:8] bytes are modified.

func EncodeTimestamp

func EncodeTimestamp(b []byte, v Timestamp)

EncodeTimestamp encodes Timestamp value v into b.

b must be at least 8 (SizeTimestamp) bytes long; otherwise, EncodeTimestamp will panic. Only b[0:8] bytes are modified.

func Size

func Size[T ScalarType](v T) int

Size returns a size of the encoding of value v in bytes.

func SizeAny

func SizeAny(v any) int

SizeAny returns a size of the encoding of value v in bytes.

It panics if v is not a ScalarType (including CString).

func SizeBinary

func SizeBinary(v Binary) int

SizeBinary returns a size of the encoding of v Binary in bytes.

func SizeCString

func SizeCString(v string) int

SizeCString returns a size of the encoding of v cstring in bytes.

func SizeRegex

func SizeRegex(v Regex) int

SizeRegex returns a size of the encoding of v Regex in bytes.

func SizeString

func SizeString(v string) int

SizeString returns a size of the encoding of v string in bytes.

Types

type Binary

type Binary struct {
	B       []byte
	Subtype BinarySubtype
}

Binary represents BSON scalar type binary.

func DecodeBinary

func DecodeBinary(b []byte) (Binary, error)

DecodeBinary decodes Binary value from b.

If there is not enough bytes, DecodeBinary will return a wrapped ErrDecodeShortInput. If the input is otherwise invalid, a wrapped ErrDecodeInvalidInput is returned.

type BinarySubtype

type BinarySubtype byte

BinarySubtype represents BSON Binary's subtype.

func (BinarySubtype) String

func (i BinarySubtype) String() string

type Decimal128

type Decimal128 struct {
	L uint64
	H uint64
}

Decimal128 represents BSON scalar type decimal128.

func DecodeDecimal128

func DecodeDecimal128(b []byte) (Decimal128, error)

DecodeDecimal128 decodes Decimal128 value from b.

If there is not enough bytes, DecodeDecimal128 will return a wrapped ErrDecodeShortInput.

type NullType

type NullType struct{}

NullType represents BSON scalar type null.

type ObjectID

type ObjectID [12]byte

ObjectID represents BSON scalar type ObjectID.

func DecodeObjectID

func DecodeObjectID(b []byte) (ObjectID, error)

DecodeObjectID decodes ObjectID value from b.

If there is not enough bytes, DecodeObjectID will return a wrapped ErrDecodeShortInput.

type Regex

type Regex struct {
	Pattern string
	Options string
}

Regex represents BSON scalar type regular expression.

func DecodeRegex

func DecodeRegex(b []byte) (Regex, error)

DecodeRegex decodes Regex value from b.

If there is not enough bytes, DecodeRegex will return a wrapped ErrDecodeShortInput. If the input is otherwise invalid, a wrapped ErrDecodeInvalidInput is returned.

type ScalarType

type ScalarType interface {
	float64 | string | Binary | ObjectID | bool | time.Time | NullType | Regex | int32 | Timestamp | int64 | Decimal128
}

ScalarType represents a BSON scalar type.

CString is not included as it is not a real BSON type.

type Timestamp

type Timestamp uint64

Timestamp represents BSON scalar type timestamp.

func DecodeTimestamp

func DecodeTimestamp(b []byte) (Timestamp, error)

DecodeTimestamp decodes Timestamp value from b.

If there is not enough bytes, DecodeTimestamp will return a wrapped ErrDecodeShortInput.