UnicodeToUtf8 (Unicode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (syntax terms, tags and links)
Line 1: Line 1:
{{Template:Unicode:UnicodeToUtf8 subtitle}}
{{Template:Unicode:UnicodeToUtf8 subtitle}}
<var>UnicodeToUtf8</var> converts a <var>Unicode</var> string to a UTF-8 <var>Longstring</var> byte stream.


This function converts a <var>Unicode</var> string to a UTF-8
<var>Longstring</var> byte stream.
The <var>UnicodeToUtf8</var> function is available as of version 7.3 of the <var class=product>Sirius Mods</var>.
==Syntax==
==Syntax==
{{Template:Unicode:UnicodeToUtf8 syntax}}
{{Template:Unicode:UnicodeToUtf8 syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%utf8Stream</th>
<tr><th>%string</th>
<td>A <var>String</var> or <var>Longstring</var> variable to receive the method object string translated to a UTF-8 byte stream. </td></tr>
<td>A <var>String</var> or <var>Longstring</var> variable to receive the method object string translated to a UTF-8 byte stream.</td></tr>
<tr><th>unicode</th>
<tr><th>unicode</th>
<td>A <var>Unicode</var> string. </td></tr>
<td>A <var>Unicode</var> string.</td></tr>
<tr><th>InsertBOM=bool</th>
<tr><th>InsertBOM</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, encoded as X'EFBBBF') 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>
<td>The optional (<var>[[Methods#Named parameters|Name-Required]]</var>) <var class="term">InsertBOM</var> argument is a Boolean:<ul><li>If its value is <code>True</code>, the "Byte Order Mark" (U+FEFF, encoded as X'EFBBBF') is inserted at the start of the output stream.<li>If its value is <code>False</code>, the default, no Byte Order Mark is inserted.</ul></td></tr>
</table>
</table>
===Exceptions===
===Exceptions===
 
<var>UnicodeToUtf8</var> can throw the following exception:
This function can throw the following exception:
<dl>
<dl>
<dt><var>CharacterTranslationException</var>
<dt><var>[[CharacterTranslationException class|CharacterTranslationException]]</var>
<dd>If the method encounters a translation problem,
<dd>If the method encounters a translation problem, properties of the exception object may indicate the location and type of problem.
properties of the exception object may indicate the location and type of problem.
See [[CharacterTranslationException exception class]].
</dl>
</dl>


==Usage notes==
==Usage notes==
<ul>
<ul><li><var>UnicodeToUtf8</var> is available as of <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.3.</ul>
<li>For more information about UTF-8 conversions, see [[Unicode#UTF-8 and UTF-16]].
 
<li>The [[UnicodeToUtf16 (Unicode function)|UnicodeToUtf16]] method
converts a <var>Unicode</var> string to UTF-16.
<li>The [[Utf8ToUnicode (String function)|Utf8ToUnicode]] method
converts a UTF-8 <var>Longstring</var> byte stream to <var>Unicode</var>.
</ul>
==Examples==
==Examples==
 
<ol><li>In the following fragment, <var>UnicodeToUtf8</var> is used to show how the <var>Unicode</var> U+B2 character (superscript 2) is represented in UTF-8. Appending the <var>StringToHex</var> method is useful for viewing the hex values of characters that do not have displayable EBCDIC equivalents.
In the following fragment, <var>UnicodeToUtf8</var> is used to show how the
<p class="code">%u unicode initial('&amp;#xB2;':[[U (String function)|U]])
<var>Unicode</var> U+B2 character (superscript 2) is represented in UTF-8.
print %u:UnicodeToUtf8:[[StringToHex (String function)|stringToHex]]
Appending the <var>StringToHex</var> method is useful for viewing
the hex values of characters that do not have displayable EBCDIC equivalents.
 
The [[U (String function)|U constant function]] and [[StringToHex (String function)|StringToHex]] function
are used in the example.
<p class="code">%u Unicode Initial('&amp;#xB2;':U)
Print %u:UnicodeToUtf8:StringToHex
</p>
</p>
The result is:
The result is:
<p class="output">C2B2
<p class="output">C2B2
</p>
</p></ol>


==See also==
==See also==
<ul><li>For more information about UTF-8 conversions, see [[Unicode#UTF-8 and UTF-16|"Unicode: UTF-8 and UTF-16"]].
<li><var>[[UnicodeToUtf16 (Unicode function)|UnicodeToUtf16]]</var> converts a <var>Unicode</var> string to UTF-16.
<li><var>[[Utf8ToUnicode (String function)|Utf8ToUnicode]]</var> converts a UTF-8 <var>Longstring</var> byte stream to <var>Unicode</var>.
</ul>
{{Template:Unicode:UnicodeToUtf8 footer}}
{{Template:Unicode:UnicodeToUtf8 footer}}

Revision as of 05:55, 25 February 2011

Translate to UTF-8 (Unicode class)

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

Syntax

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

Syntax terms

%string A String or Longstring variable to receive the method object string translated to a UTF-8 byte stream.
unicode A Unicode string.
InsertBOM 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

UnicodeToUtf8 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

Examples

  1. 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.

    %u unicode initial('&#xB2;':U) print %u:UnicodeToUtf8:stringToHex

    The result is:

    C2B2

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=UnicodeToUtf8_(Unicode_function)&oldid=12263"