bson_append_utf8 (3) - Linux Manuals

bson_append_utf8: The bson_append_utf8() function shall append a UTF-8 encoded string to bson.

NAME

bson_append_utf8() - The bson_append_utf8() function shall append a UTF-8 encoded string to bson.

SYNOPSIS

bool
bson_append_utf8 (bson_t     *bson,
                  const char *key,
                  int         key_length,
                  const char *value,
                  int         length);

PARAMETERS

bson
A bson_t \&.

key
An ASCII C string containing the name of the field.

key_length
The length of key in bytes, or -1 to determine the length with strlen(3) \&.

value
A UTF-8 encoded string.

length
The number of bytes in value excluding the trailing \0 , or -1 to determine the length with strlen(3) \&.

DESCRIPTION

The bson_append_utf8(3) function shall append a UTF-8 encoded string to bson \&.

_value_ MUST be valid UTF-8.

Some UTF-8 implementations allow for \0 to be contained within the string (excluding the termination \0 \&. This is allowed, but remember that it could cause issues with communicating with external systems that do not support it.

It is suggested to use modified UTF-8 which uses a 2 byte representation for embedded \0 within the string. This will allow these UTF-8 encoded strings to used with many libc functions.

RETURNS

true if the operation was applied successfully, otherwise false and bson should be discarded.

COLOPHON

This page is part of libbson. Please report any bugs at https://jira.mongodb.org/browse/CDRIVER.

Pages related to bson_append_utf8

  • bson_append_undefined (3) - The bson_append_undefined() function shall append a new element to bson of type BSON_TYPE_UNDEFINED. Undefined is common in Javascript. However, this element type is deprecated and should not be used in new code.
  • bson_append_array (3) - The bson_append_array() function shall append child to bson using the specified key. The type of the field will be an array, but it is the responsibility of the caller to ensure that the keys of child are properly formatted with string keys such as "0", "1", "2" and so forth.
  • bson_append_array_begin (3) - The bson_append_array_begin() function shall begin appending an array field to bson. This allows for incrementally building a sub-array. Doing so will generally yield better performance as you will serialize to a single buffer. When done building the sub-array, the caller MUST call bson_append_array_end().
  • bson_append_array_end (3) - The bson_append_array_end() function shall complete the appending of an array field started with bson_append_array_begin(). child is invalid after calling this function.
  • bson_append_binary (3) - The bson_append_binary() function shall append a new element to bson containing the binary data provided.
  • bson_append_bool (3) - The bson_append_bool() function shall append a new element to bson containing the boolean provided.
  • bson_append_code (3) - The bson_append_code() function shall append a new element to bson using the UTF-8 encoded javascript provided. javascript must be a NULL terminated C string.
  • bson_append_code_with_scope (3) - The bson_append_code_with_scope() function shall perform like bson_append_code() except it allows providing a scope to the javascript function in the form of a bson document.
  • bson_append_date_time (3) - The bson_append_date_time() function shall append a new element to a bson document containing a date and time with no timezone information. value is assumed to be in UTC format of milliseconds since the UNIX epoch. value MAY be negative.
  • bson_append_dbpointer (3) - The dbpointer field type is DEPRECATED and should only be used when interacting with legacy systems.
  • bson_append_document (3) - The bson_append_document() function shall append child to bson using the specified key. The type of the field will be a document.
  • bson_append_document_begin (3) - The bson_append_document_begin() function shall begin appending a sub-document to bson. Use child to add fields to the sub-document. When completed, call bson_append_document_end() to complete the element.
  • bson_append_document_end (3) - The bson_append_document_end() function shall complete the appending of a document with bson_append_document_begin(). child is invalid after calling this function.
  • bson_append_double (3) - The bson_append_double() function shall append a new element to a bson document of type double.
  • bson_append_int32 (3) - The bson_append_int32() function shall append a new element to bson containing a 32-bit signed integer.
  • bson_append_int64 (3) - The bson_append_int64() function shall append a new element to bson containing a 64-bit signed integer.