.\" Man page generated from reStructuredText.
.
.TH "BSON_APPEND_UTF8" "3" "Feb 23, 2019" "1.14.0" "Libbson"
.SH NAME
bson_append_utf8 \- bson_append_utf8()
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#define BSON_APPEND_UTF8(b, key, val) \e
   bson_append_utf8 (b, key, (int) strlen (key), val, (int) strlen (val))

bool
bson_append_utf8 (bson_t *bson,
                  const char *key,
                  int key_length,
                  const char *value,
                  int length);
.ft P
.fi
.UNINDENT
.UNINDENT
.SH PARAMETERS
.INDENT 0.0
.IP \(bu 2
\fBbson\fP: A \fBbson_t\fP\&.
.IP \(bu 2
\fBkey\fP: An ASCII C string containing the name of the field.
.IP \(bu 2
\fBkey_length\fP: The length of \fBkey\fP in bytes, or \-1 to determine the length with \fBstrlen()\fP\&.
.IP \(bu 2
\fBvalue\fP: A UTF\-8 encoded string.
.IP \(bu 2
\fBlength\fP: The number of bytes in \fBvalue\fP excluding the trailing \fB\e0\fP, or \-1 to determine the length with \fBstrlen()\fP\&.
.UNINDENT
.SH DESCRIPTION
.sp
The \fBbson_append_utf8()\fP function shall append a UTF\-8 encoded string to \fBbson\fP\&.
.sp
\fBvalue\fP \fIMUST\fP be valid UTF\-8.
.sp
Some UTF\-8 implementations allow for \fB\e0\fP to be contained within the string (excluding the termination \fB\e0\fP\&. This is allowed, but remember that it could cause issues with communicating with external systems that do not support it.
.sp
It is suggested to use modified UTF\-8 which uses a 2 byte representation for embedded \fB\e0\fP within the string. This will allow these UTF\-8 encoded strings to used with many libc functions.
.SH RETURNS
.sp
Returns \fBtrue\fP if the operation was applied successfully. The function will fail if appending the value grows \fBbson\fP larger than INT32_MAX.
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.