bsoncore

package
v1.13.1 Latest Latest
Warning

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

 Go to latest Published: Dec 6, 2023 License: Apache-2.0 Imports: 13 Imported by: 750

Documentation

Overview

Package bsoncore contains functions that can be used to encode and decode BSON elements and values to or from a slice of bytes. These functions are aimed at allowing low level manipulation of BSON and can be used to build a higher level BSON library.

The Read* functions within this package return the values of the element and a boolean indicating if the values are valid. A boolean was used instead of an error because any error that would be returned would be the same: not enough bytes. This library attempts to do no validation, it will only return false if there are not enough bytes for an item to be read. For example, the ReadDocument function checks the length, if that length is larger than the number of bytes available, it will return false, if there are enough bytes, it will return those bytes and true. It is the consumers responsibility to validate those bytes.

The Append* functions within this package will append the type value to the given dst slice. If the slice has enough capacity, it will not grow the slice. The Append*Element functions within this package operate in the same way, but additionally append the BSON type and the key before the value.

Warning: Package bsoncore is unstable and there is no backward compatibility guarantee. It is experimental and subject to change.

Index

Examples

Constants

View Source 
const (
	// EmptyDocumentLength is the length of a document that has been started/ended but has no elements.
	EmptyDocumentLength = 5
)

Variables

View Source 
var BuildDocumentFromElements = BuildDocument

BuildDocumentFromElements is an alaias for the BuildDocument function.

View Source 
var ErrCorruptedDocument = errors.New("invalid DocumentSequence: corrupted document")

ErrCorruptedDocument is returned when a full document couldn't be read from the sequence.

View Source 
var ErrElementNotFound = errors.New("element not found")

ErrElementNotFound indicates that an Element matching a certain condition does not exist.

View Source 
var ErrEmptyKey = errors.New("empty key provided")

ErrEmptyKey indicates that no key was provided to a Lookup method.

View Source 
var ErrInvalidDocumentSequenceStyle = errors.New("invalid DocumentSequenceStyle")

ErrInvalidDocumentSequenceStyle is returned when an unknown DocumentSequenceStyle is set on a DocumentSequence.

View Source 
var ErrNilReader = errors.New("nil reader")

ErrNilReader indicates that an operation was attempted on a nil io.Reader.

View Source 
var ErrNonDocument = errors.New("invalid DocumentSequence: a non-document value was found in sequence")

ErrNonDocument is returned when a DocumentSequence contains a non-document BSON value.

View Source 
var ErrOutOfBounds = errors.New("out of bounds")

ErrOutOfBounds indicates that an index provided to access something was invalid.

Functions

func AppendArray 

func AppendArray(dst []byte, arr []byte) []byte

AppendArray will append arr to dst and return the extended buffer.

func AppendArrayElement 

func AppendArrayElement(dst []byte, key string, arr []byte) []byte

AppendArrayElement will append a BSON array element using key and arr to dst and return the extended buffer.

func AppendArrayElementStart 

func AppendArrayElementStart(dst []byte, key string) (index int32, b []byte)

AppendArrayElementStart appends an array element header and then the length bytes for an array, returning the index where the length starts.

func AppendArrayEnd 

func AppendArrayEnd(dst []byte, index int32) ([]byte, error)

AppendArrayEnd appends the null byte to an array and calculates the length, inserting that calculated length starting at index.

func AppendArrayStart 

func AppendArrayStart(dst []byte) (index int32, b []byte)

AppendArrayStart appends the length bytes to an array and then returns the index of the start of those length bytes.

func AppendBinary 

func AppendBinary(dst []byte, subtype byte, b []byte) []byte

AppendBinary will append subtype and b to dst and return the extended buffer.

func AppendBinaryElement 

func AppendBinaryElement(dst []byte, key string, subtype byte, b []byte) []byte

AppendBinaryElement will append a BSON binary element using key, subtype, and b to dst and return the extended buffer.

func AppendBoolean 

func AppendBoolean(dst []byte, b bool) []byte

AppendBoolean will append b to dst and return the extended buffer.

func AppendBooleanElement 

func AppendBooleanElement(dst []byte, key string, b bool) []byte

AppendBooleanElement will append a BSON boolean element using key and b to dst and return the extended buffer.

func AppendCodeWithScope 

func AppendCodeWithScope(dst []byte, code string, scope []byte) []byte

AppendCodeWithScope will append code and scope to dst and return the extended buffer.

func AppendCodeWithScopeElement 

func AppendCodeWithScopeElement(dst []byte, key, code string, scope []byte) []byte

AppendCodeWithScopeElement will append a BSON code with scope element using key, code, and scope to dst and return the extended buffer.

func AppendDBPointer 

func AppendDBPointer(dst []byte, ns string, oid primitive.ObjectID) []byte

AppendDBPointer will append ns and oid to dst and return the extended buffer.

func AppendDBPointerElement 

func AppendDBPointerElement(dst []byte, key, ns string, oid primitive.ObjectID) []byte

AppendDBPointerElement will append a BSON DBPointer element using key, ns, and oid to dst and return the extended buffer.

func AppendDateTime 

func AppendDateTime(dst []byte, dt int64) []byte

AppendDateTime will append dt to dst and return the extended buffer.

func AppendDateTimeElement 

func AppendDateTimeElement(dst []byte, key string, dt int64) []byte

AppendDateTimeElement will append a BSON datetime element using key and dt to dst and return the extended buffer.

func AppendDecimal128 

func AppendDecimal128(dst []byte, d128 primitive.Decimal128) []byte

AppendDecimal128 will append d128 to dst and return the extended buffer.

func AppendDecimal128Element 

func AppendDecimal128Element(dst []byte, key string, d128 primitive.Decimal128) []byte

AppendDecimal128Element will append a BSON primitive.28 element using key and d128 to dst and return the extended buffer.

func AppendDocument 

