Differences

This shows you the differences between two versions of the page.

--- manual:Calculations [2018/05/17 02:07] – JMichaelTX
+++ manual:Calculations [2025/02/26 02:04] (current) – [Operators] peternlewis
@@ Line 3: / Line 3: @@
 ===== Overview =====
-Keyboard Maestro supports calculations in almost any numeric [[/Text_Fields|text fields]].  For example you can Pause for "60*Time in Minutes".  Calculations can also use comma separated lists of numbers as arrays, and can return such arrays, so you can operate on frames and points.  Numeric fields often start small with up/down step arrows, but if you type anything other than a number they will expand to allow a more complex expression to be entered.  You can tell that a field accepts calculations because a small BUTTON{{{C}}} shows in the field while editing it.
+Keyboard Maestro supports calculations in almost any numeric [[/Text_Fields|text fields]].  For example you can Pause for "60*Time in Minutes".  Calculations can also use comma separated lists of numbers as arrays, and can return such arrays, so you can operate on rectangle frames and points.  Numeric fields often start small with up/down step arrows, but if you type anything other than a number they will expand to allow a more complex expression to be entered.  You can tell that a field accepts calculations because a small BUTTON{{{C}}} shows in the field while editing it.
 ===== Examples =====
@@ Line 23: / Line 23: @@
 Operators based on precedence from lowest to highest are:
