bson

package
v0.0.17 Latest Latest
Warning

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

 Go to latest Published: Oct 25, 2018 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package bson is a library for reading, writing, and manipulating BSON. The library has three types for representing BSON.

The Reader type is used to validate and retrieve elements from a byte slice. If you are not manipulating the underlying document and just want to validate or ensure the document has certain keys, this is the type you should use.

The Document type is a more generic type that can do all the read actions the Reader can do and allows for manipulation of documents. The main usecase for this type is reading some BSON and then adding, changing, or removing elements or to build a document that will need to be manipulated later. If the document can be created in a single pass without the need to do any lookups, the Builder type is might be more appropriate.

The Builder type (in the "bson/builder" package) is used to create a BSON document. The type only allows the iterative building of a document, so there is no way to verify the contents outside of writing the document. If you have a Builder and need to conditionally add a field, you can write the document to a byte slice and use the Reader type to lookup the desired document, but in this case you should probably use a Document instead.

The Element type represents a BSON element and the Value type represents an individual value for a BSON element.

The Encoder and Decoder types can be used to marshal a type to an io.Writer or to unmarshal into a type from an io.Reader. These types will use reflection and evaluate struct tags unless the provided types implements the Marshaler or Unmarshaler interfaces. The Builder and Reader types can be used to implement these interfaces for types.

The DocumentEncoder type can be used to encode a type to a Document instead of an io.Writer. This is useful if some additional manipulation is required after encoding a document. This type supports the same encoding behavior as the Encoder type.

Index

Examples

Constants

View Source 
const (
	TypeDouble           = bsontype.Double
	TypeString           = bsontype.String
	TypeEmbeddedDocument = bsontype.EmbeddedDocument
	TypeArray            = bsontype.Array
	TypeBinary           = bsontype.Binary
	TypeUndefined        = bsontype.Undefined
	TypeObjectID         = bsontype.ObjectID
	TypeBoolean          = bsontype.Boolean
	TypeDateTime         = bsontype.DateTime
	TypeNull             = bsontype.Null
	TypeRegex            = bsontype.Regex
	TypeDBPointer        = bsontype.DBPointer
	TypeJavaScript       = bsontype.JavaScript
	TypeSymbol           = bsontype.Symbol
	TypeCodeWithScope    = bsontype.CodeWithScope
	TypeInt32            = bsontype.Int32
	TypeTimestamp        = bsontype.Timestamp
	TypeInt64            = bsontype.Int64
	TypeDecimal128       = bsontype.Decimal128
	TypeMinKey           = bsontype.MinKey
	TypeMaxKey           = bsontype.MaxKey
)

These constants uniquely refer to each BSON type.

Variables

View Source 
var DefaultRegistry = NewRegistryBuilder().Build()

DefaultRegistry is the default bsoncodec.Registry. It contains the default codecs and the primitive codecs.

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 ErrInvalidArrayKey = errors.New("invalid array key")

ErrInvalidArrayKey indicates that a key that isn't a positive integer was used to lookup an element in an array.

View Source 
var ErrInvalidBinarySubtype = errors.New("invalid BSON binary Subtype")

ErrInvalidBinarySubtype indicates that a BSON binary value had an undefined subtype.

View Source 
var ErrInvalidBooleanType = errors.New("invalid value for BSON Boolean Type")

ErrInvalidBooleanType indicates that a BSON boolean value had an incorrect byte.

View Source 
var ErrInvalidDepthTraversal = errors.New("invalid depth traversal")

ErrInvalidDepthTraversal indicates that a provided path of keys to a nested value in a document does not exist.

TODO(skriptble): This error message is pretty awful. Please fix.

View Source 
var ErrInvalidDocumentType = errors.New("invalid document type")

ErrInvalidDocumentType indicates that a type which doesn't represent a BSON document was was provided when a document was expected.

View Source 
var ErrInvalidElement = errors.New("invalid Element")

ErrInvalidElement indicates that a bson.Element had invalid underlying BSON.

View Source 
var ErrInvalidKey = errors.New("invalid document key")

ErrInvalidKey indicates that the BSON representation of a key is missing a null terminator.

View Source 
var ErrInvalidLength = errors.New("document length is invalid")

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

View Source 
var ErrInvalidReadOnlyDocument = errors.New("invalid read-only document")

ErrInvalidReadOnlyDocument indicates that the underlying bytes of a bson.Reader are invalid.

View Source 
var ErrInvalidString = errors.New("invalid string value")

ErrInvalidString indicates that a BSON string value had an incorrect length.

View Source 
var ErrInvalidWriter = errors.New("bson: invalid writer provided")

ErrInvalidWriter indicates that a type that can't be written into was passed to a writer method.

View Source 
var ErrNilDocument = errors.New("document is nil")

ErrNilDocument indicates that an operation was attempted on a nil *bson.Document.

View Source 
var ErrNilElement = errors.New("element is nil")

ErrNilElement indicates that a nil element was provided when none was expected.

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

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

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

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

View Source 
var ErrStringLargerThanContainer = errors.New("string size is larger than the JavaScript code with scope container")

ErrStringLargerThanContainer indicates that the code portion of a BSON JavaScript code with scope value is larger than the specified length of the entire value.

View Source 
var ErrUninitializedElement = errors.New("bson/ast/compact: Method call on uninitialized Element")

ErrUninitializedElement is returned whenever any method is invoked on an uninitialized Element.

View Source 
var MaxKey struct{}

MaxKey represents the BSON minkey value.

View Source 
var MinKey struct{}

MinKey represents the BSON maxkey value.

View Source 
var Null struct{}

Null represents the BSON null value.

View Source 
var Undefined struct{}

Undefined represents the BSON undefined value.

Functions

func Marshal added in v0.0.2 

func Marshal(val interface{}) ([]byte, error)

Marshal returns the BSON encoding of val.

Marshal will use the default registry created by NewRegistry to recursively marshal val into a []byte. Marshal will inspect struct tags and alter the marshaling process accordingly.

func MarshalAppend added in v0.0.14 

func MarshalAppend(dst []byte, val interface{}) ([]byte, error)

MarshalAppend will append the BSON encoding of val to dst. If dst is not large enough to hold the BSON encoding of val, dst will be grown.

func MarshalAppendWithRegistry added in v0.0.14 

func MarshalAppendWithRegistry(r *bsoncodec.Registry, dst []byte, val interface{}) ([]byte, error)

MarshalAppendWithRegistry will append the BSON encoding of val to dst using Registry r. If dst is not large enough to hold the BSON encoding of val, dst will be grown.

func MarshalExtJSON added in v0.0.17 

func MarshalExtJSON(val interface{}, canonical, escapeHTML bool) ([]byte, error)

MarshalExtJSON returns the extended JSON encoding of val.

func MarshalExtJSONAppend added in v0.0.17 

func MarshalExtJSONAppend(dst []byte, val interface{}, canonical, escapeHTML bool) ([]byte, error)

MarshalExtJSONAppend will append the extended JSON encoding of val to dst. If dst is not large enough to hold the extended JSON encoding of val, dst will be grown.

func MarshalExtJSONAppendWithRegistry added in v0.0.17 

func MarshalExtJSONAppendWithRegistry(r *bsoncodec.Registry, dst []byte, val interface{}, canonical, escapeHTML bool) ([]byte, error)

