UnicodeToUtf8 (Unicode function)

Translate to UTF-8 (Unicode class)

This function converts a Unicode string to a UTF-8 Longstring byte stream.

The UnicodeToUtf8 function is available as of version 7.3 of the Sirius Mods.

Syntax

%string = unicode:UnicodeToUtf8[( [InsertBOM= boolean])]

Syntax terms

%utf8Stream	A `String` or `Longstring` variable to receive the method object string translated to a UTF-8 byte stream.
unicode	A `Unicode` string.
InsertBOM=bool	The optional (name required) InsertBOM argument is a Boolean: If its value is `True`, the "Byte Order Mark" (U+FEFF, encoded as X'EFBBBF') is inserted at the start of the output stream. If its value is `False`, the default, no Byte Order Mark is inserted.

Exceptions

This function can throw the following exception:

CharacterTranslationException: If the method encounters a translation problem, properties of the exception object may indicate the location and type of problem. See CharacterTranslationException exception class.

Usage notes

For more information about UTF-8 conversions, see Unicode#UTF-8 and UTF-16.
The UnicodeToUtf16 method converts a Unicode string to UTF-16.
The Utf8ToUnicode method converts a UTF-8 Longstring byte stream to Unicode.

Examples

In the following fragment, UnicodeToUtf8 is used to show how the Unicode U+B2 character (superscript 2) is represented in UTF-8. Appending the StringToHex method is useful for viewing the hex values of characters that do not have displayable EBCDIC equivalents.

The U constant function and StringToHex function are used in the example.

    %u <var>Unicode</var> Initial('&#xB2;':U)
    Print %u:<var>UnicodeToUtf8</var>:<var>String</var>ToHex

The result is:

    C2B2