LOOKDOWN

Syntax : LOOKDOWNTarget, (Value0, Value1, ...ValueN ), Variable
Syntax : LOOKDOWN Target, {ComparisonOp} [Value0, Value1, ...ValueN], Variable

Function

Compare Target value to a list of values and store the index number of the first value that matches into Variable. If no value in the list matches, Variable is left unaffected. On the BS2, BS2e, BS2sx and BS2p, the optional ComparisonOp is used as criteria for the match; the default criteria is "equal to."

• Target is a variable/constant/expression* (0 - 65535) to be compared to the values in the list.
• ComparisonOp is an optional comparison operator (as described below) to be used as the criteria when comparing values. When no ComparisonOp is specified, equal to (=) is assumed. This argument is not available on the BS1.
• Values are variables/constants/expressions* (0 - 65535) to be compared to Target.
• Variable is a variable (usually a byte) that will be set to the index (0 - 255) of the matching value in the Values list. If no matching value is found, Variable is left unaffected.

* Note: expressions are not allowed as arguments on the BS1.

Quick Facts

Explanation

LOOKDOWN works like the index in a book. In an index, you search for a topic and get the page number. LOOKDOWN searches for a target value in a list, and stores the index number of the first match in a variable. For example:

SYMBOL  value   = B2
SYMBOL  result  = B3

Setup:
  value = 17
  result = 15

Main:
  LOOKDOWN value, (26, 177, 13, 1, 0, 17, 99), result
  DEBUG "Value matches item ", #result, "in list"
  END

value   VAR     Byte
result  VAR     Byte

Setup:
  value = 17
  result = 15

Main:
  LOOKDOWN value, [26, 177, 13, 1, 0, 17, 99], result
  DEBUG "Value matches item ", DEC result, " in list"
  END

DEBUG prints, "Value matches item 5 in list" because the value (17) matches item 5 of [26, 177, 13, 1, 0, 17, 99]. Note that index numbers count up from 0, not 1; that is, in this list, 26 is item 0.

What happens if the value doesn't match any of the items in the list? Try changing "value = 17" to "value = 2." Since 2 is not on the list, LOOKDOWN leaves result unaffected. Since result contained 15 before LOOKDOWN executed, DEBUG prints "Value matches item 15 in list." By strategically setting the initial value of result, as we have here, your program can be written to detect when an item was not found in the list.

Don't forget that text phrases are just lists of byte values, so they too are eligible for LOOKDOWN searches, as in this example:

SYMBOL  value   = B2
SYMBOL  result  = B3

Setup:
  value = "f"
  result = 255

Main:
  LOOKDOWN value, ("The quick brown fox"), result
  DEBUG "Value matches item ", #result, "in list"
  END

value   VAR     Byte
result  VAR     Byte

Setup:
  value = "f"
  result = 255

Main:
  LOOKDOWN value, ["The quick brown fox"], result
  DEBUG "Value matches item ", DEC result, " in list"
  END

DEBUG prints, "Value matches item 16 in list" because the character at index item 16 is "f" in the phrase, "The quick brown fox".

The examples above show LOOKDOWN working with lists of constants, but it also works with variables and expressions also. Note, however, that expressions are not allowed as argument on the BS1.

On the BS2, BS2e, BS2sx, BS2p and BS2pe, the LOOKDOWN command can also use another criteria (other than "equal to") for its list. All of the examples above use LOOKDOWN's default comparison operator, =, that searches for an exact match. The entire list of ComaprisonOps is shown below. The "greater than" comparison operator (>) is used in the following example:

value   VAR     Byte
result  VAR     Byte

Setup:
  value = 17
  result = 15

Main:
  LOOKDOWN value, >[26, 177, 13, 1, 0, 17, 99], result
  DEBUG "Value greater than item ", DEC result, " in list"
  END

DEBUG prints, "Value greater than item 2 in list" because the first item the value 17 is greater than is 13 (which is item 2 in the list). Value is also greater than items 3 and 4, but these are ignored, because LOOKDOWN only cares about the first item that matches the criteria. This can require a certain amount of planning in devising the order of the list. To see a complete program, see the LOOKDOWN Examples.

LOOKDOWN comparison operators use unsigned 16-bit math. They will not work correctly with signed numbers, which are represented internally as two's complement (large 16-bit integers). For example, the two's complement representation of -99 is 65437. So although -99 is certainly less than 0, it would appear to be larger than zero to the LOOKDOWN comparison operators. The bottom line is: Don't used signed numbers with LOOKDOWN comparisons.

A common application for LOOKDOWN is to use it in conjunction with the BRANCH command to create selective jumps based on a simple variable input:

SYMBOL  cmd     = B2

Setup:
  cmd = "M"

Main:
  LOOKDOWN cmd, ("SLMH"), cmd
  BRANCH cmd, (_Stop, _Low, _Medium, _High)
  DEBUG "Command not in list"
  END

_Stop: 
  DEBUG "Stop"
  END

_Low:
  DEBUG "Low"
  END

_Medium:
  DEBUG "Medium"
  END

_High:
  DEBUG "High"
  END

cmd     VAR     Byte

Setup:
  cmd = "M"

Main:
  LOOKDOWN cmd, ["SLMH"], cmd
  BRANCH cmd, [_Stop, _Low, _Medium, _High]
  DEBUG "Command not in list"
  END

_Stop: 
  DEBUG "Stop"
  END

_Low:
  DEBUG "Low"
  END

_Medium:
  DEBUG "Medium"
  END

_High:
  DEBUG "High"
  END

In this example, cmd contains "M" (ASCII 77). LOOKDOWN finds that this is item 2 of a list of one-character commands and stores 2 into cmd. BRANCHthen goes to item 2 of its list, which is the program label "_Medium" at which point DEBUG prints "Medium" on the PC screen. This is a powerful method for interpreting user input, and a lot neater than the alternative IF...THENinstructions.

Another great use of LOOKDOWN is in combination with LOOKUP to "map" non-contiguous sets of numbers together. For example, you may have an application where certain numbers are received by the BASIC Stamp and, in response, the BASIC Stamp needs to send a specific set of numbers. This may be easy to code if the numbers are contiguous, or follow some known algebraic equation... but what if they don't? The table below shows some sample, non-contiguous inputs and the corresponding outputs the BASIC Stamp needs to respond with:

So, if we receive the number 5, we need to output 16. If we received 43, we need to output 24, and so on. These numbers are not contiguous and they don't appear to be derived from any simple algorithm. We can solve this problem with two lines of code, as follows:

  LOOKDOWN value, [5, 14, 1, 43, 26, 22, 30], value
  LOOKUP value, [16, 17, 18, 24, 10, 12, 11], value

Assuming our received number is in value, the first line (LOOKDOWN) will find the value in the list and store the index of the location that matches back into value. (This step "maps" the non-contiguous numbers: 5, 14, 1, etc, to a contiguous set of numbers: 0, 1, 2, etc). The second line (LOOKUP) takes our new value, finds the number at that location and stores it back into value. If the received value was 14, LOOKDOWN stores 1 into value and LOOKUP looks at the value at location 1 and stores 17 in value. The number 43 gets mapped to 3, 3 gets mapped to 24, and so on. This is a quick and easy fix for a potentially messy problem!