MarshalExtJSONAppendWithRegistry will append the extended JSON encoding of val to dst using Registry r. If dst is not large enough to hold the BSON encoding of val, dst will be grown.

func MarshalExtJSONWithRegistry added in v0.0.17 

func MarshalExtJSONWithRegistry(r *bsoncodec.Registry, val interface{}, canonical, escapeHTML bool) ([]byte, error)

MarshalExtJSONWithRegistry returns the extended JSON encoding of val using Registry r.

func MarshalWithRegistry added in v0.0.14 

func MarshalWithRegistry(r *bsoncodec.Registry, val interface{}) ([]byte, error)

MarshalWithRegistry returns the BSON encoding of val using Registry r.

func NewRegistryBuilder added in v0.0.14 

func NewRegistryBuilder() *bsoncodec.RegistryBuilder

NewRegistryBuilder creates a new RegistryBuilder configured with the default encoders and deocders from the bsoncodec.DefaultValueEncoders and bsoncodec.DefaultValueDecoders types and the PrimitiveCodecs type in this package.

func ToExtJSON added in v0.0.6 

func ToExtJSON(canonical bool, bson []byte) (string, error)

ToExtJSON converts a BSON byte slice into an extended JSON string. If canonical is true, it will output canonical extended JSON. Otherwise, it will output relaxed extended JSON.

func Unmarshal added in v0.0.2 

func Unmarshal(data []byte, val interface{}) error

Unmarshal parses the BSON-encoded data and stores the result in the value pointed to by val. If val is nil or not a pointer, Unmarshal returns InvalidUnmarshalError.

func UnmarshalExtJSON added in v0.0.17 

func UnmarshalExtJSON(data []byte, canonical bool, val interface{}) error

UnmarshalExtJSON parses the extended JSON-encoded data and stores the result in the value pointed to by val. If val is nil or not a pointer, Unmarshal returns InvalidUnmarshalError.

func UnmarshalExtJSONWithRegistry added in v0.0.17 

func UnmarshalExtJSONWithRegistry(r *bsoncodec.Registry, data []byte, canonical bool, val interface{}) error

UnmarshalExtJSONWithRegistry parses the extended JSON-encoded data using Registry r and stores the result in the value pointed to by val. If val is nil or not a pointer, UnmarshalWithRegistry returns InvalidUnmarshalError.

func UnmarshalWithRegistry added in v0.0.14 

func UnmarshalWithRegistry(r *bsoncodec.Registry, data []byte, val interface{}) error

UnmarshalWithRegistry parses the BSON-encoded data using Registry r and stores the result in the value pointed to by val. If val is nil or not a pointer, UnmarshalWithRegistry returns InvalidUnmarshalError.

Types

type Array 

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

Array represents an array in BSON. The methods of this type are more expensive than those on Document because they require potentially updating multiple keys to ensure the array stays valid at all times.

Example 
internalVersion := "1234567"

f := func(appName string) *Array {
	arr := NewArray()
	arr.Append(
		VC.DocumentFromElements(
			EC.String("name", "mongo-go-driver"),
			EC.String("version", internalVersion),
		),
		VC.DocumentFromElements(
			EC.String("type", "darwin"),
			EC.String("architecture", "amd64"),
		),
		VC.String("go1.9.2"),
	)
	if appName != "" {
		arr.Append(VC.DocumentFromElements(EC.String("name", appName)))
	}

	return arr
}
buf, err := f("hello-world").MarshalBSON()
if err != nil {
	fmt.Println(err)
}
fmt.Println(buf)

Output:

[154 0 0 0 3 48 0 52 0 0 0 2 110 97 109 101 0 16 0 0 0 109 111 110 103 111 45 103 111 45 100 114 105 118 101 114 0 2 118 101 114 115 105 111 110 0 8 0 0 0 49 50 51 52 53 54 55 0 0 3 49 0 46 0 0 0 2 116 121 112 101 0 7 0 0 0 100 97 114 119 105 110 0 2 97 114 99 104 105 116 101 99 116 117 114 101 0 6 0 0 0 97 109 100 54 52 0 0 2 50 0 8 0 0 0 103 111 49 46 57 46 50 0 3 51 0 27 0 0 0 2 110 97 109 101 0 12 0 0 0 104 101 108 108 111 45 119 111 114 108 100 0 0 0]

func ArrayFromDocument 

func ArrayFromDocument(doc *Document) *Array

ArrayFromDocument creates an array from a *Document. The returned array does not make a copy of the *Document, so any changes made to either will be present in both.

func NewArray 

func NewArray(values ...*Value) *Array

NewArray creates a new array with the specified value.

func (*Array) Append 

func (a *Array) Append(values ...*Value) *Array

Append adds the given values to the end of the array. It returns a reference to itself.

func (*Array) Concat 

func (a *Array) Concat(docs ...interface{}) error

Concat will append all the values from each of the arguments onto the array.

Each argument must be one of the following:

  • *Array
  • *Document
  • []byte
  • bson.Reader

Note that in the case of *Document, []byte, and bson.Reader, the keys will be ignored and only the values will be appended.

func (*Array) Delete 

func (a *Array) Delete(index uint) *Value

Delete removes the value at the given index from the array.

func (*Array) Equal added in v0.0.14 

func (a *Array) Equal(a2 *Array) bool

Equal compares this document to another, returning true if they are equal.

func (*Array) Iterator added in v0.0.7 

func (a *Array) Iterator() (*ArrayIterator, error)

Iterator returns a ArrayIterator that can be used to iterate through the elements of this Array.

func (*Array) Len 

func (a *Array) Len() int

Len returns the number of elements in the array.

func (*Array) Lookup 

func (a *Array) Lookup(index uint) (*Value, error)

Lookup returns the value in the array at the given index or an error if it cannot be found.

TODO: We should fix this to align with the semantics of the *Document type, e.g. have Lookup return just a *Value or panic if it's out of bounds and have a LookupOK that returns a bool. Although if we want to align with the semantics of how Go arrays and slices work, we would not provide a LookupOK and force users to use the Len method before hand to avoid panics.

func (*Array) MarshalBSON 

func (a *Array) MarshalBSON() ([]byte, error)

MarshalBSON implements the Marshaler interface.

func (*Array) Prepend 

func (a *Array) Prepend(values ...*Value) *Array

Prepend adds the given values to the beginning of the array. It returns a reference to itself.

func (*Array) Reset 

func (a *Array) Reset()

Reset clears all elements from the array.

func (*Array) Set 

func (a *Array) Set(index uint, value *Value) *Array

Set replaces the value at the given index with the parameter value. It panics if the index is out of bounds.

func (*Array) String 

func (a *Array) String() string

String implements the fmt.Stringer interface.

func (*Array) Validate 

func (a *Array) Validate() (uint32, error)

Validate ensures that the array's underlying BSON is valid. It returns the the number of bytes in the underlying BSON if it is valid or an error if it isn't.

func (*Array) WriteArray 

func (a *Array) WriteArray(start uint, writer []byte) (int64, error)

WriteArray will serialize this array to the provided writer beginning at the provided start position.

func (*Array) WriteTo 

func (a *Array) WriteTo(w io.Writer) (int64, error)

WriteTo implements the io.WriterTo interface.

type ArrayIterator added in v0.0.7 

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

ArrayIterator facilitates iterating over a bson.Array.

func NewArrayIterator added in v0.0.7 

func NewArrayIterator(array *Array) (*ArrayIterator, error)

