diff options
Diffstat (limited to 'docsrc/xlisp/xlisp-doc/reference/assoc.htm')
| -rw-r--r-- | docsrc/xlisp/xlisp-doc/reference/assoc.htm | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/docsrc/xlisp/xlisp-doc/reference/assoc.htm b/docsrc/xlisp/xlisp-doc/reference/assoc.htm new file mode 100644 index 0000000..ab1344a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/assoc.htm @@ -0,0 +1,121 @@ +<html><head><title>XLISP assoc</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>assoc</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>assoc</b> <i>expr a-list</i> [{:test | :test-not} <i>test</i>])</dt>
+<dd><i>expr</i> - the expression to find as an atom or list<br>
+<i>a-list</i> - the association list to search<br>
+<i>test</i> - optional test function (default is <a href="eql.htm">eql</a>)<br>
+returns - the alist entry or <a href="nil.htm">NIL</a></dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>An association list is a collection of list pairs of the form:</p>
+
+<pre class="example">
+((<font color="#0000CC">key1 item1</font>) (<font color="#0000CC">key2 item2</font>) ... (<font color="#0000CC">keyN itemN</font>))
+</pre>
+
+<p>The 'assoc' function searches through an association list
+'<nobr>a-list</nobr>' looking for the key
+<nobr>[a <a href="car.htm">car</a></nobr> in an association pair] that
+matches the search 'expr'. <nobr>If a</nobr> match is found, that
+association pair is returned as the result. <nobr>If no</nobr> match is
+found, <nobr><a href="nil.htm">NIL</a> is</nobr> returned. <nobr>You
+may</nobr> specify your own test with the ':test' and
+'<nobr>:test-not</nobr>' keywords followed by the 'test' you wish to
+perform.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq mylist '((a . my-a)
+ (b . his-b)
+ (c . her-c)
+ (d . end)))
+
+(assoc 'a mylist) => (A . MY-A)
+(assoc 'b mylist) => (B . HIS-B)
+(assoc 1 mylist) => NIL
+</pre>
+
+<pre class="example">
+(setq agelist '((1 (bill bob))
+ (2 (jane jill))
+ (3 (tim tom))
+ (5 (larry daryl daryl))))
+
+(assoc 1 agelist) => (1 (BILL BOB))
+(assoc 3 agelist :test #'>=) => (1 (BILL BOB))
+(assoc 3 agelist :test #'<) => (5 (LARRY DARYL DARYL))
+(assoc 3 agelist :test #'<=) => (3 (TIM TOM))
+(assoc 3 agelist :test-not #'>=) => (5 (LARRY DARYL DARYL))
+</pre>
+
+<p>Using a list as key, tested with <a href="equal.htm">equal</a>:</p>
+
+<pre class="example">
+> (assoc '(a b) '(((c d) e) ((a b) x)) :test #'equal)
+((A B) X)
+</pre>
+
+<p><b>Note:</b> The 'assoc' function can work with a list or string as the
+'expr'. However, the default <a href="eql.htm">eql</a> test does
+not work with lists or strings, only symbols and numbers.
+<nobr>To make</nobr> this work, you need to use the ':test' keyword along
+with <a href="equal.htm">equal</a> <nobr>for 'test'</nobr>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#list-functions">List Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file |