Returns the position of the first item that meets your search criteria from a list . In its simplest form, it will return the position of the first item from the list inList that matches item. It is more useful when you supply a key, which is a function name applied to each entry in inList. If no entry meets the criteria, NoValue is returned.
position ( item as Any, _
inList As List, _
Optional key As Any = :Identity ) As Any
| Argument | Type | Description |
|---|---|---|
| item | any | The value that must be matched for a successful search. |
| inList | list | List of candidates. Only the first one to match will be returned. |
| key | Any | Optional; can either be a name of a function or an integer value; default is :Identity. When using a function name, the function is called for each item in the list . The function must return a value that can be matched against item. When using an integer value, each item in the list must itself be a list . The value represents the position within each sublist that contains the value to match against item. |
Intent >position(13, {11, 12, 13})
--> 3
Here, the
integer
value 13 was matched at position 3. Intent >position(7, {4, 8, 2})
--> NoValue
Here, the
integer
value 7 was not matched by any of the list items, so
NoValue
is returned. Intent >position(9, {{3, 6, 9}, {9, 5, 6}, {9, 1, 2}}, key := :first)
--> 2
In this example, item is compared to only the first member of each of the
lists
in inList. Note that only the position of the first match was returned. Intent >position(42, { {"abc", 10}, {"def", 42}, {"ghi", 18} }, key := 2)
--> 2
Here, the 2nd element of each sublist is compared against item. This matches the 2nd sublist.