[List.IndicesOf:]

Returns a list of index positions (starting at 0) of items in a list that match the specified string.


Compatibility

The macro can be used in all input document types and in Report Studio.


Updates

6 months ago · April 2026

Added the 'comparisonLambda' parameter to allow for custom sorting logic using a lambda expression. See List.Sort macro for an example.


Parameters (114)
Mandatory (1)
Parameter TypePurpose Options Default
values
List<Object>The list of input values. In Legacy Mode, they should be split by the delimiter character. N/A N/A
Behaviour (12)
Parameter TypePresencePurpose Options Default
calculate
StringOptionalPost processing formula. Use {value} to substitute the macro's output into the formula as text, e.g. {value}/1024, or the bare word value to use the output itself, e.g. jPath(value, 'id') to read a property from an object. If the result is fractional it is shown to two decimal places unless you also set format, e.g. format=G to show it in full; a value kept by storeAs always retains its full precision. N/A N/A
desiredExecutionResult
List<ExecutionResult>OptionalIf specified, asserts the expected execution result of the macro. Accepts a single value or a semicolon-separated list of acceptable values (e.g. 'Success;Warning'). The macro executes normally; if the actual result matches any of the desired values, the result is converted to Success. If the actual result does not match, the result is converted to MacroError with a descriptive message. This is primarily used for testing and diagnostic purposes. Valid values are: 'Unknown', 'Success', 'MacroError', 'WorkerStopped', 'Running', 'Warning', 'NeverRun', 'Cancelled', 'Pending', 'Paused', 'SystemError', 'Deferred' and 'Stopped'.
  • Cancelled
  • Deferred
  • MacroError
  • NeverRun
  • Paused
  • Pending
  • Running
  • Stopped
  • Success
  • SystemError
  • Warning
  • WorkerStopped
N/A
errorOnOverflow
BooleanOptionalShould NCalc expression evaluation throw error on Overflow
  • true
  • false
true
expectedType
StringOptionalIf specified, asserts the expected output type of the macro result. The macro executes normally; if the actual type does not match, a macro error is generated. Requires 'storeAs', 'storeAsHidden', or 'storeFormattedValueAs' to be set for typed validation. Valid types include CLR names (e.g. Int32, Int64, Single, Double, Boolean, String, JArray, JObject) and C# keyword aliases (e.g. int, long, float, double, bool, string, uint, ulong, short, ushort, byte, sbyte, decimal, char, object). The special value 'Number' matches any numeric type. N/A N/A
expectedValue
StringOptionalIf specified, asserts the expected output value of the macro result. The macro executes normally; if the actual value does not match, a macro error is generated. When 'storeAs' or 'storeAsHidden' is set, the stored variable value is compared. Otherwise, the document output text is compared. N/A N/A
hidden
BooleanOptionalWhether to hide the macro output.
  • true
  • false
false
if
StringOptionalThe condition that must be true in order for the macro to be executed/evaluated. Must either evaluate to true or false, for example: "3+5=8" or "contains('abcd', 'z')". N/A true
mode
MacroModeOptionalThe mode in which variables are stored. In legacy mode (default for Schedules), the variable created is a string and formatted. In normal mode (default for Report Studio), the output variable is stored as a strongly-typed object, e.g. an Int32 or a JArray etc., rather than a formatted string.
  • Legacy
  • Normal
Legacy
obfuscation
ObfuscationTypeOptionalObfuscation type. Use obfuscation to write reports where sensitive data is hidden. When used, ReportMagic guarantees that the same input string will map to the same output string for the whole of the report (but the next time the report runs, it will most likely map to a different value). If you use obfuscation, the property in your macro will not show up and instead, you will see a fake item of the obfuscation type chosen.
  • None
  • UkTown
  • DeviceName
  • Company
  • IpAddress
  • PrivateIpAddress
None
redact
BooleanOptionalWhether substituted variables are hidden from macro results (and the word 'REDACTED' will appear in progress screens and elsewhere in the web UI).
  • true
  • false
false
trimWhitespace
BooleanOptionalWhether to trim leading and trailing whitespace on input items. The trim operation is done BEFORE other operators such as selecting distinct items or sorting.
  • true
  • false
