PageRenderTime 39ms CodeModel.GetById 10ms RepoModel.GetById 0ms app.codeStats 0ms

/AutoHotkey.docset/Contents/Resources/Documents/commands/SetFormat.htm

https://gitlab.com/ahkscript/Autohotkey.docset
HTML | 77 lines | 66 code | 11 blank | 0 comment | 0 complexity | c73eae983ada534039894adc28d92310 MD5 | raw file
    

  1. <!DOCTYPE HTML>
    2. 

  2. <html>
    3. 

  3. <head>
    4. 

  4. <title>SetFormat</title>
    5. 

  5. <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    6. 

  6. <meta http-equiv="X-UA-Compatible" content="IE=edge">
    7. 

  7. <link href="../static/theme.css" rel="stylesheet" type="text/css" />
    8. 

  8. <script src="../static/content.js" type="text/javascript"></script>
    9. 

  9. </head>
    10. 

  10. <body>
    11. 

  11. 

  12. <h1>SetFormat</h1>
    13. 

  13. 

  14. <p>Sets the format of integers and floating point numbers generated by math operations.</p>
    15. 

  15. 

  16. <pre class="Syntax">SetFormat, NumberType, Format</pre>
    17. 

  17. <h3>Parameters</h3>
    18. 

  18. <dl>
    19. 

  19. 

  20.   <dt>NumberType</dt>
    21. 

  21.   <dd><p>Must be either IntegerFast, FloatFast, Integer, or Float (the two fast modes require v1.0.48+; see <a href="#Fast">remarks</a>).</p></dd>
    22. 

  22. 

  23.   <dt>Format</dt>
    24. 

  24.   <dd><p>For <em>NumberType</em> Integer or IntegerFast, specify H or HEX for hexadecimal, or D for decimal. Hexadecimal numbers all start with the prefix 0x (e.g. 0xFF). <span class="ver">[AHK_L 42+]:</span> Hexadecimal integers are formatted with digits A-F in lowercase when this parameter is <code>h</code> and uppercase when it is <code>H</code>.</p>
    25. 

  25.       <p id="sci">For <em>NumberType</em> Float or FloatFast, specify <code>TotalWidth<strong>.</strong>DecimalPlaces</code> (e.g. <code>0.6</code>). In v1.0.46.11+, the letter &quot;e&quot; may be appended to produce scientific notation; e.g. <code>0.6e</code> or <code>0.6E</code> (using uppercase produces an uppercase E in each number instead of lowercase). Note: In AutoHotkey 1.x, scientific notation must include a decimal point; e.g. <code>1.0e1</code> is valid but not <code>1e1</code>.</p>
    26. 

  26.       <p><em>TotalWidth</em> is typically  0 to indicate that number should not have any blank or zero padding. If a higher value is used, numbers  will be padded with spaces or zeroes (see <a href="#Float">remarks</a>) to make them that wide.</p>
    27. 

  27.     <p id="DecimalPlaces"><em>DecimalPlaces</em> is the number of  decimal places to display (rounding will occur). If blank or zero, neither a  decimal portion nor a decimal point will be displayed, that is, floating point results are displayed as integers rather than a floating point number. The starting default is 6.</p>
    28. 

  28.     <p>Padding: If <em>TotalWidth</em> is high enough to cause padding, spaces will be added on the left side; that is, each number will be right-justified. To use left-justification instead, precede <em>TotalWidth</em> with a minus sign. To pad with zeroes instead of spaces, precede <em>TotalWidth</em> with a zero (e.g. <code>06.2</code>).</p></dd>
    29. 

  29. 

  30. </dl>
    31. 

  31. 

  32. <h3 id="Fast">Fast vs. Slow Mode</h3>
    33. 

  33. In v1.0.48+, IntegerFast may be used instead of Integer, and FloatFast may be used instead of Float.
    34. 

  34. <ul>
    35. 

  35. <li><strong>Advantages</strong>: The fast mode preserves the ability of variables to cache integers and floating point numbers, which substantially accelerates numerically-intensive operations. (By contrast, the slow mode forces all numeric results to be immediately converted and stored as strings.)</li>
    36. 

  36. <li id="FastDisadv"><strong>Disadvantages</strong>: When storing a number in a variable, the fast mode delays the effects of SetFormat until the script actually needs a text/string version of that variable (e.g. to display in a <a href="MsgBox.htm">MsgBox</a>). Since a different SetFormat may be in effect at that time (e.g. more or fewer decimal places), this can lead to unexpected results. To make the current fast format take effect immediately, use an operation like <code>HexValue <strong>.=</strong> &quot;&quot;</code>, which appends an empty string to the number currently stored in <em>HexValue</em>.</li>
    37. 

  37. </ul>
    38. 

  38. <p>If the slow mode &quot;Integer&quot; or &quot;Float&quot; is used anywhere in the script, even if that SetFormat line is never executed, the caching of integers or floating point numbers (respectively) is disabled the moment the script launches.</p>
    39. 

  39. <h3 id="Float">Floating Point Format</h3>
    40. 

  40. <p>In v1.0.48+, floating point variables have about 15 digits of precision internally unless <code>SetFormat Float</code> (i.e. the slow mode) is present anywhere in the script. In that case, the stored precision of floating point numbers is determined by <em><a href="#DecimalPlaces">DecimalPlaces</a></em> (like it was in pre-1.0.48 versions). In other words, once a floating point result is stored in a variable, the extra precision is lost and cannot be reclaimed without redoing the calculation with something like <code>SetFormat, Float, 0.15</code>. To avoid this loss of precision, avoid using <code>SetFormat Float</code> anywhere in the script, or use <a href="#Fast"><code>SetFormat FloatFast</code></a> instead.</p>
    41. 

  41. <p>Regardless of whether slow or fast mode is in effect, floating point results and variables are rounded off to <em><a href="#DecimalPlaces">DecimalPlaces</a></em> whenever they are displayed or converted to a string of text (e.g. <a href="MsgBox.htm">MsgBox</a> or <a href="FileAppend.htm">FileAppend</a>). To see the full precision, use something like <code>SetFormat, FloatFast, 0.15</code>.</p>
    42. 

  42. <p>To convert a floating point number to an integer, use <code>Var:=<a href="../Functions.htm#Round">Round</a>(Var)</code>, <code>Var:=<a href="../Functions.htm#Floor">Floor</a>(Var)</code>, or <code>Var:=<a href="../Functions.htm#Ceil">Ceil</a>(Var)</code>. To convert an integer to a floating point number, add 0.0 to it (e.g. <code>Var+=0.0</code>) or use something like <code>MyFloat:=<a href="../Functions.htm#Round">Round</a>(MyInteger, 1)</code>.</p>
    43. 

  43. <p>The built-in variable <strong>A_FormatFloat</strong> contains the current floating point format (e.g. <code>0.6</code>).</p>
    44. 

  44. <h3 id="Integer">Integer Format</h3>
    45. 

  45. <p>Integer results are normally displayed as decimal, not hexadecimal. To switch to hexadecimal, use <code>SetFormat, IntegerFast, Hex</code>. This may also be used to convert an integer from decimal to hexadecimal (or vice versa) as shown in the example at the very bottom of this page.</p>
    46. 

  46. <p>Literal integers specified in a script may be written as either hexadecimal or decimal. Hexadecimal integers all start with the prefix 0x (e.g. <code>0xA9</code>). They may be used anywhere a numerical value is expected. For example, <code>Sleep 0xFF</code> is equivalent to <code>Sleep 255</code> regardless of the current integer format set by SetFormat.</p>
    47. 

  47. <p>AutoHotkey supports 64-bit signed integers, which range from -9223372036854775808 (-0x8000000000000000) to 9223372036854775807 (0x7FFFFFFFFFFFFFFF).</p>
    48. 

  48. <p>The built-in variable <strong>A_FormatInteger</strong> contains the current integer format (H or D).</p>
    49. 

  49. <h3>General Remarks</h3>
    50. 

  50. <p>If SetFormat is not used in a script, integers default to decimal format, and floating point numbers default to <code>TotalWidth.DecimalPlaces</code> = <code>0.6</code>. Every newly launched <a href="../misc/Threads.htm">thread</a> (such as a <a href="../Hotkeys.htm">hotkey</a>, <a href="Menu.htm">custom menu item</a>, or <a href="SetTimer.htm">timed</a> subroutine) starts off fresh with these defaults; but the defaults may be changed by using SetFormat in the auto-execute section (top part of the script).</p>
    51. 

  51. <p>An old-style assignment like <code>x=%y%</code> omits any leading or trailing spaces (i.e. padding). To avoid this, use <a href="AutoTrim.htm">AutoTrim</a> or the <a href="SetExpression.htm">colon-equals operator</a> (e.g. <code>x:=y</code>).</p>
    52. 

  52. <p>You can determine whether a variable contains a numeric value by using &quot;<a href="IfIs.htm">if var is number/integer/float</a>&quot;</p>
    53. 

  53. <p>To pad an integer with zeros or spaces without having to use floating point math on it, follow this example:</p>
    54. 

  54. <pre>Var := &quot;          &quot; . Var     <em>; The quotes contain 10 spaces.  To pad with zeros, substitute zeros for the spaces.</em>
    55. 

  55. StringRight, Var, Var, 10  <em>; This pads the number in <i>Var</i> with enough spaces to make its total width 10 characters.</em>
    56. 

  56. Var := SubStr(&quot;          &quot; . Var, -9)  <em>; A single-line alternative to the above two lines.</em></pre>
    57. 

  57. 

  58. <h3>Related</h3>
    59. 

  59. <p><a href="Format.htm">Format()</a>, <a href="SetExpression.htm">Expression assignment (:=)</a>, <a href="EnvAdd.htm">EnvAdd</a>, <a href="EnvSub.htm">EnvSub</a>, <a href="EnvMult.htm">EnvMult</a>, <a href="EnvDiv.htm">EnvDiv</a>, <a href="AutoTrim.htm">AutoTrim</a>, <a href="IfIs.htm">if var is type</a></p>
    60. 

  60. 

  61. <h3>Examples</h3>
    62. 

  62. <pre class="NoIndent">Var = 11.333333
    63. 

  63. SetFormat, float, 6.2
    64. 

  64. Var -= 1  <em>; Sets Var to be 10.33 with one leading space because the total width is 6.</em>
    65. 

  65. SetFormat, float, 0.2
    66. 

  66. Var += 1  <em>; Sets Var to be 11.33 with no leading spaces.</em>
    67. 

  67. SetFormat, float, 06.0
    68. 

  68. Var += 0  <em>; Sets Var to be 000011</em>
    69. 

  69. 

  70. <em>; Convert a decimal integer to hexadecimal:</em>
    71. 

  71. SetFormat, IntegerFast, hex
    72. 

  72. Var += 0  <em>; Sets Var (which previously contained 11) to be 0xb</em>.
    73. 

  73. Var <strong>.</strong>= &quot;&quot;  <em>; Necessary due to the &quot;fast&quot; mode.</em>
    74. 

  74. SetFormat, IntegerFast, d</pre>
    75. 

  75. 

  76. </body>
    77. 

  77. </html>
    78. 

  78.