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 marshalling and unmarshalling 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 and
11 // 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 unmarshalling:
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 marshalling a D or M to BSON. Some other useful marshalling 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.
72 // 5. uint8 and uint16 marshal to a BSON int32.
73 // 6. uint, uint32, and uint64 marshal to a BSON int32 if the value is between math.MinInt32 and math.MaxInt32,
74 // inclusive, and BSON int64 otherwise.
75 // 7. BSON null and undefined values will unmarshal into the zero value of a field (e.g. unmarshalling a BSON null or
76 // undefined value into a string will yield the empty string.).
77 //
78 // # Structs
79 //
80 // Structs can be marshalled/unmarshalled to/from BSON or Extended JSON. When transforming structs to/from BSON or Extended
81 // JSON, the following rules apply:
82 //
83 // 1. Only exported fields in structs will be marshalled or unmarshalled.
84 //
85 // 2. When marshalling a struct, each field will be lowercased to generate the key for the corresponding BSON element.
86 // For example, a struct field named "Foo" will generate key "foo". This can be overridden via a struct tag (e.g.
87 // `bson:"fooField"` to generate key "fooField" instead).
88 //
89 // 3. An embedded struct field is marshalled as a subdocument. The key will be the lowercased name of the field's type.
90 //
91 // 4. A pointer field is marshalled as the underlying type if the pointer is non-nil. If the pointer is nil, it is
92 // marshalled as a BSON null value.
93 //
94 // 5. When unmarshalling, a field of type interface{} will follow the D/M type mappings listed above. BSON documents
95 // unmarshalled into an interface{} field will be unmarshalled as a D.
96 //
97 // The encoding of each struct field can be customized by the "bson" struct tag.
98 //
99 // This tag behavior is configurable, and different struct tag behavior can be configured by initializing a new
100 // bsoncodec.StructCodec with the desired tag parser and registering that StructCodec onto the Registry. By default, JSON tags
101 // are not honored, but that can be enabled by creating a StructCodec with JSONFallbackStructTagParser, like below:
102 //
103 // Example:
104 //
105 // structcodec, _ := bsoncodec.NewStructCodec(bsoncodec.JSONFallbackStructTagParser)
106 //
107 // The bson tag gives the name of the field, possibly followed by a comma-separated list of options.
108 // The name may be empty in order to specify options without overriding the default field name. The following options can be used
109 // to configure behavior:
110 //
111 // 1. omitempty: If the omitempty struct tag is specified on a field, the field will not be marshalled if it is set to
112 // the zero value. Fields with language primitive types such as integers, booleans, and strings are considered empty if
113 // their value is equal to the zero value for the type (i.e. 0 for integers, false for booleans, and "" for strings).
114 // Slices, maps, and arrays are considered empty if they are of length zero. Interfaces and pointers are considered
115 // empty if their value is nil. By default, structs are only considered empty if the struct type implements the
116 // bsoncodec.Zeroer interface and the IsZero method returns true. Struct fields whose types do not implement Zeroer are
117 // never considered empty and will be marshalled as embedded documents.
118 // NOTE: It is recommended that this tag be used for all slice and map fields.
119 //
120 // 2. minsize: If the minsize struct tag is specified on a field of type int64, uint, uint32, or uint64 and the value of
121 // the field can fit in a signed int32, the field will be serialized as a BSON int32 rather than a BSON int64. For other
122 // types, this tag is ignored.
123 //
124 // 3. truncate: If the truncate struct tag is specified on a field with a non-float numeric type, BSON doubles unmarshalled
125 // into that field will be truncated at the decimal point. For example, if 3.14 is unmarshalled into a field of type int,
126 // it will be unmarshalled as 3. If this tag is not specified, the decoder will throw an error if the value cannot be
127 // decoded without losing precision. For float64 or non-numeric types, this tag is ignored.
128 //
129 // 4. inline: If the inline struct tag is specified for a struct or map field, the field will be "flattened" when
130 // marshalling and "un-flattened" when unmarshalling. This means that all of the fields in that struct/map will be
131 // pulled up one level and will become top-level fields rather than being fields in a nested document. For example, if a
132 // map field named "Map" with value map[string]interface{}{"foo": "bar"} is inlined, the resulting document will be
133 // {"foo": "bar"} instead of {"map": {"foo": "bar"}}. There can only be one inlined map field in a struct. If there are
134 // duplicated fields in the resulting document when an inlined struct is marshalled, the inlined field will be overwritten.
135 // If there are duplicated fields in the resulting document when an inlined map is marshalled, an error will be returned.
136 // This tag can be used with fields that are pointers to structs. If an inlined pointer field is nil, it will not be
137 // marshalled. For fields that are not maps or structs, this tag is ignored.
138 //
139 // # Marshalling and Unmarshalling
140 //
141 // Manually marshalling and unmarshalling can be done with the Marshal and Unmarshal family of functions.
142 //
143 // [Work with BSON]: https://www.mongodb.com/docs/drivers/go/current/fundamentals/bson/
144 package bson
145