1:man_page: bson_t
2
3bson_t
4======
5
6BSON Document Abstraction
7
8Synopsis
9--------
10
11.. code-block:: c
12
13  #include <bson.h>
14
15  /**
16   * bson_empty:
17   * @b: a bson_t.
18   *
19   * Checks to see if @b is an empty BSON document. An empty BSON document is
20   * a 5 byte document which contains the length (4 bytes) and a single NUL
21   * byte indicating end of fields.
22   */
23  #define bson_empty(b) /* ... */
24
25  /**
26   * bson_empty0:
27   *
28   * Like bson_empty() but treats NULL the same as an empty bson_t document.
29   */
30  #define bson_empty0(b) /* ... */
31
32  /**
33   * bson_clear:
34   *
35   * Easily free a bson document and set it to NULL. Use like:
36   *
37   * bson_t *doc = bson_new();
38   * bson_clear (&doc);
39   * BSON_ASSERT (doc == NULL);
40   */
41  #define bson_clear(bptr) /* ... */
42
43  /**
44   * BSON_MAX_SIZE:
45   *
46   * The maximum size in bytes of a BSON document.
47   */
48  #define BSON_MAX_SIZE /* ... */
49
50  #define BSON_APPEND_ARRAY(b, key, val) \
51     bson_append_array (b, key, (int) strlen (key), val)
52
53  #define BSON_APPEND_ARRAY_BEGIN(b, key, child) \
54     bson_append_array_begin (b, key, (int) strlen (key), child)
55
56  #define BSON_APPEND_BINARY(b, key, subtype, val, len) \
57     bson_append_binary (b, key, (int) strlen (key), subtype, val, len)
58
59  #define BSON_APPEND_BOOL(b, key, val) \
60     bson_append_bool (b, key, (int) strlen (key), val)
61
62  #define BSON_APPEND_CODE(b, key, val) \
63     bson_append_code (b, key, (int) strlen (key), val)
64
65  #define BSON_APPEND_CODE_WITH_SCOPE(b, key, val, scope) \
66     bson_append_code_with_scope (b, key, (int) strlen (key), val, scope)
67
68  #define BSON_APPEND_DBPOINTER(b, key, coll, oid) \
69     bson_append_dbpointer (b, key, (int) strlen (key), coll, oid)
70
71  #define BSON_APPEND_DOCUMENT_BEGIN(b, key, child) \
72     bson_append_document_begin (b, key, (int) strlen (key), child)
73
74  #define BSON_APPEND_DOUBLE(b, key, val) \
75     bson_append_double (b, key, (int) strlen (key), val)
76
77  #define BSON_APPEND_DOCUMENT(b, key, val) \
78     bson_append_document (b, key, (int) strlen (key), val)
79
80  #define BSON_APPEND_INT32(b, key, val) \
81     bson_append_int32 (b, key, (int) strlen (key), val)
82
83  #define BSON_APPEND_INT64(b, key, val) \
84     bson_append_int64 (b, key, (int) strlen (key), val)
85
86  #define BSON_APPEND_MINKEY(b, key) \
87     bson_append_minkey (b, key, (int) strlen (key))
88
89  #define BSON_APPEND_DECIMAL128(b, key, val) \
90     bson_append_decimal128 (b, key, (int) strlen (key), val)
91
92  #define BSON_APPEND_MAXKEY(b, key) \
93     bson_append_maxkey (b, key, (int) strlen (key))
94
95  #define BSON_APPEND_NULL(b, key) bson_append_null (b, key, (int) strlen (key))
96
97  #define BSON_APPEND_OID(b, key, val) \
98     bson_append_oid (b, key, (int) strlen (key), val)
99
100  #define BSON_APPEND_REGEX(b, key, val, opt) \
101     bson_append_regex (b, key, (int) strlen (key), val, opt)
102
103  #define BSON_APPEND_UTF8(b, key, val) \
104     bson_append_utf8 (b, key, (int) strlen (key), val, (int) strlen (val))
105
106  #define BSON_APPEND_SYMBOL(b, key, val) \
107     bson_append_symbol (b, key, (int) strlen (key), val, (int) strlen (val))
108
109  #define BSON_APPEND_TIME_T(b, key, val) \
110     bson_append_time_t (b, key, (int) strlen (key), val)
111
112  #define BSON_APPEND_TIMEVAL(b, key, val) \
113     bson_append_timeval (b, key, (int) strlen (key), val)
114
115  #define BSON_APPEND_DATE_TIME(b, key, val) \
116     bson_append_date_time (b, key, (int) strlen (key), val)
117
118  #define BSON_APPEND_TIMESTAMP(b, key, val, inc) \
119     bson_append_timestamp (b, key, (int) strlen (key), val, inc)
120
121  #define BSON_APPEND_UNDEFINED(b, key) \
122     bson_append_undefined (b, key, (int) strlen (key))
123
124  #define BSON_APPEND_VALUE(b, key, val) \
125     bson_append_value (b, key, (int) strlen (key), (val))
126
127  BSON_ALIGNED_BEGIN (128)
128  typedef struct {
129     uint32_t flags;       /* Internal flags for the bson_t. */
130     uint32_t len;         /* Length of BSON data. */
131     uint8_t padding[120]; /* Padding for stack allocation. */
132  } bson_t BSON_ALIGNED_END (128);
133
134Description
135-----------
136
137The :symbol:`bson_t` structure represents a BSON document. This structure manages the underlying BSON encoded buffer. For mutable documents, it can append new data to the document.
138
139Performance Notes
140-----------------
141
142The :symbol:`bson_t` structure attempts to use an inline allocation within the structure to speed up performance of small documents. When this internal buffer has been exhausted, a heap allocated buffer will be dynamically allocated. Therefore, it is essential to call :symbol:`bson_destroy()` on allocated documents.
143
144.. only:: html
145
146  Functions
147  ---------
148
149  .. toctree::
150    :titlesonly:
151    :maxdepth: 1
152
153    bson_append_array
154    bson_append_array_begin
155    bson_append_array_end
156    bson_append_binary
157    bson_append_bool
158    bson_append_code
159    bson_append_code_with_scope
160    bson_append_date_time
161    bson_append_dbpointer
162    bson_append_decimal128
163    bson_append_document
164    bson_append_document_begin
165    bson_append_document_end
166    bson_append_double
167    bson_append_int32
168    bson_append_int64
169    bson_append_iter
170    bson_append_maxkey
171    bson_append_minkey
172    bson_append_now_utc
173    bson_append_null
174    bson_append_oid
175    bson_append_regex
176    bson_append_symbol
177    bson_append_time_t
178    bson_append_timestamp
179    bson_append_timeval
180    bson_append_undefined
181    bson_append_utf8
182    bson_append_value
183    bson_array_as_json
184    bson_as_canonical_extended_json
185    bson_as_json
186    bson_as_relaxed_extended_json
187    bson_compare
188    bson_concat
189    bson_copy
190    bson_copy_to
191    bson_copy_to_excluding
192    bson_copy_to_excluding_noinit
193    bson_count_keys
194    bson_destroy
195    bson_destroy_with_steal
196    bson_equal
197    bson_get_data
198    bson_has_field
199    bson_init
200    bson_init_from_json
201    bson_init_static
202    bson_new
203    bson_new_from_buffer
204    bson_new_from_data
205    bson_new_from_json
206    bson_reinit
207    bson_reserve_buffer
208    bson_sized_new
209    bson_steal
210    bson_validate
211    bson_validate_with_error
212
213Example
214-------
215
216.. code-block:: c
217
218  static void
219  create_on_heap (void)
220  {
221     bson_t *b = bson_new ();
222
223     BSON_APPEND_INT32 (b, "foo", 123);
224     BSON_APPEND_UTF8 (b, "bar", "foo");
225     BSON_APPEND_DOUBLE (b, "baz", 1.23f);
226
227     bson_destroy (b);
228  }
229
230