bson

package
v1.21.0 Latest Latest
Warning

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

 Go to latest Published: Mar 20, 2024 License: Apache-2.0 Imports: 16 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

This section is empty.

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

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

LogValue implements slog.LogValuer interface.

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) 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) 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) 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.

func (*Document) LogValue added in v1.21.0 

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

LogValue implements slog.LogValuer interface.

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) 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 singe 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) 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

Directories

Path Synopsis
Package oldbson contains old implementation of BSON that is used for cross-testing only.
 Package oldbson contains old implementation of BSON that is used for cross-testing only.

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.