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) GetByIndex(i int) (string, any)
- func (doc *Document) Len() int
- 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 LogMessage that never uses a flow style.
func LogMessageFlow ¶
LogMessageFlow is a variant of 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 MustDocument ¶ added in v0.0.3
MustDocument is a variant of NewDocument that panics on error.
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 in the original order.
If document contains duplicate field names, the same name will 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. To get other fields, a for/range loop can be used with Document.Len and Document.GetByIndex. Or iterators.
func (*Document) GetByIndex ¶ added in v0.0.5
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.
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