Simple calculation (+,-,*,/,%)
See also: Calculate value, Calculation expression
Value resolver – Abstract
Purpose: This combines several numerical values with one of the four basic arithmetic operations (+,-,*,/ and % for Modulo) to return a scalar result – i.e. a ‘number without a unit’.
The Simple calculation (+,-,*,/,%) value resolver combines several numerical values with one of the four basic arithmetic operations in order to return a scalar result – i.e. a 'Number without a unit':
|
Calculation method |
Calculation scheme for values |
Similar function for aCalculation expression |
|
|
+ |
Addition with multiple summands |
A + B [+ C [+ ...]] |
|
|
- |
Subtraction with a minuend (first value) and one or more subtrahends |
A - B [- C [- ...]] |
|
|
* |
Multiplication by several factors |
A x B [x C [x ...]] |
|
|
/ |
Division with a dividend (first value) and one or more divisors |
A ÷ B [÷ C [÷ ...]] |
|
|
% |
Modulo-Rechnung (ermittelt den "Rest" einer ein- oder mehrstufigen Ganzzahldivision) |
A % B [% C [% ...]] |
calc (Calculate expression) mit einem Ausdruck wie a % b |
List values as input data
Similar to the functions for basic arithmetic operations in calculation expressions (sum(), dif(), product(), quotient()), the Simple calculation (+,-,*,/,%) resolver also accepts lists instead of or in combination with single values as ‘input data’. Furthermore, lists can even be used in a modulo calculation (%).
If value configurations for input data return a list of values, these are ‘resolved’ into individual values and added to the list of all input data:
►IMPORTANT◄ Resolving lists affects exactly one level. Individual values are not resolved recursively from nested lists.
Examples:
A mixture of single values and lists (described in JSON as: [1,2],[3,4],5,6) is processed using the Subtraction calculation type as dif(1,2,3,4,5,6)and returns the value -19 (=1-2-3-4-5-6).
If an attempt is made to provide the two list values for a list of lists (example in JSON: [[1,2],[3,4]],5,6), a Subtraction such as dif(5,6) is performed and the result is -1 (=5-6).
Although the nested lists are resolved, they do not produce a numerical scalar value but $null. They are therefore skipped.
If the nested list also contains single values (example in JSON: [0,[1,2],[3,4]],5,6), these are taken into account. A Subtraction of the example data calculates dif(0,5,6)and results in -11 (=0-5-6).
►NOTE◄ The Calculate value resolver is available for more complex mathematical operations, although it always uses the 'Number with unit' data type (see also Numeric input with unit, Unit conversion) for the result. If the calculation does not result in a unit, a 'Number with unit' is returned without a unit. This is not really a problem, but it can appear cumbersome or confusing. The Simple calculation (+,-,*,/,%) value resolver, on the other hand, delivers a purely numerical result directly and provides a clearer configuration for individual calculation steps with basic mathematical operations. It can also be used to construct 'aggregates' with several calculation steps on the basis of basic arithmetic operations (see examples), although the Calculate value resolver results in a leaner and more transparent configuration if the calculation process is more complex.
Examples
Simple use case (addition): Offset for loop index
In the context of a For each loop, a Show alert event action is executed for each loop pass, which informs the currently processed list value via a 'Message' and names the iteration index in the 'Title', starting at 1. The $index variable provides information about the latter during iteration, although it works with a starting value of 0. This is something machines like. People tend not to. The desired result must therefore be 'converted'. The very simple formula for this is: $input + 1. This task is a clear case for the Simple calculation (+,-,*,/,%) resolver.
Configuration:
|
The screenshot on the right shows the configuration for a For each loop event action:
|
|
Simple use case (subtraction): 'Countdown' – iteration index in reverse gear
As in the previous example, a list of entities provided by the variable listOfEntities is processed in a loop.
Unlike the previous case, the Title of the notification issued for each iteration step should no longer display the sequence number of the iteration step (ascending from the value 1), but a 'countdown', i.e. an indication of the number of remaining iterations, which indicates the value 0 in the last step.
Configuration:
The 'countdown' can be achieved within the For each loop by forming the difference between two automatically provided 'loop variables' for each iteration step:
$length → Integer value for the total number of iteration steps
$index → Integer value for the current iteration index (ascending from the value 0)
In order for the countdown to display the value 0 in the last iteration, the fixed value 1 must be subtracted from the $length value in addition to the $index.
The total calculation to be performed for each iteration step is therefore: $length - $index - 1
|
The screenshot on the right only shows the value configuration for the Title parameter in the Show alert event action. The surrounding configuration can be copied unchanged from the previous example.
|
|
►NOTE◄ Although the 'Countdown' count in the Title runs backwards due to the conversion, the entries in the listOfEntities are processed forwards unchanged. Reversing the direction for the iteration requires a little more effort, as the For each loop event action only iterates forwards. If the countdown index is calculated using the Simple calculation (+,-,*,/,%) resolver and stored in a variable, the name of this variable can be addressed in the 'Offset' parameter of a list item value resolver in order to retrieve the List item matching the displayed index.
More complex use case (subtraction and division): Calculating the 'age' of a company account
As an example of the possibility of creating an aggregate with different calculation operations from several instances of the Simple calculation (+,-,*,/,%) value resolver, the 'age' of a specific company account in years is determined here.
The 'age' of an entity is considered to be the time span between the creation date (created property) and the current system time (Relative date with time with the 'Now' type).
As time spans are always primarily determined as a millisecond difference, they must then be converted into the target unit (here: years) by division (by 'milliseconds per year').
We calculate the duration of a year in milliseconds as 1000 ms/s x 3600 s/h x 24 h/d x 365.25 d/y = 31557600000 ms. Switching days are therefore 'apportioned' at a flat rate of 0.25 days per year.
Configuration:
|
The screenshot on the right shows a value resolver chain that returns the 'age' of the Company of session in years as a double decimal number:
|
|
►NOTE◄ Below is a configuration with the Calculate value resolver with the same content for comparison:
|
In contrast to the Simple calculation (+,-,*,/,%) value resolver, the value configurations for input values must be integrated into the calculation via arbitrarily named variables (now, created). The variables can then be used directly together with static values to formulate the calculation (top right in the screenshot). In order to finally obtain the pure numerical value from the calculation result, which is formally generated as a 'Unit number', the Object property 'Value' (value) must be explicitly accessed. The direct comparison shows that the Calculate value resolver can already map the required 'aggregate' more compactly and clearly in this not yet too complex use case than the comparable configuration with two nested Simple calculation (+,-,*,/,%) instances in the example above. With the number of calculation steps to be aggregated, a configuration that nests Simple calculation (+,-,*,/,%) instances increases disproportionately, so that the advantage of a 'calculation expression' that names input data as variables and places them in a relationship defined as an 'overall approach' becomes increasingly clear. Similarly, for a Calculation expression, it should be considered whether the functions sum (Addition), dif (Difference), product (Multiplication) and quotient (Division) should be used for aggregates based on the basic arithmetic operations instead of calc (Calculate expression) with an overall approach. |
|
More complex use case (multiplication): Calculate product of efficiencies
A list with a limited number of Double values from the value range [0,1] is provided in an efficiencyFactors variable, which are to be multiplicatively concatenated as efficiencies in order to determine an overall efficiency.
Specific numerical example:
Specifically, the value of the efficiencyFactors variable in JSON format could look like this: [0.9, 0.95, 0.75]
This results in an overall efficiency of (0.9 x 0.95 x 0.75 = 0.64125).
Configuration:
In a Calculation expression, the list value from the variable could be processed directly in the product (Multiplication) function. Accordingly, $product($var(efficiencyFactors)) would be a target-oriented calculation expression.
As the Simple calculation (+,-,*,/,%) value resolver – as briefly mentioned in the footnote above – cannot process list values directly, the direct translation of the calculation expression into a corresponding value configuration fails.
The following approach demonstrates what a 'multiplicative concatenation' could look like for up to five factors:
|
The screenshot on the right shows a value resolver chain that starts with the list of individual efficiencies from the Variable efficiencyFactors.
If the list contains fewer than five values in the input value, some of the List item value resolvers return 'No value' ($null). Empty values are simply skipped in the calculation so that all non-empty values are concatenated as required. |
|
►NOTE◄ The approach described above only fulfills the task if the maximum number of factors can be sufficiently limited in advance. A predetermined number of factors, on the other hand, cannot be processed. It makes little sense to cover a large number of list values in this way if they are only rarely required. The following alternative avoids this restriction.
Alternative configuration:
|
The screenshot on the right shows a value resolver chain that starts with the list of individual efficiencies from the efficiencyFactors Variable. With this approach, the list is passed as an input value to the concatenated Simple calculation (+,-,*,/,%) resolver:
|
|
►NOTE◄ The efficiencyFactors Variable could also be accessed here directly instead of the object property value resolver within the calculation. However, the variant in the screenshot is intended to illustrate that a list of input data for the calculation can be provided as an input value via concatenation. If required, a Collect values resolver can then also be used within the calculation, e.g. to extract input data from a list of complex objects.
More complex use case (addition & modulo): Container loading
A Variable shipments provides a list of data on shipments, including the weight of each shipment in the item_kgs field.
These shipments are to be loaded onto containers of the same type for joint transport, the maximum payload of which is specified by another Variable kgs_per_container.
Under the assumption that the denomination of the shipments allows a full utilisation of all used containers except for one, the weight for the partial load should be calculated, which theoretically falls to this ‘last’ container.
Configuration:
|
The screenshot on the right shows a value resolver chain (see Chained resolver) that calculates the theoretical 'partial load' based on the list of shipment data in the shipments Variable:
|
|
