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