bson

package
v1.22.0 Latest Latest
Warning

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

 Go to latest Published: Jun 26, 2024 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package bson 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     *bson.Document or bson.RawDocument
Array               *bson.Array    or bson.RawArray

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

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 = bsonproto.BinaryGeneric

	// BinaryFunction represents a BSON Binary function subtype.
	BinaryFunction = bsonproto.BinaryFunction

	// BinaryGenericOld represents a BSON Binary generic-old subtype.
	BinaryGenericOld = bsonproto.BinaryGenericOld

	// BinaryUUIDOld represents a BSON Binary UUID old subtype.
	BinaryUUIDOld = bsonproto.BinaryUUIDOld

	// BinaryUUID represents a BSON Binary UUID subtype.
	BinaryUUID = bsonproto.BinaryUUID

	// BinaryMD5 represents a BSON Binary MD5 subtype.
	BinaryMD5 = bsonproto.BinaryMD5

	// BinaryEncrypted represents a BSON Binary encrypted subtype.
	BinaryEncrypted = bsonproto.BinaryEncrypted

	// BinaryUser represents a BSON Binary user-defined subtype.
	BinaryUser = bsonproto.BinaryUser
)

Variables

View Source 
var (
	// ErrDecodeShortInput is returned wrapped by Decode functions if the input bytes slice is too short.
	ErrDecodeShortInput = bsonproto.ErrDecodeShortInput

	// ErrDecodeInvalidInput is returned wrapped by Decode functions if the input bytes slice is invalid.
	ErrDecodeInvalidInput = bsonproto.ErrDecodeInvalidInput
)
View Source 
var Null = bsonproto.Null

Null represents BSON scalar value null.

Functions

func Convert added in v1.21.0 

func Convert[T types.Type](v T) (any, error)

Convert converts valid types package values to BSON values of that package.

Conversions of composite types may cause errors.

func DecodeCString added in v1.21.0 

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 added in v1.21.0 

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 added in v1.21.0 

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 added in v1.21.0 

func LogMessage(v any) string

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

func LogMessageBlock added in v1.21.0 

func LogMessageBlock(v any) string

LogMessageBlock is a variant of [RawArray.LogMessage] that never uses a flow style.

func LogMessageFlow added in v1.22.0 

func LogMessageFlow(v any) string

LogMessageFlow is a variant of [RawArray.LogMessage] that always uses a flow style.

func SizeCString added in v1.21.0 

func SizeCString(s string) int

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

Types

type AnyArray added in v1.22.0 

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

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 added in v1.22.0 

type AnyDocument interface {
	Encode() (RawDocument, error)
	Decode() (*Document, error)
	Convert() (*types.Document, error)
}

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 ConvertArray added in v1.21.0 

func ConvertArray(arr *types.Array) (*Array, error)

ConvertArray converts *types.Array to Array.

func MakeArray added in v1.21.0 

func MakeArray(cap int) *Array

MakeArray creates a new empty Array with the given capacity.

func NewArray added in v1.21.0 

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

NewArray creates a new Array from the given values.

func (*Array) Add added in v1.21.0 

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

Add adds a new element to the Array.

func (*Array) Convert added in v1.21.0 

func (arr *Array) Convert() (*types.Array, error)

Convert converts Array to *types.Array, decoding raw documents and arrays on the fly.

func (*Array) Decode added in v1.22.0 

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

Decode returns itself to implement the AnyArray interface.

func (*Array) Encode added in v1.21.0 

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

Encode encodes BSON array.

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

func (*Array) Freeze added in v1.22.0 

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 added in v1.22.0 

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

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

func (*Array) Len added in v1.22.0 

func (arr *Array) Len() int

Len returns the number of elements in the Array.

func (*Array) LogValue added in v1.21.0 

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

LogValue implements slog.LogValuer interface.

func (*Array) Replace added in v1.22.0 

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.

type Binary 

type Binary = bsonproto.Binary

Binary represents BSON scalar type binary.

type BinarySubtype added in v1.21.0 

type BinarySubtype = bsonproto.BinarySubtype

BinarySubtype represents BSON Binary's subtype.

type CompositeType added in v1.21.0 

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

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

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 ConvertDocument 

func ConvertDocument(doc *types.Document) (*Document, error)

ConvertDocument converts *types.Document to Document.

func MakeDocument added in v1.21.0 

func MakeDocument(cap int) *Document

MakeDocument creates a new empty Document with the given capacity.

func NewDocument added in v1.21.0 

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

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

func (*Document) Add added in v1.21.0 

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

Add adds a new field to the Document.

func (*Document) Command added in v1.22.0 

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) Convert added in v1.21.0 

func (doc *Document) Convert() (*types.Document, error)

Convert converts Document to *types.Document, decoding raw documents and arrays on the fly.

func (*Document) Decode added in v1.22.0 

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

Decode returns itself to implement the AnyDocument interface.

func (*Document) Encode added in v1.21.0 

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

Encode encodes BSON document.

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

func (*Document) FieldNames added in v1.22.0 

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

FieldNames returns a slice of field names in the Document.

If document contains duplicate field names, the same name may appear multiple times.

func (*Document) Freeze added in v1.22.0 

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 added in v1.21.0 

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.

TODO https://github.com/FerretDB/FerretDB/issues/4208

func (*Document) LogValue added in v1.21.0 

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

LogValue implements slog.LogValuer interface.

func (*Document) Remove added in v1.22.0 

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 added in v1.22.0 

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.

type NullType added in v1.21.0 

type NullType = bsonproto.NullType

NullType represents BSON scalar type null.

type ObjectID 

type ObjectID = bsonproto.ObjectID

ObjectID represents BSON scalar type ObjectID.

type RawArray added in v1.21.0 

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) Convert added in v1.21.0 

func (raw RawArray) Convert() (*types.Array, error)

Convert converts a single valid BSON array that takes the whole byte slice into *types.Array.

func (RawArray) Decode added in v1.21.0 

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

Decode decodes a single BSON array that takes the whole 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 added in v1.21.0 

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

DecodeDeep decodes a single valid BSON array that takes the whole byte slice.

All nested documents and arrays are decoded recursively.

func (RawArray) Encode added in v1.22.0 

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

Encode returns itself to implement the AnyArray interface.

func (RawArray) LogValue added in v1.21.0 

func (raw RawArray) LogValue() slog.Value

LogValue implements slog.LogValuer interface.

type RawDocument added in v1.21.0 

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) Convert added in v1.21.0 

func (raw RawDocument) Convert() (*types.Document, error)

Convert converts a single valid BSON document that takes the whole byte slice into *types.Document.

func (RawDocument) Decode added in v1.21.0 

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

Decode decodes a single BSON document that takes the whole 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 added in v1.21.0 

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

DecodeDeep decodes a single valid BSON document that takes the whole byte slice.

All nested documents and arrays are decoded recursively.

func (RawDocument) Encode added in v1.22.0 

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

Encode returns itself to implement the AnyDocument interface.

func (RawDocument) LogValue added in v1.21.0 

func (raw RawDocument) LogValue() slog.Value

LogValue implements slog.LogValuer interface.

type Regex 

type Regex = bsonproto.Regex

Regex represents BSON scalar type regular expression.

type ScalarType added in v1.21.0 

type ScalarType = bsonproto.ScalarType

ScalarType represents a BSON scalar type.

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

type Timestamp 

type Timestamp = bsonproto.Timestamp

Timestamp represents BSON scalar type timestamp.

type Type added in v1.21.0 

type Type interface {
	ScalarType | CompositeType
}

Type represents a BSON type.

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.