.\" This manpage is Copyright (C) 2015 MongoDB, Inc.
.\" 
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.3
.\" or any later version published by the Free Software Foundation;
.\" with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.\" A copy of the license is included in the section entitled "GNU
.\" Free Documentation License".
.\" 
.TH "BSON_APPEND_UTF8" "3" "2015-02-10" "libbson"
.SH NAME
bson_append_utf8()
.SH "SYNOPSIS"

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

.SH "PARAMETERS"

.TP
.B bson
A
.BR bson_t
\&.
.LP
.TP
.B key
An ASCII C string containing the name of the field.
.LP
.TP
.B key_length
The length of
.B key
in bytes, or -1 to determine the length with
.B strlen()
\&.
.LP
.TP
.B value
A UTF-8 encoded string.
.LP
.TP
.B length
The number of bytes in
.B value
excluding the trailing
.B \0
, or -1 to determine the length with
.B strlen()
\&.
.LP

.SH "DESCRIPTION"

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

_value_
.BR MUST
be valid UTF-8.

Some UTF-8 implementations allow for
.B \0
to be contained within the string (excluding the termination
.B \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
.B \0
within the string. This will allow these UTF-8 encoded strings to used with many libc functions.

.SH "RETURNS"

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


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