NewArrayIterator constructs a new ArrayIterator over a given Array

func (*ArrayIterator) Err added in v0.0.7 

func (iter *ArrayIterator) Err() error

Err returns the error that occurred while iterating, or nil if none occurred.

func (*ArrayIterator) Next added in v0.0.7 

func (iter *ArrayIterator) Next() bool

Next fetches the next value in the Array, returning whether or not it could be fetched successfully. If true is returned, call Value to get the value. If false is returned, call Err to check if an error occurred.

func (*ArrayIterator) Value added in v0.0.7 

func (iter *ArrayIterator) Value() *Value

Value returns the current value of the ArrayIterator. The pointer returned will _always_ be the same for a given ArrayIterator. The returned value will be nil if this function is called before the first successful call to Next().

type Binary 

type Binary struct {
	Subtype byte
	Data    []byte
}

Binary represents a BSON binary value.

type CodeWithScope 

type CodeWithScope struct {
	Code  string
	Scope *Document
}

CodeWithScope represents a BSON JavaScript code with scope value.

func (CodeWithScope) String 

func (cws CodeWithScope) String() string

type DBPointer 

type DBPointer struct {
	DB      string
	Pointer objectid.ObjectID
}

DBPointer represents a BSON dbpointer value.

func (DBPointer) String 

func (d DBPointer) String() string

type DateTime added in v0.0.14 

type DateTime int64

DateTime represents the BSON datetime value.

type Decoder 

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

A Decoder reads and decodes BSON documents from a stream.

func NewDecoder 

func NewDecoder(r *bsoncodec.Registry, vr bsonrw.ValueReader) (*Decoder, error)

NewDecoder returns a new decoder that uses Registry reg to read from r.

func (*Decoder) Decode 

func (d *Decoder) Decode(val interface{}) error

Decode reads the next BSON document from the stream and decodes it into the value pointed to by val.

The documentation for Unmarshal contains details about of BSON into a Go value.

func (*Decoder) Reset added in v0.0.17 

func (d *Decoder) Reset(vr bsonrw.ValueReader) error

Reset will reset the state of the decoder, using the same *Registry used in the original construction but using r for reading.

func (*Decoder) SetRegistry added in v0.0.17 

func (d *Decoder) SetRegistry(r *bsoncodec.Registry) error

SetRegistry replaces the current registry of the decoder with r.

type Document 

type Document struct {
	// The default behavior or Append, Prepend, and Replace is to panic on the
	// insertion of a nil element. Setting IgnoreNilInsert to true will instead
	// silently ignore any nil parameters to these methods.
	IgnoreNilInsert bool
	// contains filtered or unexported fields
}

Document is a mutable ordered map that compactly represents a BSON document.

Example 
internalVersion := "1234567"

f := func(appName string) *Document {
	doc := NewDocument(
		EC.SubDocumentFromElements("driver",
			EC.String("name", "mongo-go-driver"),
			EC.String("version", internalVersion),
		),
		EC.SubDocumentFromElements("os",
			EC.String("type", "darwin"),
			EC.String("architecture", "amd64"),
		),
		EC.String("platform", "go1.9.2"),
	)
	if appName != "" {
		doc.Append(EC.SubDocumentFromElements("application", EC.String("name", appName)))
	}

	return doc
}
buf, err := f("hello-world").MarshalBSON()
if err != nil {
	fmt.Println(err)
}
fmt.Println(buf)

Output:

[177 0 0 0 3 100 114 105 118 101 114 0 52 0 0 0 2 110 97 109 101 0 16 0 0 0 109 111 110 103 111 45 103 111 45 100 114 105 118 101 114 0 2 118 101 114 115 105 111 110 0 8 0 0 0 49 50 51 52 53 54 55 0 0 3 111 115 0 46 0 0 0 2 116 121 112 101 0 7 0 0 0 100 97 114 119 105 110 0 2 97 114 99 104 105 116 101 99 116 117 114 101 0 6 0 0 0 97 109 100 54 52 0 0 2 112 108 97 116 102 111 114 109 0 8 0 0 0 103 111 49 46 57 46 50 0 3 97 112 112 108 105 99 97 116 105 111 110 0 27 0 0 0 2 110 97 109 101 0 12 0 0 0 104 101 108 108 111 45 119 111 114 108 100 0 0 0]

func NewDocument 

func NewDocument(elems ...*Element) *Document

NewDocument creates an empty Document. The numberOfElems parameter will preallocate the underlying storage which can prevent extra allocations.

func ReadDocument 

func ReadDocument(b []byte) (*Document, error)

ReadDocument will create a Document using the provided slice of bytes. If the slice of bytes is not a valid BSON document, this method will return an error.

func (*Document) Append 

func (d *Document) Append(elems ...*Element) *Document

Append adds each element to the end of the document, in order. If a nil element is passed as a parameter this method will panic. To change this behavior to silently ignore a nil element, set IgnoreNilInsert to true on the Document.

If a nil element is inserted and this method panics, it does not remove the previously added elements.

func (*Document) Concat 

func (d *Document) Concat(docs ...interface{}) error

Concat will take the keys from the provided document and concat them onto the end of this document.

doc must be one of the following:

  • *Document
  • []byte
  • io.Reader

func (*Document) Copy added in v0.0.9 

func (d *Document) Copy() *Document

Copy makes a shallow copy of this document.

func (*Document) Delete 

func (d *Document) Delete(key ...string) *Element

Delete removes the keys from the Document. The deleted element is returned. If the key does not exist, then nil is returned and the delete is a no-op. The same is true if something along the depth tree does not exist or is not a traversable type.

func (*Document) ElementAt 

func (d *Document) ElementAt(index uint) *Element

ElementAt retrieves the element at the given index in a Document. It panics if the index is out-of-bounds.

TODO(skriptble): This method could be variadic and return the element at the provided depth.

func (*Document) ElementAtOK added in v0.0.2 

func (d *Document) ElementAtOK(index uint) (*Element, bool)

ElementAtOK is the same as ElementAt, but returns a boolean instead of panicking.

func (*Document) Equal 

func (d *Document) Equal(d2 *Document) bool

Equal compares this document to another, returning true if they are equal.

func (*Document) Iterator 

func (d *Document) Iterator() *Iterator

Iterator creates an Iterator for this document and returns it.

func (*Document) Keys 

func (d *Document) Keys(recursive bool) (Keys, error)

Keys returns all of the element keys for this document. If recursive is true, this method will also return the keys of any subdocuments or arrays.

func (*Document) Len 

func (d *Document) Len() int

Len returns the number of elements in the document.

func (*Document) Lookup 

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

Lookup searches the document and potentially subdocuments or arrays for the provided key. Each key provided to this method represents a layer of depth.

Lookup will return nil if it encounters an error.

func (*Document) LookupElement added in v0.0.6 

func (d *Document) LookupElement(key ...string) *Element

LookupElement searches the document and potentially subdocuments or arrays for the provided key. Each key provided to this method represents a layer of depth.

LookupElement will return nil if it encounters an error.

func (*Document) LookupElementErr added in v0.0.6 

func (d *Document) LookupElementErr(key ...string) (*Element, error)

LookupElementErr searches the document and potentially subdocuments or arrays for the provided key. Each key provided to this method represents a layer of depth.

func (*Document) LookupErr added in v0.0.6 

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

LookupErr searches the document and potentially subdocuments or arrays for the provided key. Each key provided to this method represents a layer of depth.

