[#BloombergLP-bdlde-CharConvertUtf32-utf8ToUtf32-0c]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlde.adoc[bdlde]::xref:BloombergLP/bdlde/CharConvertUtf32.adoc[CharConvertUtf32]::utf8ToUtf32
:relfileprefix: ../../../
:mrdocs:

Convert the UTF&hyphen;8 `srcString` into UTF&hyphen;32 in `dstBuffer`&period;

== Synopsis

Declared in `&lt;bdlde&lowbar;charconvertutf32&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
static
int
utf8ToUtf32(
    unsigned int* dstBuffer,
    std::size&lowbar;t dstCapacity,
    char const* srcString,
    std::size&lowbar;t* numCodePointsWritten = 0,
    unsigned int errorWord = &apos;?&apos;,
    xref:BloombergLP/bdlde/ByteOrder/Enum.adoc[ByteOrder::Enum] byteOrder = ByteOrder&colon;&colon;e&lowbar;HOST);
----

== Description

Load into the specified `dstBuffer` of the specified `dstCapacity`, the result of converting the specified UTF&hyphen;8 `srcString` to its UTF&hyphen;32 equivalent&period; Optionally specify `numCodePointsWritten`, which (if not 0) indicates the location of the variable into which the number of Unicode code points (including the null terminator) written is to be loaded&period; Optionally specify `errorWord` to be substituted (if not 0) for invalid encodings in the input string&period; Invalid encodings are multi&hyphen;byte encoding parts out of sequence, non&hyphen;minimal UTF&hyphen;8 encodings, UTF&hyphen;8 encodings more than four bytes in length, or code points outside the ranges that UTF&hyphen;32 can validly encode (i&period;e&period;, `&lsqb; 1 &period;&period; 0xd7ff &rsqb;` and `&lsqb; 0xe000 &period;&period; 0x10ffff &rsqb;`)&period; If `errorWord` is 0, invalid input code points are ignored (i&period;e&period;, produce no corresponding output)&period; Optionally specify `byteOrder` to indicate the byte order of the UTF&hyphen;32 output&semi; if `byteOrder` is not specified, the output is assumed to be in host byte order&period; Return 0 on success and a bit&hyphen;wise OR of the masks defined by `CharConvertStatus&colon;&colon;Enum` otherwise, where `CharConvertStatus&colon;&colon;k&lowbar;INVALID&lowbar;INPUT&lowbar;BIT` will be set if one or more invalid sequences were encountered in the input, and `CharConvertStatus&colon;&colon;k&lowbar;OUT&lowbar;OF&lowbar;SPACE&lowbar;BIT` will be set if the output space was exhausted before conversion was complete&period; If `dstCapacity &gt; 0` yet `dstCapacity` specifies a buffer too small to hold the output, the maximal null&hyphen;terminated prefix of the properly converted result string is loaded into `dstBuffer`&period; The behavior is undefined unless `dstBuffer` refers to an array of at least `dstCapacity` elements, `srcString`, if specified as a `const char &ast;`, is null&hyphen;terminated, and `errorWord` is either 0 or a valid UTF&hyphen;32 code point (in the range `&lsqb; 1 &period;&period; 0xd7ff &rsqb;` or `&lsqb; 0xe000 &period;&period; 0x10ffff &rsqb;`)&period; Note that if `dstCapacity` is 0, `&ast;dstBuffer` is not modified and this function returns a value with `CharConvertStatus&colon;&colon;k&lowbar;OUT&lowbar;OF&lowbar;SPACE&lowbar;BIT` set and 0 is written into `&ast;numCodePointsWritten` (if that pointer is not 0), since there is insufficient space for even a null terminator alone&period; Also note that one Unicode code point always occupies one 32&hyphen;bit _word_ in UTF&hyphen;32, but may occupy more than one _byte_ of UTF&hyphen;8, so that `&ast;numCodePointsWritten` equals the number of _words_ written&period; Also note that `errorWord` is assumed to be in host byte order&period;

== Return Value

0 on success and a bit&hyphen;wise OR of `CharConvertStatus&colon;&colon;Enum` masks otherwise

== Parameters

[cols="1,4"]
|===
| Name| Description
| *dstBuffer*
| buffer for the UTF&hyphen;32 conversion result
| *dstCapacity*
| capacity of `dstBuffer` in words
| *srcString*
| null&hyphen;terminated UTF&hyphen;8 source string to convert
| *numCodePointsWritten*
| if non&hyphen;null, receives the number of code points written (including the terminator)
| *errorWord*
| optional substitute for invalid encodings&semi; 0 ignores them
| *byteOrder*
| byte order of the UTF&hyphen;32 output (host by default)
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#
