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