3 * @brief BSON Declarations
6 /* Copyright 2009-2012 10gen Inc.
7 * Copyright (C) 2012-2015 Softmotions Ltd <info@softmotions.com>
9 * Licensed under the Apache License, Version 2.0 (the "License");
10 * you may not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
13 * http://www.apache.org/licenses/LICENSE-2.0
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS,
17 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
28 #if ! defined(__cplusplus)
34 #define BSON_IS_NUM_TYPE(atype) (atype == BSON_INT || atype == BSON_LONG || atype == BSON_DOUBLE)
35 #define BSON_IS_STRING_TYPE(atype) ((atype) == BSON_STRING || (atype) == BSON_SYMBOL)
42 //Maximum field path length allocated on stack
43 #define BSON_MAX_FPATH_LEN (255)
46 BSON_SIZE_OVERFLOW = 1 /**< Trying to create a BSON object larger than INT_MAX. */
49 enum bson_validity_t {
50 BSON_VALID = 0, /**< BSON is valid and UTF-8 compliant. */
51 BSON_NOT_UTF8 = (1 << 1), /**< A key or a string is not valid UTF-8. */
52 BSON_FIELD_HAS_DOT = (1 << 2), /**< Warning: key contains '.' character. */
53 BSON_FIELD_INIT_DOLLAR = (1 << 3), /**< Warning: key starts with '$' character. */
54 BSON_ALREADY_FINISHED = (1 << 4), /**< Trying to modify a finished BSON object. */
55 BSON_ERROR_ANY = (1 << 5) /**< Unspecified error */
58 enum bson_binary_subtype_t {
61 BSON_BIN_BINARY_OLD = 2,
68 BSON_FLAG_QUERY_MODE = 1,
69 BSON_FLAG_STACK_ALLOCATED = 1 << 1 /**< If it set BSON data is allocated on stack and realloc should deal with this case */
85 BSON_DBREF = 12, /**< Deprecated. */
94 typedef int bson_bool_t;
102 char *data; /**< Pointer to a block of data in this BSON object. */
103 char *cur; /**< Pointer to the current position. */
104 int dataSize; /**< The number of bytes allocated to char *data. */
105 bson_bool_t finished; /**< When finished, the BSON object can no longer be modified. */
106 int stack[32]; /**< A stack used to keep track of nested BSON elements. */
107 int stackPos; /**< Index of current stack position. */
108 int err; /**< Bitfield representing errors or warnings on this buffer */
109 char *errstr; /**< A string representation of the most recent error or warning. */
121 typedef int64_t bson_date_t; /* milliseconds since epoch UTC */
124 int i; /* increment */
125 int t; /* time in seconds */
129 EJDB_EXPORT const char* bson_first_errormsg(bson *bson);
132 #define BSON_ITERATOR_FROM_BUFFER(_bs_I, _bs_B) \
133 (_bs_I)->cur = ((char*) (_bs_B)) + 4; \
136 #define BSON_ITERATOR_SUBITERATOR(_bs_I, _bs_S) \
137 BSON_ITERATOR_FROM_BUFFER((_bs_S), bson_iterator_value(_bs_I))
139 #define BSON_ITERATOR_TYPE(_bs_I) \
140 ((bson_type) (_bs_I)->cur[0])
142 #define BSON_ITERATOR_KEY(_bs_I) \
145 #define BSON_ITERATOR_INIT(_bs_I, _bs) \
146 (_bs_I)->cur = (_bs)->data + 4; \
149 /* ----------------------------
151 ------------------------------ */
153 EJDB_EXPORT bson* bson_create(void);
154 EJDB_EXPORT void bson_dispose(bson* b);
157 * Size of a BSON object.
159 * @param b the BSON object.
163 EJDB_EXPORT int bson_size(const bson *b);
164 EJDB_EXPORT int bson_size2(const void *bsdata);
165 EJDB_EXPORT int bson_buffer_size(const bson *b);
168 * Return a pointer to the raw buffer stored by this bson object.
170 * @param b a BSON object
172 EJDB_EXPORT const char *bson_data(const bson *b);
173 EJDB_EXPORT const char* bson_data2(const bson *b, int *bsize);
176 * Print a string representation of a BSON object.
178 * @param bson the raw data to print.
179 * @param depth the depth to recurse the object.x
181 EJDB_EXPORT void bson_print_raw(const char *bson, int depth);
184 * Advance a bson_iterator to the named field.
186 * @param it the bson_iterator to use.
187 * @param obj the BSON object to use.
188 * @param name the name of the field to find.
190 * @return the type of the found object or BSON_EOO if it is not found.
192 EJDB_EXPORT bson_type bson_find(bson_iterator *it, const bson *obj, const char *name);
194 EJDB_EXPORT bson_type bson_find_from_buffer(bson_iterator *it, const char *buffer, const char *name);
196 typedef struct { /**< Find field path context */
199 bson_iterator *input;
202 int mpos; /**< Array index of the first matched array field */
203 int dpos; /**< Position of `$` in array projection fieldpath. */
208 * Advance specified iterator 'it' to field value pointing by 'fieldpath'/
209 * Field path string format: 'field1.nestedfield1.nestedfield.2'.
210 * If specified field not found BSON_EOO will be returned.
212 * @param fieldpath Path specification to the BSON field.
213 * @param it the bson_iterator to use.
214 * @return the type of the found object or BSON_EOO if it is not found.
216 EJDB_EXPORT bson_type bson_find_fieldpath_value(const char *fieldpath, bson_iterator *it);
217 EJDB_EXPORT bson_type bson_find_fieldpath_value2(const char *fpath, int fplen, bson_iterator *it);
218 EJDB_EXPORT bson_type bson_find_fieldpath_value3(FFPCTX* ffctx);
221 * BSON object visitor
222 * @param it bson iterator to traverse
223 * @param visitor Visitor function
224 * @param op Opaque data for visitor
227 BSON_TRAVERSE_ARRAYS_EXCLUDED = 1,
228 BSON_TRAVERSE_OBJECTS_EXCLUDED = 1 << 1
229 } bson_traverse_flags_t;
233 BSON_VCMD_TERMINATE = 1,
234 BSON_VCMD_SKIP_NESTED = 1 << 1,
235 BSON_VCMD_SKIP_AFTER = 1 << 2
236 } bson_visitor_cmd_t;
237 typedef bson_visitor_cmd_t(*BSONVISITOR)(const char *ipath, int ipathlen, const char *key, int keylen, const bson_iterator *it, bool after, void *op);
238 EJDB_EXPORT void bson_visit_fields(bson_iterator *it, bson_traverse_flags_t flags, BSONVISITOR visitor, void *op);
241 EJDB_EXPORT bson_iterator* bson_iterator_create(void);
242 EJDB_EXPORT void bson_iterator_dispose(bson_iterator*);
244 * Initialize a bson_iterator.
246 * @param i the bson_iterator to initialize.
247 * @param bson the BSON object to associate with the iterator.
249 EJDB_EXPORT void bson_iterator_init(bson_iterator *i, const bson *b);
252 * Initialize a bson iterator from a const char* buffer. Note
253 * that this is mostly used internally.
255 * @param i the bson_iterator to initialize.
256 * @param buffer the buffer to point to.
258 EJDB_EXPORT void bson_iterator_from_buffer(bson_iterator *i, const char *buffer);
260 /* more returns true for eoo. best to loop with bson_iterator_next(&it) */
262 * Check to see if the bson_iterator has more data.
264 * @param i the iterator.
266 * @return returns true if there is more data.
268 EJDB_EXPORT bson_bool_t bson_iterator_more(const bson_iterator *i);
271 * Point the iterator at the next BSON object.
273 * @param i the bson_iterator.
275 * @return the type of the next BSON object.
277 EJDB_EXPORT bson_type bson_iterator_next(bson_iterator *i);
280 * Get the type of the BSON object currently pointed to by the iterator.
282 * @param i the bson_iterator
284 * @return the type of the current BSON object.
286 EJDB_EXPORT bson_type bson_iterator_type(const bson_iterator *i);
289 * Get the key of the BSON object currently pointed to by the iterator.
291 * @param i the bson_iterator
293 * @return the key of the current BSON object.
295 EJDB_EXPORT const char *bson_iterator_key(const bson_iterator *i);
298 * Get the value of the BSON object currently pointed to by the iterator.
300 * @param i the bson_iterator
302 * @return the value of the current BSON object.
304 EJDB_EXPORT const char *bson_iterator_value(const bson_iterator *i);
306 /* these convert to the right type (return 0 if non-numeric) */
308 * Get the double value of the BSON object currently pointed to by the
311 * @param i the bson_iterator
313 * @return the value of the current BSON object.
315 EJDB_EXPORT double bson_iterator_double(const bson_iterator *i);
318 * Get the int value of the BSON object currently pointed to by the iterator.
320 * @param i the bson_iterator
322 * @return the value of the current BSON object.
324 EJDB_EXPORT int bson_iterator_int(const bson_iterator *i);
327 * Get the long value of the BSON object currently pointed to by the iterator.
329 * @param i the bson_iterator
331 * @return the value of the current BSON object.
333 EJDB_EXPORT int64_t bson_iterator_long(const bson_iterator *i);
335 /* return the bson timestamp as a whole or in parts */
337 * Get the timestamp value of the BSON object currently pointed to by
340 * @param i the bson_iterator
342 * @return the value of the current BSON object.
344 EJDB_EXPORT bson_timestamp_t bson_iterator_timestamp(const bson_iterator *i);
345 EJDB_EXPORT int bson_iterator_timestamp_time(const bson_iterator *i);
346 EJDB_EXPORT int bson_iterator_timestamp_increment(const bson_iterator *i);
349 * Get the boolean value of the BSON object currently pointed to by
352 * @param i the bson_iterator
354 * @return the value of the current BSON object.
356 /* false: boolean false, 0 in any type, or null */
357 /* true: anything else (even empty strings and objects) */
358 EJDB_EXPORT bson_bool_t bson_iterator_bool(const bson_iterator *i);
361 * Get the double value of the BSON object currently pointed to by the
362 * iterator. Assumes the correct type is used.
364 * @param i the bson_iterator
366 * @return the value of the current BSON object.
368 /* these assume you are using the right type */
369 EJDB_EXPORT double bson_iterator_double_raw(const bson_iterator *i);
372 * Get the int value of the BSON object currently pointed to by the
373 * iterator. Assumes the correct type is used.
375 * @param i the bson_iterator
377 * @return the value of the current BSON object.
379 EJDB_EXPORT int bson_iterator_int_raw(const bson_iterator *i);
382 * Get the long value of the BSON object currently pointed to by the
383 * iterator. Assumes the correct type is used.
385 * @param i the bson_iterator
387 * @return the value of the current BSON object.
389 EJDB_EXPORT int64_t bson_iterator_long_raw(const bson_iterator *i);
392 * Get the bson_bool_t value of the BSON object currently pointed to by the
393 * iterator. Assumes the correct type is used.
395 * @param i the bson_iterator
397 * @return the value of the current BSON object.
399 EJDB_EXPORT bson_bool_t bson_iterator_bool_raw(const bson_iterator *i);
402 * Get the bson_oid_t value of the BSON object currently pointed to by the
405 * @param i the bson_iterator
407 * @return the value of the current BSON object.
409 EJDB_EXPORT bson_oid_t *bson_iterator_oid(const bson_iterator *i);
412 * Get the string value of the BSON object currently pointed to by the
415 * @param i the bson_iterator
417 * @return the value of the current BSON object.
419 /* these can also be used with bson_code and bson_symbol*/
420 EJDB_EXPORT const char *bson_iterator_string(const bson_iterator *i);
423 * Get the string length of the BSON object currently pointed to by the
426 * @param i the bson_iterator
428 * @return the length of the current BSON object.
430 EJDB_EXPORT int bson_iterator_string_len(const bson_iterator *i);
433 * Get the code value of the BSON object currently pointed to by the
434 * iterator. Works with bson_code, bson_codewscope, and BSON_STRING
435 * returns NULL for everything else.
437 * @param i the bson_iterator
439 * @return the code value of the current BSON object.
441 /* works with bson_code, bson_codewscope, and BSON_STRING */
442 /* returns NULL for everything else */
443 EJDB_EXPORT const char *bson_iterator_code(const bson_iterator *i);
446 * Calls bson_empty on scope if not a bson_codewscope
448 * @param i the bson_iterator.
449 * @param scope the bson scope.
451 /* calls bson_empty on scope if not a bson_codewscope */
452 EJDB_EXPORT void bson_iterator_code_scope(const bson_iterator *i, bson *scope);
455 * Get the date value of the BSON object currently pointed to by the
458 * @param i the bson_iterator
460 * @return the date value of the current BSON object.
462 /* both of these only work with bson_date */
463 EJDB_EXPORT bson_date_t bson_iterator_date(const bson_iterator *i);
466 * Get the time value of the BSON object currently pointed to by the
469 * @param i the bson_iterator
471 * @return the time value of the current BSON object.
473 EJDB_EXPORT time_t bson_iterator_time_t(const bson_iterator *i);
476 * Get the length of the BSON binary object currently pointed to by the
479 * @param i the bson_iterator
481 * @return the length of the current BSON binary object.
483 EJDB_EXPORT int bson_iterator_bin_len(const bson_iterator *i);
486 * Get the type of the BSON binary object currently pointed to by the
489 * @param i the bson_iterator
491 * @return the type of the current BSON binary object.
493 EJDB_EXPORT char bson_iterator_bin_type(const bson_iterator *i);
496 * Get the value of the BSON binary object currently pointed to by the
499 * @param i the bson_iterator
501 * @return the value of the current BSON binary object.
503 EJDB_EXPORT const char *bson_iterator_bin_data(const bson_iterator *i);
506 * Get the value of the BSON regex object currently pointed to by the
509 * @param i the bson_iterator
511 * @return the value of the current BSON regex object.
513 EJDB_EXPORT const char *bson_iterator_regex(const bson_iterator *i);
516 * Get the options of the BSON regex object currently pointed to by the
519 * @param i the bson_iterator.
521 * @return the options of the current BSON regex object.
523 EJDB_EXPORT const char *bson_iterator_regex_opts(const bson_iterator *i);
525 /* these work with BSON_OBJECT and BSON_ARRAY */
527 * Get the BSON subobject currently pointed to by the
530 * @param i the bson_iterator.
531 * @param sub the BSON subobject destination.
533 EJDB_EXPORT void bson_iterator_subobject(const bson_iterator *i, bson *sub);
536 * Get a bson_iterator that on the BSON subobject.
538 * @param i the bson_iterator.
539 * @param sub the iterator to point at the BSON subobject.
541 EJDB_EXPORT void bson_iterator_subiterator(const bson_iterator *i, bson_iterator *sub);
543 /* str must be at least 24 hex chars + null byte */
545 * Create a bson_oid_t from a string.
547 * @param oid the bson_oid_t destination.
548 * @param str a null terminated string comprised of at least 24 hex chars.
550 EJDB_EXPORT void bson_oid_from_string(bson_oid_t *oid, const char *str);
553 * Create a string representation of the bson_oid_t.
555 * @param oid the bson_oid_t source.
556 * @param str the string representation destination.
558 EJDB_EXPORT void bson_oid_to_string(const bson_oid_t *oid, char *str);
561 * Create a bson_oid object.
563 * @param oid the destination for the newly created bson_oid_t.
565 EJDB_EXPORT void bson_oid_gen(bson_oid_t *oid);
568 * Set a function to be used to generate the second four bytes
571 * @param func a pointer to a function that returns an int.
573 EJDB_EXPORT void bson_set_oid_fuzz(int ( *func)(void));
576 * Set a function to be used to generate the incrementing part
577 * of an object id (last four bytes). If you need thread-safety
578 * in generating object ids, you should set this function.
580 * @param func a pointer to a function that returns an int.
582 EJDB_EXPORT void bson_set_oid_inc(int ( *func)(void));
585 * Get the time a bson_oid_t was created.
587 * @param oid the bson_oid_t.
589 EJDB_EXPORT time_t bson_oid_generated_time(bson_oid_t *oid); /* Gives the time the OID was created */
591 /* ----------------------------
593 ------------------------------ */
596 EJDB_EXPORT void bson_append(bson *b, const void *data, int len);
599 * Initialize a new bson object. If not created
600 * with bson_new, you must initialize each new bson
601 * object using this function.
603 * @note When finished, you must pass the bson object to
606 EJDB_EXPORT void bson_init(bson *b);
610 * Intialize a new bson object. In query contruction mode allowing
611 * dot and dollar chars in field names.
614 EJDB_EXPORT void bson_init_as_query(bson *b);
617 * Initialize a BSON object, and point its data
618 * pointer to the provided char*.
620 * @param b the BSON object to initialize.
621 * @param data the raw BSON data.
623 * @return BSON_OK or BSON_ERROR.
625 EJDB_EXPORT int bson_init_data(bson *b, char *data);
626 EJDB_EXPORT int bson_init_finished_data(bson *b, const char *data);
629 * Initialize a BSON object, and set its
630 * buffer to the given size.
632 * @param b the BSON object to initialize.
633 * @param size the initial size of the buffer.
635 * @return BSON_OK or BSON_ERROR.
637 EJDB_EXPORT void bson_init_size(bson *b, int size);
639 EJDB_EXPORT void bson_init_on_stack(bson *b, char *bstack, int mincapacity, int maxonstack);
642 * Grow a bson object.
644 * @param b the bson to grow.
645 * @param bytesNeeded the additional number of bytes needed.
647 * @return BSON_OK or BSON_ERROR with the bson error object set.
648 * Exits if allocation fails.
650 EJDB_EXPORT int bson_ensure_space(bson *b, const int bytesNeeded);
653 * Finalize a bson object.
655 * @param b the bson object to finalize.
657 * @return the standard error code. To deallocate memory,
658 * call bson_del on the bson object.
660 EJDB_EXPORT int bson_finish(bson *b);
663 * Destroy a bson object.
664 * Clears bson object and frees internal memory buffers held by bson
665 * object BUT does not delete bson object itself
666 * @param b the bson object to destroy.
668 EJDB_EXPORT void bson_destroy(bson *b);
671 * The bson_del() performs bson_destroy() then frees bson object itself.
674 EJDB_EXPORT void bson_del(bson *b);
676 EJDB_EXPORT void bson_reset(bson *b);
679 * Returns a pointer to a static empty BSON object.
681 * @param obj the BSON object to initialize.
683 * @return the empty initialized BSON object.
685 /* returns pointer to static empty bson object */
686 EJDB_EXPORT bson *bson_empty(bson *obj);
689 * Make a complete copy of the a BSON object.
690 * The source bson object must be in a finished
691 * state; otherwise, the copy will fail.
693 * @param out the copy destination BSON object.
694 * @param in the copy source BSON object.
696 EJDB_EXPORT int bson_copy(bson *out, const bson *in); /* puts data in new buffer. NOOP if out==NULL */
699 * Append a previously created bson_oid_t to a bson object.
701 * @param b the bson to append to.
702 * @param name the key for the bson_oid_t.
703 * @param oid the bson_oid_t to append.
705 * @return BSON_OK or BSON_ERROR.
707 EJDB_EXPORT int bson_append_oid(bson *b, const char *name, const bson_oid_t *oid);
710 * Append a bson_oid_t to a bson.
712 * @param b the bson to append to.
713 * @param name the key for the bson_oid_t.
715 * @return BSON_OK or BSON_ERROR.
717 EJDB_EXPORT int bson_append_new_oid(bson *b, const char *name);
720 * Append an int to a bson.
722 * @param b the bson to append to.
723 * @param name the key for the int.
724 * @param i the int to append.
726 * @return BSON_OK or BSON_ERROR.
728 EJDB_EXPORT int bson_append_int(bson *b, const char *name, const int i);
731 * Append an long to a bson.
733 * @param b the bson to append to.
734 * @param name the key for the long.
735 * @param i the long to append.
737 * @return BSON_OK or BSON_ERROR.
739 EJDB_EXPORT int bson_append_long(bson *b, const char *name, const int64_t i);
742 * Append an double to a bson.
744 * @param b the bson to append to.
745 * @param name the key for the double.
746 * @param d the double to append.
748 * @return BSON_OK or BSON_ERROR.
750 EJDB_EXPORT int bson_append_double(bson *b, const char *name, const double d);
753 * Append a string to a bson.
755 * @param b the bson to append to.
756 * @param name the key for the string.
757 * @param str the string to append.
759 * @return BSON_OK or BSON_ERROR.
761 EJDB_EXPORT int bson_append_string(bson *b, const char *name, const char *str);
764 * Append len bytes of a string to a bson.
766 * @param b the bson to append to.
767 * @param name the key for the string.
768 * @param str the string to append.
769 * @param len the number of bytes from str to append.
771 * @return BSON_OK or BSON_ERROR.
773 EJDB_EXPORT int bson_append_string_n(bson *b, const char *name, const char *str, int len);
776 * Append a symbol to a bson.
778 * @param b the bson to append to.
779 * @param name the key for the symbol.
780 * @param str the symbol to append.
782 * @return BSON_OK or BSON_ERROR.
784 EJDB_EXPORT int bson_append_symbol(bson *b, const char *name, const char *str);
787 * Append len bytes of a symbol to a bson.
789 * @param b the bson to append to.
790 * @param name the key for the symbol.
791 * @param str the symbol to append.
792 * @param len the number of bytes from str to append.
794 * @return BSON_OK or BSON_ERROR.
796 EJDB_EXPORT int bson_append_symbol_n(bson *b, const char *name, const char *str, int len);
799 * Append code to a bson.
801 * @param b the bson to append to.
802 * @param name the key for the code.
803 * @param str the code to append.
804 * @param len the number of bytes from str to append.
806 * @return BSON_OK or BSON_ERROR.
808 EJDB_EXPORT int bson_append_code(bson *b, const char *name, const char *str);
811 * Append len bytes of code to a bson.
813 * @param b the bson to append to.
814 * @param name the key for the code.
815 * @param str the code to append.
816 * @param len the number of bytes from str to append.
818 * @return BSON_OK or BSON_ERROR.
820 EJDB_EXPORT int bson_append_code_n(bson *b, const char *name, const char *str, int len);
823 * Append code to a bson with scope.
825 * @param b the bson to append to.
826 * @param name the key for the code.
827 * @param str the string to append.
828 * @param scope a BSON object containing the scope.
830 * @return BSON_OK or BSON_ERROR.
832 EJDB_EXPORT int bson_append_code_w_scope(bson *b, const char *name, const char *code, const bson *scope);
835 * Append len bytes of code to a bson with scope.
837 * @param b the bson to append to.
838 * @param name the key for the code.
839 * @param str the string to append.
840 * @param len the number of bytes from str to append.
841 * @param scope a BSON object containing the scope.
843 * @return BSON_OK or BSON_ERROR.
845 EJDB_EXPORT int bson_append_code_w_scope_n(bson *b, const char *name, const char *code, int size, const bson *scope);
848 * Append binary data to a bson.
850 * @param b the bson to append to.
851 * @param name the key for the data.
852 * @param type the binary data type.
853 * @param str the binary data.
854 * @param len the length of the data.
856 * @return BSON_OK or BSON_ERROR.
858 EJDB_EXPORT int bson_append_binary(bson *b, const char *name, char type, const char *str, int len);
861 * Append a bson_bool_t to a bson.
863 * @param b the bson to append to.
864 * @param name the key for the boolean value.
865 * @param v the bson_bool_t to append.
867 * @return BSON_OK or BSON_ERROR.
869 EJDB_EXPORT int bson_append_bool(bson *b, const char *name, const bson_bool_t v);
872 * Append a null value to a bson.
874 * @param b the bson to append to.
875 * @param name the key for the null value.
877 * @return BSON_OK or BSON_ERROR.
879 EJDB_EXPORT int bson_append_null(bson *b, const char *name);
882 * Append an undefined value to a bson.
884 * @param b the bson to append to.
885 * @param name the key for the undefined value.
887 * @return BSON_OK or BSON_ERROR.
889 EJDB_EXPORT int bson_append_undefined(bson *b, const char *name);
892 * Append a regex value to a bson.
894 * @param b the bson to append to.
895 * @param name the key for the regex value.
896 * @param pattern the regex pattern to append.
897 * @param the regex options.
899 * @return BSON_OK or BSON_ERROR.
901 EJDB_EXPORT int bson_append_regex(bson *b, const char *name, const char *pattern, const char *opts);
904 * Append bson data to a bson.
906 * @param b the bson to append to.
907 * @param name the key for the bson data.
908 * @param bson the bson object to append.
910 * @return BSON_OK or BSON_ERROR.
912 EJDB_EXPORT int bson_append_bson(bson *b, const char *name, const bson *bson);
915 * Append a BSON element to a bson from the current point of an iterator.
917 * @param b the bson to append to.
918 * @param name_or_null the key for the BSON element, or NULL.
919 * @param elem the bson_iterator.
921 * @return BSON_OK or BSON_ERROR.
923 EJDB_EXPORT int bson_append_element(bson *b, const char *name_or_null, const bson_iterator *elem);
926 * Append a bson_timestamp_t value to a bson.
928 * @param b the bson to append to.
929 * @param name the key for the timestampe value.
930 * @param ts the bson_timestamp_t value to append.
932 * @return BSON_OK or BSON_ERROR.
934 EJDB_EXPORT int bson_append_timestamp(bson *b, const char *name, bson_timestamp_t *ts);
935 EJDB_EXPORT int bson_append_timestamp2(bson *b, const char *name, int time, int increment);
937 /* these both append a bson_date */
939 * Append a bson_date_t value to a bson.
941 * @param b the bson to append to.
942 * @param name the key for the date value.
943 * @param millis the bson_date_t to append.
945 * @return BSON_OK or BSON_ERROR.
947 EJDB_EXPORT int bson_append_date(bson *b, const char *name, bson_date_t millis);
950 * Append a time_t value to a bson.
952 * @param b the bson to append to.
953 * @param name the key for the date value.
954 * @param secs the time_t to append.
956 * @return BSON_OK or BSON_ERROR.
958 EJDB_EXPORT int bson_append_time_t(bson *b, const char *name, time_t secs);
961 * Start appending a new object to a bson.
963 * @param b the bson to append to.
964 * @param name the name of the new object.
966 * @return BSON_OK or BSON_ERROR.
968 EJDB_EXPORT int bson_append_start_object(bson *b, const char *name);
969 EJDB_EXPORT int bson_append_start_object2(bson *b, const char *name, int namelen);
972 * Start appending a new array to a bson.
974 * @param b the bson to append to.
975 * @param name the name of the new array.
977 * @return BSON_OK or BSON_ERROR.
979 EJDB_EXPORT int bson_append_start_array(bson *b, const char *name);
980 EJDB_EXPORT int bson_append_start_array2(bson *b, const char *name, int namelen);
983 * Finish appending a new object or array to a bson.
985 * @param b the bson to append to.
987 * @return BSON_OK or BSON_ERROR.
989 EJDB_EXPORT int bson_append_finish_object(bson *b);
992 * Finish appending a new object or array to a bson. This
993 * is simply an alias for bson_append_finish_object.
995 * @param b the bson to append to.
997 * @return BSON_OK or BSON_ERROR.
999 EJDB_EXPORT int bson_append_finish_array(bson *b);
1001 EJDB_EXPORT void bson_numstr(char *str, int64_t i);
1002 EJDB_EXPORT int bson_numstrn(char *str, int maxbuf, int64_t i);
1004 //void bson_incnumstr(char *str);
1006 /* Error handling and standard library function over-riding. */
1007 /* -------------------------------------------------------- */
1009 /* bson_err_handlers shouldn't return!!! */
1010 typedef void( *bson_err_handler)(const char *errmsg);
1011 typedef int (*bson_printf_func)(const char *, ...);
1013 extern void *(*bson_malloc_func)(size_t);
1014 extern void *(*bson_realloc_func)(void *, size_t);
1015 extern void ( *bson_free_func)(void *);
1017 extern bson_printf_func bson_errprintf;
1019 void bson_free(void *ptr);
1022 * Allocates memory and checks return value, exiting fatally if malloc() fails.
1024 * @param size bytes to allocate.
1026 * @return a pointer to the allocated memory.
1030 void *bson_malloc(int size);
1033 * Changes the size of allocated memory and checks return value,
1034 * exiting fatally if realloc() fails.
1036 * @param ptr pointer to the space to reallocate.
1037 * @param size bytes to allocate.
1039 * @return a pointer to the allocated memory.
1043 void *bson_realloc(void *ptr, int size);
1046 * Set a function for error handling.
1048 * @param func a bson_err_handler function.
1050 * @return the old error handling function, or NULL.
1052 EJDB_EXPORT bson_err_handler set_bson_err_handler(bson_err_handler func);
1054 /* does nothing if ok != 0 */
1058 * @param ok exits if ok is equal to 0.
1060 void bson_fatal(int ok);
1063 * Exit fatally with an error message.
1065 * @param ok exits if ok is equal to 0.
1066 * @param msg prints to stderr before exiting.
1068 void bson_fatal_msg(int ok, const char *msg);
1071 * Invoke the error handler, but do not exit.
1073 * @param b the buffer object.
1075 void bson_builder_error(bson *b);
1078 * Cast an int64_t to double. This is necessary for embedding in
1079 * certain environments.
1082 EJDB_EXPORT double bson_int64_to_double(int64_t i64);
1083 EJDB_EXPORT void bson_swap_endian32(void *outp, const void *inp);
1084 EJDB_EXPORT void bson_swap_endian64(void *outp, const void *inp);
1088 * Append current field from iterator into bson object.
1092 * @return BSON_OK or BSON_ERROR.
1094 EJDB_EXPORT int bson_append_field_from_iterator(const bson_iterator *from, bson *into);
1097 * Append current field value from iterator into bson object under specified string key.
1099 * @param key Key name.
1100 * @param from Source iterator value
1101 * @param into Target bsob object
1102 * @return BSON_OK or BSON_ERROR.
1104 EJDB_EXPORT int bson_append_field_from_iterator2(const char *key, const bson_iterator *from, bson *into);
1105 EJDB_EXPORT int bson_append_object_from_iterator(const char *key, bson_iterator *from, bson *into);
1106 EJDB_EXPORT int bson_append_array_from_iterator(const char *key, bson_iterator *from, bson *into);
1110 * Merge bson `b2` into `b1` saving result the 'out' object.
1111 * `b1` & `b2` bson must be finished BSONS.
1112 * Resulting 'out' bson must be allocated and not finished.
1114 * Nested object skipped and usupported.
1116 * @param b1 BSON to to be merged in `out`
1117 * @param b2 Second BSON to to be merged in `out`
1118 * @param overwrite if `true` all `b1` fields will be overwriten by corresponding `b2` fields
1121 * @return BSON_OK or BSON_ERROR.
1123 EJDB_EXPORT int bson_merge(const bson *b1, const bson *b2, bson_bool_t overwrite, bson *out);
1124 EJDB_EXPORT int bson_merge2(const void *b1data, const void *b2data, bson_bool_t overwrite, bson *out);
1127 * Recursive merge bson `b2` into `b1` saving result the 'out' object.
1128 * `b1` & `b2` bson must be finished BSONS.
1129 * Resulting 'out' bson must be allocated and not finished.
1131 * NOTE. Arrays with same paths joined.
1133 * @param b1 BSON to to be merged in `out`
1134 * @param b2 Second BSON to to be merged in `out`
1135 * @param overwrite if `true` all `b1` fields will be overwriten by corresponding `b2` fields
1138 * @return BSON_OK or BSON_ERROR.
1140 EJDB_EXPORT int bson_merge_recursive(const bson *b1, const bson *b2, bson_bool_t overwrite, bson *out);
1141 EJDB_EXPORT int bson_merge_recursive2(const void *b1data, const void *b2data, bson_bool_t overwrite, bson *out);
1145 * `bsdata2` may contain field path keys (eg: 'foo.bar').
1146 * @param bsdata1 BSON data to to be merged in `out`
1147 * @param bsdata2 Second BSON data to to be merged in `out`
1148 * @param out Resulting `out` bson must be allocated and not finished.
1150 * @return BSON_OK or BSON_ERROR.
1152 EJDB_EXPORT int bson_merge3(const void *bsdata1, const void *bsdata2, bson *out);
1154 EJDB_EXPORT int bson_inplace_set_bool(bson_iterator *pos, bson_bool_t val);
1155 EJDB_EXPORT int bson_inplace_set_long(bson_iterator *pos, int64_t val);
1156 EJDB_EXPORT int bson_inplace_set_double(bson_iterator *pos, double val);
1159 TCMAP *ifields; //Required Map of fieldpaths. Map values are a simple boolean bufs.
1160 bool imode; //Required If true fpaths will be included. Otherwise fpaths will be excluded from bson.
1161 const void *bsbuf; //Required BSON buffer to process.
1162 bson *bsout; //Required Allocated output not finished bson* object.
1163 TCMAP *fkfields; //Optional: Map (fpath => bson key) used to force specific bson keys for selected fpaths.
1167 * Include or exclude fpaths in the specified BSON and put resulting data into `bsout`.
1168 * On completion it finishes `bsout` object.
1170 * @param ifields Map of fieldpaths. Map values are a simple boolean bufs.
1171 * @param imode If true fpaths will be included. Otherwise fpaths will be excluded from bson.
1172 * @param bsbuf BSON buffer to process.
1173 * @param bsout Allocated output not finished bson* object
1174 * @return BSON error code
1176 EJDB_EXPORT int bson_strip(TCMAP *ifields, bool imode, const void *bsbuf, bson *bsout);
1177 EJDB_EXPORT int bson_strip2(BSONSTRIPCTX *sctx);
1181 * Compares field path primitive values of two BSONs
1182 * @param bsdata1 BSON raw data
1183 * @param bsdata2 BSON raw data
1184 * @param fpath Field path to the field
1185 * @param fplen Length of fpath value
1187 EJDB_EXPORT int bson_compare(const void *bsdata1, const void *bsdata2, const char* fpath, int fplen);
1188 EJDB_EXPORT int bson_compare_fpaths(const void *bsdata1, const void *bsdata2, const char *fpath1, int fplen1, const char *fpath2, int fplen2);
1189 EJDB_EXPORT int bson_compare_it_current(const bson_iterator *it1, const bson_iterator *it2);
1190 EJDB_EXPORT int bson_compare_string(const char* cv, const void *bsdata, const char *fpath);
1191 EJDB_EXPORT int bson_compare_long(const int64_t cv, const void *bsdata, const char *fpath);
1192 EJDB_EXPORT int bson_compare_double(double cv, const void *bsdata, const char *fpath);
1193 EJDB_EXPORT int bson_compare_bool(bson_bool_t cv, const void *bsdata, const char *fpath);
1197 * Duplicates BSON object.
1199 * @return Finished copy of src
1201 EJDB_EXPORT bson* bson_dup(const bson *src);
1204 EJDB_EXPORT bson* bson_create_from_iterator(bson_iterator *from);
1205 EJDB_EXPORT bson* bson_create_from_buffer(const void *buf, int bufsz);
1206 EJDB_EXPORT bson* bson_create_from_buffer2(bson *bs, const void *buf, int bufsz);
1207 EJDB_EXPORT void bson_init_with_data(bson *bs, const void *bsdata);
1209 EJDB_EXPORT bool bson_find_unmerged_array_sets(const void *mbuf, const void *inbuf);
1210 EJDB_EXPORT bool bson_find_merged_array_sets(const void *mbuf, const void *inbuf, bool expandall);
1211 EJDB_EXPORT int bson_merge_array_sets(const void *mbuf, const void *inbuf, bool pull, bool expandall, bson *bsout);
1215 * Convert BSON into JSON buffer.
1217 * A caller should free an allocated `*buf`
1218 * if value of `*buf` is not `NULL` after function completion.
1220 * @param src BSON data
1221 * @param buf Allocated buffer with resulting JSON data
1222 * @param sp JSON data length will be stored into
1223 * @return BSON_OK or BSON_ERROR
1225 EJDB_EXPORT int bson2json(const char *bsdata, char **buf, int *sp);
1228 * Convert JSON into BSON object.
1229 * @param jsonstr NULL terminated JSON string
1230 * @return Allocated BSON object filled with given JSON data or NULL on error
1232 EJDB_EXPORT bson* json2bson(const char *jsonstr);