func AppendDocument(dst []byte, doc []byte) []byte

AppendDocument will append doc to dst and return the extended buffer.

func AppendDocumentElement 

func AppendDocumentElement(dst []byte, key string, doc []byte) []byte

AppendDocumentElement will append a BSON embedded document element using key and doc to dst and return the extended buffer.

func AppendDocumentElementStart 

func AppendDocumentElementStart(dst []byte, key string) (index int32, b []byte)

AppendDocumentElementStart writes a document element header and then reserves the length bytes.

func AppendDocumentEnd 

func AppendDocumentEnd(dst []byte, index int32) ([]byte, error)

AppendDocumentEnd writes the null byte for a document and updates the length of the document. The index should be the beginning of the document's length bytes.

func AppendDocumentStart 

func AppendDocumentStart(dst []byte) (index int32, b []byte)

AppendDocumentStart reserves a document's length and returns the index where the length begins. This index can later be used to write the length of the document.

func AppendDocumentStartInline 

func AppendDocumentStartInline(dst []byte, index *int32) []byte

AppendDocumentStartInline functions the same as AppendDocumentStart but takes a pointer to the index int32 which allows this function to be used inline.

func AppendDouble 

func AppendDouble(dst []byte, f float64) []byte

AppendDouble will append f to dst and return the extended buffer.

func AppendDoubleElement 

func AppendDoubleElement(dst []byte, key string, f float64) []byte

AppendDoubleElement will append a BSON double element using key and f to dst and return the extended buffer.

func AppendHeader 

func AppendHeader(dst []byte, t bsontype.Type, key string) []byte

AppendHeader will append Type t and key to dst and return the extended buffer.

func AppendInt32 

func AppendInt32(dst []byte, i32 int32) []byte

AppendInt32 will append i32 to dst and return the extended buffer.

func AppendInt32Element 

func AppendInt32Element(dst []byte, key string, i32 int32) []byte

AppendInt32Element will append a BSON int32 element using key and i32 to dst and return the extended buffer.

func AppendInt64 

func AppendInt64(dst []byte, i64 int64) []byte

AppendInt64 will append i64 to dst and return the extended buffer.

func AppendInt64Element 

func AppendInt64Element(dst []byte, key string, i64 int64) []byte

AppendInt64Element will append a BSON int64 element using key and i64 to dst and return the extended buffer.

func AppendJavaScript 

func AppendJavaScript(dst []byte, js string) []byte

AppendJavaScript will append js to dst and return the extended buffer.

func AppendJavaScriptElement 

func AppendJavaScriptElement(dst []byte, key, js string) []byte

AppendJavaScriptElement will append a BSON JavaScript element using key and js to dst and return the extended buffer.

func AppendKey 

func AppendKey(dst []byte, key string) []byte

AppendKey will append key to dst and return the extended buffer.

func AppendMaxKeyElement 

func AppendMaxKeyElement(dst []byte, key string) []byte

AppendMaxKeyElement will append a BSON max key element using key to dst and return the extended buffer.

func AppendMinKeyElement 

func AppendMinKeyElement(dst []byte, key string) []byte

AppendMinKeyElement will append a BSON min key element using key to dst and return the extended buffer.

func AppendNullElement 

func AppendNullElement(dst []byte, key string) []byte

AppendNullElement will append a BSON null element using key to dst and return the extended buffer.

func AppendObjectID 

func AppendObjectID(dst []byte, oid primitive.ObjectID) []byte

AppendObjectID will append oid to dst and return the extended buffer.

func AppendObjectIDElement 

func AppendObjectIDElement(dst []byte, key string, oid primitive.ObjectID) []byte

AppendObjectIDElement will append a BSON ObjectID element using key and oid to dst and return the extended buffer.

func AppendRegex 

func AppendRegex(dst []byte, pattern, options string) []byte

AppendRegex will append pattern and options to dst and return the extended buffer.

func AppendRegexElement 

func AppendRegexElement(dst []byte, key, pattern, options string) []byte

AppendRegexElement will append a BSON regex element using key, pattern, and options to dst and return the extended buffer.

func AppendString 

func AppendString(dst []byte, s string) []byte

AppendString will append s to dst and return the extended buffer.

func AppendStringElement 

func AppendStringElement(dst []byte, key, val string) []byte

AppendStringElement will append a BSON string element using key and val to dst and return the extended buffer.

func AppendSymbol 

func AppendSymbol(dst []byte, symbol string) []byte

AppendSymbol will append symbol to dst and return the extended buffer.

func AppendSymbolElement 

func AppendSymbolElement(dst []byte, key, symbol string) []byte

AppendSymbolElement will append a BSON symbol element using key and symbol to dst and return the extended buffer.

func AppendTime 

func AppendTime(dst []byte, t time.Time) []byte

AppendTime will append time as a BSON DateTime to dst and return the extended buffer.

func AppendTimeElement 

func AppendTimeElement(dst []byte, key string, t time.Time) []byte

AppendTimeElement will append a BSON datetime element using key and dt to dst and return the extended buffer.

func AppendTimestamp 

func AppendTimestamp(dst []byte, t, i uint32) []byte

AppendTimestamp will append t and i to dst and return the extended buffer.

func AppendTimestampElement 

func AppendTimestampElement(dst []byte, key string, t, i uint32) []byte

AppendTimestampElement will append a BSON timestamp element using key, t, and i to dst and return the extended buffer.

func AppendType 

func AppendType(dst []byte, t bsontype.Type) []byte

AppendType will append t to dst and return the extended buffer.

func AppendUndefinedElement 

func AppendUndefinedElement(dst []byte, key string) []byte

AppendUndefinedElement will append a BSON undefined element using key to dst and return the extended buffer.

func AppendValueElement added in v1.1.0 

func AppendValueElement(dst []byte, key string, value Value) []byte

AppendValueElement appends value to dst as an element using key as the element's key.

