wirebson

package
v0.0.18 Latest Latest
Warning

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

 Go to latest Published: Feb 18, 2025 License: Apache-2.0 Imports: 18 Imported by: 1

Documentation

Overview

Package wirebson implements encoding and decoding of BSON as defined by https://bsonspec.org/spec.html.

Types

The following BSON types are supported: 

BSON                Go

Document/Object     *Document or RawDocument
Array               *Array    or RawArray

Double              float64
String              string
Binary data         Binary
Undefined           UndefinedType
ObjectId            ObjectID
Boolean             bool
Date                time.Time
Null                NullType
Regular Expression  Regex
32-bit integer      int32
Timestamp           Timestamp
64-bit integer      int64
Decimal128          Decimal128

Composite types (Document and Array) are passed by pointers. Raw composite type and scalars are passed by values.

Index

Constants

View Source 
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
)

Variables

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

	// ErrDecodeInvalidInput is returned wrapped by Decode functions if the input bytes slice is invalid.
	ErrDecodeInvalidInput = errors.New("wirebson: invalid input")
)
View Source 
var Null = NullType{}

Null represents BSON scalar value null.

View Source 
var Undefined = UndefinedType{}

Undefined represents BSON scalar value undefined.

Its usage is deprecated, but it is still used in a few places. See https://github.com/FerretDB/FerretDB/issues/2286 for an example.

Functions

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 EncodeCString 

func EncodeCString(b []byte, v string)

EncodeCString encodes cstring value v into b.

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

func FindRaw 

func FindRaw(b []byte) (int, error)

FindRaw finds the first raw BSON document or array in b and returns its length l. It should start from the first byte of b. RawDocument(b[:l]) / RawArray(b[:l]) might not be valid. It is the caller's responsibility to check it.

Use RawDocument(b) / RawArray(b) conversion instead if b contains exactly one document/array and no extra bytes.

func LogMessage 

func LogMessage(v any) string

LogMessage returns a representation as a string. It may change over time.

func LogMessageIndent added in v0.0.10 

func LogMessageIndent(v any) string

LogMessageIndent returns a representation as an indented string. It may change over time.

func Size added in v0.0.14 

func Size(v any) int

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

It panics for invalid types.

func SizeCString 

func SizeCString(v string) int

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

Types

type AnyArray 

type AnyArray interface {
	Encode() (RawArray, error)
	Decode() (*Array, error)
	LogMessage() string
	LogMessageIndent() string
}

AnyArray represents a BSON array type (both *Array and RawArray).

Note that the Encode and Decode methods could return the receiver itself, so care must be taken when results are modified.

type AnyDocument 

type AnyDocument interface {
	Encode() (RawDocument, error)
	Decode() (*Document, error)
	LogMessage() string
	LogMessageIndent() string
}

AnyDocument represents a BSON document type (both *Document and RawDocument).

Note that the Encode and Decode methods could return the receiver itself, so care must be taken when results are modified.

type Array 

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

Array represents a BSON array in the (partially) decoded form.

func MakeArray 

func MakeArray(cap int) *Array

MakeArray creates a new empty Array with the given capacity.

func MustArray added in v0.0.3 

func MustArray(values ...any) *Array

MustArray is a variant of NewArray that panics on error.

func NewArray 

func NewArray(values ...any) (*Array, error)

NewArray creates a new Array from the given values.

func (*Array) Add 

func (arr *Array) Add(value any) error

Add adds a new value to the end of the Array.

func (*Array) All added in v0.0.8 

func (arr *Array) All() iter.Seq2[int, any]

All returns an iterator over index/value pairs of the Array.

func (*Array) Decode 

func (arr *Array) Decode() (*Array, error)

Decode returns itself to implement AnyArray.

Receiver must not be nil.

func (*Array) Encode 

func (arr *Array) Encode() (RawArray, error)

Encode encodes non-nil Array.

TODO https://github.com/FerretDB/wire/issues/21 This method should accept a slice of bytes, not return it. That would allow to avoid unnecessary allocations.

func (*Array) Freeze 

func (arr *Array) Freeze()

Freeze prevents Array from further modifications. Any methods that would modify the Array will panic.

It is safe to call Freeze multiple times.

func (*Array) Get 

func (arr *Array) Get(index int) any

Get returns the value at the given index. It panics if index is out of bounds.

func (*Array) Len 

