[#BloombergLP-bdlde-CharConvertUtf32-utf8ToUtf32-04]
= 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 `dstVector`&period;

== Synopsis

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

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
static
int
utf8ToUtf32(
    xref:bsl/vector-00d.adoc[bsl::vector&lt;unsigned int&gt;]* dstVector,
    char const* srcString,
    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 `dstVector` the result of converting the specified UTF&hyphen;8 `srcString` to its UTF&hyphen;32 equivalent&period; Optionally specify `errorWord` to be substituted, if not 0, for invalid encodings in the input string&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 `CharConvertStatus&colon;&colon;k&lowbar;INVALID&lowbar;INPUT&lowbar;BIT` otherwise&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 sequences are ignored (i&period;e&period;, produce no corresponding output)&period; Any previous contents of the destination are discarded&period; The behavior is undefined unless `srcString` is null&hyphen;terminated when specified as a `const char &ast;`, and unless `errorWord` is either 0 or a valid Unicode code point&period; Note that one code point always occupies one 32&hyphen;bit &ast;ord of output&semi; there is no `numCodePointsWritten` argument since, after the call, `dstVector&hyphen;&gt;size()` will equal the number of code points written&period; Also note that when the input is a `bsl&colon;&colon;string&lowbar;view`, it may contain embedded nulls, which are translated to zeroes in the output&period; Also note that `errorWord` is assumed to be in host byte order&period;

== Return Value

0 on success and `CharConvertStatus&colon;&colon;k&lowbar;INVALID&lowbar;INPUT&lowbar;BIT` otherwise

== Parameters

[cols="1,4"]
|===
| Name| Description
| *dstVector*
| destination for the UTF&hyphen;32 conversion result
| *srcString*
| null&hyphen;terminated UTF&hyphen;8 source string to convert
| *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]#
