Operator Type:
Operator Scope of Action:
Operator Purpose:
Data Type Returned:
Operator First Added:
Operator in Current Baseline:
Operator Last Altered:
Operator Has Optional Arguments:
Operator Has Conditional Arguments:
Operator Uses Loop Variable Argument:
Function [other Function type actions]
Group [operators of similar scope]
Mathematical [other Mathematical operators]
Number [about Number data type]
v9.5.0
Baseline
As at baseline
[More on optional operator arguments]
list.sum_if(loopVar, condition[, actionStr])
The dot-operator .sum_if() sums the values of members of a List- or Set-type list that satisfy a condition.
Implicit assumption: list contains numerical values. String item values (i.e. non-digit characters) are ignored.
Each item in the list is bound in turn to loopVar, and if condition is met, the items value is added to the returned sum. Note that the actionStr is evaluated, allowing a transform to be carried out on a matched list member's value before it is added to the overall returned sum.
loopVar is essentially the same as the loop variable used by the list.each() operator. In the examples below, for clarity the loopVar value "anItem" is used, but as with any loop variable a shorter less expressive values such a "x" can be used (e.g. by more expert users).
The condition argument is a conditional query expression for which each tested item must return true or false.
The operator applies the actionStr to only those list items for which condition is true. For only list items meeting condition, the result of actionStr on loopVar is returned as List-type data.
For example, if $MyList is "1;2;3;4;5", then:
$MyListA = $MyList.sum_if(aValue, aValue>3)
returns the sum of all the members of $MyList that are greater than 3, i.e. 9.
Non-numeric list values are ignored. Were $MyList to be "1;2;foo;3;4;5", then
$MyListA = $MyList.sum_if(aValue, aValue>3)
returns the sum of all the numeric members of $MyList that are greater than 3, i.e. 9.
An optional third argument actionStr allows a matched values to be transformed before they are added to the sum. So, if $MyList is "1;2;3;4;5", then:
$MyListA = $MyList.sum_if(aValue, aValue>3, aValue*aValue)
returns the sum of the squares of each member that is greater than 3, i.e. 4 and 5 squared, 41.
list.sum_if() vs. sum_if()
Although the two appear similar. The .sum_if() operator works directly on the source list values, whereas sum_if() creates a list of $Path values and returns an attribute value from each of those paths (where the item at the $Path meets the 'if' condition).