HexToString (String function): Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
m (→Examples) |
||
| (9 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:String:HexToString subtitle}} | {{Template:String:HexToString subtitle}} | ||
<var>HexToString</var> is an [[Intrinsic classes|intrinsic]] function that returns the unencoded value of a hex encoded string. | |||
==Syntax== | ==Syntax== | ||
{{Template:String:HexToString syntax}} | {{Template:String:HexToString syntax}} | ||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>% | <tr><th>%outString</th> | ||
<td>A string variable to receive the unencoded value of the | <td>A string variable to receive the unencoded value of the method object <var class="term">string</var>.</td></tr> | ||
<tr><th>string</th> | <tr><th>string</th> | ||
<td>A hex-encoded string value.</td></tr> | <td>A hex-encoded string value.</td></tr> | ||
</table> | </table> | ||
==Exceptions== | |||
This [[Intrinsic classes|intrinsic]] function can throw the following exceptions: | This [[Intrinsic classes|intrinsic]] function can throw the following exceptions: | ||
<dl> | <dl> | ||
<dt>[[InvalidHexData]] | <dt><var>[[InvalidHexData class|InvalidHexData]]</var> | ||
<dd>If the method object string does not contain a properly encoded hexadecimal value. | <dd>If the method object string does not contain a properly encoded hexadecimal value. | ||
The exception object indicates the position of the first invalid character | The exception object indicates the position of the first invalid character | ||
| Line 24: | Line 22: | ||
string had an odd number of characters. | string had an odd number of characters. | ||
</dl> | </dl> | ||
==Usage notes== | ==Usage notes== | ||
<ul><li> | |||
Hex (short for hexadecimal) encoding is usually used for debugging when there is a concern that non-displayable characters (including trailing blanks) might be present in a string. By hex-encoding such a string, all non-displayable bytes are converted to displayable hexadecimal equivalents. | |||
<li><var>HexToString</var> requires a method object string with an even number of bytes. | |||
<li><var>HexToString</var> displays a question mark (<tt>?</tt>) in cases where a converted hex value has no displayable character representation. | |||
<li><var>HexToString</var> is available as of <var class="product">[[Sirius Mods|Sirius Mods]]</var> version 7.2.</ul> | |||
==Examples== | ==Examples== | ||
<ol><li>The following statement displays <code>Saint Marie</code>: | |||
<p class="code">[[ | <p class="code">[[PrintText statement|printText]] {'E2818995A340D481998985':hexToString} | ||
</p> | </p> | ||
<li>The following statement displays <code>??</code> because no displayable characters exist for the specified hex values: | |||
<p class="code">printText {'FFFE':hexToString(signed=true)} | <p class="code">printText {'FFFE':hexToString(signed=true)} | ||
</p> | |||
</ol> | |||
==See also== | ==See also== | ||
<ul><li>[[X (String function)|X]] is a compile-time only equivalent of the <var>HexToString</var> method. | |||
<li>The inverse of <var>HexToString</var> is <var>[[StringToHex (String function)|StringToHex]]</var>.</ul> | |||
{{Template:String:HexToString footer}} | {{Template:String:HexToString footer}} | ||
Latest revision as of 20:58, 2 November 2012
Convert a hexadecimal string to Ebcdic (String class)
HexToString is an intrinsic function that returns the unencoded value of a hex encoded string.
Syntax
%outString = string:HexToString Throws InvalidHexData
Syntax terms
| %outString | A string variable to receive the unencoded value of the method object string. |
|---|---|
| string | A hex-encoded string value. |
Exceptions
This intrinsic function can throw the following exceptions:
- InvalidHexData
- If the method object string does not contain a properly encoded hexadecimal value. The exception object indicates the position of the first invalid character in the method object string, or it indicates a zero if the method object string had an odd number of characters.
Usage notes
- Hex (short for hexadecimal) encoding is usually used for debugging when there is a concern that non-displayable characters (including trailing blanks) might be present in a string. By hex-encoding such a string, all non-displayable bytes are converted to displayable hexadecimal equivalents.
- HexToString requires a method object string with an even number of bytes.
- HexToString displays a question mark (?) in cases where a converted hex value has no displayable character representation.
- HexToString is available as of Sirius Mods version 7.2.
Examples
- The following statement displays
Saint Marie:printText {'E2818995A340D481998985':hexToString}
- The following statement displays
??because no displayable characters exist for the specified hex values:printText {'FFFE':hexToString(signed=true)}
See also
- X is a compile-time only equivalent of the HexToString method.
- The inverse of HexToString is StringToHex.