HexToString (String function): Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
m (1 revision) |
||
| Line 1: | Line 1: | ||
{{Template:String:HexToString subtitle}} | {{Template:String:HexToString subtitle}} | ||
This [[Intrinsic classes|intrinsic]] function returns the unencoded value of a hex encoded string. | This [[Intrinsic classes|intrinsic]] function returns the unencoded value of a hex encoded string. | ||
HexToString is available as of version 7.2 of the [[Sirius Mods]]. | HexToString is available as of version 7.2 of the [[Sirius Mods]]. | ||
==Syntax== | ==Syntax== | ||
{{Template:String:HexToString syntax}} | {{Template:String:HexToString syntax}} | ||
| Line 13: | Line 13: | ||
<td>A hex-encoded string value.</td></tr> | <td>A hex-encoded string value.</td></tr> | ||
</table> | </table> | ||
===Exceptions=== | ===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>[[InvalidHexData]] | ||
<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 | ||
in the method object string, or it indicates a zero if the method object | in the method object string, or it indicates a zero if the method object | ||
string had an odd number of characters. | string had an odd number of characters. | ||
</dl> | </dl> | ||
==Usage notes== | ==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. | *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. | ||
*The HexToString function requires a method object string with an even number of bytes. | *The HexToString function requires a method object string with an even number of bytes. | ||
*HexToString displays a question mark (''''?'''') in a case where a converted hex value has no displayable character representation. | *HexToString displays a question mark (''''?'''') in a case where a converted hex value has no displayable character representation. | ||
*The [[X (String function)|X]] function is a compile-time only equivalent of the HexToString method. | *The [[X (String function)|X]] function is a compile-time only equivalent of the HexToString method. | ||
*The inverse of HexToString is [[StringToHex (String function)|StringToHex]]. | *The inverse of HexToString is [[StringToHex (String function)|StringToHex]]. | ||
==Examples== | ==Examples== | ||
*The following statement displays ''''Saint Marie'''': | *The following statement displays ''''Saint Marie'''': | ||
[[Intrinsic classes#printtext|printText]] {'E2818995A340D481998985':hexToString} | [[Intrinsic classes#printtext|printText]] {'E2818995A340D481998985':hexToString} | ||
*The following statement displays ''''??'''' because no displayable characters exist for the specified hex values: | *The following statement displays ''''??'''' because no displayable characters exist for the specified hex values: | ||
printText {'FFFE':hexToString(signed=true)} | printText {'FFFE':hexToString(signed=true)} | ||
===See also=== | ===See also=== | ||
[[List of intrinsic String methods]] | [[List of intrinsic String methods]] | ||
[[Category:Intrinsic String methods|HexToString function]] | [[Category:Intrinsic String methods|HexToString function]] | ||
[[Category:Intrinsic methods]] | [[Category:Intrinsic methods]] | ||
Revision as of 14:04, 19 January 2011
Convert a hexadecimal string to Ebcdic (String class)
This intrinsic function returns the unencoded value of a hex encoded string.
HexToString is available as of version 7.2 of the Sirius Mods.
Syntax
%outString = string:HexToString Throws InvalidHexData
Syntax terms
| %outStr | 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.
- The HexToString function requires a method object string with an even number of bytes.
- HexToString displays a question mark ('?') in a case where a converted hex value has no displayable character representation.
- The X function is a compile-time only equivalent of the HexToString method.
- The inverse of HexToString is StringToHex.
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)}