<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="6" MadCap:lastHeight="94" MadCap:lastWidth="853" MadCap:disableMasterStylesheet="true" MadCap:tocPath="" MadCap:InPreviewMode="false" MadCap:PreloadImages="false" MadCap:RuntimeFileType="Topic" MadCap:TargetType="WebHelp" lang="en-us" xml:lang="en-us" MadCap:PathToHelpSystem="../../../" MadCap:HelpSystemFileName="Default.xml" MadCap:SearchType="Stem">
<head><title>LOOKUP</title>
<link href="../../SkinSupport/MadCap.css" rel="stylesheet" />
<link href="../../Resources/Stylesheets/BSE_Help.css" rel="stylesheet" />
<script src="../../SkinSupport/MadCapAll.js" type="text/javascript">
</script>
</head>
<body>
<h1 class="code">LOOKUP</h1>
<div class="ImagePlusCaption">
<div class="Col2">
<p>
<img src="../../graphics/pgm_icon1.gif" border="0" alt="BS1 icon" title="BS1 icon" />
<img src="../../graphics/pgm_icon2.gif" border="0" alt="BS2 icon" title="BS2 icon" />
<img src="../../graphics/pgm_icon2e.gif" border="0" alt="BS2e icon" title="BS2e icon" />
<img src="../../graphics/pgm_icon2sx.gif" border="0" alt="BS2sx icon" title="BS2sx icon" />
<img src="../../graphics/pgm_icon2p.gif" border="0" alt="BS2p icon" title="BS2p icon" />
<img src="../../graphics/pgm_icon2pe.gif" border="0" alt="BS2pe icon" title="BS2pe icon" />
<img src="../../graphics/pgm_icon2px.gif" border="0" alt="BS2px icon" title="BS2px icon" />
</p>
</div>
<p style="text-align: right;"><a href="../ExampleTopics/LookupEx.htm" target="" title="" alt="" class="MCXref_0">LOOKUP Examples</a>
</p>
<p> </p>
</div>
<p class="clear"> </p>
<p> </p>
<p class="PlainText">Syntax <img align="absmiddle" src="../../graphics/mini_1.gif" /> :
<span class="keyword_in_text">LOOKUP</span> <![CDATA[ ]]><i>Index</i>, (<i>Value0</i>,<i> Value1</i>, ...<i>ValueN</i>),<i>
Variable</i><br />Syntax <img align="absmiddle" src="../../graphics/mini_2.gif" /> :
<span class="keyword_in_text">LOOKUP</span> <![CDATA[ ]]><i>Index</i>, [<i>Value0</i>,<i> Value1</i>, ...<i>ValueN</i>],<i>
Variable</i></p>
<h2>Function</h2>
<p class="PlainText">Find the value at location <i>Index</i> and store it in <i>Variable</i>.
If <i>Index</i> exceeds the highest index value of the items in the list,
<i>Variable</i> is left unaffected.
</p>
<ul>
<li value="1"><b><i>Index</i></b> is a variable/constant/expression* (0 - 255) indicating
the list item to retrieve. </li>
<li value="2"><b><i>Values</i></b> are variables/constants/expressions* (0 - 65535).</li>
<li value="3"><b><i>Variables</i></b> is a variable that will be set to the value at the
<i>Index</i> location. If <i>Index</i> exceeds the highest location number, <i>Variable</i> is left unaffected.</li>
</ul>
<p class="PlainText">*<img src="../../graphics/bs1note.gif" style="vertical-align: super;" /> Note: expressions are not allowed as arguments on the BS1.</p>
<h2>Quick Facts</h2>
<table width="100%" cellpadding="4" cellspacing="0" border="1">
<tr>
<td width="20%" align="center" bgcolor="#CFCFCF"> </td>
<td width="80%" align="center" bgcolor="#CFCFCF">All BASIC Stamp Modules</td>
</tr>
<tr>
<td align="center" bgcolor="#CFCFCF">Limit of value entries</td>
<td align="center">256</td>
</tr>
<tr>
<td align="center" bgcolor="#CFCFCF">Starting index number</td>
<td align="center">0</td>
</tr>
<tr>
<td align="center" bgcolor="#CFCFCF">If index exceeds the highest location...</td>
<td align="center"><i>Variable</i> is left unaffected</td>
</tr>
<tr>
<td align="center" bgcolor="#CFCFCF">Related Command</td>
<td align="center" colspan="1">
<p colspan="1" align="center"><a href="LOOKDOWN.htm" target="" title="" alt="" class="MCXref_0">LOOKDOWN</a>
</p>
</td>
</tr>
</table>
<h2>Explanation</h2>
<p class="PlainText"><span class="keyword_in_text">LOOKUP</span> retrieves an item from a list based on the item's position, Index,
in the list. For example: </p>
<p>
<img src="../../graphics/bs1_inline.gif" border="0">
</img>
</p><pre class="BScode" xml:space="preserve">
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
</pre>
<p>
<img src="../../graphics/bs2all_inline.gif" border="0">
</img>
</p><pre class="BScode" xml:space="preserve">
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
</pre>
<p class="PlainText">In this example, <span class="keyword_in_text">DEBUG</span> 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.</p>
<p class="PlainText">If <i>Index</i> 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 <span class="keyword_in_text">LOOKUP</span>
executed. </p>
<p class="PlainText">Don't forget that text phrases are just lists of byte values, so they too are
eligible for <span class="keyword_in_text">LOOKUP</span> searches, as in this example:</p>
<p>
<img src="../../graphics/bs1_inline.gif" border="0">
</img>
</p><pre class="BScode" xml:space="preserve">
SYMBOL idx = B2
SYMBOL result = B3
Setup:
idx = 16
result = "*"
Main:
LOOKUP idx, ("The quick brown fox"), result
DEBUG @result
END
</pre>
<p>
<img src="../../graphics/bs2all_inline.gif" border="0">
</img>
</p><pre class="BScode" xml:space="preserve">
iidx VAR Byte
result VAR Byte
Setup:
idx = 16
result = "*"
Main:
LOOKUP idx, ["The quick brown fox"], result
DEBUG ASC? result
END
</pre>
<p class="PlainText"><span class="keyword_in_text">DEBUG</span> prints, "Result = 'f'" because the character at index item 16 is
"f" in the phrase, "The quick brown fox".</p>
<p class="PlainText">The examples above show <span class="keyword_in_text">LOOKUP</span> 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. </p>
<p class="PlainText">A great use of <span class="keyword_in_text">LOOKUP</span> is in combination with <span class="keyword_in_text">LOOKDOWN</span> 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:</p>
<center>
<table width="60%" cellpadding="4" cellspacing="0" border="1">
<tr>
<td width="10%" align="center" bgcolor="#CFCFCF">Index</td>
<td width="25%" align="center" bgcolor="#CFCFCF">Each of these values
received (inputs):</td>
<td width="25%" align="center" bgcolor="#CFCFCF">Needs to result in each of
these values sent (outputs):</td>
</tr>
<tr>
<td align="center">0</td>
<td align="center">5</td>
<td align="center">16</td>
</tr>
<tr>
<td align="center">1</td>
<td align="center">14</td>
<td align="center">17</td>
</tr>
<tr>
<td align="center">2</td>
<td align="center">1</td>
<td align="center">18</td>
</tr>
<tr>
<td align="center">3</td>
<td align="center">43</td>
<td align="center">24</td>
</tr>
<tr>
<td align="center">4</td>
<td align="center">26</td>
<td align="center">10</td>
</tr>
<tr>
<td align="center">5</td>
<td align="center">22</td>
<td align="center">12</td>
</tr>
<tr>
<td align="center">6</td>
<td align="center">30</td>
<td align="center">11</td>
</tr>
</table>
</center>
<p> </p>
<p class="PlainText">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:</p><pre class="BScode" xml:space="preserve">
LOOKDOWN value, [5, 14, 1, 43, 26, 22, 30], value
LOOKUP value, [16, 17, 18, 24, 10, 12, 11], value
</pre>
<p class="PlainText">Assuming our received number is in <span class="code_in_text">value</span>, the first line (<span class="keyword_in_text">LOOKDOWN</span>)
will find the value in the list and store the index of the location that matches
back into <span class="code_in_text">value</span>. (This step "maps" the non-contiguous numbers: 5, 14, 1, etc,
to a contiguous set of numbers: 0, 1, 2, etc). The second line (<span class="keyword_in_text">LOOKUP</span>)
takes our new value, finds the number at that location and stores it back into
<span class="code_in_text">value</span>. If the received value was 14, <span class="keyword_in_text">LOOKDOWN</span> stores 1 into <span class="code_in_text">value </span>and
<span class="keyword_in_text">LOOKUP</span> looks at the value at location 1 and stores 17 in <span class="code_in_text">value</span>. 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!</p>
<div class="Col2">
<div class="MasterFoot">
<p MadCap:conditions="BSEconditions.BSEWebHelp (Primary)-INCLUDE"><a href="../../HomeTopics/HomePage.htm">Go to Welcome page</a>
</p>
</div>
</div>
<div class="Col2">
<div class="MasterFoot">
<p style="text-align: right;"><span class="ContactInfoProjectName">BASIC Stamp Help</span> <![CDATA[ ]]><span class="ContactInfoVersion#">Version 2.5.4</span> <![CDATA[ ]]></p>
<p style="text-align: right;">Copyright © <span class="ContactInfoCompanyName">Parallax Inc.</span></p>
<p style="text-align: right;"><span class="SystemShortDate">8/8/2012</span>
</p>
</div>
</div>
<script type="text/javascript">/* <![CDATA[ */
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-285614-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
/* ]]> */</script>
<script type="text/javascript" src="../../SkinSupport/MadCapBodyEnd.js">
</script>
</body>
</html>