diff options
Diffstat (limited to 'docsrc/xlisp/xlisp-doc/reference/mapcar.htm')
| -rw-r--r-- | docsrc/xlisp/xlisp-doc/reference/mapcar.htm | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/docsrc/xlisp/xlisp-doc/reference/mapcar.htm b/docsrc/xlisp/xlisp-doc/reference/mapcar.htm new file mode 100644 index 0000000..8112cba --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/mapcar.htm @@ -0,0 +1,151 @@ +<html><head><title>XLISP mapcar</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>mapcar</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>
+
+<dl>
+<dt>(mapcar <i>function list1</i> [<i>list2</i> ... ])</dt>
+<dd><i>function</i> - a function definition like a
+<a href="lambda.htm">lambda</a> or a function name<br>
+<i>listN</i> - a list or list expression<br>
+returns - a list that is constructed from the results of the <i>function</i> applications</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The mapcan function 'mapcar' applies the 'function' to the succesive
+<a href="car.htm">car</a>s of each of the lists 'listN'. Each of
+the lists supplies one of the arguments to 'function'. The 'mapcar' function
+returns a list that is constructed from the results of the 'function'
+applications. If the lists are of different lengths, the shortest list will
+determine the number of applications of 'function'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+> (mapcar #'+ '(1 2 3) '(1 2 3))
+(2 4 6)
+
+> (mapcar #'princ '(1 2 3))
+123 <font color="#008844">; screen output</font>
+(1 2 3) <font color="#008844">; return value</font>
+
+> (mapcar #'+ '(1 2 3) '(1 2 3 4 5 6) <font color="#008844">; different length lists</font>
+(2 4 6)
+</pre>
+
+<p><b>Note:</b> The use of the 'function' will work properly when it is a
+<nobr>sharp-quoted</nobr> symbol, <nobr>a quoted</nobr> symbol [must be the
+name of a function], <nobr>an unquoted</nobr> symbol whose value is a
+function, or a closure object like a <a href="lambda.htm">lambda</a>
+form.</p>
+
+<p><div class="box">
+
+<p><b>Bug:</b> The proper syntax for 'function' when 'function' is a
+<a href="lambda.htm">lambda</a> expression is, for example:</p>
+
+<pre class="example">
+(mapcar #'(lambda (arg1 arg2) (+ arg1 arg2)) '(1 2))
+</pre>
+
+<p>and not:</p>
+
+<pre class="example">
+(mapcar '(lambda (arg1 arg2) (+ arg1 arg2)) '(1 2))
+</pre>
+
+<p>That is, the #' [<a href="function.htm">function</a>] read macro must be
+present. This error should be caught by the XLISP interpreter, but it is
+not, with the result that very obscure garbage collection bugs occur.
+<nobr>[I still</nobr> haven't tested Nyquist for possible garbage collection
+bugs caused by this.]</p>
+
+</div></p>
+
+<h2>Notes</h2>
+
+<p>In XLISP, a '<nobr>special form</nobr>' of type FSUBR is not a function.
+This means that 'mapcar' only works with functions of type SUBR
+<nobr>[built-in</nobr> function] or CLOSURE [function defined by
+<a href="defun.htm">defun</a>, <a href="flet.htm">flet</a>,
+<a href="labels.htm">labels</a>, or <a href="lambda.htm">lambda</a>], but
+with special forms of <nobr>type FSUBR</nobr> a 'bad function' error is
+signalled. Here is an example how to work around this behaviour:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">mapcar*</font> (function &rest args)
+ (if (eq (type-of (symbol-function (second function))) 'fsubr)
+ (let ((rest (gensym)))
+ `(mapcar #'(lambda (&rest ,rest)
+ (eval (cons ,function ,rest)))
+ ,@args))
+ `(mapcar ,function ,@args)))
+</pre>
+
+<p>Examples:</p>
+
+<pre class="example">
+(type-of #'eql) => SUBR <font color="#008844">; built-in function</font>
+(type-of #'and) => FSUBR <font color="#008844">; built-in special form</font>
+
+> (macroexpand-1 '(mapcar* #'eql '(1 2 3) '(t nil 3)))
+(MAPCAR (FUNCTION EQL)
+ (QUOTE (1 2 3))
+ (QUOTE (T NIL 3)))
+
+> (macroexpand-1 '(mapcar* #'and '(1 2 3) '(t nil 3)))
+(MAPCAR (FUNCTION (LAMBDA (&REST G7)
+ (EVAL (CONS (FUNCTION AND) G7))))
+ (QUOTE (1 2 3))
+ (QUOTE (T NIL 3)))
+
+(mapcar #'eql '(1 2 3) '(t nil 3))) => (NIL NIL T)
+(mapcar* #'eql '(1 2 3) '(t nil 3))) => (NIL NIL T)
+
+(mapcar #'and '(1 2 3) '(t nil 3))) => <font color="#AA0000">error: bad function</font>
+(mapcar* #'and '(1 2 3) '(t nil 3))) => (T NIL 3)
+</pre>
+
+
+<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 |