List.PositionOf
ListReturns the zero-based index of the first (or specified) occurrence of a value in a list. Returns -1 if the value is not found.
Syntax
List.PositionOf(list as list, value as any, optional occurrence as nullable number, optional equationCriteria as any) as anyParameters
| Name | Type | Required | Description |
|---|---|---|---|
list | list | Yes | The list to search. |
value | any | Yes | The value to find in the list. |
occurrence | nullable number | No | Controls which occurrence to find. Use Occurrence.First (default), Occurrence.Last, or Occurrence.All to return all positions. |
equationCriteria | any | No | An optional equation criteria to control how equality is determined. |
Return Value
any — The zero-based index of the value's occurrence, or -1 if not found. Returns a list of positions when Occurrence.All is used.
Remarks
List.PositionOf searches a list for a value and returns its zero-based index position. By default, it finds the first occurrence. Returns -1 if the value is not found — unlike many M functions, it does not throw an error for a missing value, making it safe to use for membership-and-position checks.
The occurrence parameter controls which match to find: Occurrence.First (default) returns the index of the first match, Occurrence.Last returns the index of the last match, and Occurrence.All returns a list of all positions where the value appears. Note that the return type changes when using Occurrence.All — the result is a list of numbers, not a single number.
Comparison is case-sensitive for text by default. Pass Comparer.OrdinalIgnoreCase as the equationCriteria argument for case-insensitive search. For checking presence without needing the position, List.Contains is simpler. For finding positions of multiple target values at once, use List.PositionOfAny.
Examples
Example 3: Find the last occurrence
List.PositionOf({"A", "B", "A", "C", "A"}, "A", Occurrence.Last)Result | |
|---|---|
| 1 | 4 |
Example 4: Find all occurrences
List.PositionOf({1, 2, 1, 3, 1, 4}, 1, Occurrence.All)Result | |
|---|---|
| 1 | {0, 2, 4} |