HexToString (String function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(29 intermediate revisions by 5 users not shown)
Line 1: Line 1:
This [[Intrinsic classes|intrinsic]] function returns the unencoded value of a hex encoded string.
{{Template:String:HexToString subtitle}}
                                                                                                 
HexToString is available as of version 7.2 of the [[Sirius Mods]].                               
===HexToString syntax===                                                                         
  %outStr = string:hexToString                                                                   
===Syntax Terms===                                                                               
<dl>                                                                                             
<dt>%outStr                                                                                       
<dd>A string variable to receive the unencoded value of the                                       
method object string.                                                                             
<dt>string                                                                                       
<dd>A hex-encoded string value.                                                                   
                                                                                                 
</dl>                                                                                             
===Exceptions===                                                                                 
                                                                                                 
This [[Intrinsic classes|intrinsic]] function can throw the following exceptions:                
<dl>                                                                                             
<dt>[[InvalidHexData]]                                                                           
<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                       
in the method object string, or it indicates a zero if the method object                         
string had an odd number of characters.                                                           
</dl>                                                                                             
===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 (String function)|X]] function is a compile-time only equivalent of the HexToString method. 
*The inverse of HexToString is [[StringToHex (String function)|StringToHex]].


===Examples===                                                                     
<var>HexToString</var> is an [[Intrinsic classes|intrinsic]] function that returns the unencoded value of a hex encoded string.
*The following statement displays ''''Saint Marie'''':                             
    [[Intrinsic classes#printtext|printText]] {'E2818995A340D481998985':hexToString}       
*The following statement displays ''''??'''' because no displayable characters exist for the specified hex values:               
    printText {'FFFE':hexToString(signed=true)}


===See also===                                                                                        
==Syntax==
[[List of intrinsic String methods]]
{{Template:String:HexToString syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%outString</th>
<td>A string variable to receive the unencoded value of the method object <var class="term">string</var>.</td></tr>
<tr><th>string</th>
<td>A hex-encoded string value.</td></tr>
</table>


[[Category:Intrinsic String methods|HexToString function]]
==Exceptions==
[[Category:Intrinsic methods]]
This [[Intrinsic classes|intrinsic]] function can throw the following exceptions:
<dl>
<dt><var>[[InvalidHexData class|InvalidHexData]]</var>
<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
in the method object string, or it indicates a zero if the method object
string had an odd number of characters.
</dl>
 
==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==
<ol><li>The following statement displays <code>Saint Marie</code>:
<p class="code">[[PrintText statement|printText]] {'E2818995A340D481998985':hexToString}
</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>
</ol>
 
==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}}

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

  1. The following statement displays Saint Marie:

    printText {'E2818995A340D481998985':hexToString}

  2. 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.
Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=HexToString_(String_function)&oldid=884"