SequoiaDB
 All Classes Files Functions Variables Enumerations Enumerator
Classes | Macros | Typedefs | Enumerations | Functions | Variables
bson.h File Reference

BSON Declarations. More...

#include <time.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <stdarg.h>
#include "common_decimal.h"
#include <stdint.h>

Go to the source code of this file.

Classes

struct  bson_iterator
 
struct  bson
 
union  bson_oid_t
 
struct  bson_timestamp_t
 

Macros

#define SDB_EXPORT   __declspec(dllimport)
 
#define SDB_EXTERN_C_START
 
#define SDB_EXTERN_C_END
 
#define bson_little_endian64(out, in)   ( memcpy(out, in, 8) )
 
#define bson_little_endian32(out, in)   ( memcpy(out, in, 4) )
 
#define bson_little_endian16(out, in)   ( memcpy(out, in, 2) )
 
#define bson_big_endian64(out, in)   ( bson_swap_endian64(out, in) )
 
#define bson_big_endian32(out, in)   ( bson_swap_endian32(out, in) )
 
#define bson_big_endian16(out, in)   ( bson_swap_endian16(out, in) )
 
#define BSON_OK   0
 
#define BSON_ERROR   -1
 
#define BSON_MAX_STACK_SIZE   32
 

Typedefs

typedef int bson_bool_t
 
typedef int64_t bson_date_t
 
typedef void(* bson_err_handler )(const char *errmsg)
 
typedef int(* bson_printf_func )(const char *,...)
 
typedef int(* bson_fprintf_func )(FILE *, const char *,...)
 
typedef int(* bson_sprintf_func )(char *, const char *,...)
 
typedef void *(* bson_malloc_func_p )(size_t)
 
typedef void *(* bson_realloc_func_p )(void *, size_t)
 
typedef void(* bson_free_func_p )(void *)
 

Enumerations

enum  bson_error_t { BSON_SIZE_OVERFLOW = 1 }
 
enum  bson_validity_t {
  BSON_VALID = 0, BSON_NOT_UTF8 = ( 1<<1 ), BSON_FIELD_HAS_DOT = ( 1<<2 ), BSON_FIELD_INIT_DOLLAR = ( 1<<3 ),
  BSON_ALREADY_FINISHED = ( 1<<4 )
}
 
enum  bson_binary_subtype_t {
  BSON_BIN_BINARY = 0, BSON_BIN_FUNC = 1, BSON_BIN_BINARY_OLD = 2, BSON_BIN_UUID = 3,
  BSON_BIN_MD5 = 5, BSON_BIN_USER = 128
}
 
enum  bson_type {
  BSON_MINKEY = -1, BSON_EOO = 0, BSON_DOUBLE = 1, BSON_STRING = 2,
  BSON_OBJECT = 3, BSON_ARRAY = 4, BSON_BINDATA = 5, BSON_UNDEFINED = 6,
  BSON_OID = 7, BSON_BOOL = 8, BSON_DATE = 9, BSON_NULL = 10,
  BSON_REGEX = 11, BSON_DBREF = 12, BSON_CODE = 13, BSON_SYMBOL = 14,
  BSON_CODEWSCOPE = 15, BSON_INT = 16, BSON_TIMESTAMP = 17, BSON_LONG = 18,
  BSON_DECIMAL = 100, BSON_MAXKEY = 127
}
 

Functions

SDB_EXPORT bsonbson_create (void)
 Create a BSON object and in initilize it.
 
SDB_EXPORT void bson_dispose (bson *b)
 Free a BSON object.
 
SDB_EXPORT int bson_size (const bson *b)
 Size of a BSON object.
 
SDB_EXPORT int bson_buffer_size (const bson *b)
 Minimun finished size of an unfinished BSON object.
 
SDB_EXPORT void bson_print (const bson *b)
 Print a string representation of a BSON object.
 
SDB_EXPORT int bson_sprint_iterator (char **pbuf, int *left, bson_iterator *i, char delChar)
 Print a string representation of BSON Iterator to buffer ( without key ).
 
SDB_EXPORT int bson_sprint (char *buffer, int bufsize, const bson *b)
 Print a string representation of a BSON object to buffer.
 
SDB_EXPORT int bson_sprint_length_iterator (bson_iterator *i)
 Estimate the length of a bson iterator.
 
SDB_EXPORT int bson_sprint_length (const bson *b)
 Estimate the length of the string representation of the specified BSON object.
 
SDB_EXPORT const char * bson_data (const bson *b)
 Return a pointer to the raw buffer stored by this bson object.
 
SDB_EXPORT int bson_sprint_raw (char **pbuf, int *left, const char *data, int isobj)
 Print a string representation of a BSON object.
 
SDB_EXPORT int bson_sprint_length_raw (const char *data, int isobj)
 Estimate the length of the string representation of the specified BSON object.
 
SDB_EXPORT bson_type bson_find (bson_iterator *it, const bson *obj, const char *name)
 Advance a bson_iterator to the named field.
 
SDB_EXPORT bson_iteratorbson_iterator_create (void)
 Create a bson_iterator on the heap.
 
SDB_EXPORT void bson_iterator_dispose (bson_iterator *)
 Free a bson_iterator which build on the heap.
 