func (*Document) MarshalBSON 

func (d *Document) MarshalBSON() ([]byte, error)

MarshalBSON implements the Marshaler interface.

func (*Document) Prepend 

func (d *Document) Prepend(elems ...*Element) *Document

Prepend adds each element to the beginning of the document, in order. If a nil element is passed as a parameter this method will panic. To change this behavior to silently ignore a nil element, set IgnoreNilInsert to true on the Document.

If a nil element is inserted and this method panics, it does not remove the previously added elements.

func (*Document) ReadFrom 

func (d *Document) ReadFrom(r io.Reader) (int64, error)

ReadFrom will read one BSON document from the given io.Reader.

func (*Document) Reset 

func (d *Document) Reset()

Reset clears a document so it can be reused. This method clears references to the underlying pointers to elements so they can be garbage collected.

func (*Document) Set 

func (d *Document) Set(elem *Element) *Document

Set replaces an element of a document. If an element with a matching key is found, the element will be replaced with the one provided. If the document does not have an element with that key, the element is appended to the document instead. If a nil element is passed as a parameter this method will panic. To change this behavior to silently ignore a nil element, set IgnoreNilInsert to true on the Document.

If a nil element is inserted and this method panics, it does not remove the previously added elements.

TODO(skriptble): Do we need to panic on a nil element? Semantically, if you ask to replace an element in the document with a nil element, you aren't asking for anything to be done.

func (*Document) String 

func (d *Document) String() string

String implements the fmt.Stringer interface.

func (*Document) ToExtJSON added in v0.0.6 

func (d *Document) ToExtJSON(canonical bool) string

ToExtJSON marshals this document to BSON and transforms that BSON to extended JSON. If there is an error during the conversion, this method will return an empty string. To receive the error, use the ToExtJSONErr method.

func (*Document) ToExtJSONErr added in v0.0.6 

func (d *Document) ToExtJSONErr(canonical bool) (string, error)

ToExtJSONErr marshals this document to BSON and transforms that BSON to extended JSON.

func (*Document) UnmarshalBSON 

func (d *Document) UnmarshalBSON(b []byte) error

UnmarshalBSON implements the Unmarshaler interface.

func (*Document) Validate 

func (d *Document) Validate() (uint32, error)

Validate validates the document and returns its total size.

func (*Document) WriteDocument 

func (d *Document) WriteDocument(start uint, writer interface{}) (int64, error)

WriteDocument will serialize this document to the provided writer beginning at the provided start position.

func (*Document) WriteTo 

func (d *Document) WriteTo(w io.Writer) (int64, error)

WriteTo implements the io.WriterTo interface.

TODO(skriptble): We can optimize this by having creating implementations of writeByteSlice that write directly to an io.Writer instead.

type Element 

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

Element represents a BSON element, i.e. key-value pair of a BSON document.

NOTE: Element cannot be the value of a map nor a property of a struct without special handling. The default encoders and decoders will not process Element correctly. To do so would require information loss since an Element contains a key, but the keys used when encoding a struct are the struct field names. Instead of using an Element, use a Value as the property of a struct field as that is the correct type in this circumstance.

func (*Element) Clone 

func (e *Element) Clone() *Element

Clone creates a shallow copy of the element/

func (*Element) Equal added in v0.0.15 

func (e *Element) Equal(e2 *Element) bool

Equal compares this element to element and returns true if they are equal.

func (*Element) Key 

func (e *Element) Key() string

Key returns the key for this element. It panics if e is uninitialized.

func (*Element) MarshalBSON 

func (e *Element) MarshalBSON() ([]byte, error)

MarshalBSON implements the Marshaler interface.

func (*Element) String 

func (e *Element) String() string

String implements the fmt.Stringer interface.

func (*Element) Validate 

func (e *Element) Validate() (uint32, error)

Validate validates the element and returns its total size.

func (*Element) Value 

func (e *Element) Value() *Value

Value returns the value associated with the BSON element.

func (*Element) WriteElement 

func (e *Element) WriteElement(start uint, writer interface{}) (int64, error)

WriteElement serializes this element to the provided writer starting at the provided start position.

func (*Element) WriteTo 

func (e *Element) WriteTo(w io.Writer) (int64, error)

WriteTo implements the io.WriterTo interface.

type ElementConstructor added in v0.0.2 

type ElementConstructor struct{}

ElementConstructor is used as a namespace for document element constructor functions. 

var EC ElementConstructor

EC is a convenience variable provided for access to the ElementConstructor methods.

func (ElementConstructor) Array added in v0.0.2 

func (ElementConstructor) Array(key string, a *Array) *Element

Array creates an array element with the given key and value.

func (ElementConstructor) ArrayFromElements added in v0.0.2 

func (c ElementConstructor) ArrayFromElements(key string, values ...*Value) *Element

ArrayFromElements creates an element with the given key. The elements passed as arguments will be used to create a new array as the value.

func (ElementConstructor) Binary added in v0.0.2 

func (c ElementConstructor) Binary(key string, b []byte) *Element

Binary creates a binary element with the given key and value.

func (ElementConstructor) BinaryWithSubtype added in v0.0.2 

func (ElementConstructor) BinaryWithSubtype(key string, b []byte, btype byte) *Element

BinaryWithSubtype creates a binary element with the given key. It will create a new BSON binary value with the given data and subtype.

func (ElementConstructor) Boolean added in v0.0.2 

func (ElementConstructor) Boolean(key string, b bool) *Element

Boolean creates a boolean element with the given key and value.

func (ElementConstructor) CodeWithScope added in v0.0.2 

func (ElementConstructor) CodeWithScope(key string, code string, scope *Document) *Element

CodeWithScope creates a JavaScript code with scope element with the given key and value.

func (ElementConstructor) DBPointer added in v0.0.2 

func (ElementConstructor) DBPointer(key string, ns string, oid objectid.ObjectID) *Element

DBPointer creates a dbpointer element with the given key and value.

func (ElementConstructor) DateTime added in v0.0.2 

func (ElementConstructor) DateTime(key string, dt int64) *Element

DateTime creates a datetime element with the given key and value. dt represents milliseconds since the Unix epoch

func (ElementConstructor) Decimal128 added in v0.0.2 

func (ElementConstructor) Decimal128(key string, d decimal.Decimal128) *Element

Decimal128 creates a decimal element with the given key and value.

func (ElementConstructor) Double added in v0.0.2 

func (ElementConstructor) Double(key string, f float64) *Element

Double creates a double element with the given key and value.

func (ElementConstructor) FromBytes added in v0.0.15 

func (ElementConstructor) FromBytes(src []byte) *Element

FromBytes constructs an element from the bytes provided. If the bytes are not a valid element, this method will panic.

func (ElementConstructor) FromBytesErr added in v0.0.15 

func (ElementConstructor) FromBytesErr(src []byte) (*Element, error)

FromBytesErr constructs an element from the bytes provided, but unlike FromBytes this method will return an error and not panic if the bytes are not a valid element.

func (ElementConstructor) FromValue added in v0.0.15 

func (ElementConstructor) FromValue(key string, value *Value) *Element

FromValue constructs an element using the underlying value.

func (ElementConstructor) Int32 added in v0.0.2 

func (ElementConstructor) Int32(key string, i int32) *Element

Int32 creates a int32 element with the given key and value.

func (ElementConstructor) Int64 added in v0.0.2 