func BuildArray added in v1.1.0 

func BuildArray(dst []byte, values ...Value) []byte

BuildArray will append a BSON array to dst built from values.

func BuildArrayElement added in v1.1.0 

func BuildArrayElement(dst []byte, key string, values ...Value) []byte

BuildArrayElement will create an array element using the provided values.

func BuildDocument 

func BuildDocument(dst []byte, elems ...[]byte) []byte

BuildDocument will create a document with the given slice of elements and will append it to dst and return the extended buffer.

func BuildDocumentElement added in v1.1.0 

func BuildDocumentElement(dst []byte, key string, elems ...[]byte) []byte

BuildDocumentElement will append a BSON embedded document element using key and the provided elements and return the extended buffer.

func EqualValue 

func EqualValue(t1, t2 bsontype.Type, v1, v2 []byte) bool

EqualValue will return true if the two values are equal.

func NewArrayLengthError added in v1.5.0 

func NewArrayLengthError(length, rem int) error

NewArrayLengthError creates and returns an error for when the length of an array exceeds the bytes available.

func NewDocumentLengthError 

func NewDocumentLengthError(length, rem int) error

NewDocumentLengthError creates and returns an error for when the length of a document exceeds the bytes available.

func ReadBinary 

func ReadBinary(src []byte) (subtype byte, bin []byte, rem []byte, ok bool)

ReadBinary will read a subtype and bin from src. If there are not enough bytes it will return false.

func ReadBoolean 

func ReadBoolean(src []byte) (bool, []byte, bool)

ReadBoolean will read a bool from src. If there are not enough bytes it will return false.

func ReadCodeWithScope 

func ReadCodeWithScope(src []byte) (code string, scope []byte, rem []byte, ok bool)

ReadCodeWithScope will read code and scope from src. If there are not enough bytes it will return false.

func ReadDBPointer 

func ReadDBPointer(src []byte) (ns string, oid primitive.ObjectID, rem []byte, ok bool)

ReadDBPointer will read a ns and oid from src. If there are not enough bytes it will return false.

func ReadDateTime 

func ReadDateTime(src []byte) (int64, []byte, bool)

ReadDateTime will read an int64 datetime from src. If there are not enough bytes it will return false.

func ReadDecimal128 

func ReadDecimal128(src []byte) (primitive.Decimal128, []byte, bool)

ReadDecimal128 will read a primitive.Decimal128 from src. If there are not enough bytes it will return false.

func ReadDouble 

func ReadDouble(src []byte) (float64, []byte, bool)

ReadDouble will read a float64 from src. If there are not enough bytes it will return false.

func ReadHeader 

func ReadHeader(src []byte) (t bsontype.Type, key string, rem []byte, ok bool)

ReadHeader will read a type byte and a key from src. If both of these values cannot be read, false is returned.

func ReadHeaderBytes 

func ReadHeaderBytes(src []byte) (header []byte, rem []byte, ok bool)

ReadHeaderBytes will read a type and a key from src and the remainder of the bytes are returned as rem. If either the type or key cannot be red, ok will be false.

func ReadInt32 

func ReadInt32(src []byte) (int32, []byte, bool)

ReadInt32 will read an int32 from src. If there are not enough bytes it will return false.

func ReadInt64 

func ReadInt64(src []byte) (int64, []byte, bool)

ReadInt64 will read an int64 from src. If there are not enough bytes it will return false.

func ReadJavaScript 

func ReadJavaScript(src []byte) (js string, rem []byte, ok bool)

ReadJavaScript will read a js string from src. If there are not enough bytes it will return false.

func ReadKey 

func ReadKey(src []byte) (string, []byte, bool)

ReadKey will read a key from src. The 0x00 byte will not be present in the returned string. If there are not enough bytes available, false is returned.

func ReadKeyBytes 

func ReadKeyBytes(src []byte) ([]byte, []byte, bool)

ReadKeyBytes will read a key from src as bytes. The 0x00 byte will not be present in the returned string. If there are not enough bytes available, false is returned.

func ReadLength 

func ReadLength(src []byte) (int32, []byte, bool)

ReadLength reads an int32 length from src and returns the length and the remaining bytes. If there aren't enough bytes to read a valid length, src is returned unomdified and the returned bool will be false.

func ReadObjectID 

func ReadObjectID(src []byte) (primitive.ObjectID, []byte, bool)

ReadObjectID will read an ObjectID from src. If there are not enough bytes it will return false.

func ReadRegex 

func ReadRegex(src []byte) (pattern, options string, rem []byte, ok bool)

ReadRegex will read a pattern and options from src. If there are not enough bytes it will return false.

func ReadString 

func ReadString(src []byte) (string, []byte, bool)

ReadString will read a string from src. If there are not enough bytes it will return false.

func ReadSymbol 

func ReadSymbol(src []byte) (symbol string, rem []byte, ok bool)

ReadSymbol will read a symbol string from src. If there are not enough bytes it will return false.

func ReadTime 

func ReadTime(src []byte) (time.Time, []byte, bool)

ReadTime will read an time.Time datetime from src. If there are not enough bytes it will return false.

func ReadTimestamp 

func ReadTimestamp(src []byte) (t, i uint32, rem []byte, ok bool)

ReadTimestamp will read t and i from src. If there are not enough bytes it will return false.

func ReadType 

func ReadType(src []byte) (bsontype.Type, []byte, bool)

ReadType will return the first byte of the provided []byte as a type. If there is no available byte, false is returned.

func ReserveLength 

func ReserveLength(dst []byte) (int32, []byte)

ReserveLength reserves the space required for length and returns the index where to write the length and the []byte with reserved space.

func UpdateLength 

func UpdateLength(dst []byte, index, length int32) []byte

UpdateLength updates the length at index with length and returns the []byte.

Types

type Array added in v1.1.0 

type Array []byte