SDB_EXPORT void bson_iterator_init (bson_iterator *i, const bson *b)
 Initialize a bson_iterator.
 
SDB_EXPORT void bson_iterator_from_buffer (bson_iterator *i, const char *buffer)
 Initialize a bson iterator from a const char* buffer.
 
SDB_EXPORT bson_bool_t bson_iterator_more (const bson_iterator *i)
 Check to see if the bson_iterator has more data.
 
SDB_EXPORT bson_type bson_iterator_next (bson_iterator *i)
 Point the iterator at the next BSON object.
 
SDB_EXPORT bson_type bson_iterator_type (const bson_iterator *i)
 Get the type of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT const char * bson_iterator_key (const bson_iterator *i)
 Get the key of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT const char * bson_iterator_value (const bson_iterator *i)
 Get the value of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT double bson_iterator_double (const bson_iterator *i)
 Get the double value of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT int bson_iterator_int (const bson_iterator *i)
 Get the int value of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT int64_t bson_iterator_long (const bson_iterator *i)
 Get the long value of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT int bson_iterator_decimal_scale (const bson_iterator *i, int *sign, int *scale)
 Get the decimal's sign and scale of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT int bson_iterator_decimal_typemod (const bson_iterator *i, int *typemod)
 Get the decimal's typemod of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT int bson_iterator_decimal_weight (const bson_iterator *i, int *weight)
 Get the decimal's weight of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT int bson_iterator_decimal_size (const bson_iterator *i, int *size)
 Get the decimal's size of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT int bson_iterator_decimal (const bson_iterator *i, bson_decimal *decimal)
 Get the decimal value of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT bson_timestamp_t bson_iterator_timestamp (const bson_iterator *i)
 Get the timestamp value of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT int bson_iterator_timestamp_time (const bson_iterator *i)
 
SDB_EXPORT int bson_iterator_timestamp_increment (const bson_iterator *i)
 
SDB_EXPORT bson_bool_t bson_iterator_bool (const bson_iterator *i)
 Get the boolean value of the BSON object currently pointed to by the iterator.
 
double bson_iterator_double_raw (const bson_iterator *i)
 Get the double value of the BSON object currently pointed to by the iterator.
 
int bson_iterator_int_raw (const bson_iterator *i)
 Get the int value of the BSON object currently pointed to by the iterator.
 
int64_t bson_iterator_long_raw (const bson_iterator *i)
 Get the long value of the BSON object currently pointed to by the iterator.
 
bson_bool_t bson_iterator_bool_raw (const bson_iterator *i)
 Get the bson_bool_t value of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT bson_oid_tbson_iterator_oid (const bson_iterator *i)
 Get the bson_oid_t value of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT const char * bson_iterator_string (const bson_iterator *i)
 Get the string value of the BSON object currently pointed to by the iterator.
 
int bson_iterator_string_len (const bson_iterator *i)
 Get the string length of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT const char * bson_iterator_code (const bson_iterator *i)
 Get the code value of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT void bson_iterator_code_scope (const bson_iterator *i, bson *scope)
 Calls bson_empty on scope if not a bson_codewscope.
 
SDB_EXPORT bson_date_t bson_iterator_date (const bson_iterator *i)
 Get the date value of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT time_t bson_iterator_time_t (const bson_iterator *i)
 Get the time value of the BSON object currently pointed to by the iterator.
 
SDB_EXPORT int bson_iterator_bin_len (const bson_iterator *i)
 Get the length of the BSON binary object currently pointed to by the iterator.
 
SDB_EXPORT char bson_iterator_bin_type (const bson_iterator *i)
 Get the type of the BSON binary object currently pointed to by the iterator.
 
SDB_EXPORT const char * bson_iterator_bin_data (const bson_iterator *i)
 Get the value of the BSON binary object currently pointed to by the iterator.
 
SDB_EXPORT const char * bson_iterator_regex (const bson_iterator *i)
 Get the value of the BSON regex object currently pointed to by the iterator.
 
SDB_EXPORT const char * bson_iterator_regex_opts (const bson_iterator *i)
 Get the options of the BSON regex object currently pointed to by the iterator.
 
SDB_EXPORT const char * bson_iterator_dbref (const bson_iterator *i)
 Get the DB name of the BSON DBRef object currently pointed to by the iterator.
 
SDB_EXPORT bson_oid_tbson_iterator_dbref_oid (const bson_iterator *i)
 Get the DB OID of the BSON DBRef object currently pointed to by the iterator.
 
SDB_EXPORT void bson_iterator_subobject (const bson_iterator *i, bson *sub)
 Get the BSON subobject currently pointed to by the iterator.
 
SDB_EXPORT void bson_iterator_subiterator (const bson_iterator *i, bson_iterator *sub)
 Get a bson_iterator that on the BSON subobject.
 
SDB_EXPORT void bson_oid_from_string (bson_oid_t *oid, const char *str)
 Create a bson_oid_t from a string.
 
SDB_EXPORT void bson_oid_to_string (const bson_oid_t *oid, char *str)
 Create a string representation of the bson_oid_t.
 
SDB_EXPORT void bson_oid_gen (bson_oid_t *oid)
 Create a bson_oid object.
 
