diff --git a/bson/decoder.go b/bson/decoder.go index c6a7626719..2fa9e6f1d6 100644 --- a/bson/decoder.go +++ b/bson/decoder.go @@ -87,7 +87,7 @@ func (d *Decoder) SetRegistry(r *Registry) { d.dc.Registry = r } -// DefaultDocumentM causes the Decoder to always unmarshal documents into the primitive.M type. This +// DefaultDocumentM causes the Decoder to always unmarshal documents into the bson.M type. This // behavior is restricted to data typed as "interface{}" or "map[string]interface{}". func (d *Decoder) DefaultDocumentM() { d.dc.defaultDocumentType = reflect.TypeOf(M{}) @@ -101,7 +101,7 @@ func (d *Decoder) AllowTruncatingDoubles() { } // BinaryAsSlice causes the Decoder to unmarshal BSON binary field values that are the "Generic" or -// "Old" BSON binary subtype as a Go byte slice instead of a primitive.Binary. +// "Old" BSON binary subtype as a Go byte slice instead of a bson.Binary. func (d *Decoder) BinaryAsSlice() { d.dc.binaryAsSlice = true } diff --git a/bson/doc.go b/bson/doc.go index 9990da008e..81aceef278 100644 --- a/bson/doc.go +++ b/bson/doc.go @@ -47,20 +47,20 @@ // 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. +// 8. BSON ObjectId unmarshals to a bson.ObjectID. +// 9. BSON datetime unmarshals to a bson.DateTime. +// 10. BSON binary unmarshals to a bson.Binary. +// 11. BSON regular expression unmarshals to a bson.Regex. +// 12. BSON JavaScript unmarshals to a bson.JavaScript. +// 13. BSON code with scope unmarshals to a bson.CodeWithScope. +// 14. BSON timestamp unmarshals to an bson.Timestamp. +// 15. BSON 128-bit decimal unmarshals to an bson.Decimal128. +// 16. BSON min key unmarshals to an bson.MinKey. +// 17. BSON max key unmarshals to an bson.MaxKey. +// 18. BSON undefined unmarshals to a bson.Undefined. // 19. BSON null unmarshals to nil. -// 20. BSON DBPointer unmarshals to a primitive.DBPointer. -// 21. BSON symbol unmarshals to a primitive.Symbol. +// 20. BSON DBPointer unmarshals to a bson.DBPointer. +// 21. BSON symbol unmarshals to a bson.Symbol. // // The above mappings also apply when marshaling a D or M to BSON. Some other useful marshaling mappings are: // diff --git a/bson/primitive.go b/bson/primitive.go index 80cf085b02..162bfa7133 100644 --- a/bson/primitive.go +++ b/bson/primitive.go @@ -60,7 +60,7 @@ func (d DateTime) MarshalJSON() ([]byte, error) { return d.Time().UTC().MarshalJSON() } -// UnmarshalJSON creates a primitive.DateTime from a JSON string. +// UnmarshalJSON creates a bson.DateTime from a JSON string. func (d *DateTime) UnmarshalJSON(data []byte) error { // Ignore "null" so that we can distinguish between a "null" value and // valid value that is the zero time (as reported by time.Time.IsZero). diff --git a/docs/migration-2.0.md b/docs/migration-2.0.md index c0c6f3a20b..aa11b57f92 100644 --- a/docs/migration-2.0.md +++ b/docs/migration-2.0.md @@ -867,6 +867,34 @@ The `NewRegistryBuilder` function has been removed along with the `bsoncodec.Reg ### Decoder +The BSON decoding logic has changed to decode into a `bson.D` by default. + +The example shows the behavior change. + +```go +// v1 + +b1 := bson.M{"a": 1, "b": bson.M{"c": 2}} +b2, _ := bson.Marshal(b1) +b3 := bson.M{} +bson.Unmarshal(b2, &b3) +fmt.Printf("b3.b type: %T\n", b3["b"]) +// Output: b3.b type: primitive.M +``` + +```go +// v2 + +b1 := bson.M{"a": 1, "b": bson.M{"c": 2}} +b2, _ := bson.Marshal(b1) +b3 := bson.M{} +bson.Unmarshal(b2, &b3) +fmt.Printf("b3.b type: %T\n", b3["b"]) +// Output: b3.b type: bson.D +``` + +Use `Decoder.DefaultDocumentM()` or set the `DefaultDocumentM` field of `options.BSONOptions` to always decode documents into the `bson.M` type. + #### NewDecoder The signature of `NewDecoder` has been updated without an error being returned. @@ -1043,11 +1071,11 @@ The signature of `Reset` has been updated without an error being returned. #### DefaultDocumentD / DefaultDocumentM -`Decoder.DefaultDocumentD` has been removed since a document, including a top-level value (e.g. you pass in an empty interface value to Decode), is always decoded into a `bson.D` by default. Therefore, use `Decoder.DefaultDocumentM` to always decode a document into a `bson.M` to avoid unexpected decode results. +`Decoder.DefaultDocumentD()` has been removed since a document, including a top-level value (e.g. you pass in an empty interface value to Decode), is always decoded into a `bson.D` by default. Therefore, use `Decoder.DefaultDocumentM()` to always decode a document into a `bson.M` to avoid unexpected decode results. #### ObjectIDAsHexString -`Decoder.ObjectIDAsHexString` method enables decoding a BSON ObjectId as a hexadecimal string. Otherwise, the decoder returns an error by default instead of decoding as the UTF-8 representation of the raw ObjectId bytes, which results in a garbled and unusable string. +`Decoder.ObjectIDAsHexString()` method enables decoding a BSON ObjectId as a hexadecimal string. Otherwise, the decoder returns an error by default instead of decoding as the UTF-8 representation of the raw ObjectId bytes, which results in a garbled and unusable string. ### Encoder diff --git a/mongo/gridfs_download_stream.go b/mongo/gridfs_download_stream.go index 1cc9bf65fd..29df84cc0a 100644 --- a/mongo/gridfs_download_stream.go +++ b/mongo/gridfs_download_stream.go @@ -52,7 +52,7 @@ type GridFSDownloadStream struct { // GridFSDownloadStream.GetFile method. type GridFSFile struct { // ID is the file's ID. This will match the file ID specified when uploading the file. If an upload helper that - // does not require a file ID was used, this field will be a primitive.ObjectID. + // does not require a file ID was used, this field will be a bson.ObjectID. ID interface{} // Length is the length of this file in bytes. diff --git a/mongo/options/clientoptions.go b/mongo/options/clientoptions.go index bbca8b0ddb..1c036b387d 100644 --- a/mongo/options/clientoptions.go +++ b/mongo/options/clientoptions.go @@ -197,11 +197,11 @@ type BSONOptions struct { // BinaryAsSlice causes the driver to unmarshal BSON binary field values // that are the "Generic" or "Old" BSON binary subtype as a Go byte slice - // instead of a primitive.Binary. + // instead of a bson.Binary. BinaryAsSlice bool // DefaultDocumentM causes the driver to always unmarshal documents into the - // primitive.M type. This behavior is restricted to data typed as + // bson.M type. This behavior is restricted to data typed as // "interface{}" or "map[string]interface{}". DefaultDocumentM bool diff --git a/mongo/options/encryptoptions.go b/mongo/options/encryptoptions.go index 46d8d46fdd..5a45ac16ed 100644 --- a/mongo/options/encryptoptions.go +++ b/mongo/options/encryptoptions.go @@ -128,7 +128,7 @@ func Encrypt() *EncryptOptionsBuilder { return &EncryptOptionsBuilder{} } -// SetKeyID specifies an _id of a data key. This should be a UUID (a primitive.Binary with subtype 4). +// SetKeyID specifies an _id of a data key. This should be a UUID (a bson.Binary with subtype 4). func (e *EncryptOptionsBuilder) SetKeyID(keyID bson.Binary) *EncryptOptionsBuilder { e.Opts = append(e.Opts, func(opts *EncryptOptions) error { opts.KeyID = &keyID