.\" This manpage is Copyright (C) 2016 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_ITER_UTF8" "3" "2016\(hy10\(hy12" "libbson"
.SH NAME
bson_iter_utf8() \- The bson_iter_utf8() function shall retrieve the contents of a BSON_TYPE_UTF8 element currently observed by iter.
.SH "SYNOPSIS"

.nf
.nf
#define BSON_ITER_HOLDS_UTF8(iter) \e
   (bson_iter_type ((iter)) == BSON_TYPE_UTF8)

const char *
bson_iter_utf8 (const bson_iter_t *iter,
                uint32_t          *length);
.fi
.fi

.SH "PARAMETERS"

.TP
.B
iter
A
.B bson_iter_t
.
.LP
.TP
.B
length
An optional location for the length of the resulting UTF\(hy8 encoded string.
.LP

.SH "DESCRIPTION"

The
.B bson_iter_utf8(3)
function shall retrieve the contents of a BSON_TYPE_UTF8 element currently observed by
.B iter
.

It is invalid to call this function while observing an element other than BSON_TYPE_UTF8.

.SH "RETURNS"

A UTF\(hy8 encoded string that has not been modified or freed.

It is suggested that the caller validate the content is valid UTF\(hy8 before using this in other places. That can be done by calling
.B bson_utf8_validate(3)
or validating the underlying
.B bson_t
before iterating it.

Note that not all drivers use multi\(hybyte representation for
.B \0
in UTF\(hy8 encodings (commonly referred to as modified\(hyUTF8). You probably want to take a look at the length field when marshaling to other runtimes.


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