doc/info/Expressions.texi

   1 @menu
   2 * Introduction to Expressions::
   3 * Nouns and Verbs::
   4 * Identifiers::
   5 * Inequality::
   6 * Functions and Variables for Expressions::
   7 @end menu
   8
   9 @c -----------------------------------------------------------------------------
  10 @node Introduction to Expressions, Nouns and Verbs, Expressions, Expressions
  11 @section Introduction to Expressions
  12 @c -----------------------------------------------------------------------------
  13
  14 There are a number of reserved words which should not be used as variable names.
  15 Their use would cause a possibly cryptic syntax error.
  16
  17 @example
  18 integrate            next           from                 diff
  19 in                   at             limit                sum
  20 for                  and            elseif               then
  21 else                 do             or                   if
  22 unless               product        while                thru
  23 step
  24 @end example
  25
  26 Most things in Maxima are expressions.  A sequence of expressions
  27 can be made into an expression by separating them by commas and
  28 putting parentheses around them.  This is similar to the @b{C}
  29 @i{comma expression}.
  30
  31 @c ===beg===
  32 @c x: 3$
  33 @c (x: x+1, x: x^2);
  34 @c (if (x > 17) then 2 else 4);
  35 @c (if (x > 17) then x: 2 else y: 4, y+x);
  36 @c ===end===
  37 @example
  38 (%i1) x: 3$
  39 (%i2) (x: x+1, x: x^2);
  40 (%o2)                          16
  41 (%i3) (if (x > 17) then 2 else 4);
  42 (%o3)                           4
  43 (%i4) (if (x > 17) then x: 2 else y: 4, y+x);
  44 (%o4)                          20
  45 @end example
  46
  47 Even loops in Maxima are expressions, although the value they
  48 return is the not too useful @code{done}.
  49
  50 @c ===beg===
  51 @c y: (x: 1, for i from 1 thru 10 do (x: x*i))$
  52 @c y;
  53 @c ===end===
  54 @example
  55 (%i1) y: (x: 1, for i from 1 thru 10 do (x: x*i))$
  56 (%i2) y;
  57 (%o2)                         done
  58 @end example
  59
  60 Whereas what you really want is probably to include a third
  61 term in the @i{comma expression} which actually gives back the value.
  62
  63 @c ===beg===
  64 @c y: (x: 1, for i from 1 thru 10 do (x: x*i), x)$
  65 @c y;
  66 @c ===end===
  67 @example
  68 (%i3) y: (x: 1, for i from 1 thru 10 do (x: x*i), x)$
  69 (%i4) y;
  70 (%o4)                        3628800
  71 @end example
  72
  73 @c -----------------------------------------------------------------------------
  74 @node Nouns and Verbs, Identifiers, Introduction to Expressions, Expressions
  75 @section Nouns and Verbs
  76 @c -----------------------------------------------------------------------------
  77
  78 Maxima distinguishes between operators which are "nouns" and operators which are
  79 "verbs".  A verb is an operator which can be executed.  A noun is an operator
  80 which appears as a symbol in an expression, without being executed.  By default,
  81 function names are verbs.  A verb can be changed into a noun by quoting the
  82 function name or applying the @mref{nounify} function.  A noun can be changed
  83 into a verb by applying the @mref{verbify} function.  The evaluation flag
  84 @mref{nouns} causes @mref{ev} to evaluate nouns in an expression.
  85
  86 The verb form is distinguished by a leading dollar sign @code{$} on the
  87 corresponding Lisp symbol.  In contrast, the noun form is distinguished by a
  88 leading percent sign @code{%} on the corresponding Lisp symbol.  Some nouns have
  89 special display properties, such as @code{'integrate} and @code{'derivative}
  90 (returned by @mref{diff}), but most do not.  By default, the noun and verb forms
  91 of a function are identical when displayed.  The global flag @mref{noundisp}@w{}
  92 causes Maxima to display nouns with a leading quote mark @code{'}.
  93
  94 See also @mrefcomma{noun} @mrefcomma{nouns} @mrefcomma{nounify} and
  95 @mrefdot{verbify}
  96
  97 Examples:
  98
  99 @c ===beg===
 100 @c foo (x) := x^2;
 101 @c foo (42);
 102 @c 'foo (42);
 103 @c 'foo (42), nouns;
 104 @c declare (bar, noun);
 105 @c bar (x) := x/17;
 106 @c bar (52);
 107 @c bar (52), nouns;
 108 @c integrate (1/x, x, 1, 42);
 109 @c 'integrate (1/x, x, 1, 42);
 110 @c ev (%, nouns);
 111 @c ===end===
 112 @example
 113 @group
 114 (%i1) foo (x) := x^2;
 115                                      2
 116 (%o1)                     foo(x) := x
 117 @end group
 118 @group
 119 (%i2) foo (42);
 120 (%o2)                         1764
 121 @end group
 122 @group
 123 (%i3) 'foo (42);
 124 (%o3)                        foo(42)
 125 @end group
 126 @group
 127 (%i4) 'foo (42), nouns;
 128 (%o4)                         1764
 129 @end group
 130 @group
 131 (%i5) declare (bar, noun);
 132 (%o5)                         done
 133 @end group
 134 @group
 135 (%i6) bar (x) := x/17;
 136                                     x
 137 (%o6)                     bar(x) := --
 138                                     17
 139 @end group
 140 @group
 141 (%i7) bar (52);
 142 (%o7)                        bar(52)
 143 @end group
 144 @group
 145 (%i8) bar (52), nouns;
 146 (%o8)                        bar(52)
 147 @end group
 148 @group
 149 (%i9) integrate (1/x, x, 1, 42);
 150 (%o9)                        log(42)
 151 @end group
 152 @group
 153 (%i10) 'integrate (1/x, x, 1, 42);
 154                              42
 155                             /
 156                             [   1
 157 (%o10)                      I   - dx
 158                             ]   x
 159                             /
 160                              1
 161 @end group
 162 @group
 163 (%i11) ev (%, nouns);
 164 (%o11)                       log(42)
 165 @end group
 166 @end example
 167
 168 @opencatbox{Categories:}
 169 @category{Evaluation}
 170 @category{Nouns and verbs}
 171 @closecatbox
 172
 173 @c -----------------------------------------------------------------------------
 174 @node Identifiers, Inequality, Nouns and Verbs, Expressions
 175 @section Identifiers
 176 @c -----------------------------------------------------------------------------
 177
 178 Maxima identifiers may comprise alphabetic characters, plus the numerals 0
 179 through 9, plus any other character preceded by the backslash @code{\}
 180 character.
 181
 182 A numeral may be the first character of an identifier if it is preceded by a
 183 backslash.  Numerals which are the second or later characters need not be
 184 preceded by a backslash.
 185
 186 The alphabetic characters are initially @code{%}, @code{_},
 187 and all characters for which the Lisp function
 188 @url{http://www.lispworks.com/documentation/HyperSpec/Body/f_alpha_.htm,
 189 @code{ALPHA-CHAR-P}} returns @code{true}.
 190 Characters may be declared alphabetic by the @code{declare} function.
 191 If so declared, they need not be preceded by a backslash in an identifier.
 192
 193 Maxima is case-sensitive.  The identifiers @code{foo}, @code{FOO}, and
 194 @code{Foo} are distinct.  See @ref{Lisp and Maxima} for more on this point.
 195
 196 A Maxima identifier is a Lisp symbol which begins with a dollar sign @code{$}.
 197 Any other Lisp symbol is preceded by a question mark @code{?} when it appears
 198 in Maxima.  See @ref{Lisp and Maxima} for more on this point.
 199
 200 Examples:
 201
 202 @c ===beg===
 203 @c %an_ordinary_identifier42;
 204 @c embedded\ spaces\ in\ an\ identifier;
 205 @c symbolp (%);
 206 @c [foo+bar, foo\+bar];
 207 @c [1729, \1729];
 208 @c [symbolp (foo\+bar), symbolp (\1729)];
 209 @c [is (foo\+bar = foo+bar), is (\1729 = 1729)];
 210 @c baz\~quux;
 211 @c declare ("~", alphabetic);
 212 @c baz~quux;
 213 @c [is (foo = FOO), is (FOO = Foo), is (Foo = foo)];
 214 @c :lisp (defvar *my-lisp-variable* '$foo)
 215 @c ?\*my\-lisp\-variable\*;
 216 @c ===end===
 217 @example
 218 @group
 219 (%i1) %an_ordinary_identifier42;
 220 (%o1)               %an_ordinary_identifier42
 221 @end group
 222 @group
 223 (%i2) embedded\ spaces\ in\ an\ identifier;
 224 (%o2)           embedded spaces in an identifier
 225 @end group
 226 @group
 227 (%i3) symbolp (%);
 228 (%o3)                         true
 229 @end group
 230 @group
 231 (%i4) [foo+bar, foo\+bar];
 232 (%o4)                 [foo + bar, foo+bar]
 233 @end group
 234 @group
 235 (%i5) [1729, \1729];
 236 (%o5)                     [1729, 1729]
 237 @end group
 238 @group
 239 (%i6) [symbolp (foo\+bar), symbolp (\1729)];
 240 (%o6)                     [true, true]
 241 @end group
 242 @group
 243 (%i7) [is (foo\+bar = foo+bar), is (\1729 = 1729)];
 244 (%o7)                    [false, false]
 245 @end group
 246 @group
 247 (%i8) baz\~quux;
 248 (%o8)                       baz~quux
 249 @end group
 250 @group
 251 (%i9) declare ("~", alphabetic);
 252 (%o9)                         done
 253 @end group
 254 @group
 255 (%i10) baz~quux;
 256 (%o10)                      baz~quux
 257 @end group
 258 @group
 259 (%i11) [is (foo = FOO), is (FOO = Foo), is (Foo = foo)];
 260 (%o11)                [false, false, false]
 261 @end group
 262 @group
 263 (%i12) :lisp (defvar *my-lisp-variable* '$foo)
 264 *MY-LISP-VARIABLE*
 265 @end group
 266 @group
 267 (%i12) ?\*my\-lisp\-variable\*;
 268 (%o12)                         foo
 269 @end group
 270 @end example
 271
 272 @opencatbox{Categories:}
 273 @category{Syntax}
 274 @closecatbox
 275
 276 @c -----------------------------------------------------------------------------
 277 @node Inequality, Functions and Variables for Expressions, Identifiers, Expressions
 278 @section Inequality
 279 @c -----------------------------------------------------------------------------
 280
 281 Maxima has the inequality operators @code{<}, @code{<=}, @code{>=}, @code{>},
 282 @code{#}, and @code{notequal}.  @xref{if} for a description of conditional
 283 expressions.
 284
 285 @c -----------------------------------------------------------------------------
 286 @node Functions and Variables for Expressions,  , Inequality, Expressions
 287 @section Functions and Variables for Expressions
 288 @c -----------------------------------------------------------------------------
 289
 290 @c NEEDS WORK, ESPECIALLY EXAMPLES
 291
 292 @c -----------------------------------------------------------------------------
 293 @anchor{alias}
 294 @deffn {Function} alias (@var{new_name_1}, @var{old_name_1}, @dots{}, @var{new_name_n}, @var{old_name_n})
 295
 296 provides an alternate name for a (user or system) function, variable, array,
 297 etc.  Any even number of arguments may be used.
 298
 299 @opencatbox{Categories:}
 300 @category{Declarations and inferences}
 301 @closecatbox
 302 @end deffn
 303
 304 @c -----------------------------------------------------------------------------
 305 @anchor{aliases}
 306 @defvr {System variable} aliases
 307 Default value: @code{[]}
 308
 309 @code{aliases} is the list of atoms which have a user defined alias (set up by
 310 the @mrefcomma{alias} @mrefcomma{ordergreat} @mref{orderless} functions or by
 311 declaring the atom a @mref{noun} with @mrefdot{declare})
 312
 313 @opencatbox{Categories:}
 314 @category{Declarations and inferences}
 315 @category{Global variables}
 316 @closecatbox
 317 @end defvr
 318
 319 @c NEEDS TO BE REWORKED.  NOT CONVINCED THIS SYMBOL NEEDS ITS OWN ITEM
 320 @c (SHOULD BE DESCRIBED IN CONTEXT OF EACH FUNCTION WHICH RECOGNIZES IT)
 321
 322 @c -----------------------------------------------------------------------------
 323 @anchor{allbut}
 324 @defvr {Keyword} allbut
 325
 326 works with the @code{part} commands (i.e.  @mrefcomma{part}@w{}
 327 @mrefcomma{inpart} @mrefcomma{substpart} @mrefcomma{substinpart}@w{}
 328 @mrefcomma{dpart} and @mref{lpart}).
 329 For example,
 330
 331 @c ===beg===
 332 @c expr : e + d + c + b + a;
 333 @c part (expr, [2, 5]);
 334 @c ===end===
 335 @example
 336 @group
 337 (%i1) expr : e + d + c + b + a;
 338 (%o1)                   e + d + c + b + a
 339 @end group
 340 @group
 341 (%i2) part (expr, [2, 5]);
 342 (%o2)                         d + a
 343 @end group
 344 @end example
 345
 346 while
 347
 348 @c ===beg===
 349 @c expr : e + d + c + b + a;
 350 @c part (expr, allbut (2, 5));
 351 @c ===end===
 352 @example
 353 @group
 354 (%i1) expr : e + d + c + b + a;
 355 (%o1)                   e + d + c + b + a
 356 @end group
 357 @group
 358 (%i2) part (expr, allbut (2, 5));
 359 (%o2)                       e + c + b
 360 @end group
 361 @end example
 362
 363 @code{allbut} is also recognized by @mrefdot{kill}
 364
 365 @c ===beg===
 366 @c [aa : 11, bb : 22, cc : 33, dd : 44, ee : 55];
 367 @c kill (allbut (cc, dd));
 368 @c [aa, bb, cc, dd];
 369 @c ===end===
 370 @example
 371 @group
 372 (%i1) [aa : 11, bb : 22, cc : 33, dd : 44, ee : 55];
 373 (%o1)                 [11, 22, 33, 44, 55]
 374 @end group
 375 @group
 376 (%i2) kill (allbut (cc, dd));
 377 (%o0)                         done
 378 @end group
 379 @group
 380 (%i1) [aa, bb, cc, dd];
 381 (%o1)                   [aa, bb, 33, 44]
 382 @end group
 383 @end example
 384
 385 @code{kill(allbut(@var{a_1}, @var{a_2}, ...))} has the effect of
 386 @code{kill(all)} except that it does not kill the symbols @var{a_1}, @var{a_2},
 387 @dots{}
 388 @end defvr
 389
 390 @c -----------------------------------------------------------------------------
 391 @anchor{args}
 392 @deffn {Function} args (@var{expr})
 393
 394 Returns the list of arguments of @code{expr}, which may be any kind of
 395 expression other than an atom.  Only the arguments of the top-level operator
 396 are extracted; subexpressions of @code{expr} appear as elements or
 397 subexpressions of elements of the list of arguments.
 398
 399 The order of the items in the list may depend on the global flag
 400 @mrefdot{inflag}
 401
 402 @code{args (@var{expr})} is equivalent to @code{substpart ("[", @var{expr}, 0)}.
 403 See also @mrefcomma{substpart} @mrefcomma{apply} @mrefcomma{funmake} and @mrefdot{op}
 404
 405 How to convert a matrix to a nested list:
 406
 407 @c ===beg===
 408 @c M:matrix([1,2],[3,4]);
 409 @c args(M);
 410 @c ===end===
 411 @example
 412 @group
 413 (%i1) M:matrix([1,2],[3,4]);
 414                             [ 1  2 ]
 415 (%o1)                       [      ]
 416                             [ 3  4 ]
 417 @end group
 418 @group
 419 (%i2) args(M);
 420 (%o2)                   [[1, 2], [3, 4]]
 421 @end group
 422 @end example
 423
 424 Since maxima internally treats a sum of @code{n} terms as a summation command
 425 with @code{n} arguments args() can extract the list of terms in a sum:
 426
 427 @c ===beg===
 428 @c a+b+c;
 429 @c args(%);
 430 @c ===end===
 431 @example
 432 @group
 433 (%i1) a+b+c;
 434 (%o1)                       c + b + a
 435 @end group
 436 @group
 437 (%i2) args(%);
 438 (%o2)                       [c, b, a]
 439 @end group
 440 @end example
 441
 442
 443
 444 @opencatbox{Categories:}
 445 @category{Expressions}
 446 @closecatbox
 447 @end deffn
 448
 449 @c REPHRASE
 450 @c SPLIT OFF EXAMPLES INTO EXAMPLE SECTION
 451
 452 @c -----------------------------------------------------------------------------
 453 @anchor{atom}
 454 @deffn {Function} atom (@var{expr})
 455
 456 Returns @code{true} if @var{expr} is atomic (i.e. a number, name or string) else
 457 @code{false}.  Thus @code{atom(5)} is @code{true} while @code{atom(a[1])} and
 458 @code{atom(sin(x))} are @code{false} (assuming @code{a[1]} and @code{x} are
 459 unbound).
 460
 461 @opencatbox{Categories:}
 462 @category{Expressions}
 463 @category{Predicate functions}
 464 @closecatbox
 465 @end deffn
 466
 467 @c -----------------------------------------------------------------------------
 468 @anchor{box}
 469 @deffn {Function} box @
 470 @fname{box} (@var{expr}) @
 471 @fname{box} (@var{expr}, @var{a})
 472
 473 Returns @var{expr} enclosed in a box.  The return value is an expression with
 474 @code{box} as the operator and @var{expr} as the argument.  A box is drawn on
 475 the display when @mref{display2d} is @code{true}.
 476
 477 @code{box (@var{expr}, @var{a})} encloses @var{expr} in a box labelled by the
 478 symbol @var{a}.  The label is truncated if it is longer than the width of the
 479 box.
 480
 481 @code{box} evaluates its argument.  However, a boxed expression does not
 482 evaluate to its content, so boxed expressions are effectively excluded from
 483 computations. @mref{rembox} removes the box again.
 484
 485 @mref{boxchar} is the character used to draw the box in @code{box} and in the
 486 @mref{dpart} and @mref{lpart} functions.
 487
 488 See also @mrefcomma{rembox} @mref{dpart} and @mrefdot{lpart}
 489
 490 Examples:
 491
 492 @c ===beg===
 493 @c box (a^2 + b^2);
 494 @c a : 1234;
 495 @c b : c - d;
 496 @c box (a^2 + b^2);
 497 @c box (a^2 + b^2, term_1);
 498 @c 1729 - box (1729);
 499 @c boxchar: "-";
 500 @c box (sin(x) + cos(y));
 501 @c ===end===
 502 @example
 503 @group
 504 (%i1) box (a^2 + b^2);
 505                             """""""""
 506                             " 2    2"
 507 (%o1)                       "b  + a "
 508                             """""""""
 509 @end group
 510 @group
 511 (%i2) a : 1234;
 512 (%o2)                         1234
 513 @end group
 514 @group
 515 (%i3) b : c - d;
 516 (%o3)                         c - d
 517 @end group
 518 @group
 519 (%i4) box (a^2 + b^2);
 520                       """"""""""""""""""""
 521                       "       2          "
 522 (%o4)                 "(c - d)  + 1522756"
 523                       """"""""""""""""""""
 524 @end group
 525 @group
 526 (%i5) box (a^2 + b^2, term_1);
 527                       term_1""""""""""""""
 528                       "       2          "
 529 (%o5)                 "(c - d)  + 1522756"
 530                       """"""""""""""""""""
 531 @end group
 532 @group
 533 (%i6) 1729 - box (1729);
 534                                  """"""
 535 (%o6)                     1729 - "1729"
 536                                  """"""
 537 @end group
 538 @group
 539 (%i7) boxchar: "-";
 540 (%o7)                           -
 541 @end group
 542 @group
 543 (%i8) box (sin(x) + cos(y));
 544                         -----------------
 545 (%o8)                   -cos(y) + sin(x)-
 546                         -----------------
 547 @end group
 548 @end example
 549
 550 @opencatbox{Categories:}
 551 @category{Expressions}
 552 @closecatbox
 553 @end deffn
 554
 555 @c -----------------------------------------------------------------------------
 556 @anchor{boxchar}
 557 @defvr {Option variable} boxchar
 558 Default value: @code{"}
 559
 560 @code{boxchar} is the character used to draw the box in the @mref{box}@w{}
 561 and in the @mref{dpart} and @mref{lpart} functions.
 562
 563 @code{boxchar} is only used when @code{display2d_unicode} is @code{false}.
 564
 565 All boxes in an expression are drawn with the current value of @code{boxchar};
 566 the drawing character is not stored with the box expression.
 567
 568 @opencatbox{Categories:}
 569 @category{Expressions}
 570 @closecatbox
 571 @end defvr
 572
 573 @c NEEDS CLARIFICATION !!!
 574
 575 @c -----------------------------------------------------------------------------
 576 @anchor{collapse}
 577 @deffn {Function} collapse (@var{expr})
 578
 579 Collapses @var{expr} by causing all of its common (i.e., equal) subexpressions
 580 to share (i.e., use the same cells), thereby saving space.  (@code{collapse} is
 581 a subroutine used by the @mref{optimize} command.)  Thus, calling
 582 @code{collapse} may be useful after loading in a @mref{save} file.  You can
 583 collapse several expressions together by using
 584 @code{collapse ([@var{expr_1}, ..., @var{expr_n}])}.  Similarly, you can
 585 collapse the elements of the array @code{A} by doing
 586 @code{collapse (listarray ('A))}.
 587
 588 @opencatbox{Categories:}
 589 @category{Expressions}
 590 @closecatbox
 591 @end deffn
 592
 593 @c -----------------------------------------------------------------------------
 594 @anchor{copy}
 595 @deffn {Function} copy (@var{e})
 596
 597 Return a copy of the Maxima expression @var{e}.  Although @var{e} can be any
 598 Maxima expression, the copy function is the most useful when @var{e} is either
 599 a list or a matrix; consider:
 600
 601 @c ===beg===
 602 @c m : [1,[2,3]]$
 603 @c mm : m$
 604 @c mm[2][1] : x$
 605 @c m;
 606 @c mm;
 607 @c ===end===
 608 @example
 609 (%i1) m : [1,[2,3]]$
 610 (%i2) mm : m$
 611 (%i3) mm[2][1] : x$
 612 @group
 613 (%i4) m;
 614 (%o4)                      [1, [x, 3]]
 615 @end group
 616 @group
 617 (%i5) mm;
 618 (%o5)                      [1, [x, 3]]
 619 @end group
 620 @end example
 621
 622 Let's try the same experiment, but this time let @var{mm} be a copy of @var{m}
 623
 624 @c ===beg===
 625 @c m : [1,[2,3]]$
 626 @c mm : copy(m)$
 627 @c mm[2][1] : x$
 628 @c m;
 629 @c mm;
 630 @c ===end===
 631 @example
 632 (%i1) m : [1,[2,3]]$
 633 (%i2) mm : copy(m)$
 634 (%i3) mm[2][1] : x$
 635 @group
 636 (%i4) m;
 637 (%o4)                      [1, [2, 3]]
 638 @end group
 639 @group
 640 (%i5) mm;
 641 (%o5)                      [1, [x, 3]]
 642 @end group
 643 @end example
 644
 645 This time, the assignment to @var{mm} does not change the value of @var{m}.
 646
 647 @opencatbox{Categories:}
 648 @category{Expressions}
 649 @closecatbox
 650 @end deffn
 651
 652 @c NEEDS WORK
 653
 654 @c -----------------------------------------------------------------------------
 655 @anchor{disolate}
 656 @deffn {Function} disolate (@var{expr}, @var{x_1}, @dots{}, @var{x_n})
 657
 658 is similar to @mref{isolate}@code{ (@var{expr}, @var{x})} except that it enables the
 659 user to isolate more than one variable simultaneously.  This might be useful,
 660 for example, if one were attempting to change variables in a multiple
 661 integration, and that variable change involved two or more of the integration
 662 variables.  This function is autoloaded from @file{simplification/disol.mac}.
 663 A demo is available by @code{demo("disol")$}.
 664
 665 @opencatbox{Categories:}
 666 @category{Expressions}
 667 @closecatbox
 668 @end deffn
 669
 670 @c -----------------------------------------------------------------------------
 671 @anchor{dispform}
 672 @deffn  {Function} dispform @
 673 @fname{dispform} (@var{expr}) @
 674 @fname{dispform} (@var{expr}, all)
 675
 676 Returns the external representation of @var{expr}.
 677
 678 @code{dispform(@var{expr})} returns the external representation with respect to
 679 the main (top-level) operator.  @code{dispform(@var{expr}, all)} returns the
 680 external representation with respect to all operators in @var{expr}.
 681
 682 See also @mrefcomma{part} @mrefcomma{inpart} and @mrefdot{inflag}
 683
 684 Examples:
 685
 686 The internal representation of @code{- x} is "negative one times @code{x}"
 687 while the external representation is "minus @code{x}".
 688
 689 @c ===beg===
 690 @c - x;
 691 @c ?format (true, "~S~%", %);
 692 @c dispform (- x);
 693 @c ?format (true, "~S~%", %);
 694 @c ===end===
 695 @example
 696 @group
 697 (%i1) - x;
 698 (%o1)                          - x
 699 @end group
 700 @group
 701 (%i2) ?format (true, "~S~%", %);
 702 ((MTIMES SIMP) -1 $X)
 703 (%o2)                         false
 704 @end group
 705 @group
 706 (%i3) dispform (- x);
 707 (%o3)                          - x
 708 @end group
 709 @group
 710 (%i4) ?format (true, "~S~%", %);
 711 ((MMINUS SIMP) $X)
 712 (%o4)                         false
 713 @end group
 714 @end example
 715
 716 The internal representation of @code{sqrt(x)} is "@code{x} to the power 1/2"
 717 while the external representation is "square root of @code{x}".
 718
 719 @c ===beg===
 720 @c sqrt (x);
 721 @c ?format (true, "~S~%", %);
 722 @c dispform (sqrt (x));
 723 @c ?format (true, "~S~%", %);
 724 @c ===end===
 725 @example
 726 @group
 727 (%i1) sqrt (x);
 728 (%o1)                        sqrt(x)
 729 @end group
 730 @group
 731 (%i2) ?format (true, "~S~%", %);
 732 ((MEXPT SIMP) $X ((RAT SIMP) 1 2))
 733 (%o2)                         false
 734 @end group
 735 @group
 736 (%i3) dispform (sqrt (x));
 737 (%o3)                        sqrt(x)
 738 @end group
 739 @group
 740 (%i4) ?format (true, "~S~%", %);
 741 ((%SQRT SIMP) $X)
 742 (%o4)                         false
 743 @end group
 744 @end example
 745
 746 Use of the optional argument @code{all}.
 747
 748 @c ===beg===
 749 @c expr : sin (sqrt (x));
 750 @c freeof (sqrt, expr);
 751 @c freeof (sqrt, dispform (expr));
 752 @c freeof (sqrt, dispform (expr, all));
 753 @c ===end===
 754 @example
 755 @group
 756 (%i1) expr : sin (sqrt (x));
 757 (%o1)                     sin(sqrt(x))
 758 @end group
 759 @group
 760 (%i2) freeof (sqrt, expr);
 761 (%o2)                         true
 762 @end group
 763 @group
 764 (%i3) freeof (sqrt, dispform (expr));
 765 (%o3)                         true
 766 @end group
 767 @group
 768 (%i4) freeof (sqrt, dispform (expr, all));
 769 (%o4)                         false
 770 @end group
 771 @end example
 772
 773 @opencatbox{Categories:}
 774 @category{Expressions}
 775 @closecatbox
 776 @end deffn
 777
 778 @c NEEDS WORK
 779
 780 @c -----------------------------------------------------------------------------
 781 @anchor{dpart}
 782 @deffn {Function} dpart (@var{expr}, @var{n_1}, @dots{}, @var{n_k})
 783
 784 Selects the same subexpression as @mrefcomma{part} but instead of just returning
 785 that subexpression as its value, it returns the whole expression with the
 786 selected subexpression displayed inside a box.  The box is actually part of the
 787 expression.
 788
 789 @c ===beg===
 790 @c dpart (x+y/z^2, 1, 2, 1);
 791 @c ===end===
 792 @example
 793 (%i1) dpart (x+y/z^2, 1, 2, 1);
 794                              y
 795 (%o1)                       ---- + x
 796                                2
 797                             """
 798                             "z"
 799                             """
 800 @end example
 801
 802 @opencatbox{Categories:}
 803 @category{Expressions}
 804 @closecatbox
 805 @end deffn
 806
 807 @c -----------------------------------------------------------------------------
 808 @anchor{exptisolate}
 809 @defvr {Option variable} exptisolate
 810 Default value: @code{false}
 811
 812 @c WHAT DOES THIS MEAN EXACTLY ??
 813 @code{exptisolate}, when @code{true}, causes @code{isolate (expr, var)} to
 814 examine exponents of atoms (such as @code{%e}) which contain @code{var}.
 815
 816 @c NEED EXAMPLES HERE
 817 @opencatbox{Categories:}
 818 @category{Expressions}
 819 @closecatbox
 820 @end defvr
 821
 822 @c -----------------------------------------------------------------------------
 823 @anchor{exptsubst}
 824 @defvr {Option variable} exptsubst
 825 Default value: @code{false}
 826
 827 @code{exptsubst}, when @code{true}, permits substitutions such as @code{y}
 828 for @code{%e^x} in @code{%e^(a x)}.
 829
 830 @c ===beg===
 831 @c %e^(a*x);
 832 @c exptsubst;
 833 @c subst(y, %e^x, %e^(a*x));
 834 @c exptsubst: not exptsubst;
 835 @c subst(y, %e^x, %e^(a*x));
 836 @c ===end===
 837 @example
 838 @group
 839 (%i1) %e^(a*x);
 840                                 a x
 841 (%o1)                         %e
 842 @end group
 843 @group
 844 (%i2) exptsubst;
 845 (%o2)                         false
 846 @end group
 847 @group
 848 (%i3) subst(y, %e^x, %e^(a*x));
 849                                 a x
 850 (%o3)                         %e
 851 @end group
 852 @group
 853 (%i4) exptsubst: not exptsubst;
 854 (%o4)                         true
 855 @end group
 856 @group
 857 (%i5) subst(y, %e^x, %e^(a*x));
 858                                 a
 859 (%o5)                          y
 860 @end group
 861 @end example
 862
 863 @opencatbox{Categories:}
 864 @category{Exponential and logarithm functions}
 865 @category{Expressions}
 866 @closecatbox
 867 @end defvr
 868
 869 @c -----------------------------------------------------------------------------
 870 @anchor{freeof}
 871 @deffn {Function} freeof (@var{x_1}, @dots{}, @var{x_n}, @var{expr})
 872
 873 @code{freeof (@var{x_1}, @var{expr})} returns @code{true} if no subexpression of
 874 @var{expr} is equal to @var{x_1} or if @var{x_1} occurs only as a dummy variable
 875 in @var{expr}, or if @var{x_1} is neither the noun nor verb form of any operator
 876 in @var{expr}, and returns @code{false} otherwise.
 877
 878 @code{freeof (@var{x_1}, ..., @var{x_n}, @var{expr})} is equivalent to
 879 @code{freeof (@var{x_1}, @var{expr}) and ... and freeof (@var{x_n},
 880 @var{expr})}.
 881
 882 The arguments @var{x_1}, @dots{}, @var{x_n} may be names of functions and
 883 variables, subscripted names, operators (enclosed in double quotes), or general
 884 expressions.  @code{freeof} evaluates its arguments.
 885
 886 @code{freeof} operates only on @var{expr} as it stands (after simplification and
 887 evaluation) and does not attempt to determine if some equivalent expression
 888 would give a different result.  In particular, simplification may yield an
 889 equivalent but different expression which comprises some different elements than
 890 the original form of @var{expr}.
 891
 892 A variable is a dummy variable in an expression if it has no binding outside of
 893 the expression.  Dummy variables recognized by @code{freeof} are the index of a
 894 sum or product, the limit variable in @mrefcomma{limit} the integration variable
 895 in the definite integral form of @mref{integrate}, the original variable in
 896 @mrefcomma{laplace} formal variables in @mref{at} expressions, and arguments in
 897 @mref{lambda} expressions.
 898
 899 The indefinite form of @code{integrate} is @i{not} free of its variable of
 900 integration.
 901
 902 Examples:
 903
 904 Arguments are names of functions, variables, subscripted names, operators, and
 905 expressions.  @code{freeof (a, b, expr)} is equivalent to
 906 @code{freeof (a, expr) and freeof (b, expr)}.
 907
 908 @c ===beg===
 909 @c expr: z^3 * cos (a[1]) * b^(c+d);
 910 @c freeof (z, expr);
 911 @c freeof (cos, expr);
 912 @c freeof (a[1], expr);
 913 @c freeof (cos (a[1]), expr);
 914 @c freeof (b^(c+d), expr);
 915 @c freeof ("^", expr);
 916 @c freeof (w, sin, a[2], sin (a[2]), b*(c+d), expr);
 917 @c ===end===
 918 @example
 919 (%i1) expr: z^3 * cos (a[1]) * b^(c+d);
 920                                  d + c  3
 921 (%o1)                   cos(a ) b      z
 922                              1
 923 (%i2) freeof (z, expr);
 924 (%o2)                         false
 925 (%i3) freeof (cos, expr);
 926 (%o3)                         false
 927 (%i4) freeof (a[1], expr);
 928 (%o4)                         false
 929 (%i5) freeof (cos (a[1]), expr);
 930 (%o5)                         false
 931 (%i6) freeof (b^(c+d), expr);
 932 (%o6)                         false
 933 (%i7) freeof ("^", expr);
 934 (%o7)                         false
 935 (%i8) freeof (w, sin, a[2], sin (a[2]), b*(c+d), expr);
 936 (%o8)                         true
 937 @end example
 938
 939 @code{freeof} evaluates its arguments.
 940
 941 @c ===beg===
 942 @c expr: (a+b)^5$
 943 @c c: a$
 944 @c freeof (c, expr);
 945 @c ===end===
 946 @example
 947 (%i1) expr: (a+b)^5$
 948 (%i2) c: a$
 949 (%i3) freeof (c, expr);
 950 (%o3)                         false
 951 @end example
 952
 953 @code{freeof} does not consider equivalent expressions.
 954 Simplification may yield an equivalent but different expression.
 955
 956 @c ===beg===
 957 @c expr: (a+b)^5$
 958 @c expand (expr);
 959 @c freeof (a+b, %);
 960 @c freeof (a+b, expr);
 961 @c exp (x);
 962 @c freeof (exp, exp (x));
 963 @c ===end===
 964 @example
 965 (%i1) expr: (a+b)^5$
 966 (%i2) expand (expr);
 967           5        4       2  3       3  2      4      5
 968 (%o2)    b  + 5 a b  + 10 a  b  + 10 a  b  + 5 a  b + a
 969 (%i3) freeof (a+b, %);
 970 (%o3)                         true
 971 (%i4) freeof (a+b, expr);
 972 (%o4)                         false
 973 (%i5) exp (x);
 974                                  x
 975 (%o5)                          %e
 976 (%i6) freeof (exp, exp (x));
 977 (%o6)                         true
 978 @end example
 979
 980 A summation or definite integral is free of its dummy variable.
 981 An indefinite integral is not free of its variable of integration.
 982
 983 @c ===beg===
 984 @c freeof (i, 'sum (f(i), i, 0, n));
 985 @c freeof (x, 'integrate (x^2, x, 0, 1));
 986 @c freeof (x, 'integrate (x^2, x));
 987 @c ===end===
 988 @example
 989 (%i1) freeof (i, 'sum (f(i), i, 0, n));
 990 (%o1)                         true
 991 (%i2) freeof (x, 'integrate (x^2, x, 0, 1));
 992 (%o2)                         true
 993 (%i3) freeof (x, 'integrate (x^2, x));
 994 (%o3)                         false
 995 @end example
 996
 997 @opencatbox{Categories:}
 998 @category{Expressions}
 999 @closecatbox
1000 @end deffn
1001
1002 @c -----------------------------------------------------------------------------
1003 @anchor{inflag}
1004 @defvr {Option variable} inflag
1005 Default value: @code{false}
1006
1007 When @code{inflag} is @code{true}, functions for part extraction inspect the
1008 internal form of @code{expr}.
1009
1010 Note that the simplifier re-orders expressions.  Thus @code{first (x + y)}
1011 returns @code{x} if @code{inflag} is @code{true} and @code{y} if @code{inflag}
1012 is @code{false}.  (@code{first (y + x)} gives the same results.)
1013
1014 Also, setting @code{inflag} to @code{true} and calling @mref{part} or
1015 @mref{substpart} is the same as calling @mref{inpart} or @mrefdot{substinpart}
1016
1017 Functions affected by the setting of @code{inflag} are: @mrefcomma{part}@w{}
1018 @mrefcomma{substpart} @mrefcomma{first} @mrefcomma{rest} @mrefcomma{last}@w{}
1019 @mrefcomma{length} the @mref{for} @dots{} @code{in} construct,
1020 @mrefcomma{map} @mrefcomma{fullmap} @mrefcomma{maplist} @mref{reveal} and
1021 @mrefdot{pickapart}
1022
1023 @c NEED EXAMPLES HERE
1024 @opencatbox{Categories:}
1025 @category{Expressions}
1026 @closecatbox
1027 @end defvr
1028
1029 @c NEEDS WORK
1030
1031 @c -----------------------------------------------------------------------------
1032 @anchor{inpart}
1033 @deffn {Function} inpart (@var{expr}, @var{n_1}, @dots{}, @var{n_k})
1034
1035 is similar to @mref{part} but works on the internal representation of the
1036 expression rather than the displayed form and thus may be faster since no
1037 formatting is done.  Care should be taken with respect to the order of
1038 subexpressions in sums and products (since the order of variables in the
1039 internal form is often different from that in the displayed form) and in dealing
1040 with unary minus, subtraction, and division (since these operators are removed
1041 from the expression).  @code{part (x+y, 0)} or @code{inpart (x+y, 0)} yield
1042 @code{+}, though in order to refer to the operator it must be enclosed in "s.
1043 For example @code{... if inpart (%o9,0) = "+" then ...}.
1044
1045 Examples:
1046
1047 @c ===beg===
1048 @c x + y + w*z;
1049 @c inpart (%, 3, 2);
1050 @c part (%th (2), 1, 2);
1051 @c 'limit (f(x)^g(x+1), x, 0, minus);
1052 @c inpart (%, 1, 2);
1053 @c ===end===
1054 @example
1055 (%i1) x + y + w*z;
1056 (%o1)                      w z + y + x
1057 (%i2) inpart (%, 3, 2);
1058 (%o2)                           z
1059 (%i3) part (%th (2), 1, 2);
1060 (%o3)                           z
1061 (%i4) 'limit (f(x)^g(x+1), x, 0, minus);
1062                                   g(x + 1)
1063 (%o4)                 limit   f(x)
1064                       x -> 0-
1065 (%i5) inpart (%, 1, 2);
1066 (%o5)                       g(x + 1)
1067 @end example
1068
1069 @opencatbox{Categories:}
1070 @category{Expressions}
1071 @closecatbox
1072 @end deffn
1073
1074 @c NEEDS WORK
1075
1076 @c -----------------------------------------------------------------------------
1077 @anchor{isolate}
1078 @deffn {Function} isolate (@var{expr}, @var{x})
1079
1080 Returns @var{expr} with subexpressions which are sums and which do not contain
1081 @var{var} replaced by intermediate expression labels (these being atomic symbols
1082 like @code{%t1}, @code{%t2}, @dots{}).  This is often useful to avoid
1083 unnecessary expansion of subexpressions which don't contain the variable of
1084 interest.  Since the intermediate labels are bound to the subexpressions they
1085 can all be substituted back by evaluating the expression in which they occur.
1086
1087 @mref{exptisolate} (default value: @code{false}) if @code{true} will cause
1088 @code{isolate} to examine exponents of atoms (like @code{%e}) which contain
1089 @var{var}.
1090
1091 @code{isolate_wrt_times} if @code{true}, then @code{isolate} will also isolate
1092 with respect to products.  See @mrefdot{isolate_wrt_times} See also @mrefdot{disolate}
1093
1094
1095 Do @code{example (isolate)} for examples.
1096
1097 @opencatbox{Categories:}
1098 @category{Expressions}
1099 @closecatbox
1100 @end deffn
1101
1102 @c NEEDS WORK
1103
1104 @c -----------------------------------------------------------------------------
1105 @anchor{isolate_wrt_times}
1106 @defvr {Option variable} isolate_wrt_times
1107 Default value: @code{false}
1108
1109 When @code{isolate_wrt_times} is @code{true}, @code{isolate} will also isolate
1110 with respect to products.  E.g. compare both settings of the switch on
1111
1112 @example
1113 (%i1) isolate_wrt_times: true$
1114 (%i2) isolate (expand ((a+b+c)^2), c);
1115
1116 (%t2)                          2 a
1117
1118
1119 (%t3)                          2 b
1120
1121                           2            2
1122 (%t4)                    b  + 2 a b + a
1123
1124                      2
1125 (%o4)               c  + %t3 c + %t2 c + %t4
1126 (%i4) isolate_wrt_times: false$
1127 (%i5) isolate (expand ((a+b+c)^2), c);
1128                      2
1129 (%o5)               c  + 2 b c + 2 a c + %t4
1130 @end example
1131
1132 @opencatbox{Categories:}
1133 @category{Expressions}
1134 @closecatbox
1135 @end defvr
1136
1137 @c NEEDS EXAMPLES
1138
1139 @c -----------------------------------------------------------------------------
1140 @anchor{listconstvars}
1141 @defvr {Option variable} listconstvars
1142 Default value: @code{false}
1143
1144 When @code{listconstvars} is @code{true} the list returned by
1145 @code{listofvars} contains constant variables, such as @code{%e},
1146 @code{%pi}, @code{%i} or any variables declared as constant that
1147 occur in @var{expr}. A variable is declared as @code{constant}
1148 type via @mref{declare}, and @mref{constantp} returns @code{true}
1149 for all variables declared as @code{constant}. The default is to
1150 omit constant variables from @code{listofvars} return value.
1151
1152 @opencatbox{Categories:}
1153 @category{Expressions}
1154 @closecatbox
1155 @end defvr
1156
1157 @c -----------------------------------------------------------------------------
1158 @anchor{listdummyvars}
1159 @defvr {Option variable} listdummyvars
1160 Default value: @code{true}
1161
1162 When @code{listdummyvars} is @code{false}, "dummy variables" in the expression
1163 will not be included in the list returned by @mrefdot{listofvars}  (The meaning
1164 of "dummy variables" is as given in @mrefdot{freeof}  "Dummy variables" are
1165 mathematical things like the index of a sum or product, the limit variable,
1166 and the definite integration variable.)
1167
1168 Example:
1169
1170 @c ===beg===
1171 @c listdummyvars: true$
1172 @c listofvars ('sum(f(i), i, 0, n));
1173 @c listdummyvars: false$
1174 @c listofvars ('sum(f(i), i, 0, n));
1175 @c ===end===
1176 @example
1177 (%i1) listdummyvars: true$
1178 (%i2) listofvars ('sum(f(i), i, 0, n));
1179 (%o2)                        [i, n]
1180 (%i3) listdummyvars: false$
1181 (%i4) listofvars ('sum(f(i), i, 0, n));
1182 (%o4)                          [n]
1183 @end example
1184
1185 @opencatbox{Categories:}
1186 @category{Expressions}
1187 @closecatbox
1188 @end defvr
1189
1190 @c NEEDS WORK
1191
1192 @c -----------------------------------------------------------------------------
1193 @anchor{listofvars}
1194 @deffn {Function} listofvars (@var{expr})
1195
1196 Returns a list of the variables in @var{expr}.
1197
1198 @mref{listconstvars} if @code{true} causes @code{listofvars} to include
1199 @code{%e}, @code{%pi}, @code{%i}, and any variables declared constant in the
1200 list it returns if they appear in @var{expr}.  The default is to omit these.
1201
1202 See also the option variable @mref{listdummyvars} to exclude or include
1203 "dummy variables" in the list of variables.
1204
1205 @c ===beg===
1206 @c listofvars (f (x[1]+y) / g^(2+a));
1207 @c ===end===
1208 @example
1209 (%i1) listofvars (f (x[1]+y) / g^(2+a));
1210 (%o1)                     [g, a, x , y]
1211                                   1
1212 @end example
1213
1214 @opencatbox{Categories:}
1215 @category{Expressions}
1216 @closecatbox
1217 @end deffn
1218
1219 @c NEEDS WORK
1220
1221 @c -----------------------------------------------------------------------------
1222 @anchor{lfreeof}
1223 @deffn {Function} lfreeof (@var{list}, @var{expr})
1224
1225 For each member @var{m} of @var{list}, calls
1226 @code{freeof (@var{m}, @var{expr})}.  It returns @code{false} if any call to
1227 @mref{freeof} does and @code{true} otherwise.
1228
1229 Example:
1230
1231 @c ===beg===
1232 @c lfreeof ([ a, x], x^2+b);
1233 @c lfreeof ([ b, x], x^2+b);
1234 @c lfreeof ([ a, y], x^2+b);
1235 @c ===end===
1236 @example
1237 @group
1238 (%i1) lfreeof ([ a, x], x^2+b);
1239 (%o1)                         false
1240 @end group
1241 @group
1242 (%i2) lfreeof ([ b, x], x^2+b);
1243 (%o2)                         false
1244 @end group
1245 @group
1246 (%i3) lfreeof ([ a, y], x^2+b);
1247 (%o3)                         true
1248 @end group
1249 @end example
1250
1251 @opencatbox{Categories:}
1252 @category{Expressions}
1253 @closecatbox
1254 @end deffn
1255
1256 @c NEEDS WORK
1257
1258 @c -----------------------------------------------------------------------------
1259 @anchor{lpart}
1260 @deffn {Function} lpart (@var{label}, @var{expr}, @var{n_1}, @dots{}, @var{n_k})
1261
1262 is similar to @mref{dpart} but uses a labelled box.  A labelled box is similar
1263 to the one produced by @code{dpart} but it has a name in the top line.
1264
1265 @opencatbox{Categories:}
1266 @category{Expressions}
1267 @closecatbox
1268 @end deffn
1269
1270 @c NEEDS CLARIFICATION, EXAMPLES
1271
1272 @c -----------------------------------------------------------------------------
1273 @anchor{mainvar}
1274 @defvr {Property} mainvar
1275
1276 You may declare variables to be @code{mainvar}.  The ordering scale for atoms is
1277 essentially: numbers @code{<} constants (e.g., @code{%e}, @code{%pi}) @code{<} scalars @code{<} other
1278 variables @code{<} mainvars.  E.g., compare @code{expand ((X+Y)^4)} with
1279 @code{(declare (x, mainvar), expand ((x+y)^4))}.  (Note: Care should be taken if
1280 you elect to use the above feature.  E.g., if you subtract an expression in
1281 which @code{x} is a @code{mainvar} from one in which @code{x} isn't a
1282 @code{mainvar}, resimplification e.g. with @code{ev (expr, simp)} may be
1283 necessary if cancellation is to occur.  Also, if you save an expression in which
1284 @code{x} is a @code{mainvar}, you probably should also save @code{x}.)
1285
1286 @opencatbox{Categories:}
1287 @category{Declarations and inferences}
1288 @category{Expressions}
1289 @closecatbox
1290 @end defvr
1291
1292 @c NEEDS CLARIFICATION, EXAMPLES
1293
1294 @c -----------------------------------------------------------------------------
1295 @anchor{noun}
1296 @defvr {Property} noun
1297
1298 @code{noun} is one of the options of the @mref{declare} command.  It makes a
1299 function so declared a "noun", meaning that it won't be evaluated
1300 automatically.
1301
1302 Example:
1303
1304 @c ===beg===
1305 @c factor (12345678);
1306 @c declare (factor, noun);
1307 @c factor (12345678);
1308 @c ''%, nouns;
1309 @c ===end===
1310 @example
1311 @group
1312 (%i1) factor (12345678);
1313                              2
1314 (%o1)                     2 3  47 14593
1315 @end group
1316 @group
1317 (%i2) declare (factor, noun);
1318 (%o2)                         done
1319 @end group
1320 @group
1321 (%i3) factor (12345678);
1322 (%o3)                   factor(12345678)
1323 @end group
1324 @group
1325 (%i4) ''%, nouns;
1326                              2
1327 (%o4)                     2 3  47 14593
1328 @end group
1329 @end example
1330
1331 @opencatbox{Categories:}
1332 @category{Nouns and verbs}
1333 @closecatbox
1334 @end defvr
1335
1336 @c NEEDS CLARIFICATION, EXAMPLES
1337
1338 @c -----------------------------------------------------------------------------
1339 @anchor{noundisp}
1340 @defvr {Option variable} noundisp
1341 Default value: @code{false}
1342
1343 When @code{noundisp} is @code{true}, nouns display with
1344 a single quote.  This switch is always @code{true} when displaying function
1345 definitions.
1346
1347 @opencatbox{Categories:}
1348 @category{Display flags and variables}
1349 @category{Nouns and verbs}
1350 @closecatbox
1351 @end defvr
1352
1353 @c NEEDS WORK
1354
1355 @c -----------------------------------------------------------------------------
1356 @anchor{nounify}
1357 @deffn {Function} nounify (@var{f})
1358
1359 Returns the noun form of the function name @var{f}.  This is
1360 needed if one wishes to refer to the name of a verb function as if it
1361 were a noun.  Note that some verb functions will return their noun
1362 forms if they can't be evaluated for certain arguments.  This is also
1363 the form returned if a function call is preceded by a quote.
1364
1365 See also @mrefdot{verbify}
1366
1367 @opencatbox{Categories:}
1368 @category{Nouns and verbs}
1369 @closecatbox
1370 @end deffn
1371
1372 @c NEEDS WORK
1373
1374 @c -----------------------------------------------------------------------------
1375 @anchor{nterms}
1376 @deffn {Function} nterms (@var{expr})
1377
1378 Returns the number of terms that @var{expr} would have if it were fully
1379 expanded out and no cancellations or combination of terms occurred.
1380 Note that expressions like @code{sin (@var{expr})}, @code{sqrt (@var{expr})},
1381 @code{exp (@var{expr})}, etc. count as just one term regardless of how many
1382 terms @var{expr} has (if it is a sum).
1383
1384 @opencatbox{Categories:}
1385 @category{Expressions}
1386 @closecatbox
1387 @end deffn
1388
1389 @c NEEDS WORK
1390
1391 @c -----------------------------------------------------------------------------
1392 @anchor{op}
1393 @deffn {Function} op (@var{expr})
1394
1395 Returns the main operator of the expression @var{expr}.
1396 This is equivalent to @code{part (@var{expr}, 0)} with @code{partswitch} set
1397 to @code{false}.
1398
1399 @code{op} returns a string if the main operator is a built-in or user-defined
1400 prefix, binary or n-ary infix, postfix, matchfix, or nofix operator.
1401 Otherwise, if @var{expr} is a subscripted function expression, @code{op}
1402 returns the subscripted function; in this case the return value is not an atom.
1403 Otherwise, @var{expr} is a @mref{memoizing function} or ordinary function expression,
1404 and @code{op} returns a symbol.
1405
1406 @code{op} observes the value of the global flag @mrefdot{inflag}
1407
1408 @code{op} evaluates it argument.
1409
1410 See also @mrefdot{args}
1411
1412 Examples:
1413
1414 @c ===beg===
1415 @c stringdisp: true$
1416 @c op (a * b * c);
1417 @c op (a * b + c);
1418 @c op ('sin (a + b));
1419 @c op (a!);
1420 @c op (-a);
1421 @c op ([a, b, c]);
1422 @c op ('(if a > b then c else d));
1423 @c op ('foo (a));
1424 @c prefix (foo);
1425 @c op (foo a);
1426 @c op (F [x, y] (a, b, c));
1427 @c op (G [u, v, w]);
1428 @c ===end===
1429 @example
1430 (%i1) stringdisp: true$
1431 @group
1432 (%i2) op (a * b * c);
1433 (%o2)                          "*"
1434 @end group
1435 @group
1436 (%i3) op (a * b + c);
1437 (%o3)                          "+"
1438 @end group
1439 @group
1440 (%i4) op ('sin (a + b));
1441 (%o4)                          sin
1442 @end group
1443 @group
1444 (%i5) op (a!);
1445 (%o5)                          "!"
1446 @end group
1447 @group
1448 (%i6) op (-a);
1449 (%o6)                          "-"
1450 @end group
1451 @group
1452 (%i7) op ([a, b, c]);
1453 (%o7)                          "["
1454 @end group
1455 @group
1456 (%i8) op ('(if a > b then c else d));
1457 (%o8)                         "if"
1458 @end group
1459 @group
1460 (%i9) op ('foo (a));
1461 (%o9)                          foo
1462 @end group
1463 @group
1464 (%i10) prefix (foo);
1465 (%o10)                        "foo"
1466 @end group
1467 @group
1468 (%i11) op (foo a);
1469 (%o11)                        "foo"
1470 @end group
1471 @group
1472 (%i12) op (F [x, y] (a, b, c));
1473 (%o12)                        F
1474                                x, y
1475 @end group
1476 @group
1477 (%i13) op (G [u, v, w]);
1478 (%o13)                          G
1479 @end group
1480 @end example
1481
1482 @opencatbox{Categories:}
1483 @category{Expressions}
1484 @category{Operators}
1485 @closecatbox
1486 @end deffn
1487
1488 @c NEEDS WORK
1489
1490 @c -----------------------------------------------------------------------------
1491 @anchor{operatorp}
1492 @deffn  {Function} operatorp @
1493 @fname{operatorp} (@var{expr}, @var{op}) @
1494 @fname{operatorp} (@var{expr}, [@var{op_1}, @dots{}, @var{op_n}])
1495
1496 @code{operatorp (@var{expr}, @var{op})} returns @code{true}
1497 if @var{op} is equal to the operator of @var{expr}.
1498
1499 @code{operatorp (@var{expr}, [@var{op_1}, ..., @var{op_n}])} returns
1500 @code{true} if some element @var{op_1}, @dots{}, @var{op_n} is equal to the
1501 operator of @var{expr}.
1502
1503 @code{operatorp} observes the value of the global flag @mrefdot{inflag}
1504
1505 @opencatbox{Categories:}
1506 @category{Operators}
1507 @category{Predicate functions}
1508 @closecatbox
1509 @end deffn
1510
1511 @c NEEDS CLARIFICATION, EXAMPLES
1512
1513 @c -----------------------------------------------------------------------------
1514 @anchor{option_opsubst}
1515 @defvr {Option variable} opsubst
1516 Default value: @code{true}
1517
1518 When @code{opsubst} is @code{false}, @mref{subst} does not attempt to
1519 substitute into the operator of an expression.  E.g.,
1520 @code{(opsubst: false, subst (x^2, r, r+r[0]))} will work.
1521
1522 @c ===beg===
1523 @c r+r[0];
1524 @c opsubst;
1525 @c subst (x^2, r, r+r[0]);
1526 @c opsubst: not opsubst;
1527 @c subst (x^2, r, r+r[0]);
1528 @c ===end===
1529 @example
1530 @group
1531 (%i1) r+r[0];
1532 (%o1)                        r + r
1533                                   0
1534 @end group
1535 @group
1536 (%i2) opsubst;
1537 (%o2)                         true
1538 @end group
1539 @group
1540 (%i3) subst (x^2, r, r+r[0]);
1541                             2     2
1542 (%o3)                      x  + (x )
1543                                     0
1544 @end group
1545 @group
1546 (%i4) opsubst: not opsubst;
1547 (%o4)                         false
1548 @end group
1549 @group
1550 (%i5) subst (x^2, r, r+r[0]);
1551                               2
1552 (%o5)                        x  + r
1553                                    0
1554 @end group
1555 @end example
1556
1557 @opencatbox{Categories:}
1558 @category{Expressions}
1559 @closecatbox
1560 @end defvr
1561
1562 @c NEEDS WORK
1563
1564 @c -----------------------------------------------------------------------------
1565 @anchor{optimize}
1566 @deffn {Function} optimize (@var{expr})
1567
1568 Returns an expression that produces the same value and
1569 side effects as @var{expr} but does so more efficiently by avoiding the
1570 recomputation of common subexpressions.  @code{optimize} also has the side
1571 effect of "collapsing" its argument so that all common subexpressions
1572 are shared.  Do @code{example (optimize)} for examples.
1573
1574 @opencatbox{Categories:}
1575 @category{Expressions}
1576 @closecatbox
1577 @end deffn
1578
1579
1580 @c -----------------------------------------------------------------------------
1581 @anchor{optimprefix}
1582 @defvr {Option variable} optimprefix
1583 Default value: @code{%}
1584
1585 @code{optimprefix} is the prefix used for generated symbols by
1586 the @mref{optimize} command.
1587
1588 @opencatbox{Categories:}
1589 @category{Expressions}
1590 @closecatbox
1591 @end defvr
1592
1593 @c -----------------------------------------------------------------------------
1594 @anchor{ordergreat}
1595 @anchor{orderless}
1596 @deffn  {Function} ordergreat (@var{v_1}, @dots{}, @var{v_n})
1597 @deffnx {Function} orderless (@var{v_1}, @dots{}, @var{v_n})
1598
1599 @code{ordergreat} changes the canonical ordering of Maxima expressions
1600 such that @var{v_1} succeeds @var{v_2} succeeds @dots{}  succeeds @var{v_n},
1601 and @var{v_n} succeeds any other symbol not mentioned as an argument.
1602
1603 @code{orderless} changes the canonical ordering of Maxima expressions
1604 such that @var{v_1} precedes @var{v_2} precedes @dots{} precedes @var{v_n},
1605 and @var{v_n} precedes any other variable not mentioned as an argument.
1606
1607 The order established by @code{ordergreat} and @code{orderless} is dissolved
1608 by @mrefdot{unorder}  @code{ordergreat} and @code{orderless} can be called only
1609 once each, unless @code{unorder} is called; only the last call to
1610 @code{ordergreat} and @code{orderless} has any effect.
1611
1612 See also @mrefdot{ordergreatp}
1613
1614 @opencatbox{Categories:}
1615 @category{Expressions}
1616 @closecatbox
1617 @end deffn
1618
1619 @c -----------------------------------------------------------------------------
1620 @anchor{ordergreatp}
1621 @anchor{orderlessp}
1622 @deffn  {Function} ordergreatp (@var{expr_1}, @var{expr_2})
1623 @deffnx {Function} orderlessp (@var{expr_1}, @var{expr_2})
1624
1625 @code{ordergreatp} returns @code{true} if @var{expr_1} succeeds @var{expr_2} in
1626 the canonical ordering of Maxima expressions, and @code{false} otherwise.
1627
1628 @code{orderlessp} returns @code{true} if @var{expr_1} precedes @var{expr_2} in
1629 the canonical ordering of Maxima expressions, and @code{false} otherwise.
1630
1631 All Maxima atoms and expressions are comparable under @code{ordergreatp} and
1632 @code{orderlessp}, although there are isolated examples of expressions for which
1633 these predicates are not transitive; that is a bug.
1634
1635 The canonical ordering of atoms (symbols, literal numbers, and strings) is the
1636 following.
1637
1638 (integers and floats) precede (bigfloats) precede
1639 (declared constants) precede (strings) precede (declared scalars)
1640 precede (first argument to @mref{orderless}) precedes @dots{} precedes
1641 (last argument to @code{orderless}) precedes (other symbols) precede
1642 (last argument to @mref{ordergreat}) precedes @dots{} precedes
1643 (first argument to @code{ordergreat}) precedes (declared main variables)
1644
1645 For non-atomic expressions, the canonical ordering is derived from the ordering
1646 for atoms.  For the built-in @code{+} @code{*} and @code{^} operators,
1647 the ordering is not easily summarized.  For other built-in operators and all
1648 other functions and operators, expressions are ordered by their arguments
1649 (beginning with the first argument), then by the name of the operator or
1650 function.  In the case of subscripted expressions, the subscripted symbol is
1651 considered the operator and the subscript is considered an argument.
1652
1653 The canonical ordering of expressions is modified by the functions
1654 @mref{ordergreat} and @mrefcomma{orderless} and the @mrefcomma{mainvar}@w{}
1655 @mrefcomma{constant} and @code{scalar} declarations.
1656
1657 See also @mrefdot{sort}
1658
1659 Examples:
1660
1661 Ordering ordinary symbols and constants.
1662 Note that @code{%pi} is not ordered according to its numerical value.
1663
1664 @c ===beg===
1665 @c stringdisp : true;
1666 @c sort ([%pi, 3b0, 3.0, x, X, "foo", 3, a, 4, "bar", 4.0, 4b0]);
1667 @c ===end===
1668 @example
1669 @group
1670 (%i1) stringdisp : true;
1671 (%o1)                         true
1672 @end group
1673 @group
1674 (%i2) sort ([%pi, 3b0, 3.0, x, X, "foo", 3, a, 4, "bar", 4.0, 4b0]);
1675 (%o2) [3, 3.0, 4, 4.0, 3.0b0, 4.0b0, %pi, "bar", "foo", X, a, x]
1676 @end group
1677 @end example
1678
1679 Effect of @code{ordergreat} and @code{orderless} functions.
1680
1681 @c ===beg===
1682 @c sort ([M, H, K, T, E, W, G, A, P, J, S]);
1683 @c ordergreat (S, J);
1684 @c orderless (M, H);
1685 @c sort ([M, H, K, T, E, W, G, A, P, J, S]);
1686 @c ===end===
1687 @example
1688 @group
1689 (%i1) sort ([M, H, K, T, E, W, G, A, P, J, S]);
1690 (%o1)           [A, E, G, H, J, K, M, P, S, T, W]
1691 @end group
1692 @group
1693 (%i2) ordergreat (S, J);
1694 (%o2)                         done
1695 @end group
1696 @group
1697 (%i3) orderless (M, H);
1698 (%o3)                         done
1699 @end group
1700 @group
1701 (%i4) sort ([M, H, K, T, E, W, G, A, P, J, S]);
1702 (%o4)           [M, H, A, E, G, K, P, T, W, J, S]
1703 @end group
1704 @end example
1705
1706 Effect of @code{mainvar}, @code{constant}, and @code{scalar} declarations.
1707
1708 @c ===beg===
1709 @c sort ([aa, foo, bar, bb, baz, quux, cc, dd, A1, B1, C1]);
1710 @c declare (aa, mainvar);
1711 @c declare ([baz, quux], constant);
1712 @c declare ([A1, B1], scalar);
1713 @c sort ([aa, foo, bar, bb, baz, quux, cc, dd, A1, B1, C1]);
1714 @c ===end===
1715 @example
1716 @group
1717 (%i1) sort ([aa, foo, bar, bb, baz, quux, cc, dd, A1, B1, C1]);
1718 (%o1)   [A1, B1, C1, aa, bar, baz, bb, cc, dd, foo, quux]
1719 @end group
1720 @group
1721 (%i2) declare (aa, mainvar);
1722 (%o2)                         done
1723 @end group
1724 @group
1725 (%i3) declare ([baz, quux], constant);
1726 (%o3)                         done
1727 @end group
1728 @group
1729 (%i4) declare ([A1, B1], scalar);
1730 (%o4)                         done
1731 @end group
1732 @group
1733 (%i5) sort ([aa, foo, bar, bb, baz, quux, cc, dd, A1, B1, C1]);
1734 (%o5)   [baz, quux, A1, B1, C1, bar, bb, cc, dd, foo, aa]
1735 @end group
1736 @end example
1737
1738 Ordering non-atomic expressions.
1739
1740 @c ===beg===
1741 @c sort ([1, 2, n, f(1), f(2), f(2, 1), g(1), g(1, 2), g(n),
1742 @c        f(n, 1)]);
1743 @c sort ([foo(1), X[1], X[k], foo(k), 1, k]);
1744 @c ===end===
1745 @example
1746 @group
1747 (%i1) sort ([1, 2, n, f(1), f(2), f(2, 1), g(1), g(1, 2), g(n),
1748        f(n, 1)]);
1749 (%o1) [1, 2, f(1), g(1), g(1, 2), f(2), f(2, 1), n, g(n),
1750                                                          f(n, 1)]
1751 @end group
1752 @group
1753 (%i2) sort ([foo(1), X[1], X[k], foo(k), 1, k]);
1754 (%o2)            [1, X , foo(1), k, X , foo(k)]
1755                       1              k
1756 @end group
1757 @end example
1758
1759 @opencatbox{Categories:}
1760 @category{Expressions}
1761 @category{Predicate functions}
1762 @closecatbox
1763 @end deffn
1764
1765 @c NEEDS WORK
1766
1767 @c -----------------------------------------------------------------------------
1768 @anchor{part}
1769 @deffn {Function} part (@var{expr}, @var{n_1}, @dots{}, @var{n_k})
1770
1771 Returns parts of the displayed form of @code{expr}.  It obtains the part of
1772 @code{expr} as specified by the indices @var{n_1}, @dots{}, @var{n_k}.  First
1773 part @var{n_1} of @code{expr} is obtained, then part @var{n_2} of that, etc.
1774 The result is part @var{n_k} of @dots{} part @var{n_2} of part @var{n_1} of
1775 @code{expr}.  If no indices are specified @code{expr} is returned.
1776
1777 @code{part} can be used to obtain an element of a list, a row of a matrix, etc.
1778
1779 @c "If the last argument to a part function" => FOLLOWING APPLIES TO OTHER FUNCTIONS ??
1780 @c ATTEMPT TO VERIFY; IF SO, COPY THIS COMMENTARY TO DESCRIPTIONS OF OTHER FUNCTIONS
1781 If the last argument to a @code{part} function is a list of indices then
1782 several subexpressions are picked out, each one corresponding to an
1783 index of the list.  Thus @code{part (x + y + z, [1, 3])} is @code{z+x}.
1784
1785 @mref{piece} holds the last expression selected when using the @code{part}
1786 functions.  It is set during the execution of the function and thus
1787 may be referred to in the function itself as shown below.
1788
1789 If @mref{partswitch} is set to @code{true} then @code{end} is returned when a
1790 selected part of an expression doesn't exist, otherwise an error message is
1791 given.
1792
1793 See also @mrefcomma{inpart} @mrefcomma{substpart} @mrefcomma{substinpart}@w{}
1794 @mrefcomma{dpart} and @mrefdot{lpart}
1795
1796 Examples:
1797
1798 @c ===beg===
1799 @c part(z+2*y+a,2);
1800 @c part(z+2*y+a,[1,3]);
1801 @c part(z+2*y+a,2,1);
1802 @c ===end===
1803 @example
1804 @group
1805 (%i1) part(z+2*y+a,2);
1806 (%o1)                          2 y
1807 @end group
1808 @group
1809 (%i2) part(z+2*y+a,[1,3]);
1810 (%o2)                         z + a
1811 @end group
1812 @group
1813 (%i3) part(z+2*y+a,2,1);
1814 (%o3)                           2
1815 @end group
1816 @end example
1817
1818 @code{example (part)} displays additional examples.
1819
1820 @opencatbox{Categories:}
1821 @category{Expressions}
1822 @closecatbox
1823 @end deffn
1824
1825 @c NEEDS WORK
1826
1827 @c -----------------------------------------------------------------------------
1828 @anchor{partition}
1829 @deffn {Function} partition (@var{expr}, @var{x})
1830
1831 Returns a list of two expressions.  They are (1) the factors of @var{expr}
1832 (if it is a product), the terms of @var{expr} (if it is a sum), or the list
1833 (if it is a list) which don't contain @var{x} and, (2) the factors, terms,
1834 or list which do.
1835
1836 Examples:
1837
1838 @c ===beg===
1839 @c partition (2*a*x*f(x), x);
1840 @c partition (a+b, x);
1841 @c partition ([a, b, f(a), c], a);
1842 @c ===end===
1843 @example
1844 (%i1) partition (2*a*x*f(x), x);
1845 (%o1)                     [2 a, x f(x)]
1846 (%i2) partition (a+b, x);
1847 (%o2)                      [b + a, 0]
1848 (%i3) partition ([a, b, f(a), c], a);
1849 (%o3)                  [[b, c], [a, f(a)]]
1850 @end example
1851
1852 @opencatbox{Categories:}
1853 @category{Expressions}
1854 @closecatbox
1855 @end deffn
1856
1857 @c NEEDS EXAMPLE
1858
1859 @c -----------------------------------------------------------------------------
1860 @anchor{partswitch}
1861 @defvr {Option variable} partswitch
1862 Default value: @code{false}
1863
1864 When @code{partswitch} is @code{true}, @code{end} is returned
1865 when a selected part of an expression doesn't exist, otherwise an
1866 error message is given.
1867
1868 @opencatbox{Categories:}
1869 @category{Expressions}
1870 @closecatbox
1871 @end defvr
1872
1873 @c -----------------------------------------------------------------------------
1874 @anchor{pickapart}
1875 @deffn {Function} pickapart (@var{expr}, @var{n})
1876
1877 Assigns intermediate expression labels to subexpressions of @var{expr} at depth
1878 @var{n}, an integer.  Subexpressions at greater or lesser depths are not
1879 assigned labels.  @code{pickapart} returns an expression in terms of
1880 intermediate expressions equivalent to the original expression @var{expr}.
1881
1882 See also @mrefcomma{part} @mrefcomma{dpart} @mrefcomma{lpart}@w{}
1883 @mrefcomma{inpart} and @mrefdot{reveal}
1884
1885 Examples:
1886
1887 @example
1888 (%i1) expr: (a+b)/2 + sin (x^2)/3 - log (1 + sqrt(x+1));
1889                                           2
1890                                      sin(x )   b + a
1891 (%o1)       - log(sqrt(x + 1) + 1) + ------- + -----
1892                                         3        2
1893 (%i2) pickapart (expr, 0);
1894 @group
1895                                           2
1896                                      sin(x )   b + a
1897 (%t2)       - log(sqrt(x + 1) + 1) + ------- + -----
1898                                         3        2
1899 @end group
1900 (%o2)                          %t2
1901 (%i3) pickapart (expr, 1);
1902
1903 (%t3)                - log(sqrt(x + 1) + 1)
1904
1905
1906                                   2
1907                              sin(x )
1908 (%t4)                        -------
1909                                 3
1910
1911
1912                               b + a
1913 (%t5)                         -----
1914                                 2
1915
1916 (%o5)                    %t5 + %t4 + %t3
1917 (%i5) pickapart (expr, 2);
1918
1919 (%t6)                 log(sqrt(x + 1) + 1)
1920
1921
1922                                   2
1923 (%t7)                        sin(x )
1924
1925
1926 (%t8)                         b + a
1927
1928                          %t8   %t7
1929 (%o8)                    --- + --- - %t6
1930                           2     3
1931 (%i8) pickapart (expr, 3);
1932
1933 (%t9)                    sqrt(x + 1) + 1
1934
1935
1936                                 2
1937 (%t10)                         x
1938
1939                   b + a              sin(%t10)
1940 (%o10)            ----- - log(%t9) + ---------
1941                     2                    3
1942 (%i10) pickapart (expr, 4);
1943
1944 (%t11)                     sqrt(x + 1)
1945 @group
1946                       2
1947                  sin(x )   b + a
1948 (%o11)           ------- + ----- - log(%t11 + 1)
1949                     3        2
1950 @end group
1951 (%i11) pickapart (expr, 5);
1952
1953 (%t12)                        x + 1
1954
1955                    2
1956               sin(x )   b + a
1957 (%o12)        ------- + ----- - log(sqrt(%t12) + 1)
1958                  3        2
1959 (%i12) pickapart (expr, 6);
1960                   2
1961              sin(x )   b + a
1962 (%o12)       ------- + ----- - log(sqrt(x + 1) + 1)
1963                 3        2
1964 @end example
1965
1966 @opencatbox{Categories:}
1967 @category{Expressions}
1968 @closecatbox
1969 @end deffn
1970
1971 @c NEEDS WORK
1972
1973 @c -----------------------------------------------------------------------------
1974 @anchor{piece}
1975 @defvr {System variable} piece
1976
1977 Holds the last expression selected when using the @mref{part} functions.
1978 @c WHAT DOES THIS MEAN EXACTLY ??
1979 It is set during the execution of the function and thus may be referred to in
1980 the function itself.
1981
1982 @c NEED "SEE ALSO" TO POINT TO LIST OF ALL RELEVANT FUNCTIONS
1983
1984 @opencatbox{Categories:}
1985 @category{Expressions}
1986 @closecatbox
1987 @end defvr
1988
1989 @c -----------------------------------------------------------------------------
1990 @anchor{psubst}
1991 @deffn  {Function} psubst @
1992 @fname{psubst} (@var{list}, @var{expr}) @
1993 @fname{psubst} (@var{a}, @var{b}, @var{expr})
1994
1995 @code{psubst(@var{a}, @var{b}, @var{expr})} is similar to @code{subst}.  See
1996 @mrefdot{subst}
1997
1998 In distinction from @code{subst} the function @code{psubst} makes parallel
1999 substitutions, if the first argument @var{list} is a list of equations.
2000
2001 See also @mref{sublis} for making parallel substitutions and @mref{let} and
2002 @mref{letsimp} for others ways to do substitutions.
2003
2004 Example:
2005
2006 The first example shows parallel substitution with @code{psubst}.  The second
2007 example shows the result for the function @code{subst}, which does a serial
2008 substitution.
2009
2010 @c ===beg===
2011 @c psubst ([a^2=b, b=a], sin(a^2) + sin(b));
2012 @c subst ([a^2=b, b=a], sin(a^2) + sin(b));
2013 @c ===end===
2014 @example
2015 @group
2016 (%i1) psubst ([a^2=b, b=a], sin(a^2) + sin(b));
2017 (%o1)                    sin(b) + sin(a)
2018 @end group
2019 @group
2020 (%i2) subst ([a^2=b, b=a], sin(a^2) + sin(b));
2021 (%o2)                       2 sin(a)
2022 @end group
2023 @end example
2024
2025 @opencatbox{Categories:}
2026 @category{Expressions}
2027 @closecatbox
2028 @end deffn
2029
2030 @c -----------------------------------------------------------------------------
2031 @anchor{rembox}
2032 @deffn  {Function} rembox @
2033 @fname{rembox} (@var{expr}, unlabelled) @
2034 @fname{rembox} (@var{expr}, @var{label}) @
2035 @fname{rembox} (@var{expr})
2036
2037 Removes boxes from @var{expr}.
2038
2039 @code{rembox (@var{expr}, unlabelled)} removes all unlabelled boxes from
2040 @var{expr}.
2041
2042 @code{rembox (@var{expr}, @var{label})} removes only boxes bearing @var{label}.
2043
2044 @code{rembox (@var{expr})} removes all boxes, labelled and unlabelled.
2045
2046 Boxes are drawn by the @mrefcomma{box} @mrefcomma{dpart} and @mref{lpart}@w{}
2047 functions.
2048
2049 Examples:
2050
2051 @c ===beg===
2052 @c expr: (a*d - b*c)/h^2 + sin(%pi*x);
2053 @c dpart (dpart (expr, 1, 1), 2, 2);
2054 @c expr2: lpart (BAR, lpart (FOO, %, 1), 2);
2055 @c rembox (expr2, unlabelled);
2056 @c rembox (expr2, FOO);
2057 @c rembox (expr2, BAR);
2058 @c rembox (expr2);
2059 @c ===end===
2060 @example
2061 @group
2062 (%i1) expr: (a*d - b*c)/h^2 + sin(%pi*x);
2063                                   a d - b c
2064 (%o1)                sin(%pi x) + ---------
2065                                       2
2066                                      h
2067 @end group
2068 @group
2069 (%i2) dpart (dpart (expr, 1, 1), 2, 2);
2070 dpart: fell off the end.
2071  -- an error. To debug this try: debugmode(true);
2072 @end group
2073 @group
2074 (%i3) expr2: lpart (BAR, lpart (FOO, %, 1), 2);
2075                                   BAR""""""""
2076                    FOO"""""""""   "a d - b c"
2077 (%o3)              "sin(%pi x)" + "---------"
2078                    """"""""""""   "    2    "
2079                                   "   h     "
2080                                   """""""""""
2081 @end group
2082 @group
2083 (%i4) rembox (expr2, unlabelled);
2084                                   BAR""""""""
2085                    FOO"""""""""   "a d - b c"
2086 (%o4)              "sin(%pi x)" + "---------"
2087                    """"""""""""   "    2    "
2088                                   "   h     "
2089                                   """""""""""
2090 @end group
2091 @group
2092 (%i5) rembox (expr2, FOO);
2093                                  BAR""""""""
2094                                  "a d - b c"
2095 (%o5)               sin(%pi x) + "---------"
2096                                  "    2    "
2097                                  "   h     "
2098                                  """""""""""
2099 @end group
2100 @group
2101 (%i6) rembox (expr2, BAR);
2102                     FOO"""""""""   a d - b c
2103 (%o6)               "sin(%pi x)" + ---------
2104                     """"""""""""       2
2105                                       h
2106 @end group
2107 @group
2108 (%i7) rembox (expr2);
2109                                   a d - b c
2110 (%o7)                sin(%pi x) + ---------
2111                                       2
2112                                      h
2113 @end group
2114 @end example
2115
2116 @opencatbox{Categories:}
2117 @category{Expressions}
2118 @closecatbox
2119 @end deffn
2120
2121 @c -----------------------------------------------------------------------------
2122 @anchor{reveal}
2123 @deffn {Function} reveal (@var{expr}, @var{depth})
2124
2125 Replaces parts of @var{expr} at the specified integer @var{depth}
2126 with descriptive summaries.
2127
2128 @itemize @bullet
2129 @item
2130 Sums and differences are replaced by @code{Sum(@var{n})}
2131 where @var{n} is the number of operands of the sum.
2132 @item
2133 Products are replaced by @code{Product(@var{n})}
2134 where @var{n} is the number of operands of the product.
2135 @item
2136 Exponentials are replaced by @code{Expt}.
2137 @item
2138 Quotients are replaced by @code{Quotient}.
2139 @item
2140 Unary negation is replaced by @code{Negterm}.
2141 @item
2142 Lists are replaced by @code{List(@var{n})} where @var{n} is the number of
2143 elements of the list.
2144 @end itemize
2145
2146 When @var{depth} is greater than or equal to the maximum depth of @var{expr},
2147 @code{reveal (@var{expr}, @var{depth})} returns @var{expr} unmodified.
2148
2149 @code{reveal} evaluates its arguments.
2150 @code{reveal} returns the summarized expression.
2151
2152 Example:
2153
2154 @c ===beg===
2155 @c e: expand ((a - b)^2)/expand ((exp(a) + exp(b))^2);
2156 @c reveal (e, 1);
2157 @c reveal (e, 2);
2158 @c reveal (e, 3);
2159 @c reveal (e, 4);
2160 @c reveal (e, 5);
2161 @c reveal (e, 6);
2162 @c ===end===
2163 @example
2164 (%i1) e: expand ((a - b)^2)/expand ((exp(a) + exp(b))^2);
2165                           2            2
2166                          b  - 2 a b + a
2167 (%o1)               -------------------------
2168                         b + a     2 b     2 a
2169                     2 %e      + %e    + %e
2170 (%i2) reveal (e, 1);
2171 (%o2)                       Quotient
2172 (%i3) reveal (e, 2);
2173                              Sum(3)
2174 (%o3)                        ------
2175                              Sum(3)
2176 (%i4) reveal (e, 3);
2177 @group
2178                      Expt + Negterm + Expt
2179 (%o4)               ------------------------
2180                     Product(2) + Expt + Expt
2181 @end group
2182 (%i5) reveal (e, 4);
2183                        2                 2
2184                       b  - Product(3) + a
2185 (%o5)         ------------------------------------
2186                          Product(2)     Product(2)
2187               2 Expt + %e           + %e
2188 (%i6) reveal (e, 5);
2189                          2            2
2190                         b  - 2 a b + a
2191 (%o6)              --------------------------
2192                        Sum(2)     2 b     2 a
2193                    2 %e       + %e    + %e
2194 (%i7) reveal (e, 6);
2195                           2            2
2196                          b  - 2 a b + a
2197 (%o7)               -------------------------
2198                         b + a     2 b     2 a
2199                     2 %e      + %e    + %e
2200 @end example
2201
2202 @opencatbox{Categories:}
2203 @category{Expressions}
2204 @category{Display functions}
2205 @closecatbox
2206 @end deffn
2207
2208 @c -----------------------------------------------------------------------------
2209 @anchor{sqrtdenest}
2210 @deffn {Function} sqrtdenest (@var{expr})
2211 Denests @code{sqrt} of simple, numerical, binomial surds, where possible.  E.g.
2212
2213 @c ===beg===
2214 @c sqrt(sqrt(3)/2+1)/sqrt(11*sqrt(2)-12);
2215 @c sqrtdenest(%);
2216 @c ===end===
2217 @example
2218 @group
2219 (%i1) sqrt(sqrt(3)/2+1)/sqrt(11*sqrt(2)-12);
2220                              sqrt(3)
2221                         sqrt(------- + 1)
2222                                 2
2223 (%o1)                 ---------------------
2224                       sqrt(11 sqrt(2) - 12)
2225 @end group
2226 @group
2227 (%i2) sqrtdenest(%);
2228                            sqrt(3)   1
2229                            ------- + -
2230                               2      2
2231 (%o2)                     -------------
2232                              1/4    3/4
2233                           3 2    - 2
2234 @end group
2235 @end example
2236
2237 Sometimes it helps to apply @code{sqrtdenest} more than once, on such as
2238 @code{(19601-13860 sqrt(2))^(7/4)}.
2239
2240 @opencatbox{Categories:}
2241 @category{Expressions}
2242 @closecatbox
2243
2244 @end deffn
2245
2246 @c NEEDS EXPANSION, CLARIFICATION, MORE EXAMPLES
2247
2248 @c -----------------------------------------------------------------------------
2249 @anchor{sublis}
2250 @deffn {Function} sublis (@var{list}, @var{expr})
2251
2252 Makes multiple parallel substitutions into an expression.  @var{list} is a list
2253 of equations.  The left hand side of the equations must be an atom.
2254
2255 The variable @mref{sublis_apply_lambda} controls simplification after
2256 @code{sublis}.
2257
2258 See also @mref{psubst} for making parallel substitutions.
2259
2260 Example:
2261
2262 @c ===beg===
2263 @c sublis ([a=b, b=a], sin(a) + cos(b));
2264 @c ===end===
2265 @example
2266 @group
2267 (%i1) sublis ([a=b, b=a], sin(a) + cos(b));
2268 (%o1)                    sin(b) + cos(a)
2269 @end group
2270 @end example
2271
2272 @opencatbox{Categories:}
2273 @category{Expressions}
2274 @closecatbox
2275 @end deffn
2276
2277 @c -----------------------------------------------------------------------------
2278 @anchor{sublis_apply_lambda}
2279 @defvr {Option variable} sublis_apply_lambda
2280 Default value: @code{true}
2281
2282 Controls whether @code{lambda}'s substituted are applied in simplification after
2283 @code{sublis} is used or whether you have to do an @mref{ev} to get things to
2284 apply.  @code{true} means do the application.
2285
2286 @opencatbox{Categories:}
2287 @category{Expressions}
2288 @closecatbox
2289 @end defvr
2290
2291 @c -----------------------------------------------------------------------------
2292 @anchor{subnumsimp}
2293 @defvr {Option variable} subnumsimp
2294 Default value: @code{false}
2295
2296 If @code{true} then the functions @mref{subst} and @mref{psubst} can substitute
2297 a subscripted variable @code{f[x]} with a number, when only the symbol @code{f}
2298 is given.
2299
2300 See also @mrefdot{subst}
2301
2302 @c ===beg===
2303 @c subst(100,g,g[x]+2);
2304 @c subst(100,g,g[x]+2),subnumsimp:true;
2305 @c ===end===
2306 @example
2307 (%i1) subst(100,g,g[x]+2);
2308
2309 subst: cannot substitute 100 for operator g in expression g
2310                                                            x
2311  -- an error. To debug this try: debugmode(true);
2312
2313 (%i2) subst(100,g,g[x]+2),subnumsimp:true;
2314 (%o2)                          102
2315 @end example
2316
2317 @opencatbox{Categories:}
2318 @category{Expressions}
2319 @closecatbox
2320 @end defvr
2321
2322 @c NEEDS CLARIFICATION, MORE EXAMPLES
2323
2324 @c -----------------------------------------------------------------------------
2325 @anchor{subst}
2326 @deffn {Function} subst (@var{a}, @var{b}, @var{c})
2327
2328 Substitutes @var{a} for @var{b} in @var{c}.  @var{b} must be an atom or a
2329 complete subexpression of @var{c}.  For example, @code{x+y+z} is a complete
2330 subexpression of @code{2*(x+y+z)/w} while @code{x+y} is not.  When @var{b} does
2331 not have these characteristics, one may sometimes use @mref{substpart} or
2332 @mref{ratsubst} (see below).  Alternatively, if @var{b} is of the form
2333 @code{e/f} then one could use @code{subst (a*f, e, c)} while if @var{b} is of
2334 the form @code{e^(1/f)} then one could use @code{subst (a^f, e, c)}.  The
2335 @code{subst} command also discerns the @code{x^y} in @code{x^-y} so that
2336 @code{subst (a, sqrt(x), 1/sqrt(x))} yields @code{1/a}.  @var{a} and @var{b}
2337 may also be operators of an expression enclosed in double-quotes @code{"} or
2338 they may be function names.  If one wishes to substitute for the independent
2339 variable in derivative forms then the @code{at} function (see below) should be
2340 used.
2341
2342 @c UMM, REVERSE THIS AND MOVE IT TO substitute ??
2343 @code{subst} is an alias for @code{substitute}.
2344
2345 The commands @code{subst (@var{eq_1}, @var{expr})} or
2346 @code{subst ([@var{eq_1}, ..., @var{eq_k}], @var{expr})} are other permissible
2347 forms.  The @var{eq_i} are equations indicating substitutions to be made.
2348 For each equation, the right side will be substituted for the left in the
2349 expression @var{expr}.  The equations are substituted in serial from left to
2350 right in @var{expr}.  See the functions @code{sublis} and @code{psubst} for
2351 making parallel substitutions.
2352
2353 @mref{exptsubst} if @code{true} permits substitutions
2354 like @code{y} for @code{%e^x} in @code{%e^(a*x)} to take place.
2355
2356 @c WHAT IS THIS ABOUT ??
2357 When @code{opsubst} is @code{false},
2358 @code{subst} will not attempt to substitute into the operator of an expression.
2359 E.g. @code{(opsubst: false, subst (x^2, r, r+r[0]))} will work.
2360
2361 See also @mrefcomma{at} @mref{ev} and @mrefcomma{psubst} as well as @mref{let}
2362 and @mrefdot{letsimp}
2363
2364 Examples:
2365
2366 @c ===beg===
2367 @c subst (a, x+y, x + (x+y)^2 + y);
2368 @c subst (-%i, %i, a + b*%i);
2369 @c ===end===
2370 @example
2371 @group
2372 (%i1) subst (a, x+y, x + (x+y)^2 + y);
2373                                     2
2374 (%o1)                      y + x + a
2375 @end group
2376 @group
2377 (%i2) subst (-%i, %i, a + b*%i);
2378 (%o2)                       a - %i b
2379 @end group
2380 @end example
2381
2382 The substitution is done in serial for a list of equations.  Compare this with
2383 a parallel substitution:
2384
2385 @c ===beg===
2386 @c subst([a=b, b=c], a+b);
2387 @c sublis([a=b, b=c], a+b);
2388 @c ===end===
2389 @example
2390 @group
2391 (%i1) subst([a=b, b=c], a+b);
2392 (%o1)                          2 c
2393 @end group
2394 @group
2395 (%i2) sublis([a=b, b=c], a+b);
2396 (%o2)                         c + b
2397 @end group
2398 @end example
2399
2400 Single-character Operators like @code{+} and @code{-} have to be quoted in
2401 order to be replaced by subst. It is to note, though, that @code{a+b-c}
2402 might be expressed as @code{a+b+(-1*c)} internally.
2403
2404 @c ===beg===
2405 @c subst(["+"="-"],a+b-c);
2406 @c ===end===
2407 @example
2408 (%i3) subst(["+"="-"],a+b-c);
2409 (%o3)                                 c-b+a
2410 @end example
2411
2412 The difference between @code{subst} and @code{at} can be seen in the
2413 following example:
2414 @c ===beg===
2415 @c g1:y(t)=a*x(t)+b*diff(x(t),t);
2416 @c subst('diff(x(t),t)=1,g1);
2417 @c at(g1,'diff(x(t),t)=1);
2418 @c ===end===
2419 @example
2420 @group
2421 (%i1) g1:y(t)=a*x(t)+b*diff(x(t),t);
2422                             d
2423 (%o1)             y(t) = b (-- (x(t))) + a x(t)
2424                             dt
2425 @end group
2426 @group
2427 (%i2) subst('diff(x(t),t)=1,g1);
2428 (%o2)                   y(t) = a x(t) + b
2429 @end group
2430 @group
2431 (%i3) at(g1,'diff(x(t),t)=1);
2432                               !
2433                      d        !
2434 (%o3)      y(t) = b (-- (x(t))!             ) + a x(t)
2435                      dt       !d
2436                               !-- (x(t)) = 1
2437                                dt
2438 @end group
2439 @end example
2440
2441 @noindent
2442 For further examples, do @code{example (subst)}.
2443
2444 @opencatbox{Categories:}
2445 @category{Expressions}
2446 @closecatbox
2447 @end deffn
2448
2449 @c NEEDS CLARIFICATION
2450
2451 @c ----------------------------------------------------------------------------
2452 @anchor{substinpart}
2453 @deffn {Function} substinpart (@var{x}, @var{expr}, @var{n_1}, @dots{}, @var{n_k})
2454
2455 Similar to @mrefcomma{substpart} but @code{substinpart} works on the
2456 internal representation of @var{expr}.
2457
2458 Examples:
2459
2460 @c ===beg===
2461 @c x . 'diff (f(x), x, 2);
2462 @c substinpart (d^2, %, 2);
2463 @c substinpart (f1, f[1](x + 1), 0);
2464 @c ===end===
2465 @example
2466 @group
2467 (%i1) x . 'diff (f(x), x, 2);
2468                               2
2469                              d
2470 (%o1)                   x . (--- (f(x)))
2471                                2
2472                              dx
2473 @end group
2474 @group
2475 (%i2) substinpart (d^2, %, 2);
2476                                   2
2477 (%o2)                        x . d
2478 @end group
2479 @group
2480 (%i3) substinpart (f1, f[1](x + 1), 0);
2481 (%o3)                       f1(x + 1)
2482 @end group
2483 @end example
2484
2485 If the last argument to a @code{part} function is a list of indices then
2486 several subexpressions are picked out, each one corresponding to an
2487 index of the list.  Thus
2488
2489 @c ===beg===
2490 @c part (x + y + z, [1, 3]);
2491 @c ===end===
2492 @example
2493 @group
2494 (%i1) part (x + y + z, [1, 3]);
2495 (%o1)                         z + x
2496 @end group
2497 @end example
2498
2499 @mref{piece} holds the value of the last expression selected when using the
2500 @code{part} functions.  It is set during the execution of the function and
2501 thus may be referred to in the function itself as shown below.
2502 If @mref{partswitch} is set to @code{true} then @code{end} is returned when a
2503 selected part of an expression doesn't exist, otherwise an error
2504 message is given.
2505
2506 @c ===beg===
2507 @c expr: 27*y^3 + 54*x*y^2 + 36*x^2*y + y + 8*x^3 + x + 1;
2508 @c part (expr, 2, [1, 3]);
2509 @c sqrt (piece/54);
2510 @c substpart (factor (piece), expr, [1, 2, 3, 5]);
2511 @c expr: 1/x + y/x - 1/z;
2512 @c substpart (xthru (piece), expr, [2, 3]);
2513 @c ===end===
2514 @example
2515 @group
2516 (%i1) expr: 27*y^3 + 54*x*y^2 + 36*x^2*y + y + 8*x^3 + x + 1;
2517               3         2       2            3
2518 (%o1)     27 y  + 54 x y  + 36 x  y + y + 8 x  + x + 1
2519 @end group
2520 @group
2521 (%i2) part (expr, 2, [1, 3]);
2522                                   2
2523 (%o2)                         54 y
2524 @end group
2525 @group
2526 (%i3) sqrt (piece/54);
2527 (%o3)                        abs(y)
2528 @end group
2529 @group
2530 (%i4) substpart (factor (piece), expr, [1, 2, 3, 5]);
2531                                3
2532 (%o4)               (3 y + 2 x)  + y + x + 1
2533 @end group
2534 @group
2535 (%i5) expr: 1/x + y/x - 1/z;
2536                              1    y   1
2537 (%o5)                     (- -) + - + -
2538                              z    x   x
2539 @end group
2540 @group
2541 (%i6) substpart (xthru (piece), expr, [2, 3]);
2542                             y + 1   1
2543 (%o6)                       ----- - -
2544                               x     z
2545 @end group
2546 @end example
2547
2548 Also, setting the option @mref{inflag} to @code{true} and calling @mref{part}
2549 or @mref{substpart} is the same as calling @mref{inpart} or @code{substinpart}.
2550
2551 @opencatbox{Categories:}
2552 @category{Expressions}
2553 @closecatbox
2554 @end deffn
2555
2556 @c NEEDS CLARIFICATION
2557
2558 @c -----------------------------------------------------------------------------
2559 @anchor{substpart}
2560 @deffn {Function} substpart (@var{x}, @var{expr}, @var{n_1}, @dots{}, @var{n_k})
2561
2562 Substitutes @var{x} for the subexpression picked out by the rest of the
2563 arguments as in @mrefdot{part}  It returns the new value of @var{expr}.  @var{x}
2564 may be some operator to be substituted for an operator of @var{expr}.  In some
2565 cases @var{x} needs to be enclosed in double-quotes @code{"} (e.g.
2566 @code{substpart ("+", a*b, 0)} yields @code{b + a}).
2567
2568 Example:
2569
2570 @c ===beg===
2571 @c 1/(x^2 + 2);
2572 @c substpart (3/2, %, 2, 1, 2);
2573 @c a*x + f(b, y);
2574 @c substpart ("+", %, 1, 0);
2575 @c ===end===
2576 @example
2577 @group
2578 (%i1) 1/(x^2 + 2);
2579                                1
2580 (%o1)                        ------
2581                               2
2582                              x  + 2
2583 @end group
2584 @group
2585 (%i2) substpart (3/2, %, 2, 1, 2);
2586                                1
2587 (%o2)                       --------
2588                              3/2
2589                             x    + 2
2590 @end group
2591 @group
2592 (%i3) a*x + f(b, y);
2593 (%o3)                     a x + f(b, y)
2594 @end group
2595 @group
2596 (%i4) substpart ("+", %, 1, 0);
2597 (%o4)                    x + f(b, y) + a
2598 @end group
2599 @end example
2600
2601 Also, setting the option @mref{inflag} to @code{true} and calling @mref{part}
2602 or @code{substpart} is the same as calling @code{inpart} or
2603 @mrefdot{substinpart}
2604
2605 @opencatbox{Categories:}
2606 @category{Expressions}
2607 @closecatbox
2608 @end deffn
2609
2610 @c -----------------------------------------------------------------------------
2611 @anchor{symbolp}
2612 @deffn {Function} symbolp (@var{expr})
2613
2614 Returns @code{true} if @var{expr} is a symbol, else @code{false}.
2615
2616 @c FOLLOWING REALLY WANTS TO BE @xref{Identiifers} BUT THAT
2617 @c LEAVES THE UNPLEASANT RESIDUE *Note ...:: IN THE OUTPUT OF describe
2618 See also @ref{Identifiers}.
2619
2620 @opencatbox{Categories:}
2621 @category{Predicate functions}
2622 @closecatbox
2623 @end deffn
2624
2625 @c -----------------------------------------------------------------------------
2626 @anchor{unorder}
2627 @deffn {Function} unorder ()
2628
2629 Disables the aliasing created by the last use of the ordering commands
2630 @code{ordergreat} and @code{orderless}.  @code{ordergreat} and @code{orderless}
2631 may not be used more than one time each without calling @code{unorder}.
2632 @code{unorder} does not substitute back in expressions the original symbols for
2633 the aliases introduced by @code{ordergreat} and @code{orderless}.  Therefore,
2634 after execution of @code{unorder} the aliases appear in previous expressions.
2635
2636 See also @code{ordergreat} and @code{orderless}.
2637
2638 Examples:
2639
2640 @code{ordergreat(a)} introduces an alias for the symbol @code{a}.  Therefore,
2641 the difference of @code{%o2} and @code{%o4} does not vanish.  @code{unorder}
2642 does not substitute back the symbol @code{a} and the alias appears in the
2643 output @code{%o7}.
2644
2645 @c ===beg===
2646 @c unorder();
2647 @c b*x + a^2;
2648 @c ordergreat (a);
2649 @c b*x + a^2;
2650 @c  %th(1) - %th(3);
2651 @c unorder();
2652 @c %th(2);
2653 @c ===end===
2654 @example
2655 @group
2656 (%i1) unorder();
2657 (%o1)                          []
2658 @end group
2659 @group
2660 (%i2) b*x + a^2;
2661                                    2
2662 (%o2)                       b x + a
2663 @end group
2664 @group
2665 (%i3) ordergreat (a);
2666 (%o3)                         done
2667 @end group
2668 @group
2669 (%i4) b*x + a^2;
2670  %th(1) - %th(3);
2671                              2
2672 (%o4)                       a  + b x
2673 @end group
2674 @group
2675 (%i5) unorder();
2676                               2    2
2677 (%o5)                        a  - a
2678 @end group
2679 @group
2680 (%i6) %th(2);
2681 (%o6)                          [a]
2682 @end group
2683 @end example
2684
2685 @opencatbox{Categories:}
2686 @category{Expressions}
2687 @closecatbox
2688 @end deffn
2689
2690 @c -----------------------------------------------------------------------------
2691 @anchor{verbify}
2692 @deffn {Function} verbify (@var{f})
2693
2694 Returns the verb form of the function name @var{f}.
2695 See also @code{verb}, @code{noun}, and @code{nounify}.
2696
2697 Examples:
2698
2699 @c ===beg===
2700 @c verbify ('foo);
2701 @c :lisp $%
2702 @c nounify (foo);
2703 @c :lisp $%
2704 @c ===end===
2705 @example
2706 @group
2707 (%i1) verbify ('foo);
2708 (%o1)                          foo
2709 @end group
2710 @group
2711 (%i2) :lisp $%
2712 $FOO
2713 @end group
2714 @group
2715 (%i2) nounify (foo);
2716 (%o2)                          foo
2717 @end group
2718 @group
2719 (%i3) :lisp $%
2720 %FOO
2721 @end group
2722 @end example
2723
2724 @opencatbox{Categories:}
2725 @category{Nouns and verbs}
2726 @closecatbox
2727 @end deffn
2728