SDB_EXPORT void bson_set_oid_fuzz (int(*func)(void))
 Set a function to be used to generate the second four bytes of an object id.
 
SDB_EXPORT void bson_set_oid_inc (int(*func)(void))
 Set a function to be used to generate the incrementing part of an object id (last four bytes).
 
SDB_EXPORT time_t bson_oid_generated_time (bson_oid_t *oid)
 Get the time a bson_oid_t was created.
 
SDB_EXPORT void bson_init (bson *b)
 Initialize a new bson object.
 
int bson_init_data (bson *b, const char *data)
 Initialize a BSON object, and point its data pointer to the provided char*.
 
int bson_init_finished_data (bson *b, const char *data)
 Initialize a BSON object, and point its data pointer to the provided char*, then finish building this BSON object.
 
SDB_EXPORT void bson_init_size (bson *b, int size)
 Initialize a BSON object, and set its buffer to the given size.
 
int bson_ensure_space (bson *b, const int bytesNeeded)
 Grow a bson object.
 
SDB_EXPORT int bson_finish (bson *b)
 Finalize a bson object.
 
SDB_EXPORT void bson_destroy (bson *b)
 Destroy a bson object.
 
SDB_EXPORT bsonbson_empty (bson *obj)
 Returns a pointer to a static empty BSON object.
 
SDB_EXPORT bson_bool_t bson_is_empty (bson *obj)
 Check BSON object is empty or not.
 
SDB_EXPORT int bson_copy (bson *out, const bson *in)
 Make a complete copy of the a BSON object.
 
SDB_EXPORT int bson_init_by_reset (bson *obj)
 Reset bson initialization, this can reuse bson's memory.
 
SDB_EXPORT int bson_append_oid (bson *b, const char *name, const bson_oid_t *oid)
 Append a previously created bson_oid_t to a bson object.
 
SDB_EXPORT int bson_append_new_oid (bson *b, const char *name)
 Append a bson_oid_t to a bson.
 
SDB_EXPORT int bson_append_int (bson *b, const char *name, const int i)
 Append an int to a bson.
 
SDB_EXPORT int bson_append_long (bson *b, const char *name, const int64_t i)
 Append an long to a bson.
 
SDB_EXPORT int bson_append_decimal (bson *b, const char *name, const bson_decimal *decimal)
 Append an decimal to a bson.
 
SDB_EXPORT int bson_append_decimal2 (bson *b, const char *name, const char *value, int precision, int scale)
 Append an decimal to a bson.
 
SDB_EXPORT int bson_append_decimal3 (bson *b, const char *name, const char *value)
 Append an decimal to a bson.
 
SDB_EXPORT int bson_append_double (bson *b, const char *name, const double d)
 Append an double to a bson.
 
SDB_EXPORT int bson_append_string (bson *b, const char *name, const char *str)
 Append a string to a bson.
 
SDB_EXPORT int bson_append_string_n (bson *b, const char *name, const char *str, int len)
 Append len bytes of a string to a bson.
 
SDB_EXPORT int bson_append_symbol (bson *b, const char *name, const char *str)
 Append a symbol to a bson.
 
SDB_EXPORT int bson_append_symbol_n (bson *b, const char *name, const char *str, int len)
 Append len bytes of a symbol to a bson.
 
SDB_EXPORT int bson_append_code (bson *b, const char *name, const char *str)
 Append code to a bson.
 
SDB_EXPORT int bson_append_code_n (bson *b, const char *name, const char *str, int len)
 Append len bytes of code to a bson.
 
SDB_EXPORT int bson_append_code_w_scope (bson *b, const char *name, const char *code, const bson *scope)
 Append code to a bson with scope.
 
SDB_EXPORT int bson_append_code_w_scope_n (bson *b, const char *name, const char *code, int size, const bson *scope)
 Append len bytes of code to a bson with scope.
 
SDB_EXPORT int bson_append_binary (bson *b, const char *name, char type, const char *str, int len)
 Append binary data to a bson.
 
SDB_EXPORT int bson_append_bool (bson *b, const char *name, const bson_bool_t v)
 Append a bson_bool_t to a bson.
 
SDB_EXPORT int bson_append_null (bson *b, const char *name)
 Append a null value to a bson.
 
SDB_EXPORT int bson_append_undefined (bson *b, const char *name)
 Append an undefined value to a bson.
 
SDB_EXPORT int bson_append_regex (bson *b, const char *name, const char *pattern, const char *opts)
 Append a regex value to a bson.
 
SDB_EXPORT int bson_append_minkey (bson *b, const char *name)
 Append a minkey to a bson.
 
SDB_EXPORT int bson_append_maxkey (bson *b, const char *name)
 Append a maxkey to a bson.
 
SDB_EXPORT int bson_append_bson (bson *b, const char *name, const bson *bson)
 Append bson data to a bson.
 
SDB_EXPORT int bson_append_array (bson *b, const char *name, const bson *bson)
 Append array data to a bson.
 
SDB_EXPORT int bson_append_element (bson *b, const char *name_or_null, const bson_iterator *elem)
 Append a BSON element to a bson from the current point of an iterator.
 
SDB_EXPORT int bson_append_elements (bson *dst, const bson *src)
 Append all the elements of a bson to another bson.
 
