Documentation

Overview

Package bson is a library for reading, writing, and manipulating BSON. BSON is a binary serialization format used to store documents and make remote procedure calls in MongoDB. The BSON specification is located at https://bsonspec.org. The BSON library handles marshalling and unmarshalling of values through a configurable codec system. For a description of the codec system and examples of registering custom codecs, see the bsoncodec package.

Raw BSON

The Raw family of types is used to validate and retrieve elements from a slice of bytes. This type is most useful when you want do lookups on BSON bytes without unmarshaling it into another type.

Example:

var raw bson.Raw = ... // bytes from somewhere
err := raw.Validate()
if err != nil { return err }
val := raw.Lookup("foo")
i32, ok := val.Int32OK()
// do something with i32...

Native Go Types

The D and M types defined in this package can be used to build representations of BSON using native Go types. D is a slice and M is a map. For more information about the use cases for these types, see the documentation on the type definitions.

Example:

bson.D{{"foo", "bar"}, {"hello", "world"}, {"pi", 3.14159}}
bson.M{"foo": "bar", "hello": "world", "pi": 3.14159}

When decoding BSON to a D or M, the following type mappings apply when unmarshalling:

1. BSON int32 unmarshals to an int32.
2. BSON int64 unmarshals to an int64.
3. BSON double unmarshals to a float64.
4. BSON string unmarshals to a string.
5. BSON boolean unmarshals to a bool.
6. BSON embedded document unmarshals to the parent type (i.e. D for a D, M for an M).
7. BSON array unmarshals to a bson.A.
8. BSON ObjectId unmarshals to a primitive.ObjectID.
9. BSON datetime unmarshals to a primitive.DateTime.
10. BSON binary unmarshals to a primitive.Binary.
11. BSON regular expression unmarshals to a primitive.Regex.
12. BSON JavaScript unmarshals to a primitive.JavaScript.
13. BSON code with scope unmarshals to a primitive.CodeWithScope.
14. BSON timestamp unmarshals to an primitive.Timestamp.
15. BSON 128-bit decimal unmarshals to an primitive.Decimal128.
16. BSON min key unmarshals to an primitive.MinKey.
17. BSON max key unmarshals to an primitive.MaxKey.
18. BSON undefined unmarshals to a primitive.Undefined.
19. BSON null unmarshals to nil.
20. BSON DBPointer unmarshals to a primitive.DBPointer.
21. BSON symbol unmarshals to a primitive.Symbol.

The above mappings also apply when marshalling a D or M to BSON. Some other useful marshalling mappings are:

1. time.Time marshals to a BSON datetime.
2. int8, int16, and int32 marshal to a BSON int32.
3. int marshals to a BSON int32 if the value is between math.MinInt32 and math.MaxInt32, inclusive, and a BSON int64
otherwise.
4. int64 marshals to BSON int64.
5. uint8 and uint16 marshal to a BSON int32.
6. uint, uint32, and uint64 marshal to a BSON int32 if the value is between math.MinInt32 and math.MaxInt32,
inclusive, and BSON int64 otherwise.
7. BSON null and undefined values will unmarshal into the zero value of a field (e.g. unmarshalling a BSON null or
undefined value into a string will yield the empty string.).

Structs

Structs can be marshalled/unmarshalled to/from BSON or Extended JSON. When transforming structs to/from BSON or Extended JSON, the following rules apply:

1. Only exported fields in structs will be marshalled or unmarshalled.

2. When marshalling a struct, each field will be lowercased to generate the key for the corresponding BSON element.
For example, a struct field named "Foo" will generate key "foo". This can be overriden via a struct tag (e.g.
`bson:"fooField"` to generate key "fooField" instead).

3. An embedded struct field is marshalled as a subdocument. The key will be the lowercased name of the field's type.

4. A pointer field is marshalled as the underlying type if the pointer is non-nil. If the pointer is nil, it is
marshalled as a BSON null value.

5. When unmarshalling, a field of type interface{} will follow the D/M type mappings listed above. BSON documents
unmarshalled into an interface{} field will be unmarshalled as a D.

