Command: Get the index of a value in a list.

((PUB ┆ PRI))
   LOOKDOWN ( Value : ExpressionList )

((PUB ┆ PRI))
   LOOKDOWNZ ( Value : ExpressionList )

Returns: One-based index position (LOOKDOWN) or a zero-based index position (LOOKDOWNZ) of Value in ExpressionList, or 0 if Value not found.

• Value is an expression indicating the value to find in ExpressionList.
• ExpressionList is a comma-separated list of expressions. Quoted strings of characters are also allowed; they are treated as a comma-separated list of characters.

Explanation

LOOKDOWN and LOOKDOWNZ are commands that retrieve indexes of values from a list of values. LOOKDOWN returns the one-based index position (1..N) of Value from ExpressionList. LOOKDOWNZ is just like LOOKDOWN except it returns the zero-based index position (0..N−1). For both commands, if Value is not found in ExpressionList then 0 is returned.

Using LOOKDOWN or LOOKDOWNZ

LOOKDOWN and LOOKDOWNZ are useful for mapping a set of non-contiguous numbers (25, -103, 18, etc.) to a set of contiguous numbers (1, 2, 3, etc. –or– 0, 1, 2, etc.) where no algebraic expression can be found to do so concisely. The following example assumes Print is a method created elsewhere.

PUB ShowList | Index
  Print(GetIndex(25))
  Print(GetIndex(300))
  Print(GetIndex(2510))
  Print(GetIndex(163))
  Print(GetIndex(17))
  Print(GetIndex(8000))
  Print(GetIndex(3))

PUB GetIndex(Value): Index
  Index := lookdown(Value: 25, 300, 2_510, 163, 17, 8_000, 3)

The GetIndex method in this example uses LOOKDOWN to find Value and returns the index where it was found in the ExpressionList, or 0 if not found. The ShowList method calls GetIndex repeatedly with different values and prints the resulting index on a display. Assuming Print is a method that displays a value, this example will print 1, 2, 3, 4, 5, 6 and 7 on a display.

If LOOKDOWNZ were used instead of LOOKDOWN this example would print 0, 1, 2, 3, 4, 5, and 6 on a display.

If Value is not found, LOOKDOWN, or LOOKDOWNZ, returns 0. So if one of the lines of the ShowList method was, Print(GetIndex(50)), the display would show 0 at the time it was executed.

If using LOOKDOWNZ, keep in mind that it may return 0 if either Value was not found or Value is at index 0. Make sure this will not cause an error in your code or use LOOKDOWN instead.