SDB_EXPORT int bson_append_timestamp (bson *b, const char *name, bson_timestamp_t *ts)
 Append a bson_timestamp_t value to a bson.
 
SDB_EXPORT int bson_append_timestamp2 (bson *b, const char *name, int time, int increment)
 Append the timestamp value to a bson.
 
SDB_EXPORT int bson_append_date (bson *b, const char *name, bson_date_t millis)
 Append a bson_date_t value to a bson.
 
SDB_EXPORT int bson_append_time_t (bson *b, const char *name, time_t secs)
 Append a time_t value to a bson.
 
SDB_EXPORT int bson_append_start_object (bson *b, const char *name)
 Start appending a new object to a bson.
 
SDB_EXPORT int bson_append_start_array (bson *b, const char *name)
 Start appending a new array to a bson.
 
SDB_EXPORT int bson_append_finish_object (bson *b)
 Finish appending a new object or array to a bson.
 
SDB_EXPORT int bson_append_finish_array (bson *b)
 Finish appending a new object or array to a bson.
 
void bson_numstr (char *str, int i)
 
void bson_incnumstr (char *str)
 
void bson_set_malloc_func (bson_malloc_func_p func)
 
void bson_set_realloc_func (bson_realloc_func_p func)
 
void bson_set_free_func (bson_free_func_p func)
 
SDB_EXPORT void bson_free (void *ptr)
 
SDB_EXPORT void * bson_malloc (int size)
 Allocates memory and checks return value, exiting fatally if malloc() fails.
 
void * bson_realloc (void *ptr, int size)
 Changes the size of allocated memory and checks return value, exiting fatally if realloc() fails.
 
SDB_EXPORT bson_err_handler set_bson_err_handler (bson_err_handler func)
 Set a function for error handling.
 
void bson_fatal (int ok)
 Exit fatally.
 
void bson_fatal_msg (int ok, const char *msg)
 Exit fatally with an error message.
 
void bson_builder_error (bson *b)
 Invoke the error handler, but do not exit.
 
SDB_EXPORT double bson_int64_to_double (int64_t i64)
 Cast an int64_t to double.
 
SDB_EXPORT void bson_swap_endian32 (void *outp, const void *inp)
 
SDB_EXPORT void bson_swap_endian64 (void *outp, const void *inp)
 
SDB_EXPORT bson_bool_t bson_is_inf (double d, int *pSign)
 
SDB_EXPORT void bson_set_js_compatibility (int compatible)
 when this value is not zero, the bson_print method will show the string which is the same with that shows in sdb shell.
 
SDB_EXPORT int bson_get_js_compatibility ()
 get whether bson_print method will show the string which is the same with that shows in sdb shell or not
 

Variables

bson_printf_func bson_printf
 
bson_fprintf_func bson_fprintf
 
bson_sprintf_func bson_sprintf
 
bson_printf_func bson_errprintf
 

Detailed Description

BSON Declarations.

Enumeration Type Documentation

Enumerator:
BSON_BIN_BINARY 

Binary / Generic .

BSON_BIN_FUNC 

Function .

BSON_BIN_BINARY_OLD 

Binary(Old) .

BSON_BIN_UUID 

UUID (Old).

BSON_BIN_MD5 

MD5 .

BSON_BIN_USER 

User defined.

Enumerator:
BSON_SIZE_OVERFLOW 

Trying to create a BSON object larger than INT_MAX.

enum bson_type
Enumerator:
BSON_MINKEY 

Min key.

BSON_EOO 

End of object.

BSON_DOUBLE 

Floatint point.

BSON_STRING 

UTF-8 string.

BSON_OBJECT 

Embedded document.

BSON_ARRAY 

Array.

BSON_BINDATA 

Binary data.

BSON_UNDEFINED 

Undefined-Deprecated.

BSON_OID 

Objectid.

BSON_BOOL 

BOOlean.

BSON_DATE 

UTC datetime.

BSON_NULL 

Null value.

BSON_REGEX 

Regular expression.

BSON_DBREF 

DBPointer-Deprecated.

BSON_CODE 

JavaScript code.

BSON_SYMBOL 

Symbol-Deprecated.

BSON_CODEWSCOPE 

JavaScript code w/scope.

BSON_INT 

32-bit integer.

BSON_TIMESTAMP 

Timestamp.

BSON_LONG 

64-bit integer.

BSON_MAXKEY 

decimal type

Max key.

Enumerator:
BSON_VALID 

BSON is valid and UTF-8 compliant.

BSON_NOT_UTF8 

A key or a string is not valid UTF-8.

BSON_FIELD_HAS_DOT 

Warning: key contains '.

' character.

BSON_FIELD_INIT_DOLLAR 

Warning: key starts with '$' character.

BSON_ALREADY_FINISHED 

Trying to modify a finished BSON object.

Function Documentation

SDB_EXPORT int bson_append_array ( bson b,
const char *  name,
const bson bson 
)

Append array data to a bson.

Parameters
bthe bson to append to.
namethe key for the bson data.
bsonthe bson array to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_binary ( bson b,
const char *  name,
char  type,
const char *  str,
int  len 
)

Append binary data to a bson.

Parameters
bthe bson to append to.
namethe key for the data.
typethe binary data type.
strthe binary data.
lenthe length of the data.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_bool ( bson b,
const char *  name,
const bson_bool_t  v 
)

