LOOKUP

Syntax : LOOKUP Index, (Value0, Value1, ...ValueN), Variable
Syntax : LOOKUP Index, [Value0, Value1, ...ValueN], Variable

Function

Find the value at location Index and store it in Variable. If Index exceeds the highest index value of the items in the list, Variable is left unaffected.

• Index is a variable/constant/expression* (0 - 255) indicating the list item to retrieve.
• Values are variables/constants/expressions* (0 - 65535).
• Variables is a variable that will be set to the value at the Index location. If Index exceeds the highest location number, Variable is left unaffected.

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

Quick Facts

Explanation

LOOKUP retrieves an item from a list based on the item's position, Index, in the list. For example:

SYMBOL  idx     = B2
SYMBOL  result  = B3

Setup:
  idx = 3
  result = 255
  
Main:
  LOOKUP idx, (26, 177, 13, 1, 0, 17, 99), result
  DEBUG  "Item ", #idx, "is: ", #result
  END

idx     VAR     Nib
result  VAR     Byte

Setup:
  idx = 3
  result = 255

Main:
  LOOKUP idx, [26, 177, 13, 1, 0, 17, 99], result
  DEBUG  "Item ", DEC idx, " is: ", DEC result
  END

In this example, DEBUG prints "Item 3 is: 1." Note that the first location number is 0. In the list above, item 0 is 26, item 1 is 177, etc.

If Index is beyond the end of the list, the result variable is unchanged. In the example above, if index were greater than 6, the message would have reported the result to be 255, because that's what result contained before LOOKUP executed.

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

SYMBOL  idx     = B2
SYMBOL  result  = B3

Setup:
  idx = 16
  result = "*"

Main:
  LOOKUP idx, ("The quick brown fox"), result
  DEBUG @result
  END

iidx     VAR     Byte
result  VAR     Byte

Setup:
  idx = 16
  result = "*"

Main:
  LOOKUP idx, ["The quick brown fox"], result
  DEBUG ASC? result
  END

DEBUG prints, "Result = 'f'" because the character at index item 16 is "f" in the phrase, "The quick brown fox".

The examples above show LOOKUP 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.

A great use of LOOKUP is in combination with LOOKDOWN 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 know algebraic equations… 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!