UnicodeToUtf16 (Unicode function)

Unicode string converted to UTF-16 byte stream

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

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

Syntax

  %utf16Stream = unicode:UnicodeToUtf16([InsertBOM=bool])

Syntax Terms

%utf16Stream

A String or Longstring variable to receive the method object string translated to a UTF-16 Big-Endian byte stream (that is, any Unicode point U+wxyz results in the pair of bytes X'wx' and X'yz', in that order).

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) 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-16 conversions, see ?? refid=utf816.
• The UnicodeToUtf8 method (described ??UnicodeToUtf8) converts a Unicode string to UTF-8.
• The Utf16ToUnicode method (described ??Utf16ToUnicode) converts a UTF-16 Longstring byte stream to Unicode.

Examples

The following fragment shows a successful call of UnicodeToUtf16. The U constant function used in the example is described ??U; and StringToHex is ??StringToHex.

    %u Unicode Initial('1':U)
    Print %u:UnicodeToUtf16:StringToHex
    Print %u:UnicodeToUtf16(InsertBOM=True):StringToHex

The result is:

    0031
    FEFF0031