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