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 *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 Decimal128 bson.Decimal128
Composite types (Document and Array) are passed by pointers. Raw composite type and scalars are passed by values.
Index ¶
- Constants
- Variables
- func DecodeCString(b []byte) (string, error)
- func EncodeCString(b []byte, v string)
- func FindRaw(b []byte) (int, error)
- func LogMessage(v any) string
- func LogMessageBlock(v any) string
- func LogMessageFlow(v any) string
- func SizeCString(s string) int
- type AnyArray
- type AnyDocument
- type Array
- func (arr *Array) Add(value any) error
- func (arr *Array) Decode() (*Array, error)
- func (arr *Array) Encode() (RawArray, error)
- func (arr *Array) Freeze()
- func (arr *Array) Get(index int) any
- func (arr *Array) Len() int
- func (arr *Array) LogValue() slog.Value
- func (arr *Array) Replace(index int, value any) error
- type Binary
- type BinarySubtype
- type CompositeType
- type Decimal128
- type Document
- func (doc *Document) Add(name string, value any) error
- func (doc *Document) Command() string
- func (doc *Document) Decode() (*Document, error)
- func (doc *Document) Encode() (RawDocument, error)
- func (doc *Document) FieldNames() []string
- func (doc *Document) Freeze()
- func (doc *Document) Get(name string) any
- func (doc *Document) LogValue() slog.Value
- func (doc *Document) Remove(name string)
- func (doc *Document) Replace(name string, value any) error
- type NullType
- type ObjectID
- type RawArray
- type RawDocument
- type Regex
- type ScalarType
- type Timestamp
- type Type
Constants ¶
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 ¶
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 )
var Null = bsonproto.Null
Null represents BSON scalar value null.
Functions ¶
func DecodeCString ¶
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 ¶
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 ¶
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 ¶
LogMessage returns a representation as a string. It may change over time.
func LogMessageBlock ¶
LogMessageBlock is a variant of [RawArray.LogMessage] that never uses a flow style.
func LogMessageFlow ¶
LogMessageFlow is a variant of [RawArray.LogMessage] that always uses a flow style.
func SizeCString ¶
SizeCString returns a size of the encoding of v cstring in bytes.
Types ¶
type AnyArray ¶
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)
}
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 (*Array) Encode ¶
Encode encodes non-nil 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.
Receiver must not be nil.
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 ¶
Get returns the element at the given index. It panics if index is out of bounds.
func (*Array) LogValue ¶
LogValue implements slog.LogValuer.
type BinarySubtype ¶
type BinarySubtype = bsonproto.BinarySubtype
BinarySubtype represents BSON Binary's subtype.
type CompositeType ¶
type CompositeType interface {
*Document | *Array | RawDocument | RawArray
}
CompositeType represents a BSON composite type (including raw types).
type Decimal128 ¶
type Decimal128 = bsonproto.Decimal128
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 ¶
MakeDocument creates a new empty Document with the given capacity.
func NewDocument ¶
NewDocument creates a new Document from the given pairs of field names and values.
func (*Document) Command ¶
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) Encode ¶
func (doc *Document) Encode() (RawDocument, error)
Encode encodes non-nil 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.
Receiver must not be nil.
func (*Document) FieldNames ¶
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 ¶
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 ¶
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 ¶
LogValue implements slog.LogValuer.
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 ¶
Decode decodes a single BSON array that takes the whole not-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.
Receiver must not be nil.
func (RawArray) DecodeDeep ¶
DecodeDeep decodes a single valid BSON array that takes the whole not-nil byte slice.
All nested documents and arrays are decoded recursively.
Receiver must not be nil.
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 BSON document that takes the whole not-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.
Receiver must not be nil.
func (RawDocument) DecodeDeep ¶
func (raw RawDocument) DecodeDeep() (*Document, error)
DecodeDeep decodes a single valid BSON document that takes the whole not-nil byte slice.
All nested documents and arrays are decoded recursively.
Receiver must not be nil.
func (RawDocument) Encode ¶
func (raw RawDocument) Encode() (RawDocument, error)
Encode returns itself to implement the AnyDocument interface.
Receiver must not be nil.
func (RawDocument) LogValue ¶
func (raw RawDocument) LogValue() slog.Value
LogValue implements slog.LogValuer.
type ScalarType ¶
type ScalarType = bsonproto.ScalarType
ScalarType represents a BSON scalar type.
CString is not included as it is not a real BSON type.
Source Files