| blob | 8d99ff6bf62fc70dd03f388c12ab3c66bdde4efb |
1 @menu
2 * Lisp and Maxima::
3 * Garbage Collection::
4 * Introduction to Program Flow::
5 * Functions and Variables for Program Flow::
6 @end menu
8 @c -----------------------------------------------------------------------------
9 @node Lisp and Maxima, Garbage Collection, Program Flow, Program Flow
10 @section Lisp and Maxima
11 @c -----------------------------------------------------------------------------
13 Maxima is a fairly complete programming language. But since it is written in
14 Lisp, it additionally can provide easy access to Lisp functions and variables
15 from Maxima and vice versa. Lisp and Maxima symbols are distinguished by a
16 naming convention. A Lisp symbol which begins with a dollar sign @code{$}
17 corresponds to a Maxima symbol without the dollar sign.
19 @c NEED TO MENTION THIS OR IS IT JUST CLUTTERING ??
20 @c This includes special Maxima variables such as @code{%} and input and output
21 @c labels, which appear as @code{$%}, @code{$%i1}, @code{$%o1}, etc., in Lisp.
23 A Maxima symbol which begins with a question mark @code{?} corresponds to a Lisp
24 symbol without the question mark. For example, the Maxima symbol @code{foo}
25 corresponds to the Lisp symbol @code{$FOO}, while the Maxima symbol @code{?foo}
26 corresponds to the Lisp symbol @code{FOO}. Note that @code{?foo} is written
27 without a space between @code{?} and @code{foo}; otherwise it might be mistaken
28 for @code{describe ("foo")}.
30 Hyphen @code{-}, asterisk @code{*}, or other special characters in Lisp symbols
31 must be escaped by backslash @code{\} where they appear in Maxima code. For
32 example, the Lisp identifier @code{*foo-bar*} is written @code{?\*foo\-bar\*}
33 in Maxima.
35 Lisp code may be executed from within a Maxima session. A single line of Lisp
36 (containing one or more forms) may be executed by the special command
37 @code{:lisp}. For example,
39 @example
40 (%i1) :lisp (foo $x $y)
41 @end example
43 @noindent
44 calls the Lisp function @code{foo} with Maxima variables @code{x} and @code{y}
45 as arguments. The @code{:lisp} construct can appear at the interactive prompt
46 or in a file processed by @mref{batch} or @mrefcomma{demo} but not in a file
47 processed by @mrefcomma{load} @mrefcomma{batchload}@w{}
48 @mrefcomma{translate_file} or @mrefdot{compile_file}
50 The function @mref{to_lisp} opens an interactive Lisp session.
51 Entering @code{(to-maxima)} closes the Lisp session and returns to Maxima.
52 @c I DON'T EVEN WANT TO MENTION USING CTRL-C TO OPEN A LISP SESSION.
53 @c (1) IT TAKES EXTRA SET UP TO GET STARTED NAMELY :lisp (setq *debugger-hook* nil)
54 @c (2) IT GETS SCREWED UP EASILY -- TYPE SOMETHING WRONG AND YOU CAN'T GET BACK TO MAXIMA
55 @c (3) IT DOESN'T OFFER FUNCTIONALITY NOT PRESENT IN THE to_lisp() SESSION
57 Lisp functions and variables which are to be visible in Maxima as functions and
58 variables with ordinary names (no special punctuation) must have Lisp names
59 beginning with the dollar sign @code{$}.
61 Maxima is case-sensitive, distinguishing between lowercase and uppercase letters
62 in identifiers. There are some rules governing the translation of names between
63 Lisp and Maxima.
65 @enumerate
66 @item
67 A Lisp identifier not enclosed in vertical bars corresponds to a Maxima
68 identifier in lowercase. Whether the Lisp identifier is uppercase, lowercase,
69 or mixed case, is ignored. E.g., Lisp @code{$foo}, @code{$FOO}, and @code{$Foo}
70 all correspond to Maxima @code{foo}. But this is because @code{$foo},
71 @code{$FOO} and @code{$Foo} are converted by the Lisp reader by default to the
72 Lisp symbol @code{$FOO}.
73 @item
74 A Lisp identifier which is all uppercase or all lowercase and enclosed in
75 vertical bars corresponds to a Maxima identifier with case reversed. That is,
76 uppercase is changed to lowercase and lowercase to uppercase. E.g., Lisp
77 @code{|$FOO|} and @code{|$foo|} correspond to Maxima @code{foo} and @code{FOO},
78 respectively.
79 @item
80 A Lisp identifier which is mixed uppercase and lowercase and enclosed in
81 vertical bars corresponds to a Maxima identifier with the same case. E.g.,
82 Lisp @code{|$Foo|} corresponds to Maxima @code{Foo}.
83 @end enumerate
85 The @code{#$} Lisp macro allows the use of Maxima expressions in Lisp code.
86 @code{#$@var{expr}$} expands to a Lisp expression equivalent to the Maxima
87 expression @var{expr}.
89 @example
90 (msetq $foo #$[x, y]$)
91 @end example
93 @noindent
94 This has the same effect as entering
96 @example
97 (%i1) foo: [x, y];
98 @end example
100 @noindent
101 The Lisp function @code{displa} prints an expression in Maxima format.
103 @example
104 (%i1) :lisp #$[x, y, z]$
105 ((MLIST SIMP) $X $Y $Z)
106 (%i1) :lisp (displa '((MLIST SIMP) $X $Y $Z))
107 [x, y, z]
108 NIL
109 @end example
111 Functions defined in Maxima are not ordinary Lisp functions. The Lisp function
112 @code{mfuncall} calls a Maxima function. For example:
114 @example
115 (%i1) foo(x,y) := x*y$
116 (%i2) :lisp (mfuncall '$foo 'a 'b)
117 ((MTIMES SIMP) A B)
118 @end example
120 Some Lisp functions are shadowed in the Maxima package, namely the following.
122 @verbatim
123 complement continue //
124 float functionp array
125 exp listen signum
126 atan asin acos
127 asinh acosh atanh
128 tanh cosh sinh
129 tan break gcd
130 @end verbatim
132 @opencatbox{Categories:}
133 @category{Programming}
134 @closecatbox
136 @c -----------------------------------------------------------------------------
137 @node Garbage Collection, Introduction to Program Flow, Lisp and Maxima, Program Flow
138 @section Garbage Collection
139 @c -----------------------------------------------------------------------------
141 One of the advantages of using lisp is that it uses ``Garbage Collection''. In other
142 words it automatically takes care of freeing memory occupied for example of
143 intermediate results that were used during symbolic computation.
145 Garbage Collection avoids many errors frequently found in C programs (memory
146 being freed too early, multiple times or not at all).
148 @c -----------------------------------------------------------------------------
150 @anchor{garbage_collect}
151 @deffn {Function} garbage_collect ()
153 Tries to manually trigger the lisp's garbage collection. This rarely is necessary
154 as the lisp will employ an excellent algorithm for determining when to start
155 garbage collection.
157 If maxima knows how to do manually trigger the garbage collection for the
158 current lisp @code{garbage_collect} returns @code{true}, else @code{false}.
160 @opencatbox{Categories:}
161 @category{Programming}
162 @closecatbox
163 @end deffn
165 @c -----------------------------------------------------------------------------
166 @node Introduction to Program Flow, Functions and Variables for Program Flow, Garbage Collection, Program Flow
167 @section Introduction to Program Flow
168 @c -----------------------------------------------------------------------------
170 Maxima provides a @code{do} loop for iteration, as well as more primitive
171 constructs such as @code{go}.
173 @c end concepts Program Flow
175 @c -----------------------------------------------------------------------------
176 @node Functions and Variables for Program Flow, , Introduction to Program Flow, Program Flow
177 @section Functions and Variables for Program Flow
178 @c -----------------------------------------------------------------------------
180 @c -----------------------------------------------------------------------------
181 @anchor{backtrace}
182 @deffn {Function} backtrace @
183 @fname{backtrace} () @
184 @fname{backtrace} (@var{n})
186 Prints the call stack, that is, the list of functions which
187 called the currently active function.
189 @code{backtrace ()} prints the entire call stack.
191 @code{backtrace (@var{n})} prints the @var{n} most recent
192 functions, including the currently active function.
194 @c IS THIS STATEMENT REALLY NEEDED ??
195 @c (WHY WOULD ANYONE BELIEVE backtrace CANNOT BE CALLED OUTSIDE A DEBUGGING CONTEXT??)
196 @code{backtrace} can be called from a script, a function, or the interactive
197 prompt (not only in a debugging context).
199 Examples:
201 @itemize @bullet
202 @item
203 @code{backtrace ()} prints the entire call stack.
205 @example
206 (%i1) h(x) := g(x/7)$
207 (%i2) g(x) := f(x-11)$
208 (%i3) f(x) := e(x^2)$
209 (%i4) e(x) := (backtrace(), 2*x + 13)$
210 (%i5) h(10);
211 #0: e(x=4489/49)
212 #1: f(x=-67/7)
213 #2: g(x=10/7)
214 #3: h(x=10)
215 9615
216 (%o5) ----
217 49
218 @end example
219 @end itemize
221 @itemize @bullet
222 @item
223 @code{backtrace (@var{n})} prints the @var{n} most recent
224 functions, including the currently active function.
226 @example
227 (%i1) h(x) := (backtrace(1), g(x/7))$
228 (%i2) g(x) := (backtrace(1), f(x-11))$
229 (%i3) f(x) := (backtrace(1), e(x^2))$
230 (%i4) e(x) := (backtrace(1), 2*x + 13)$
231 (%i5) h(10);
232 #0: h(x=10)
233 #0: g(x=10/7)
234 #0: f(x=-67/7)
235 #0: e(x=4489/49)
236 9615
237 (%o5) ----
238 49
239 @end example
240 @end itemize
242 @opencatbox{Categories:}
243 @category{Debugging}
244 @closecatbox
245 @end deffn
247 @c -----------------------------------------------------------------------------
248 @anchor{do}
249 @anchor{while}
250 @anchor{unless}
251 @anchor{for}
252 @anchor{from}
253 @anchor{thru}
254 @anchor{step}
255 @anchor{next}
256 @anchor{in}
257 @deffn {Special operator} do
258 @deffnx {Special operator} while
259 @deffnx {Special operator} unless
260 @deffnx {Special operator} for
261 @deffnx {Special operator} from
262 @deffnx {Special operator} thru
263 @deffnx {Special operator} step
264 @deffnx {Special operator} next
265 @deffnx {Special operator} in
267 The @code{do} statement is used for performing iteration. The general
268 form of the @code{do} statements maxima supports is:
270 @itemize @bullet
271 @item
272 @code{for @var{variable}: @var{initial_value} step @var{increment}
273 thru @var{limit} do @var{body}}
274 @item
275 @code{for @var{variable}: @var{initial_value} step @var{increment}
276 while @var{condition} do @var{body}}
277 @item
278 @code{for @var{variable}: @var{initial_value} step @var{increment}
279 unless @var{condition} do @var{body}}
280 @item
281 @code{for @var{variable} in @var{list} do @var{body}}
282 @end itemize
284 If the loop is expected to generate a list as output the command
285 @mref{makelist} may be the appropriate command to use instead,
286 @xref{Performance considerations for Lists}.
288 @var{initial_value}, @var{increment}, @var{limit}, and @var{body} can be any
289 expression. @var{list} is a list. If the increment is 1 then "@code{step 1}"
290 may be omitted; As always, if @code{body} needs to contain more than one command
291 these commands can be specified as a comma-separated list surrounded
292 by parenthesis or as a @mrefdot{block}
293 Due to its great generality the @code{do} statement will be described in two parts.
294 The first form of the @code{do} statement (which is shown in the first three
295 items above) is analogous to that used in
296 several other programming languages (Fortran, Algol, PL/I, etc.); then
297 the other features will be mentioned.
299 The execution of the @code{do} statement proceeds by first assigning
300 the @var{initial_value} to the @var{variable} (henceforth called the
301 control-variable). Then: (1) If the control-variable has exceeded the
302 limit of a @code{thru} specification, or if the condition of the
303 @code{unless} is @code{true}, or if the condition of the @code{while}
304 is @code{false} then the @code{do} terminates. (2) The @var{body} is
305 evaluated. (3) The increment is added to the control-variable. The
306 process from (1) to (3) is performed repeatedly until the termination
307 condition is satisfied. One may also give several termination
308 conditions in which case the @code{do} terminates when any of them is
309 satisfied.
311 In general the @code{thru} test is satisfied when the control-variable
312 is greater than the @var{limit} if the @var{increment} was
313 non-negative, or when the control-variable is less than the
314 @var{limit} if the @var{increment} was negative. The
315 @var{increment} and @var{limit} may be non-numeric expressions as
316 long as this inequality can be determined. However, unless the
317 @var{increment} is syntactically negative (e.g. is a negative number)
318 at the time the @code{do} statement is input, Maxima assumes it will
319 be positive when the @code{do} is executed. If it is not positive,
320 then the @code{do} may not terminate properly.
322 Note that the @var{limit}, @var{increment}, and termination condition are
323 evaluated each time through the loop. Thus if any of these involve
324 much computation, and yield a result that does not change during all
325 the executions of the @var{body}, then it is more efficient to set a
326 variable to their value prior to the @code{do} and use this variable in the
327 @code{do} form.
329 The value normally returned by a @code{do} statement is the atom
330 @code{done}. However, the function @code{return} may be used inside
331 the @var{body} to exit the @code{do} prematurely and give it any
332 desired value. Note however that a @code{return} within a @code{do}
333 that occurs in a @code{block} will exit only the @code{do} and not the
334 @code{block}. Note also that the @code{go} function may not be used
335 to exit from a @code{do} into a surrounding @code{block}.
337 The control-variable is always local to the @code{do} and thus any
338 variable may be used without affecting the value of a variable with
339 the same name outside of the @code{do}. The control-variable is unbound
340 after the @code{do} terminates.
342 @example
343 (%i1) for a:-3 thru 26 step 7 do display(a)$
344 a = - 3
346 a = 4
348 a = 11
350 a = 18
352 a = 25
353 @end example
355 @c ===beg===
356 @c s: 0$
357 @c for i: 1 while i <= 10 do s: s+i;
358 @c s;
359 @c ===end===
360 @example
361 (%i1) s: 0$
362 (%i2) for i: 1 while i <= 10 do s: s+i;
363 (%o2) done
364 (%i3) s;
365 (%o3) 55
366 @end example
368 Note that the condition @code{while i <= 10}
369 is equivalent to @code{unless i > 10} and also @code{thru 10}.
371 @c ===beg===
372 @c series: 1$
373 @c term: exp (sin (x))$
374 @c for p: 1 unless p > 7 do
375 @c (term: diff (term, x)/p,
376 @c series: series + subst (x=0, term)*x^p)$
377 @c series;
378 @c ===end===
379 @example
380 (%i1) series: 1$
381 (%i2) term: exp (sin (x))$
382 (%i3) for p: 1 unless p > 7 do
383 (term: diff (term, x)/p,
384 series: series + subst (x=0, term)*x^p)$
385 (%i4) series;
386 7 6 5 4 2
387 x x x x x
388 (%o4) -- - --- - -- - -- + -- + x + 1
389 90 240 15 8 2
390 @end example
392 which gives 8 terms of the Taylor series for @code{e^sin(x)}.
394 @c ===beg===
395 @c poly: 0$
396 @c for i: 1 thru 5 do
397 @c for j: i step -1 thru 1 do
398 @c poly: poly + i*x^j$
399 @c poly;
400 @c guess: -3.0$
401 @c for i: 1 thru 10 do
402 @c (guess: subst (guess, x, 0.5*(x + 10/x)),
403 @c if abs (guess^2 - 10) < 0.00005 then return (guess));
404 @c ===end===
405 @example
406 (%i1) poly: 0$
407 (%i2) for i: 1 thru 5 do
408 for j: i step -1 thru 1 do
409 poly: poly + i*x^j$
410 (%i3) poly;
411 5 4 3 2
412 (%o3) 5 x + 9 x + 12 x + 14 x + 15 x
413 (%i4) guess: -3.0$
414 (%i5) for i: 1 thru 10 do
415 (guess: subst (guess, x, 0.5*(x + 10/x)),
416 if abs (guess^2 - 10) < 0.00005 then return (guess));
417 (%o5) - 3.162280701754386
418 @end example
420 This example computes the negative square root of 10 using the
421 Newton- Raphson iteration a maximum of 10 times. Had the convergence
422 criterion not been met the value returned would have been @code{done}.
424 Instead of always adding a quantity to the control-variable one
425 may sometimes wish to change it in some other way for each iteration.
426 In this case one may use @code{next @var{expression}} instead of
427 @code{step @var{increment}}. This will cause the control-variable to be set to
428 the result of evaluating @var{expression} each time through the loop.
430 @example
431 (%i6) for count: 2 next 3*count thru 20 do display (count)$
432 count = 2
434 count = 6
436 count = 18
437 @end example
439 @c UGH. DO WE REALLY NEED TO MENTION THIS??
440 As an alternative to @code{for @var{variable}: @var{value} ...do...}
441 the syntax @code{for @var{variable} from @var{value} ...do...} may be
442 used. This permits the @code{from @var{value}} to be placed after the
443 @code{step} or @code{next} value or after the termination condition.
444 If @code{from @var{value}} is omitted then 1 is used as the initial
445 value.
447 Sometimes one may be interested in performing an iteration where
448 the control-variable is never actually used. It is thus permissible
449 to give only the termination conditions omitting the initialization
450 and updating information as in the following example to compute the
451 square-root of 5 using a poor initial guess.
453 @c ===beg===
454 @c x: 1000$
455 @c thru 20 do x: 0.5*(x + 5.0/x)$
456 @c x;
457 @c sqrt(5), numer;
458 @c ===end===
459 @example
460 (%i1) x: 1000$
461 (%i2) thru 20 do x: 0.5*(x + 5.0/x)$
462 (%i3) x;
463 (%o3) 2.23606797749979
464 (%i4) sqrt(5), numer;
465 (%o4) 2.23606797749979
466 @end example
468 If it is desired one may even omit the termination conditions entirely
469 and just give @code{do @var{body}} which will continue to evaluate the
470 @var{body} indefinitely. In this case the function @code{return}
471 should be used to terminate execution of the @code{do}.
473 @c ===beg===
474 @c newton (f, x):= ([y, df, dfx], df: diff (f ('x), 'x),
475 @c do (y: ev(df), x: x - f(x)/y,
476 @c if abs (f (x)) < 5e-6 then return (x)))$
477 @c sqr (x) := x^2 - 5.0$
478 @c newton (sqr, 1000);
479 @c ===end===
480 @example
481 (%i1) newton (f, x):= ([y, df, dfx], df: diff (f ('x), 'x),
482 do (y: ev(df), x: x - f(x)/y,
483 if abs (f (x)) < 5e-6 then return (x)))$
484 (%i2) sqr (x) := x^2 - 5.0$
485 (%i3) newton (sqr, 1000);
486 (%o3) 2.236068027062195
487 @end example
489 @c DUNNO IF WE NEED THIS LEVEL OF DETAIL; THIS ARTICLE IS GETTING PRETTY LONG
490 (Note that @code{return}, when executed, causes the current value of @code{x} to
491 be returned as the value of the @code{do}. The @code{block} is exited and this
492 value of the @code{do} is returned as the value of the @code{block} because the
493 @code{do} is the last statement in the block.)
495 One other form of the @code{do} is available in Maxima. The syntax is:
497 @example
498 for @var{variable} in @var{list} @var{end_tests} do @var{body}
499 @end example
501 The elements of @var{list} are any expressions which will successively
502 be assigned to the @code{variable} on each iteration of the
503 @var{body}. The optional termination tests @var{end_tests} can be
504 used to terminate execution of the @code{do}; otherwise it will
505 terminate when the @var{list} is exhausted or when a @code{return} is
506 executed in the @var{body}. (In fact, @code{list} may be any
507 non-atomic expression, and successive parts are taken.)
509 @example
510 (%i1) for f in [log, rho, atan] do ldisp(f(1))$
511 (%t1) 0
512 (%t2) rho(1)
513 %pi
514 (%t3) ---
515 4
516 (%i4) ev(%t3,numer);
517 (%o4) 0.78539816
518 @end example
520 @opencatbox{Categories:}
521 @category{Programming}
522 @closecatbox
523 @end deffn
525 @c -----------------------------------------------------------------------------
526 @anchor{errcatch}
527 @deffn {Function} errcatch (@var{expr_1}, @dots{}, @var{expr_n})
529 Evaluates @var{expr_1}, @dots{}, @var{expr_n} one by one and
530 returns @code{[@var{expr_n}]} (a list) if no error occurs. If an
531 error occurs in the evaluation of any argument, @code{errcatch}
532 prevents the error from propagating and
533 returns the empty list @code{[]} without evaluating any more arguments.
535 @code{errcatch}
536 is useful in @code{batch} files where one suspects an error might occur which
537 would terminate the @code{batch} if the error weren't caught.
539 See also @mrefdot{errormsg}
541 @opencatbox{Categories:}
542 @category{Programming}
543 @closecatbox
544 @end deffn
546 @c -----------------------------------------------------------------------------
547 @anchor{error}
548 @deffn {Function} error (@var{expr_1}, @dots{}, @var{expr_n})
549 @deffnx {System variable} error
551 Evaluates and prints @var{expr_1}, @dots{}, @var{expr_n},
552 and then causes an error return to top level Maxima
553 or to the nearest enclosing @code{errcatch}.
555 The variable @code{error} is set to a list describing the error.
556 The first element of @code{error} is a format string, which merges all the
557 strings among the arguments @var{expr_1}, @dots{}, @var{expr_n},
558 and the remaining elements are the values of any non-string arguments.
560 @code{errormsg()} formats and prints @code{error}.
561 This is effectively reprinting the most recent error message.
563 @opencatbox{Categories:}
564 @category{Programming}
565 @closecatbox
566 @end deffn
568 @c -----------------------------------------------------------------------------
569 @anchor{warning}
570 @deffn {Function} warning (@var{expr_1}, @dots{}, @var{expr_n})
572 Evaluates and prints @var{expr_1}, @dots{}, @var{expr_n},
573 as a warning message that is formatted in a standard way so a maxima front-end
574 may be able to recognize the warning and to format it accordingly.
576 The function @code{warning} always returns false.
578 @opencatbox{Categories:}
579 @category{Programming}
580 @closecatbox
581 @end deffn
583 @c -----------------------------------------------------------------------------
584 @anchor{error_size}
585 @defvr {Option variable} error_size
586 Default value: 60
588 @code{error_size} modifies error messages according to the size of expressions
589 which appear in them. If the size of an expression (as determined by the Lisp
590 function @code{ERROR-SIZE}) is greater than @code{error_size}, the expression is
591 replaced in the message by a symbol, and the symbol is assigned the expression.
592 The symbols are taken from the list @mref{error_syms}.
594 Otherwise, the expression is smaller than @code{error_size}, and the expression
595 is displayed in the message.
597 See also @mref{error} and @mrefdot{error_syms}
599 Example:
600 @c OUTPUT GENERATED BY THE FOLLOWING
601 @c U: (C^D^E + B + A)/(cos(X-1) + 1)$
602 @c error_size: 20$
603 @c error ("Example expression is", U);
604 @c errexp1;
605 @c error_size: 30$
606 @c error ("Example expression is", U);
608 The size of @code{U}, as determined by @code{ERROR-SIZE}, is 24.
610 @example
611 (%i1) U: (C^D^E + B + A)/(cos(X-1) + 1)$
613 (%i2) error_size: 20$
615 (%i3) error ("Example expression is", U);
617 Example expression is errexp1
618 -- an error. Quitting. To debug this try debugmode(true);
619 (%i4) errexp1;
620 E
621 D
622 C + B + A
623 (%o4) --------------
624 cos(X - 1) + 1
625 (%i5) error_size: 30$
627 (%i6) error ("Example expression is", U);
629 E
630 D
631 C + B + A
632 Example expression is --------------
633 cos(X - 1) + 1
634 -- an error. Quitting. To debug this try debugmode(true);
635 @end example
637 @opencatbox{Categories:}
638 @category{Debugging}
639 @category{Display flags and variables}
640 @closecatbox
641 @end defvr
643 @c -----------------------------------------------------------------------------
644 @anchor{error_syms}
645 @defvr {Option variable} error_syms
646 Default value: @code{[errexp1, errexp2, errexp3]}
648 In error messages, expressions larger than @mref{error_size} are replaced by
649 symbols, and the symbols are set to the expressions. The symbols are taken from
650 the list @code{error_syms}. The first too-large expression is replaced by
651 @code{error_syms[1]}, the second by @code{error_syms[2]}, and so on.
653 If there are more too-large expressions than there are elements of
654 @code{error_syms}, symbols are constructed automatically, with the @var{n}-th
655 symbol equivalent to @code{concat ('errexp, @var{n})}.
657 See also @mref{error} and @mrefdot{error_size}
659 @opencatbox{Categories:}
660 @category{Debugging}
661 @category{Display flags and variables}
662 @closecatbox
663 @end defvr
665 @c -----------------------------------------------------------------------------
666 @anchor{errormsg_fn}
667 @deffn {Function} errormsg ()
669 Reprints the most recent error message.
670 The variable @code{error} holds the message,
671 and @mref{errormsg} formats and prints it.
673 @opencatbox{Categories:}
674 @category{Programming}
675 @closecatbox
676 @end deffn
678 @c -----------------------------------------------------------------------------
679 @anchor{errormsg}
680 @defvr {Option variable} errormsg
681 Default value: @code{true}
683 When @code{false} the output of error messages is suppressed.
685 The option variable @code{errormsg} can not be set in a block to a local
686 value. The global value of @code{errormsg} is always present.
688 @c ===beg===
689 @c errormsg;
690 @c sin(a,b);
691 @c errormsg: false;
692 @c sin(a,b);
693 @c ===end===
694 @example
695 @group
696 (%i1) errormsg;
697 (%o1) true
698 @end group
699 @group
700 (%i2) sin(a,b);
701 sin: wrong number of arguments.
702 -- an error. To debug this try: debugmode(true);
703 @end group
704 @group
705 (%i3) errormsg: false;
706 (%o3) false
707 @end group
708 @group
709 (%i4) sin(a,b);
710 -- an error. To debug this try: debugmode(true);
711 @end group
712 @end example
714 The option variable @code{errormsg} can not be set in a block to a local value.
716 @c ===beg===
717 @c f(bool):=block([errormsg:bool],
718 @c print ("value of errormsg is",errormsg))$
719 @c errormsg:true;
720 @c f(false);
721 @c errormsg:false;
722 @c f(true);
723 @c ===end===
724 @example
725 (%i1) f(bool):=block([errormsg:bool],
726 print ("value of errormsg is",errormsg))$
727 @group
728 (%i2) errormsg:true;
729 (%o2) true
730 @end group
731 @group
732 (%i3) f(false);
733 value of errormsg is true
734 (%o3) true
735 @end group
736 @group
737 (%i4) errormsg:false;
738 (%o4) false
739 @end group
740 @group
741 (%i5) f(true);
742 value of errormsg is false
743 (%o5) false
744 @end group
745 @end example
747 @opencatbox{Categories:}
748 @category{Programming}
749 @closecatbox
750 @end defvr
752 @c -----------------------------------------------------------------------------
753 @anchor{go}
754 @deffn {Function} go (@var{tag})
756 is used within a @mref{block} to transfer control to the statement
757 of the block which is tagged with the argument to @code{go}. To tag a
758 statement, precede it by an atomic argument as another statement in
759 the @code{block}. For example:
761 @example
762 block ([x], x:1, loop, x+1, ..., go(loop), ...)
763 @end example
765 The argument to @code{go} must be the name of a tag appearing in the same
766 @code{block}. One cannot use @code{go} to transfer to tag in a @code{block}
767 other than the one containing the @code{go}.
769 @opencatbox{Categories:}
770 @category{Programming}
771 @closecatbox
772 @end deffn
774 @c NEEDS CLARIFICATION, EXPANSION, EXAMPLES
775 @c THIS ITEM IS IMPORTANT
777 @c -----------------------------------------------------------------------------
778 @anchor{if}
779 @deffn {Special operator} if
781 Represents conditional evaluation. Various forms of @code{if} expressions are
782 recognized.
784 @code{if @var{cond_1} then @var{expr_1} else @var{expr_0}}
785 eva@-lu@-ates to @var{expr_1} if @var{cond_1} evaluates to @code{true},
786 otherwise the expression evaluates to @var{expr_0}.
788 The command @code{if @var{cond_1} then @var{expr_1} elseif @var{cond_2} then
789 @var{expr_2} elseif ... else @var{expr_0}} evaluates to @var{expr_k} if
790 @var{cond_k} is @code{true} and all preceding conditions are @code{false}. If
791 none of the conditions are @code{true}, the expression evaluates to
792 @code{expr_0}.
794 A trailing @code{else false} is assumed if @code{else} is missing. That is,
795 the command @code{if @var{cond_1} then @var{expr_1}} is equivalent to
796 @code{if @var{cond_1} then @var{expr_1} else false}, and the command
797 @code{if @var{cond_1} then @var{expr_1} elseif ... elseif @var{cond_n} then
798 @var{expr_n}} is equivalent to @code{if @var{cond_1} then @var{expr_1} elseif
799 ... elseif @var{cond_n} then @var{expr_n} else false}.
801 The alternatives @var{expr_0}, @dots{}, @var{expr_n} may be any Maxima
802 expressions, including nested @code{if} expressions. The alternatives are
803 neither simplified nor evaluated unless the corresponding condition is
804 @code{true}.
806 The conditions @var{cond_1}, @dots{}, @var{cond_n} are expressions which
807 potentially or actually evaluate to @code{true} or @code{false}.
808 When a condition does not actually evaluate to @code{true} or @code{false},
809 the behavior of @code{if} is governed by the global flag @code{prederror}.
810 When @code{prederror} is @code{true}, it is an error if any evaluated condition
811 does not evaluate to @code{true} or @code{false}. Otherwise, conditions which
812 do not evaluate to @code{true} or @code{false} are accepted, and the result is
813 a conditional expression.
815 Among other elements, conditions may comprise relational and logical operators
816 as follows.
818 @c - SEEMS LIKE THIS TABLE WANTS TO BE IN A DISCUSSION OF PREDICATE FUNCTIONS; PRESENT LOCATION IS OK I GUESS
819 @c - REFORMAT THIS TABLE USING TEXINFO MARKUP (MAYBE)
820 @example
821 Operation Symbol Type
823 less than < relational infix
824 less than <=
825 or equal to relational infix
826 equality (syntactic) = relational infix
827 negation of = # relational infix
828 equality (value) equal relational function
829 negation of equal notequal relational function
830 greater than >=
831 or equal to relational infix
832 greater than > relational infix
833 and and logical infix
834 or or logical infix
835 not not logical prefix
836 @end example
838 @opencatbox{Categories:}
839 @category{Programming}
840 @category{Predicate functions}
841 @closecatbox
842 @end deffn
844 @c NEEDS CLARIFICATION
845 @c THIS ITEM IS IMPORTANT
847 @c -----------------------------------------------------------------------------
848 @anchor{map}
849 @deffn {Function} map (@var{f}, @var{expr_1}, @dots{}, @var{expr_n})
851 Returns an expression whose leading operator is the same as that of the
852 expressions @var{expr_1}, @dots{}, @var{expr_n} but whose subparts are the
853 results of applying @var{f} to the corresponding subparts of the expressions.
854 @var{f} is either the name of a function of @math{n} arguments or is a
855 @code{lambda} form of @math{n} arguments.
857 @mref{maperror} - if @code{false} will cause all of the mapping
858 functions to (1) stop when they finish going down the shortest
859 @var{expr_i} if not all of the @var{expr_i} are of the same length and
860 (2) apply @var{f} to [@var{expr_1}, @var{expr_2}, @dots{}] if the
861 @var{expr_i} are not all the same type of object. If @code{maperror}
862 is @code{true} then an error message will be given in the above two
863 instances.
865 One of the uses of this function is to @code{map} a function (e.g.
866 @mref{partfrac}) onto each term of a very large expression where it ordinarily
867 wouldn't be possible to use the function on the entire expression due to an
868 exhaustion of list storage space in the course of the computation.
870 See also @mrefcomma{scanmap} @mrefcomma{maplist} @mrefcomma{outermap} @mref{matrixmap} and @mrefdot{apply}
872 @c IN THESE EXAMPLES, SPELL OUT WHAT IS THE MAIN OPERATOR
873 @c AND SHOW HOW THE RESULT FOLLOWS FROM THE DESCRIPTION STATED IN THE FIRST PARAGRAPH
875 @c ===beg===
876 @c map(f,x+a*y+b*z);
877 @c map(lambda([u],partfrac(u,x)),x+1/(x^3+4*x^2+5*x+2));
878 @c map(ratsimp, x/(x^2+x)+(y^2+y)/y);
879 @c map("=",[a,b],[-0.5,3]);
880 @c ===end===
881 @example
882 (%i1) map(f,x+a*y+b*z);
883 (%o1) f(b z) + f(a y) + f(x)
884 (%i2) map(lambda([u],partfrac(u,x)),x+1/(x^3+4*x^2+5*x+2));
885 1 1 1
886 (%o2) ----- - ----- + -------- + x
887 x + 2 x + 1 2
888 (x + 1)
889 (%i3) map(ratsimp, x/(x^2+x)+(y^2+y)/y);
890 1
891 (%o3) y + ----- + 1
892 x + 1
893 (%i4) map("=",[a,b],[-0.5,3]);
894 (%o4) [a = - 0.5, b = 3]
897 @end example
899 @opencatbox{Categories:}
900 @category{Function application}
901 @closecatbox
902 @end deffn
904 @c -----------------------------------------------------------------------------
905 @anchor{mapatom}
906 @deffn {Function} mapatom (@var{expr})
908 Returns @code{true} if and only if @var{expr} is treated by the mapping
909 routines as an atom. "Mapatoms" are atoms, numbers
910 (including rational numbers), subscripted variables and structure
911 references.
912 @c WHAT ARE "THE MAPPING ROUTINES", AND WHY DO THEY HAVE A SPECIALIZED NOTION OF ATOMS ??
914 @opencatbox{Categories:}
915 @category{Predicate functions}
916 @closecatbox
917 @end deffn
919 @c NEEDS CLARIFICATION
921 @c -----------------------------------------------------------------------------
922 @anchor{maperror}
923 @defvr {Option variable} maperror
924 Default value: @code{true}
926 When @code{maperror} is @code{false}, causes all of the mapping functions,
927 for example
929 @example
930 map (@var{f}, @var{expr_1}, @var{expr_2}, ...)
931 @end example
933 to (1) stop when they finish going down the shortest @var{expr_i} if
934 not all of the @var{expr_i} are of the same length and (2) apply
935 @var{f} to [@var{expr_1}, @var{expr_2}, @dots{}] if the @var{expr_i} are
936 not all the same type of object.
938 If @code{maperror} is @code{true} then an error message
939 is displayed in the above two instances.
941 @opencatbox{Categories:}
942 @category{Function application}
943 @closecatbox
944 @end defvr
946 @c -----------------------------------------------------------------------------
947 @anchor{mapprint}
948 @defvr {Option variable} mapprint
949 Default value: @code{true}
951 When @code{mapprint} is @code{true}, various information messages from
952 @mref{map}, @mref{maplist}, and @mref{fullmap} are produced in certain
953 situations. These include situations where @code{map} would use
954 @mref{apply}, or @code{map} is truncating on the shortest list.
956 If @mref{mapprint} is @code{false}, these messages are suppressed.
958 @opencatbox{Categories:}
959 @category{Function application}
960 @closecatbox
961 @end defvr
963 @c NEEDS CLARIFICATION
965 @c -----------------------------------------------------------------------------
966 @anchor{maplist}
967 @deffn {Function} maplist (@var{f}, @var{expr_1}, @dots{}, @var{expr_n})
969 Returns a list of the applications of @var{f} to the parts of the expressions
970 @var{expr_1}, @dots{}, @var{expr_n}. @var{f} is the name of a function, or a
971 lambda expression.
973 @code{maplist} differs from @code{map(@var{f}, @var{expr_1}, ..., @var{expr_n})}
974 which returns an expression with the same main operator as @var{expr_i} has
975 (except for simplifications and the case where @mref{map} does an @mref{apply}).
977 @opencatbox{Categories:}
978 @category{Function application}
979 @closecatbox
980 @end deffn
982 @c NEEDS CLARIFICATION
984 @c -----------------------------------------------------------------------------
985 @anchor{prederror}
986 @defvr {Option variable} prederror
987 Default value: @code{false}
989 When @code{prederror} is @code{true}, an error message is displayed whenever the
990 predicate of an @code{if} statement or an @mref{is} function fails to evaluate
991 to either @code{true} or @code{false}.
993 If @code{false}, @code{unknown} is returned
994 instead in this case. The @code{prederror: false} mode is not supported in
995 translated code;
996 however, @code{maybe} is supported in translated code.
998 See also @mref{is} and @mrefdot{maybe}
1000 @opencatbox{Categories:}
1001 @category{Programming}
1002 @category{Predicate functions}
1003 @closecatbox
1005 @end defvr
1007 @anchor{return}
1008 @deffn {Function} return (@var{value})
1009 May be used to exit explicitly from the current @mrefcomma{block} @mrefcomma{while}
1010 @mref{for} or @mref{do} loop bringing its argument. It therefore can be compared
1011 with the @code{return} statement found in other programming languages but it yields
1012 one difference: In maxima only returns from the current block, not from the entire
1013 function it was called in. In this aspect it more closely resembles the @code{break}
1014 statement from C.
1016 @c ===beg===
1017 @c for i:1 thru 10 do o:i;
1018 @c for i:1 thru 10 do if i=3 then return(i);
1019 @c for i:1 thru 10 do
1020 @c (
1021 @c block([i],
1022 @c i:3,
1023 @c return(i)
1024 @c ),
1025 @c return(8)
1026 @c );
1027 @c block([i],
1028 @c i:4,
1029 @c block([o],
1030 @c o:5,
1031 @c return(o)
1032 @c ),
1033 @c return(i),
1034 @c return(10)
1035 @c );
1036 @c ===end===
1037 @example
1038 @group
1039 (%i1) for i:1 thru 10 do o:i;
1040 (%o1) done
1041 @end group
1042 @group
1043 (%i2) for i:1 thru 10 do if i=3 then return(i);
1044 (%o2) 3
1045 @end group
1046 @group
1047 (%i3) for i:1 thru 10 do
1048 (
1049 block([i],
1050 i:3,
1051 return(i)
1052 ),
1053 return(8)
1054 );
1055 (%o3) 8
1056 @end group
1057 (%i4) block([i],
1058 i:4,
1059 block([o],
1060 o:5,
1061 return(o)
1062 ),
1063 return(i),
1064 return(10)
1065 );
1066 (%o4) 4
1067 @end example
1070 See also @mrefcomma{for} @mrefcomma{while} @mref{do} and @mref{block}.
1072 @opencatbox{Categories:}
1073 @category{Programming}
1074 @closecatbox
1075 @end deffn
1077 @c NEEDS CLARIFICATION
1078 @anchor{scanmap}
1079 @deffn {Function} scanmap @
1080 @fname{scanmap} (@var{f}, @var{expr}) @
1081 @fname{scanmap} (@var{f}, @var{expr}, bottomup)
1083 Recursively applies @var{f} to @var{expr}, in a top
1084 down manner. This is most useful when complete factorization is
1085 desired, for example:
1087 @example
1088 (%i1) exp:(a^2+2*a+1)*y + x^2$
1089 (%i2) scanmap(factor,exp);
1090 2 2
1091 (%o2) (a + 1) y + x
1092 @end example
1094 Note the way in which @code{scanmap} applies the given function
1095 @code{factor} to the constituent subexpressions of @var{expr}; if
1096 another form of @var{expr} is presented to @code{scanmap} then the
1097 result may be different. Thus, @code{%o2} is not recovered when
1098 @code{scanmap} is applied to the expanded form of @code{exp}:
1100 @example
1101 (%i3) scanmap(factor,expand(exp));
1102 2 2
1103 (%o3) a y + 2 a y + y + x
1104 @end example
1106 Here is another example of the way in which @code{scanmap} recursively
1107 applies a given function to all subexpressions, including exponents:
1109 @example
1110 (%i4) expr : u*v^(a*x+b) + c$
1111 (%i5) scanmap('f, expr);
1112 f(f(f(a) f(x)) + f(b))
1113 (%o5) f(f(f(u) f(f(v) )) + f(c))
1114 @end example
1116 @code{scanmap (@var{f}, @var{expr}, bottomup)} applies @var{f} to @var{expr} in a
1117 bottom-up manner. E.g., for undefined @code{f},
1119 @example
1120 scanmap(f,a*x+b) ->
1121 f(a*x+b) -> f(f(a*x)+f(b)) -> f(f(f(a)*f(x))+f(b))
1122 scanmap(f,a*x+b,bottomup) -> f(a)*f(x)+f(b)
1123 -> f(f(a)*f(x))+f(b) ->
1124 f(f(f(a)*f(x))+f(b))
1125 @end example
1127 In this case, you get the same answer both
1128 ways.
1130 @opencatbox{Categories:}
1131 @category{Function application}
1132 @closecatbox
1133 @end deffn
1135 @c -----------------------------------------------------------------------------
1136 @anchor{throw}
1137 @deffn {Function} throw (@var{expr})
1139 Evaluates @var{expr} and throws the value back to the most recent
1140 @mref{catch}. @code{throw} is used with @code{catch} as a nonlocal return
1141 mechanism.
1143 @opencatbox{Categories:}
1144 @category{Programming}
1145 @closecatbox
1146 @end deffn
1148 @c -----------------------------------------------------------------------------
1149 @anchor{outermap}
1150 @deffn {Function} outermap (@var{f}, @var{a_1}, @dots{}, @var{a_n})
1152 Applies the function @var{f} to each one of the elements of the outer product
1153 @var{a_1} cross @var{a_2} @dots{} cross @var{a_n}.
1155 @var{f} is the name of a function of @math{n} arguments or a lambda expression
1156 of @math{n} arguments. Each argument @var{a_k} may be a list or nested list,
1157 or a matrix, or any other kind of expression.
1159 The @code{outermap} return value is a nested structure. Let @var{x} be the
1160 return value. Then @var{x} has the same structure as the first list, nested
1161 list, or matrix argument, @code{@var{x}[i_1]...[i_m]} has the same structure as
1162 the second list, nested list, or matrix argument,
1163 @code{@var{x}[i_1]...[i_m][j_1]...[j_n]} has the same structure as the third
1164 list, nested list, or matrix argument, and so on, where @var{m}, @var{n},
1165 @dots{} are the numbers of indices required to access the elements of each
1166 argument (one for a list, two for a matrix, one or more for a nested list).
1167 Arguments which are not lists or matrices have no effect on the structure of
1168 the return value.
1170 Note that the effect of @code{outermap} is different from that of applying
1171 @var{f} to each one of the elements of the outer product returned by
1172 @mref{cartesian_product}. @code{outermap} preserves the structure of the
1173 arguments in the return value, while @code{cartesian_product} does not.
1175 @code{outermap} evaluates its arguments.
1177 See also @mrefcomma{map} @mrefcomma{maplist} and @mrefdot{apply}
1178 @c CROSS REF OTHER FUNCTIONS HERE ??
1180 Examples:
1182 Elementary examples of @code{outermap}.
1183 To show the argument combinations more clearly, @code{F} is left undefined.
1185 @c ===beg===
1186 @c outermap (F, [a, b, c], [1, 2, 3]);
1187 @c outermap (F, matrix ([a, b], [c, d]), matrix ([1, 2], [3, 4]));
1188 @c outermap (F, [a, b], x, matrix ([1, 2], [3, 4]));
1189 @c outermap (F, [a, b], matrix ([1, 2]), matrix ([x], [y]));
1190 @c outermap ("+", [a, b, c], [1, 2, 3]);
1191 @c ===end===
1192 @example
1193 @group
1194 (%i1) outermap (F, [a, b, c], [1, 2, 3]);
1195 (%o1) [[F(a, 1), F(a, 2), F(a, 3)], [F(b, 1), F(b, 2), F(b, 3)],
1196 [F(c, 1), F(c, 2), F(c, 3)]]
1197 @end group
1198 @group
1199 (%i2) outermap (F, matrix ([a, b], [c, d]), matrix ([1, 2], [3, 4]));
1200 [ [ F(a, 1) F(a, 2) ] [ F(b, 1) F(b, 2) ] ]
1201 [ [ ] [ ] ]
1202 [ [ F(a, 3) F(a, 4) ] [ F(b, 3) F(b, 4) ] ]
1203 (%o2) [ ]
1204 [ [ F(c, 1) F(c, 2) ] [ F(d, 1) F(d, 2) ] ]
1205 [ [ ] [ ] ]
1206 [ [ F(c, 3) F(c, 4) ] [ F(d, 3) F(d, 4) ] ]
1207 @end group
1208 @group
1209 (%i3) outermap (F, [a, b], x, matrix ([1, 2], [3, 4]));
1210 [ F(a, x, 1) F(a, x, 2) ] [ F(b, x, 1) F(b, x, 2) ]
1211 (%o3) [[ ], [ ]]
1212 [ F(a, x, 3) F(a, x, 4) ] [ F(b, x, 3) F(b, x, 4) ]
1213 @end group
1214 @group
1215 (%i4) outermap (F, [a, b], matrix ([1, 2]), matrix ([x], [y]));
1216 [ [ F(a, 1, x) ] [ F(a, 2, x) ] ]
1217 (%o4) [[ [ ] [ ] ],
1218 [ [ F(a, 1, y) ] [ F(a, 2, y) ] ]
1219 [ [ F(b, 1, x) ] [ F(b, 2, x) ] ]
1220 [ [ ] [ ] ]]
1221 [ [ F(b, 1, y) ] [ F(b, 2, y) ] ]
1222 @end group
1223 @group
1224 (%i5) outermap ("+", [a, b, c], [1, 2, 3]);
1225 (%o5) [[a + 1, a + 2, a + 3], [b + 1, b + 2, b + 3],
1226 [c + 1, c + 2, c + 3]]
1227 @end group
1228 @end example
1230 A closer examination of the @code{outermap} return value. The first, second,
1231 and third arguments are a matrix, a list, and a matrix, respectively.
1232 The return value is a matrix.
1233 Each element of that matrix is a list,
1234 and each element of each list is a matrix.
1236 @c ===beg===
1237 @c arg_1 : matrix ([a, b], [c, d]);
1238 @c arg_2 : [11, 22];
1239 @c arg_3 : matrix ([xx, yy]);
1240 @c xx_0 : outermap (lambda ([x, y, z], x / y + z), arg_1,
1241 @c arg_2, arg_3);
1242 @c xx_1 : xx_0 [1][1];
1243 @c xx_2 : xx_0 [1][1] [1];
1244 @c xx_3 : xx_0 [1][1] [1] [1][1];
1245 @c [op (arg_1), op (arg_2), op (arg_3)];
1246 @c [op (xx_0), op (xx_1), op (xx_2)];
1247 @c ===end===
1248 @example
1249 @group
1250 (%i1) arg_1 : matrix ([a, b], [c, d]);
1251 [ a b ]
1252 (%o1) [ ]
1253 [ c d ]
1254 @end group
1255 @group
1256 (%i2) arg_2 : [11, 22];
1257 (%o2) [11, 22]
1258 @end group
1259 @group
1260 (%i3) arg_3 : matrix ([xx, yy]);
1261 (%o3) [ xx yy ]
1262 @end group
1263 (%i4) xx_0 : outermap (lambda ([x, y, z], x / y + z), arg_1,
1264 arg_2, arg_3);
1265 [ [ a a ] [ a a ] ]
1266 [ [[ xx + -- yy + -- ], [ xx + -- yy + -- ]] ]
1267 [ [ 11 11 ] [ 22 22 ] ]
1268 (%o4) Col 1 = [ ]
1269 [ [ c c ] [ c c ] ]
1270 [ [[ xx + -- yy + -- ], [ xx + -- yy + -- ]] ]
1271 [ [ 11 11 ] [ 22 22 ] ]
1272 [ [ b b ] [ b b ] ]
1273 [ [[ xx + -- yy + -- ], [ xx + -- yy + -- ]] ]
1274 [ [ 11 11 ] [ 22 22 ] ]
1275 Col 2 = [ ]
1276 [ [ d d ] [ d d ] ]
1277 [ [[ xx + -- yy + -- ], [ xx + -- yy + -- ]] ]
1278 [ [ 11 11 ] [ 22 22 ] ]
1279 @group
1280 (%i5) xx_1 : xx_0 [1][1];
1281 [ a a ] [ a a ]
1282 (%o5) [[ xx + -- yy + -- ], [ xx + -- yy + -- ]]
1283 [ 11 11 ] [ 22 22 ]
1284 @end group
1285 @group
1286 (%i6) xx_2 : xx_0 [1][1] [1];
1287 [ a a ]
1288 (%o6) [ xx + -- yy + -- ]
1289 [ 11 11 ]
1290 @end group
1291 @group
1292 (%i7) xx_3 : xx_0 [1][1] [1] [1][1];
1293 a
1294 (%o7) xx + --
1295 11
1296 @end group
1297 @group
1298 (%i8) [op (arg_1), op (arg_2), op (arg_3)];
1299 (%o8) [matrix, [, matrix]
1300 @end group
1301 @group
1302 (%i9) [op (xx_0), op (xx_1), op (xx_2)];
1303 (%o9) [matrix, [, matrix]
1304 @end group
1305 @end example
1307 @code{outermap} preserves the structure of the arguments in the return value,
1308 while @code{cartesian_product} does not.
1310 @c ===beg===
1311 @c outermap (F, [a, b, c], [1, 2, 3]);
1312 @c setify (flatten (%));
1313 @c map (lambda ([L], apply (F, L)),
1314 @c cartesian_product ({a, b, c}, {1, 2, 3}));
1315 @c is (equal (%, %th (2)));
1316 @c ===end===
1317 @example
1318 @group
1319 (%i1) outermap (F, [a, b, c], [1, 2, 3]);
1320 (%o1) [[F(a, 1), F(a, 2), F(a, 3)], [F(b, 1), F(b, 2), F(b, 3)],
1321 [F(c, 1), F(c, 2), F(c, 3)]]
1322 @end group
1323 @group
1324 (%i2) setify (flatten (%));
1325 (%o2) @{F(a, 1), F(a, 2), F(a, 3), F(b, 1), F(b, 2), F(b, 3),
1326 F(c, 1), F(c, 2), F(c, 3)@}
1327 @end group
1328 @group
1329 (%i3) map (lambda ([L], apply (F, L)),
1330 cartesian_product (@{a, b, c@}, @{1, 2, 3@}));
1331 (%o3) @{F(a, 1), F(a, 2), F(a, 3), F(b, 1), F(b, 2), F(b, 3),
1332 F(c, 1), F(c, 2), F(c, 3)@}
1333 @end group
1334 @group
1335 (%i4) is (equal (%, %th (2)));
1336 (%o4) true
1337 @end group
1338 @end example
1340 @opencatbox{Categories:}
1341 @category{Function application}
1342 @closecatbox
1343 @end deffn