|
6 | 6 |
|
7 | 7 | // Package bson is a library for reading, writing, and manipulating BSON. BSON is a binary serialization format used to |
8 | 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. |
| 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 | 12 | // |
13 | 13 | // # Raw BSON |
14 | 14 | // |
|
38 | 38 | // bson.D{{"foo", "bar"}, {"hello", "world"}, {"pi", 3.14159}} |
39 | 39 | // bson.M{"foo": "bar", "hello": "world", "pi": 3.14159} |
40 | 40 | // |
41 | | -// When decoding BSON to a D or M, the following type mappings apply when unmarshalling: |
| 41 | +// When decoding BSON to a D or M, the following type mappings apply when unmarshaling: |
42 | 42 | // |
43 | 43 | // 1. BSON int32 unmarshals to an int32. |
44 | 44 | // 2. BSON int64 unmarshals to an int64. |
|
62 | 62 | // 20. BSON DBPointer unmarshals to a primitive.DBPointer. |
63 | 63 | // 21. BSON symbol unmarshals to a primitive.Symbol. |
64 | 64 | // |
65 | | -// The above mappings also apply when marshalling a D or M to BSON. Some other useful marshalling mappings are: |
| 65 | +// The above mappings also apply when marshaling a D or M to BSON. Some other useful marshaling mappings are: |
66 | 66 | // |
67 | 67 | // 1. time.Time marshals to a BSON datetime. |
68 | 68 | // 2. int8, int16, and int32 marshal to a BSON int32. |
|
72 | 72 | // 5. uint8 and uint16 marshal to a BSON int32. |
73 | 73 | // 6. uint, uint32, and uint64 marshal to a BSON int32 if the value is between math.MinInt32 and math.MaxInt32, |
74 | 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 |
| 75 | +// 7. BSON null and undefined values will unmarshal into the zero value of a field (e.g. unmarshaling a BSON null or |
76 | 76 | // undefined value into a string will yield the empty string.). |
77 | 77 | // |
78 | 78 | // # Structs |
79 | 79 | // |
80 | | -// Structs can be marshalled/unmarshalled to/from BSON or Extended JSON. When transforming structs to/from BSON or Extended |
| 80 | +// Structs can be marshaled/unmarshaled to/from BSON or Extended JSON. When transforming structs to/from BSON or Extended |
81 | 81 | // JSON, the following rules apply: |
82 | 82 | // |
83 | | -// 1. Only exported fields in structs will be marshalled or unmarshalled. |
| 83 | +// 1. Only exported fields in structs will be marshaled or unmarshaled. |
84 | 84 | // |
85 | | -// 2. When marshalling a struct, each field will be lowercased to generate the key for the corresponding BSON element. |
| 85 | +// 2. When marshaling a struct, each field will be lowercased to generate the key for the corresponding BSON element. |
86 | 86 | // For example, a struct field named "Foo" will generate key "foo". This can be overridden via a struct tag (e.g. |
87 | 87 | // `bson:"fooField"` to generate key "fooField" instead). |
88 | 88 | // |
89 | | -// 3. An embedded struct field is marshalled as a subdocument. The key will be the lowercased name of the field's type. |
| 89 | +// 3. An embedded struct field is marshaled as a subdocument. The key will be the lowercased name of the field's type. |
90 | 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. |
| 91 | +// 4. A pointer field is marshaled as the underlying type if the pointer is non-nil. If the pointer is nil, it is |
| 92 | +// marshaled as a BSON null value. |
93 | 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. |
| 94 | +// 5. When unmarshaling, a field of type interface{} will follow the D/M type mappings listed above. BSON documents |
| 95 | +// unmarshaled into an interface{} field will be unmarshaled as a D. |
96 | 96 | // |
97 | 97 | // The encoding of each struct field can be customized by the "bson" struct tag. |
98 | 98 | // |
99 | 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: |
| 100 | +// bsoncodec.StructCodec with the desired tag parser and registering that StructCodec onto the Registry. By default, JSON |
| 101 | +// tags are not honored, but that can be enabled by creating a StructCodec with JSONFallbackStructTagParser, like below: |
102 | 102 | // |
103 | 103 | // Example: |
104 | 104 | // |
105 | 105 | // structcodec, _ := bsoncodec.NewStructCodec(bsoncodec.JSONFallbackStructTagParser) |
106 | 106 | // |
107 | 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. |
| 108 | +// The name may be empty in order to specify options without overriding the default field name. The following options can |
| 109 | +// be used to configure behavior: |
| 110 | +// |
| 111 | +// 1. omitempty: If the omitempty struct tag is specified on a field, the field will be omitted from the marshaling if |
| 112 | +// the field has an empty value, defined as false, 0, a nil pointer, a nil interface value, and any empty array, |
| 113 | +// slice, map, or string. |
118 | 114 | // NOTE: It is recommended that this tag be used for all slice and map fields. |
119 | 115 | // |
120 | 116 | // 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. |
| 117 | +// the field can fit in a signed int32, the field will be serialized as a BSON int32 rather than a BSON int64. For |
| 118 | +// other types, this tag is ignored. |
123 | 119 | // |
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. |
| 120 | +// 3. truncate: If the truncate struct tag is specified on a field with a non-float numeric type, BSON doubles |
| 121 | +// unmarshaled into that field will be truncated at the decimal point. For example, if 3.14 is unmarshaled into a |
| 122 | +// field of type int, it will be unmarshaled as 3. If this tag is not specified, the decoder will throw an error if |
| 123 | +// the value cannot be decoded without losing precision. For float64 or non-numeric types, this tag is ignored. |
128 | 124 | // |
129 | 125 | // 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. |
| 126 | +// marshaling and "un-flattened" when unmarshaling. This means that all of the fields in that struct/map will be |
| 127 | +// pulled up one level and will become top-level fields rather than being fields in a nested document. For example, |
| 128 | +// if a map field named "Map" with value map[string]interface{}{"foo": "bar"} is inlined, the resulting document will |
| 129 | +// be {"foo": "bar"} instead of {"map": {"foo": "bar"}}. There can only be one inlined map field in a struct. If |
| 130 | +// there are duplicated fields in the resulting document when an inlined struct is marshaled, the inlined field will |
| 131 | +// be overwritten. If there are duplicated fields in the resulting document when an inlined map is marshaled, an |
| 132 | +// error will be returned. This tag can be used with fields that are pointers to structs. If an inlined pointer field |
| 133 | +// is nil, it will not be marshaled. For fields that are not maps or structs, this tag is ignored. |
| 134 | +// |
| 135 | +// # Marshaling and Unmarshaling |
| 136 | +// |
| 137 | +// Manually marshaling and unmarshaling can be done with the Marshal and Unmarshal family of functions. |
142 | 138 | // |
143 | 139 | // [Work with BSON]: https://www.mongodb.com/docs/drivers/go/current/fundamentals/bson/ |
144 | 140 | package bson |
0 commit comments