PageRenderTime 51ms CodeModel.GetById 22ms RepoModel.GetById 1ms app.codeStats 0ms

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

https://gitlab.com/ahkscript/Autohotkey.docset
HTML | 91 lines | 83 code | 8 blank | 0 comment | 0 complexity | e8698b2022ea42db620a91f2bebce176 MD5 | raw file
    

  1. <!DOCTYPE HTML>
    2. 

  2. <html>
    3. 

  3. <head>
    4. 

  4. <title>Transform</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>Transform</h1>
    13. 

  13. 

  14. <p>Performs miscellaneous math functions, bitwise operations, and tasks such as ASCII/Unicode conversion.</p>
    15. 

  15. 

  16. <pre class="Syntax">Transform, OutputVar, Cmd, Value1 [, Value2]</pre>
    17. 

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

  18. <dl>
    19. 

  19. 

  20.   <dt>OutputVar</dt>
    21. 

  21.   <dd><p>The name of the variable in which to store the result of <em>Cmd</em>. <a href="SetFormat.htm">SetFormat</a> determines whether integers are stored as hexadecimal or decimal.</p></dd>
    22. 

  22. 

  23.   <dt>Cmd, Value1/2</dt>
    24. 

  24.   <dd><p>See list below.</p></dd>
    25. 

  25. 

  26. </dl>
    27. 

  27. 

  28. <h3>Cmd, Value1, Value2</h3>
    29. 

  29. <p>The <em>Cmd</em>, <em>Value1</em> and <em>Value2</em> parameters are dependent upon each other and their usage is described below.</p>
    30. 

  30. <p id="Unicode"><strong>Unicode [, String]</strong>: <em>(This command is not available in Unicode versions of AutoHotkey.)</em> Retrieves or stores Unicode text on the clipboard. Note: The entire clipboard may be saved and restored by means of <a href="../misc/Clipboard.htm#ClipboardAll">ClipboardAll</a>, which allows &quot;Transform Unicode&quot; to operate without losing the original contents of the clipboard.</p>
    31. 

  31. <p>There are two modes of operation as illustrated in the following examples:</p>
    32. 

  32. <pre>Transform, OutputVar, Unicode  <em>; Retrieves the clipboard's Unicode text as a UTF-8 string.</em>
    33. 

  33. Transform, Clipboard, Unicode, %MyUTF_String%  <em>; Places Unicode text onto the clipboard.</em></pre>
    34. 

  34. <p>In the second example above, a literal UTF-8 string may be optionally used in place of %MyUTF_String%.</p>
    35. 

  35. <p>Use a hotkey such as the following to determine the UTF-8 string that corresponds to a given Unicode string:</p>
    36. 

  36. <pre>^!u::  <em>; Control+Alt+U hotkey.</em>
    37. 

  37. MsgBox Copy some Unicode text onto the clipboard, then return to this window and press OK to continue.
    38. 

  38. Transform, ClipUTF, Unicode
    39. 

  39. Clipboard = Transform, Clipboard, Unicode, %ClipUTF%`r`n
    40. 

  40. MsgBox The clipboard now contains the following line that you can paste into your script. When executed, this line will cause the original Unicode string you copied to be placed onto the clipboard:`n`n%Clipboard%
    41. 

  41. return</pre>
    42. 

  42. <p>Note: The <code><a href="Send.htm#sendu">Send {U+nnnn}</a></code> command is an alternate way to produce Unicode characters.</p>
    43. 

  43. <br>
    44. 

  44. <p><strong>Asc, String</strong>: Retrieves the ASCII code (a number between 1 and 255) for the first character in <em>String</em>. If <em>String</em> is empty, <em>OutputVar</em> will also be made empty. For example: <code>Transform, OutputVar, Asc, %VarContainingString%</code>. Corresponding function: <a href="../Functions.htm#Asc">Asc(String)</a>.</p>
    45. 

  45. <p><strong>Chr, Value1</strong>: Retrieves the single character corresponding to the ASCII code indicated by <em>Value1</em>. If <em>Value1</em> is not between 1 and 255 inclusive, <em>OutputVar</em> will be made blank to indicate the problem. For example: <code>Transform, OutputVar, Chr, 130</code>. Corresponding function: <a href="../Functions.htm#Chr">Chr(Number)</a>.</p>
    46. 

  46. <p id="Deref"><strong>Deref, String</strong>: Expands variable references and <a href="_EscapeChar.htm">escape sequences</a> contained inside other variables. Any badly formatted variable references will be omitted from the expanded result. The same is true if <em>OutputVar</em> is expanded into itself; in other words, any references to <em>OutputVar</em> inside <em>String's</em> variables  will be omitted from the expansion (note however that <em>String</em> itself can <u>be</u> %<em>OutputVar</em>%). In the following example, if var1 contains the string &quot;test&quot; and var2 contains the <u>literal</u> string &quot;%var1%&quot;, <em>OutputVar</em> will be set to the string &quot;test&quot;: <code>Transform, OutputVar, deref, %var2%</code>. Within a <a href="../Functions.htm">function</a>, each variable in <em>String</em> always resolves to a local variable unless there is no such variable, in which case it resolves to a global variable (or blank if none).</p>
    47. 

  47. <p id="HTML"><strong>HTML, String [, Flags]</strong>:</p>
    48. 

  48. <p><em>For ANSI executables:</em> Converts <em>String</em> into its HTML equivalent by translating characters whose ASCII values are above 127 to their HTML names (e.g. &pound; becomes &amp;pound;). In addition, the four characters &quot;&amp;&lt;&gt; are translated to &amp;quot;&amp;amp;&amp;lt;&amp;gt;. Finally, each linefeed (`n) is translated to &lt;br&gt;`n (i.e. &lt;br&gt; followed by a linefeed). The <em>Flags</em> parameter is ignored.</p>
    49. 

  49. <p><em>For Unicode executables:</em> In addition of the functionality above, <em>Flags</em> can be zero or a combination (sum) of the following values. If omitted, it defaults to 1.</p>
    50. 

  50. <ul>
    51. 

  51.     <li>1: Converts certain characters to named expressions. e.g. &euro; is converted to <code>&amp;euro;</code></li>
    52. 

  52.     <li>2: Converts certain characters to numbered expressions. e.g. &#8364; is converted to <code>&amp;#8364;</code></li>
    53. 

  53. </ul>
    54. 

  54. <p>Only non-ASCII characters are affected.  If <i>Flags</i> = 3, numbered expressions are used only where a named expression is not available.  The following characters are always converted: <code>&lt;&gt;&quot;&amp;</code> and <code>`n</code> (line feed).</p>
    55. 

  55. <p><strong id="FromCodePage">FromCodePage</strong> / <strong id="ToCodePage">ToCodePage</strong>: Deprecated. Use <a href="StrPutGet.htm">StrPut() / StrGet()</a> instead.</p>
    56. 

  56. <p><strong>Mod, Dividend, Divisor</strong>: Retrieves the remainder of <em>Dividend</em> divided by <em>Divisor</em>. If <em>Divisor</em> is zero, <em>OutputVar</em> will be made blank. <em>Dividend</em> and <em>Divisor</em> can both contain a decimal point. If negative, <em>Divisor</em> will be treated as positive for the calculation. In the following example, the result is 2: <code>Transform, OutputVar, mod, 5, 3</code>. Corresponding function: <a href="../Functions.htm#Mod">Mod(Dividend, Divisor)</a>.</p>
    57. 

  57. <p><strong>Pow, Base, Exponent</strong>: Retrieves <em>Base</em> raised to the power of <em>Exponent</em>. Both <em>Base</em> and <em>Exponent</em> may contain a decimal point. If <em>Exponent</em> is negative, <em>OutputVar</em> will be formatted as a floating point number even if <em>Base</em> and <em>Exponent</em> are both integers. A negative <em>Base</em> combined with a fractional <em>Exponent</em> such as 1.5 is not supported; it will cause <em>OutputVar</em> to be made blank. See also: <a href="../Variables.htm#pow">** operator</a>.</p>
    58. 

  58. <p><strong>Exp, N</strong>: Retrieves e (which is approximately 2.71828182845905) raised to the <em>N</em>th power. <em>N</em> may be negative and may contain a decimal point. Corresponding function: <a href="../Functions.htm#Exp">Exp(N)</a>.</p>
    59. 

  59. <p><strong>Sqrt, Value1</strong>: Retrieves the square root of Value1. If <em>Value1</em> is negative, <em>OutputVar</em> will be made blank. Corresponding function: <a href="../Functions.htm#Sqrt">Sqrt(Number)</a>.</p>
    60. 

  60. <p><strong>Log, Value1</strong>: Retrieves the logarithm (base 10) of <em>Value1</em>. If <em>Value1</em> is negative, <em>OutputVar</em> will be made blank. Corresponding function: <a href="../Functions.htm#Log">Log(Number)</a>.</p>
    61. 

  61. <p><strong>Ln, Value1</strong>: Retrieves the natural logarithm (base e) of <em>Value1</em>. If <em>Value1</em> is negative, <em>OutputVar</em> will be made blank. Corresponding function: <a href="../Functions.htm#Ln">Ln(Number)</a>.</p>
    62. 

  62. <p><strong>Round, Value1 [, N]</strong>: If <em>N</em> is omitted, <em>OutputVar</em> will be set to <em>Value1</em> rounded to the nearest integer. If <em>N</em> is positive number, <em>Value1</em> will be rounded to <em>N</em> decimal places. If <em>N</em> is negative, <em>Value1</em> will be rounded by <em>N</em> digits to the left of the decimal point. For example, -1 rounds to the ones place, -2 rounds to the tens place, and-3 rounds to the hundreds place. Note: Round does not remove trailing zeros when rounding decimal places. For example, 12.333 rounded to one decimal place would become 12.300000. This behavior can be altered by using something like <code><a href="SetFormat.htm">SetFormat</a>, Float, 0.1</code> prior to the operation (in fact, <a href="SetFormat.htm">SetFormat</a> might eliminate the need to use Round in the first place). Corresponding function: <a href="../Functions.htm#Round">Round(Number [, N])</a>.</p>
    63. 

  63. <p><strong>Ceil, Value1</strong>: Retrieves <em>Value1</em> rounded up to the nearest integer. Corresponding function: <a href="../Functions.htm#Ceil">Ceil(Number)</a>.</p>
    64. 

  64. <p><strong>Floor, Value1</strong>: Retrieves <em>Value1</em> rounded down to the nearest integer. Corresponding function: <a href="../Functions.htm#Floor">Floor(Number)</a>.</p>
    65. 

  65. <p><strong>Abs, Value1</strong>: Retrieves the absolute value of <em>Value1</em>, which is computed by removing the leading minus sign (dash) from <em>Value1</em> if it has one. Corresponding function: <a href="../Functions.htm#Abs">Abs(Number)</a>.</p>
    66. 

  66. <p><strong>Sin, Value1</strong>: Retrieves the trigonometric sine of <em>Value1</em>. <em>Value1</em> must be expressed in radians. Corresponding function: <a href="../Functions.htm#Sin">Sin(Number)</a>.</p>
    67. 

  67. <p><strong>Cos, Value1</strong>: Retrieves the trigonometric cosine of <em>Value1</em>. <em>Value1</em> must be expressed in radians. Corresponding function: <a href="../Functions.htm#Cos">Cos(Number)</a>.</p>
    68. 

  68. <p><strong>Tan, Value1</strong>: Retrieves the trigonometric tangent of <em>Value1</em>. <em>Value1</em> must be expressed in radians. Corresponding function: <a href="../Functions.htm#Tan">Tan(Number)</a>.</p>
    69. 

  69. <p><strong>ASin, Value1</strong>: Retrieves the arcsine (the number whose sine is <em>Value1</em>) in radians. If <em>Value1</em> is less than -1 or greater than 1, <em>OutputVar</em> will be made blank. Corresponding function: <a href="../Functions.htm#ASin">ASin(Number)</a>.</p>
    70. 

  70. <p><strong>ACos, Value1</strong>: Retrieves the arccosine (the number whose cosine is <em>Value1</em>) in radians. If <em>Value1</em> is less than -1 or greater than 1, <em>OutputVar</em> will be made blank. Corresponding function: <a href="../Functions.htm#ACos">ACos(Number)</a>.</p>
    71. 

  71. <p><strong>ATan, Value1</strong>: Retrieves the arctangent (the number whose tangent is <em>Value1</em>) in radians. Corresponding function: <a href="../Functions.htm#ATan">ATan(Number)</a>.</p>
    72. 

  72. <br>
    73. 

  73. <p>NOTE: Each of the following bitwise operations has a more concise <a href="../Variables.htm#bitwise">bitwise operator</a> for use in expressions.</p>
    74. 

  74. <p><strong>BitNot, Value1</strong>: Stores the bit-inverted version of <em>Value1</em> in <em>OutputVar</em> (if <em>Value1</em> is floating point, it is truncated to an integer prior to the calculation). If <em>Value1</em> is between 0 and 4294967295 (0xffffffff), it will be treated as an <u>unsigned</u> 32-bit value. Otherwise, it is treated as a <u>signed</u> 64-bit value. In the following example, the result is 0xfffff0f0 (4294963440): <code>Transform, OutputVar, BitNot, 0xf0f</code>.</p>
    75. 

  75. <p><strong>BitAnd, Value1, Value2</strong>: Retrieves the result of the bitwise-AND of <em>Value1</em> and <em>Value2</em> (floating point values are truncated to integers prior to the calculation). In the following example, the result is 0xff00 (65280): <code>Transform, OutputVar, BitAnd, 0xff0f, 0xfff0</code>.</p>
    76. 

  76. <p><strong>BitOr, Value1, Value2</strong>: Retrieves the result of the bitwise-OR of <em>Value1</em> and <em>Value2</em> (floating point values are truncated to integers prior to the calculation). In the following example, the result is 0xf0f0 (61680): <code>Transform, OutputVar, BitOr, 0xf000, 0x00f0</code>.</p>
    77. 

  77. <p><strong>BitXOr, Value1, Value2</strong>: Retrieves the result of the bitwise-EXCLUSIVE-OR of <em>Value1</em> and <em>Value2</em> (floating point values are truncated to integers prior to the calculation). In the following example, the result is 0xff00 (65280): <code>Transform, OutputVar, BitXOr, 0xf00f, 0x0f0f</code>.</p>
    78. 

  78. <p><strong>BitShiftLeft, Value1, Value2</strong>: Retrieves the result of shifting <em>Value1</em> to the left by <em>Value2</em> bit positions, which is equivalent to multiplying <em>Value1</em> by &quot;2 to the <em>Value2</em>th power&quot; (floating point values are truncated to integers prior to the calculation). In the following example, the result is 8: <code>Transform, OutputVar, BitShiftLeft, 1, 3</code>.</p>
    79. 

  79. <p><strong>BitShiftRight, Value1, Value2</strong>: Retrieves the result of shifting <em>Value1</em> to the right by <em>Value2</em> bit positions, which is equivalent to dividing <em>Value1</em> by &quot;2 to the <em>Value2</em>th power&quot;, truncating the remainder (floating point values are truncated to integers prior to the calculation). In the following example, the result is 2: <code>Transform, OutputVar, BitShiftRight, 17, 3</code>.</p>
    80. 

  80. <h3>Remarks</h3>
    81. 

  81. <p>Sub-commands that accept numeric parameters can also use <a href="../Variables.htm#Expressions">expressions</a> for those parameters.</p>
    82. 

  82. <p>If either <em>Value1</em> or <em>Value2</em> is a floating point number, the following <em>Cmd</em>s will retrieve a floating point number  rather than an integer: Mod, Pow, Round, and Abs. The number of decimal places retrieved is determined by <a href="SetFormat.htm">SetFormat</a>.</p>
    83. 

  83. <p>To convert a radians value to degrees, multiply it by 180/pi (approximately 57.29578). To convert a degrees value to radians, multiply it by pi/180 (approximately 0.01745329252).</p>
    84. 

  84. <p>The value of pi (approximately 3.141592653589793) is 4 times the arctangent of 1.</p>
    85. 

  85. <h3>Related</h3>
    86. 

  86. <p><a href="SetFormat.htm">SetFormat</a>, <a href="../Variables.htm#Expressions">Expressions</a>, <a href="EnvMult.htm">EnvMult</a>, <a href="EnvDiv.htm">EnvDiv</a>, <a href="StringLower.htm">StringLower</a>, <a href="IfIs.htm">if var is type</a></p>
    87. 

  87. <h3>Example</h3>
    88. 

  88. <pre class="NoIndent">Transform, OutputVar, Asc, A  <em>; Get the ASCII code of the letter A.</em></pre>
    89. 

    90. 

  90. </body>
    91. 

  91. </html>
    92. 

    93.