HexToString (String function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(25 intermediate revisions by 4 users not shown)
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.  
<var>HexToString</var> is an [[Intrinsic classes|intrinsic]] function that returns the unencoded value of a hex encoded string.
                                                                                                 
 
HexToString is available as of version 7.2 of the [[Sirius Mods]].                               
==Syntax==
==Syntax==
{{Template:String:HexToString syntax}}
{{Template:String:HexToString syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%outStr                                                                                        </th>
<tr><th>%outString</th>
<td>A string variable to receive the unencoded value of the                                       method object string.                                                                             </td></tr>
<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===                                                                                 
==Exceptions==
                                                                                                 
This [[Intrinsic classes|intrinsic]] function can throw the following exceptions:
This [[Intrinsic classes|intrinsic]] function can throw the following exceptions:                
<dl>
<dl>                                                                                              
<dt><var>[[InvalidHexData class|InvalidHexData]]</var>
<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.  
<ul><li>
*The HexToString function requires a method object string with an even number of bytes.  
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 displays a question mark (''''?'''') in a case where a converted hex value has no displayable character representation.  
<li><var>HexToString</var> requires a method object string with an even number of bytes.
*The [[X (String function)|X]] function is a compile-time only equivalent of the HexToString method. 
<li><var>HexToString</var> displays a question mark (<tt>?</tt>) in cases where a converted hex value has no displayable character representation.
*The inverse of HexToString is [[StringToHex (String function)|StringToHex]].
<li><var>HexToString</var> is available as of <var class="product">[[Sirius Mods|Sirius Mods]]</var> version 7.2.</ul>


==Examples==
==Examples==
*The following statement displays ''''Saint Marie'''':                              
<ol><li>The following statement displays <code>Saint Marie</code>:
    [[Intrinsic classes#printtext|printText]] {'E2818995A340D481998985':hexToString}        
<p class="code">[[PrintText statement|printText]] {'E2818995A340D481998985':hexToString}
*The following statement displays ''''??'''' because no displayable characters exist for the specified hex values:              
</p>
    printText {'FFFE':hexToString(signed=true)}
<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)}
===See also===                                                                                       
</p>
[[List of intrinsic String methods]]
</ol>


[[Category:Intrinsic String methods|HexToString function]]
==See also==
[[Category:Intrinsic methods]]
<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.