func (ElementConstructor) Int64(key string, i int64) *Element

Int64 creates a int64 element with the given key and value.

func (ElementConstructor) Interface added in v0.0.2 

func (ElementConstructor) Interface(key string, value interface{}) *Element

Interface will attempt to turn the provided key and value into an Element. For common types, type casting is used, if the type is more complex, such as a map or struct, reflection is used. If the value cannot be converted either by typecasting or through reflection, a null Element is constructed with the key. This method will never return a nil *Element. If an error turning the value into an Element is desired, use the InterfaceErr method.

func (ElementConstructor) InterfaceErr added in v0.0.2 

func (c ElementConstructor) InterfaceErr(key string, value interface{}) (*Element, error)

InterfaceErr does what Interface does, but returns an error when it cannot properly convert a value into an *Element. See Interface for details.

func (ElementConstructor) JavaScript added in v0.0.2 

func (ElementConstructor) JavaScript(key string, code string) *Element

JavaScript creates a JavaScript code element with the given key and value.

func (ElementConstructor) MaxKey added in v0.0.2 

func (ElementConstructor) MaxKey(key string) *Element

MaxKey creates a maxkey element with the given key and value.

func (ElementConstructor) MinKey added in v0.0.2 

func (ElementConstructor) MinKey(key string) *Element

MinKey creates a minkey element with the given key and value.

func (ElementConstructor) Null added in v0.0.2 

func (ElementConstructor) Null(key string) *Element

Null creates a null element with the given key.

func (ElementConstructor) ObjectID added in v0.0.2 

func (ElementConstructor) ObjectID(key string, oid objectid.ObjectID) *Element

ObjectID creates a objectid element with the given key and value.

func (ElementConstructor) Regex added in v0.0.2 

func (ElementConstructor) Regex(key string, pattern, options string) *Element

Regex creates a regex element with the given key and value.

func (ElementConstructor) String added in v0.0.2 

func (ElementConstructor) String(key string, val string) *Element

String creates a string element with the given key and value.

func (ElementConstructor) SubDocument added in v0.0.2 

func (ElementConstructor) SubDocument(key string, d *Document) *Element

SubDocument creates a subdocument element with the given key and value.

func (ElementConstructor) SubDocumentFromElements added in v0.0.2 

func (c ElementConstructor) SubDocumentFromElements(key string, elems ...*Element) *Element

SubDocumentFromElements creates a subdocument element with the given key. The elements passed as arguments will be used to create a new document as the value.

func (ElementConstructor) SubDocumentFromReader added in v0.0.2 

func (ElementConstructor) SubDocumentFromReader(key string, r Reader) *Element

SubDocumentFromReader creates a subdocument element with the given key and value.

func (ElementConstructor) Symbol added in v0.0.2 

func (ElementConstructor) Symbol(key string, symbol string) *Element

Symbol creates a symbol element with the given key and value.

func (ElementConstructor) Time added in v0.0.4 

func (c ElementConstructor) Time(key string, t time.Time) *Element

Time creates a datetime element with the given key and value.

func (ElementConstructor) Timestamp added in v0.0.2 

func (ElementConstructor) Timestamp(key string, t uint32, i uint32) *Element

Timestamp creates a timestamp element with the given key and value.

func (ElementConstructor) Undefined added in v0.0.2 

func (ElementConstructor) Undefined(key string) *Element

Undefined creates a undefined element with the given key.

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 Encoder 

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

An Encoder writes a serialization format to an output stream.

func NewEncoder 

func NewEncoder(r *bsoncodec.Registry, vw bsonrw.ValueWriter) (*Encoder, error)

NewEncoder returns a new encoder that uses Registry r to write to w.

func (*Encoder) Encode 

func (e *Encoder) Encode(val interface{}) error

Encode writes the BSON encoding of val to the stream.

The documentation for Marshal contains details about the conversion of Go values to BSON.

func (*Encoder) Reset added in v0.0.17 

func (e *Encoder) Reset(vw bsonrw.ValueWriter) error

Reset will reset the state of the encoder, using the same *Registry used in the original construction but using vw.

func (*Encoder) SetRegistry added in v0.0.17 

func (e *Encoder) SetRegistry(r *bsoncodec.Registry) error

SetRegistry replaces the current registry of the encoder with r.

type ErrTooSmall 

type ErrTooSmall struct {
	Stack stack.CallStack
}

ErrTooSmall indicates that a slice provided to write into is not large enough to fit the data.

func NewErrTooSmall added in v0.0.2 

func NewErrTooSmall() ErrTooSmall

NewErrTooSmall creates a new ErrTooSmall with the given message and the current stack.

func (ErrTooSmall) Equals added in v0.0.2 

func (e ErrTooSmall) Equals(err2 error) bool

Equals checks that err2 also is an ErrTooSmall.

func (ErrTooSmall) Error added in v0.0.2 

func (e ErrTooSmall) Error() string

Error implements the error interface.

func (ErrTooSmall) ErrorStack added in v0.0.2 

func (e ErrTooSmall) ErrorStack() string

ErrorStack returns a string representing the stack at the point where the error occurred.

type Iterator 

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

Iterator facilitates iterating over a bson.Document.

func (*Iterator) Element 

func (itr *Iterator) Element() *Element

Element returns the current element of the Iterator. The pointer that it returns will _always_ be the same for a given Iterator.

func (*Iterator) Err 

func (itr *Iterator) Err() error

Err returns the error that occurred when iterating, or nil if none occurred.

func (*Iterator) Next 

func (itr *Iterator) Next() bool

Next fetches the next element of the document, returning whether or not the next element was able to be fetched. If true is returned, then call Element to get the element. If false is returned, call Err to check if an error occurred.

type JavaScriptCode 

type JavaScriptCode string

JavaScriptCode represents a BSON JavaScript code value.

type Key 

type Key struct {
	Prefix []string
	Name   string
}

Key represents an individual key of a BSON document. The Prefix property is used to represent the depth of this key.

func (Key) String 

func (k Key) String() string

String implements the fmt.Stringer interface.

type Keys 

type Keys []Key

Keys represents the keys of a BSON document.

type Marshaler 

type Marshaler interface {
	MarshalBSON() ([]byte, error)
}

Marshaler is an interface implemented by types that can marshal themselves into a BSON document represented as bytes. The bytes returned must be a valid BSON document if the error is nil.

type MaxKeyv2 added in v0.0.14 

type MaxKeyv2 struct{}

MaxKeyv2 represents the BSON maxkey value.

type MinKeyv2 added in v0.0.14 

type MinKeyv2 struct{}

MinKeyv2 represents the BSON minkey value.

type Nullv2 added in v0.0.14 

type Nullv2 struct{}

Nullv2 repreesnts the BSON null value.

type PrimitiveCodecs added in v0.0.17 

type PrimitiveCodecs struct{}

PrimitiveCodecs is a namespace for all of the default bsoncodec.Codecs for the primitive types defined in this package.

func (PrimitiveCodecs) ArrayDecodeValue added in v0.0.17 

func (pc PrimitiveCodecs) ArrayDecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

ArrayDecodeValue is the ValueDecoderFunc for *Array.

func (PrimitiveCodecs) ArrayEncodeValue added in v0.0.17 

func (pc PrimitiveCodecs) ArrayEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

ArrayEncodeValue is the ValueEncoderFunc for *Array.

func (PrimitiveCodecs) BinaryDecodeValue added in v0.0.17 

