CharacterTranslationException class: Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
m (minor cleanup)
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
<!-- CharacterTranslationException class -->
<!-- CharacterTranslationException class -->
__NOTOC__
__NOTOC__
Various methods throw a <var>CharacterTranslationException</var> exception when they encounter character translation problems. To avert request cancellation, you can <var>[[catch]]</var> such an exception, optionally catching to an object of this class.
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.
This class is available as of <var class="product">[[Sirius Mods]]</var> Version 7.3.
Line 10: Line 10:
The methods in the class are described in the subsections that follow. In addition:
The methods in the class are described in the subsections that follow. In addition:
<ul>
<ul>
<li>[[Notation conventions for methods|"Notation conventions for methods"]] has information
<li>[[Notation conventions for methods]] has information about the conventions followed. </li>
about the conventions followed.  
<li>[[CharacterTranslationException methods syntax]] is a single page that contains the syntax diagrams of all the methods in the class. </li>
<li>[[CharacterTranslationException methods syntax|"CharacterTranslationException methods syntax"]] is a single page that contains the syntax diagrams of all the methods in the class.
</ul>
</ul>


Line 18: Line 17:
==BytePosition property==
==BytePosition property==
{{Template:CharacterTranslationException:BytePosition subtitle}}
{{Template:CharacterTranslationException:BytePosition subtitle}}
===Syntax===
===Syntax===
{{Template:CharacterTranslationException:BytePosition syntax}}
{{Template:CharacterTranslationException:BytePosition syntax}}
====Syntax terms====
====Syntax terms====
<table class="syntaxTable">
<table>
<tr><th>%number</th>
<tr><th>%number</th>
<td>The position of the byte at which the exception was thrown.
<td>The position of the byte at which the exception was thrown.
Line 32: Line 33:
==CharacterPosition property==
==CharacterPosition property==
{{Template:CharacterTranslationException:CharacterPosition subtitle}}
{{Template:CharacterTranslationException:CharacterPosition subtitle}}
===Syntax===
===Syntax===
{{Template:CharacterTranslationException:CharacterPosition syntax}}
{{Template:CharacterTranslationException:CharacterPosition syntax}}
====Syntax terms====
====Syntax terms====
<table class="syntaxTable">
<table>
<tr><th>%number</th>
<tr><th>%number</th>
<td>The position of the character at which the exception was thrown.
<td>The position of the character at which the exception was thrown.
Line 48: Line 51:
that causes the exception:
that causes the exception:
<ul>
<ul>
<li>If EBCDIC, one byte corresponds to one character.
<li>If EBCDIC, one byte corresponds to one character. </li>
<li>If [[Unicode]], two bytes correspond to one character.
<li>If [[Unicode]], two bytes correspond to one character. </li>
<li>If UTF-16, two bytes correspond to one character.
<li>If UTF-16, two bytes correspond to one character. </li>
<li>If UTF-8, the relationship between bytes and characters is
<li>If UTF-8, the relationship between bytes and characters is variable, depending on the code points. </li>
variable, depending on the code points.
</ul> </li>
</ul></ul>
</ul>




==Description property==
==Description property==
{{Template:CharacterTranslationException:Description subtitle}}
{{Template:CharacterTranslationException:Description subtitle}}
===Syntax===
===Syntax===
{{Template:CharacterTranslationException:Description syntax}}
{{Template:CharacterTranslationException:Description syntax}}
====Syntax terms====
====Syntax terms====
<table class="syntaxTable">
<table>
<tr><th>%string</th>
<tr><th>%string</th>
<td>A string to receive the description of the exception.
<td>A string to receive the description of the exception.
</td></tr>
</td></tr>
<tr><th>characterTranslationException</th>
<tr><th>characterTranslationException</th>
<td>A reference to an instance of a <var>[[CharacterTranslationException_class|CharacterTranslationException]]</var> object.
<td>A reference to an instance of a <var>[[CharacterTranslationException_class|CharacterTranslationException]]</var> object.
 
</td></tr>
</td></tr></table>
</table>




