<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="utf8">

  <info><link type="guide" xref="index#intro"/></info>
  <title>UTF-8</title>

  <p>Libbson expects that you are always working with UTF-8 encoded text. Anything else is INVALID API USE.</p>
  <p>If you should need to walk through UTF-8 sequences, you can use the various UTF-8 helper functions distributed with Libbson.</p>

  <section id="validate">
    <title>Validating a UTF-8 Sequence</title>

    <p>To validate the string contained in <code>my_string</code>, use the following. You may pass <code>-1</code> for the string length if you know the string is NULL-terminated.</p>

    <synopsis><code mime="text/x-csrc"><![CDATA[if (!bson_utf8_validate (my_string, -1, false)) {
   printf ("Validation failed.\n");
}]]></code></synopsis>

    <p>If <code>my_string</code> has NULL bytes within the string, you must provide the string length. Use the follwing format. Notice the <code>true</code> at the end indicationg <code>\0</code> is allowed.</p>

    <synopsis><code mime="text/x-csrc"><![CDATA[if (!bson_utf8_validate (my_string, my_string_len, true)) {
   printf ("Validation failed.\n");
}]]></code></synopsis>

    <p>For more information see the API reference for <code xref="bson_utf8_validate">bson_utf8_validate()</code>.</p>

  </section>

</page>