-| array separator (,) | separates elements of an array |
+| Array Separator (`,`) | Allows a text Variable, which has comma separated values, to work somewhat like an Array.\\ Assume `MyKMVariable` contains "12,34,56", then `MyKMVariable[2]` returns "34". |
-| ternary operator (?) | a=b ? 3 : 4 |
+| Ternary Operator (`?`) | a=b ? 3 : 4 |
-| bitwise or (%%|%%), bitwise and (%%&%%) and bitwise xor | operators |
+| Bitwise OR (`|`), Bitwise AND (`&`) and Bitwise XOR | bitwise operators, which also act as logical boolean operators for 0 (false) and 1 (true). |
-| comparison operators (<, ≤, =, >, ≥, ≠) | compare for (in)equality and return 0 or 1 |
+| Comparison Operators (`<, ≤, =, >, ≥, ≠`) | compare for (in)equality and return 0 or 1. |
-| shift operators (≪, ≫) | shift a number left or right |
+| Shift Operators (`≪, ≫`) | shift a number left or right. |
-| addition operators (+, -) | add or subtract |
+| Arithmetic Addition Operators \\   • Add (`+`)\\   • Subtract (`-`) | Basic mathematical operations. |
-| multiplication operators (*, /, MOD) | multiply, divide or [Modulo](https://en.wikipedia.org/wiki/Modulo_operation) |
+| Arithmetic Multiplication Operators \\   • Multiply (`*`)\\   • Divide (`/`) | Basic mathematical operations. |
-| power operator (%%^%%) | exponentiation |
+| [Modulo](https://en.wikipedia.org/wiki/Modulo_operation) (`i MOD n`) | The remainder of the division of `i` by `n`.\\ Both values (`i`, `n`) will be treated as integer.\\ `n` must not be 0.\\ The sign of the result is the same as the sign of i.  |
-| unary prefix operators (√ (Option-V), -, brackets) | square root, negation, sub-expressions |
+| Integer division (`i DIV n`) | The integer quotient of the division of `i` by `n`.\\ Both values (`i`, `n`) will be treated as integer.\\ `n` must not be 0.\\ The sign of the result matches the sign of regular division.  |
-| functions | a large variety of functions |
+| Power Operator (`^`) | exponentiation. |
-| numbers and variables or array accesses (5,$5A,0x50,8#007,Variable,Variable[5]) | identifiers and values |
+| Unary Prefix Operators (`√`, `-`, `( )` ) | square root, negation, sub-expressions. |
-| unary postfix operators (!,%,° (Option-Shift-8)) | factorial, percent, degrees |
+| [[:Functions|Functions]] | a large variety of functions. |
+| Numbers and Variables or Array Accesses (5,$5A,0x50,8#007,Variable,Variable[5]) | identifiers and values. |
+| Unary Postfix Operators (`!,%,°`)) | factorial, percent, degrees. |
-You can use either `=` or `==` (v8+) for testing for equality.
+Numbers are in decimal by default, but may use base 16 if they start with `$` or `0x` (eg $5A or 0x5A), or may start with a specific base followed by a `#` (eg 8#007). Numbers may include underscores, for example `1_000_000` or `0xABCD_EF89`.
+[[Variables|Variables]] can be used if they contain numeric expressions, including an *array* of numbers separated by commas, in which case you can use an array index to select the desired number.
+You can use either `=` or `==` for testing for equality.
 Operators and functions must be in uppercase to minimize conflict with variables.
@@ Line 44: / Line 50: @@
 The available functions are listed on the [[/Functions|wiki Functions page]].
-You can insert a function by name by choosing [[Menus#Insert_Function_by_Name|Insert Function by Name]] from the [[Menus#Edit|Edit menu]].
+You can insert a function by name by choosing from the [[Menus#Insert_Function|Edit ➤ Insert Function menu]] or choosing the [[Menus#Insert_Function_by_Name|Edit ➤ Insert Function by Name menu]].
 ===== Variables =====
-Variables are used unadorned in numeric calculations.  Do not try to use tokens (like <del>%Variable%MyVar%</del>) in numeric calculation fields, just use MyVar by itself. The variable must contain a valid numeric value, or an expression (v8+) that evaluates to a valid numeric value.  So for example, if MyVar contains a text value of `2*3`, then the calculation `4*MyVar` will return 24.
+In numeric calculation fields, Variable Names are used without the `%` that are used in text token fields.  Do not try to use tokens (like `%Variable%MyVar%`) in numeric calculation fields, just use MyVar by itself. The variable must contain a valid numeric value, or an expression that evaluates to a valid numeric value.  So for example, if MyVar contains a text value of `2*3`, then the calculation `4*MyVar` will return 24.
-===== Screen Coordinates =====
-Keyboard Maestro refers to screen coordinates as two or four comma separated numbers in the text of a Keyboard Maestro Variable (which is always a string).
-  * Screen object points, like the left,top position of a window, have two values, like 12,34
-  * Screen object rectangles, like the frame of a window, have four values 12,34,56,78 (with a fifth value for fuzz in some instances).
-  * You can reference these values by position in the string, as it the Variable were an array:
-  * For example:
-if the Variable `myWindow` is "12,34,56,78"
-then all of these forms of reference will provide a value of 34 in a Calculation field:
-    * myWindow[2]
-    * myWindow.y
-    * myWindow.Top
 ===== Variable Array Access =====
@@ Line 71: / Line 64: @@
 Indices are 1-based, so MyVar[1] is the first element.  If the index is 0, the size of the array is returned (so MyVar[0] would be `6`).  If the index is less than zero, the array is indexed from the end (so MyVar[-5] would be `20`).
-===== Variable Dot Notation =====
+===== Screen Coordinates and Dot Notation =====
+Keyboard Maestro refers to screen coordinates as two or four comma separated numbers in the text of a Keyboard Maestro Variable (which is always a string).
+Screen object points, like the left,top position of a window, have two values, like 12,34.
+Screen object rectangles, like the frame of a window, have four values 12,34,56,78 (with a fifth value for fuzz in some instances).
 In a Calculation field you can reference the numbers in a Keyboard Maestro Variable (which is always a string) using dot notation:
@@ Line 86: / Line 85: @@
 | Variable.MidX | the horizontal middle of a rectangle |
 | Variable.MidY | the vertical middle of a rectangle |
+For example if the Variable `myWindow` is "12,34,56,78" then all of these forms of reference will provide a value of 34 in a Calculation field:
+    * myWindow[2]
+    * myWindow.y
+    * myWindow.Top
 The Variable Name and Dot reference are case insensitive.
 ===== Text Fields =====
@@ Line 96: / Line 101: @@
 However in a text field, since any text is allowed, you must use percent encoded tokens to indicate where more processing is required.  You can include a variable in the text by using the [[token:Variable|%Variable%]] token, or you can use a calculation by using the [[token:Calculate|%Calculate%]] token, or any number of other [[:Tokens|Tokens]].
-    The result is %Calculate%3 * Count + 7%.
+    The result is %Calculate% 3 * Count + 7 %.
-===== Examples of Variable Data Reference =====
+===== Examples of Variable Array Reference =====
-** Macro Actions**\\
+=== Macro Actions ===
-{{:manual:window-frame-example-actions-km-7.3.png?nolink|}}
-**Example Results**\\
+{{ window-frame-example-actions.png?nolink&584x592 | Window Frame Example Actions }}
-{{:manual:window-frame-example-results-km-7.3.png?nolink|}}
-Some example expressions might be:
+=== Example Results ===
+{{ window-frame-example-results.png?nolink&487x495 | Window Frame Example Results }}
+===== Example Expressions =====
 <code>
 Amount in Dollars * 100
 MJD() > 55928
-NOW() > TIME(2012,3,23,12,2,1)
+NOW() > TIME(2023,3,23,12,2,1)
-DOW(TIME(2012,4,4)) = 4
+DOW(TIME(2023,4,4)) = 4
 Radius*SIN(20°),Radius*COS(20°)
 Window Frame[1]+Window Frame[3]/2,Window Frame.MidY
@@ Line 119: / Line 126: @@
 </code>
----
-**KeyWords:**  MOD, Modulo