func (PrimitiveCodecs) BinaryDecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

BinaryDecodeValue is the ValueDecoderFunc for Binary.

func (PrimitiveCodecs) BinaryEncodeValue added in v0.0.17 

func (PrimitiveCodecs) BinaryEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

BinaryEncodeValue is the ValueEncoderFunc for Binary.

func (PrimitiveCodecs) CodeWithScopeDecodeValue added in v0.0.17 

func (pc PrimitiveCodecs) CodeWithScopeDecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

CodeWithScopeDecodeValue is the ValueDecoderFunc for CodeWithScope.

func (PrimitiveCodecs) CodeWithScopeEncodeValue added in v0.0.17 

func (pc PrimitiveCodecs) CodeWithScopeEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

CodeWithScopeEncodeValue is the ValueEncoderFunc for CodeWithScope.

func (PrimitiveCodecs) DBPointerDecodeValue added in v0.0.17 

func (PrimitiveCodecs) DBPointerDecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

DBPointerDecodeValue is the ValueDecoderFunc for DBPointer.

func (PrimitiveCodecs) DBPointerEncodeValue added in v0.0.17 

func (PrimitiveCodecs) DBPointerEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

DBPointerEncodeValue is the ValueEncoderFunc for DBPointer.

func (PrimitiveCodecs) DateTimeDecodeValue added in v0.0.17 

func (PrimitiveCodecs) DateTimeDecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

DateTimeDecodeValue is the ValueDecoderFunc for DateTime.

func (PrimitiveCodecs) DateTimeEncodeValue added in v0.0.17 

func (PrimitiveCodecs) DateTimeEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

DateTimeEncodeValue is the ValueEncoderFunc for DateTime.

func (PrimitiveCodecs) DocumentDecodeValue added in v0.0.17 