Append a bson_bool_t to a bson.

Parameters
bthe bson to append to.
namethe key for the boolean value.
vthe bson_bool_t to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_bson ( bson b,
const char *  name,
const bson bson 
)

Append bson data to a bson.

Parameters
bthe bson to append to.
namethe key for the bson data.
bsonthe bson object to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_code ( bson b,
const char *  name,
const char *  str 
)

Append code to a bson.

Parameters
bthe bson to append to.
namethe key for the code.
strthe code to append.
lenthe number of bytes from str to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_code_n ( bson b,
const char *  name,
const char *  str,
int  len 
)

Append len bytes of code to a bson.

Parameters
bthe bson to append to.
namethe key for the code.
strthe code to append.
lenthe number of bytes from str to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_code_w_scope ( bson b,
const char *  name,
const char *  code,
const bson scope 
)

Append code to a bson with scope.

Parameters
bthe bson to append to.
namethe key for the code.
strthe string to append.
scopea BSON object containing the scope.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_code_w_scope_n ( bson b,
const char *  name,
const char *  code,
int  size,
const bson scope 
)

Append len bytes of code to a bson with scope.

Parameters
bthe bson to append to.
namethe key for the code.
strthe string to append.
lenthe number of bytes from str to append.
scopea BSON object containing the scope.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_date ( bson b,
const char *  name,
bson_date_t  millis 
)

Append a bson_date_t value to a bson.

Parameters
bthe bson to append to.
namethe key for the date value.
millisthe bson_date_t to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_decimal ( bson b,
const char *  name,
const bson_decimal *  decimal 
)

Append an decimal to a bson.

Parameters
bthe bson to append to.
namethe key for the decimal.
decimalthe decimal to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_decimal2 ( bson b,
const char *  name,
const char *  value,
int  precision,
int  scale 
)

Append an decimal to a bson.

Parameters
bthe bson to append to.
namethe key for the decimal.
valuethe string format of the decimal to append.
precision,theprecision of decimal
scale,thescale of decimal
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_decimal3 ( bson b,
const char *  name,
const char *  value 
)

Append an decimal to a bson.

Parameters
bthe bson to append to.
namethe key for the decimal.
valuethe string format of the decimal to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_double ( bson b,
const char *  name,
const double  d 
)

Append an double to a bson.

Parameters
bthe bson to append to.
namethe key for the double.
dthe double to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_element ( bson b,
const char *  name_or_null,
const bson_iterator elem 
)

Append a BSON element to a bson from the current point of an iterator.

Parameters
bthe bson to append to.
name_or_nullthe key for the BSON element, or NULL.
elemthe bson_iterator.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_elements ( bson dst,
const bson src 
)

Append all the elements of a bson to another bson.

Parameters
dstthe destination bson.
srcthe source bson.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_finish_array ( bson b)

Finish appending a new object or array to a bson.

This is simply an alias for bson_append_finish_object.

Parameters
bthe bson to append to.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_finish_object ( bson b)

Finish appending a new object or array to a bson.

Parameters
bthe bson to append to.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_int ( bson b,
const char *  name,
const int  i 
)

Append an int to a bson.

Parameters
bthe bson to append to.
namethe key for the int.
ithe int to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_long ( bson b,
const char *  name,
const int64_t  i 
)

Append an long to a bson.

Parameters
bthe bson to append to.
namethe key for the long.
ithe long to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_maxkey ( bson b,
const char *  name 
)

Append a maxkey to a bson.

Parameters
bthe bson to append to.
namethe key for the maxkey.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_minkey ( bson b,
const char *  name 
)

Append a minkey to a bson.

Parameters
bthe bson to append to.
namethe key for the minkey.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_new_oid ( bson b,
const char *  name 
)

Append a bson_oid_t to a bson.

Parameters
bthe bson to append to.
namethe key for the bson_oid_t.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_null ( bson b,
const char *  name 
)

Append a null value to a bson.

Parameters
bthe bson to append to.
namethe key for the null value.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_oid ( bson b,
const char *  name,
const bson_oid_t oid 
)

Append a previously created bson_oid_t to a bson object.

Parameters
bthe bson to append to.
namethe key for the bson_oid_t.
oidthe bson_oid_t to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_regex ( bson b,
const char *  name,
const char *  pattern,
const char *  opts 
)

Append a regex value to a bson.

Parameters
bthe bson to append to.
namethe key for the regex value.
patternthe regex pattern to append.
theregex options.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_start_array ( bson b,
const char *  name 
)

Start appending a new array to a bson.

Parameters
bthe bson to append to.
namethe name of the new array.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_start_object ( bson b,
const char *  name 
)

Start appending a new object to a bson.

Parameters
bthe bson to append to.
namethe name of the new object.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_string ( bson b,
const char *  name,
const char *  str 
)

Append a string to a bson.

Parameters
bthe bson to append to.
namethe key for the string.
strthe string to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_string_n ( bson b,
const char *  name,
const char *  str,
int  len 
)

Append len bytes of a string to a bson.

Parameters
bthe bson to append to.
namethe key for the string.
strthe string to append.
lenthe number of bytes from str to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_symbol ( bson b,
const char *  name,
const char *  str 
)