==HexValue property==
==HexValue property==
{{Template:CharacterTranslationException:HexValue subtitle}}
{{Template:CharacterTranslationException:HexValue subtitle}}
===Syntax===
===Syntax===
{{Template:CharacterTranslationException:HexValue syntax}}
{{Template:CharacterTranslationException:HexValue syntax}}
====Syntax terms====
====Syntax terms====
<table class="syntaxTable">
<table>
<tr><th>%string</th>
<tr><th>%string</th>
<td>A string to receive the hexadecimal value of the bytes that caused the exception to be thrown.
<td>A string to receive the hexadecimal value of the bytes that caused the exception to be thrown.
</td></tr>
</td></tr>
<tr><th>characterTranslationException</th>
<tr><th>characterTranslationException</th>
<td>A reference to an instance of a <var>[[CharacterTranslationException_class|CharacterTranslationException]]</var> object.
<td>A reference to an instance of a <var>[[CharacterTranslationException_class|CharacterTranslationException]]</var> object.
</td></tr></table>
</td></tr>
</table>




Line 94: Line 104:


====Syntax terms====
====Syntax terms====
<table class="syntaxTable">
<table>
 
<tr><th>%characterTranslationException</th>
<tr><th>%characterTranslationException</th>
<td>A reference to the newly created instance of a <var>[[CharacterTranslationException_class|CharacterTranslationException]]</var> object.
<td>A reference to the newly created instance of a <var>[[CharacterTranslationException_class|CharacterTranslationException]]</var> object.
Line 105: Line 114:
<tr><th><var>Reason</var></th>
<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.
<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>
<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>
<tr><th><var>HexValue</var></th>
Line 112: Line 122:


<tr><th><var>BytePosition</var></th>
<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>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>
</td></tr>


Line 131: Line 141:


====Syntax terms====
====Syntax terms====
<table class="syntaxTable">
<table>
<tr><th>%translationExceptionReason</th>
<tr><th>%translationExceptionReason</th>
<td>This <var>TranslationExceptionReason</var> enumeration value (see below) describes the reason for the translation failure.
<td>This <var>TranslationExceptionReason</var> enumeration value (see below) describes the reason for the translation failure.
Line 142: Line 152:
====TranslationExceptionReason enumeration====
====TranslationExceptionReason enumeration====
A <var>TranslationExceptionReason</var> [[Enumerations|enumeration]] may have one of the following values:
A <var>TranslationExceptionReason</var> [[Enumerations|enumeration]] may have one of the following values:
<table>
<table class="thJustBold">
<tr><th>InvalidEncoding</th>
<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 D800 (which is in the surrogates range).</td></tr>
<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>
<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.
<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.
<p>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.</p></td></tr>
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>
<tr><th>UntranslatableCharacter</th>
<td>The following are examples of untranslatable characters (with the translation tables as delivered by Sirius):  
<td>The following are examples of untranslatable characters (with the translation tables as delivered by Sirius):  
<ul>
<ul>
<li>The EBCDIC input to the <var>[[EbcdicToUnicode_(String_function)|EbcdicToUnicode]]</var> method contains a byte whose hexadecimal value is X'FF.
<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 Unicode 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>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>
</ul></td></tr>


Line 162: Line 172:


===Usage notes===
===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"]].
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]]
[[Category:System exception classes]]

Latest revision as of 22:13, 18 November 2014


Various methods throw a CharacterTranslationException exception when they encounter character translation problems. To avert request cancellation, you can catch such an exception, optionally catching to an object of this class.

This class is available as of Sirius Mods Version 7.3.

The CharacterTranslationException methods

The following are the available CharacterTranslationException class methods.

MethodDescription
BytePositionPosition of byte at which the exception was thrown
CharacterPositionPosition of character at which the exception was thrown
DescriptionBrief description of the exception
HexValueHexadecimal value of bytes causing the exception
NewCreate a new CharacterTranslationException object
ReasonEnumerated cause of the exception

The methods in the class are described in the subsections that follow. In addition:


BytePosition property

Position of byte at which the exception was thrown (CharacterTranslationException class)

Syntax

%number = characterTranslationException:BytePosition