false
warning
StringOptionalIf specified, adds a warning message for this macro. This is processed as an NCalc, and the warning message will ALWAYS be present and will be the value of the evaluated NCalc expression. N/A N/A
Colours (21)
Parameter TypePresencePurpose Options Default
colorTableCell
BooleanOptionalWhether to color table cells if thresholds are breached, rather than color the text.
  • true
  • false
true
criticalFontBackgroundColor
ColorOptionalThe critical font background color to use. If omitted, no change is made. N/A
criticalFontColor
ColorOptionalThe critical font color to use. If omitted, no change is made. N/A
criticalTableCellBackgroundColor
ColorOptionalThe critical table cell background color to use. If omitted, no change is made. N/A
errorFontBackgroundColor
ColorOptionalThe error font background color to use. If omitted, no change is made. N/A
errorFontColor
ColorOptionalThe error font color to use. If omitted, no change is made. N/A
errorTableCellBackgroundColor
ColorOptionalThe error table cell background color to use. If omitted, no change is made. N/A
fatalFontBackgroundColor
ColorOptionalThe fatal font background color to use. If omitted, no change is made. N/A
fatalFontColor
ColorOptionalThe fatal font color to use. If omitted, no change is made. N/A
fatalTableCellBackgroundColor
ColorOptionalThe fatal table cell background color to use. If omitted, no change is made. N/A
fontBackgroundColor
ColorOptionalThe font background color to use. N/A
fontColor
ColorOptionalThe font color to use. N/A
infoFontBackgroundColor
ColorOptionalThe info font background color to use. If omitted, no change is made. N/A
infoFontColor
ColorOptionalThe info font color to use. If omitted, no change is made. N/A
infoTableCellBackgroundColor
ColorOptionalThe info table cell background color to use. If omitted, no change is made. N/A
normalFontBackgroundColor
ColorOptionalThe normal font background color to use. If omitted, no change is made. N/A
normalFontColor
ColorOptionalThe normal font color to use. If omitted, no change is made. N/A
normalTableCellBackgroundColor
ColorOptionalThe normal table cell background color to use. If omitted, no change is made. N/A
warningFontBackgroundColor
ColorOptionalThe warning font background color to use. If omitted, no change is made. N/A
warningFontColor
ColorOptionalThe warning font color to use. If omitted, no change is made. N/A
warningTableCellBackgroundColor
ColorOptionalThe warning table cell background color to use. If omitted, no change is made. N/A
Formatting (15)
Parameter TypePresencePurpose Options Default
criticalFontBold
BooleanOptionalChange the critical font weight (true=strong, false=normal). If omitted, no change is made.
  • true
  • false
N/A
criticalFontSize
DoubleOptionalChange the critical font size in points. If omitted, no change is made.
  • From 2 to 200
N/A
errorFontBold
BooleanOptionalChange the error font weight (true=strong, false=normal). If omitted, no change is made.
  • true
  • false
N/A
errorFontSize
DoubleOptionalChange the error font size in points. If omitted, no change is made.
  • From 2 to 200
N/A
fatalFontBold
BooleanOptionalChange the fatal font weight (true=strong, false=normal). If omitted, no change is made.
  • true
  • false
N/A
fatalFontSize
DoubleOptionalChange the fatal font size in points. If omitted, no change is made.
  • From 2 to 200
N/A
fontBold
BooleanOptionalChange the font weight (true=strong, false=normal). If omitted, no change is made.
  • true
  • false
N/A
fontSize
DoubleOptionalChange the font size in points. If omitted, no change is made.
  • From 2 to 200
N/A
format
StringOptionalThe formatting to use for numbers. You can also specify 'format=string' to force numbers to be treated as strings. For dates, C# date formats are supported, plus two special values (in any casing): 'format=dayOfWeek' for the day of the week as a number (Sunday = 0; use 'format=dddd' for the day name) and 'format=epoch' for the number of seconds since 1970-01-01 UTC. N/A N/A
infoFontBold
BooleanOptionalChange the info font weight (true=strong, false=normal). If omitted, no change is made.
  • true
  • false