Append a symbol to a bson.

Parameters
bthe bson to append to.
namethe key for the symbol.
strthe symbol to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_symbol_n ( bson b,
const char *  name,
const char *  str,
int  len 
)

Append len bytes of a symbol to a bson.

Parameters
bthe bson to append to.
namethe key for the symbol.
strthe symbol to append.
lenthe number of bytes from str to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_time_t ( bson b,
const char *  name,
time_t  secs 
)

Append a time_t value to a bson.

Parameters
bthe bson to append to.
namethe key for the date value.
secsthe time_t to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_timestamp ( bson b,
const char *  name,
bson_timestamp_t ts 
)

Append a bson_timestamp_t value to a bson.

Parameters
bthe bson to append to.
namethe key for the timestampe value.
tsthe bson_timestamp_t value to append.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_timestamp2 ( bson b,
const char *  name,
int  time,
int  increment 
)

Append the timestamp value to a bson.

Parameters
bthe bson to append to.
namethe key for the timestampe value.
timeseconds since epoch.
incrementmicroseconds in range of [0us, 999999us].
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_append_undefined ( bson b,
const char *  name 
)

Append an undefined value to a bson.

Parameters
bthe bson to append to.
namethe key for the undefined value.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_buffer_size ( const bson b)

Minimun finished size of an unfinished BSON object.

Parameters
bthe BSON object.
Returns
the BSON object's minimun finished size.
void bson_builder_error ( bson b)

Invoke the error handler, but do not exit.

Parameters
bthe buffer object.
SDB_EXPORT int bson_copy ( bson out,
const bson in 
)

Make a complete copy of the a BSON object.

The source bson object must be in a finished state; otherwise, the copy will fail.

Parameters
outthe copy destination BSON object.
inthe copy source BSON object.
SDB_EXPORT bson* bson_create ( void  )

Create a BSON object and in initilize it.

Returns
the newly created bson object.
SDB_EXPORT const char* bson_data ( const bson b)

Return a pointer to the raw buffer stored by this bson object.

Parameters
ba BSON object
SDB_EXPORT void bson_destroy ( bson b)

Destroy a bson object.

Parameters
bthe bson object to destroy.
SDB_EXPORT void bson_dispose ( bson b)

Free a BSON object.

Parameters
bthe BSON object.
SDB_EXPORT bson* bson_empty ( bson obj)

Returns a pointer to a static empty BSON object.

Parameters
objthe BSON object to initialize.
Returns
the empty initialized BSON object.
int bson_ensure_space ( bson b,
const int  bytesNeeded 
)

Grow a bson object.

Parameters
bthe bson to grow.
bytesNeededthe additional number of bytes needed.
Returns
BSON_OK or BSON_ERROR with the bson error object set. Exits if allocation fails.
void bson_fatal ( int  ok)

Exit fatally.

Parameters
okexits if ok is equal to 0.
void bson_fatal_msg ( int  ok,
const char *  msg 
)

Exit fatally with an error message.

Parameters
okexits if ok is equal to 0.
msgprints to stderr before exiting.
SDB_EXPORT bson_type bson_find ( bson_iterator it,
const bson obj,
const char *  name 
)

Advance a bson_iterator to the named field.

Parameters
itthe bson_iterator to use.
objthe BSON object to use.
namethe name of the field to find.
Returns
the type of the found object or BSON_EOO if it is not found.
SDB_EXPORT int bson_finish ( bson b)

Finalize a bson object.

Parameters
bthe bson object to finalize.
Returns
the standard error code. To deallocate memory, call bson_destroy on the bson object.
SDB_EXPORT void bson_init ( bson b)

Initialize a new bson object.

If not created with bson_new, you must initialize each new bson object using this function.

Note
When finished, you must pass the bson object to bson_destroy( ).
SDB_EXPORT int bson_init_by_reset ( bson obj)

Reset bson initialization, this can reuse bson's memory.

Parameters
inthe BSON object.
int bson_init_data ( bson b,
const char *  data 
)

Initialize a BSON object, and point its data pointer to the provided char*.

Parameters
bthe BSON object to initialize.
datathe raw BSON data.
Returns
BSON_OK or BSON_ERROR.
int bson_init_finished_data ( bson b,
const char *  data 
)

Initialize a BSON object, and point its data pointer to the provided char*, then finish building this BSON object.

Parameters
bthe BSON object to initialize.
datathe raw BSON data.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT void bson_init_size ( bson b,
int  size 
)

Initialize a BSON object, and set its buffer to the given size.

Parameters
bthe BSON object to initialize.
sizethe initial size of the buffer.
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT double bson_int64_to_double ( int64_t  i64)

Cast an int64_t to double.

This is necessary for embedding in certain environments.

SDB_EXPORT bson_bool_t bson_is_empty ( bson obj)

Check BSON object is empty or not.

Parameters
objthe BSON object.
Returns
true or false.
SDB_EXPORT const char* bson_iterator_bin_data ( const bson_iterator i)

Get the value of the BSON binary object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the value of the current BSON binary object.
SDB_EXPORT int bson_iterator_bin_len ( const bson_iterator i)

Get the length of the BSON binary object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the length of the current BSON binary object.
SDB_EXPORT char bson_iterator_bin_type ( const bson_iterator i)