func (arr *Array) Len() int

Len returns the number of values in the Array.

func (*Array) LogMessage added in v0.0.11 

func (arr *Array) LogMessage() string

LogMessage implements AnyArray.

func (*Array) LogMessageIndent added in v0.0.11 

func (arr *Array) LogMessageIndent() string

LogMessageIndent implements AnyArray.

func (*Array) LogValue 

func (arr *Array) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*Array) MarshalJSON added in v0.0.14 

func (arr *Array) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*Array) Replace 

func (arr *Array) Replace(index int, value any) error

Replace sets the value of the element at the given index. It panics if index is out of bounds.

func (*Array) SortInterface added in v0.0.9 

func (arr *Array) SortInterface(less func(a, b any) bool) sort.Interface

SortInterface returns sort.Interface that can be used to sort Array in place. Passed function should return true is a < b, false otherwise. It should be able to handle values of different types.

func (*Array) UnmarshalJSON added in v0.0.14 

func (arr *Array) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (*Array) Values added in v0.0.8 

func (arr *Array) Values() iter.Seq[any]

Values returns an iterator over values of the Array.

type Binary 

type Binary struct {
	B       []byte
	Subtype BinarySubtype
}

Binary represents BSON scalar type binary.

type BinarySubtype 

type BinarySubtype byte

BinarySubtype represents BSON Binary's subtype.

func (BinarySubtype) String added in v0.0.8 

func (i BinarySubtype) String() string

type CompositeType 

type CompositeType interface {
	*Document | *Array | RawDocument | RawArray
}

CompositeType represents a BSON composite type (including raw types).

type Decimal128 

type Decimal128 struct {
	H uint64
	L uint64
}

Decimal128 represents BSON scalar type decimal128.

type Document 

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

Document represents a BSON document a.k.a object in the (partially) decoded form.

It may contain duplicate field names.

func MakeDocument 

func MakeDocument(cap int) *Document

MakeDocument creates a new empty Document with the given capacity.

func MustDocument added in v0.0.3 

func MustDocument(pairs ...any) *Document

MustDocument is a variant of NewDocument that panics on error.

func NewDocument 

func NewDocument(pairs ...any) (*Document, error)

NewDocument creates a new Document from the given pairs of field names and values.

func (*Document) Add 

func (doc *Document) Add(name string, value any) error

Add adds a new field to the end of the Document.

func (*Document) All added in v0.0.8 

func (doc *Document) All() iter.Seq2[string, any]

All returns an iterator over all field name/value pairs of the Document.

func (*Document) Command 

func (doc *Document) Command() string

Command returns the first field name. This is often used as a command name. It returns an empty string if Document is nil or empty.

func (*Document) Decode 

func (doc *Document) Decode() (*Document, error)

Decode returns itself to implement AnyDocument.

Receiver must not be nil.

func (*Document) Encode 

func (doc *Document) Encode() (RawDocument, error)

Encode encodes non-nil Document.

TODO https://github.com/FerretDB/wire/issues/21 This method should accept a slice of bytes, not return it. That would allow to avoid unnecessary allocations.

func (*Document) FieldNames deprecated 

func (doc *Document) FieldNames() []string

FieldNames returns a slice of field names in the Document in the original order.

If Document contains duplicate field names, the same name will appear multiple times.

Deprecated: use Document.Fields instead.

func (*Document) Fields added in v0.0.10 

func (doc *Document) Fields() iter.Seq[string]

Fields returns an iterator over all field names of the Document.

func (*Document) Freeze 

func (doc *Document) Freeze()

Freeze prevents Document from further field modifications. Any methods that would modify Document fields will panic.

It is safe to call Freeze multiple times.

func (*Document) Get 

func (doc *Document) Get(name string) any

Get returns a value of the field with the given name.

It returns nil if the field is not found.

If Document contains duplicate field names, it returns the first one. To get other fields, a for/range loop can be used with Document.All.

func (*Document) GetByIndex deprecated added in v0.0.5 

func (doc *Document) GetByIndex(i int) (string, any)

GetByIndex returns the name and the value of the field at the given index (between 0 and Document.Len-1). It panics if index is out of bounds.

Deprecated: use Document.All instead.

func (*Document) Len added in v0.0.5 

func (doc *Document) Len() int

Len returns the number of fields in the Document.

func (*Document) LogMessage added in v0.0.11 