N/A
infoFontSize
DoubleOptionalChange the info font size in points. If omitted, no change is made.
  • From 2 to 200
N/A
normalFontBold
BooleanOptionalChange the normal font weight (true=strong, false=normal). If omitted, no change is made.
  • true
  • false
N/A
normalFontSize
DoubleOptionalChange the normal font size in points. If omitted, no change is made.
  • From 2 to 200
N/A
warningFontBold
BooleanOptionalChange the warning font weight (true=strong, false=normal). If omitted, no change is made.
  • true
  • false
N/A
warningFontSize
DoubleOptionalChange the warning font size in points. If omitted, no change is made.
  • From 2 to 200
N/A
Conditional Formatting (35)
Parameter TypePresencePurpose Options Default
criticalEq
StringOptionalThe macro is considered 'critical' if the output is equal to this value. N/A N/A
criticalGe
StringOptionalThe macro is considered 'critical' if the output is greater than or equal to this value. N/A N/A
criticalGt
StringOptionalThe macro is considered 'critical' if the output is greater than this value. N/A N/A
criticalIf
StringOptionalThe macro is considered 'critical' if the expression evaluates to true. Use 'value' as the macro output in the expression. N/A N/A
criticalLe
StringOptionalThe macro is considered 'critical' if the output is less than or equal to this value. N/A N/A
criticalLt
StringOptionalThe macro is considered 'critical' if the output is less than this value. N/A N/A
criticalNe
StringOptionalThe macro is considered 'critical' if the output is not equal to this value. N/A N/A
errorEq
StringOptionalThe macro is considered 'error' if the output is equal to this value. N/A N/A
errorGe
StringOptionalThe macro is considered 'error' if the output is greater than or equal to this value. N/A N/A
errorGt
StringOptionalThe macro is considered 'error' if the output is greater than this value. N/A N/A
errorIf
StringOptionalThe macro is considered 'error' if the expression evaluates to true. Use 'value' as the macro output in the expression. N/A N/A
errorLe
StringOptionalThe macro is considered 'error' if the output is less than or equal to this value. N/A N/A
errorLt
StringOptionalThe macro is considered 'error' if the output is less than this value. N/A N/A
errorNe
StringOptionalThe macro is considered 'error' if the output is not equal to this value. N/A N/A
fatalEq
StringOptionalThe macro is considered 'fatal' if the output is equal to this value. N/A N/A
fatalGe
StringOptionalThe macro is considered 'fatal' if the output is greater than or equal to this value. N/A N/A
fatalGt
StringOptionalThe macro is considered 'fatal' if the output is greater than this value. N/A N/A
fatalIf
StringOptionalThe macro is considered 'fatal' if the expression evaluates to true. Use 'value' as the macro output in the expression. N/A N/A
fatalLe
StringOptionalThe macro is considered 'fatal' if the output is less than or equal to this value. N/A N/A
fatalLt
StringOptionalThe macro is considered 'fatal' if the output is less than this value. N/A N/A
fatalNe
StringOptionalThe macro is considered 'fatal' if the output is not equal to this value. N/A N/A
infoEq
StringOptionalThe macro is considered 'info' if the output is equal to this value. N/A N/A
infoGe
StringOptionalThe macro is considered 'info' if the output is greater than or equal to this value. N/A N/A
infoGt
StringOptionalThe macro is considered 'info' if the output is greater than this value. N/A N/A
infoIf
StringOptionalThe macro is considered 'info' if the expression evaluates to true. Use 'value' as the macro output in the expression. N/A N/A
infoLe
StringOptionalThe macro is considered 'info' if the output is less than or equal to this value. N/A N/A
infoLt
StringOptionalThe macro is considered 'info' if the output is less than this value. N/A N/A
infoNe
StringOptionalThe macro is considered 'info' if the output is not equal to this value. N/A N/A
warningEq
StringOptionalThe macro is considered 'warning' if the output is equal to this value. N/A N/A
warningGe
StringOptionalThe macro is considered 'warning' if the output is greater than or equal to this value. N/A N/A
warningGt
StringOptionalThe macro is considered 'warning' if the output is greater than this value. N/A N/A
warningIf
StringOptionalThe macro is considered 'warning' if the expression evaluates to true. Use 'value' as the macro output in the expression. N/A N/A
warningLe
StringOptionalThe macro is considered 'warning' if the output is less than or equal to this value. N/A N/A
warningLt
StringOptionalThe macro is considered 'warning' if the output is less than this value. N/A N/A
warningNe
StringOptionalThe macro is considered 'warning' if the output is not equal to this value. N/A N/A
Filtering & Sorting (12)2 additional
Parameter TypePresencePurpose Options Default
matchExpression
StringConditionalThe expression to use to determine if the item matches. Only one of this or 'matchOn' must be set N/A N/A
matchOn
StringConditionalThe string to compare each item in the list against. Only one of this or 'matchExpression' must be set. N/A N/A
comparisonItemName
StringOptionalThe name of the variable representing the current list item in the 'comparisonLambda' expression. N/A item
comparisonLambda
StringOptionalAn NCalc expression evaluated per item to extract the sort key. Use the variable name specified in 'comparisonItemName' (default 'item') to refer to the current list item. Supports functions like jPath() for accessing properties with special characters (e.g. dots in names). Cannot be used together with 'comparisons'. N/A N/A
comparisons
List<String>OptionalIn 'normal' mode only, the comparisons that are jsonPaths. For multiple items, separate by a semi-colon e.g. property1;property2;... N/A N/A
condition
StringOptionalThe condition that must be true, using 'value'. N/A N/A
orderByIndices
List<Int32>OptionalThe semicolon-separated ordered list of columns to order by. The first is 0. e.g. 0;2;1 N/A N/A
orderDirection
List<String>OptionalThe semicolon-separated order directions. Each must be one of: Ascending, Asc, Descending or Desc. When 'comparisonLambda' is used, the default is Asc (not None) since providing a lambda implies sorting is desired. Only the first value is used with 'comparisonLambda'. N/A None
skip
Int32OptionalThe number of items AFTER the sort to skip. N/A 0
sortTypes
List<String>OptionalThe semicolon-separated sort types. Each must be one of Alphanumeric, Numeric, Natural or Auto. The default (Auto) will attempt a numeric sort if all the values are numeric, otherwise falls back to alphanumeric. Alphanumeric is a plain lexicographic string sort (so '1', '11', '2'), whereas Natural is a human/version-aware sort where embedded numbers order by value (so '1', '2', '11', and 'b1', 'b2', 'b10'). Note that Natural compares the minus sign and the dot as ordinary characters, so it is neither signed-number nor semantic-version aware: negative numbers are not ordered by their true value (so '-2' sorts before '-10'), and a release sorts before its own pre-release (so '1.0.0' before '1.0.0-alpha'). For true numeric ordering that respects negative values, use Numeric (or the default Auto, which sorts numerically when every value is a number). N/A Auto
stringListSortType
StringListSortTypeOptionalThe sort method to use. This can be used to adjust the sort order used by the system.
  • OrdinalIgnoreCase
  • Ordinal
  • InvariantCulture
  • InvariantCultureIgnoreCase