func (pc PrimitiveCodecs) DocumentDecodeValue(dctx bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

DocumentDecodeValue is the ValueDecoderFunc for *Document.

func (PrimitiveCodecs) DocumentEncodeValue added in v0.0.17 

func (pc PrimitiveCodecs) DocumentEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

DocumentEncodeValue is the ValueEncoderFunc for *Document.

func (PrimitiveCodecs) ElementSliceDecodeValue added in v0.0.17 

func (pc PrimitiveCodecs) ElementSliceDecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

ElementSliceDecodeValue is the ValueDecoderFunc for []*Element.

func (PrimitiveCodecs) ElementSliceEncodeValue added in v0.0.17 

func (pc PrimitiveCodecs) ElementSliceEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

ElementSliceEncodeValue is the ValueEncoderFunc for []*Element.

func (PrimitiveCodecs) EmptyInterfaceDecodeValue added in v0.0.17 

func (PrimitiveCodecs) EmptyInterfaceDecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

EmptyInterfaceDecodeValue is the ValueDecoderFunc for interface{}.

func (PrimitiveCodecs) JavaScriptDecodeValue added in v0.0.17 

func (PrimitiveCodecs) JavaScriptDecodeValue(dctx bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

JavaScriptDecodeValue is the ValueDecoderFunc for the JavaScriptPrimitive type.

func (PrimitiveCodecs) JavaScriptEncodeValue added in v0.0.17 

func (PrimitiveCodecs) JavaScriptEncodeValue(ectx bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

JavaScriptEncodeValue is the ValueEncoderFunc for the JavaScriptPrimitive type.

func (PrimitiveCodecs) MaxKeyDecodeValue added in v0.0.17 

func (PrimitiveCodecs) MaxKeyDecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

MaxKeyDecodeValue is the ValueDecoderFunc for MaxKey.

func (PrimitiveCodecs) MaxKeyEncodeValue added in v0.0.17 

func (PrimitiveCodecs) MaxKeyEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

MaxKeyEncodeValue is the ValueEncoderFunc for MaxKey.

func (PrimitiveCodecs) MinKeyDecodeValue added in v0.0.17 

func (PrimitiveCodecs) MinKeyDecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

MinKeyDecodeValue is the ValueDecoderFunc for MinKey.

func (PrimitiveCodecs) MinKeyEncodeValue added in v0.0.17 

func (PrimitiveCodecs) MinKeyEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

MinKeyEncodeValue is the ValueEncoderFunc for MinKey.

func (PrimitiveCodecs) NullDecodeValue added in v0.0.17 

func (PrimitiveCodecs) NullDecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

NullDecodeValue is the ValueDecoderFunc for Null.

func (PrimitiveCodecs) NullEncodeValue added in v0.0.17 

func (PrimitiveCodecs) NullEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

NullEncodeValue is the ValueEncoderFunc for Null.

func (PrimitiveCodecs) ReaderDecodeValue added in v0.0.17 

func (PrimitiveCodecs) ReaderDecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

ReaderDecodeValue is the ValueDecoderFunc for Reader.

func (PrimitiveCodecs) ReaderEncodeValue added in v0.0.17 

func (PrimitiveCodecs) ReaderEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

ReaderEncodeValue is the ValueEncoderFunc for Reader.

func (PrimitiveCodecs) RegexDecodeValue added in v0.0.17 

func (PrimitiveCodecs) RegexDecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

RegexDecodeValue is the ValueDecoderFunc for Regex.

func (PrimitiveCodecs) RegexEncodeValue added in v0.0.17 

func (PrimitiveCodecs) RegexEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

RegexEncodeValue is the ValueEncoderFunc for Regex.

func (PrimitiveCodecs) RegisterPrimitiveCodecs added in v0.0.17 

func (pc PrimitiveCodecs) RegisterPrimitiveCodecs(rb *bsoncodec.RegistryBuilder)

RegisterPrimitiveCodecs will register the encode and decode methods attached to PrimitiveCodecs with the provided RegistryBuilder. if rb is nil, a new empty RegistryBuilder will be created.

func (PrimitiveCodecs) SymbolDecodeValue added in v0.0.17 

func (PrimitiveCodecs) SymbolDecodeValue(dctx bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

SymbolDecodeValue is the ValueDecoderFunc for the SymbolPrimitive type.

func (PrimitiveCodecs) SymbolEncodeValue added in v0.0.17 

func (PrimitiveCodecs) SymbolEncodeValue(ectx bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

SymbolEncodeValue is the ValueEncoderFunc for the SymbolPrimitive type.

func (PrimitiveCodecs) TimestampDecodeValue added in v0.0.17 

func (PrimitiveCodecs) TimestampDecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

TimestampDecodeValue is the ValueDecoderFunc for Timestamp.

func (PrimitiveCodecs) TimestampEncodeValue added in v0.0.17 

func (PrimitiveCodecs) TimestampEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

TimestampEncodeValue is the ValueEncoderFunc for Timestamp.

func (PrimitiveCodecs) UndefinedDecodeValue added in v0.0.17 

func (PrimitiveCodecs) UndefinedDecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

UndefinedDecodeValue is the ValueDecoderFunc for Undefined.

func (PrimitiveCodecs) UndefinedEncodeValue added in v0.0.17 

func (PrimitiveCodecs) UndefinedEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

UndefinedEncodeValue is the ValueEncoderFunc for Undefined.

func (PrimitiveCodecs) ValueDecodeValue added in v0.0.17 

func (pc PrimitiveCodecs) ValueDecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, i interface{}) error

ValueDecodeValue is the ValueDecoderFunc for *Value.

func (PrimitiveCodecs) ValueEncodeValue added in v0.0.17 

func (pc PrimitiveCodecs) ValueEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, i interface{}) error

ValueEncodeValue is the ValueEncoderFunc for *Value.

type Reader 

type Reader []byte

Reader is a wrapper around a byte slice. It will interpret the slice as a BSON document. Most of the methods on Reader are low cost and are meant for simple operations that are run a few times. Because there is no metadata stored all methods run in O(n) time. If a more efficient lookup method is necessary then the Document type should be used.

func NewFromIOReader 

func NewFromIOReader(r io.Reader) (Reader, error)

NewFromIOReader reads in a document from the given io.Reader and constructs a bson.Reader from it.

func (Reader) ElementAt 

func (r Reader) ElementAt(index uint) (*Element, error)

ElementAt searches for a retrieves the element at the given index. This method will validate all the elements up to and including the element at the given index.

func (Reader) Iterator 

func (r Reader) Iterator() (*ReaderIterator, error)

Iterator returns a ReaderIterator that can be used to iterate through the elements of this Reader.

func (Reader) Keys 

func (r Reader) Keys(recursive bool) (Keys, error)

Keys returns the keys for this document. If recursive is true then this method will also return the keys for subdocuments and arrays.

The keys will be return in order.

func (Reader) Lookup 

func (r Reader) Lookup(key ...string) (*Element, error)

Lookup search 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 any key except for the last is not a document or an array, an error will be returned.

TODO(skriptble): Implement better error messages.

TODO(skriptble): Determine if this should return an error on empty key and key not found.

func (Reader) MarshalBSON added in v0.0.15 

func (r Reader) MarshalBSON() ([]byte, error)

MarshalBSON implements the bsoncodec.Marshaler interface.

This method does not copy the bytes from r.

func (Reader) String 

func (r Reader) String() string

String implements the fmt.Stringer interface.

func (Reader) Validate 

func (r Reader) Validate() (size uint32, err error)

Validate validates the document. This method only validates the first document in the slice, to validate other documents, the slice must be resliced.

Example 
rdr := make(Reader, 500)
rdr[250], rdr[251], rdr[252], rdr[253], rdr[254] = '\x05', '\x00', '\x00', '\x00', '\x00'
n, err := rdr[250:].Validate()
fmt.Println(n, err)

Output:

5 <nil>

type ReaderIterator 

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

ReaderIterator facilitates iterating over a bson.Reader.

func NewReaderIterator 

func NewReaderIterator(r Reader) (*ReaderIterator, error)

NewReaderIterator constructors a new ReaderIterator over a given Reader.

func (*ReaderIterator) Element 

func (itr *ReaderIterator) Element() *Element

Element returns the current element of the ReaderIterator. The pointer that it returns will _always_ be the same for a given ReaderIterator.

func (*ReaderIterator) Err 

func (itr *ReaderIterator) Err() error

Err returns the error that occurred when iterating, or nil if none occurred.

func (*ReaderIterator) Next 

func (itr *ReaderIterator) Next() bool

Next fetches the next element of the Reader, returning whether or not the next element was able to be fetched. If true is returned, then call Element to get the element. If false is returned, call Err to check if an error occurred.

type Regex 

type Regex struct {
	Pattern string
	Options string
}

Regex represents a BSON regex value.

func (Regex) String 

func (r Regex) String() string

type Symbol 

type Symbol string

Symbol represents a BSON symbol value.

type Timestamp 

type Timestamp struct {
	T uint32
	I uint32
}

Timestamp represents a BSON timestamp value.

type Undefinedv2 added in v0.0.14 

type Undefinedv2 struct{}

Undefinedv2 represents the BSON undefined value type.

type Unmarshaler 

type Unmarshaler interface {
	UnmarshalBSON([]byte) error
}

Unmarshaler is an interface implemented by types that can unmarshal a BSON document representation of themselves. The BSON bytes can be assumed to be valid. UnmarshalBSON must copy the BSON bytes if it wishes to retain the data after returning.

type Value 

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

Value represents a BSON value. It can be obtained as part of a bson.Element or created for use in a bson.Array with the bson.VC constructors.

func (*Value) Add 

func (v *Value) Add(v2 *Value) error

Add will add this Value to another. This is currently only implemented for strings and numbers. If either value is a string, the other type is coerced into a string and added to the other.

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 added in v0.0.14 

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

func (v *Value) DBPointer() (string, objectid.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, objectid.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) Decimal128 

func (v *Value) Decimal128() decimal.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() (decimal.Decimal128, bool)

Decimal128OK is the same as Decimal128, except that 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 double ('\x01') or if e is uninitialized.

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 added in v0.0.15 

func (v *Value) Equal(v2 *Value) bool

Equal compares v to v2 and returns true if they are equal. This method will ensure that the values are logically equal, even if their internal structure is different. This method should be used over reflect.DeepEqual which will not return true for Values that are logically the same but not internally the same.

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

func (v *Value) Interface() interface{}

Interface returns the Go value of this Value as an empty interface.

func (*Value) IsNumber 

func (v *Value) IsNumber() bool

IsNumber returns true if the type of v is a numberic 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) MutableArray 

func (v *Value) MutableArray() *Array

MutableArray returns the array for this element.

func (*Value) MutableArrayOK 

func (v *Value) MutableArrayOK() (*Array, bool)

MutableArrayOK is the same as MutableArray, except it returns a boolean instead of panicking.

func (*Value) MutableDocument 

func (v *Value) MutableDocument() *Document

MutableDocument returns the subdocument for this element.

func (*Value) MutableDocumentOK 

func (v *Value) MutableDocumentOK() (*Document, bool)

MutableDocumentOK is the same as MutableDocument, except it returns a boolean instead of panicking.

func (*Value) MutableJavaScriptWithScope 

func (v *Value) MutableJavaScriptWithScope() (code string, d *Document)

MutableJavaScriptWithScope returns the javascript code and the scope document for this element.

func (*Value) MutableJavaScriptWithScopeOK 

func (v *Value) MutableJavaScriptWithScopeOK() (string, *Document, bool)

MutableJavaScriptWithScopeOK is the same as MutableJavascriptWithScope, except that it returns a boolean instead of panicking.

func (*Value) ObjectID 

func (v *Value) ObjectID() objectid.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() (objectid.ObjectID, bool)

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

func (*Value) Offset added in v0.0.2 

func (v *Value) Offset() uint32

Offset returns the offset to the beginning of the value in the underlying data. When called on a value obtained from a Reader, it can be used to find the value manually within the Reader's bytes.

func (*Value) ReaderArray 

func (v *Value) ReaderArray() Reader

ReaderArray returns the BSON document the Value represents as a bson.Reader. It panics if the value is a BSON type other than array.

func (*Value) ReaderArrayOK 

func (v *Value) ReaderArrayOK() (Reader, bool)

ReaderArrayOK is the same as ReaderArray, except it returns a boolean instead of panicking.

func (*Value) ReaderDocument 

func (v *Value) ReaderDocument() Reader

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

func (*Value) ReaderDocumentOK 

func (v *Value) ReaderDocumentOK() (Reader, bool)

ReaderDocumentOK is the same as ReaderDocument, except it returns a boolean instead of panicking.

func (*Value) ReaderJavaScriptWithScope 

func (v *Value) ReaderJavaScriptWithScope() (string, Reader)

ReaderJavaScriptWithScope returns the BSON JavaScript code with scope the Value represents, with the scope being returned as a bson.Reader. It panics if the value is a BSON type other than JavaScript code with scope.

func (*Value) ReaderJavaScriptWithScopeOK 

func (v *Value) ReaderJavaScriptWithScopeOK() (string, Reader, bool)

ReaderJavaScriptWithScopeOK is the same as ReaderJavaScriptWithScope, except that 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) StringValue 

func (v *Value) StringValue() string

StringValue returns the string balue for this element. It panics if e's BSON type is not StringValue ('\x02') or if e is uninitialized.

NOTE: This method is called StringValue to avoid it implementing 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) Time added in v0.0.13 

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 added in v0.0.13 

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() (uint32, 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() (uint32, uint32, bool)

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

func (*Value) Type 

func (v *Value) Type() bsontype.Type

Type returns the identifying element byte for this element. It panics if e is uninitialized.

func (*Value) Validate added in v0.0.15 

func (v *Value) Validate() error

Validate validates the value.

type ValueConstructor added in v0.0.2 

type ValueConstructor struct{}

ValueConstructor is used as a namespace for document element constructor functions. 

var VC ValueConstructor

VC is a convenience variable provided for access to the ValueConstructor methods.

func (ValueConstructor) Array added in v0.0.2 

func (ValueConstructor) Array(a *Array) *Value

Array creates an array value from the argument.

func (ValueConstructor) ArrayFromValues added in v0.0.2 

func (ValueConstructor) ArrayFromValues(values ...*Value) *Value

ArrayFromValues creates an array element from the given the elements.

func (ValueConstructor) Binary added in v0.0.2 

func (ac ValueConstructor) Binary(b []byte) *Value

Binary creates a binary value from the argument.

func (ValueConstructor) BinaryWithSubtype added in v0.0.2 

func (ValueConstructor) BinaryWithSubtype(b []byte, btype byte) *Value

BinaryWithSubtype creates a new binary element with the given data and subtype.

func (ValueConstructor) Boolean added in v0.0.2 

func (ValueConstructor) Boolean(b bool) *Value

Boolean creates a boolean value from the argument.

func (ValueConstructor) CodeWithScope added in v0.0.2 

func (ValueConstructor) CodeWithScope(code string, scope *Document) *Value

CodeWithScope creates a JavaScript code with scope value from the arguments.

func (ValueConstructor) DBPointer added in v0.0.2 

func (ValueConstructor) DBPointer(ns string, oid objectid.ObjectID) *Value

DBPointer creates a dbpointer value from the arguments.

func (ValueConstructor) DateTime added in v0.0.2 

func (ValueConstructor) DateTime(dt int64) *Value

DateTime creates a datetime value from the argument.

func (ValueConstructor) Decimal128 added in v0.0.2 

func (ValueConstructor) Decimal128(d decimal.Decimal128) *Value

Decimal128 creates a decimal value from the argument.

func (ValueConstructor) Document added in v0.0.2 

func (ValueConstructor) Document(d *Document) *Value

Document creates a subdocument value from the argument.

func (ValueConstructor) DocumentFromElements added in v0.0.2 

func (ValueConstructor) DocumentFromElements(elems ...*Element) *Value

DocumentFromElements creates a subdocument element from the given elements.

func (ValueConstructor) DocumentFromReader added in v0.0.2 

func (ValueConstructor) DocumentFromReader(r Reader) *Value

DocumentFromReader creates a subdocument element from the given value.

func (ValueConstructor) Double added in v0.0.2 

func (ValueConstructor) Double(f float64) *Value

Double creates a double element with the given value.

func (ValueConstructor) Int32 added in v0.0.2 

func (ValueConstructor) Int32(i int32) *Value

Int32 creates a int32 value from the argument.

func (ValueConstructor) Int64 added in v0.0.2 

func (ValueConstructor) Int64(i int64) *Value

Int64 creates a int64 value from the argument.

func (ValueConstructor) JavaScript added in v0.0.2 

func (ValueConstructor) JavaScript(code string) *Value

JavaScript creates a JavaScript code value from the argument.

func (ValueConstructor) MaxKey added in v0.0.2 

func (ValueConstructor) MaxKey() *Value

MaxKey creates a maxkey value from the argument.

func (ValueConstructor) MinKey added in v0.0.2 

func (ValueConstructor) MinKey() *Value

MinKey creates a minkey value from the argument.

func (ValueConstructor) Null added in v0.0.2 

func (ValueConstructor) Null() *Value

Null creates a null value from the argument.

func (ValueConstructor) ObjectID added in v0.0.2 

func (ValueConstructor) ObjectID(oid objectid.ObjectID) *Value

ObjectID creates a objectid value from the argument.

func (ValueConstructor) Regex added in v0.0.2 

func (ValueConstructor) Regex(pattern, options string) *Value

Regex creates a regex value from the arguments.

func (ValueConstructor) String added in v0.0.2 

func (ValueConstructor) String(val string) *Value

String creates a string element with the given value.

func (ValueConstructor) Symbol added in v0.0.2 

func (ValueConstructor) Symbol(symbol string) *Value

Symbol creates a symbol value from the argument.

func (ValueConstructor) Time added in v0.0.17 

func (ValueConstructor) Time(t time.Time) *Value

Time creates a datetime value from the argument.

func (ValueConstructor) Timestamp added in v0.0.2 

func (ValueConstructor) Timestamp(t uint32, i uint32) *Value

Timestamp creates a timestamp value from the arguments.

func (ValueConstructor) Undefined added in v0.0.2 

func (ValueConstructor) Undefined() *Value

Undefined creates a undefined element.

type ValueMarshaler 

type ValueMarshaler interface {
	MarshalBSONValue() (bsontype.Type, []byte, error)
}

ValueMarshaler is an interface implemented by types that can marshal themselves into a BSON value as bytes. The type must be the valid type for the bytes returned. The bytes and byte type together must be valid if the error is nil.

type ValueUnmarshaler added in v0.0.17 

type ValueUnmarshaler interface {
	UnmarshalBSONValue(bsontype.Type, []byte) error
}

ValueUnmarshaler is an interface implemented by types that can unmarshal a BSON value representaiton of themselves. The BSON bytes and type can be assumed to be valid. UnmarshalBSONValue must copy the BSON value bytes if it wishes to retain the data after returning.

type Zeroer added in v0.0.4 

type Zeroer interface {
	IsZero() bool
}

Zeroer allows custom struct types to implement a report of zero state. All struct types that don't implement Zeroer or where IsZero returns false are considered to be not zero.

Source Files

View all Source files

Directories

Path Synopsis
Package bsoncore contains functions that can be used to encode and decode BSON elements and values to or from a slice of bytes.
 Package bsoncore contains functions that can be used to encode and decode BSON elements and values to or from a slice of bytes.
Package bsonrw contains abstractions for reading and writing BSON and BSON like types from sources.
 Package bsonrw contains abstractions for reading and writing BSON and BSON like types from sources.
bsonrwtest
Package bsontype is a utility package that contains types for each BSON type and the a stringifier for the Type to enable easier debugging when working with BSON.
 Package bsontype is a utility package that contains types for each BSON type and the a stringifier for the Type to enable easier debugging when working with BSON.
Package elements holds the logic to encode and decode the BSON element types from native Go to BSON binary and vice versa.
 Package elements holds the logic to encode and decode the BSON element types from native Go to BSON binary and vice versa.
ast

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.