Get the type of the BSON binary object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the type of the current BSON binary object.
SDB_EXPORT bson_bool_t bson_iterator_bool ( const bson_iterator i)

Get the boolean value of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the value of the current BSON object.
bson_bool_t bson_iterator_bool_raw ( const bson_iterator i)

Get the bson_bool_t value of the BSON object currently pointed to by the iterator.

Assumes the correct type is used.

Parameters
ithe bson_iterator
Returns
the value of the current BSON object.
SDB_EXPORT const char* bson_iterator_code ( const bson_iterator i)

Get the code value of the BSON object currently pointed to by the iterator.

Works with bson_code, bson_codewscope, and BSON_STRING returns NULL for everything else.

Parameters
ithe bson_iterator
Returns
the code value of the current BSON object.
SDB_EXPORT void bson_iterator_code_scope ( const bson_iterator i,
bson scope 
)

Calls bson_empty on scope if not a bson_codewscope.

Parameters
ithe bson_iterator.
scopethe bson scope.
SDB_EXPORT bson_iterator* bson_iterator_create ( void  )

Create a bson_iterator on the heap.

Returns
the newly created iterator.
SDB_EXPORT bson_date_t bson_iterator_date ( const bson_iterator i)

Get the date value of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the date value of the current BSON object.
SDB_EXPORT const char* bson_iterator_dbref ( const bson_iterator i)

Get the DB name of the BSON DBRef object currently pointed to by the iterator.

Parameters
ithe bson_iterator.
Returns
the DB name of the current BSON DBRef object.
SDB_EXPORT bson_oid_t* bson_iterator_dbref_oid ( const bson_iterator i)

Get the DB OID of the BSON DBRef object currently pointed to by the iterator.

Parameters
ithe bson_iterator.
Returns
the DB OID of the current BSON DBRef object.
SDB_EXPORT int bson_iterator_decimal ( const bson_iterator i,
bson_decimal *  decimal 
)

Get the decimal value of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_iterator_decimal_scale ( const bson_iterator i,
int *  sign,
int *  scale 
)

Get the decimal's sign and scale of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_iterator_decimal_size ( const bson_iterator i,
int *  size 
)

Get the decimal's size of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_iterator_decimal_typemod ( const bson_iterator i,
int *  typemod 
)

Get the decimal's typemod of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT int bson_iterator_decimal_weight ( const bson_iterator i,
int *  weight 
)

Get the decimal's weight of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
BSON_OK or BSON_ERROR.
SDB_EXPORT double bson_iterator_double ( const bson_iterator i)

Get the double value of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the value of the current BSON object.
double bson_iterator_double_raw ( const bson_iterator i)

Get the double value of the BSON object currently pointed to by the iterator.

Assumes the correct type is used.

Parameters
ithe bson_iterator
Returns
the value of the current BSON object.
SDB_EXPORT void bson_iterator_from_buffer ( bson_iterator i,
const char *  buffer 
)

Initialize a bson iterator from a const char* buffer.

Note that this is mostly used internally.

Parameters
ithe bson_iterator to initialize.
bufferthe buffer to point to.
SDB_EXPORT void bson_iterator_init ( bson_iterator i,
const bson b 
)

Initialize a bson_iterator.

Parameters
ithe bson_iterator to initialize.
bsonthe BSON object to associate with the iterator.
SDB_EXPORT int bson_iterator_int ( const bson_iterator i)

Get the int value of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the value of the current BSON object.
int bson_iterator_int_raw ( const bson_iterator i)

Get the int value of the BSON object currently pointed to by the iterator.

Assumes the correct type is used.

Parameters
ithe bson_iterator
Returns
the value of the current BSON object.
SDB_EXPORT const char* bson_iterator_key ( const bson_iterator i)

Get the key of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the key of the current BSON object.
SDB_EXPORT int64_t bson_iterator_long ( const bson_iterator i)

Get the long value of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the value of the current BSON object.
int64_t bson_iterator_long_raw ( const bson_iterator i)

Get the long value of the BSON object currently pointed to by the iterator.

Assumes the correct type is used.

Parameters
ithe bson_iterator
Returns
the value of the current BSON object.
SDB_EXPORT bson_bool_t bson_iterator_more ( const bson_iterator i)

Check to see if the bson_iterator has more data.

Parameters
ithe iterator.
Returns
returns true if there is more data.
SDB_EXPORT bson_type bson_iterator_next ( bson_iterator i)

Point the iterator at the next BSON object.

Parameters
ithe bson_iterator.
Returns
the type of the next BSON object.
SDB_EXPORT bson_oid_t* bson_iterator_oid ( const bson_iterator i)

Get the bson_oid_t value of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the value of the current BSON object.
SDB_EXPORT const char* bson_iterator_regex ( const bson_iterator i)

Get the value of the BSON regex object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the value of the current BSON regex object.
SDB_EXPORT const char* bson_iterator_regex_opts ( const bson_iterator i)

Get the options of the BSON regex object currently pointed to by the iterator.

Parameters
ithe bson_iterator.
Returns
the options of the current BSON regex object.
SDB_EXPORT const char* bson_iterator_string ( const bson_iterator i)