func (doc *Document) LogMessage() string

LogMessage implements AnyDocument.

func (*Document) LogMessageIndent added in v0.0.11 

func (doc *Document) LogMessageIndent() string

LogMessageIndent implements AnyDocument.

func (*Document) LogValue 

func (doc *Document) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*Document) MarshalJSON added in v0.0.14 

func (doc *Document) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*Document) Remove 

func (doc *Document) Remove(name string)

Remove removes the first existing field with the given name. It does nothing if the field with that name does not exist.

func (*Document) Replace 

func (doc *Document) Replace(name string, value any) error

Replace sets the value for the first existing field with the given name. It does nothing if the field with that name does not exist.

func (*Document) UnmarshalJSON added in v0.0.14 

func (doc *Document) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

type NullType 

type NullType struct{}

NullType represents BSON scalar type null.

type ObjectID 

type ObjectID [12]byte

ObjectID represents BSON scalar type ObjectID.

type RawArray 

type RawArray []byte

RawArray represents a single BSON array in the binary encoded form.

It generally references a part of a larger slice, not a copy.

func (RawArray) Decode 

func (raw RawArray) Decode() (*Array, error)

Decode decodes a single non-nil BSON array that takes the whole non-nil byte slice.

Only top-level elements are decoded; nested documents and arrays are converted to RawDocument and RawArray respectively, using raw's subslices without copying.

func (RawArray) DecodeDeep 

func (raw RawArray) DecodeDeep() (*Array, error)

DecodeDeep decodes a single non-nil BSON array that takes the whole non-nil byte slice.

All nested documents and arrays are decoded recursively.

Receiver must not be nil.

func (RawArray) Encode 

func (raw RawArray) Encode() (RawArray, error)

Encode returns itself to implement the AnyArray interface.

Receiver must not be nil.

func (RawArray) LogMessage added in v0.0.11 

func (raw RawArray) LogMessage() string

LogMessage implements AnyArray.

func (RawArray) LogMessageIndent added in v0.0.11 

func (raw RawArray) LogMessageIndent() string

LogMessageIndent implements AnyArray.

func (RawArray) LogValue 

func (raw RawArray) LogValue() slog.Value

LogValue implements slog.LogValuer.

type RawDocument 

type RawDocument []byte

RawDocument represents a single BSON document a.k.a object in the binary encoded form.

It generally references a part of a larger slice, not a copy.

func (RawDocument) Decode 

func (raw RawDocument) Decode() (*Document, error)

Decode decodes a single non-nil BSON document that takes the whole non-nil byte slice.

Only top-level fields are decoded; nested documents and arrays are converted to RawDocument and RawArray respectively, using raw's subslices without copying.

func (RawDocument) DecodeDeep 

func (raw RawDocument) DecodeDeep() (*Document, error)

DecodeDeep decodes a single non-nil BSON document that takes the whole non-nil byte slice.

All nested documents and arrays are decoded recursively.

func (RawDocument) Encode 

func (raw RawDocument) Encode() (RawDocument, error)

Encode returns itself to implement the AnyDocument interface.

Receiver must not be nil.

func (RawDocument) LogMessage added in v0.0.11 

func (raw RawDocument) LogMessage() string

LogMessage implements AnyDocument.

func (RawDocument) LogMessageIndent added in v0.0.11 

func (raw RawDocument) LogMessageIndent() string

LogMessageIndent implements AnyDocument.

func (RawDocument) LogValue 

func (raw RawDocument) LogValue() slog.Value

LogValue implements slog.LogValuer.

type Regex 

type Regex struct {
	Pattern string
	Options string
}

Regex represents BSON scalar type regular expression.

type ScalarType 

type ScalarType interface {
	float64 | string | Binary | UndefinedType | 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 NewTimestamp added in v0.0.17 

func NewTimestamp(t, i uint32) Timestamp

NewTimestamp creates a Timestamp using the provided time and increment.

func (Timestamp) I added in v0.0.17 

func (ts Timestamp) I() uint32

I returns the increment part of the timestamp.

func (Timestamp) T added in v0.0.17 

func (ts Timestamp) T() uint32

T returns the time part of the timestamp.

type Type 

type Type interface {
	CompositeType | ScalarType
}

Type represents a BSON type.

type UndefinedType added in v0.0.17 

type UndefinedType struct{}

UndefinedType represents BSON scalar type undefined.

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.