The encoding of each struct field can be customized by the "bson" struct tag.

This tag behavior is configurable, and different struct tag behavior can be configured by initializing a new bsoncodec.StructCodec with the desired tag parser and registering that StructCodec onto the Registry. By default, JSON tags are not honored, but that can be enabled by creating a StructCodec with JSONFallbackStructTagParser, like below:

Example:

structcodec, _ := bsoncodec.NewStructCodec(bsoncodec.JSONFallbackStructTagParser)

The bson tag gives the name of the field, possibly followed by a comma-separated list of options. The name may be empty in order to specify options without overriding the default field name. The following options can be used to configure behavior:

1. omitempty: If the omitempty struct tag is specified on a field, the field will not be marshalled if it is set to
the zero value. Fields with language primitive types such as integers, booleans, and strings are considered empty if
their value is equal to the zero value for the type (i.e. 0 for integers, false for booleans, and "" for strings).
Slices, maps, and arrays are considered empty if they are of length zero. Interfaces and pointers are considered
empty if their value is nil. By default, structs are only considered empty if the struct type implements the
bsoncodec.Zeroer interface and the IsZero method returns true. Struct fields whose types do not implement Zeroer are
never considered empty and will be marshalled as embedded documents.
NOTE: It is recommended that this tag be used for all slice and map fields.

2. minsize: If the minsize struct tag is specified on a field of type int64, uint, uint32, or uint64 and the value of
the field can fit in a signed int32, the field will be serialized as a BSON int32 rather than a BSON int64. For other
types, this tag is ignored.

3. truncate: If the truncate struct tag is specified on a field with a non-float numeric type, BSON doubles unmarshalled
into that field will be trucated at the decimal point. For example, if 3.14 is unmarshalled into a field of type int,
it will be unmarshalled as 3. If this tag is not specified, the decoder will throw an error if the value cannot be
decoded without losing precision. For float64 or non-numeric types, this tag is ignored.

4. inline: If the inline struct tag is specified for a struct or map field, the field will be "flattened" when
marshalling and "un-flattened" when unmarshalling. This means that all of the fields in that struct/map will be
pulled up one level and will become top-level fields rather than being fields in a nested document. For example, if a
map field named "Map" with value map[string]interface{}{"foo": "bar"} is inlined, the resulting document will be
{"foo": "bar"} instead of {"map": {"foo": "bar"}}. There can only be one inlined map field in a struct. If there are
duplicated fields in the resulting document when an inlined struct is marshalled, the inlined field will be overwritten.
If there are duplicated fields in the resulting document when an inlined map is marshalled, an error will be returned.
This tag can be used with fields that are pointers to structs. If an inlined pointer field is nil, it will not be
marshalled. For fields that are not maps or structs, this tag is ignored.

Marshalling and Unmarshalling

