Section 3: library functions
NAME bson_validate() – Validates a BSON document by walking through the document and inspecting the fields for valid content. SYNOPSIS typedef enum { BSON_VALIDATE_NONE = 0, BSON_VALIDATE_UTF8 = (1 << 0), BSON_VALIDATE_DOLLAR_KEYS = (1 << 1), BSON_VALIDATE_DOT_KEYS = (1 << 2), BSON_VALIDATE_UTF8_ALLOW_NULL = (1 << 3), } bson_validate_flags_t; bool bson_validate(const bson_t *bson, bson_validate_flags_t flags, size_t…
NAME bson_utf8_validate() – Validates that the content within utf8 is valid UTF-8. If allow_null is true, then embedded NULL bytes are allowed ( ). SYNOPSIS bool bson_utf8_validate(const char *utf8, size_t utf8_len, bool allow_null); PARAMETERS utf8 A string to verify. utf8_len The length of utf8 in bytes. allow_null A bool indicating that embedded
NAME bson_utf8_next_char() – Advances within utf8 to the next UTF-8 character, which may be multiple bytes offset from utf8. A pointer to the next character is returned. SYNOPSIS const char * bson_utf8_next_char(const char *utf8); PARAMETERS utf8 A UTF-8 encoded string. DESCRIPTION Advances within utf8 to the next UTF-8 character, which may be multiple bytes offset…
NAME bson_utf8_get_char() – Converts the current character in a UTF-8 sequence to a bson_unichar_t, the 32-bit representation of the multi-byte character. SYNOPSIS bson_unichar_t bson_utf8_get_char(const char *utf8); PARAMETERS utf8 A UTF-8 encoded string. DESCRIPTION Converts the current character in a UTF-8 sequence to a bson_unichar_t, the 32-bit representation of the multi-byte character. RETURNS A bson_unichar_t. COLOPHON…
NAME bson_utf8_from_unichar() – Converts a single unicode character to a multi-byte UTF-8 sequence. The result is stored in utf8 and the number of bytes used in len. SYNOPSIS void bson_utf8_from_unichar(bson_unichar_t unichar, char utf8[6], uint32_t *len); PARAMETERS unichar A bson_unichar_t \&. utf8 A location for the utf8 sequence. len A location for the number of bytes…
NAME bson_utf8_escape_for_json() – Escapes the string utf8 to be placed inside of a JSON string. SYNOPSIS char * bson_utf8_escape_for_json(const char *utf8, ssize_t utf8_len); PARAMETERS utf8 A UTF-8 encoded string. utf8_len The length of utf8 in bytes or -1 if it is NULL terminated. DESCRIPTION Escapes the string utf8 to be placed inside of a JSON…
NAME bson_unichar_t – Unicode Character Abstraction SYNOPSIS typedef uint32_t bson_unichar_t; DESCRIPTION bson_unichar_t provides an abstraction on a single unicode character. It is the 32-bit representation of a character. As UTF-8 can contain multi-byte characters, this should be used when iterating through UTF-8 text. EXAMPLE static void print_each_char(const char *str) { bson_unichar_t c; for (; *str;…
NAME bson_uint32_to_string() – Converts value to a string. SYNOPSIS size_t bson_uint32_to_string(uint32_t value, const char **strptr, char *str, size_t size); PARAMETERS value A uint32_t. strptr A location for the resulting string pointer. str A location to buffer the string. size A size_t containing the size of str \&. DESCRIPTION Converts value to a string. If value…
NAME bson_type_t – BSON Type Enumeration SYNOPSIS #include <bson.h> typedef enum { BSON_TYPE_EOD = 0x00, BSON_TYPE_DOUBLE = 0x01, BSON_TYPE_UTF8 = 0x02, BSON_TYPE_DOCUMENT = 0x03, BSON_TYPE_ARRAY = 0x04, BSON_TYPE_BINARY = 0x05, BSON_TYPE_UNDEFINED = 0x06, BSON_TYPE_OID = 0x07, BSON_TYPE_BOOL = 0x08, BSON_TYPE_DATE_TIME = 0x09, BSON_TYPE_NULL = 0x0A, BSON_TYPE_REGEX = 0x0B, BSON_TYPE_DBPOINTER = 0x0C, BSON_TYPE_CODE = 0x0D, BSON_TYPE_SYMBOL…
NAME bson_t – BSON Document Abstraction SYNOPSIS #include <bson.h> BSON_ALIGNED_BEGIN(128) typedef struct { uint32_t flags; /* Internal flags for the bson_t. */ uint32_t len; /* Length of BSON data. */ uint8_t padding[120]; /* Padding for stack allocation. */ } bson_t BSON_ALIGNED_END(128); DESCRIPTION The bson_t structure represents a BSON document. This structure manages the underlying BSON…
NAME bson_subtype_t – Binary Field Subtype SYNOPSIS #include <bson.h> typedef enum { BSON_SUBTYPE_BINARY = 0x00, BSON_SUBTYPE_FUNCTION = 0x01, BSON_SUBTYPE_BINARY_DEPRECATED = 0x02, BSON_SUBTYPE_UUID_DEPRECATED = 0x03, BSON_SUBTYPE_UUID = 0x04, BSON_SUBTYPE_MD5 = 0x05, BSON_SUBTYPE_USER = 0x80, } bson_subtype_t; DESCRIPTION This enumeration contains the various subtypes that may be used in a binary field. See http://bsonspec.org for more information….
NAME bson_strnlen() – A portable version of strnlen(). SYNOPSIS size_t bson_strnlen(const char *s, size_t maxlen); PARAMETERS s A string. maxlen The maximum size of string to check. DESCRIPTION A portable version of strnlen(3) \&. RETURNS The length of s in bytes or maxlen if no
NAME bson_strndup() – Allocates a new string and copies up to n_bytes from str into it. A trailing is always set. SYNOPSIS char * bson_strndup(const char *str, size_t n_bytes); PARAMETERS str A string to copy. n_bytes A size_t. DESCRIPTION Allocates a new string and copies up to n_bytes from str into it. A trailing
NAME bson_strncpy() – Copies up to size bytes from src into dst. dst must be at least size bytes in size. A trailing will be set. SYNOPSIS void bson_strncpy(char *dst, const char *src, size_t size); PARAMETERS dst The destination buffer. src The src buffer. size The number of bytes to copy into dst, which…
NAME bson_string_truncate() – Truncates the string so that it is len bytes in length. This must be smaller or equal to the current length of the string. SYNOPSIS void bson_string_truncate (bson_string_t *string, uint32_t len); PARAMETERS string A bson_string_t \&. len The new length of the string, excluding the trailing
NAME bson_string_t – String Building Abstraction SYNOPSIS #include <bson.h> typedef struct { char *str; uint32_t len; uint32_t alloc; } bson_string_t; DESCRIPTION bson_string_t is an abstraction for building strings. As chunks are added to the string, allocations are performed in powers of two. This API is useful if you need to build UTF-8 encoded strings. EXAMPLE…
NAME bson_string_new() – Creates a new string builder, which uses power-of-two growth of buffers. Use the various bson_string_append*() functions to append to the string. SYNOPSIS bson_string_t * bson_string_new(const char *str); PARAMETERS str A string to be copied or NULL. DESCRIPTION Creates a new string builder, which uses power-of-two growth of buffers. Use the various bson_string_append*()…
NAME bson_string_free() – Frees the bson_string_t structure and optionally the string itself. SYNOPSIS char * bson_string_free (bson_string_t *string, bool free_segment); PARAMETERS string A bson_string_t \&. free_segment A bool indicating if str->str should be returned. DESCRIPTION Frees the bson_string_t structure and optionally the string itself. RETURNS str->str if free_segment is true, otherwise NULL. COLOPHON This page…
NAME bson_string_append_unichar() – Appends a unicode character to string. The character will be encoded into its multi-byte UTF-8 representation. SYNOPSIS void bson_string_append_unichar (bson_string_t *string, bson_unichar_t unichar); PARAMETERS string A bson_string_t \&. unichar A bson_unichar_t \&. DESCRIPTION Appends a unicode character to string. The character will be encoded into its multi-byte UTF-8 representation. COLOPHON This page…
NAME bson_string_append_printf() – Like bson_string_append() but formats a printf style string and then appends that to string. SYNOPSIS void bson_string_append_printf(bson_string_t *string, const char *format, …) BSON_GNUC_PRINTF(2, 3); PARAMETERS string A bson_string_t \&. format A printf style format string. DESCRIPTION Like bson_string_append() but formats a printf style string and then appends that to string \&. COLOPHON…