Array is a raw bytes representation of a BSON array.

func NewArrayFromReader added in v1.5.0 

func NewArrayFromReader(r io.Reader) (Array, error)

NewArrayFromReader reads an array from r. This function will only validate the length is correct and that the array ends with a null byte.

func ReadArray 

func ReadArray(src []byte) (arr Array, rem []byte, ok bool)

ReadArray will read an array from src. If there are not enough bytes it will return false.

func (Array) DebugString added in v1.5.0 

func (a Array) DebugString() string

DebugString outputs a human readable version of Array. It will attempt to stringify the valid components of the array even if the entire array is not valid.

func (Array) Index added in v1.5.0 

func (a Array) Index(index uint) Value

Index searches for and retrieves the value at the given index. This method will panic if the array is invalid or if the index is out of bounds.

func (Array) IndexErr added in v1.5.0 

func (a Array) IndexErr(index uint) (Value, error)

IndexErr searches for and retrieves the value at the given index.

func (Array) String added in v1.5.0 

func (a Array) String() string

String outputs an ExtendedJSON version of Array. If the Array is not valid, this method returns an empty string.

func (Array) Validate added in v1.5.0 

func (a Array) Validate() error

Validate validates the array and ensures the elements contained within are valid.

func (Array) Values added in v1.5.0 

func (a Array) Values() ([]Value, error)

Values returns this array as a slice of values. The returned slice will contain valid values. If the array is not valid, the values up to the invalid point will be returned along with an error.

type ArrayBuilder added in v1.5.0 

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

ArrayBuilder builds a bson array

func NewArrayBuilder added in v1.5.0 

func NewArrayBuilder() *ArrayBuilder

NewArrayBuilder creates a new ArrayBuilder

func (*ArrayBuilder) AppendArray added in v1.5.0 

func (a *ArrayBuilder) AppendArray(arr []byte) *ArrayBuilder

AppendArray will append arr to ArrayBuilder.arr

func (*ArrayBuilder) AppendBinary added in v1.5.0 

func (a *ArrayBuilder) AppendBinary(subtype byte, b []byte) *ArrayBuilder

AppendBinary will append a BSON binary element using subtype, and b to a.arr

func (*ArrayBuilder) AppendBoolean added in v1.5.0 

func (a *ArrayBuilder) AppendBoolean(b bool) *ArrayBuilder

AppendBoolean will append a boolean element using b to a.arr

func (*ArrayBuilder) AppendCodeWithScope added in v1.5.0 

func (a *ArrayBuilder) AppendCodeWithScope(code string, scope Document) *ArrayBuilder

AppendCodeWithScope will append code and scope to a.arr

func (*ArrayBuilder) AppendDBPointer added in v1.5.0 

func (a *ArrayBuilder) AppendDBPointer(ns string, oid primitive.ObjectID) *ArrayBuilder

AppendDBPointer will append ns and oid to a.arr

func (*ArrayBuilder) AppendDateTime added in v1.5.0 

func (a *ArrayBuilder) AppendDateTime(dt int64) *ArrayBuilder

AppendDateTime will append datetime element dt to a.arr

func (*ArrayBuilder) AppendDecimal128 added in v1.5.0 

func (a *ArrayBuilder) AppendDecimal128(d128 primitive.Decimal128) *ArrayBuilder

AppendDecimal128 will append d128 to a.arr

func (*ArrayBuilder) AppendDocument added in v1.5.0 

func (a *ArrayBuilder) AppendDocument(doc []byte) *ArrayBuilder

AppendDocument will append doc to ArrayBuilder.arr

func (*ArrayBuilder) AppendDouble added in v1.5.0 

func (a *ArrayBuilder) AppendDouble(f float64) *ArrayBuilder

AppendDouble will append f to ArrayBuilder.doc

func (*ArrayBuilder) AppendInt32 added in v1.5.0 

func (a *ArrayBuilder) AppendInt32(i32 int32) *ArrayBuilder

AppendInt32 will append i32 to ArrayBuilder.arr

func (*ArrayBuilder) AppendInt64 added in v1.5.0 

func (a *ArrayBuilder) AppendInt64(i64 int64) *ArrayBuilder

AppendInt64 will append i64 to a.arr

func (*ArrayBuilder) AppendJavaScript added in v1.5.0 

func (a *ArrayBuilder) AppendJavaScript(js string) *ArrayBuilder

AppendJavaScript will append js to a.arr

func (*ArrayBuilder) AppendMaxKey added in v1.5.0 

func (a *ArrayBuilder) AppendMaxKey() *ArrayBuilder

AppendMaxKey will append a max key element to a.arr

func (*ArrayBuilder) AppendMinKey added in v1.5.0 

func (a *ArrayBuilder) AppendMinKey() *ArrayBuilder

AppendMinKey will append a min key element to a.arr

func (*ArrayBuilder) AppendNull added in v1.5.0 

func (a *ArrayBuilder) AppendNull() *ArrayBuilder

AppendNull will append a null element to a.arr

func (*ArrayBuilder) AppendObjectID added in v1.5.0 

func (a *ArrayBuilder) AppendObjectID(oid primitive.ObjectID) *ArrayBuilder

AppendObjectID will append oid to ArrayBuilder.doc

func (*ArrayBuilder) AppendRegex added in v1.5.0 

func (a *ArrayBuilder) AppendRegex(pattern, options string) *ArrayBuilder

AppendRegex will append pattern and options to a.arr

func (*ArrayBuilder) AppendString added in v1.5.0 

func (a *ArrayBuilder) AppendString(str string) *ArrayBuilder

AppendString will append str to ArrayBuilder.doc

func (*ArrayBuilder) AppendSymbol added in v1.5.0 

func (a *ArrayBuilder) AppendSymbol(symbol string) *ArrayBuilder

AppendSymbol will append symbol to a.arr

func (*ArrayBuilder) AppendTimestamp added in v1.5.0 

