| blob | 5a177caa194c720f777ea0fe4f4eef266299d608 |
1 @menu
2 * Numbers::
3 * Strings::
4 * Constants::
5 * Lists::
6 * Arrays::
7 * Structures::
8 @end menu
10 @c -----------------------------------------------------------------------------
11 @node Numbers, Strings, Data Types and Structures, Data Types and Structures
12 @section Numbers
13 @c -----------------------------------------------------------------------------
15 @menu
16 * Introduction to Numbers::
17 * Functions and Variables for Numbers::
18 @end menu
20 @c -----------------------------------------------------------------------------
21 @node Introduction to Numbers, Functions and Variables for Numbers, Numbers, Numbers
22 @subsection Introduction to Numbers
23 @c -----------------------------------------------------------------------------
25 @c -----------------------------------------------------------------------------
26 @subheading Complex numbers
27 @c -----------------------------------------------------------------------------
29 A complex expression is specified in Maxima by adding the real part of the
30 expression to @code{%i} times the imaginary part. Thus the roots of the
31 equation @code{x^2 - 4*x + 13 = 0} are @code{2 + 3*%i} and @code{2 - 3*%i}.
32 Note that simplification of products of complex expressions can be effected by
33 expanding the product. Simplification of quotients, roots, and other functions
34 of complex expressions can usually be accomplished by using the @code{realpart},
35 @code{imagpart}, @code{rectform}, @code{polarform}, @code{abs}, @code{carg}
36 functions.
38 @opencatbox
39 @category{Complex variables}
40 @closecatbox
42 @c -----------------------------------------------------------------------------
43 @node Functions and Variables for Numbers, , Introduction to Numbers, Numbers
44 @subsection Functions and Variables for Numbers
45 @c -----------------------------------------------------------------------------
47 @c -----------------------------------------------------------------------------
48 @anchor{bfloat}
49 @deffn {Function} bfloat (@var{expr})
51 @code{bfloat} replaces integers, rationals, floating point numbers, and some symbolic constants
52 in @var{expr} with bigfloat (variable-precision floating point) numbers.
54 The constants @code{%e}, @code{%gamma}, @code{%phi}, and @code{%pi}
55 are replaced by a numerical approximation.
56 However, @code{%e} in @code{%e^x} is not replaced by a numeric value
57 unless @code{bfloat(x)} is a number.
59 @code{bfloat} also causes numerical evaluation of some built-in functions,
60 namely trigonometric functions, exponential functions, @code{abs}, and @code{log}.
61 @c ALSO ENTIER BUT LET'S NOT GO INTO IT.
63 The number of significant digits in the resulting bigfloats is specified by the
64 global variable @mrefdot{fpprec}
65 Bigfloats already present in @var{expr} are replaced with values which have
66 precision specified by the current value of @mref{fpprec}.
68 When @mref{float2bf} is @code{false}, a warning message is printed when
69 a floating point number is replaced by a bigfloat number with less precision.
71 Examples:
73 @code{bfloat} replaces integers, rationals, floating point numbers, and some symbolic constants
74 in @var{expr} with bigfloat numbers.
76 @c ===beg===
77 @c bfloat([123, 17/29, 1.75]);
78 @c bfloat([%e, %gamma, %phi, %pi]);
79 @c bfloat((f(123) + g(h(17/29)))/(x + %gamma));
80 @c ===end===
81 @example
82 (%i1) bfloat([123, 17/29, 1.75]);
83 (%o1) [1.23b2, 5.862068965517241b-1, 1.75b0]
84 (%i2) bfloat([%e, %gamma, %phi, %pi]);
85 (%o2) [2.718281828459045b0, 5.772156649015329b-1,
86 1.618033988749895b0, 3.141592653589793b0]
87 (%i3) bfloat((f(123) + g(h(17/29)))/(x + %gamma));
88 1.0b0 (g(h(5.862068965517241b-1)) + f(1.23b2))
89 (%o3) ----------------------------------------------
90 x + 5.772156649015329b-1
91 @end example
93 @code{bfloat} also causes numerical evaluation of some built-in functions.
95 @c ===beg===
96 @c bfloat(sin(17/29));
97 @c bfloat(exp(%pi));
98 @c bfloat(abs(-%gamma));
99 @c bfloat(log(%phi));
100 @c ===end===
101 @example
102 (%i1) bfloat(sin(17/29));
103 (%o1) 5.532051841609784b-1
104 (%i2) bfloat(exp(%pi));
105 (%o2) 2.314069263277927b1
106 (%i3) bfloat(abs(-%gamma));
107 (%o3) 5.772156649015329b-1
108 (%i4) bfloat(log(%phi));
109 (%o4) 4.812118250596035b-1
110 @end example
112 @opencatbox
113 @category{Numerical evaluation}
114 @closecatbox
115 @end deffn
117 @c -----------------------------------------------------------------------------
118 @anchor{bfloatp}
119 @deffn {Function} bfloatp (@var{expr})
121 Returns @code{true} if @var{expr} is a bigfloat number, otherwise @code{false}.
123 @opencatbox
124 @category{Numerical evaluation}
125 @category{Predicate functions}
126 @closecatbox
127 @end deffn
129 @c --- 03.11.2011 --------------------------------------------------------------
130 @anchor{bftorat}
131 @defvr {Option variable} bftorat
132 Default value: @code{false}
134 @code{bftorat} controls the conversion of bfloats to rational numbers. When
135 @code{bftorat} is @code{false}, @mref{ratepsilon} will be used to control the
136 conversion (this results in relatively small rational numbers). When
137 @code{bftorat} is @code{true}, the rational number generated will accurately
138 represent the bfloat.
140 Note: @code{bftorat} has no effect on the transformation to rational numbers
141 with the function @mrefdot{rationalize}
143 Example:
145 @c ===beg===
146 @c ratepsilon:1e-4;
147 @c rat(bfloat(11111/111111)), bftorat:false;
148 @c rat(bfloat(11111/111111)), bftorat:true;
149 @c ===end===
150 @example
151 (%i1) ratepsilon:1e-4;
152 (%o1) 1.e-4
153 (%i2) rat(bfloat(11111/111111)), bftorat:false;
154 `rat' replaced 9.99990999991B-2 by 1/10 = 1.0B-1
155 1
156 (%o2)/R/ --
157 10
158 (%i3) rat(bfloat(11111/111111)), bftorat:true;
159 `rat' replaced 9.99990999991B-2 by 11111/111111 = 9.99990999991B-2
160 11111
161 (%o3)/R/ ------
162 111111
163 @end example
165 @opencatbox
166 @category{Numerical evaluation}
167 @closecatbox
168 @end defvr
170 @c -----------------------------------------------------------------------------
171 @anchor{bftrunc}
172 @defvr {Option variable} bftrunc
173 Default value: @code{true}
175 @code{bftrunc} causes trailing zeroes in non-zero bigfloat numbers not to be
176 displayed. Thus, if @code{bftrunc} is @code{false}, @code{bfloat (1)}
177 displays as @code{1.000000000000000B0}. Otherwise, this is displayed as
178 @code{1.0B0}.
180 @opencatbox
181 @category{Numerical evaluation}
182 @closecatbox
183 @end defvr
185 @c -----------------------------------------------------------------------------
186 @anchor{evenp}
187 @deffn {Function} evenp (@var{expr})
189 @c THIS IS STRANGE -- SHOULD RETURN NOUN FORM IF INDETERMINATE
190 Returns @code{true} if @var{expr} is a literal even integer, otherwise
191 @code{false}.
193 @code{evenp} returns @code{false} if @var{expr} is a symbol, even if @var{expr}
194 is declared @code{even}.
196 @opencatbox
197 @category{Predicate functions}
198 @closecatbox
199 @end deffn
201 @c -----------------------------------------------------------------------------
202 @anchor{float}
203 @deffn {Function} float (@var{expr})
205 Converts integers, rational numbers and bigfloats in @var{expr} to floating
206 point numbers. It is also an @mrefcomma{evflag} @code{float} causes
207 non-integral rational numbers and bigfloat numbers to be converted to floating
208 point.
210 @opencatbox
211 @category{Numerical evaluation}
212 @category{Evaluation flags}
213 @closecatbox
214 @end deffn
216 @c --- 08.10.2010 DK -----------------------------------------------------------
217 @anchor{float2bf}
218 @defvr {Option variable} float2bf
219 Default value: @code{true}
221 When @mref{float2bf} is @code{false}, a warning message is printed when
222 a floating point number is replaced by a bigfloat number with less precision.
223 @c DOES THAT APPLY ONLY TO BFLOAT, OR DO OTHER FUNCTIONS CALL IT ??
225 @opencatbox
226 @category{Numerical evaluation}
227 @closecatbox
228 @end defvr
230 @c -----------------------------------------------------------------------------
231 @anchor{floatnump}
232 @deffn {Function} floatnump (@var{expr})
234 Returns @code{true} if @var{expr} is a floating point number, otherwise
235 @code{false}.
237 @opencatbox
238 @category{Numerical evaluation}
239 @category{Predicate functions}
240 @closecatbox
241 @end deffn
243 @c -----------------------------------------------------------------------------
244 @anchor{fpprec}
245 @defvr {Option variable} fpprec
246 Default value: 16
248 @code{fpprec} is the number of significant digits for arithmetic on bigfloat
249 numbers. @code{fpprec} does not affect computations on ordinary floating point
250 numbers.
252 See also @mref{bfloat} and @mrefdot{fpprintprec}
254 @opencatbox
255 @category{Numerical evaluation}
256 @closecatbox
257 @end defvr
259 @c -----------------------------------------------------------------------------
260 @anchor{fpprintprec}
261 @defvr {Option variable} fpprintprec
262 Default value: 0
264 @code{fpprintprec} is the number of digits to print when printing an ordinary
265 float or bigfloat number.
267 For ordinary floating point numbers,
268 when @code{fpprintprec} has a value between 2 and 16 (inclusive),
269 the number of digits printed is equal to @code{fpprintprec}.
270 Otherwise, @code{fpprintprec} is 0, or greater than 16,
271 and the number of digits printed is 16.
273 For bigfloat numbers,
274 when @code{fpprintprec} has a value between 2 and @code{fpprec} (inclusive),
275 the number of digits printed is equal to @code{fpprintprec}.
276 Otherwise, @code{fpprintprec} is 0, or greater than @code{fpprec},
277 and the number of digits printed is equal to @code{fpprec}.
279 For both ordinary floats and bigfloats,
280 trailing zero digits are suppressed.
281 The actual number of digits printed is less than @code{fpprintprec}
282 if there are trailing zero digits.
284 @code{fpprintprec} cannot be 1.
286 @opencatbox
287 @category{Numerical evaluation}
288 @category{Display flags and variables}
289 @closecatbox
290 @end defvr
292 @c -----------------------------------------------------------------------------
293 @anchor{integerp}
294 @deffn {Function} integerp (@var{expr})
296 Returns @code{true} if @var{expr} is a literal numeric integer, otherwise
297 @code{false}.
299 @code{integerp} returns @code{false} if @var{expr} is a symbol, even if @var{expr}
300 is declared @code{integer}.
302 Examples:
304 @c ===beg===
305 @c integerp (0);
306 @c integerp (1);
307 @c integerp (-17);
308 @c integerp (0.0);
309 @c integerp (1.0);
310 @c integerp (%pi);
311 @c integerp (n);
312 @c declare (n, integer);
313 @c integerp (n);
314 @c ===end===
315 @example
316 (%i1) integerp (0);
317 (%o1) true
318 (%i2) integerp (1);
319 (%o2) true
320 (%i3) integerp (-17);
321 (%o3) true
322 (%i4) integerp (0.0);
323 (%o4) false
324 (%i5) integerp (1.0);
325 (%o5) false
326 (%i6) integerp (%pi);
327 (%o6) false
328 (%i7) integerp (n);
329 (%o7) false
330 (%i8) declare (n, integer);
331 (%o8) done
332 (%i9) integerp (n);
333 (%o9) false
334 @end example
336 @opencatbox
337 @category{Predicate functions}
338 @closecatbox
339 @end deffn
341 @c -----------------------------------------------------------------------------
342 @anchor{m1pbranch}
343 @defvr {Option variable} m1pbranch
344 Default value: @code{false}
346 @code{m1pbranch} is the principal branch for @code{-1} to a power.
347 Quantities such as @code{(-1)^(1/3)} (that is, an "odd" rational exponent) and
348 @code{(-1)^(1/4)} (that is, an "even" rational exponent) are handled as follows:
350 @c REDRAW THIS AS A TABLE
351 @example
352 domain:real
354 (-1)^(1/3): -1
355 (-1)^(1/4): (-1)^(1/4)
357 domain:complex
358 m1pbranch:false m1pbranch:true
359 (-1)^(1/3) 1/2+%i*sqrt(3)/2
360 (-1)^(1/4) sqrt(2)/2+%i*sqrt(2)/2
361 @end example
363 @opencatbox
364 @category{Expressions}
365 @category{Global flags}
366 @closecatbox
367 @end defvr
369 @c -----------------------------------------------------------------------------
370 @anchor{nonnegintegerp}
371 @deffn {Function} nonnegintegerp (@var{n})
373 Return @code{true} if and only if @code{@var{n} >= 0} and @var{n} is an integer.
375 @opencatbox
376 @category{Package linearalgebra}
377 @category{Predicate functions}
378 @closecatbox
379 @end deffn
381 @c -----------------------------------------------------------------------------
382 @anchor{numberp}
383 @deffn {Function} numberp (@var{expr})
385 Returns @code{true} if @var{expr} is a literal integer, rational number,
386 floating point number, or bigfloat, otherwise @code{false}.
388 @code{numberp} returns @code{false} if @var{expr} is a symbol, even if @var{expr}
389 is a symbolic number such as @code{%pi} or @code{%i}, or declared to be
390 @code{even}, @code{odd}, @code{integer}, @code{rational}, @code{irrational},
391 @code{real}, @code{imaginary}, or @code{complex}.
393 Examples:
395 @c ===beg===
396 @c numberp (42);
397 @c numberp (-13/19);
398 @c numberp (3.14159);
399 @c numberp (-1729b-4);
400 @c map (numberp, [%e, %pi, %i, %phi, inf, minf]);
401 @c declare (a, even, b, odd, c, integer, d, rational, e, irrational, f, real, g, imaginary, h, complex);
402 @c map (numberp, [a, b, c, d, e, f, g, h]);
403 @c ===end===
404 @example
405 (%i1) numberp (42);
406 (%o1) true
407 (%i2) numberp (-13/19);
408 (%o2) true
409 (%i3) numberp (3.14159);
410 (%o3) true
411 (%i4) numberp (-1729b-4);
412 (%o4) true
413 (%i5) map (numberp, [%e, %pi, %i, %phi, inf, minf]);
414 (%o5) [false, false, false, false, false, false]
415 (%i6) declare (a, even, b, odd, c, integer, d, rational,
416 e, irrational, f, real, g, imaginary, h, complex);
417 (%o6) done
418 (%i7) map (numberp, [a, b, c, d, e, f, g, h]);
419 (%o7) [false, false, false, false, false, false, false, false]
420 @end example
422 @opencatbox
423 @category{Predicate functions}
424 @closecatbox
425 @end deffn
427 @c NEEDS CLARIFICATION, EXAMPLES
428 @c WHAT ARE THE FUNCTIONS WHICH ARE EVALUATED IN FLOATING POINT ??
429 @c WHAT IS A "NUMERVAL" ?? (SOMETHING DIFFERENT FROM A NUMERIC VALUE ??)
430 @c NEED TO MENTION THIS IS AN evflag
432 @c -----------------------------------------------------------------------------
433 @anchor{numer}
434 @defvr {Option variable} numer
436 @code{numer} causes some mathematical functions (including exponentiation)
437 with numerical arguments to be evaluated in floating point. It causes
438 variables in @code{expr} which have been given numerals to be replaced by
439 their values. It also sets the @mref{float} switch on.
441 See also @mrefdot{%enumer}
443 Examples:
445 @c ===beg===
446 @c [sqrt(2), sin(1), 1/(1+sqrt(3))];
447 @c [sqrt(2), sin(1), 1/(1+sqrt(3))],numer;
448 @c ===end===
449 @example
450 @group
451 (%i1) [sqrt(2), sin(1), 1/(1+sqrt(3))];
452 1
453 (%o1) [sqrt(2), sin(1), -----------]
454 sqrt(3) + 1
455 @end group
456 @group
457 (%i2) [sqrt(2), sin(1), 1/(1+sqrt(3))],numer;
458 (%o2) [1.414213562373095, 0.8414709848078965, 0.3660254037844387]
459 @end group
460 @end example
462 @opencatbox
463 @category{Numerical evaluation}
464 @category{Evaluation flags}
465 @closecatbox
466 @end defvr
468 @c -----------------------------------------------------------------------------
469 @anchor{numer_pbranch}
470 @defvr {Option variable} numer_pbranch
471 Default value: @code{false}
473 The option variable @code{numer_pbranch} controls the numerical evaluation of
474 the power of a negative integer, rational, or floating point number. When
475 @code{numer_pbranch} is @code{true} and the exponent is a floating point number
476 or the option variable @mref{numer} is @code{true} too, Maxima evaluates
477 the numerical result using the principal branch. Otherwise a simplified, but
478 not an evaluated result is returned.
480 Examples:
482 @c ===beg===
483 @c (-2)^0.75;
484 @c (-2)^0.75,numer_pbranch:true;
485 @c (-2)^(3/4);
486 @c (-2)^(3/4),numer;
487 @c (-2)^(3/4),numer,numer_pbranch:true;
488 @c ===end===
489 @example
490 @group
491 (%i1) (-2)^0.75;
492 0.75
493 (%o1) (- 2)
494 @end group
495 @group
496 (%i2) (-2)^0.75,numer_pbranch:true;
497 (%o2) 1.189207115002721 %i - 1.189207115002721
498 @end group
499 @group
500 (%i3) (-2)^(3/4);
501 3/4 3/4
502 (%o3) (- 1) 2
503 @end group
504 @group
505 (%i4) (-2)^(3/4),numer;
506 0.75
507 (%o4) 1.681792830507429 (- 1)
508 @end group
509 @group
510 (%i5) (-2)^(3/4),numer,numer_pbranch:true;
511 (%o5) 1.189207115002721 %i - 1.189207115002721
512 @end group
513 @end example
515 @opencatbox
516 @category{Numerical evaluation}
517 @closecatbox
518 @end defvr
520 @c NEEDS CLARIFICATION, EXAMPLES
521 @c HOW TO FIND ALL VARIABLES WHICH HAVE NUMERVALS ??
523 @c -----------------------------------------------------------------------------
524 @anchor{numerval}
525 @deffn {Function} numerval (@var{x_1}, @var{expr_1}, @dots{}, @var{var_n}, @var{expr_n})
527 Declares the variables @code{x_1}, @dots{}, @var{x_n} to have
528 numeric values equal to @code{expr_1}, @dots{}, @code{expr_n}.
529 The numeric value is evaluated and substituted for the variable
530 in any expressions in which the variable occurs if the @code{numer} flag is
531 @code{true}. See also @mrefdot{ev}
533 The expressions @code{expr_1}, @dots{}, @code{expr_n} can be any expressions,
534 not necessarily numeric.
536 @opencatbox
537 @category{Declarations and inferences}
538 @category{Numerical evaluation}
539 @closecatbox
540 @end deffn
542 @c -----------------------------------------------------------------------------
543 @anchor{oddp}
544 @deffn {Function} oddp (@var{expr})
546 @c THIS IS STRANGE -- SHOULD RETURN NOUN FORM IF INDETERMINATE
547 Returns @code{true} if @var{expr} is a literal odd integer, otherwise
548 @code{false}.
550 @code{oddp} returns @code{false} if @var{expr} is a symbol, even if @var{expr}
551 is declared @code{odd}.
553 @opencatbox
554 @category{Predicate functions}
555 @closecatbox
556 @end deffn
558 @c --- 03.11.2011 --------------------------------------------------------------
559 @anchor{ratepsilon}
560 @defvr {Option variable} ratepsilon
561 Default value: @code{2.0e-15}
563 @code{ratepsilon} is the tolerance used in the conversion
564 of floating point numbers to rational numbers, when the option variable
565 @mref{bftorat} has the value @code{false}. See @code{bftorat} for an example.
567 @opencatbox
568 @category{Numerical evaluation}
569 @category{Rational expressions}
570 @closecatbox
571 @end defvr
573 @c -----------------------------------------------------------------------------
574 @anchor{rationalize}
575 @deffn {Function} rationalize (@var{expr})
577 Convert all double floats and big floats in the Maxima expression @var{expr} to
578 their exact rational equivalents. If you are not familiar with the binary
579 representation of floating point numbers, you might be surprised that
580 @code{rationalize (0.1)} does not equal 1/10. This behavior isn't special to
581 Maxima -- the number 1/10 has a repeating, not a terminating, binary
582 representation.
584 @c ===beg===
585 @c rationalize (0.5);
586 @c rationalize (0.1);
587 @c fpprec : 5$
588 @c rationalize (0.1b0);
589 @c fpprec : 20$
590 @c rationalize (0.1b0);
591 @c rationalize (sin (0.1*x + 5.6));
592 @c ===end===
593 @example
594 @group
595 (%i1) rationalize (0.5);
596 1
597 (%o1) -
598 2
599 @end group
600 @group
601 (%i2) rationalize (0.1);
602 3602879701896397
603 (%o2) -----------------
604 36028797018963968
605 @end group
606 (%i3) fpprec : 5$
607 @group
608 (%i4) rationalize (0.1b0);
609 209715
610 (%o4) -------
611 2097152
612 @end group
613 (%i5) fpprec : 20$
614 @group
615 (%i6) rationalize (0.1b0);
616 236118324143482260685
617 (%o6) ----------------------
618 2361183241434822606848
619 @end group
620 @group
621 (%i7) rationalize (sin (0.1*x + 5.6));
622 3602879701896397 x 3152519739159347
623 (%o7) sin(------------------ + ----------------)
624 36028797018963968 562949953421312
625 @end group
626 @end example
628 @opencatbox
629 @category{Numerical evaluation}
630 @closecatbox
631 @end deffn
633 @c -----------------------------------------------------------------------------
634 @anchor{ratnump}
635 @deffn {Function} ratnump (@var{expr})
637 Returns @code{true} if @var{expr} is a literal integer or ratio of literal
638 integers, otherwise @code{false}.
640 @opencatbox
641 @category{Predicate functions}
642 @category{Rational expressions}
643 @closecatbox
644 @end deffn
647 @c -----------------------------------------------------------------------------
648 @page
649 @node Strings, Constants, Numbers, Data Types and Structures
650 @section Strings
651 @c -----------------------------------------------------------------------------
653 @menu
654 * Introduction to Strings::
655 * Functions and Variables for Strings::
656 @end menu
658 @c -----------------------------------------------------------------------------
659 @node Introduction to Strings, Functions and Variables for Strings, Strings, Strings
660 @subsection Introduction to Strings
661 @c -----------------------------------------------------------------------------
663 @cindex backslash
664 @c The following three lines were commented out since they made "make pdf" abort
665 @c with an error:
666 @c @ifnotinfo
667 @c @cindex \
668 @c @end ifnotinfo
669 @ifinfo
670 @c adding the backslash to the index here breaks the LaTeX syntax of the file
671 @c maxima.fns that is created by the first pdfLaTeX run by "make pdf".
672 @end ifinfo
674 Strings (quoted character sequences) are enclosed in double quote marks @code{"}
675 for input, and displayed with or without the quote marks, depending on the
676 global variable @mrefdot{stringdisp}
678 Strings may contain any characters, including embedded tab, newline, and
679 carriage return characters. The sequence @code{\"} is recognized as a literal
680 double quote, and @code{\\} as a literal backslash. When backslash appears at
681 the end of a line, the backslash and the line termination (either newline or
682 carriage return and newline) are ignored, so that the string continues with the
683 next line. No other special combinations of backslash with another character
684 are recognized; when backslash appears before any character other than @code{"},
685 @code{\}, or a line termination, the backslash is ignored. There is no way to
686 represent a special character (such as tab, newline, or carriage return)
687 except by embedding the literal character in the string.
689 There is no character type in Maxima; a single character is represented as a
690 one-character string.
692 The @code{stringproc} add-on package contains many functions for working with
693 strings.
695 Examples:
697 @c ===beg===
698 @c s_1 : "This is a string.";
699 @c s_2 : "Embedded \"double quotes\" and backslash \\ characters.";
700 @c s_3 : "Embedded line termination
701 @c in this string.";
702 @c s_4 : "Ignore the \
703 @c line termination \
704 @c characters in \
705 @c this string.";
706 @c stringdisp : false;
707 @c s_1;
708 @c stringdisp : true;
709 @c s_1;
710 @c ===end===
711 @example
712 @group
713 (%i1) s_1 : "This is a string.";
714 (%o1) This is a string.
715 @end group
716 @group
717 (%i2) s_2 : "Embedded \"double quotes\" and backslash \\ characters.";
718 (%o2) Embedded "double quotes" and backslash \ characters.
719 @end group
720 @group
721 (%i3) s_3 : "Embedded line termination
722 (%o3) Embedded line termination
723 in this string.
724 @end group
725 @group
726 (%i4) in this string.";
727 (%o4) Ignore the line termination characters in this string.
728 @end group
729 @group
730 (%i5) s_4 : "Ignore the \
731 (%o5) false
732 @end group
733 @group
734 (%i6) line termination \
735 (%o6) This is a string.
736 @end group
737 @group
738 (%i7) characters in \
739 (%o7) true
740 @end group
741 @group
742 (%i8) this string.";
743 (%o8) "This is a string."
744 @end group
745 (%i9) stringdisp : false;
746 @end example
748 @opencatbox
749 @category{Syntax}
750 @closecatbox
752 @c -----------------------------------------------------------------------------
753 @node Functions and Variables for Strings, , Introduction to Strings, Strings
754 @subsection Functions and Variables for Strings
755 @c -----------------------------------------------------------------------------
757 @c -----------------------------------------------------------------------------
758 @anchor{concat}
759 @deffn {Function} concat (@var{arg_1}, @var{arg_2}, @dots{})
761 Concatenates its arguments. The arguments must evaluate to atoms. The return
762 value is a symbol if the first argument is a symbol and a string otherwise.
764 @code{concat} evaluates its arguments. The single quote @code{'} prevents
765 evaluation.
767 See also @mrefcomma{sconcat} that works on non-atoms, too, @mrefcomma{simplode}
768 @mref{string} and @mrefdot{eval_string}
769 For complex string conversions see also @mref{printf}.
771 @c ===beg===
772 @c y: 7$
773 @c z: 88$
774 @c concat (y, z/2);
775 @c concat ('y, z/2);
776 @c ===end===
777 @example
778 (%i1) y: 7$
779 (%i2) z: 88$
780 (%i3) concat (y, z/2);
781 (%o3) 744
782 (%i4) concat ('y, z/2);
783 (%o4) y44
784 @end example
786 A symbol constructed by @code{concat} may be assigned a value and appear in
787 expressions. The @mref{::} (double colon) assignment operator evaluates its
788 left-hand side.
790 @c ===beg===
791 @c a: concat ('y, z/2);
792 @c a:: 123;
793 @c y44;
794 @c b^a;
795 @c %, numer;
796 @c ===end===
797 @example
798 (%i5) a: concat ('y, z/2);
799 (%o5) y44
800 (%i6) a:: 123;
801 (%o6) 123
802 (%i7) y44;
803 (%o7) 123
804 (%i8) b^a;
805 @group
806 y44
807 (%o8) b
808 @end group
809 (%i9) %, numer;
810 123
811 (%o9) b
812 @end example
814 Note that although @code{concat (1, 2)} looks like a number, it is a string.
816 @c ===beg===
817 @c concat (1, 2) + 3;
818 @c ===end===
819 @example
820 (%i10) concat (1, 2) + 3;
821 (%o10) 12 + 3
822 @end example
824 @opencatbox
825 @category{Expressions}
826 @category{Strings}
827 @closecatbox
828 @end deffn
830 @c -----------------------------------------------------------------------------
831 @anchor{sconcat}
832 @deffn {Function} sconcat (@var{arg_1}, @var{arg_2}, @dots{})
834 Concatenates its arguments into a string. Unlike @mrefcomma{concat} the
835 arguments do @i{not} need to be atoms.
837 See also @mrefcomma{concat} @mrefcomma{simplode} @mref{string} and @mrefdot{eval_string}
838 For complex string conversions see also @mref{printf}.
840 @c ===beg===
841 @c sconcat ("xx[", 3, "]:", expand ((x+y)^3));
842 @c ===end===
843 @example
844 @group
845 (%i1) sconcat ("xx[", 3, "]:", expand ((x+y)^3));
846 (%o1) xx[3]:y^3+3*x*y^2+3*x^2*y+x^3
847 @end group
848 @end example
850 Another purpose for @code{sconcat} is to convert arbitrary objects to strings.
851 @c ===beg===
852 @c sconcat (x);
853 @c stringp(%);
854 @c ===end===
855 @example
856 @group
857 (%i1) sconcat (x);
858 (%o1) x
859 @end group
860 @group
861 (%i2) stringp(%);
862 (%o2) true
863 @end group
864 @end example
866 @opencatbox
867 @category{Expressions}
868 @category{Strings}
869 @closecatbox
870 @end deffn
872 @c NEEDS CLARIFICATION AND EXAMPLES
874 @c -----------------------------------------------------------------------------
875 @anchor{string}
876 @deffn {Function} string (@var{expr})
878 Converts @code{expr} to Maxima's linear notation just as if it had been typed
879 in.
881 The return value of @code{string} is a string, and thus it cannot be used in a
882 computation.
884 See also @mrefcomma{concat} @mrefcomma{sconcat} @mref{simplode} and
885 @mrefdot{eval_string}
887 @opencatbox
888 @category{Strings}
889 @closecatbox
890 @end deffn
892 @c SHOULD BE WRITTEN WITH LEADING ? BUT THAT CONFUSES CL-INFO SO WORK AROUND
894 @c -----------------------------------------------------------------------------
895 @anchor{stringdisp}
896 @defvr {Option variable} stringdisp
897 Default value: @code{false}
899 When @code{stringdisp} is @code{true}, strings are displayed enclosed in double
900 quote marks. Otherwise, quote marks are not displayed.
902 @code{stringdisp} is always @code{true} when displaying a function definition.
904 Examples:
906 @c ===beg===
907 @c stringdisp: false$
908 @c "This is an example string.";
909 @c foo () :=
910 @c print ("This is a string in a function definition.");
911 @c stringdisp: true$
912 @c "This is an example string.";
913 @c ===end===
914 @example
915 (%i1) stringdisp: false$
916 @group
917 (%i2) "This is an example string.";
918 (%o2) This is an example string.
919 @end group
920 @group
921 (%i3) foo () :=
922 print ("This is a string in a function definition.");
923 (%o3) foo() :=
924 print("This is a string in a function definition.")
925 @end group
926 (%i4) stringdisp: true$
927 @group
928 (%i5) "This is an example string.";
929 (%o5) "This is an example string."
930 @end group
931 @end example
933 @opencatbox
934 @category{Display flags and variables}
935 @closecatbox
936 @end defvr