OrdinalIgnoreCase
take
Int32OptionalThe number of items AFTER the sort to take. N/A 2147483647
Additional (2)
Parameter TypePresencePurpose Options Default
includeWhitespaceItems
BooleanOptionalWhether to include whitespace items.
  • true
  • false
true
selectDistinct
BooleanOptionalWhether to exclude duplicates.
  • true
  • false
false
Output (1)9 additional
Parameter TypePresencePurpose Options Default
indexDelimiter
CharOptionalThe index delimiter. N/A ^
Additional (9)
Parameter TypePresencePurpose Options Default
delimiter
CharOptionalThe delimiter character to delimit text-based input lists (e.g. 1;2;3;4). When this parameter is set and 'listDelimiter' is NOT set, this acts as both the input and output list delimiter. N/A ;
failureText
StringOptionalThe text to display should the macro fail to execute. Note that a poorly-specified macro (e.g. omitting mandatory parameters) will still result in an error message. N/A N/A
failureVariable
StringOptionalThe name of a variable to create should the macro fail to execute. The variable will be a text variable, and will contain either the failure text (only if the failureText parameter is set), otherwise it will contain the exception / failure message. N/A N/A
listDelimiter
CharOptionalIn Legacy Mode only, the delimiter character to delimit the output list, UNLESS only 'delimiter' is set, in which case 'delimiter' acts as both the input and output list delimiter. N/A ;
outputListsAsJarray
Normal mode
BooleanOptionalAny macros that output lists can optionally (in Normal mode) output a jArray instead.
  • true
  • false