Manually marshalling and unmarshalling can be done with the Marshal and Unmarshal family of functions.

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 ErrDecodeToNil = errors.New("cannot Decode to nil value")

        ErrDecodeToNil is the error returned when trying to decode to a nil value

        View Source
        var ErrNilContext = errors.New("DecodeContext cannot be nil")

          ErrNilContext is returned when the provided DecodeContext is nil.

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

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

            View Source
            var ErrNilRegistry = errors.New("Registry cannot be nil")

              ErrNilRegistry is returned when the provided registry is nil.

              Functions

              func Marshal

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

                Marshal returns the BSON encoding of val as a BSON document. If val is not a type that can be transformed into a document, MarshalValue should be used instead.

                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

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

                  MarshalAppend will encode val as a BSON document and append the bytes to dst. If dst is not large enough to hold the bytes, it will be grown. If val is not a type that can be transformed into a document, MarshalValueAppend should be used instead.

                  func MarshalAppendWithContext

                  func MarshalAppendWithContext(ec bsoncodec.EncodeContext, dst []byte, val interface{}) ([]byte, error)

                    MarshalAppendWithContext will encode val as a BSON document using Registry r and EncodeContext ec and append the bytes to dst. If dst is not large enough to hold the bytes, it will be grown. If val is not a type that can be transformed into a document, MarshalValueAppendWithContext should be used instead.

                    func MarshalAppendWithRegistry

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

                      MarshalAppendWithRegistry will encode val as a BSON document using Registry r and append the bytes to dst. If dst is not large enough to hold the bytes, it will be grown. If val is not a type that can be transformed into a document, MarshalValueAppendWithRegistry should be used instead.

                      func MarshalExtJSON

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

                        MarshalExtJSON returns the extended JSON encoding of val.

                        func MarshalExtJSONAppend

                        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 MarshalExtJSONAppendWithContext

                          func MarshalExtJSONAppendWithContext(ec bsoncodec.EncodeContext, dst []byte, val interface{}, canonical, escapeHTML bool) ([]byte, error)

                            MarshalExtJSONAppendWithContext 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 MarshalExtJSONAppendWithRegistry

                            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 MarshalExtJSONWithContext

                              func MarshalExtJSONWithContext(ec bsoncodec.EncodeContext, val interface{}, canonical, escapeHTML bool) ([]byte, error)

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

                                func MarshalExtJSONWithRegistry

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

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

                                  func MarshalValue

                                  func MarshalValue(val interface{}) (bsontype.Type, []byte, error)

                                    MarshalValue returns the BSON encoding of val.

                                    MarshalValue will use bson.DefaultRegistry to transform val into a BSON value. If val is a struct, this function will inspect struct tags and alter the marshalling process accordingly.

                                    func MarshalValueAppend

                                    func MarshalValueAppend(dst []byte, val interface{}) (bsontype.Type, []byte, error)

                                      MarshalValueAppend 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 MarshalValueAppendWithContext

                                      func MarshalValueAppendWithContext(ec bsoncodec.EncodeContext, dst []byte, val interface{}) (bsontype.Type, []byte, error)

                                        MarshalValueAppendWithContext will append the BSON encoding of val to dst using EncodeContext ec. If dst is not large enough to hold the BSON encoding of val, dst will be grown.

                                        func MarshalValueAppendWithRegistry

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

                                          MarshalValueAppendWithRegistry 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 MarshalValueWithContext

                                          func MarshalValueWithContext(ec bsoncodec.EncodeContext, val interface{}) (bsontype.Type, []byte, error)

                                            MarshalValueWithContext returns the BSON encoding of val using EncodeContext ec.

                                            func MarshalValueWithRegistry

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

                                              MarshalValueWithRegistry returns the BSON encoding of val using Registry r.

                                              func MarshalWithContext

                                              func MarshalWithContext(ec bsoncodec.EncodeContext, val interface{}) ([]byte, error)

                                                MarshalWithContext returns the BSON encoding of val as a BSON document using EncodeContext ec. If val is not a type that can be transformed into a document, MarshalValueWithContext should be used instead.

                                                func MarshalWithRegistry

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

                                                  MarshalWithRegistry returns the BSON encoding of val as a BSON document. If val is not a type that can be transformed into a document, MarshalValueWithRegistry should be used instead.

                                                  func NewRegistryBuilder

                                                  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 Unmarshal

                                                    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

                                                      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 UnmarshalExtJSONWithContext

                                                        func UnmarshalExtJSONWithContext(dc bsoncodec.DecodeContext, data []byte, canonical bool, val interface{}) error

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

                                                          func UnmarshalExtJSONWithRegistry

                                                          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 UnmarshalWithContext

                                                            func UnmarshalWithContext(dc bsoncodec.DecodeContext, data []byte, val interface{}) error

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

                                                              func UnmarshalWithRegistry

                                                              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 A

                                                                type A = primitive.A

                                                                  An A is an ordered representation of a BSON array.

                                                                  Example usage:

                                                                  bson.A{"bar", "world", 3.14159, bson.D{{"qux", 12345}}}
                                                                  

                                                                  type D

                                                                  type D = primitive.D

                                                                    D is an ordered representation of a BSON document. This type should be used when the order of the elements matters, such as MongoDB command documents. If the order of the elements does not matter, an M should be used instead.

                                                                    Example usage:

                                                                    bson.D{{"foo", "bar"}, {"hello", "world"}, {"pi", 3.14159}}
                                                                    

                                                                    type Decoder

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

                                                                      A Decoder reads and decodes BSON documents from a stream. It reads from a bsonrw.ValueReader as the source of BSON data.

                                                                      func NewDecoder

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

                                                                        NewDecoder returns a new decoder that uses the DefaultRegistry to read from vr.

                                                                        func NewDecoderWithContext

                                                                        func NewDecoderWithContext(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader) (*Decoder, error)

                                                                          NewDecoderWithContext returns a new decoder that uses DecodeContext dc to read from vr.

                                                                          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

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

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

                                                                              func (*Decoder) SetContext

                                                                              func (d *Decoder) SetContext(dc bsoncodec.DecodeContext) error

                                                                                SetContext replaces the current registry of the decoder with dc.

                                                                                func (*Decoder) SetRegistry

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

                                                                                  SetRegistry replaces the current registry of the decoder with r.

                                                                                  type E

                                                                                  type E = primitive.E

                                                                                    E represents a BSON element for a D. It is usually used inside a D.

                                                                                    type Encoder

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

                                                                                      An Encoder writes a serialization format to an output stream. It writes to a bsonrw.ValueWriter as the destination of BSON data.

                                                                                      func NewEncoder

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

                                                                                        NewEncoder returns a new encoder that uses the DefaultRegistry to write to vw.

                                                                                        func NewEncoderWithContext

                                                                                        func NewEncoderWithContext(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter) (*Encoder, error)

                                                                                          NewEncoderWithContext returns a new encoder that uses EncodeContext ec to write to vw.

                                                                                          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

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

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

                                                                                              func (*Encoder) SetContext

                                                                                              func (e *Encoder) SetContext(ec bsoncodec.EncodeContext) error

                                                                                                SetContext replaces the current EncodeContext of the encoder with er.

                                                                                                func (*Encoder) SetRegistry

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

                                                                                                  SetRegistry replaces the current registry of the encoder with r.

                                                                                                  type M

                                                                                                  type M = primitive.M

                                                                                                    M is an unordered representation of a BSON document. This type should be used when the order of the elements does not matter. This type is handled as a regular map[string]interface{} when encoding and decoding. Elements will be serialized in an undefined, random order. If the order of the elements matters, a D should be used instead.

                                                                                                    Example usage:

                                                                                                    bson.M{"foo": "bar", "hello": "world", "pi": 3.14159}
                                                                                                    

                                                                                                    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 PrimitiveCodecs

                                                                                                      type PrimitiveCodecs struct{}

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

                                                                                                        func (PrimitiveCodecs) RawDecodeValue

                                                                                                          RawDecodeValue is the ValueDecoderFunc for Reader.

                                                                                                          func (PrimitiveCodecs) RawEncodeValue

                                                                                                            RawEncodeValue is the ValueEncoderFunc for Reader.

                                                                                                            func (PrimitiveCodecs) RawValueDecodeValue

                                                                                                            func (PrimitiveCodecs) RawValueDecodeValue(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, val reflect.Value) error

                                                                                                              RawValueDecodeValue is the ValueDecoderFunc for RawValue.

                                                                                                              func (PrimitiveCodecs) RawValueEncodeValue

                                                                                                              func (PrimitiveCodecs) RawValueEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, val reflect.Value) error

                                                                                                                RawValueEncodeValue is the ValueEncoderFunc for RawValue.

                                                                                                                func (PrimitiveCodecs) RegisterPrimitiveCodecs

                                                                                                                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.

                                                                                                                  type Raw

                                                                                                                  type Raw []byte

                                                                                                                    Raw is a wrapper around a byte slice. It will interpret the slice as a BSON document. This type is a wrapper around a bsoncore.Document. Errors returned from the methods on this type and associated types come from the bsoncore package.

                                                                                                                    func NewFromIOReader

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

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

                                                                                                                      func (Raw) Elements

                                                                                                                      func (r Raw) Elements() ([]RawElement, 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 (Raw) Index

                                                                                                                        func (r Raw) Index(index uint) RawElement

                                                                                                                          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 (Raw) IndexErr

                                                                                                                          func (r Raw) IndexErr(index uint) (RawElement, error)

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

                                                                                                                            func (Raw) Lookup

                                                                                                                            func (r Raw) Lookup(key ...string) RawValue

                                                                                                                              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 an error occurs or if the value doesn't exist, an empty RawValue is returned.

                                                                                                                              func (Raw) LookupErr

                                                                                                                              func (r Raw) LookupErr(key ...string) (RawValue, 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 (Raw) String

                                                                                                                                func (r Raw) String() string

                                                                                                                                  String implements the fmt.Stringer interface.

                                                                                                                                  func (Raw) Validate

                                                                                                                                  func (r Raw) Validate() (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
                                                                                                                                    Output:
                                                                                                                                    
                                                                                                                                    <nil>
                                                                                                                                    

                                                                                                                                    func (Raw) Values

                                                                                                                                    func (r Raw) Values() ([]RawValue, 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 RawElement

                                                                                                                                      type RawElement []byte

                                                                                                                                        RawElement represents a BSON element in byte form. This type provides a simple way to transform a slice of bytes into a BSON element and extract information from it.

                                                                                                                                        RawElement is a thin wrapper around a bsoncore.Element.

                                                                                                                                        func (RawElement) DebugString

                                                                                                                                        func (re RawElement) 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 (RawElement) Key

                                                                                                                                          func (re RawElement) 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 (RawElement) KeyErr

                                                                                                                                            func (re RawElement) KeyErr() (string, error)

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

                                                                                                                                              func (RawElement) String

                                                                                                                                              func (re RawElement) String() string

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

                                                                                                                                                func (RawElement) Validate

                                                                                                                                                func (re RawElement) Validate() error

                                                                                                                                                  Validate ensures re is a valid BSON element.

                                                                                                                                                  func (RawElement) Value

                                                                                                                                                  func (re RawElement) Value() RawValue

                                                                                                                                                    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 (RawElement) ValueErr

                                                                                                                                                    func (re RawElement) ValueErr() (RawValue, error)

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

                                                                                                                                                      type RawValue

                                                                                                                                                      type RawValue struct {
                                                                                                                                                      	Type  bsontype.Type
                                                                                                                                                      	Value []byte
                                                                                                                                                      	// contains filtered or unexported fields
                                                                                                                                                      }

                                                                                                                                                        RawValue represents a BSON value in byte form. It can be used to hold unprocessed BSON or to defer processing of BSON. Type is the BSON type of the value and Value are the raw bytes that represent the element.

                                                                                                                                                        This type wraps bsoncore.Value for most of it's functionality.

                                                                                                                                                        func (RawValue) Array

                                                                                                                                                        func (rv RawValue) Array() Raw

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

                                                                                                                                                          func (RawValue) ArrayOK

                                                                                                                                                          func (rv RawValue) ArrayOK() (Raw, bool)

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

                                                                                                                                                            func (RawValue) AsInt32

                                                                                                                                                            func (rv RawValue) AsInt32() int32

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

                                                                                                                                                              func (RawValue) AsInt32OK

                                                                                                                                                              func (rv RawValue) AsInt32OK() (int32, bool)

                                                                                                                                                                AsInt32OK is the same as AsInt32, except that it returns a boolean instead of panicking.

                                                                                                                                                                func (RawValue) AsInt64

                                                                                                                                                                func (rv RawValue) AsInt64() int64

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

                                                                                                                                                                  func (RawValue) AsInt64OK

                                                                                                                                                                  func (rv RawValue) AsInt64OK() (int64, bool)

                                                                                                                                                                    AsInt64OK is the same as AsInt64, except that it returns a boolean instead of panicking.

                                                                                                                                                                    func (RawValue) Binary

                                                                                                                                                                    func (rv RawValue) 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 (RawValue) BinaryOK

                                                                                                                                                                      func (rv RawValue) BinaryOK() (subtype byte, data []byte, ok bool)

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

                                                                                                                                                                        func (RawValue) Boolean

                                                                                                                                                                        func (rv RawValue) Boolean() bool

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

                                                                                                                                                                          func (RawValue) BooleanOK

                                                                                                                                                                          func (rv RawValue) BooleanOK() (bool, bool)

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

                                                                                                                                                                            func (RawValue) CodeWithScope

                                                                                                                                                                            func (rv RawValue) CodeWithScope() (string, Raw)

                                                                                                                                                                              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 (RawValue) CodeWithScopeOK

                                                                                                                                                                              func (rv RawValue) CodeWithScopeOK() (string, Raw, bool)

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

                                                                                                                                                                                func (RawValue) DBPointer

                                                                                                                                                                                func (rv RawValue) 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 (RawValue) DBPointerOK

                                                                                                                                                                                  func (rv RawValue) DBPointerOK() (string, primitive.ObjectID, bool)

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

                                                                                                                                                                                    func (RawValue) DateTime

                                                                                                                                                                                    func (rv RawValue) 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 (RawValue) DateTimeOK

                                                                                                                                                                                      func (rv RawValue) DateTimeOK() (int64, bool)

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

                                                                                                                                                                                        func (RawValue) DebugString

                                                                                                                                                                                        func (rv RawValue) 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 (RawValue) Decimal128

                                                                                                                                                                                          func (rv RawValue) Decimal128() primitive.Decimal128

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

                                                                                                                                                                                            func (RawValue) Decimal128OK

                                                                                                                                                                                            func (rv RawValue) Decimal128OK() (primitive.Decimal128, bool)

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

                                                                                                                                                                                              func (RawValue) Document

                                                                                                                                                                                              func (rv RawValue) Document() Raw

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

                                                                                                                                                                                                func (RawValue) DocumentOK

                                                                                                                                                                                                func (rv RawValue) DocumentOK() (Raw, bool)

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

                                                                                                                                                                                                  func (RawValue) Double

                                                                                                                                                                                                  func (rv RawValue) Double() float64

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

                                                                                                                                                                                                    func (RawValue) DoubleOK

                                                                                                                                                                                                    func (rv RawValue) DoubleOK() (float64, bool)

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

                                                                                                                                                                                                      func (RawValue) Equal

                                                                                                                                                                                                      func (rv RawValue) Equal(rv2 RawValue) bool

                                                                                                                                                                                                        Equal compares rv and rv2 and returns true if they are equal.

                                                                                                                                                                                                        func (RawValue) Int32

                                                                                                                                                                                                        func (rv RawValue) Int32() int32

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

                                                                                                                                                                                                          func (RawValue) Int32OK

                                                                                                                                                                                                          func (rv RawValue) Int32OK() (int32, bool)

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

                                                                                                                                                                                                            func (RawValue) Int64

                                                                                                                                                                                                            func (rv RawValue) Int64() int64

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

                                                                                                                                                                                                              func (RawValue) Int64OK

                                                                                                                                                                                                              func (rv RawValue) Int64OK() (int64, bool)

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

                                                                                                                                                                                                                func (RawValue) IsNumber

                                                                                                                                                                                                                func (rv RawValue) IsNumber() bool

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

                                                                                                                                                                                                                  func (RawValue) JavaScript

                                                                                                                                                                                                                  func (rv RawValue) 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 (RawValue) JavaScriptOK

                                                                                                                                                                                                                    func (rv RawValue) JavaScriptOK() (string, bool)

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

                                                                                                                                                                                                                      func (RawValue) ObjectID

                                                                                                                                                                                                                      func (rv RawValue) 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 (RawValue) ObjectIDOK

                                                                                                                                                                                                                        func (rv RawValue) ObjectIDOK() (primitive.ObjectID, bool)

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

                                                                                                                                                                                                                          func (RawValue) Regex

                                                                                                                                                                                                                          func (rv RawValue) 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 (RawValue) RegexOK

                                                                                                                                                                                                                            func (rv RawValue) RegexOK() (pattern, options string, ok bool)

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

                                                                                                                                                                                                                              func (RawValue) String

                                                                                                                                                                                                                              func (rv RawValue) 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 (RawValue) StringValue

                                                                                                                                                                                                                                func (rv RawValue) StringValue() string

                                                                                                                                                                                                                                  StringValue returns the string value 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 (RawValue) StringValueOK

                                                                                                                                                                                                                                  func (rv RawValue) StringValueOK() (string, bool)

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

                                                                                                                                                                                                                                    func (RawValue) Symbol

                                                                                                                                                                                                                                    func (rv RawValue) Symbol() string

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

                                                                                                                                                                                                                                      func (RawValue) SymbolOK

                                                                                                                                                                                                                                      func (rv RawValue) SymbolOK() (string, bool)

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

                                                                                                                                                                                                                                        func (RawValue) Time

                                                                                                                                                                                                                                        func (rv RawValue) 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 (RawValue) TimeOK

                                                                                                                                                                                                                                          func (rv RawValue) TimeOK() (time.Time, bool)

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

                                                                                                                                                                                                                                            func (RawValue) Timestamp

                                                                                                                                                                                                                                            func (rv RawValue) 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 (RawValue) TimestampOK

                                                                                                                                                                                                                                              func (rv RawValue) TimestampOK() (t, i uint32, ok bool)

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

                                                                                                                                                                                                                                                func (RawValue) Unmarshal

                                                                                                                                                                                                                                                func (rv RawValue) Unmarshal(val interface{}) error

                                                                                                                                                                                                                                                  Unmarshal deserializes BSON into the provided val. If RawValue cannot be unmarshaled into val, an error is returned. This method will use the registry used to create the RawValue, if the RawValue was created from partial BSON processing, or it will use the default registry. Users wishing to specify the registry to use should use UnmarshalWithRegistry.

                                                                                                                                                                                                                                                  func (RawValue) UnmarshalWithContext

                                                                                                                                                                                                                                                  func (rv RawValue) UnmarshalWithContext(dc *bsoncodec.DecodeContext, val interface{}) error

                                                                                                                                                                                                                                                    UnmarshalWithContext performs the same unmarshalling as Unmarshal but uses the provided DecodeContext instead of the one attached or the default registry.

                                                                                                                                                                                                                                                    func (RawValue) UnmarshalWithRegistry

                                                                                                                                                                                                                                                    func (rv RawValue) UnmarshalWithRegistry(r *bsoncodec.Registry, val interface{}) error

                                                                                                                                                                                                                                                      UnmarshalWithRegistry performs the same unmarshalling as Unmarshal but uses the provided registry instead of the one attached or the default registry.

                                                                                                                                                                                                                                                      func (RawValue) Validate

                                                                                                                                                                                                                                                      func (rv RawValue) Validate() error

                                                                                                                                                                                                                                                        Validate ensures the value is a valid BSON value.

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

                                                                                                                                                                                                                                                            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

                                                                                                                                                                                                                                                              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.

                                                                                                                                                                                                                                                                Directories

                                                                                                                                                                                                                                                                Path Synopsis
                                                                                                                                                                                                                                                                Package bsoncodec provides a system for encoding values to BSON representations and decoding values from BSON representations.
                                                                                                                                                                                                                                                                Package bsoncodec provides a system for encoding values to BSON representations and decoding values from BSON representations.
                                                                                                                                                                                                                                                                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.
                                                                                                                                                                                                                                                                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 mgocompat provides Registry, a BSON registry compatible with globalsign/mgo's BSON, with some remaining differences.
                                                                                                                                                                                                                                                                Package mgocompat provides Registry, a BSON registry compatible with globalsign/mgo's BSON, with some remaining differences.
                                                                                                                                                                                                                                                                Package primitive contains types similar to Go primitives for BSON types can do not have direct Go primitive representations.
                                                                                                                                                                                                                                                                Package primitive contains types similar to Go primitives for BSON types can do not have direct Go primitive representations.