1BSON_APPEND_UTF8(3)                 libbson                BSON_APPEND_UTF8(3)
2
3
4

NAME

6       bson_append_utf8 - bson_append_utf8()
7

SYNOPSIS

9          #define BSON_APPEND_UTF8(b, key, val) \
10             bson_append_utf8 (b, key, (int) strlen (key), val, (int) strlen (val))
11
12          bool
13          bson_append_utf8 (bson_t *bson,
14                            const char *key,
15                            int key_length,
16                            const char *value,
17                            int length);
18

PARAMETERS

20       • bson: A bson_t.
21
22       • key: An ASCII C string containing the name of the field.
23
24       • key_length: The length of key in bytes, or -1 to determine the length
25         with strlen().
26
27       • value: A UTF-8 encoded string.
28
29       • length: The number of bytes in value excluding the trailing \0, or -1
30         to determine the length with strlen().
31

DESCRIPTION

33       The  bson_append_utf8() function shall append a UTF-8 encoded string to
34       bson.
35
36       value MUST be valid UTF-8.
37
38       Some UTF-8 implementations allow for \0  to  be  contained  within  the
39       string  (excluding  the  termination  \0. This is allowed, but remember
40       that it could cause issues with  communicating  with  external  systems
41       that do not support it.
42
43       It  is  suggested to use modified UTF-8 which uses a 2 byte representa‐
44       tion for embedded \0 within the string. This will allow these UTF-8 en‐
45       coded strings to used with many libc functions.
46
47       Due  to  legacy  behavior, passing NULL for value appends a null value,
48       not a UTF8 value.  To  append  a  null  value  directly,  prefer  using
49       bson_append_null().
50

RETURNS

52       Returns  true  if  the operation was applied successfully. The function
53       will fail if appending the value grows bson larger than INT32_MAX.
54

AUTHOR

56       MongoDB, Inc
57

59       2017-present, MongoDB, Inc
60
61
62
63
641.24.3                           Aug 17, 2023              BSON_APPEND_UTF8(3)
Impressum