func (a *ArrayBuilder) AppendTimestamp(t, i uint32) *ArrayBuilder

AppendTimestamp will append t and i to a.arr

func (*ArrayBuilder) AppendUndefined added in v1.5.0 

func (a *ArrayBuilder) AppendUndefined() *ArrayBuilder

AppendUndefined will append a BSON undefined element using key to a.arr

func (*ArrayBuilder) AppendValue added in v1.5.0 

func (a *ArrayBuilder) AppendValue(val Value) *ArrayBuilder

AppendValue appends a BSON value to the array.

func (*ArrayBuilder) Build added in v1.5.0 

func (a *ArrayBuilder) Build() Array

Build updates the length of the array and index to the beginning of the documents length bytes, then returns the array (bson bytes)

func (*ArrayBuilder) FinishArray added in v1.5.0 

func (a *ArrayBuilder) FinishArray() *ArrayBuilder

FinishArray builds the most recent array created

func (*ArrayBuilder) StartArray added in v1.5.0 

func (a *ArrayBuilder) StartArray() *ArrayBuilder

StartArray starts building an inline Array. After this document is completed, the user must call a.FinishArray

type Document 

type Document []byte

Document is a raw bytes representation of a BSON document.

func NewDocumentFromReader 

func NewDocumentFromReader(r io.Reader) (Document, error)

NewDocumentFromReader reads a document from r. This function will only validate the length is correct and that the document ends with a null byte.

func ReadDocument 

func ReadDocument(src []byte) (doc Document, rem []byte, ok bool)

ReadDocument will read a document from src. If there are not enough bytes it will return false.

func (Document) DebugString 

func (d Document) DebugString() string

DebugString outputs a human readable version of Document. It will attempt to stringify the valid components of the document even if the entire document is not valid.

func (Document) Elements 

func (d Document) Elements() ([]Element, error)

Elements returns this document as a slice of elements. The returned slice will contain valid elements. If the document is not valid, the elements up to the invalid point will be returned along with an error.

func (Document) Index 

func (d Document) Index(index uint) Element

Index searches for and retrieves the element at the given index. This method will panic if the document is invalid or if the index is out of bounds.

func (Document) IndexErr 

func (d Document) IndexErr(index uint) (Element, error)

IndexErr searches for and retrieves the element at the given index.

func (Document) Lookup 

func (d Document) Lookup(key ...string) Value

Lookup searches the document, potentially recursively, for the given key. If there are multiple keys provided, this method will recurse down, as long as the top and intermediate nodes are either documents or arrays. If an error occurs or if the value doesn't exist, an empty Value is returned.

func (Document) LookupErr 

func (d Document) LookupErr(key ...string) (Value, error)

LookupErr is the same as Lookup, except it returns an error in addition to an empty Value.

func (Document) String 

func (d Document) String() string

String outputs an ExtendedJSON version of Document. If the document is not valid, this method returns an empty string.

func (Document) Validate 

func (d Document) Validate() error

Validate validates the document and ensures the elements contained within are valid.

Example 
doc := make(Document, 500)
doc[250], doc[251], doc[252], doc[253], doc[254] = 0x05, 0x00, 0x00, 0x00, 0x00
err := doc[250:].Validate()
fmt.Println(err)

Output:

<nil>

func (Document) Values 

func (d Document) Values() ([]Value, error)

Values returns this document as a slice of values. The returned slice will contain valid values. If the document is not valid, the values up to the invalid point will be returned along with an error.

type DocumentBuilder added in v1.5.0 

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

DocumentBuilder builds a bson document

func NewDocumentBuilder added in v1.5.0 

func NewDocumentBuilder() *DocumentBuilder

NewDocumentBuilder creates a new DocumentBuilder

func (*DocumentBuilder) AppendArray added in v1.5.0 

func (db *DocumentBuilder) AppendArray(key string, arr []byte) *DocumentBuilder

AppendArray will append a bson array using key and arr to DocumentBuilder.doc

func (*DocumentBuilder) AppendBinary added in v1.5.0 

func (db *DocumentBuilder) AppendBinary(key string, subtype byte, b []byte) *DocumentBuilder

AppendBinary will append a BSON binary element using key, subtype, and b to db.doc

func (*DocumentBuilder) AppendBoolean added in v1.5.0 

func (db *DocumentBuilder) AppendBoolean(key string, b bool) *DocumentBuilder

AppendBoolean will append a boolean element using key and b to db.doc

func (*DocumentBuilder) AppendCodeWithScope added in v1.5.0 

func (db *DocumentBuilder) AppendCodeWithScope(key string, code string, scope Document) *DocumentBuilder

AppendCodeWithScope will append code and scope using key to db.doc

func (*DocumentBuilder) AppendDBPointer added in v1.5.0 

func (db *DocumentBuilder) AppendDBPointer(key string, ns string, oid primitive.ObjectID) *DocumentBuilder

AppendDBPointer will append ns and oid to using key to db.doc

func (*DocumentBuilder) AppendDateTime added in v1.5.0 

func (db *DocumentBuilder) AppendDateTime(key string, dt int64) *DocumentBuilder

AppendDateTime will append a datetime element using key and dt to db.doc

func (*DocumentBuilder) AppendDecimal128 added in v1.5.0 

func (db *DocumentBuilder) AppendDecimal128(key string, d128 primitive.Decimal128) *DocumentBuilder

AppendDecimal128 will append d128 to db.doc using provided key

func (*DocumentBuilder) AppendDocument added in v1.5.0 

func (db *DocumentBuilder) AppendDocument(key string, doc []byte) *DocumentBuilder

AppendDocument will append a bson embedded document element using key and doc to DocumentBuilder.doc

func (*DocumentBuilder) AppendDouble added in v1.5.0 

func (db *DocumentBuilder) AppendDouble(key string, f float64) *DocumentBuilder