Get the string value of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the value of the current BSON object.
int bson_iterator_string_len ( const bson_iterator i)

Get the string length of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the length of the current BSON object.
SDB_EXPORT void bson_iterator_subiterator ( const bson_iterator i,
bson_iterator sub 
)

Get a bson_iterator that on the BSON subobject.

Parameters
ithe bson_iterator.
subthe iterator to point at the BSON subobject.
SDB_EXPORT void bson_iterator_subobject ( const bson_iterator i,
bson sub 
)

Get the BSON subobject currently pointed to by the iterator.

Parameters
ithe bson_iterator.
subthe BSON subobject destination.
SDB_EXPORT time_t bson_iterator_time_t ( const bson_iterator i)

Get the time value of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the time value of the current BSON object.
SDB_EXPORT bson_timestamp_t bson_iterator_timestamp ( const bson_iterator i)

Get the timestamp value of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the value of the current BSON object.
SDB_EXPORT bson_type bson_iterator_type ( const bson_iterator i)

Get the type of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the type of the current BSON object.
SDB_EXPORT const char* bson_iterator_value ( const bson_iterator i)

Get the value of the BSON object currently pointed to by the iterator.

Parameters
ithe bson_iterator
Returns
the value of the current BSON object.
SDB_EXPORT void* bson_malloc ( int  size)

Allocates memory and checks return value, exiting fatally if malloc() fails.

Parameters
sizebytes to allocate.
Returns
a pointer to the allocated memory.
See Also
malloc(3)
SDB_EXPORT void bson_oid_from_string ( bson_oid_t oid,
const char *  str 
)

Create a bson_oid_t from a string.

Parameters
oidthe bson_oid_t destination.
stra null terminated string comprised of at least 24 hex chars.
SDB_EXPORT void bson_oid_gen ( bson_oid_t oid)

Create a bson_oid object.

Parameters
oidthe destination for the newly created bson_oid_t.
SDB_EXPORT time_t bson_oid_generated_time ( bson_oid_t oid)

Get the time a bson_oid_t was created.

Parameters
oidthe bson_oid_t.
SDB_EXPORT void bson_oid_to_string ( const bson_oid_t oid,
char *  str 
)

Create a string representation of the bson_oid_t.

Parameters
oidthe bson_oid_t source.
strthe string representation destination.
SDB_EXPORT void bson_print ( const bson b)

Print a string representation of a BSON object.

Parameters
bthe BSON object to print.
void* bson_realloc ( void *  ptr,
int  size 
)

Changes the size of allocated memory and checks return value, exiting fatally if realloc() fails.

Parameters
ptrpointer to the space to reallocate.
sizebytes to allocate.
Returns
a pointer to the allocated memory.
See Also
realloc()
SDB_EXPORT void bson_set_oid_fuzz ( int(*)(void)  func)

Set a function to be used to generate the second four bytes of an object id.

Parameters
funca pointer to a function that returns an int.
SDB_EXPORT void bson_set_oid_inc ( int(*)(void)  func)

Set a function to be used to generate the incrementing part of an object id (last four bytes).

If you need thread-safety in generating object ids, you should set this function.

Parameters
funca pointer to a function that returns an int.
SDB_EXPORT int bson_size ( const bson b)

Size of a BSON object.

Parameters
bthe BSON object.
Returns
the size.
SDB_EXPORT int bson_sprint ( char *  buffer,
int  bufsize,
const bson b 
)

Print a string representation of a BSON object to buffer.

Parameters
bthe BSON object to print.
SDB_EXPORT int bson_sprint_iterator ( char **  pbuf,
int *  left,
bson_iterator i,
char  delChar 
)

Print a string representation of BSON Iterator to buffer ( without key ).

Parameters
ithe BSON Iterator to print.
delCharthe string delimiter.
SDB_EXPORT int bson_sprint_length ( const bson b)

Estimate the length of the string representation of the specified BSON object.

The actual space needed will be less than or equal to the estimated value.

Parameters
bthe BSON object to print.
Returns
estimated length of the string representation (> 0) if succeed, 0 if failed
SDB_EXPORT int bson_sprint_length_iterator ( bson_iterator i)

Estimate the length of a bson iterator.

Parameters
bthe BSON Iterator, note this doesn't include key
Returns
estimated length of the string representation if succeed, 0 if failed
SDB_EXPORT int bson_sprint_length_raw ( const char *  data,
int  isobj 
)

Estimate the length of the string representation of the specified BSON object.

The actual space needed will be less than or equal to the estimated value.

Parameters
datathe raw data to print.
isobj1 if the raw data is a object, 0 if array
Returns
estimated length of the string representation (> 0) if succeed, 0 if failed
SDB_EXPORT int bson_sprint_raw ( char **  pbuf,
int *  left,
const char *  data,
int  isobj 
)

Print a string representation of a BSON object.

Parameters
bsonthe raw data to print.
depththe depth to recurse the object.x Print a string representation of a BSON object to buffer.
bsonthe raw data to print.
depththe depth to recurse the object.x
Returns
0 for failure
1 for success
SDB_EXPORT bson_err_handler set_bson_err_handler ( bson_err_handler  func)

Set a function for error handling.

Parameters
funca bson_err_handler function.
Returns
the old error handling function, or NULL.