View source for CharacterTranslationException class

<!-- CharacterTranslationException class -->
__NOTOC__
Various methods throw a <var>CharacterTranslationException</var> exception when they encounter character translation problems. To avert request cancellation, you can <var>[[Exceptions#Try and Catch|catch]] </var> such an exception, optionally catching to an object of this class.
 
This class is available as of <var class="product">[[Sirius Mods]]</var> Version 7.3.

==The CharacterTranslationException methods==
{{Template:List of CharacterTranslationException methods}}

The methods in the class are described in the subsections that follow. In addition:
<ul>
<li>[[Notation conventions for methods]] has information about the conventions followed. </li>
<li>[[CharacterTranslationException methods syntax]] is a single page that contains the syntax diagrams of all the methods in the class. </li>
</ul>


==BytePosition property==
{{Template:CharacterTranslationException:BytePosition subtitle}}

===Syntax===
{{Template:CharacterTranslationException:BytePosition syntax}}

====Syntax terms====
<table>
<tr><th>%number</th>
<td>The position of the byte at which the exception was thrown.
</td></tr>
<tr><th>characterTranslationException</th>
<td>A reference to an instance of a <var>[[CharacterTranslationException_class|CharacterTranslationException]]</var> object.
</td></tr></table>


==CharacterPosition property==
{{Template:CharacterTranslationException:CharacterPosition subtitle}}

===Syntax===
{{Template:CharacterTranslationException:CharacterPosition syntax}}

====Syntax terms====
<table>
<tr><th>%number</th>
<td>The position of the character at which the exception was thrown.
</td></tr>
<tr><th>characterTranslationException</th>
<td>A reference to an instance of a <var>[[CharacterTranslationException_class|CharacterTranslationException]]</var> object.
</td></tr></table>

===Usage notes===
<ul>
<li>The number of bytes that constitute a character depends on the type of string
that causes the exception:
<ul>
<li>If EBCDIC, one byte corresponds to one character. </li>
<li>If [[Unicode]], two bytes correspond to one character. </li>
<li>If UTF-16, two bytes correspond to one character. </li>
<li>If UTF-8, the relationship between bytes and characters is variable, depending on the code points. </li>
</ul> </li>
</ul>


==Description property==
{{Template:CharacterTranslationException:Description subtitle}}

===Syntax===
{{Template:CharacterTranslationException:Description syntax}}

====Syntax terms====
<table>
<tr><th>%string</th>
<td>A string to receive the description of the exception.
</td></tr>

<tr><th>characterTranslationException</th>
<td>A reference to an instance of a <var>[[CharacterTranslationException_class|CharacterTranslationException]]</var> object.
</td></tr>
</table>


==HexValue property==
{{Template:CharacterTranslationException:HexValue subtitle}}

===Syntax===
{{Template:CharacterTranslationException:HexValue syntax}}

====Syntax terms====
<table>
<tr><th>%string</th>
<td>A string to receive the hexadecimal value of the bytes that caused the exception to be thrown.
</td></tr>

<tr><th>characterTranslationException</th>
<td>A reference to an instance of a <var>[[CharacterTranslationException_class|CharacterTranslationException]]</var> object.
</td></tr>
</table>


==New constructor==
{{Template:CharacterTranslationException:New subtitle}}

Each argument to <var>New</var> sets the value of the corresponding property of the newly constructed <var>CharacterTranslationException</var> object.

===Syntax===
{{Template:CharacterTranslationException:New syntax}}

====Syntax terms====
<table>
<tr><th>%characterTranslationException</th>
<td>A reference to the newly created instance of a <var>[[CharacterTranslationException_class|CharacterTranslationException]]</var> object.
</td></tr>

<tr><th><var>[%(CharacterTranslationException):]</var></th>
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>. </td></tr>

<tr><th><var>Reason</var></th>
<td><var>Reason</var> is a <b><i>non-</i></b>optional, [[Methods#Named parameters|name required]] parameter specifying the value to be assigned to the exception object's <var>[[Reason (CharacterTranslationException property)|Reason]]</var> property.
<p>
The <var>[[#TranslationExceptionReason enumeration|TranslationExceptionReason]]</var> enumeration values are <var>InvalidEncoding</var>, <var>InvalidCharacterReference</var>, and <var>UntranslatableCharacter</var>.</p></td></tr>

<tr><th><var>HexValue</var></th>
<td>This  name required parameter specifies the string value (<var class="term">string</var>) to be assigned to the object's <var>[[HexValue_(CharacterTranslationException_property)|HexValue]]</var> property.
</td></tr>

<tr><th><var>BytePosition</var></th>
<td>This name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[BytePosition_(CharacterTranslationException_property)|BytePosition]]</var> property.
</td></tr>

<tr><th><var>CharacterPosition</var></th>
<td>This  name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[CharacterPosition_(CharacterTranslationException_property)|CharacterPosition]]</var> property.
</td></tr>

<tr><th><var>Description</var></th>
<td>This name required parameter specifies the string value (<var class="term">string</var>) to be assigned to the object's <var>[[Description_(CharacterTranslationException_property)|Description]]</var> property.
</td></tr>
</table>

==Reason property==
{{Template:CharacterTranslationException:Reason subtitle}}

===Syntax===
{{Template:CharacterTranslationException:Reason syntax}}

====Syntax terms====
<table>
<tr><th>%translationExceptionReason</th>
<td>This <var>TranslationExceptionReason</var> enumeration value (see below) describes the reason for the translation failure.
</td></tr>

<tr><th>characterTranslationException</th>
<td>A reference to an instance of a <var>[[CharacterTranslationException_class|CharacterTranslationException]]</var> object.
</td></tr></table>

====TranslationExceptionReason enumeration====
A <var>TranslationExceptionReason</var> [[Enumerations|enumeration]] may have one of the following values:
<table class="thJustBold">
<tr><th>InvalidEncoding</th>
<td>An example of invalid encoding is UTF-16 string input to <var>[[Utf16ToUnicode (String function)|Utf16ToUnicode]]</var> that contains bytes whose hexadecimal value is <code>D800</code> (which is in the surrogates range).</td></tr>

<tr><th>InvalidCharacterReference</th>
<td>An XML-style hexadecimal character reference (for example, <code>&amp;#x2122;</code> for the trademark character) may validly represent a Unicode character to be translated.  Any other string that begins with by an ampersand (&amp;) &mdash; except the string <code>&amp;amp;</code> &mdash; might cause an exception explained by an <var>InvalidCharacterReference</var> enumeration.
For example, such an exception occurs if <var>[[EbcdicToUnicode (String function)|EbcdicToUnicode]]</var> is called, the method argument is <code>CharacterDecode=True</code>, and the method input contains an ampersand followed by a space.</td></tr>

<tr><th>UntranslatableCharacter</th>
<td>The following are examples of untranslatable characters (with the translation tables as delivered by Sirius): 
<ul>
<li>The EBCDIC input to the <var>[[EbcdicToUnicode_(String_function)|EbcdicToUnicode]]</var> method contains a byte whose hexadecimal value is <code>X'FF'</code>. </li>
<li>The <var>Unicode</var> input to <var>[[UnicodeToEbcdic (Unicode function)|UnicodeToEbcdic]]</var> contains one of the many Unicode characters that is not translated to an EBCDIC character (for example, <code>U+20AC</code>, the Euro currency symbol). </li>
</ul></td></tr>

<tr><th>InvalidUrlEncoding</th>
<td>This indicates that decoding of a URL failed in either the <var>[[FormUrlDecodeUnicode (String function)|FormUrlDecodeUnicode]]</var> or the <var>[[UrlDecodeUnicode (String function)|UrlDecodeUnicode]]</var> function.</td></tr>
</table>

===Usage notes===
As with all enumerations, the <var>ToString</var> method implicitly converts an enumeration value to a character string whose value is the name of the enumeration value. For more information about methods available to all enumerations, see [[Enumerations#Common enumeration methods|Common enumeration methods]].

[[Category:System exception classes]]