AppendDouble will append a double element using key and f to DocumentBuilder.doc

func (*DocumentBuilder) AppendInt32 added in v1.5.0 

func (db *DocumentBuilder) AppendInt32(key string, i32 int32) *DocumentBuilder

AppendInt32 will append an int32 element using key and i32 to DocumentBuilder.doc

func (*DocumentBuilder) AppendInt64 added in v1.5.0 

func (db *DocumentBuilder) AppendInt64(key string, i64 int64) *DocumentBuilder

AppendInt64 will append i64 to dst using key to db.doc

func (*DocumentBuilder) AppendJavaScript added in v1.5.0 

func (db *DocumentBuilder) AppendJavaScript(key, js string) *DocumentBuilder

AppendJavaScript will append js using the provided key to db.doc

func (*DocumentBuilder) AppendMaxKey added in v1.5.0 

func (db *DocumentBuilder) AppendMaxKey(key string) *DocumentBuilder

AppendMaxKey will append a max key element using key to db.doc

func (*DocumentBuilder) AppendMinKey added in v1.5.0 

func (db *DocumentBuilder) AppendMinKey(key string) *DocumentBuilder

AppendMinKey will append a min key element using key to db.doc

func (*DocumentBuilder) AppendNull added in v1.5.0 

func (db *DocumentBuilder) AppendNull(key string) *DocumentBuilder

AppendNull will append a null element using key to db.doc

func (*DocumentBuilder) AppendObjectID added in v1.5.0 

func (db *DocumentBuilder) AppendObjectID(key string, oid primitive.ObjectID) *DocumentBuilder

AppendObjectID will append oid to DocumentBuilder.doc with the given key

func (*DocumentBuilder) AppendRegex added in v1.5.0 

func (db *DocumentBuilder) AppendRegex(key, pattern, options string) *DocumentBuilder

AppendRegex will append pattern and options using key to db.doc

func (*DocumentBuilder) AppendString added in v1.5.0 

func (db *DocumentBuilder) AppendString(key string, str string) *DocumentBuilder

AppendString will append str to DocumentBuilder.doc with the given key

func (*DocumentBuilder) AppendSymbol added in v1.5.0 

func (db *DocumentBuilder) AppendSymbol(key, symbol string) *DocumentBuilder

AppendSymbol will append a BSON symbol element using key and symbol db.doc

func (*DocumentBuilder) AppendTimestamp added in v1.5.0 

func (db *DocumentBuilder) AppendTimestamp(key string, t, i uint32) *DocumentBuilder

AppendTimestamp will append t and i to db.doc using provided key

func (*DocumentBuilder) AppendUndefined added in v1.5.0 

func (db *DocumentBuilder) AppendUndefined(key string) *DocumentBuilder

AppendUndefined will append a BSON undefined element using key to db.doc

func (*DocumentBuilder) AppendValue added in v1.5.0 

func (db *DocumentBuilder) AppendValue(key string, val Value) *DocumentBuilder

AppendValue will append a BSON element with the provided key and value to the document.

func (*DocumentBuilder) Build added in v1.5.0 

func (db *DocumentBuilder) Build() Document

Build updates the length of the document and index to the beginning of the documents length bytes, then returns the document (bson bytes)

func (*DocumentBuilder) FinishDocument added in v1.5.0 

func (db *DocumentBuilder) FinishDocument() *DocumentBuilder

FinishDocument builds the most recent document created

func (*DocumentBuilder) StartDocument added in v1.5.0 

func (db *DocumentBuilder) StartDocument(key string) *DocumentBuilder

StartDocument starts building an inline document element with the provided key After this document is completed, the user must call finishDocument

type DocumentSequence added in v1.0.0 

type DocumentSequence struct {
	Style DocumentSequenceStyle
	Data  []byte
	Pos   int
}

DocumentSequence represents a sequence of documents. The Style field indicates how the documents are laid out inside of the Data field.

func (*DocumentSequence) DocumentCount added in v1.0.0 

func (ds *DocumentSequence) DocumentCount() int

DocumentCount returns the number of documents in the sequence.

func (*DocumentSequence) Documents added in v1.1.0 

func (ds *DocumentSequence) Documents() ([]Document, error)

Documents returns a slice of the documents. If nil either the Data field is also nil or could not be properly read.

func (*DocumentSequence) Empty added in v1.1.0 

func (ds *DocumentSequence) Empty() bool

Empty returns true if the sequence is empty. It always returns true for unknown sequence styles.

func (*DocumentSequence) Next added in v1.0.0 

func (ds *DocumentSequence) Next() (Document, error)

Next retrieves the next document from this sequence and returns it. This method will return io.EOF when it has reached the end of the sequence.

func (*DocumentSequence) ResetIterator added in v1.0.0 

func (ds *DocumentSequence) ResetIterator()

ResetIterator resets the iteration point for the Next method to the beginning of the document sequence.

type DocumentSequenceStyle added in v1.0.0 

type DocumentSequenceStyle uint32

DocumentSequenceStyle is used to represent how a document sequence is laid out in a slice of bytes. 

const (
	SequenceStyle DocumentSequenceStyle
	ArrayStyle
)

These constants are the valid styles for a DocumentSequence.

type Element 

type Element []byte

Element is a raw bytes representation of a BSON element.

func ReadElement 

func ReadElement(src []byte) (Element, []byte, bool)

ReadElement reads the next full element from src. It returns the element, the remaining bytes in the slice, and a boolean indicating if the read was successful.

func (Element) CompareKey 

func (e Element) CompareKey(key []byte) bool

CompareKey will compare this element's key to key. This method makes it easy to compare keys without needing to allocate a string. The key may be null terminated. If a valid key cannot be read this method will return false.

func (Element) DebugString 

func (e Element) DebugString() string

DebugString outputs a human readable version of RawElement. It will attempt to stringify the valid components of the element even if the entire element is not valid.