true
storeAs
StringOptionalThe variable to store the result as. If the variable name ends 'Json' (any casing) its value is wrapped in json tags. That marks the value as JSON so it can be passed straight into a parameter that expects json content, and the RMScript editor also displays it with JSON highlighting. When several variables are stored at once each one is judged by its own name. N/A N/A
storeAsHidden
StringOptionalThe variable to store the result as, while hiding the output. Equivalent to 'storeAs=ThisValue, hidden=true'. N/A N/A
storeAsVariableDelimiter
CharOptionalThe delimiter used by storeAs to split a TEXT value, when there are multiple stored variables. For example, in this macro, we indicate that the value to be stored should be split by the asterisk when being stored: [String:value=a*b*c*d, storeAs=var1;var2;var3;var4, storeAsVariableDelimiter=*]. If splitting on this delimiter does not produce one value per variable, the '^' character is tried instead; that applies whatever this parameter is set to, and is what allows a single variable to hold a value containing a ';'. Note this delimiter is only used for a TEXT value. A list or a JSON array is instead shared out one element per variable, and a JSON object by its property values in order, so storing jObject('a',1,'b',2) as two variables gives 1 and 2. Any other type cannot be split across several variables at all. N/A ;
storeFormattedValueAs
StringOptionalThe name of the STRING variable to store the result as and output (both will use the same format) into the report. Note that if you also use 'storeAsHidden' in the same macro, you should not expect the output to be hidden, as this parameter overrides that. As with 'storeAs', a name ending 'Json' has its value wrapped in json tags. N/A N/A
General (3)
Parameter TypePresencePurpose Options Default
values
List<Object>MandatoryThe list of input values. In Legacy Mode, they should be split by the delimiter character. N/A N/A
comment
StringOptionalAdd a comment to make your document template more readable. The comment is discarded in the output document. N/A N/A
singleValueList
Normal mode
BooleanOptionalIn Normal Mode and for macros that output JArrays only, whether to convert a JArray of single-property jObjects into a flat JArray of values.
  • true
  • false
false
Deprecated (4)
Parameter TypePreferred ParameterPurpose Options Default
comparison
List<String>comparisonsIn 'normal' mode only, the comparisons that are jsonPaths. For multiple items, separate by a semi-colon e.g. property1;property2;... N/A N/A
order
List<String>orderDirectionThe semicolon-separated order directions. Each must be one of: Ascending, Asc, Descending or Desc. When 'comparisonLambda' is used, the default is Asc (not None) since providing a lambda implies sorting is desired. Only the first value is used with 'comparisonLambda'. N/A None
orderByIndex
List<Int32>orderByIndicesThe semicolon-separated ordered list of columns to order by. The first is 0. e.g. 0;2;1 N/A N/A
sortType
List<String>sortTypesThe semicolon-separated sort types. Each must be one of Alphanumeric, Numeric, Natural or Auto. The default (Auto) will attempt a numeric sort if all the values are numeric, otherwise falls back to alphanumeric. Alphanumeric is a plain lexicographic string sort (so '1', '11', '2'), whereas Natural is a human/version-aware sort where embedded numbers order by value (so '1', '2', '11', and 'b1', 'b2', 'b10'). Note that Natural compares the minus sign and the dot as ordinary characters, so it is neither signed-number nor semantic-version aware: negative numbers are not ordered by their true value (so '-2' sorts before '-10'), and a release sorts before its own pre-release (so '1.0.0' before '1.0.0-alpha'). For true numeric ordering that respects negative values, use Numeric (or the default Auto, which sorts numerically when every value is a number). N/A Auto

