UnicodeToUtf16 (Unicode function): Difference between revisions

Revision as of 15:49, 20 January 2011

Translate to UTF-16 (Unicode class)

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

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

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 Unicode#UTF-8 and UTF-16.
The UnicodeToUtf8 method converts a Unicode string to UTF-8.
The Utf16ToUnicode method converts a UTF-16 Longstring byte stream to Unicode.

Examples

The following fragment shows a successful call of UnicodeToUtf16. The U constant function and StringToHex function are used in the example.

    %u <var>Unicode</var> Initial('&#x31;':U)
    Print %u:<var>UnicodeToUtf16</var>:<var>String</var>ToHex
    Print %u:<var>UnicodeToUtf16</var>(InsertBOM=True):<var>String</var>ToHex

The result is:

    0031
    FEFF0031

@@ Line 2: / Line 2: @@
 [[Category:Unicode methods|UnicodeToUtf16 function]]
 [[Category:Intrinsic methods]]
-<!--DPL?? Category:Unicode methods|<var>UnicodeToUtf16</var> function: Unicode string converted to UTF-16 byte stream-->
+<!--DPL?? Category:<var>Unicode</var> methods|<var>UnicodeToUtf16</var> function: <var>Unicode</var> string converted to UTF-16 byte stream-->
-<!--DPL?? Category:Intrinsic methods|<var>UnicodeToUtf16</var> (Unicode function): Unicode string converted to UTF-16 byte stream-->
+<!--DPL?? Category:Intrinsic methods|<var>UnicodeToUtf16</var> (<var>Unicode</var> function): <var>Unicode</var> string converted to UTF-16 byte stream-->
-<!--DPL?? Category:System methods|<var>UnicodeToUtf16</var> (Unicode function): Unicode string converted to UTF-16 byte stream-->
+<!--DPL?? Category:<var>System</var> methods|<var>UnicodeToUtf16</var> (<var>Unicode</var> function): <var>Unicode</var> string converted to UTF-16 byte stream-->
-This function converts a Unicode string to a UTF-16
+This function converts a <var>Unicode</var> string to a UTF-16
-Longstring byte stream.
+<var>Longstring</var> byte stream.
 The <var>UnicodeToUtf16</var> function is available as of version 7.3 of the <var class=product>Sirius Mods</var>.
@@ Line 15: / Line 15: @@
 <table class="syntaxTable">
 <tr><th><i>%utf16Stream</i></th>
-<td>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). </td></tr>
+<td>A <var>String</var> or <var>Longstring</var> variable to receive the method object string translated to a UTF-16 Big-Endian byte stream (that is, any <var>Unicode</var> point U+wxyz results in the pair of bytes X'wx' and X'yz', in that order). </td></tr>
 <tr><th><i>unicode</i></th>
-<td>A Unicode string. </td></tr>
+<td>A <var>Unicode</var> string. </td></tr>
 <tr><th><b>InsertBOM=</b><i>bool</i></th>
 <td>The optional (name required) InsertBOM argument is a Boolean: <ul> <li>If its value is <tt>True</tt>, the "Byte Order Mark" (U+FEFF) is inserted at the start of the output stream. <li>If its value is <tt>False</tt>, the default, no Byte Order Mark is inserted. </ul></td></tr>
@@ Line 25: / Line 25: @@
 This function can throw the following exception:
 <dl>
-<dt>CharacterTranslationException
+<dt><var>CharacterTranslationException</var>
 <dd>If the method encounters a translation problem,
 properties of the exception object may indicate the location and type of problem.
@@ Line 34: / Line 34: @@
 <li>For more information about UTF-16 conversions, see [[Unicode#UTF-8 and UTF-16]].
 <li>The [[UnicodeToUtf8 (Unicode function)|UnicodeToUtf8]] method
-converts a Unicode string to UTF-8.
+converts a <var>Unicode</var> string to UTF-8.
 <li>The [[Utf16ToUnicode (String function)|Utf16ToUnicode]] method
-converts a UTF-16 Longstring byte stream to Unicode.
+converts a UTF-16 <var>Longstring</var> byte stream to <var>Unicode</var>.
 </ul>
 ==Examples==
@@ Line 44: / Line 44: @@
 are used in the example.
 <pre>
-     %u Unicode Initial('&amp;#x31;':U)
+     %u <var>Unicode</var> Initial('&amp;#x31;':U)
-     Print %u:<var>UnicodeToUtf16</var>:StringToHex
+     Print %u:<var>UnicodeToUtf16</var>:<var>String</var>ToHex
-     Print %u:<var>UnicodeToUtf16</var>(InsertBOM=True):StringToHex
+     Print %u:<var>UnicodeToUtf16</var>(InsertBOM=True):<var>String</var>ToHex
 </pre>
 The result is: