Utf8ToUnicode (String function): Difference between revisions

Revision as of 15:48, 20 January 2011

Convert a UTF-8 Longstring bytestream to Unicode (String class)

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

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

Syntax

%unicode = string:Utf8ToUnicode[( [AllowUntranslatable= boolean])] Throws CharacterTranslationException

Syntax terms

%unicode	A string variable to receive the method object string translated to `Unicode`.
string	A `String` or `Longstring` that is presumed to contain a UTF-8 byte stream.

Exceptions

This intrinsic 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.

Usage notes

Utf8 and Utf16 has more information about UTF-8 conversions.
The Utf16ToUnicode method converts a UTF-16 byte stream to Unicode.
The UnicodeToUtf8 method converts a Unicode string to a UTF-8 Longstring byte stream.

Examples

In the following fragment, Utf8ToUnicode converts a hexadecimal input to a single Unicode character. In case the Unicode character translates to an EBCDIC character that cannot be displayed, the CharacterEncode option of the UnicodeToEbcdic method causes the output of a hexadecimal character reference. The 'X' constant function is used in the example.

   %u Unicode
   %u = 'E284A2':X:Utf8ToUnicode
   Print %u:unicodeToEbcdic(CharacterEncode=true)

The result of the above fragment is the character reference for the trademark character:

   &#x2122;

@@ Line 1: / Line 1: @@
 {{Template:String:Utf8ToUnicode subtitle}}
-This [[Intrinsic classes|intrinsic]] function converts a UTF-8 Longstring byte stream to Unicode.
+This [[Intrinsic classes|intrinsic]] function converts a UTF-8 <var>Longstring</var> byte stream to <var>Unicode</var>.
 The <var>Utf8ToUnicode</var> function is available as of version 7.3 of the <var class=product>Sirius Mods</var>.
@@ Line 9: / Line 9: @@
 <table class="syntaxTable">
 <tr><th>%unicode</th>
-<td>A string variable to receive the method object string translated to Unicode. </td></tr>
+<td>A string variable to receive the method object string translated to <var>Unicode</var>. </td></tr>
 <tr><th>string</th>
-<td>A String or Longstring that is presumed to contain a UTF-8 byte stream.</td></tr>
+<td>A <var>String</var> or <var>Longstring</var> that is presumed to contain a UTF-8 byte stream.</td></tr>
 </table>
@@ Line 23: / Line 23: @@
 ==Usage notes==
 *[[Utf8 and Utf16]] has more information about UTF-8 conversions.
-*The [[Utf16ToUnicode (String function)|Utf16ToUnicode]] method converts a UTF-16 byte stream to Unicode.
+*The [[Utf16ToUnicode (String function)|Utf16ToUnicode]] method converts a UTF-16 byte stream to <var>Unicode</var>.
-*The [[UnicodeToUtf8 (String function)|UnicodeToUtf8]] method converts a Unicode string to a UTF-8 Longstring byte stream.
+*The [[UnicodeToUtf8 (String function)|UnicodeToUtf8]] method converts a <var>Unicode</var> string to a UTF-8 <var>Longstring</var> byte stream.
 ==Examples==
-In the following fragment, <var>Utf8ToUnicode</var> converts a hexadecimal input to a single Unicode character. In case the Unicode character translates to an EBCDIC character that cannot be displayed, the CharacterEncode option of the [[UnicodeToEbcdic (Unicode function)|UnicodeToEbcdic]] method
+In the following fragment, <var>Utf8ToUnicode</var> converts a hexadecimal input to a single <var>Unicode</var> character. In case the <var>Unicode</var> character translates to an EBCDIC character that cannot be displayed, the CharacterEncode option of the [[UnicodeToEbcdic (Unicode function)|UnicodeToEbcdic]] method
 causes the output of a hexadecimal character reference. The ''''[[X (String function)|X]]'''' constant function is used in the example.
-     %u Unicode
+     %u <var>Unicode</var>
      %u = 'E284A2':X:<var>Utf8ToUnicode</var>
      Print %u:unicodeToEbcdic(CharacterEncode=true)