func (Element) Key 

func (e Element) Key() string

Key returns the key for this element. If the element is not valid, this method returns an empty string. If knowing if the element is valid is important, use KeyErr.

func (Element) KeyBytes 

func (e Element) KeyBytes() []byte

KeyBytes returns the key for this element as a []byte. If the element is not valid, this method returns an empty string. If knowing if the element is valid is important, use KeyErr. This method will not include the null byte at the end of the key in the slice of bytes.

func (Element) KeyBytesErr 

func (e Element) KeyBytesErr() ([]byte, error)

KeyBytesErr returns the key for this element as a []byte, returning an error if the element is not valid.

func (Element) KeyErr 

func (e Element) KeyErr() (string, error)

KeyErr returns the key for this element, returning an error if the element is not valid.

func (Element) String 

func (e Element) String() string

String implements the fmt.String interface. The output will be in extended JSON format.

func (Element) Validate 

func (e Element) Validate() error

Validate ensures the element is a valid BSON element.

func (Element) Value 

func (e Element) Value() Value

Value returns the value of this element. If the element is not valid, this method returns an empty Value. If knowing if the element is valid is important, use ValueErr.

func (Element) ValueErr 

func (e Element) ValueErr() (Value, error)

ValueErr returns the value for this element, returning an error if the element is not valid.

type ElementTypeError 

type ElementTypeError struct {
	Method string
	Type   bsontype.Type
}

ElementTypeError specifies that a method to obtain a BSON value an incorrect type was called on a bson.Value.

func (ElementTypeError) Error 

func (ete ElementTypeError) Error() string

Error implements the error interface.

type InsufficientBytesError 

type InsufficientBytesError struct {
	Source    []byte
	Remaining []byte
}

InsufficientBytesError indicates that there were not enough bytes to read the next component.

func NewInsufficientBytesError 

func NewInsufficientBytesError(src, rem []byte) InsufficientBytesError

NewInsufficientBytesError creates a new InsufficientBytesError with the given Document and remaining bytes.

func (InsufficientBytesError) Equal 

func (ibe InsufficientBytesError) Equal(err2 error) bool

Equal checks that err2 also is an ErrTooSmall.

func (InsufficientBytesError) Error 

func (ibe InsufficientBytesError) Error() string

Error implements the error interface.

type InvalidDepthTraversalError 

type InvalidDepthTraversalError struct {
	Key  string
	Type bsontype.Type
}

InvalidDepthTraversalError is returned when attempting a recursive Lookup when one component of the path is neither an embedded document nor an array.

func (InvalidDepthTraversalError) Error 

func (idte InvalidDepthTraversalError) Error() string

type MalformedElementError 

type MalformedElementError string

MalformedElementError represents a class of errors that RawElement methods return. 

const ErrElementMissingKey MalformedElementError = "element is missing key"

ErrElementMissingKey is returned when a RawElement is missing a key. 

const ErrElementMissingType MalformedElementError = "element is missing type"

ErrElementMissingType is returned when a RawElement is missing a type.

func (MalformedElementError) Error 

func (mee MalformedElementError) Error() string

type ValidationError added in v1.5.0 

type ValidationError string

ValidationError is an error type returned when attempting to validate a document or array. 

const ErrInvalidLength ValidationError = "document or array length is invalid"

ErrInvalidLength indicates that a length in a binary representation of a BSON document or array is invalid. 

const ErrMissingNull ValidationError = "document or array end is missing null byte"

ErrMissingNull is returned when a document or array's last byte is not null.

func (ValidationError) Error added in v1.5.0 

func (ve ValidationError) Error() string

type Value 

type Value struct {
	Type bsontype.Type
	Data []byte
}

Value represents a BSON value with a type and raw bytes.

func BuildDocumentValue added in v1.1.0 

func BuildDocumentValue(elems ...[]byte) Value

BuildDocumentValue creates an Embedded Document value from the given elements.

func ReadValue 

func ReadValue(src []byte, t bsontype.Type) (Value, []byte, bool)

ReadValue reads the next value as the provided types and returns a Value, the remaining bytes, and a boolean indicating if the read was successful.

func (Value) Array 

func (v Value) Array() Array

Array returns the BSON array the Value represents as an Array. It panics if the value is a BSON type other than array.

func (Value) ArrayOK 

func (v Value) ArrayOK() (Array, bool)

ArrayOK is the same as Array, except it returns a boolean instead of panicking.

func (Value) AsInt32 

func (v Value) AsInt32() int32

AsInt32 returns a BSON number as an int32. If the BSON type is not a numeric one, this method will panic.

func (Value) AsInt32OK 

func (v Value) AsInt32OK() (int32, bool)

AsInt32OK functions the same as AsInt32 but returns a boolean instead of panicking. False indicates an error.

func (Value) AsInt64 

func (v Value) AsInt64() int64

AsInt64 returns a BSON number as an int64. If the BSON type is not a numeric one, this method will panic.

func (Value) AsInt64OK 

func (v Value) AsInt64OK() (int64, bool)

AsInt64OK functions the same as AsInt64 but returns a boolean instead of panicking. False indicates an error.

func (Value) Binary 

func (v Value) Binary() (subtype byte, data []byte)

Binary returns the BSON binary value the Value represents. It panics if the value is a BSON type other than binary.

func (Value) BinaryOK 

func (v Value) BinaryOK() (subtype byte, data []byte, ok bool)

BinaryOK is the same as Binary, except it returns a boolean instead of panicking.

func (Value) Boolean 

func (v Value) Boolean() bool

Boolean returns the boolean value the Value represents. It panics if the value is a BSON type other than boolean.

func (Value) BooleanOK 

func (v Value) BooleanOK() (bool, bool)

BooleanOK is the same as Boolean, except it returns a boolean instead of panicking.

func (Value) CodeWithScope 

