Utf16ToUnicode (String function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
m (minor cleanup)
 
(45 intermediate revisions by 8 users not shown)
Line 1: Line 1:
This [[Intrinsic classes|intrinsic]] function converts a UTF-16 Longstring byte stream to Unicode.
{{Template:String:Utf16ToUnicode subtitle}}
The Utf16ToUnicode function is available as of version 7.3 of the [[Sirius Mods]].   
The <var>Utf16ToUnicode</var> [[Intrinsic classes|intrinsic]] function converts a UTF-16 <var>Longstring</var> byte stream to <var>Unicode</var>.
===Utf16ToUnicode syntax===
  %unicode = string:Utf16ToUnicode      
===Syntax Terms===
<dl>                                                                                                  
<dt>%unicode                                                                                           
<dd>A string variable to receive the method object string translated to Unicode.
<dt>string                                                                                             
<dd>A String or Longstring that is presumed to contain a UTF-16 byte stream.
                                                                                                       
</dl>                                                                                                  
===Exceptions===                                                                                       
This [[Intrinsic classes|intrinsic]] function can throw the following exception:
<dl>                                                                                                  
<dt>[[CharacterTranslationException]]                                                                 
<dd>If the method encounters a translation problem,
properties of the exception object may indicate the location and type of problem.
</dl>                                                                                                  
===Usage Notes===                             
*The input UTF-16 stream may contain a Byte Order Mark (U+FEFF). If one is present, that controls the conversion from UTF-16 to Unicode. If a Byte Order Mark is not present, the input stream is considered to be a Big Endian stream, that is, it is the same as if the stream were preceded by the two bytes X'FE' and X'FF', in that order.
*[[UTF-8 and UTF-16]] has more information about UTF-16 conversions.    
*The [[Utf8ToUnicode (String function)|Utf8ToUnicode]] method converts a UTF-8 byte stream to Unicode.
===Examples===
             
In the following fragment, Utf16ToUnicode converts a hexadecimal input to a single Unicode character. The ''''[[X (String function)|X]]'''' constant function is used in the example.   
    %u Unicode                                                                                     
    %u = '0032':X:Utf16ToUnicode                                                                   
    Print %u                                                                                       
The result is:                                                                                     
    2                                                                                               


[[Category:Intrinsic String methods|Utf16ToUnicode function]]
==Syntax==
[[Category:Intrinsic methods]]                                                                      
{{Template:String:Utf16ToUnicode syntax}}
[[Category:System methods]]
 
===Syntax terms===
<table>
<tr><th>%unicode</th>
<td>A <var>Unicode</var> string variable to receive the method object <var class="term">string</var> translated to <var>Unicode</var>. </td></tr>
 
<tr><th>string</th>
<td>A string that is presumed to contain a UTF-16 byte stream.</td></tr>
 
<tr><th><var>AllowUntranslatable</var></th>
<td>This argument indicates whether this function will store values into the target <var>Unicode</var> string that cannot be translated to EBCDIC. This value defaults to <var>True</var>, which means that such values are allowed. If this argument is set to <var>False</var>, a Unicode value not translatable to EBCDIC produces a [[CharacterTranslationException class|CharacterTranslationException exception]].
<p>
Unless there is a compelling reason to do otherwise, it is best to use the default value of <var>True</var>.</p></td></tr>
 
<tr><th><var>BOM</var></th>
<td>This Byte Order Mark argument is <i><b>usable only by Rocket Software</b>. [[Contacting Rocket Software Technical Support|Contact Rocket Software]] if you think this argument might be of value to you.</i>
<p>
<var>BOM</var> is a name required parameter with a value that is a <var>Utf16Bom</var> enumeration. </p></td></tr>
</table>
 
===Exceptions===
<var>Utf16ToUnicode</var> can throw the following exception:
<dl>
<dt><var>[[CharacterTranslationException_class|CharacterTranslationException]]</var>
<dd>If the method encounters a translation problem, properties of the exception object may indicate the location and type of problem.
</dl>
 
==Usage notes==
<ul>
<li>The input UTF-16 stream may contain a Byte Order Mark (U+FEFF).<ul><li>If one is present, that controls the conversion from UTF-16 to <var>Unicode</var>.<li> If a Byte Order Mark is not present, the input stream is considered to be a Big Endian stream: that is, it is the same as if the stream were preceded by the two bytes X'FE' and X'FF', in that order.</ul>
</ul>
 
==Examples==
In the following fragment, <var>Utf16ToUnicode</var> converts a hexadecimal input to a single <var>Unicode</var> character:
<p class="code">%u unicode
%u = '0032':[[X (String function)|X]]:Utf16ToUnicode
print %u
</p>
The result is:
<p class="output">2
</p>
 
==See also==
<ul>
<li>[[Unicode#UTF-8 and UTF-16|UTF-8 and UTF-16]] has more information about UTF-16 conversions. </li>
 
<li>The <var>[[Utf8ToUnicode (String function)|Utf8ToUnicode]]</var> method converts a UTF-8 byte stream to <var>Unicode</var>. </li>
</ul>
 
{{Template:String:Utf16ToUnicode footer}}

Latest revision as of 19:35, 13 April 2016

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

The Utf16ToUnicode intrinsic function converts a UTF-16 Longstring byte stream to Unicode.

Syntax

%unicode = string:Utf16ToUnicode[( [AllowUntranslatable= boolean], - [Bom= utf16BOM])] Throws CharacterTranslationException

Syntax terms

%unicode A Unicode string variable to receive the method object string translated to Unicode.
string A string that is presumed to contain a UTF-16 byte stream.
AllowUntranslatable This argument indicates whether this function will store values into the target Unicode string that cannot be translated to EBCDIC. This value defaults to True, which means that such values are allowed. If this argument is set to False, a Unicode value not translatable to EBCDIC produces a CharacterTranslationException exception.

Unless there is a compelling reason to do otherwise, it is best to use the default value of True.

BOM This Byte Order Mark argument is usable only by Rocket Software. Contact Rocket Software if you think this argument might be of value to you.

BOM is a name required parameter with a value that is a Utf16Bom enumeration.

Exceptions

Utf16ToUnicode 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

  • The input UTF-16 stream may contain a Byte Order Mark (U+FEFF).
    • If one is present, that controls the conversion from UTF-16 to Unicode.
    • If a Byte Order Mark is not present, the input stream is considered to be a Big Endian stream: that is, it is the same as if the stream were preceded by the two bytes X'FE' and X'FF', in that order.

Examples

In the following fragment, Utf16ToUnicode converts a hexadecimal input to a single Unicode character:

%u unicode %u = '0032':X:Utf16ToUnicode print %u

The result is:

2

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Utf16ToUnicode_(String_function)&oldid=83751"