Examples (11)

Example 1Normal mode

This Normal Mode example shows how it works with a list (JArray) as input. The JArray is first created using the [Calculate:] macro shorthand [=:] to store the list as a variable:

[=:`list(true, false, true, true, true, false)`, =>List1] [List.IndicesOf: values={=List1}, matchOn="False", trimWhitespace=true, mode=Normal]
Outputs: [ 1, 5 ]

Example 2

Outputs the indexes of all occurrences of 'value1' in a list:

[List.IndicesOf: values=value1;value2;value1;value2, matchOn="value1"]
Outputs: 0;2

Example 3

Outputs the indexes of all occurrences of 'false' in a list:

[List.IndicesOf: values=true;false;true;true;true;false, matchOn="false"]
Outputs: 1;5

Example 4

Outputs the indexes of all occurrences of 'false' in a list that has whitespace between items:(demonstrates that the whitespace is removed because the 'trimWhitespace' parameter is set to true):

[List.IndicesOf: values=true ; false ; true ; true ; true ; false, matchOn="false", trimWhitespace=true]
Outputs: 1;5

Example 5

Demonstrates the use of the 'condition' parameter:

[List.IndicesOf: values=true ; false ; true ; true ; true ; false, matchOn="false", trimWhitespace=true, condition="value < 5"]
Outputs: 1

Example 6Normal mode

This Normal Mode example demonstrates the use of the 'matchExpression' parameter to match 2 numbers:

[=:`list(123, 'x', 'y', 'z', 123)`, =>List1] // Create a variable to determine what to match on (a number in this case) [String: value=123, =>MatchValue] // Use the variable in the [List.IndicesOf: values={=List1}, matchExpression=`value={MatchValue}`, =>Indexes1]
Outputs: [ 0, 4 ]

Example 7Normal mode

This Normal Mode example demonstrates the use of the 'matchExpression' parameter to match 2 numbers, and the $'condition' parameter to subsequently take those indexes less than 4 (i.e. exclude the last index of the value 123):

[=:`list(123, 'x', 'y', 'z', 123)`, =>List1] // Create a variable to determine what to match on (a number in this case) [String: value=123, storeAs=MatchValue] // Use the variable in the macro [List.IndicesOf: values={=List1}, matchExpression=`value={MatchValue}`, condition=value<4, =>Indexes2]
Outputs: [ 0 ]

Example 8Normal mode

This Normal Mode example demonstrates the use of the 'matchExpression' parameter to find indexes of items in a JArray, by using the NCalc 'startsWith' and '' functions:

[Array: value=`[ { "Item" : "E" }, { "Item" : "D" }, { "Item" : "C" }, { "Item" : "B" }, { "Item" : "A" } ]`, =>Array] [List.IndicesOf: values={=Array}, matchExpression=`startsWith(jPath(value,'Item'), 'C')`, =>Indexes3]
Outputs: [ 2 ]

Example 9Normal mode

This Normal Mode example demonstrates the use of the 'matchExpression' parameter to find all values where the value + 1 equals 124:

[=:`list(1, 'x', 'y', 'z', 123)`, =>List2] [List.IndicesOf: values={=List2}, matchExpression=`value+1=124`, =>Indexes4]
Outputs: [ 4 ]

Example 10Normal mode

This Normal Mode example demonstrates the use of the 'matchExpression' parameter to find the indexes of the letter x:

[=:`list('x', 'y', 'z')`, =>List3] [List.IndicesOf: values={=List3}, matchExpression=`value='x'`, =>Indexes5]
Outputs: [ 0 ]

Example 11Normal mode

This Normal Mode example demonstrates the use of the 'matchExpression' parameter to find the indexes of numbers greater than 3:

[=:`list(1, 2, 3, 4, 5)`, =>List4] [List.IndicesOf: values={=List4}, matchExpression=`value>3`, =>Indexes6]
Outputs: [ 3, 4 ]

Reconnection

Reconnection

Reconnection

timed out

timed out

Attempt of

Reload
An unhandled error has occurred. Reload 🗙