| blob | b11e1630fc214417f4316757a734cb05fd95e28c |
1 @menu
2 * Introduction to operators::
3 * Arithmetic operators::
4 * Relational operators::
5 * Logical operators::
6 * Operators for Equations::
7 * Assignment operators::
8 * User defined operators::
9 @end menu
11 @c -----------------------------------------------------------------------------
12 @node Introduction to operators, Arithmetic operators, Operators, Operators
13 @section Introduction to operators
14 @c -----------------------------------------------------------------------------
16 It is possible to define new operators with specified precedence, to undefine
17 existing operators, or to redefine the precedence of existing operators. An
18 operator may be unary prefix or unary postfix, binary infix, n-ary infix,
19 matchfix, or nofix. "Matchfix" means a pair of symbols which enclose their
20 argument or arguments, and "nofix" means an operator which takes no arguments.
21 As examples of the different types of operators, there are the following.
23 @table @asis
24 @item unary prefix
25 negation @code{- a}
26 @item unary postfix
27 factorial @code{a!}
28 @item binary infix
29 exponentiation @code{a^b}
30 @item n-ary infix
31 addition @code{a + b}
32 @item matchfix
33 list construction @code{[a, b]}
34 @end table
36 (There are no built-in nofix operators; for an example of such an operator,
37 see @code{nofix}.)
39 The mechanism to define a new operator is straightforward. It is only necessary
40 to declare a function as an operator; the operator function might or might not
41 be defined.
43 An example of user-defined operators is the following. Note that the explicit
44 function call @code{"dd" (a)} is equivalent to @code{dd a}, likewise
45 @code{"<-" (a, b)} is equivalent to @code{a <- b}. Note also that the functions
46 @code{"dd"} and @code{"<-"} are undefined in this example.
48 @c ===beg===
49 @c prefix ("dd");
50 @c dd a;
51 @c "dd" (a);
52 @c infix ("<-");
53 @c a <- dd b;
54 @c "<-" (a, "dd" (b));
55 @c ===end===
56 @example
57 (%i1) prefix ("dd");
58 (%o1) dd
59 (%i2) dd a;
60 (%o2) dd a
61 (%i3) "dd" (a);
62 (%o3) dd a
63 (%i4) infix ("<-");
64 (%o4) <-
65 (%i5) a <- dd b;
66 (%o5) a <- dd b
67 (%i6) "<-" (a, "dd" (b));
68 (%o6) a <- dd b
69 @end example
71 The Maxima functions which define new operators are summarized in this table,
72 stating the default left and right binding powers (lbp and rbp, respectively).
73 @c REWORK FOLLOWING COMMENT.
74 @c IT'S NOT CLEAR ENOUGH, GIVEN THAT IT'S FAIRLY IMPORTANT
75 (Binding power determines operator precedence. However, since left and right
76 binding powers can differ, binding power is somewhat more complicated than
77 precedence.) Some of the operation definition functions take additional
78 arguments; see the function descriptions for details.
80 @c MAKE ANCHORS FOR ALL 6 FUNCTIONS AND CHANGE @code TO @ref ACCORDINGLY
81 @table @code
82 @item prefix
83 rbp=180
84 @item postfix
85 lbp=180
86 @item infix
87 lbp=180, rbp=180
88 @item nary
89 lbp=180, rbp=180
90 @item matchfix
91 (binding power not applicable)
92 @item nofix
93 (binding power not applicable)
94 @end table
96 For comparison, here are some built-in operators and their left and right
97 binding powers.
99 @example
100 Operator lbp rbp
102 : 180 20
103 :: 180 20
104 := 180 20
105 ::= 180 20
106 ! 160
107 !! 160
108 ^ 140 139
109 . 130 129
110 * 120
111 / 120 120
112 + 100 100
113 - 100 134
114 = 80 80
115 # 80 80
116 > 80 80
117 >= 80 80
118 < 80 80
119 <= 80 80
120 not 70
121 and 65
122 or 60
123 , 10
124 $ -1
125 ; -1
126 @end example
128 @mref{remove} and @mref{kill} remove operator properties from an atom.
129 @code{remove ("@var{a}", op)} removes only the operator properties of @var{a}.
130 @code{kill ("@var{a}")} removes all properties of @var{a}, including the
131 operator properties. Note that the name of the operator must be enclosed in
132 quotation marks.
134 @c MAYBE COPY THIS EXAMPLE TO remove AND/OR kill
135 @c ===beg===
136 @c infix ("##");
137 @c "##" (a, b) := a^b;
138 @c 5 ## 3;
139 @c remove ("##", op);
140 @c 5 ## 3;
141 @c "##" (5, 3);
142 @c infix ("##");
143 @c 5 ## 3;
144 @c kill ("##");
145 @c 5 ## 3;
146 @c "##" (5, 3);
147 @c ===end===
148 @example
149 (%i1) infix ("##");
150 (%o1) ##
151 (%i2) "##" (a, b) := a^b;
152 b
153 (%o2) a ## b := a
154 (%i3) 5 ## 3;
155 (%o3) 125
156 (%i4) remove ("##", op);
157 (%o4) done
158 (%i5) 5 ## 3;
159 Incorrect syntax: # is not a prefix operator
160 5 ##
161 ^
162 (%i5) "##" (5, 3);
163 (%o5) 125
164 (%i6) infix ("##");
165 (%o6) ##
166 (%i7) 5 ## 3;
167 (%o7) 125
168 (%i8) kill ("##");
169 (%o8) done
170 (%i9) 5 ## 3;
171 Incorrect syntax: # is not a prefix operator
172 5 ##
173 ^
174 (%i9) "##" (5, 3);
175 (%o9) ##(5, 3)
176 @end example
178 @opencatbox{Categories:}
179 @category{Operators}
180 @category{Syntax}
181 @closecatbox
183 @c -----------------------------------------------------------------------------
184 @node Arithmetic operators, Relational operators, Introduction to operators, Operators
185 @section Arithmetic operators
186 @c -----------------------------------------------------------------------------
188 @c -----------------------------------------------------------------------------
189 @anchor{+}
190 @anchor{-}
191 @anchor{*}
192 @anchor{/}
193 @anchor{^}
194 @fnindex Addition
195 @fnindex Subtraction
196 @fnindex Multiplication
197 @fnindex Division
198 @fnindex Exponentiation
200 @deffn {Operator} +
201 @deffnx {Operator} -
202 @deffnx {Operator} *
203 @deffnx {Operator} /
204 @deffnx {Operator} ^
206 The symbols @code{+} @code{*} @code{/} and @code{^} represent addition,
207 multiplication, division, and exponentiation, respectively. The names of these
208 operators are @code{"+"} @code{"*"} @code{"/"} and @code{"^"}, which may appear
209 where the name of a function or operator is required.
211 The symbols @code{+} and @code{-} represent unary addition and negation,
212 respectively, and the names of these operators are @code{"+"} and @code{"-"},
213 respectively.
215 Subtraction @code{a - b} is represented within Maxima as addition,
216 @code{a + (- b)}. Expressions such as @code{a + (- b)} are displayed as
217 subtraction. Maxima recognizes @code{"-"} only as the name of the unary
218 negation operator, and not as the name of the binary subtraction operator.
220 Division @code{a / b} is represented within Maxima as multiplication,
221 @code{a * b^(- 1)}. Expressions such as @code{a * b^(- 1)} are displayed as
222 division. Maxima recognizes @code{"/"} as the name of the division operator.
224 Addition and multiplication are n-ary, commutative operators.
225 Division and exponentiation are binary, noncommutative operators.
227 Maxima sorts the operands of commutative operators to construct a canonical
228 representation. For internal storage, the ordering is determined by
229 @mrefdot{orderlessp} For display, the ordering for addition is determined by
230 @mrefcomma{ordergreatp} and for multiplication, it is the same as the internal
231 ordering.
233 Arithmetic computations are carried out on literal numbers (integers, rationals,
234 ordinary floats, and bigfloats). Except for exponentiation, all arithmetic
235 operations on numbers are simplified to numbers. Exponentiation is simplified
236 to a number if either operand is an ordinary float or bigfloat or if the result
237 is an exact integer or rational; otherwise an exponentiation may be simplified
238 to @mref{sqrt} or another exponentiation or left unchanged.
240 Floating-point contagion applies to arithmetic computations: if any operand is
241 a bigfloat, the result is a bigfloat; otherwise, if any operand is an ordinary
242 float, the result is an ordinary float; otherwise, the operands are rationals
243 or integers and the result is a rational or integer.
245 Arithmetic computations are a simplification, not an evaluation.
246 Thus arithmetic is carried out in quoted (but simplified) expressions.
248 Arithmetic operations are applied element-by-element to lists when the global
249 flag @mref{listarith} is @code{true}, and always applied element-by-element to
250 matrices. When one operand is a list or matrix and another is an operand of
251 some other type, the other operand is combined with each of the elements of the
252 list or matrix.
254 Examples:
256 Addition and multiplication are n-ary, commutative operators.
257 Maxima sorts the operands to construct a canonical representation.
258 The names of these operators are @code{"+"} and @code{"*"}.
260 @c ===beg===
261 @c c + g + d + a + b + e + f;
262 @c [op (%), args (%)];
263 @c c * g * d * a * b * e * f;
264 @c [op (%), args (%)];
265 @c apply ("+", [a, 8, x, 2, 9, x, x, a]);
266 @c apply ("*", [a, 8, x, 2, 9, x, x, a]);
267 @c ===end===
268 @example
269 (%i1) c + g + d + a + b + e + f;
270 (%o1) g + f + e + d + c + b + a
271 (%i2) [op (%), args (%)];
272 (%o2) [+, [g, f, e, d, c, b, a]]
273 (%i3) c * g * d * a * b * e * f;
274 (%o3) a b c d e f g
275 (%i4) [op (%), args (%)];
276 (%o4) [*, [a, b, c, d, e, f, g]]
277 (%i5) apply ("+", [a, 8, x, 2, 9, x, x, a]);
278 (%o5) 3 x + 2 a + 19
279 (%i6) apply ("*", [a, 8, x, 2, 9, x, x, a]);
280 2 3
281 (%o6) 144 a x
282 @end example
284 Division and exponentiation are binary, noncommutative operators.
285 The names of these operators are @code{"/"} and @code{"^"}.
287 @c ===beg===
288 @c [a / b, a ^ b];
289 @c [map (op, %), map (args, %)];
290 @c [apply ("/", [a, b]), apply ("^", [a, b])];
291 @c ===end===
292 @example
293 (%i1) [a / b, a ^ b];
294 a b
295 (%o1) [-, a ]
296 b
297 (%i2) [map (op, %), map (args, %)];
298 (%o2) [[/, ^], [[a, b], [a, b]]]
299 (%i3) [apply ("/", [a, b]), apply ("^", [a, b])];
300 a b
301 (%o3) [-, a ]
302 b
303 @end example
305 Subtraction and division are represented internally
306 in terms of addition and multiplication, respectively.
308 @c ===beg===
309 @c [inpart (a - b, 0), inpart (a - b, 1), inpart (a - b, 2)];
310 @c [inpart (a / b, 0), inpart (a / b, 1), inpart (a / b, 2)];
311 @c ===end===
312 @example
313 (%i1) [inpart (a - b, 0), inpart (a - b, 1), inpart (a - b, 2)];
314 (%o1) [+, a, - b]
315 (%i2) [inpart (a / b, 0), inpart (a / b, 1), inpart (a / b, 2)];
316 1
317 (%o2) [*, a, -]
318 b
319 @end example
321 Computations are carried out on literal numbers.
322 Floating-point contagion applies.
324 @c ===beg===
325 @c 17 + b - (1/2)*29 + 11^(2/4);
326 @c [17 + 29, 17 + 29.0, 17 + 29b0];
327 @c ===end===
328 @example
329 (%i1) 17 + b - (1/2)*29 + 11^(2/4);
330 5
331 (%o1) b + sqrt(11) + -
332 2
333 (%i2) [17 + 29, 17 + 29.0, 17 + 29b0];
334 (%o2) [46, 46.0, 4.6b1]
335 @end example
337 Arithmetic computations are a simplification, not an evaluation.
339 @c ===beg===
340 @c simp : false;
341 @c '(17 + 29*11/7 - 5^3);
342 @c simp : true;
343 @c '(17 + 29*11/7 - 5^3);
344 @c ===end===
345 @example
346 (%i1) simp : false;
347 (%o1) false
348 (%i2) '(17 + 29*11/7 - 5^3);
349 29 11 3
350 (%o2) 17 + ----- - 5
351 7
352 (%i3) simp : true;
353 (%o3) true
354 (%i4) '(17 + 29*11/7 - 5^3);
355 437
356 (%o4) - ---
357 7
358 @end example
360 Arithmetic is carried out element-by-element for lists (depending on
361 @code{listarith}) and matrices.
363 @c ===beg===
364 @c matrix ([a, x], [h, u]) - matrix ([1, 2], [3, 4]);
365 @c 5 * matrix ([a, x], [h, u]);
366 @c listarith : false;
367 @c [a, c, m, t] / [1, 7, 2, 9];
368 @c [a, c, m, t] ^ x;
369 @c listarith : true;
370 @c [a, c, m, t] / [1, 7, 2, 9];
371 @c [a, c, m, t] ^ x;
372 @c ===end===
373 @example
374 (%i1) matrix ([a, x], [h, u]) - matrix ([1, 2], [3, 4]);
375 @group
376 [ a - 1 x - 2 ]
377 (%o1) [ ]
378 [ h - 3 u - 4 ]
379 @end group
380 (%i2) 5 * matrix ([a, x], [h, u]);
381 [ 5 a 5 x ]
382 (%o2) [ ]
383 [ 5 h 5 u ]
384 (%i3) listarith : false;
385 (%o3) false
386 (%i4) [a, c, m, t] / [1, 7, 2, 9];
387 [a, c, m, t]
388 (%o4) ------------
389 [1, 7, 2, 9]
390 (%i5) [a, c, m, t] ^ x;
391 x
392 (%o5) [a, c, m, t]
393 (%i6) listarith : true;
394 (%o6) true
395 (%i7) [a, c, m, t] / [1, 7, 2, 9];
396 c m t
397 (%o7) [a, -, -, -]
398 7 2 9
399 (%i8) [a, c, m, t] ^ x;
400 x x x x
401 (%o8) [a , c , m , t ]
402 @end example
404 @opencatbox{Categories:}
405 @category{Operators}
406 @closecatbox
407 @end deffn
409 @c -----------------------------------------------------------------------------
410 @anchor{**}
411 @deffn {Operator} **
413 Exponentiation operator.
414 Maxima recognizes @code{**} as the same operator as @mref{^} in input,
415 and it is displayed as @code{^} in 1-dimensional output,
416 or by placing the exponent as a superscript in 2-dimensional output.
418 The @mref{fortran} function displays the exponentiation operator as @code{**},
419 whether it was input as @code{**} or @code{^}.
421 Examples:
423 @c ===beg===
424 @c is (a**b = a^b);
425 @c x**y + x^z;
426 @c string (x**y + x^z);
427 @c fortran (x**y + x^z);
428 @c ===end===
429 @example
430 (%i1) is (a**b = a^b);
431 (%o1) true
432 (%i2) x**y + x^z;
433 z y
434 (%o2) x + x
435 (%i3) string (x**y + x^z);
436 (%o3) x^z+x^y
437 (%i4) fortran (x**y + x^z);
438 x**z+x**y
439 (%o4) done
440 @end example
442 @opencatbox{Categories:}
443 @category{Operators}
444 @closecatbox
445 @end deffn
447 @c -----------------------------------------------------------------------------
448 @anchor{^^}
449 @deffn {Operator} ^^
450 @ifinfo
451 @fnindex Noncommutative exponentiation
452 @end ifinfo
454 Noncommutative exponentiation operator.
455 @code{^^} is the exponentiation operator corresponding to noncommutative
456 multiplication @code{.}, just as the ordinary exponentiation operator @code{^}
457 corresponds to commutative multiplication @code{*}.
459 Noncommutative exponentiation is displayed by @code{^^} in 1-dimensional output,
460 and by placing the exponent as a superscript within angle brackets @code{< >}
461 in 2-dimensional output.
463 Examples:
465 @c ===beg===
466 @c a . a . b . b . b + a * a * a * b * b;
467 @c string (a . a . b . b . b + a * a * a * b * b);
468 @c ===end===
469 @example
470 (%i1) a . a . b . b . b + a * a * a * b * b;
471 3 2 <2> <3>
472 (%o1) a b + a . b
473 (%i2) string (a . a . b . b . b + a * a * a * b * b);
474 (%o2) a^3*b^2+a^^2 . b^^3
475 @end example
477 @opencatbox{Categories:}
478 @category{Operators}
479 @closecatbox
480 @end deffn
482 @c -----------------------------------------------------------------------------
483 @anchor{.}
484 @deffn {Operator} .
485 @ifinfo
486 @fnindex Noncommutative multiplication
487 @end ifinfo
489 The dot operator, for matrix (non-commutative) multiplication.
490 When @code{"."} is used in this way, spaces should be left on both sides of
491 it, e.g. @code{A . B} This distinguishes it plainly from a decimal point in
492 a floating point number.
494 See also
495 @mrefcomma{Dot}
496 @mrefcomma{dot0nscsimp}
497 @mrefcomma{dot0simp}
498 @mrefcomma{dot1simp}
499 @mrefcomma{dotassoc}
500 @mrefcomma{dotconstrules}
501 @mrefcomma{dotdistrib}
502 @mrefcomma{dotexptsimp}
503 @mrefcomma{dotident}
504 and
505 @mrefdot{dotscrules}
507 @opencatbox{Categories:}
508 @category{Operators}
509 @closecatbox
510 @end deffn
512 @c -----------------------------------------------------------------------------
513 @node Relational operators, Logical operators, Arithmetic operators, Operators
514 @section Relational operators
515 @c -----------------------------------------------------------------------------
517 @c -----------------------------------------------------------------------------
518 @anchor{<}
519 @anchor{<=}
520 @anchor{>=}
521 @anchor{>}
522 @fnindex Less than
523 @fnindex Less than or equal
524 @fnindex Greater than or equal
525 @fnindex Greater than
527 @deffn {Operator} <
528 @deffnx {Operator} <=
529 @deffnx {Operator} >=
530 @deffnx {Operator} >
532 The symbols @code{<} @code{<=} @code{>=} and @code{>} represent less than, less
533 than or equal, greater than or equal, and greater than, respectively. The names
534 of these operators are @code{"<"} @code{"<="} @code{">="} and @code{">"}, which
535 may appear where the name of a function or operator is required.
537 These relational operators are all binary operators; constructs such as
538 @code{a < b < c} are not recognized by Maxima.
540 Relational expressions are evaluated to Boolean values by the functions
541 @mref{is} and @mrefcomma{maybe} and the programming constructs
542 @mrefcomma{if} @mrefcomma{while} and @mrefdot{unless} Relational expressions
543 are not otherwise evaluated or simplified to Boolean values, although the
544 arguments of relational expressions are evaluated (when evaluation is not
545 otherwise prevented by quotation).
547 When a relational expression cannot be evaluated to @code{true} or @code{false},
548 the behavior of @code{is} and @code{if} are governed by the global flag
549 @mrefdot{prederror} When @code{prederror} is @code{true}, @code{is} and
550 @code{if} trigger an error. When @code{prederror} is @code{false}, @code{is}
551 returns @code{unknown}, and @code{if} returns a partially-evaluated conditional
552 expression.
554 @code{maybe} always behaves as if @code{prederror} were @code{false}, and
555 @code{while} and @code{unless} always behave as if @code{prederror} were
556 @code{true}.
558 Relational operators do not distribute over lists or other aggregates.
560 See also @mrefcomma{=} @mrefcomma{#} @mrefcomma{equal} and @mrefdot{notequal}
562 Examples:
564 Relational expressions are evaluated to Boolean values by some functions and
565 programming constructs.
567 @c ===beg===
568 @c [x, y, z] : [123, 456, 789];
569 @c is (x < y);
570 @c maybe (y > z);
571 @c if x >= z then 1 else 0;
572 @c block ([S], S : 0, for i:1 while i <= 100 do S : S + i,
573 @c return (S));
574 @c ===end===
575 @example
576 (%i1) [x, y, z] : [123, 456, 789];
577 (%o1) [123, 456, 789]
578 (%i2) is (x < y);
579 (%o2) true
580 (%i3) maybe (y > z);
581 (%o3) false
582 (%i4) if x >= z then 1 else 0;
583 (%o4) 0
584 (%i5) block ([S], S : 0, for i:1 while i <= 100 do S : S + i,
585 return (S));
586 (%o5) 5050
587 @end example
589 Relational expressions are not otherwise evaluated or simplified to Boolean
590 values, although the arguments of relational expressions are evaluated.
592 @c ===beg===
593 @c [x, y, z] : [123, 456, 789];
594 @c [x < y, y <= z, z >= y, y > z];
595 @c map (is, %);
596 @c ===end===
597 @example
598 (%o1) [123, 456, 789]
599 (%i2) [x < y, y <= z, z >= y, y > z];
600 (%o2) [123 < 456, 456 <= 789, 789 >= 456, 456 > 789]
601 (%i3) map (is, %);
602 (%o3) [true, true, true, false]
603 @end example
605 @opencatbox{Categories:}
606 @category{Operators}
607 @closecatbox
608 @end deffn
610 @c -----------------------------------------------------------------------------
611 @node Logical operators, Operators for Equations, Relational operators, Operators
612 @section Logical operators
613 @c -----------------------------------------------------------------------------
615 @c NEEDS EXAMPLES
617 @c -----------------------------------------------------------------------------
618 @anchor{and}
619 @deffn {Operator} and
620 @ifinfo
621 @fnindex Logical conjunction
622 @end ifinfo
624 The logical conjunction operator. @code{and} is an n-ary infix operator;
625 its operands are Boolean expressions, and its result is a Boolean value.
627 @code{and} forces evaluation (like @mref{is}) of one or more operands,
628 and may force evaluation of all operands.
630 Operands are evaluated in the order in which they appear. @code{and} evaluates
631 only as many of its operands as necessary to determine the result. If any
632 operand is @code{false}, the result is @code{false} and no further operands are
633 evaluated.
635 The global flag @mref{prederror} governs the behavior of @code{and} when an
636 evaluated operand cannot be determined to be @code{true} or @code{false}.
637 @code{and} prints an error message when @code{prederror} is @code{true}.
638 Otherwise, operands which do not evaluate to @code{true} or @code{false} are
639 accepted, and the result is a Boolean expression.
641 @code{and} is not commutative: @code{a and b} might not be equal to
642 @code{b and a} due to the treatment of indeterminate operands.
644 @opencatbox{Categories:}
645 @category{Operators}
646 @closecatbox
647 @end deffn
649 @c NEEDS EXAMPLES
651 @c -----------------------------------------------------------------------------
652 @anchor{not}
653 @deffn {Operator} not
654 @ifinfo
655 @fnindex Logical negation
656 @end ifinfo
658 The logical negation operator. @code{not} is a prefix operator;
659 its operand is a Boolean expression, and its result is a Boolean value.
661 @code{not} forces evaluation (like @code{is}) of its operand.
663 The global flag @mref{prederror} governs the behavior of @code{not} when its
664 operand cannot be determined to be @code{true} or @code{false}. @code{not}
665 prints an error message when @code{prederror} is @code{true}. Otherwise,
666 operands which do not evaluate to @code{true} or @code{false} are accepted,
667 and the result is a Boolean expression.
669 @opencatbox{Categories:}
670 @category{Operators}
671 @closecatbox
672 @end deffn
674 @c NEEDS EXAMPLES
676 @c -----------------------------------------------------------------------------
677 @anchor{or}
678 @deffn {Operator} or
679 @ifinfo
680 @fnindex Logical disjunction
681 @end ifinfo
683 The logical disjunction operator. @code{or} is an n-ary infix operator;
684 its operands are Boolean expressions, and its result is a Boolean value.
686 @code{or} forces evaluation (like @mref{is}) of one or more operands,
687 and may force evaluation of all operands.
689 Operands are evaluated in the order in which they appear. @code{or} evaluates
690 only as many of its operands as necessary to determine the result. If any
691 operand is @code{true}, the result is @code{true} and no further operands are
692 evaluated.
694 The global flag @mref{prederror} governs the behavior of @code{or} when an
695 evaluated operand cannot be determined to be @code{true} or @code{false}.
696 @code{or} prints an error message when @code{prederror} is @code{true}.
697 Otherwise, operands which do not evaluate to @code{true} or @code{false} are
698 accepted, and the result is a Boolean expression.
700 @code{or} is not commutative: @code{a or b} might not be equal to @code{b or a}
701 due to the treatment of indeterminate operands.
703 @opencatbox{Categories:}
704 @category{Operators}
705 @closecatbox
706 @end deffn
708 @c -----------------------------------------------------------------------------
709 @node Operators for Equations, Assignment operators, Logical operators, Operators
710 @section Operators for Equations
711 @c -----------------------------------------------------------------------------
713 @c -----------------------------------------------------------------------------
714 @anchor{#}
715 @deffn {Operator} #
716 @ifinfo
717 @fnindex Not equal (syntactic inequality)
718 @end ifinfo
720 Represents the negation of syntactic equality @mrefdot{=}
722 Note that because of the rules for evaluation of predicate expressions
723 (in particular because @code{not @var{expr}} causes evaluation of @var{expr}),
724 @code{not @var{a} = @var{b}} is equivalent to @code{is(@var{a} # @var{b})},
725 instead of @code{@var{a} # @var{b}}.
727 Examples:
729 @c ===beg===
730 @c a = b;
731 @c is (a = b);
732 @c a # b;
733 @c not a = b;
734 @c is (a # b);
735 @c is (not a = b);
736 @c ===end===
737 @example
738 (%i1) a = b;
739 (%o1) a = b
740 (%i2) is (a = b);
741 (%o2) false
742 (%i3) a # b;
743 (%o3) a # b
744 (%i4) not a = b;
745 (%o4) true
746 (%i5) is (a # b);
747 (%o5) true
748 (%i6) is (not a = b);
749 (%o6) true
750 @end example
752 @opencatbox{Categories:}
753 @category{Operators}
754 @closecatbox
755 @end deffn
757 @c -----------------------------------------------------------------------------
758 @anchor{=}
759 @deffn {Operator} =
760 @ifinfo
761 @fnindex Equation operator
762 @fnindex Equal (syntactic equality)
763 @end ifinfo
765 The equation operator.
767 An expression @code{@var{a} = @var{b}}, by itself, represents an unevaluated
768 equation, which might or might not hold. Unevaluated equations may appear as
769 arguments to @mref{solve} and @mref{algsys} or some other functions.
771 The function @mref{is} evaluates @code{=} to a Boolean value.
772 @code{is(@var{a} = @var{b})} evaluates @code{@var{a} = @var{b}} to @code{true}
773 when @var{a} and @var{b} are identical. That is, @var{a} and @var{b} are atoms
774 which are identical, or they are not atoms and their operators are identical and
775 their arguments are identical. Otherwise, @code{is(@var{a} = @var{b})}
776 evaluates to @code{false}; it never evaluates to @code{unknown}. When
777 @code{is(@var{a} = @var{b})} is @code{true}, @var{a} and @var{b} are said to be
778 syntactically equal, in contrast to equivalent expressions, for which
779 @code{is(equal(@var{a}, @var{b}))} is @code{true}. Expressions can be
780 equivalent and not syntactically equal.
782 The negation of @code{=} is represented by @mrefdot{#}
783 As with @code{=}, an expression @code{@var{a} # @var{b}}, by itself, is not
784 evaluated. @code{is(@var{a} # @var{b})} evaluates @code{@var{a} # @var{b}} to
785 @code{true} or @code{false}.
787 In addition to @code{is}, some other operators evaluate @code{=} and @code{#}
788 to @code{true} or @code{false}, namely @mrefcomma{if} @mrefcomma{and}@w{}
789 @mrefcomma{or} and @mrefdot{not}
791 Note that because of the rules for evaluation of predicate expressions
792 (in particular because @code{not @var{expr}} causes evaluation of @var{expr}),
793 @code{not @var{a} = @var{b}} is equivalent to @code{is(@var{a} # @var{b})},
794 instead of @code{@var{a} # @var{b}}.
796 @mref{rhs} and @mref{lhs} return the right-hand and left-hand sides,
797 respectively, of an equation or inequation.
799 See also @mref{equal} and @mrefdot{notequal}
801 Examples:
803 An expression @code{@var{a} = @var{b}}, by itself, represents
804 an unevaluated equation, which might or might not hold.
806 @c ===beg===
807 @c eq_1 : a * x - 5 * y = 17;
808 @c eq_2 : b * x + 3 * y = 29;
809 @c solve ([eq_1, eq_2], [x, y]);
810 @c subst (%, [eq_1, eq_2]);
811 @c ratsimp (%);
812 @c ===end===
813 @example
814 (%i1) eq_1 : a * x - 5 * y = 17;
815 (%o1) a x - 5 y = 17
816 (%i2) eq_2 : b * x + 3 * y = 29;
817 (%o2) 3 y + b x = 29
818 (%i3) solve ([eq_1, eq_2], [x, y]);
819 196 29 a - 17 b
820 (%o3) [[x = ---------, y = -----------]]
821 5 b + 3 a 5 b + 3 a
822 (%i4) subst (%, [eq_1, eq_2]);
823 @group
824 196 a 5 (29 a - 17 b)
825 (%o4) [--------- - --------------- = 17,
826 5 b + 3 a 5 b + 3 a
827 196 b 3 (29 a - 17 b)
828 --------- + --------------- = 29]
829 5 b + 3 a 5 b + 3 a
830 @end group
831 (%i5) ratsimp (%);
832 (%o5) [17 = 17, 29 = 29]
833 @end example
835 @code{is(@var{a} = @var{b})} evaluates @code{@var{a} = @var{b}} to @code{true}
836 when @var{a} and @var{b} are syntactically equal (that is, identical).
837 Expressions can be equivalent and not syntactically equal.
839 @c ===beg===
840 @c a : (x + 1) * (x - 1);
841 @c b : x^2 - 1;
842 @c [is (a = b), is (a # b)];
843 @c [is (equal (a, b)), is (notequal (a, b))];
844 @c ===end===
845 @example
846 (%i1) a : (x + 1) * (x - 1);
847 (%o1) (x - 1) (x + 1)
848 (%i2) b : x^2 - 1;
849 2
850 (%o2) x - 1
851 (%i3) [is (a = b), is (a # b)];
852 (%o3) [false, true]
853 (%i4) [is (equal (a, b)), is (notequal (a, b))];
854 (%o4) [true, false]
855 @end example
857 Some operators evaluate @code{=} and @code{#} to @code{true} or @code{false}.
859 @c ===beg===
860 @c if expand ((x + y)^2) = x^2 + 2 * x * y + y^2 then FOO else
861 @c BAR;
862 @c eq_3 : 2 * x = 3 * x;
863 @c eq_4 : exp (2) = %e^2;
864 @c [eq_3 and eq_4, eq_3 or eq_4, not eq_3];
865 @c ===end===
866 @example
867 (%i1) if expand ((x + y)^2) = x^2 + 2 * x * y + y^2 then FOO else
868 BAR;
869 (%o1) FOO
870 (%i2) eq_3 : 2 * x = 3 * x;
871 (%o2) 2 x = 3 x
872 (%i3) eq_4 : exp (2) = %e^2;
873 2 2
874 (%o3) %e = %e
875 (%i4) [eq_3 and eq_4, eq_3 or eq_4, not eq_3];
876 (%o4) [false, true, true]
877 @end example
879 Because @code{not @var{expr}} causes evaluation of @var{expr},
880 @code{not @var{a} = @var{b}} is equivalent to @code{is(@var{a} # @var{b})}.
882 @c ===beg===
883 @c [2 * x # 3 * x, not (2 * x = 3 * x)];
884 @c is (2 * x # 3 * x);
885 @c ===end===
886 @example
887 (%i1) [2 * x # 3 * x, not (2 * x = 3 * x)];
888 (%o1) [2 x # 3 x, true]
889 (%i2) is (2 * x # 3 * x);
890 (%o2) true
891 @end example
893 @opencatbox{Categories:}
894 @category{Operators}
895 @closecatbox
896 @end deffn
898 @c -----------------------------------------------------------------------------
899 @node Assignment operators, User defined operators, Operators for Equations, Operators
900 @section Assignment operators
901 @c -----------------------------------------------------------------------------
903 @c -----------------------------------------------------------------------------
904 @anchor{:}
905 @deffn {Operator} :
906 @ifinfo
907 @fnindex Assignment operator
908 @end ifinfo
910 Assignment operator.
912 When the left-hand side is a simple variable (not subscripted), @code{:}
913 evaluates its right-hand side and associates that value with the left-hand side.
915 When the left-hand side is a subscripted element of a list, matrix, declared
916 Maxima array, or Lisp array, the right-hand side is assigned to that element.
917 The subscript must name an existing element; such objects cannot be extended by
918 naming nonexistent elements.
920 When the left-hand side is a subscripted element of a @mrefcomma{hashed array}
921 the right-hand side is assigned to that element, if it already exists,
922 or a new element is allocated, if it does not already exist.
924 When the left-hand side is a list of simple and/or subscripted variables, the
925 right-hand side must evaluate to a list, and the elements of the right-hand
926 side are assigned to the elements of the left-hand side, in parallel.
928 See also @mref{kill} and @mrefcomma{remvalue} which undo the association between
929 the left-hand side and its value.
931 Examples:
933 Assignment to a simple variable.
935 @c ===beg===
936 @c a;
937 @c a : 123;
938 @c a;
939 @c ===end===
940 @example
941 (%i1) a;
942 (%o1) a
943 (%i2) a : 123;
944 (%o2) 123
945 (%i3) a;
946 (%o3) 123
947 @end example
949 Assignment to an element of a list.
951 @c ===beg===
952 @c b : [1, 2, 3];
953 @c b[3] : 456;
954 @c b;
955 @c ===end===
956 @example
957 (%i1) b : [1, 2, 3];
958 (%o1) [1, 2, 3]
959 (%i2) b[3] : 456;
960 (%o2) 456
961 (%i3) b;
962 (%o3) [1, 2, 456]
963 @end example
965 Assignment to a variable that neither is the name of a list nor of an array
966 creates a @mrefdot{hashed array}
968 @c ===beg===
969 @c c[99] : 789;
970 @c c[99];
971 @c c;
972 @c arrayinfo (c);
973 @c listarray (c);
974 @c ===end===
975 @example
976 (%i1) c[99] : 789;
977 (%o1) 789
978 (%i2) c[99];
979 (%o2) 789
980 (%i3) c;
981 (%o3) c
982 (%i4) arrayinfo (c);
983 (%o4) [hashed, 1, [99]]
984 (%i5) listarray (c);
985 (%o5) [789]
986 @end example
988 Multiple assignment.
990 @c ===beg===
991 @c [a, b, c] : [45, 67, 89];
992 @c a;
993 @c b;
994 @c c;
995 @c ===end===
996 @example
997 (%i1) [a, b, c] : [45, 67, 89];
998 (%o1) [45, 67, 89]
999 (%i2) a;
1000 (%o2) 45
1001 (%i3) b;
1002 (%o3) 67
1003 (%i4) c;
1004 (%o4) 89
1005 @end example
1007 Multiple assignment is carried out in parallel.
1008 The values of @code{a} and @code{b} are exchanged in this example.
1010 @c ===beg===
1011 @c [a, b] : [33, 55];
1012 @c [a, b] : [b, a];
1013 @c a;
1014 @c b;
1015 @c ===end===
1016 @example
1017 (%i1) [a, b] : [33, 55];
1018 (%o1) [33, 55]
1019 (%i2) [a, b] : [b, a];
1020 (%o2) [55, 33]
1021 (%i3) a;
1022 (%o3) 55
1023 (%i4) b;
1024 (%o4) 33
1025 @end example
1027 @opencatbox{Categories:}
1028 @category{Evaluation}
1029 @category{Operators}
1030 @closecatbox
1031 @end deffn
1033 @c -----------------------------------------------------------------------------
1034 @need 900
1035 @anchor{::}
1036 @deffn {Operator} ::
1037 @ifinfo
1038 @fnindex Assignment operator (evaluates left-hand side)
1039 @end ifinfo
1041 Assignment operator.
1043 @code{::} is the same as @mref{:} (which see) except that @code{::} evaluates
1044 its left-hand side as well as its right-hand side.
1046 Examples:
1048 @c ===beg===
1049 @c x : 'foo;
1050 @c x :: 123;
1051 @c foo;
1052 @c x : '[a, b, c];
1053 @c x :: [11, 22, 33];
1054 @c a;
1055 @c b;
1056 @c c;
1057 @c ===end===
1058 @example
1059 (%i1) x : 'foo;
1060 (%o1) foo
1061 (%i2) x :: 123;
1062 (%o2) 123
1063 (%i3) foo;
1064 (%o3) 123
1065 (%i4) x : '[a, b, c];
1066 (%o4) [a, b, c]
1067 (%i5) x :: [11, 22, 33];
1068 (%o5) [11, 22, 33]
1069 (%i6) a;
1070 (%o6) 11
1071 (%i7) b;
1072 (%o7) 22
1073 (%i8) c;
1074 (%o8) 33
1075 @end example
1077 @opencatbox{Categories:}
1078 @category{Evaluation}
1079 @category{Operators}
1080 @closecatbox
1081 @end deffn
1083 @c -----------------------------------------------------------------------------
1084 @anchor{::=}
1085 @deffn {Operator} ::=
1086 @ifinfo
1087 @fnindex Macro function definition operator
1088 @end ifinfo
1090 Macro function definition operator.
1091 @code{::=} defines a function (called a "macro" for historical reasons) which
1092 quotes its arguments, and the expression which it returns (called the "macro
1093 expansion") is evaluated in the context from which the macro was called.
1094 A macro function is otherwise the same as an ordinary function.
1096 @mref{macroexpand} returns a macro expansion (without evaluating it).
1097 @code{macroexpand (foo (x))} followed by @code{''%} is equivalent to
1098 @code{foo (x)} when @code{foo} is a macro function.
1100 @code{::=} puts the name of the new macro function onto the global list
1101 @mrefdot{macros} @mrefcomma{kill} @mrefcomma{remove} and @mref{remfunction}@w{}
1102 unbind macro function definitions and remove names from @code{macros}.
1104 @mref{fundef} or @mref{dispfun} return a macro function definition or assign it
1105 to a label, respectively.
1107 Macro functions commonly contain @mref{buildq} and @mref{splice} expressions to
1108 construct an expression, which is then evaluated.
1110 Examples
1112 A macro function quotes its arguments, so message (1) shows @code{y - z}, not
1113 the value of @code{y - z}. The macro expansion (the quoted expression
1114 @code{'(print ("(2) x is equal to", x))}) is evaluated in the context from which
1115 the macro was called, printing message (2).
1117 @c ===beg===
1118 @c x: %pi$
1119 @c y: 1234$
1120 @c z: 1729 * w$
1121 @c printq1 (x) ::= block (print ("(1) x is equal to", x),
1122 @c '(print ("(2) x is equal to", x)))$
1123 @c printq1 (y - z);
1124 @c ===end===
1125 @example
1126 (%i1) x: %pi$
1127 (%i2) y: 1234$
1128 (%i3) z: 1729 * w$
1129 (%i4) printq1 (x) ::= block (print ("(1) x is equal to", x),
1130 '(print ("(2) x is equal to", x)))$
1131 (%i5) printq1 (y - z);
1132 (1) x is equal to y - z
1133 (2) x is equal to %pi
1134 (%o5) %pi
1135 @end example
1137 An ordinary function evaluates its arguments, so message (1) shows the value of
1138 @code{y - z}. The return value is not evaluated, so message (2) is not printed
1139 until the explicit evaluation @code{''%}.
1141 @c ===beg===
1142 @c x: %pi$
1143 @c y: 1234$
1144 @c z: 1729 * w$
1145 @c printe1 (x) := block (print ("(1) x is equal to", x),
1146 @c '(print ("(2) x is equal to", x)))$
1147 @c printe1 (y - z);
1148 @c ''%;
1149 @c ===end===
1150 @example
1151 (%i1) x: %pi$
1152 (%i2) y: 1234$
1153 (%i3) z: 1729 * w$
1154 (%i4) printe1 (x) := block (print ("(1) x is equal to", x),
1155 '(print ("(2) x is equal to", x)))$
1156 (%i5) printe1 (y - z);
1157 (1) x is equal to 1234 - 1729 w
1158 (%o5) print((2) x is equal to, x)
1159 (%i6) ''%;
1160 (2) x is equal to %pi
1161 (%o6) %pi
1162 @end example
1164 @code{macroexpand} returns a macro expansion.
1165 @code{macroexpand (foo (x))} followed by @code{''%} is equivalent to
1166 @code{foo (x)} when @code{foo} is a macro function.
1168 @c ===beg===
1169 @c x: %pi$
1170 @c y: 1234$
1171 @c z: 1729 * w$
1172 @c g (x) ::= buildq ([x], print ("x is equal to", x))$
1173 @c macroexpand (g (y - z));
1174 @c ''%;
1175 @c g (y - z);
1176 @c ===end===
1177 @example
1178 (%i1) x: %pi$
1179 (%i2) y: 1234$
1180 (%i3) z: 1729 * w$
1181 (%i4) g (x) ::= buildq ([x], print ("x is equal to", x))$
1182 (%i5) macroexpand (g (y - z));
1183 (%o5) print(x is equal to, y - z)
1184 (%i6) ''%;
1185 x is equal to 1234 - 1729 w
1186 (%o6) 1234 - 1729 w
1187 (%i7) g (y - z);
1188 x is equal to 1234 - 1729 w
1189 (%o7) 1234 - 1729 w
1190 @end example
1192 @opencatbox{Categories:}
1193 @category{Function definition}
1194 @category{Operators}
1195 @closecatbox
1196 @end deffn
1198 @c -----------------------------------------------------------------------------
1199 @anchor{:=}
1200 @deffn {Operator} :=
1201 @ifinfo
1202 @fnindex Function definition operator
1203 @end ifinfo
1205 The function definition operator.
1207 @code{@var{f}(@var{x_1}, ..., @var{x_n}) := @var{expr}} defines a function named
1208 @var{f} with arguments @var{x_1}, @dots{}, @var{x_n} and function body
1209 @var{expr}. @code{:=} never evaluates the function body (unless explicitly
1210 evaluated by quote-quote @code{'@w{}'}).
1211 The function body is evaluated every time the function is called.
1213 @code{@var{f}[@var{x_1}, ..., @var{x_n}] := @var{expr}} defines a so-called
1214 @mrefdot{memoizing function}
1215 Its function body is evaluated just once for each distinct value of its arguments,
1216 and that value is returned, without evaluating the function body,
1217 whenever the arguments have those values again.
1218 (A function of this kind is also known as a ``array function''.)
1220 @code{@var{f}[@var{x_1}, ..., @var{x_n}](@var{y_1}, ..., @var{y_m}) := @var{expr}}
1221 is a special case of a @mrefdot{memoizing function}
1222 @code{@var{f}[@var{x_1}, ..., @var{x_n}]} is a @mref{memoizing function} which returns a lambda expression
1223 with arguments @code{@var{y_1}, ..., @var{y_m}}.
1224 The function body is evaluated once for each distinct value of @code{@var{x_1}, ..., @var{x_n}},
1225 and the body of the lambda expression is that value.
1227 When the last or only function argument @var{x_n} is a list of one element, the
1228 function defined by @code{:=} accepts a variable number of arguments. Actual
1229 arguments are assigned one-to-one to formal arguments @var{x_1}, @dots{},
1230 @var{x_(n - 1)}, and any further actual arguments, if present, are assigned to
1231 @var{x_n} as a list.
1233 All function definitions appear in the same namespace; defining a function
1234 @code{f} within another function @code{g} does not automatically limit the scope
1235 of @code{f} to @code{g}. However, @code{local(f)} makes the definition of
1236 function @code{f} effective only within the block or other compound expression
1237 in which @mref{local} appears.
1239 If some formal argument @var{x_k} is a quoted symbol, the function defined by
1240 @code{:=} does not evaluate the corresponding actual argument. Otherwise all
1241 actual arguments are evaluated.
1243 See also @mref{define} and @mrefdot{::=}
1245 Examples:
1247 @code{:=} never evaluates the function body (unless explicitly evaluated by
1248 quote-quote).
1250 @c ===beg===
1251 @c expr : cos(y) - sin(x);
1252 @c F1 (x, y) := expr;
1253 @c F1 (a, b);
1254 @c F2 (x, y) := ''expr;
1255 @c F2 (a, b);
1256 @c ===end===
1257 @example
1258 (%i1) expr : cos(y) - sin(x);
1259 (%o1) cos(y) - sin(x)
1260 (%i2) F1 (x, y) := expr;
1261 (%o2) F1(x, y) := expr
1262 (%i3) F1 (a, b);
1263 (%o3) cos(y) - sin(x)
1264 (%i4) F2 (x, y) := ''expr;
1265 (%o4) F2(x, y) := cos(y) - sin(x)
1266 (%i5) F2 (a, b);
1267 (%o5) cos(b) - sin(a)
1268 @end example
1270 @code{f(@var{x_1}, ..., @var{x_n}) := ...} defines an ordinary function.
1272 @c ===beg===
1273 @c G1(x, y) := (print ("Evaluating G1 for x=", x, "and y=", y),
1274 @c x.y - y.x);
1275 @c G1([1, a], [2, b]);
1276 @c G1([1, a], [2, b]);
1277 @c ===end===
1278 @example
1279 (%i1) G1(x, y) := (print ("Evaluating G1 for x=", x, "and y=", y),
1280 x.y - y.x);
1281 (%o1) G1(x, y) := (print("Evaluating G1 for x=", x, "and y=",
1282 y), x . y - y . x)
1283 (%i2) G1([1, a], [2, b]);
1284 Evaluating G1 for x= [1, a] and y= [2, b]
1285 (%o2) 0
1286 (%i3) G1([1, a], [2, b]);
1287 Evaluating G1 for x= [1, a] and y= [2, b]
1288 (%o3) 0
1289 @end example
1291 @code{f[@var{x_1}, ..., @var{x_n}] := ...} defines a @mrefdot{memoizing function}
1293 @c ===beg===
1294 @c G2[a] := (print ("Evaluating G2 for a=", a), a^2);
1295 @c G2[1234];
1296 @c G2[1234];
1297 @c G2[2345];
1298 @c arrayinfo (G2);
1299 @c listarray (G2);
1300 @c ===end===
1301 @example
1302 (%i1) G2[a] := (print ("Evaluating G2 for a=", a), a^2);
1303 2
1304 (%o1) G2 := (print("Evaluating G2 for a=", a), a )
1305 a
1306 (%i2) G2[1234];
1307 Evaluating G2 for a= 1234
1308 (%o2) 1522756
1309 (%i3) G2[1234];
1310 (%o3) 1522756
1311 (%i4) G2[2345];
1312 Evaluating G2 for a= 2345
1313 (%o4) 5499025
1314 (%i5) arrayinfo (G2);
1315 (%o5) [hashed, 1, [1234], [2345]]
1316 (%i6) listarray (G2);
1317 (%o6) [1522756, 5499025]
1318 @end example
1320 @code{@var{f}[@var{x_1}, ..., @var{x_n}](@var{y_1}, ..., @var{y_m}) := @var{expr}}
1321 is a special case of a @mrefdot{memoizing function}
1323 @c ===beg===
1324 @c G3[n](x) := (print ("Evaluating G3 for n=", n), diff (sin(x)^2,
1325 @c x, n));
1326 @c G3[2];
1327 @c G3[2];
1328 @c G3[2](1);
1329 @c arrayinfo (G3);
1330 @c listarray (G3);
1331 @c ===end===
1332 @example
1333 (%i1) G3[n](x) := (print ("Evaluating G3 for n=", n), diff (sin(x)^2,
1334 x, n));
1335 (%o1) G3 (x) := (print("Evaluating G3 for n=", n),
1336 n
1337 2
1338 diff(sin (x), x, n))
1339 (%i2) G3[2];
1340 Evaluating G3 for n= 2
1341 2 2
1342 (%o2) lambda([x], 2 cos (x) - 2 sin (x))
1343 (%i3) G3[2];
1344 2 2
1345 (%o3) lambda([x], 2 cos (x) - 2 sin (x))
1346 (%i4) G3[2](1);
1347 2 2
1348 (%o4) 2 cos (1) - 2 sin (1)
1349 (%i5) arrayinfo (G3);
1350 (%o5) [hashed, 1, [2]]
1351 (%i6) listarray (G3);
1352 2 2
1353 (%o6) [lambda([x], 2 cos (x) - 2 sin (x))]
1354 @end example
1356 When the last or only function argument @var{x_n} is a list of one element,
1357 the function defined by @code{:=} accepts a variable number of arguments.
1359 @c ===beg===
1360 @c H ([L]) := apply ("+", L);
1361 @c H (a, b, c);
1362 @c ===end===
1363 @example
1364 (%i1) H ([L]) := apply ("+", L);
1365 (%o1) H([L]) := apply("+", L)
1366 (%i2) H (a, b, c);
1367 (%o2) c + b + a
1368 @end example
1370 @code{local} makes a local function definition.
1372 @c ===beg===
1373 @c foo (x) := 1 - x;
1374 @c foo (100);
1375 @c block (local (foo), foo (x) := 2 * x, foo (100));
1376 @c foo (100);
1377 @c ===end===
1378 @example
1379 (%i1) foo (x) := 1 - x;
1380 (%o1) foo(x) := 1 - x
1381 (%i2) foo (100);
1382 (%o2) - 99
1383 (%i3) block (local (foo), foo (x) := 2 * x, foo (100));
1384 (%o3) 200
1385 (%i4) foo (100);
1386 (%o4) - 99
1387 @end example
1389 @opencatbox{Categories:}
1390 @category{Function definition}
1391 @category{Operators}
1392 @closecatbox
1393 @end deffn
1395 @c -----------------------------------------------------------------------------
1396 @node User defined operators, , Assignment operators, Operators
1397 @section User defined operators
1398 @c -----------------------------------------------------------------------------
1400 @c -----------------------------------------------------------------------------
1401 @anchor{infix}
1402 @deffn {Function} infix @
1403 @fname{infix} (@var{op}) @
1404 @fname{infix} (@var{op}, @var{lbp}, @var{rbp}) @
1405 @fname{infix} (@var{op}, @var{lbp}, @var{rbp}, @var{lpos}, @var{rpos}, @var{pos})
1407 Declares @var{op} to be an infix operator. An infix operator is a function of
1408 two arguments, with the name of the function written between the arguments.
1409 For example, the subtraction operator @code{-} is an infix operator.
1411 @code{infix (@var{op})} declares @var{op} to be an infix operator with default
1412 binding powers (left and right both equal to 180) and parts of speech (left and
1413 right both equal to @code{any}).
1414 @c HOW IS pos DIFFERENT FROM lpos AND rpos ??
1416 @code{infix (@var{op}, @var{lbp}, @var{rbp})} declares @var{op} to be an infix
1417 operator with stated left and right binding powers and default parts of speech
1418 (left and right both equal to @code{any}).
1420 @code{infix (@var{op}, @var{lbp}, @var{rbp}, @var{lpos}, @var{rpos}, @var{pos})}
1421 declares @var{op} to be an infix operator with stated left and right binding
1422 powers and parts of speech @var{lpos}, @var{rpos}, and @var{pos} for the left
1423 operand, the right operand, and the operator result, respectively.
1425 "Part of speech", in reference to operator declarations, means expression type.
1426 Three types are recognized: @code{expr}, @code{clause}, and @code{any},
1427 indicating an algebraic expression, a Boolean expression, or any kind of
1428 expression, respectively. Maxima can detect some syntax errors by comparing the
1429 declared part of speech to an actual expression.
1431 The precedence of @var{op} with respect to other operators derives from the left
1432 and right binding powers of the operators in question. If the left and right
1433 binding powers of @var{op} are both greater the left and right binding powers of
1434 some other operator, then @var{op} takes precedence over the other operator.
1435 If the binding powers are not both greater or less, some more complicated
1436 relation holds.
1438 The associativity of @var{op} depends on its binding powers. Greater left
1439 binding power (@var{lbp}) implies an instance of @var{op} is evaluated before
1440 other operators to its left in an expression, while greater right binding power
1441 (@var{rbp}) implies an instance of @var{op} is evaluated before other operators
1442 to its right in an expression. Thus greater @var{lbp} makes @var{op}
1443 right-associative, while greater @var{rbp} makes @var{op} left-associative.
1444 If @var{lbp} is equal to @var{rbp}, @var{op} is left-associative.
1446 See also @ref{Introduction to operators}.
1448 Examples:
1450 If the left and right binding powers of @var{op} are both greater
1451 the left and right binding powers of some other operator,
1452 then @var{op} takes precedence over the other operator.
1454 @c ===beg===
1455 @c :lisp (get '$+ 'lbp)
1456 @c :lisp (get '$+ 'rbp)
1457 @c infix ("##", 101, 101);
1458 @c "##"(a, b) := sconcat("(", a, ",", b, ")");
1459 @c 1 + a ## b + 2;
1460 @c infix ("##", 99, 99);
1461 @c 1 + a ## b + 2;
1462 @c ===end===
1463 @example
1464 (%i1) :lisp (get '$+ 'lbp)
1465 100
1466 (%i1) :lisp (get '$+ 'rbp)
1467 100
1468 (%i1) infix ("##", 101, 101);
1469 (%o1) ##
1470 (%i2) "##"(a, b) := sconcat("(", a, ",", b, ")");
1471 (%o2) (a ## b) := sconcat("(", a, ",", b, ")")
1472 (%i3) 1 + a ## b + 2;
1473 (%o3) (a,b) + 3
1474 (%i4) infix ("##", 99, 99);
1475 (%o4) ##
1476 (%i5) 1 + a ## b + 2;
1477 (%o5) (a+1,b+2)
1478 @end example
1480 Greater @var{lbp} makes @var{op} right-associative,
1481 while greater @var{rbp} makes @var{op} left-associative.
1483 @c ===beg===
1484 @c infix ("##", 100, 99);
1485 @c "##"(a, b) := sconcat("(", a, ",", b, ")")$
1486 @c foo ## bar ## baz;
1487 @c infix ("##", 100, 101);
1488 @c foo ## bar ## baz;
1489 @c ===end===
1490 @example
1491 (%i1) infix ("##", 100, 99);
1492 (%o1) ##
1493 (%i2) "##"(a, b) := sconcat("(", a, ",", b, ")")$
1494 (%i3) foo ## bar ## baz;
1495 (%o3) (foo,(bar,baz))
1496 (%i4) infix ("##", 100, 101);
1497 (%o4) ##
1498 (%i5) foo ## bar ## baz;
1499 (%o5) ((foo,bar),baz)
1500 @end example
1502 Maxima can detect some syntax errors by comparing the
1503 declared part of speech to an actual expression.
1505 @c ===beg===
1506 @c infix ("##", 100, 99, expr, expr, expr);
1507 @c if x ## y then 1 else 0;
1508 @c infix ("##", 100, 99, expr, expr, clause);
1509 @c if x ## y then 1 else 0;
1510 @c ===end===
1511 @example
1512 (%i1) infix ("##", 100, 99, expr, expr, expr);
1513 (%o1) ##
1514 (%i2) if x ## y then 1 else 0;
1515 Incorrect syntax: Found algebraic expression where logical
1516 expression expected
1517 if x ## y then
1518 ^
1519 (%i2) infix ("##", 100, 99, expr, expr, clause);
1520 (%o2) ##
1521 (%i3) if x ## y then 1 else 0;
1522 (%o3) if x ## y then 1 else 0
1523 @end example
1525 @opencatbox{Categories:}
1526 @category{Operators}
1527 @category{Declarations and inferences}
1528 @category{Syntax}
1529 @closecatbox
1530 @end deffn
1532 @c -----------------------------------------------------------------------------
1533 @anchor{matchfix}
1534 @deffn {Function} matchfix @
1535 @fname{matchfix} (@var{ldelimiter}, @var{rdelimiter}) @
1536 @fname{matchfix} (@var{ldelimiter}, @var{rdelimiter}, @var{arg_pos}, @var{pos})
1538 Declares a matchfix operator with left and right delimiters @var{ldelimiter}
1539 and @var{rdelimiter}. The delimiters are specified as strings.
1541 A "matchfix" operator is a function of any number of arguments,
1542 such that the arguments occur between matching left and right delimiters.
1543 The delimiters may be any strings, so long as the parser can
1544 distinguish the delimiters from the operands
1545 and other expressions and operators.
1546 In practice this rules out unparseable delimiters such as
1547 @code{%}, @code{,}, @code{$} and @code{;},
1548 and may require isolating the delimiters with white space.
1549 The right delimiter can be the same or different from the left delimiter.
1551 A left delimiter can be associated with only one right delimiter;
1552 two different matchfix operators cannot have the same left delimiter.
1554 An existing operator may be redeclared as a matchfix operator
1555 without changing its other properties.
1556 In particular, built-in operators such as addition @code{+} can
1557 be declared matchfix,
1558 but operator functions cannot be defined for built-in operators.
1560 The command @code{matchfix (@var{ldelimiter}, @var{rdelimiter}, @var{arg_pos},
1561 @var{pos})} declares the argument part-of-speech @var{arg_pos} and result
1562 part-of-speech @var{pos}, and the delimiters @var{ldelimiter} and
1563 @var{rdelimiter}.
1565 "Part of speech", in reference to operator declarations, means expression type.
1566 Three types are recognized: @code{expr}, @code{clause}, and @code{any},
1567 indicating an algebraic expression, a Boolean expression, or any kind of
1568 expression, respectively.
1569 Maxima can detect some syntax errors by comparing the
1570 declared part of speech to an actual expression.
1572 @c DUNNO IF WE REALLY NEED TO MENTION BINDING POWER HERE -- AS NOTED IT'S IRRELEVANT
1573 @c An operator declared by @code{matchfix} is assigned a low binding power.
1574 @c Since a matchfix operator must be evaluated before any expression
1575 @c which contains it,
1576 @c binding power is effectively irrelevant
1577 @c to the declaration of a matchfix operator.
1579 The function to carry out a matchfix operation is an ordinary
1580 user-defined function.
1581 The operator function is defined
1582 in the usual way
1583 with the function definition operator @code{:=} or @code{define}.
1584 The arguments may be written between the delimiters,
1585 or with the left delimiter as a quoted string and the arguments
1586 following in parentheses.
1587 @code{dispfun (@var{ldelimiter})} displays the function definition.
1589 The only built-in matchfix operator is the list constructor @code{[ ]}.
1590 Parentheses @code{( )} and double-quotes @code{" "}
1591 act like matchfix operators,
1592 but are not treated as such by the Maxima parser.
1594 @code{matchfix} evaluates its arguments.
1595 @code{matchfix} returns its first argument, @var{ldelimiter}.
1596 @c HOW TO TAKE AWAY THE MATCHFIX PROPERTY ??
1598 Examples:
1600 Delimiters may be almost any strings.
1602 @c ===beg===
1603 @c matchfix ("@@", "~");
1604 @c @@ a, b, c ~;
1605 @c matchfix (">>", "<<");
1606 @c >> a, b, c <<;
1607 @c matchfix ("foo", "oof");
1608 @c foo a, b, c oof;
1609 @c >> w + foo x, y oof + z << / @@ p, q ~;
1610 @c ===end===
1611 @example
1612 (%i1) matchfix ("@@@@", "~");
1613 (%o1) @@@@
1614 (%i2) @@@@ a, b, c ~;
1615 (%o2) @@@@a, b, c~
1616 (%i3) matchfix (">>", "<<");
1617 (%o3) >>
1618 (%i4) >> a, b, c <<;
1619 (%o4) >>a, b, c<<
1620 (%i5) matchfix ("foo", "oof");
1621 (%o5) foo
1622 (%i6) foo a, b, c oof;
1623 (%o6) fooa, b, coof
1624 (%i7) >> w + foo x, y oof + z << / @@@@ p, q ~;
1625 >>z + foox, yoof + w<<
1626 (%o7) ----------------------
1627 @@@@p, q~
1628 @end example
1630 Matchfix operators are ordinary user-defined functions.
1632 @example
1633 (%i1) matchfix ("!-", "-!");
1634 (%o1) "!-"
1635 (%i2) !- x, y -! := x/y - y/x;
1636 x y
1637 (%o2) !-x, y-! := - - -
1638 y x
1639 (%i3) define (!-x, y-!, x/y - y/x);
1640 x y
1641 (%o3) !-x, y-! := - - -
1642 y x
1643 (%i4) define ("!-" (x, y), x/y - y/x);
1644 x y
1645 (%o4) !-x, y-! := - - -
1646 y x
1647 (%i5) dispfun ("!-");
1648 x y
1649 (%t5) !-x, y-! := - - -
1650 y x
1652 (%o5) done
1653 (%i6) !-3, 5-!;
1654 16
1655 (%o6) - --
1656 15
1657 (%i7) "!-" (3, 5);
1658 16
1659 (%o7) - --
1660 15
1661 @end example
1663 @opencatbox{Categories:}
1664 @category{Syntax}
1665 @category{Operators}
1666 @closecatbox
1667 @end deffn
1669 @c -----------------------------------------------------------------------------
1670 @anchor{function_nary}
1671 @deffn {Function} nary @
1672 @fname{nary} (@var{op}) @
1673 @fname{nary} (@var{op}, @var{bp}, @var{arg_pos}, @var{pos})
1675 An @code{nary} operator is used to denote a function of any number of arguments,
1676 each of which is separated by an occurrence of the operator, e.g. A+B or A+B+C.
1677 The @code{nary("x")} function is a syntax extension function to declare @code{x}
1678 to be an @code{nary} operator. Functions may be declared to be @code{nary}. If
1679 @code{declare(j,nary);} is done, this tells the simplifier to simplify, e.g.
1680 @code{j(j(a,b),j(c,d))} to @code{j(a, b, c, d)}.
1682 See also @ref{Introduction to operators}.
1684 @opencatbox{Categories:}
1685 @category{Operators}
1686 @category{Syntax}
1687 @closecatbox
1688 @end deffn
1690 @c -----------------------------------------------------------------------------
1691 @anchor{nofix}
1692 @deffn {Function} nofix @
1693 @fname{nofix} (@var{op}) @
1694 @fname{nofix} (@var{op}, @var{pos})
1696 @code{nofix} operators are used to denote functions of no arguments.
1697 The mere presence of such an operator in a command will cause the
1698 corresponding function to be evaluated. For example, when one types
1699 "exit;" to exit from a Maxima break, "exit" is behaving similar to a
1700 @code{nofix} operator. The function @code{nofix("x")} is a syntax extension
1701 function which declares @code{x} to be a @code{nofix} operator.
1703 See also @ref{Introduction to operators}.
1705 @opencatbox{Categories:}
1706 @category{Operators}
1707 @category{Syntax}
1708 @closecatbox
1709 @end deffn
1711 @c -----------------------------------------------------------------------------
1712 @anchor{postfix}
1713 @deffn {Function} postfix @
1714 @fname{postfix} (@var{op}) @
1715 @fname{postfix} (@var{op}, @var{lbp}, @var{lpos}, @var{pos})
1717 @code{postfix} operators like the @code{prefix} variety denote functions of a
1718 single argument, but in this case the argument immediately precedes an
1719 occurrence of the operator in the input string, e.g. 3!. The
1720 @code{postfix("x")} function is a syntax extension function to declare @code{x}
1721 to be a @code{postfix} operator.
1723 See also @ref{Introduction to operators}.
1725 @opencatbox{Categories:}
1726 @category{Operators}
1727 @category{Syntax}
1728 @closecatbox
1729 @end deffn
1731 @c -----------------------------------------------------------------------------
1732 @anchor{prefix}
1733 @deffn {Function} prefix @
1734 @fname{prefix} (@var{op}) @
1735 @fname{prefix} (@var{op}, @var{rbp}, @var{rpos}, @var{pos})
1737 A @code{prefix} operator is one which signifies a function of one argument,
1738 which argument immediately follows an occurrence of the operator.
1739 @code{prefix("x")} is a syntax extension function to declare @code{x} to be a
1740 @code{prefix} operator.
1742 See also @ref{Introduction to operators}.
1744 @opencatbox{Categories:}
1745 @category{Operators}
1746 @category{Syntax}
1747 @closecatbox
1748 @end deffn