Syntax terms

%number The position of the byte at which the exception was thrown.
characterTranslationException A reference to an instance of a CharacterTranslationException object.


CharacterPosition property

Position of character at which the exception was thrown (CharacterTranslationException class)

Syntax

%number = characterTranslationException:CharacterPosition

Syntax terms

%number The position of the character at which the exception was thrown.
characterTranslationException A reference to an instance of a CharacterTranslationException object.

Usage notes

  • The number of bytes that constitute a character depends on the type of string that causes the exception:
    • If EBCDIC, one byte corresponds to one character.
    • If Unicode, two bytes correspond to one character.
    • If UTF-16, two bytes correspond to one character.
    • If UTF-8, the relationship between bytes and characters is variable, depending on the code points.


Description property

Brief description of the exception (CharacterTranslationException class)

Syntax

%string = characterTranslationException:Description

Syntax terms

%string A string to receive the description of the exception.
characterTranslationException A reference to an instance of a CharacterTranslationException object.


HexValue property

Hexadecimal value of bytes causing the exception (CharacterTranslationException class)

Syntax

%string = characterTranslationException:HexValue

Syntax terms

%string A string to receive the hexadecimal value of the bytes that caused the exception to be thrown.
characterTranslationException A reference to an instance of a CharacterTranslationException object.


New constructor

Create a new CharacterTranslationException object (CharacterTranslationException class)

Each argument to New sets the value of the corresponding property of the newly constructed CharacterTranslationException object.

Syntax

%characterTranslationException = [%(CharacterTranslationException):]New( Reason= translationExceptionReason, - [HexValue= string], - [BytePosition= number], - [CharacterPosition= number], - [Description= string])

Syntax terms

%characterTranslationException A reference to the newly created instance of a CharacterTranslationException object.
[%(CharacterTranslationException):] The class name in parentheses denotes a Constructor.
Reason Reason is a non-optional, name required parameter specifying the value to be assigned to the exception object's Reason property.

The TranslationExceptionReason enumeration values are InvalidEncoding, InvalidCharacterReference, and UntranslatableCharacter.

HexValue This name required parameter specifies the string value (string) to be assigned to the object's HexValue property.
BytePosition This name required parameter specifies the numeric value (number) to be assigned to the object's BytePosition property.
CharacterPosition This name required parameter specifies the numeric value (number) to be assigned to the object's CharacterPosition property.
Description This name required parameter specifies the string value (string) to be assigned to the object's Description property.

Reason property

Enumerated cause of the exception (CharacterTranslationException class)

Syntax

%translationExceptionReason = characterTranslationException:Reason

Syntax terms

%translationExceptionReason This TranslationExceptionReason enumeration value (see below) describes the reason for the translation failure.
characterTranslationException A reference to an instance of a CharacterTranslationException object.

TranslationExceptionReason enumeration

A TranslationExceptionReason enumeration may have one of the following values:

InvalidEncoding An example of invalid encoding is UTF-16 string input to Utf16ToUnicode that contains bytes whose hexadecimal value is D800 (which is in the surrogates range).
InvalidCharacterReference An XML-style hexadecimal character reference (for example, &#x2122; for the trademark character) may validly represent a Unicode character to be translated. Any other string that begins with by an ampersand (&) — except the string &amp; — might cause an exception explained by an InvalidCharacterReference enumeration. For example, such an exception occurs if EbcdicToUnicode is called, the method argument is CharacterDecode=True, and the method input contains an ampersand followed by a space.
UntranslatableCharacter The following are examples of untranslatable characters (with the translation tables as delivered by Sirius):
  • The EBCDIC input to the EbcdicToUnicode method contains a byte whose hexadecimal value is X'FF'.
  • The Unicode input to UnicodeToEbcdic contains one of the many Unicode characters that is not translated to an EBCDIC character (for example, U+20AC, the Euro currency symbol).
InvalidUrlEncoding This indicates that decoding of a URL failed in either the FormUrlDecodeUnicode or the UrlDecodeUnicode function.

Usage notes

As with all enumerations, the ToString 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 Common enumeration methods.