401 lines
19 KiB
HTML
401 lines
19 KiB
HTML
<?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>LOOKDOWN</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">LOOKDOWN</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/LookdownEx.htm" target="" title="" alt="" class="MCXref_0">LOOKDOWN 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">LOOKDOWN</span><i>Target</i>, (<i>Value0, Value1</i>, ...<i>ValueN </i>),<i> Variable</i><br />Syntax <img align="absmiddle" src="../../graphics/mini_2.gif" /> :
|
|
<span class="keyword_in_text">LOOKDOWN</span> <![CDATA[ ]]><i>Target</i>, {<i>ComparisonOp</i>} [<i>Value0</i>,<i> Value1</i>,
|
|
...<i>ValueN</i>],<i> Variable</i></p>
|
|
<h2>Function</h2>
|
|
<p class="PlainText">Compare <i>Target</i> value to a list of values and store the index number of
|
|
the first value that matches into <i>Variable</i>. If no value in the list matches,
|
|
<i>Variable</i> is left unaffected. On the BS2, BS2e, BS2sx and BS2p, the optional
|
|
<i>ComparisonOp</i> is used as criteria for the match; the default criteria is
|
|
"equal to."
|
|
|
|
</p>
|
|
<ul>
|
|
<li value="1"><b><i>Target</i></b> is a variable/constant/expression* (0 - 65535) to be
|
|
compared to the values in the list. </li>
|
|
<li value="2"><b><i>ComparisonOp</i></b> is an optional comparison operator (as described
|
|
below) to be used as the criteria when comparing values. When no
|
|
<i>ComparisonOp</i> is specified, equal to (=) is assumed. This argument is
|
|
not available on the BS1.</li>
|
|
<li value="3"><b><i>Values</i></b> are variables/constants/expressions* (0 - 65535) to
|
|
be compared to <i>Target</i>.</li>
|
|
<li value="4"><b><i>Variable</i></b> is a variable (usually a byte) that will be set to
|
|
the index (0 - 255) of the matching value in the <i>Values</i> list. If no
|
|
matching value is found, <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 value list contains no match...</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="LOOKUP.htm" target="" title="" alt="" class="MCXref_0">LOOKUP</a>
|
|
</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<h2>Explanation</h2>
|
|
<p class="PlainText"><span class="keyword_in_text">LOOKDOWN</span> works like the index in a book. In an index, you search for a
|
|
topic and get the page number. <span class="keyword_in_text">LOOKDOWN</span> searches for a target value in
|
|
a list, and stores the index number of the first match in a variable. For
|
|
example: </p>
|
|
<p>
|
|
<img src="../../graphics/bs1_inline.gif" border="0">
|
|
</img>
|
|
</p><pre class="BScode" xml:space="preserve">
|
|
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
|
|
</pre>
|
|
<p>
|
|
<img src="../../graphics/bs2all_inline.gif" border="0">
|
|
</img>
|
|
</p><pre class="BScode" xml:space="preserve">
|
|
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
|
|
</pre>
|
|
<p class="PlainText"><span class="keyword_in_text">DEBUG</span> 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.</p>
|
|
<p class="PlainText">What happens if the value doesn't match any of the items in the list? Try
|
|
changing "<span class="code_in_text">value = 17</span>" to "<span class="code_in_text">value = 2.</span>" Since 2 is not on the list, <span class="keyword_in_text">LOOKDOWN</span>
|
|
leaves <span class="code_in_text">result </span>unaffected. Since <span class="code_in_text">result </span>contained 15 before <span class="keyword_in_text">LOOKDOWN</span>
|
|
executed, <span class="keyword_in_text">DEBUG</span> prints "Value matches item 15 in list." By strategically
|
|
setting the initial value of <span class="code_in_text">result</span>, as we have here, your program can be written
|
|
to detect when an item was not found in the list. </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">LOOKDOWN</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 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
|
|
</pre>
|
|
<p>
|
|
<img src="../../graphics/bs2all_inline.gif" border="0">
|
|
</img>
|
|
</p><pre class="BScode" xml:space="preserve">
|
|
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
|
|
</pre>
|
|
<p><span class="keyword_in_text">DEBUG</span> prints, "Value matches item 16 in list" 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">LOOKDOWN</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>
|
|
<img src="../../graphics/bs2all_inline.gif" border="0">
|
|
</img>
|
|
</p>
|
|
<p class="PlainText">On the BS2, BS2e, BS2sx, BS2p and BS2pe, the <span class="keyword_in_text">LOOKDOWN</span> command can also
|
|
use another criteria (other than "equal to") for its list. All of the examples
|
|
above use <span class="keyword_in_text">LOOKDOWN</span>'s default comparison operator, =, that searches for an
|
|
exact match. The entire list of <i>ComaprisonOps</i> is shown below. The
|
|
"greater than" comparison operator (>) is used in the following example: </p><pre class="BScode" xml:space="preserve">
|
|
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
|
|
</pre>
|
|
<p class="PlainText"><span class="keyword_in_text">DEBUG</span> 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 <span class="keyword_in_text">LOOKDOWN</span>
|
|
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
|
|
<a href="../ExampleTopics/LookdownEx.htm" target="" title="" alt="" class="MCXref_0">LOOKDOWN Examples</a>.</p>
|
|
<p class="PlainText"><span class="keyword_in_text">LOOKDOWN</span> 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 <span class="keyword_in_text">LOOKDOWN</span> comparison operators.
|
|
The bottom line is: Don't used signed numbers with <span class="keyword_in_text">LOOKDOWN</span> comparisons.</p>
|
|
<center>
|
|
<table width="80%" cellpadding="4" cellspacing="0" border="1">
|
|
<tr>
|
|
<td width="25%" align="center" bgcolor="#CFCFCF">ComparisonOp Symbol</td>
|
|
<td width="55%" align="center" bgcolor="#CFCFCF">Description</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">=</td>
|
|
<td align="center">Find the first value Target is equal to</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center"><></td>
|
|
<td align="center">Find the first value Target is not equal to</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">></td>
|
|
<td align="center">Find the first value Target is greater than</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center"><</td>
|
|
<td align="center">Find the first value Target is less than</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">>=</td>
|
|
<td align="center">Find the first value Target is greater than or equal to</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center"><=</td>
|
|
<td align="center">Find the first value Target is less than or equal to</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
<p> </p>
|
|
<p class="PlainText">A common application for <span class="keyword_in_text">LOOKDOWN</span> is to use it in conjunction with the
|
|
<span class="keyword_in_text">BRANCH</span> command to create selective jumps based on a simple variable input: </p>
|
|
<p>
|
|
<img src="../../graphics/bs1_inline.gif" border="0">
|
|
</img>
|
|
</p><pre class="BScode" xml:space="preserve">
|
|
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
|
|
</pre>
|
|
<p>
|
|
<img src="../../graphics/bs2all_inline.gif" border="0">
|
|
</img>
|
|
</p><pre class="BScode" xml:space="preserve">
|
|
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
|
|
</pre>
|
|
<p class="PlainText">In this example, <span class="code_in_text">cmd </span>contains "M" (ASCII 77). <span class="keyword_in_text">LOOKDOWN</span> finds that this
|
|
is item 2 of a list of one-character commands and stores 2 into <span class="code_in_text">cmd</span>. <span class="keyword_in_text">BRANCH</span>then goes to item 2 of its list, which is the program label "<span class="code_in_text">_Medium</span>" at which
|
|
point <span class="keyword_in_text">DEBUG</span> prints "Medium" on the PC screen. This is a powerful method
|
|
for interpreting user input, and a lot neater than the alternative <span class="keyword_in_text">IF...THEN</span>instructions. </p>
|
|
<p class="PlainText">Another great use of <span class="keyword_in_text">LOOKDOWN</span> is in combination with <span class="keyword_in_text">LOOKUP</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 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:</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 value, 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 value 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> |