[#BloombergLP-bdlde-CharConvertUcs2-ucs2ToUtf8-01]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlde.adoc[bdlde]::xref:BloombergLP/bdlde/CharConvertUcs2.adoc[CharConvertUcs2]::ucs2ToUtf8
:relfileprefix: ../../../
:mrdocs:

Load into `result` the UTF&hyphen;8 conversion of the null&hyphen;terminated UCS&hyphen;2 `srcString`&period;

== Synopsis

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

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
static
int
ucs2ToUtf8(
    xref:bsl/string.adoc[bsl::string]* result,
    unsigned short const* srcString,
    std::size&lowbar;t* numCharsWritten = 0);
----

== Description

Load, into the specified `result`, the conversion of the specified null&hyphen;terminated UCS&hyphen;2 `srcString` to its UTF&hyphen;8 equivalent&period; Optionally specify `numCharsWritten` which (if not 0) indicates the modifiable integer into which the number of _characters_ written (including the null terminator) is to be loaded&period; Return 0 on success and `CharConvertStatus&colon;&colon;k&lowbar;INVALID&lowbar;INPUT&lowbar;BIT` otherwise, meaning that at least one sequence of characters was encountered that could not be translated to UTF&hyphen;8&period; The behavior is undefined unless `srcString` is null&hyphen;terminated&period; Note that the null&hyphen;terminating character is not counted in `result&hyphen;&gt;length()`&period; Also note that this function does not currently implement failure modes&semi; however, this could change if UTF&hyphen;8 input validation is added&period;

== Return Value

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

== Parameters

[cols="1,4"]
|===
| Name| Description
| *result*
| output string for the UTF&hyphen;8 conversion
| *srcString*
| null&hyphen;terminated UCS&hyphen;2 input
| *numCharsWritten*
| if non&hyphen;null, receives character count written
|===


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