func (v Value) CodeWithScope() (string, Document)

CodeWithScope returns the BSON JavaScript code with scope the Value represents. It panics if the value is a BSON type other than JavaScript code with scope.

func (Value) CodeWithScopeOK 

func (v Value) CodeWithScopeOK() (string, Document, bool)

CodeWithScopeOK is the same as CodeWithScope, except that it returns a boolean instead of panicking.

func (Value) DBPointer 

func (v Value) DBPointer() (string, primitive.ObjectID)

DBPointer returns the BSON dbpointer value the Value represents. It panics if the value is a BSON type other than DBPointer.

func (Value) DBPointerOK 

func (v Value) DBPointerOK() (string, primitive.ObjectID, bool)

DBPointerOK is the same as DBPoitner, except that it returns a boolean instead of panicking.

func (Value) DateTime 

func (v Value) DateTime() int64

DateTime returns the BSON datetime value the Value represents as a unix timestamp. It panics if the value is a BSON type other than datetime.

func (Value) DateTimeOK 

func (v Value) DateTimeOK() (int64, bool)

DateTimeOK is the same as DateTime, except it returns a boolean instead of panicking.

func (Value) DebugString 

func (v Value) DebugString() string

DebugString outputs a human readable version of Document. It will attempt to stringify the valid components of the document even if the entire document is not valid.

func (Value) Decimal128 

func (v Value) Decimal128() primitive.Decimal128

Decimal128 returns the decimal the Value represents. It panics if the value is a BSON type other than decimal.

func (Value) Decimal128OK 

func (v Value) Decimal128OK() (primitive.Decimal128, bool)

Decimal128OK is the same as Decimal128, except that it returns a boolean instead of panicking.

func (Value) Document 

func (v Value) Document() Document

Document returns the BSON document the Value represents as a Document. It panics if the value is a BSON type other than document.

func (Value) DocumentOK 

func (v Value) DocumentOK() (Document, bool)

DocumentOK is the same as Document, except it returns a boolean instead of panicking.

func (Value) Double 

func (v Value) Double() float64

Double returns the float64 value for this element. It panics if e's BSON type is not bsontype.Double.

func (Value) DoubleOK 

func (v Value) DoubleOK() (float64, bool)

DoubleOK is the same as Double, but returns a boolean instead of panicking.

func (Value) Equal 

func (v Value) Equal(v2 Value) bool

Equal compaes v to v2 and returns true if they are equal.

func (Value) Int32 

func (v Value) Int32() int32

Int32 returns the int32 the Value represents. It panics if the value is a BSON type other than int32.

func (Value) Int32OK 

func (v Value) Int32OK() (int32, bool)

Int32OK is the same as Int32, except that it returns a boolean instead of panicking.

func (Value) Int64 

func (v Value) Int64() int64

Int64 returns the int64 the Value represents. It panics if the value is a BSON type other than int64.

func (Value) Int64OK 

func (v Value) Int64OK() (int64, bool)

Int64OK is the same as Int64, except that it returns a boolean instead of panicking.

func (Value) IsNumber 

func (v Value) IsNumber() bool

IsNumber returns true if the type of v is a numeric BSON type.

func (Value) JavaScript 

func (v Value) JavaScript() string

JavaScript returns the BSON JavaScript code value the Value represents. It panics if the value is a BSON type other than JavaScript code.

func (Value) JavaScriptOK 

func (v Value) JavaScriptOK() (string, bool)

JavaScriptOK is the same as Javascript, excepti that it returns a boolean instead of panicking.

func (Value) ObjectID 

func (v Value) ObjectID() primitive.ObjectID

ObjectID returns the BSON objectid value the Value represents. It panics if the value is a BSON type other than objectid.

func (Value) ObjectIDOK 

func (v Value) ObjectIDOK() (primitive.ObjectID, bool)

ObjectIDOK is the same as ObjectID, except it returns a boolean instead of panicking.

func (Value) Regex 

func (v Value) Regex() (pattern, options string)

Regex returns the BSON regex value the Value represents. It panics if the value is a BSON type other than regex.

func (Value) RegexOK 

func (v Value) RegexOK() (pattern, options string, ok bool)

RegexOK is the same as Regex, except it returns a boolean instead of panicking.

func (Value) String 

func (v Value) String() string

String implements the fmt.String interface. This method will return values in extended JSON format. If the value is not valid, this returns an empty string

func (Value) StringValue 

func (v Value) StringValue() string

StringValue returns the string balue for this element. It panics if e's BSON type is not bsontype.String.

NOTE: This method is called StringValue to avoid a collision with the String method which implements the fmt.Stringer interface.

func (Value) StringValueOK 

func (v Value) StringValueOK() (string, bool)

StringValueOK is the same as StringValue, but returns a boolean instead of panicking.

func (Value) Symbol 

func (v Value) Symbol() string

Symbol returns the BSON symbol value the Value represents. It panics if the value is a BSON type other than symbol.

func (Value) SymbolOK 

func (v Value) SymbolOK() (string, bool)

SymbolOK is the same as Symbol, excepti that it returns a boolean instead of panicking.

func (Value) Time 

func (v Value) Time() time.Time

Time returns the BSON datetime value the Value represents. It panics if the value is a BSON type other than datetime.

func (Value) TimeOK 

func (v Value) TimeOK() (time.Time, bool)

TimeOK is the same as Time, except it returns a boolean instead of panicking.

func (Value) Timestamp 

func (v Value) Timestamp() (t, i uint32)

Timestamp returns the BSON timestamp value the Value represents. It panics if the value is a BSON type other than timestamp.

func (Value) TimestampOK 

func (v Value) TimestampOK() (t, i uint32, ok bool)

TimestampOK is the same as Timestamp, except that it returns a boolean instead of panicking.

func (Value) Validate 

func (v Value) Validate() error

Validate ensures the value is a valid BSON value.

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.