• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# BSON
2
3BSON, short for Bin­ary JSON, is a bin­ary-en­coded seri­al­iz­a­tion of JSON-like doc­u­ments. Like JSON, BSON sup­ports the em­bed­ding of doc­u­ments and ar­rays with­in oth­er doc­u­ments and ar­rays. BSON also con­tains ex­ten­sions that al­low rep­res­ent­a­tion of data types that are not part of the JSON spec. For ex­ample, BSON has a Date type and a BinData type.
4
5!!! abstract "References"
6
7	- [BSON Website](http://bsonspec.org) - the main source on BSON
8	- [BSON Specification](http://bsonspec.org/spec.html) - the specification
9
10
11## Serialization
12
13The library uses the following mapping from JSON values types to BSON types:
14
15JSON value type | value/range                       | BSON type   | marker
16--------------- | --------------------------------- | ----------- | ------
17null            | `null`                            | null        | 0x0A
18boolean         | `true`, `false`                   | boolean     | 0x08
19number_integer  | -9223372036854775808..-2147483649 | int64       | 0x12
20number_integer  | -2147483648..2147483647           | int32       | 0x10
21number_integer  | 2147483648..9223372036854775807   | int64       | 0x12
22number_unsigned | 0..2147483647                     | int32       | 0x10
23number_unsigned | 2147483648..9223372036854775807   | int64       | 0x12
24number_unsigned | 9223372036854775808..18446744073709551615| --   | --
25number_float    | *any value*                       | double      | 0x01
26string          | *any value*                       | string      | 0x02
27array           | *any value*                       | document    | 0x04
28object          | *any value*                       | document    | 0x03
29binary          | *any value*                       | binary      | 0x05
30
31!!! warning "Incomplete mapping"
32
33    The mapping is **incomplete**, since only JSON-objects (and things
34    contained therein) can be serialized to BSON.
35    Also, integers larger than 9223372036854775807 cannot be serialized to BSON,
36    and the keys may not contain U+0000, since they are serialized a
37    zero-terminated c-strings.
38
39??? example
40
41    ```cpp
42    --8<-- "examples/to_bson.cpp"
43    ```
44
45    Output:
46
47    ```c
48    --8<-- "examples/to_bson.output"
49    ```
50
51
52## Deserialization
53
54The library maps BSON record types to JSON value types as follows:
55
56BSON type       | BSON marker byte | JSON value type
57--------------- | ---------------- | ---------------------------
58double          | 0x01             | number_float
59string          | 0x02             | string
60document        | 0x03             | object
61array           | 0x04             | array
62binary          | 0x05             | binary
63undefined       | 0x06             | *unsupported*
64ObjectId        | 0x07             | *unsupported*
65boolean         | 0x08             | boolean
66UTC Date-Time   | 0x09             | *unsupported*
67null            | 0x0A             | null
68Regular Expr.   | 0x0B             | *unsupported*
69DB Pointer      | 0x0C             | *unsupported*
70JavaScript Code | 0x0D             | *unsupported*
71Symbol          | 0x0E             | *unsupported*
72JavaScript Code | 0x0F             | *unsupported*
73int32           | 0x10             | number_integer
74Timestamp       | 0x11             | *unsupported*
75128-bit decimal float | 0x13       | *unsupported*
76Max Key         | 0x7F             | *unsupported*
77Min Key         | 0xFF             | *unsupported*
78
79!!! warning "Incomplete mapping"
80
81    The mapping is **incomplete**. The unsupported mappings are indicated in the table above.
82
83
84??? example
85
86    ```cpp
87    --8<-- "examples/from_bson.cpp"
88    ```
89
90    Output:
91
92    ```json
93    --8<-- "examples/from_bson.output"
94    ```
95