1 // Copyright (C) MongoDB, Inc. 2017-present. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may 4 // not use this file except in compliance with the License. You may obtain 5 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 6 7 // Package bson is a library for reading, writing, and manipulating BSON. BSON is a binary serialization format used to 8 // store documents and make remote procedure calls in MongoDB. The BSON specification is located at https://bsonspec.org. 9 // The BSON library handles marshaling and unmarshaling of values through a configurable codec system. For a description 10 // of the codec system and examples of registering custom codecs, see the bsoncodec package. For additional information 11 // and usage examples, check out the [Work with BSON] page in the Go Driver docs site. 12 // 13 // # Raw BSON 14 // 15 // The Raw family of types is used to validate and retrieve elements from a slice of bytes. This 16 // type is most useful when you want do lookups on BSON bytes without unmarshaling it into another 17 // type. 18 // 19 // Example: 20 // 21 // var raw bson.Raw = ... // bytes from somewhere 22 // err := raw.Validate() 23 // if err != nil { return err } 24 // val := raw.Lookup("foo") 25 // i32, ok := val.Int32OK() 26 // // do something with i32... 27 // 28 // # Native Go Types 29 // 30 // The D and M types defined in this package can be used to build representations of BSON using native Go types. D is a 31 // slice and M is a map. For more information about the use cases for these types, see the documentation on the type 32 // definitions. 33 // 34 // Note that a D should not be constructed with duplicate key names, as that can cause undefined server behavior. 35 // 36 // Example: 37 // 38 // bson.D{{"foo", "bar"}, {"hello", "world"}, {"pi", 3.14159}} 39 // bson.M{"foo": "bar", "hello": "world", "pi": 3.14159} 40 // 41 // When decoding BSON to a D or M, the following type mappings apply when unmarshaling: 42 // 43 // 1. BSON int32 unmarshals to an int32. 44 // 2. BSON int64 unmarshals to an int64. 45 // 3. BSON double unmarshals to a float64. 46 // 4. BSON string unmarshals to a string. 47 // 5. BSON boolean unmarshals to a bool. 48 // 6. BSON embedded document unmarshals to the parent type (i.e. D for a D, M for an M). 49 // 7. BSON array unmarshals to a bson.A. 50 // 8. BSON ObjectId unmarshals to a primitive.ObjectID. 51 // 9. BSON datetime unmarshals to a primitive.DateTime. 52 // 10. BSON binary unmarshals to a primitive.Binary. 53 // 11. BSON regular expression unmarshals to a primitive.Regex. 54 // 12. BSON JavaScript unmarshals to a primitive.JavaScript. 55 // 13. BSON code with scope unmarshals to a primitive.CodeWithScope. 56 // 14. BSON timestamp unmarshals to an primitive.Timestamp. 57 // 15. BSON 128-bit decimal unmarshals to an primitive.Decimal128. 58 // 16. BSON min key unmarshals to an primitive.MinKey. 59 // 17. BSON max key unmarshals to an primitive.MaxKey. 60 // 18. BSON undefined unmarshals to a primitive.Undefined. 61 // 19. BSON null unmarshals to nil. 62 // 20. BSON DBPointer unmarshals to a primitive.DBPointer. 63 // 21. BSON symbol unmarshals to a primitive.Symbol. 64 // 65 // The above mappings also apply when marshaling a D or M to BSON. Some other useful marshaling mappings are: 66 // 67 // 1. time.Time marshals to a BSON datetime. 68 // 2. int8, int16, and int32 marshal to a BSON int32. 69 // 3. int marshals to a BSON int32 if the value is between math.MinInt32 and math.MaxInt32, inclusive, and a BSON int64 70 // otherwise. 71 // 4. int64 marshals to BSON int64 (unless [Encoder.IntMinSize] is set). 72 // 5. uint8 and uint16 marshal to a BSON int32. 73 // 6. uint, uint32, and uint64 marshal to a BSON int64 (unless [Encoder.IntMinSize] is set). 74 // 7. BSON null and undefined values will unmarshal into the zero value of a field (e.g. unmarshaling a BSON null or 75 // undefined value into a string will yield the empty string.). 76 // 77 // # Structs 78 // 79 // Structs can be marshaled/unmarshaled to/from BSON or Extended JSON. When transforming structs to/from BSON or Extended 80 // JSON, the following rules apply: 81 // 82 // 1. Only exported fields in structs will be marshaled or unmarshaled. 83 // 84 // 2. When marshaling a struct, each field will be lowercased to generate the key for the corresponding BSON element. 85 // For example, a struct field named "Foo" will generate key "foo". This can be overridden via a struct tag (e.g. 86 // `bson:"fooField"` to generate key "fooField" instead). 87 // 88 // 3. An embedded struct field is marshaled as a subdocument. The key will be the lowercased name of the field's type. 89 // 90 // 4. A pointer field is marshaled as the underlying type if the pointer is non-nil. If the pointer is nil, it is 91 // marshaled as a BSON null value. 92 // 93 // 5. When unmarshaling, a field of type interface{} will follow the D/M type mappings listed above. BSON documents 94 // unmarshaled into an interface{} field will be unmarshaled as a D. 95 // 96 // The encoding of each struct field can be customized by the "bson" struct tag. 97 // 98 // This tag behavior is configurable, and different struct tag behavior can be configured by initializing a new 99 // bsoncodec.StructCodec with the desired tag parser and registering that StructCodec onto the Registry. By default, JSON 100 // tags are not honored, but that can be enabled by creating a StructCodec with JSONFallbackStructTagParser, like below: 101 // 102 // Example: 103 // 104 // structcodec, _ := bsoncodec.NewStructCodec(bsoncodec.JSONFallbackStructTagParser) 105 // 106 // The bson tag gives the name of the field, possibly followed by a comma-separated list of options. 107 // The name may be empty in order to specify options without overriding the default field name. The following options can 108 // be used to configure behavior: 109 // 110 // 1. omitempty: If the omitempty struct tag is specified on a field, the field will be omitted from the marshaling if 111 // the field has an empty value, defined as false, 0, a nil pointer, a nil interface value, and any empty array, 112 // slice, map, or string. 113 // NOTE: It is recommended that this tag be used for all slice and map fields. 114 // 115 // 2. minsize: If the minsize struct tag is specified on a field of type int64, uint, uint32, or uint64 and the value of 116 // the field can fit in a signed int32, the field will be serialized as a BSON int32 rather than a BSON int64. For 117 // other types, this tag is ignored. 118 // 119 // 3. truncate: If the truncate struct tag is specified on a field with a non-float numeric type, BSON doubles 120 // unmarshaled into that field will be truncated at the decimal point. For example, if 3.14 is unmarshaled into a 121 // field of type int, it will be unmarshaled as 3. If this tag is not specified, the decoder will throw an error if 122 // the value cannot be decoded without losing precision. For float64 or non-numeric types, this tag is ignored. 123 // 124 // 4. inline: If the inline struct tag is specified for a struct or map field, the field will be "flattened" when 125 // marshaling and "un-flattened" when unmarshaling. This means that all of the fields in that struct/map will be 126 // pulled up one level and will become top-level fields rather than being fields in a nested document. For example, 127 // if a map field named "Map" with value map[string]interface{}{"foo": "bar"} is inlined, the resulting document will 128 // be {"foo": "bar"} instead of {"map": {"foo": "bar"}}. There can only be one inlined map field in a struct. If 129 // there are duplicated fields in the resulting document when an inlined struct is marshaled, the inlined field will 130 // be overwritten. If there are duplicated fields in the resulting document when an inlined map is marshaled, an 131 // error will be returned. This tag can be used with fields that are pointers to structs. If an inlined pointer field 132 // is nil, it will not be marshaled. For fields that are not maps or structs, this tag is ignored. 133 // 134 // # Marshaling and Unmarshaling 135 // 136 // Manually marshaling and unmarshaling can be done with the Marshal and Unmarshal family of functions. 137 // 138 // [Work with BSON]: https://www.mongodb.com/docs/drivers/go/current/fundamentals/bson/ 139 package bson 140