| blob | 751aaa3e94b0f450c3778b98e8b42426bd533605 |
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 @fnindex Noncommutative exponentiation
450 @deffn {Operator} ^^
452 Noncommutative exponentiation operator.
453 @code{^^} is the exponentiation operator corresponding to noncommutative
454 multiplication @code{.}, just as the ordinary exponentiation operator @code{^}
455 corresponds to commutative multiplication @code{*}.
457 Noncommutative exponentiation is displayed by @code{^^} in 1-dimensional output,
458 and by placing the exponent as a superscript within angle brackets @code{< >}
459 in 2-dimensional output.
461 Examples:
463 @c ===beg===
464 @c a . a . b . b . b + a * a * a * b * b;
465 @c string (a . a . b . b . b + a * a * a * b * b);
466 @c ===end===
467 @example
468 (%i1) a . a . b . b . b + a * a * a * b * b;
469 3 2 <2> <3>
470 (%o1) a b + a . b
471 (%i2) string (a . a . b . b . b + a * a * a * b * b);
472 (%o2) a^3*b^2+a^^2 . b^^3
473 @end example
475 @opencatbox{Categories:}
476 @category{Operators}
477 @closecatbox
478 @end deffn
480 @c -----------------------------------------------------------------------------
481 @anchor{.}
482 @deffn {Operator} .
484 The dot operator, for matrix (non-commutative) multiplication.
485 When @code{"."} is used in this way, spaces should be left on both sides of
486 it, e.g. @code{A . B} This distinguishes it plainly from a decimal point in
487 a floating point number.
489 See also
490 @mrefcomma{Dot}
491 @mrefcomma{dot0nscsimp}
492 @mrefcomma{dot0simp}
493 @mrefcomma{dot1simp}
494 @mrefcomma{dotassoc}
495 @mrefcomma{dotconstrules}
496 @mrefcomma{dotdistrib}
497 @mrefcomma{dotexptsimp}
498 @mrefcomma{dotident}
499 and
500 @mrefdot{dotscrules}
502 @opencatbox{Categories:}
503 @category{Operators}
504 @closecatbox
505 @end deffn
507 @c -----------------------------------------------------------------------------
508 @node Relational operators, Logical operators, Arithmetic operators, Operators
509 @section Relational operators
510 @c -----------------------------------------------------------------------------
512 @c -----------------------------------------------------------------------------
513 @anchor{<}
514 @anchor{<=}
515 @anchor{>=}
516 @anchor{>}
517 @fnindex Less than
518 @fnindex Less than or equal
519 @fnindex Greater than or equal
520 @fnindex Greater than
522 @deffn {Operator} <
523 @deffnx {Operator} <=
524 @deffnx {Operator} >=
525 @deffnx {Operator} >
527 The symbols @code{<} @code{<=} @code{>=} and @code{>} represent less than, less
528 than or equal, greater than or equal, and greater than, respectively. The names
529 of these operators are @code{"<"} @code{"<="} @code{">="} and @code{">"}, which
530 may appear where the name of a function or operator is required.
532 These relational operators are all binary operators; constructs such as
533 @code{a < b < c} are not recognized by Maxima.
535 Relational expressions are evaluated to Boolean values by the functions
536 @mref{is} and @mrefcomma{maybe} and the programming constructs
537 @mrefcomma{if} @mrefcomma{while} and @mrefdot{unless} Relational expressions
538 are not otherwise evaluated or simplified to Boolean values, although the
539 arguments of relational expressions are evaluated (when evaluation is not
540 otherwise prevented by quotation).
542 When a relational expression cannot be evaluated to @code{true} or @code{false},
543 the behavior of @code{is} and @code{if} are governed by the global flag
544 @mrefdot{prederror} When @code{prederror} is @code{true}, @code{is} and
545 @code{if} trigger an error. When @code{prederror} is @code{false}, @code{is}
546 returns @code{unknown}, and @code{if} returns a partially-evaluated conditional
547 expression.
549 @code{maybe} always behaves as if @code{prederror} were @code{false}, and
550 @code{while} and @code{unless} always behave as if @code{prederror} were
551 @code{true}.
553 Relational operators do not distribute over lists or other aggregates.
555 See also @mrefcomma{=} @mrefcomma{#} @mrefcomma{equal} and @mrefdot{notequal}
557 Examples:
559 Relational expressions are evaluated to Boolean values by some functions and
560 programming constructs.
562 @c ===beg===
563 @c [x, y, z] : [123, 456, 789];
564 @c is (x < y);
565 @c maybe (y > z);
566 @c if x >= z then 1 else 0;
567 @c block ([S], S : 0, for i:1 while i <= 100 do S : S + i,
568 @c return (S));
569 @c ===end===
570 @example
571 (%i1) [x, y, z] : [123, 456, 789];
572 (%o1) [123, 456, 789]
573 (%i2) is (x < y);
574 (%o2) true
575 (%i3) maybe (y > z);
576 (%o3) false
577 (%i4) if x >= z then 1 else 0;
578 (%o4) 0
579 (%i5) block ([S], S : 0, for i:1 while i <= 100 do S : S + i,
580 return (S));
581 (%o5) 5050
582 @end example
584 Relational expressions are not otherwise evaluated or simplified to Boolean
585 values, although the arguments of relational expressions are evaluated.
587 @c ===beg===
588 @c [x, y, z] : [123, 456, 789];
589 @c [x < y, y <= z, z >= y, y > z];
590 @c map (is, %);
591 @c ===end===
592 @example
593 (%o1) [123, 456, 789]
594 (%i2) [x < y, y <= z, z >= y, y > z];
595 (%o2) [123 < 456, 456 <= 789, 789 >= 456, 456 > 789]
596 (%i3) map (is, %);
597 (%o3) [true, true, true, false]
598 @end example
600 @opencatbox{Categories:}
601 @category{Operators}
602 @closecatbox
603 @end deffn
605 @c -----------------------------------------------------------------------------
606 @node Logical operators, Operators for Equations, Relational operators, Operators
607 @section Logical operators
608 @c -----------------------------------------------------------------------------
610 @c NEEDS EXAMPLES
612 @c -----------------------------------------------------------------------------
613 @anchor{and}
614 @fnindex Logical conjunction
615 @deffn {Operator} and
617 The logical conjunction operator. @code{and} is an n-ary infix operator;
618 its operands are Boolean expressions, and its result is a Boolean value.
620 @code{and} forces evaluation (like @mref{is}) of one or more operands,
621 and may force evaluation of all operands.
623 Operands are evaluated in the order in which they appear. @code{and} evaluates
624 only as many of its operands as necessary to determine the result. If any
625 operand is @code{false}, the result is @code{false} and no further operands are
626 evaluated.
628 The global flag @mref{prederror} governs the behavior of @code{and} when an
629 evaluated operand cannot be determined to be @code{true} or @code{false}.
630 @code{and} prints an error message when @code{prederror} is @code{true}.
631 Otherwise, operands which do not evaluate to @code{true} or @code{false} are
632 accepted, and the result is a Boolean expression.
634 @code{and} is not commutative: @code{a and b} might not be equal to
635 @code{b and a} due to the treatment of indeterminate operands.
637 @opencatbox{Categories:}
638 @category{Operators}
639 @closecatbox
640 @end deffn
642 @c NEEDS EXAMPLES
644 @c -----------------------------------------------------------------------------
645 @anchor{not}
646 @fnindex Logical negation
647 @deffn {Operator} not
649 The logical negation operator. @code{not} is a prefix operator;
650 its operand is a Boolean expression, and its result is a Boolean value.
652 @code{not} forces evaluation (like @code{is}) of its operand.
654 The global flag @mref{prederror} governs the behavior of @code{not} when its
655 operand cannot be determined to be @code{true} or @code{false}. @code{not}
656 prints an error message when @code{prederror} is @code{true}. Otherwise,
657 operands which do not evaluate to @code{true} or @code{false} are accepted,
658 and the result is a Boolean expression.
660 @opencatbox{Categories:}
661 @category{Operators}
662 @closecatbox
663 @end deffn
665 @c NEEDS EXAMPLES
667 @c -----------------------------------------------------------------------------
668 @anchor{or}
669 @fnindex Logical disjunction
670 @deffn {Operator} or
672 The logical disjunction operator. @code{or} is an n-ary infix operator;
673 its operands are Boolean expressions, and its result is a Boolean value.
675 @code{or} forces evaluation (like @mref{is}) of one or more operands,
676 and may force evaluation of all operands.
678 Operands are evaluated in the order in which they appear. @code{or} evaluates
679 only as many of its operands as necessary to determine the result. If any
680 operand is @code{true}, the result is @code{true} and no further operands are
681 evaluated.
683 The global flag @mref{prederror} governs the behavior of @code{or} when an
684 evaluated operand cannot be determined to be @code{true} or @code{false}.
685 @code{or} prints an error message when @code{prederror} is @code{true}.
686 Otherwise, operands which do not evaluate to @code{true} or @code{false} are
687 accepted, and the result is a Boolean expression.
689 @code{or} is not commutative: @code{a or b} might not be equal to @code{b or a}
690 due to the treatment of indeterminate operands.
692 @opencatbox{Categories:}
693 @category{Operators}
694 @closecatbox
695 @end deffn
697 @c -----------------------------------------------------------------------------
698 @node Operators for Equations, Assignment operators, Logical operators, Operators
699 @section Operators for Equations
700 @c -----------------------------------------------------------------------------
702 @c -----------------------------------------------------------------------------
703 @anchor{#}
704 @fnindex Not equal (syntactic inequality)
705 @deffn {Operator} #
707 Represents the negation of syntactic equality @mrefdot{=}
709 Note that because of the rules for evaluation of predicate expressions
710 (in particular because @code{not @var{expr}} causes evaluation of @var{expr}),
711 @code{not @var{a} = @var{b}} is equivalent to @code{is(@var{a} # @var{b})},
712 instead of @code{@var{a} # @var{b}}.
714 Examples:
716 @c ===beg===
717 @c a = b;
718 @c is (a = b);
719 @c a # b;
720 @c not a = b;
721 @c is (a # b);
722 @c is (not a = b);
723 @c ===end===
724 @example
725 (%i1) a = b;
726 (%o1) a = b
727 (%i2) is (a = b);
728 (%o2) false
729 (%i3) a # b;
730 (%o3) a # b
731 (%i4) not a = b;
732 (%o4) true
733 (%i5) is (a # b);
734 (%o5) true
735 (%i6) is (not a = b);
736 (%o6) true
737 @end example
739 @opencatbox{Categories:}
740 @category{Operators}
741 @closecatbox
742 @end deffn
744 @c -----------------------------------------------------------------------------
745 @anchor{=}
746 @fnindex Equation operator
747 @fnindex Equal (syntactic equality)
748 @deffn {Operator} =
750 The equation operator.
752 An expression @code{@var{a} = @var{b}}, by itself, represents an unevaluated
753 equation, which might or might not hold. Unevaluated equations may appear as
754 arguments to @mref{solve} and @mref{algsys} or some other functions.
756 The function @mref{is} evaluates @code{=} to a Boolean value.
757 @code{is(@var{a} = @var{b})} evaluates @code{@var{a} = @var{b}} to @code{true}
758 when @var{a} and @var{b} are identical. That is, @var{a} and @var{b} are atoms
759 which are identical, or they are not atoms and their operators are identical and
760 their arguments are identical. Otherwise, @code{is(@var{a} = @var{b})}
761 evaluates to @code{false}; it never evaluates to @code{unknown}. When
762 @code{is(@var{a} = @var{b})} is @code{true}, @var{a} and @var{b} are said to be
763 syntactically equal, in contrast to equivalent expressions, for which
764 @code{is(equal(@var{a}, @var{b}))} is @code{true}. Expressions can be
765 equivalent and not syntactically equal.
767 The negation of @code{=} is represented by @mrefdot{#}
768 As with @code{=}, an expression @code{@var{a} # @var{b}}, by itself, is not
769 evaluated. @code{is(@var{a} # @var{b})} evaluates @code{@var{a} # @var{b}} to
770 @code{true} or @code{false}.
772 In addition to @code{is}, some other operators evaluate @code{=} and @code{#}
773 to @code{true} or @code{false}, namely @mrefcomma{if} @mrefcomma{and}@w{}
774 @mrefcomma{or} and @mrefdot{not}
776 Note that because of the rules for evaluation of predicate expressions
777 (in particular because @code{not @var{expr}} causes evaluation of @var{expr}),
778 @code{not @var{a} = @var{b}} is equivalent to @code{is(@var{a} # @var{b})},
779 instead of @code{@var{a} # @var{b}}.
781 @mref{rhs} and @mref{lhs} return the right-hand and left-hand sides,
782 respectively, of an equation or inequation.
784 See also @mref{equal} and @mrefdot{notequal}
786 Examples:
788 An expression @code{@var{a} = @var{b}}, by itself, represents
789 an unevaluated equation, which might or might not hold.
791 @c ===beg===
792 @c eq_1 : a * x - 5 * y = 17;
793 @c eq_2 : b * x + 3 * y = 29;
794 @c solve ([eq_1, eq_2], [x, y]);
795 @c subst (%, [eq_1, eq_2]);
796 @c ratsimp (%);
797 @c ===end===
798 @example
799 (%i1) eq_1 : a * x - 5 * y = 17;
800 (%o1) a x - 5 y = 17
801 (%i2) eq_2 : b * x + 3 * y = 29;
802 (%o2) 3 y + b x = 29
803 (%i3) solve ([eq_1, eq_2], [x, y]);
804 196 29 a - 17 b
805 (%o3) [[x = ---------, y = -----------]]
806 5 b + 3 a 5 b + 3 a
807 (%i4) subst (%, [eq_1, eq_2]);
808 @group
809 196 a 5 (29 a - 17 b)
810 (%o4) [--------- - --------------- = 17,
811 5 b + 3 a 5 b + 3 a
812 196 b 3 (29 a - 17 b)
813 --------- + --------------- = 29]
814 5 b + 3 a 5 b + 3 a
815 @end group
816 (%i5) ratsimp (%);
817 (%o5) [17 = 17, 29 = 29]
818 @end example
820 @code{is(@var{a} = @var{b})} evaluates @code{@var{a} = @var{b}} to @code{true}
821 when @var{a} and @var{b} are syntactically equal (that is, identical).
822 Expressions can be equivalent and not syntactically equal.
824 @c ===beg===
825 @c a : (x + 1) * (x - 1);
826 @c b : x^2 - 1;
827 @c [is (a = b), is (a # b)];
828 @c [is (equal (a, b)), is (notequal (a, b))];
829 @c ===end===
830 @example
831 (%i1) a : (x + 1) * (x - 1);
832 (%o1) (x - 1) (x + 1)
833 (%i2) b : x^2 - 1;
834 2
835 (%o2) x - 1
836 (%i3) [is (a = b), is (a # b)];
837 (%o3) [false, true]
838 (%i4) [is (equal (a, b)), is (notequal (a, b))];
839 (%o4) [true, false]
840 @end example
842 Some operators evaluate @code{=} and @code{#} to @code{true} or @code{false}.
844 @c ===beg===
845 @c if expand ((x + y)^2) = x^2 + 2 * x * y + y^2 then FOO else
846 @c BAR;
847 @c eq_3 : 2 * x = 3 * x;
848 @c eq_4 : exp (2) = %e^2;
849 @c [eq_3 and eq_4, eq_3 or eq_4, not eq_3];
850 @c ===end===
851 @example
852 (%i1) if expand ((x + y)^2) = x^2 + 2 * x * y + y^2 then FOO else
853 BAR;
854 (%o1) FOO
855 (%i2) eq_3 : 2 * x = 3 * x;
856 (%o2) 2 x = 3 x
857 (%i3) eq_4 : exp (2) = %e^2;
858 2 2
859 (%o3) %e = %e
860 (%i4) [eq_3 and eq_4, eq_3 or eq_4, not eq_3];
861 (%o4) [false, true, true]
862 @end example
864 Because @code{not @var{expr}} causes evaluation of @var{expr},
865 @code{not @var{a} = @var{b}} is equivalent to @code{is(@var{a} # @var{b})}.
867 @c ===beg===
868 @c [2 * x # 3 * x, not (2 * x = 3 * x)];
869 @c is (2 * x # 3 * x);
870 @c ===end===
871 @example
872 (%i1) [2 * x # 3 * x, not (2 * x = 3 * x)];
873 (%o1) [2 x # 3 x, true]
874 (%i2) is (2 * x # 3 * x);
875 (%o2) true
876 @end example
878 @opencatbox{Categories:}
879 @category{Operators}
880 @closecatbox
881 @end deffn
883 @c -----------------------------------------------------------------------------
884 @node Assignment operators, User defined operators, Operators for Equations, Operators
885 @section Assignment operators
886 @c -----------------------------------------------------------------------------
888 @c -----------------------------------------------------------------------------
889 @anchor{:}
890 @fnindex Assignment operator
891 @deffn {Operator} :
893 Assignment operator.
895 When the left-hand side is a simple variable (not subscripted), @code{:}
896 evaluates its right-hand side and associates that value with the left-hand side.
898 When the left-hand side is a subscripted element of a list, matrix, declared
899 Maxima array, or Lisp array, the right-hand side is assigned to that element.
900 The subscript must name an existing element; such objects cannot be extended by
901 naming nonexistent elements.
903 When the left-hand side is a subscripted element of a @mrefcomma{hashed array}
904 the right-hand side is assigned to that element, if it already exists,
905 or a new element is allocated, if it does not already exist.
907 When the left-hand side is a list of simple and/or subscripted variables, the
908 right-hand side must evaluate to a list, and the elements of the right-hand
909 side are assigned to the elements of the left-hand side, in parallel.
911 See also @mref{kill} and @mrefcomma{remvalue} which undo the association between
912 the left-hand side and its value.
914 Examples:
916 Assignment to a simple variable.
918 @c ===beg===
919 @c a;
920 @c a : 123;
921 @c a;
922 @c ===end===
923 @example
924 (%i1) a;
925 (%o1) a
926 (%i2) a : 123;
927 (%o2) 123
928 (%i3) a;
929 (%o3) 123
930 @end example
932 Assignment to an element of a list.
934 @c ===beg===
935 @c b : [1, 2, 3];
936 @c b[3] : 456;
937 @c b;
938 @c ===end===
939 @example
940 (%i1) b : [1, 2, 3];
941 (%o1) [1, 2, 3]
942 (%i2) b[3] : 456;
943 (%o2) 456
944 (%i3) b;
945 (%o3) [1, 2, 456]
946 @end example
948 Assignment to a variable that neither is the name of a list nor of an array
949 creates a @mrefdot{hashed array}
951 @c ===beg===
952 @c c[99] : 789;
953 @c c[99];
954 @c c;
955 @c arrayinfo (c);
956 @c listarray (c);
957 @c ===end===
958 @example
959 (%i1) c[99] : 789;
960 (%o1) 789
961 (%i2) c[99];
962 (%o2) 789
963 (%i3) c;
964 (%o3) c
965 (%i4) arrayinfo (c);
966 (%o4) [hashed, 1, [99]]
967 (%i5) listarray (c);
968 (%o5) [789]
969 @end example
971 Multiple assignment.
973 @c ===beg===
974 @c [a, b, c] : [45, 67, 89];
975 @c a;
976 @c b;
977 @c c;
978 @c ===end===
979 @example
980 (%i1) [a, b, c] : [45, 67, 89];
981 (%o1) [45, 67, 89]
982 (%i2) a;
983 (%o2) 45
984 (%i3) b;
985 (%o3) 67
986 (%i4) c;
987 (%o4) 89
988 @end example
990 Multiple assignment is carried out in parallel.
991 The values of @code{a} and @code{b} are exchanged in this example.
993 @c ===beg===
994 @c [a, b] : [33, 55];
995 @c [a, b] : [b, a];
996 @c a;
997 @c b;
998 @c ===end===
999 @example
1000 (%i1) [a, b] : [33, 55];
1001 (%o1) [33, 55]
1002 (%i2) [a, b] : [b, a];
1003 (%o2) [55, 33]
1004 (%i3) a;
1005 (%o3) 55
1006 (%i4) b;
1007 (%o4) 33
1008 @end example
1010 @opencatbox{Categories:}
1011 @category{Evaluation}
1012 @category{Operators}
1013 @closecatbox
1014 @end deffn
1016 @c -----------------------------------------------------------------------------
1017 @need 900
1018 @anchor{::}
1019 @fnindex Assignment operator (evaluates left-hand side)
1020 @deffn {Operator} ::
1022 Assignment operator.
1024 @code{::} is the same as @mref{:} (which see) except that @code{::} evaluates
1025 its left-hand side as well as its right-hand side.
1027 Examples:
1029 @c ===beg===
1030 @c x : 'foo;
1031 @c x :: 123;
1032 @c foo;
1033 @c x : '[a, b, c];
1034 @c x :: [11, 22, 33];
1035 @c a;
1036 @c b;
1037 @c c;
1038 @c ===end===
1039 @example
1040 (%i1) x : 'foo;
1041 (%o1) foo
1042 (%i2) x :: 123;
1043 (%o2) 123
1044 (%i3) foo;
1045 (%o3) 123
1046 (%i4) x : '[a, b, c];
1047 (%o4) [a, b, c]
1048 (%i5) x :: [11, 22, 33];
1049 (%o5) [11, 22, 33]
1050 (%i6) a;
1051 (%o6) 11
1052 (%i7) b;
1053 (%o7) 22
1054 (%i8) c;
1055 (%o8) 33
1056 @end example
1058 @opencatbox{Categories:}
1059 @category{Evaluation}
1060 @category{Operators}
1061 @closecatbox
1062 @end deffn
1064 @c -----------------------------------------------------------------------------
1065 @anchor{::=}
1066 @fnindex Macro function definition operator
1067 @deffn {Operator} ::=
1069 Macro function definition operator.
1070 @code{::=} defines a function (called a "macro" for historical reasons) which
1071 quotes its arguments, and the expression which it returns (called the "macro
1072 expansion") is evaluated in the context from which the macro was called.
1073 A macro function is otherwise the same as an ordinary function.
1075 @mref{macroexpand} returns a macro expansion (without evaluating it).
1076 @code{macroexpand (foo (x))} followed by @code{''%} is equivalent to
1077 @code{foo (x)} when @code{foo} is a macro function.
1079 @code{::=} puts the name of the new macro function onto the global list
1080 @mrefdot{macros} @mrefcomma{kill} @mrefcomma{remove} and @mref{remfunction}@w{}
1081 unbind macro function definitions and remove names from @code{macros}.
1083 @mref{fundef} or @mref{dispfun} return a macro function definition or assign it
1084 to a label, respectively.
1086 Macro functions commonly contain @mref{buildq} and @mref{splice} expressions to
1087 construct an expression, which is then evaluated.
1089 Examples
1091 A macro function quotes its arguments, so message (1) shows @code{y - z}, not
1092 the value of @code{y - z}. The macro expansion (the quoted expression
1093 @code{'(print ("(2) x is equal to", x))}) is evaluated in the context from which
1094 the macro was called, printing message (2).
1096 @c ===beg===
1097 @c x: %pi$
1098 @c y: 1234$
1099 @c z: 1729 * w$
1100 @c printq1 (x) ::= block (print ("(1) x is equal to", x),
1101 @c '(print ("(2) x is equal to", x)))$
1102 @c printq1 (y - z);
1103 @c ===end===
1104 @example
1105 (%i1) x: %pi$
1106 (%i2) y: 1234$
1107 (%i3) z: 1729 * w$
1108 (%i4) printq1 (x) ::= block (print ("(1) x is equal to", x),
1109 '(print ("(2) x is equal to", x)))$
1110 (%i5) printq1 (y - z);
1111 (1) x is equal to y - z
1112 (2) x is equal to %pi
1113 (%o5) %pi
1114 @end example
1116 An ordinary function evaluates its arguments, so message (1) shows the value of
1117 @code{y - z}. The return value is not evaluated, so message (2) is not printed
1118 until the explicit evaluation @code{''%}.
1120 @c ===beg===
1121 @c x: %pi$
1122 @c y: 1234$
1123 @c z: 1729 * w$
1124 @c printe1 (x) := block (print ("(1) x is equal to", x),
1125 @c '(print ("(2) x is equal to", x)))$
1126 @c printe1 (y - z);
1127 @c ''%;
1128 @c ===end===
1129 @example
1130 (%i1) x: %pi$
1131 (%i2) y: 1234$
1132 (%i3) z: 1729 * w$
1133 (%i4) printe1 (x) := block (print ("(1) x is equal to", x),
1134 '(print ("(2) x is equal to", x)))$
1135 (%i5) printe1 (y - z);
1136 (1) x is equal to 1234 - 1729 w
1137 (%o5) print((2) x is equal to, x)
1138 (%i6) ''%;
1139 (2) x is equal to %pi
1140 (%o6) %pi
1141 @end example
1143 @code{macroexpand} returns a macro expansion.
1144 @code{macroexpand (foo (x))} followed by @code{''%} is equivalent to
1145 @code{foo (x)} when @code{foo} is a macro function.
1147 @c ===beg===
1148 @c x: %pi$
1149 @c y: 1234$
1150 @c z: 1729 * w$
1151 @c g (x) ::= buildq ([x], print ("x is equal to", x))$
1152 @c macroexpand (g (y - z));
1153 @c ''%;
1154 @c g (y - z);
1155 @c ===end===
1156 @example
1157 (%i1) x: %pi$
1158 (%i2) y: 1234$
1159 (%i3) z: 1729 * w$
1160 (%i4) g (x) ::= buildq ([x], print ("x is equal to", x))$
1161 (%i5) macroexpand (g (y - z));
1162 (%o5) print(x is equal to, y - z)
1163 (%i6) ''%;
1164 x is equal to 1234 - 1729 w
1165 (%o6) 1234 - 1729 w
1166 (%i7) g (y - z);
1167 x is equal to 1234 - 1729 w
1168 (%o7) 1234 - 1729 w
1169 @end example
1171 @opencatbox{Categories:}
1172 @category{Function definition}
1173 @category{Operators}
1174 @closecatbox
1175 @end deffn
1177 @c -----------------------------------------------------------------------------
1178 @anchor{:=}
1179 @fnindex Function definition operator
1180 @deffn {Operator} :=
1182 The function definition operator.
1184 @code{@var{f}(@var{x_1}, ..., @var{x_n}) := @var{expr}} defines a function named
1185 @var{f} with arguments @var{x_1}, @dots{}, @var{x_n} and function body
1186 @var{expr}. @code{:=} never evaluates the function body (unless explicitly
1187 evaluated by quote-quote @code{'@w{}'}).
1188 The function body is evaluated every time the function is called.
1190 @code{@var{f}[@var{x_1}, ..., @var{x_n}] := @var{expr}} defines a so-called
1191 @mrefdot{memoizing function}
1192 Its function body is evaluated just once for each distinct value of its arguments,
1193 and that value is returned, without evaluating the function body,
1194 whenever the arguments have those values again.
1195 (A function of this kind is also known as a ``array function''.)
1197 @code{@var{f}[@var{x_1}, ..., @var{x_n}](@var{y_1}, ..., @var{y_m}) := @var{expr}}
1198 is a special case of a @mrefdot{memoizing function}
1199 @code{@var{f}[@var{x_1}, ..., @var{x_n}]} is a @mref{memoizing function} which returns a lambda expression
1200 with arguments @code{@var{y_1}, ..., @var{y_m}}.
1201 The function body is evaluated once for each distinct value of @code{@var{x_1}, ..., @var{x_n}},
1202 and the body of the lambda expression is that value.
1204 When the last or only function argument @var{x_n} is a list of one element, the
1205 function defined by @code{:=} accepts a variable number of arguments. Actual
1206 arguments are assigned one-to-one to formal arguments @var{x_1}, @dots{},
1207 @var{x_(n - 1)}, and any further actual arguments, if present, are assigned to
1208 @var{x_n} as a list.
1210 All function definitions appear in the same namespace; defining a function
1211 @code{f} within another function @code{g} does not automatically limit the scope
1212 of @code{f} to @code{g}. However, @code{local(f)} makes the definition of
1213 function @code{f} effective only within the block or other compound expression
1214 in which @mref{local} appears.
1216 If some formal argument @var{x_k} is a quoted symbol, the function defined by
1217 @code{:=} does not evaluate the corresponding actual argument. Otherwise all
1218 actual arguments are evaluated.
1220 See also @mref{define} and @mrefdot{::=}
1222 Examples:
1224 @code{:=} never evaluates the function body (unless explicitly evaluated by
1225 quote-quote).
1227 @c ===beg===
1228 @c expr : cos(y) - sin(x);
1229 @c F1 (x, y) := expr;
1230 @c F1 (a, b);
1231 @c F2 (x, y) := ''expr;
1232 @c F2 (a, b);
1233 @c ===end===
1234 @example
1235 (%i1) expr : cos(y) - sin(x);
1236 (%o1) cos(y) - sin(x)
1237 (%i2) F1 (x, y) := expr;
1238 (%o2) F1(x, y) := expr
1239 (%i3) F1 (a, b);
1240 (%o3) cos(y) - sin(x)
1241 (%i4) F2 (x, y) := ''expr;
1242 (%o4) F2(x, y) := cos(y) - sin(x)
1243 (%i5) F2 (a, b);
1244 (%o5) cos(b) - sin(a)
1245 @end example
1247 @code{f(@var{x_1}, ..., @var{x_n}) := ...} defines an ordinary function.
1249 @c ===beg===
1250 @c G1(x, y) := (print ("Evaluating G1 for x=", x, "and y=", y),
1251 @c x.y - y.x);
1252 @c G1([1, a], [2, b]);
1253 @c G1([1, a], [2, b]);
1254 @c ===end===
1255 @example
1256 (%i1) G1(x, y) := (print ("Evaluating G1 for x=", x, "and y=", y),
1257 x.y - y.x);
1258 (%o1) G1(x, y) := (print("Evaluating G1 for x=", x, "and y=",
1259 y), x . y - y . x)
1260 (%i2) G1([1, a], [2, b]);
1261 Evaluating G1 for x= [1, a] and y= [2, b]
1262 (%o2) 0
1263 (%i3) G1([1, a], [2, b]);
1264 Evaluating G1 for x= [1, a] and y= [2, b]
1265 (%o3) 0
1266 @end example
1268 @code{f[@var{x_1}, ..., @var{x_n}] := ...} defines a @mrefdot{memoizing function}
1270 @c ===beg===
1271 @c G2[a] := (print ("Evaluating G2 for a=", a), a^2);
1272 @c G2[1234];
1273 @c G2[1234];
1274 @c G2[2345];
1275 @c arrayinfo (G2);
1276 @c listarray (G2);
1277 @c ===end===
1278 @example
1279 (%i1) G2[a] := (print ("Evaluating G2 for a=", a), a^2);
1280 2
1281 (%o1) G2 := (print("Evaluating G2 for a=", a), a )
1282 a
1283 (%i2) G2[1234];
1284 Evaluating G2 for a= 1234
1285 (%o2) 1522756
1286 (%i3) G2[1234];
1287 (%o3) 1522756
1288 (%i4) G2[2345];
1289 Evaluating G2 for a= 2345
1290 (%o4) 5499025
1291 (%i5) arrayinfo (G2);
1292 (%o5) [hashed, 1, [1234], [2345]]
1293 (%i6) listarray (G2);
1294 (%o6) [1522756, 5499025]
1295 @end example
1297 @code{@var{f}[@var{x_1}, ..., @var{x_n}](@var{y_1}, ..., @var{y_m}) := @var{expr}}
1298 is a special case of a @mrefdot{memoizing function}
1300 @c ===beg===
1301 @c G3[n](x) := (print ("Evaluating G3 for n=", n), diff (sin(x)^2,
1302 @c x, n));
1303 @c G3[2];
1304 @c G3[2];
1305 @c G3[2](1);
1306 @c arrayinfo (G3);
1307 @c listarray (G3);
1308 @c ===end===
1309 @example
1310 (%i1) G3[n](x) := (print ("Evaluating G3 for n=", n), diff (sin(x)^2,
1311 x, n));
1312 (%o1) G3 (x) := (print("Evaluating G3 for n=", n),
1313 n
1314 2
1315 diff(sin (x), x, n))
1316 (%i2) G3[2];
1317 Evaluating G3 for n= 2
1318 2 2
1319 (%o2) lambda([x], 2 cos (x) - 2 sin (x))
1320 (%i3) G3[2];
1321 2 2
1322 (%o3) lambda([x], 2 cos (x) - 2 sin (x))
1323 (%i4) G3[2](1);
1324 2 2
1325 (%o4) 2 cos (1) - 2 sin (1)
1326 (%i5) arrayinfo (G3);
1327 (%o5) [hashed, 1, [2]]
1328 (%i6) listarray (G3);
1329 2 2
1330 (%o6) [lambda([x], 2 cos (x) - 2 sin (x))]
1331 @end example
1333 When the last or only function argument @var{x_n} is a list of one element,
1334 the function defined by @code{:=} accepts a variable number of arguments.
1336 @c ===beg===
1337 @c H ([L]) := apply ("+", L);
1338 @c H (a, b, c);
1339 @c ===end===
1340 @example
1341 (%i1) H ([L]) := apply ("+", L);
1342 (%o1) H([L]) := apply("+", L)
1343 (%i2) H (a, b, c);
1344 (%o2) c + b + a
1345 @end example
1347 @code{local} makes a local function definition.
1349 @c ===beg===
1350 @c foo (x) := 1 - x;
1351 @c foo (100);
1352 @c block (local (foo), foo (x) := 2 * x, foo (100));
1353 @c foo (100);
1354 @c ===end===
1355 @example
1356 (%i1) foo (x) := 1 - x;
1357 (%o1) foo(x) := 1 - x
1358 (%i2) foo (100);
1359 (%o2) - 99
1360 (%i3) block (local (foo), foo (x) := 2 * x, foo (100));
1361 (%o3) 200
1362 (%i4) foo (100);
1363 (%o4) - 99
1364 @end example
1366 @opencatbox{Categories:}
1367 @category{Function definition}
1368 @category{Operators}
1369 @closecatbox
1370 @end deffn
1372 @c -----------------------------------------------------------------------------
1373 @node User defined operators, , Assignment operators, Operators
1374 @section User defined operators
1375 @c -----------------------------------------------------------------------------
1377 @c -----------------------------------------------------------------------------
1378 @anchor{infix}
1379 @deffn {Function} infix @
1380 @fname{infix} (@var{op}) @
1381 @fname{infix} (@var{op}, @var{lbp}, @var{rbp}) @
1382 @fname{infix} (@var{op}, @var{lbp}, @var{rbp}, @var{lpos}, @var{rpos}, @var{pos})
1384 Declares @var{op} to be an infix operator. An infix operator is a function of
1385 two arguments, with the name of the function written between the arguments.
1386 For example, the subtraction operator @code{-} is an infix operator.
1388 @code{infix (@var{op})} declares @var{op} to be an infix operator with default
1389 binding powers (left and right both equal to 180) and parts of speech (left and
1390 right both equal to @code{any}).
1391 @c HOW IS pos DIFFERENT FROM lpos AND rpos ??
1393 @code{infix (@var{op}, @var{lbp}, @var{rbp})} declares @var{op} to be an infix
1394 operator with stated left and right binding powers and default parts of speech
1395 (left and right both equal to @code{any}).
1397 @code{infix (@var{op}, @var{lbp}, @var{rbp}, @var{lpos}, @var{rpos}, @var{pos})}
1398 declares @var{op} to be an infix operator with stated left and right binding
1399 powers and parts of speech @var{lpos}, @var{rpos}, and @var{pos} for the left
1400 operand, the right operand, and the operator result, respectively.
1402 "Part of speech", in reference to operator declarations, means expression type.
1403 Three types are recognized: @code{expr}, @code{clause}, and @code{any},
1404 indicating an algebraic expression, a Boolean expression, or any kind of
1405 expression, respectively. Maxima can detect some syntax errors by comparing the
1406 declared part of speech to an actual expression.
1408 The precedence of @var{op} with respect to other operators derives from the left
1409 and right binding powers of the operators in question. If the left and right
1410 binding powers of @var{op} are both greater the left and right binding powers of
1411 some other operator, then @var{op} takes precedence over the other operator.
1412 If the binding powers are not both greater or less, some more complicated
1413 relation holds.
1415 The associativity of @var{op} depends on its binding powers. Greater left
1416 binding power (@var{lbp}) implies an instance of @var{op} is evaluated before
1417 other operators to its left in an expression, while greater right binding power
1418 (@var{rbp}) implies an instance of @var{op} is evaluated before other operators
1419 to its right in an expression. Thus greater @var{lbp} makes @var{op}
1420 right-associative, while greater @var{rbp} makes @var{op} left-associative.
1421 If @var{lbp} is equal to @var{rbp}, @var{op} is left-associative.
1423 See also @ref{Introduction to operators}.
1425 Examples:
1427 If the left and right binding powers of @var{op} are both greater
1428 the left and right binding powers of some other operator,
1429 then @var{op} takes precedence over the other operator.
1431 @c ===beg===
1432 @c :lisp (get '$+ 'lbp)
1433 @c :lisp (get '$+ 'rbp)
1434 @c infix ("##", 101, 101);
1435 @c "##"(a, b) := sconcat("(", a, ",", b, ")");
1436 @c 1 + a ## b + 2;
1437 @c infix ("##", 99, 99);
1438 @c 1 + a ## b + 2;
1439 @c ===end===
1440 @example
1441 (%i1) :lisp (get '$+ 'lbp)
1442 100
1443 (%i1) :lisp (get '$+ 'rbp)
1444 100
1445 (%i1) infix ("##", 101, 101);
1446 (%o1) ##
1447 (%i2) "##"(a, b) := sconcat("(", a, ",", b, ")");
1448 (%o2) (a ## b) := sconcat("(", a, ",", b, ")")
1449 (%i3) 1 + a ## b + 2;
1450 (%o3) (a,b) + 3
1451 (%i4) infix ("##", 99, 99);
1452 (%o4) ##
1453 (%i5) 1 + a ## b + 2;
1454 (%o5) (a+1,b+2)
1455 @end example
1457 Greater @var{lbp} makes @var{op} right-associative,
1458 while greater @var{rbp} makes @var{op} left-associative.
1460 @c ===beg===
1461 @c infix ("##", 100, 99);
1462 @c "##"(a, b) := sconcat("(", a, ",", b, ")")$
1463 @c foo ## bar ## baz;
1464 @c infix ("##", 100, 101);
1465 @c foo ## bar ## baz;
1466 @c ===end===
1467 @example
1468 (%i1) infix ("##", 100, 99);
1469 (%o1) ##
1470 (%i2) "##"(a, b) := sconcat("(", a, ",", b, ")")$
1471 (%i3) foo ## bar ## baz;
1472 (%o3) (foo,(bar,baz))
1473 (%i4) infix ("##", 100, 101);
1474 (%o4) ##
1475 (%i5) foo ## bar ## baz;
1476 (%o5) ((foo,bar),baz)
1477 @end example
1479 Maxima can detect some syntax errors by comparing the
1480 declared part of speech to an actual expression.
1482 @c ===beg===
1483 @c infix ("##", 100, 99, expr, expr, expr);
1484 @c if x ## y then 1 else 0;
1485 @c infix ("##", 100, 99, expr, expr, clause);
1486 @c if x ## y then 1 else 0;
1487 @c ===end===
1488 @example
1489 (%i1) infix ("##", 100, 99, expr, expr, expr);
1490 (%o1) ##
1491 (%i2) if x ## y then 1 else 0;
1492 Incorrect syntax: Found algebraic expression where logical
1493 expression expected
1494 if x ## y then
1495 ^
1496 (%i2) infix ("##", 100, 99, expr, expr, clause);
1497 (%o2) ##
1498 (%i3) if x ## y then 1 else 0;
1499 (%o3) if x ## y then 1 else 0
1500 @end example
1502 @opencatbox{Categories:}
1503 @category{Operators}
1504 @category{Declarations and inferences}
1505 @category{Syntax}
1506 @closecatbox
1507 @end deffn
1509 @c -----------------------------------------------------------------------------
1510 @anchor{matchfix}
1511 @deffn {Function} matchfix @
1512 @fname{matchfix} (@var{ldelimiter}, @var{rdelimiter}) @
1513 @fname{matchfix} (@var{ldelimiter}, @var{rdelimiter}, @var{arg_pos}, @var{pos})
1515 Declares a matchfix operator with left and right delimiters @var{ldelimiter}
1516 and @var{rdelimiter}. The delimiters are specified as strings.
1518 A "matchfix" operator is a function of any number of arguments,
1519 such that the arguments occur between matching left and right delimiters.
1520 The delimiters may be any strings, so long as the parser can
1521 distinguish the delimiters from the operands
1522 and other expressions and operators.
1523 In practice this rules out unparseable delimiters such as
1524 @code{%}, @code{,}, @code{$} and @code{;},
1525 and may require isolating the delimiters with white space.
1526 The right delimiter can be the same or different from the left delimiter.
1528 A left delimiter can be associated with only one right delimiter;
1529 two different matchfix operators cannot have the same left delimiter.
1531 An existing operator may be redeclared as a matchfix operator
1532 without changing its other properties.
1533 In particular, built-in operators such as addition @code{+} can
1534 be declared matchfix,
1535 but operator functions cannot be defined for built-in operators.
1537 The command @code{matchfix (@var{ldelimiter}, @var{rdelimiter}, @var{arg_pos},
1538 @var{pos})} declares the argument part-of-speech @var{arg_pos} and result
1539 part-of-speech @var{pos}, and the delimiters @var{ldelimiter} and
1540 @var{rdelimiter}.
1542 "Part of speech", in reference to operator declarations, means expression type.
1543 Three types are recognized: @code{expr}, @code{clause}, and @code{any},
1544 indicating an algebraic expression, a Boolean expression, or any kind of
1545 expression, respectively.
1546 Maxima can detect some syntax errors by comparing the
1547 declared part of speech to an actual expression.
1549 @c DUNNO IF WE REALLY NEED TO MENTION BINDING POWER HERE -- AS NOTED IT'S IRRELEVANT
1550 @c An operator declared by @code{matchfix} is assigned a low binding power.
1551 @c Since a matchfix operator must be evaluated before any expression
1552 @c which contains it,
1553 @c binding power is effectively irrelevant
1554 @c to the declaration of a matchfix operator.
1556 The function to carry out a matchfix operation is an ordinary
1557 user-defined function.
1558 The operator function is defined
1559 in the usual way
1560 with the function definition operator @code{:=} or @code{define}.
1561 The arguments may be written between the delimiters,
1562 or with the left delimiter as a quoted string and the arguments
1563 following in parentheses.
1564 @code{dispfun (@var{ldelimiter})} displays the function definition.
1566 The only built-in matchfix operator is the list constructor @code{[ ]}.
1567 Parentheses @code{( )} and double-quotes @code{" "}
1568 act like matchfix operators,
1569 but are not treated as such by the Maxima parser.
1571 @code{matchfix} evaluates its arguments.
1572 @code{matchfix} returns its first argument, @var{ldelimiter}.
1573 @c HOW TO TAKE AWAY THE MATCHFIX PROPERTY ??
1575 Examples:
1577 Delimiters may be almost any strings.
1579 @c ===beg===
1580 @c matchfix ("@@", "~");
1581 @c @@ a, b, c ~;
1582 @c matchfix (">>", "<<");
1583 @c >> a, b, c <<;
1584 @c matchfix ("foo", "oof");
1585 @c foo a, b, c oof;
1586 @c >> w + foo x, y oof + z << / @@ p, q ~;
1587 @c ===end===
1588 @example
1589 (%i1) matchfix ("@@@@", "~");
1590 (%o1) @@@@
1591 (%i2) @@@@ a, b, c ~;
1592 (%o2) @@@@a, b, c~
1593 (%i3) matchfix (">>", "<<");
1594 (%o3) >>
1595 (%i4) >> a, b, c <<;
1596 (%o4) >>a, b, c<<
1597 (%i5) matchfix ("foo", "oof");
1598 (%o5) foo
1599 (%i6) foo a, b, c oof;
1600 (%o6) fooa, b, coof
1601 (%i7) >> w + foo x, y oof + z << / @@@@ p, q ~;
1602 >>z + foox, yoof + w<<
1603 (%o7) ----------------------
1604 @@@@p, q~
1605 @end example
1607 Matchfix operators are ordinary user-defined functions.
1609 @example
1610 (%i1) matchfix ("!-", "-!");
1611 (%o1) "!-"
1612 (%i2) !- x, y -! := x/y - y/x;
1613 x y
1614 (%o2) !-x, y-! := - - -
1615 y x
1616 (%i3) define (!-x, y-!, x/y - y/x);
1617 x y
1618 (%o3) !-x, y-! := - - -
1619 y x
1620 (%i4) define ("!-" (x, y), x/y - y/x);
1621 x y
1622 (%o4) !-x, y-! := - - -
1623 y x
1624 (%i5) dispfun ("!-");
1625 x y
1626 (%t5) !-x, y-! := - - -
1627 y x
1629 (%o5) done
1630 (%i6) !-3, 5-!;
1631 16
1632 (%o6) - --
1633 15
1634 (%i7) "!-" (3, 5);
1635 16
1636 (%o7) - --
1637 15
1638 @end example
1640 @opencatbox{Categories:}
1641 @category{Syntax}
1642 @category{Operators}
1643 @closecatbox
1644 @end deffn
1646 @c -----------------------------------------------------------------------------
1647 @anchor{function_nary}
1648 @deffn {Function} nary @
1649 @fname{nary} (@var{op}) @
1650 @fname{nary} (@var{op}, @var{bp}, @var{arg_pos}, @var{pos})
1652 An @code{nary} operator is used to denote a function of any number of arguments,
1653 each of which is separated by an occurrence of the operator, e.g. A+B or A+B+C.
1654 The @code{nary("x")} function is a syntax extension function to declare @code{x}
1655 to be an @code{nary} operator. Functions may be declared to be @code{nary}. If
1656 @code{declare(j,nary);} is done, this tells the simplifier to simplify, e.g.
1657 @code{j(j(a,b),j(c,d))} to @code{j(a, b, c, d)}.
1659 See also @ref{Introduction to operators}.
1661 @opencatbox{Categories:}
1662 @category{Operators}
1663 @category{Syntax}
1664 @closecatbox
1665 @end deffn
1667 @c -----------------------------------------------------------------------------
1668 @anchor{nofix}
1669 @deffn {Function} nofix @
1670 @fname{nofix} (@var{op}) @
1671 @fname{nofix} (@var{op}, @var{pos})
1673 @code{nofix} operators are used to denote functions of no arguments.
1674 The mere presence of such an operator in a command will cause the
1675 corresponding function to be evaluated. For example, when one types
1676 "exit;" to exit from a Maxima break, "exit" is behaving similar to a
1677 @code{nofix} operator. The function @code{nofix("x")} is a syntax extension
1678 function which declares @code{x} to be a @code{nofix} operator.
1680 See also @ref{Introduction to operators}.
1682 @opencatbox{Categories:}
1683 @category{Operators}
1684 @category{Syntax}
1685 @closecatbox
1686 @end deffn
1688 @c -----------------------------------------------------------------------------
1689 @anchor{postfix}
1690 @deffn {Function} postfix @
1691 @fname{postfix} (@var{op}) @
1692 @fname{postfix} (@var{op}, @var{lbp}, @var{lpos}, @var{pos})
1694 @code{postfix} operators like the @code{prefix} variety denote functions of a
1695 single argument, but in this case the argument immediately precedes an
1696 occurrence of the operator in the input string, e.g. 3!. The
1697 @code{postfix("x")} function is a syntax extension function to declare @code{x}
1698 to be a @code{postfix} operator.
1700 See also @ref{Introduction to operators}.
1702 @opencatbox{Categories:}
1703 @category{Operators}
1704 @category{Syntax}
1705 @closecatbox
1706 @end deffn
1708 @c -----------------------------------------------------------------------------
1709 @anchor{prefix}
1710 @deffn {Function} prefix @
1711 @fname{prefix} (@var{op}) @
1712 @fname{prefix} (@var{op}, @var{rbp}, @var{rpos}, @var{pos})
1714 A @code{prefix} operator is one which signifies a function of one argument,
1715 which argument immediately follows an occurrence of the operator.
1716 @code{prefix("x")} is a syntax extension function to declare @code{x} to be a
1717 @code{prefix} operator.
1719 See also @ref{Introduction to operators}.
1721 @opencatbox{Categories:}
1722 @category{Operators}
1723 @category{Syntax}
1724 @closecatbox
1725 @end deffn