| blob | 2f92983d8854c3f09bf84f330c34675d62f6cad8 |
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{Categories:}
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{Categories:}
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{Categories:}
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.0e-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{Categories:}
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{Categories:}
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{Categories:}
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{Categories:}
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{Categories:}
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{Categories:}
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{Categories:}
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{Categories:}
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{Categories:}
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{Categories:}
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{Categories:}
376 @category{Predicate functions}
377 @closecatbox
378 @end deffn
380 @c -----------------------------------------------------------------------------
381 @anchor{numberp}
382 @deffn {Function} numberp (@var{expr})
384 Returns @code{true} if @var{expr} is a literal integer, rational number,
385 floating point number, or bigfloat, otherwise @code{false}.
387 @code{numberp} returns @code{false} if @var{expr} is a symbol, even if @var{expr}
388 is a symbolic number such as @code{%pi} or @code{%i}, or declared to be
389 @code{even}, @code{odd}, @code{integer}, @code{rational}, @code{irrational},
390 @code{real}, @code{imaginary}, or @code{complex}.
392 Examples:
394 @c ===beg===
395 @c numberp (42);
396 @c numberp (-13/19);
397 @c numberp (3.14159);
398 @c numberp (-1729b-4);
399 @c map (numberp, [%e, %pi, %i, %phi, inf, minf]);
400 @c declare (a, even, b, odd, c, integer, d, rational,
401 @c 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{Categories:}
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{Categories:}
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{Categories:}
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{Categories:}
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{Categories:}
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{Categories:}
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{Categories:}
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{Categories:}
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 in this string.";
723 (%o3) Embedded line termination
724 in this string.
725 @end group
726 @group
727 (%i4) s_4 : "Ignore the \
728 line termination \
729 characters in \
730 this string.";
731 (%o4) Ignore the line termination characters in this string.
732 @end group
733 @group
734 (%i5) stringdisp : false;
735 (%o5) false
736 @end group
737 @group
738 (%i6) s_1;
739 (%o6) This is a string.
740 @end group
741 @group
742 (%i7) stringdisp : true;
743 (%o7) true
744 @end group
745 @group
746 (%i8) s_1;
747 (%o8) "This is a string."
748 @end group
749 @end example
751 @opencatbox{Categories:}
752 @category{Syntax}
753 @closecatbox
755 @c -----------------------------------------------------------------------------
756 @node Functions and Variables for Strings, , Introduction to Strings, Strings
757 @subsection Functions and Variables for Strings
758 @c -----------------------------------------------------------------------------
760 @c -----------------------------------------------------------------------------
761 @anchor{concat}
762 @deffn {Function} concat (@var{arg_1}, @var{arg_2}, @dots{})
764 Concatenates its arguments. The arguments must evaluate to atoms. The return
765 value is a symbol if the first argument is a symbol and a string otherwise.
767 @code{concat} evaluates its arguments. The single quote @code{'} prevents
768 evaluation.
770 See also @mrefcomma{sconcat} that works on non-atoms, too, @mrefcomma{simplode}
771 @mref{string} and @mrefdot{eval_string}
772 For complex string conversions see also @mref{printf}.
774 @c ===beg===
775 @c y: 7$
776 @c z: 88$
777 @c concat (y, z/2);
778 @c concat ('y, z/2);
779 @c ===end===
780 @example
781 (%i1) y: 7$
782 (%i2) z: 88$
783 (%i3) concat (y, z/2);
784 (%o3) 744
785 (%i4) concat ('y, z/2);
786 (%o4) y44
787 @end example
789 A symbol constructed by @code{concat} may be assigned a value and appear in
790 expressions. The @mref{::} (double colon) assignment operator evaluates its
791 left-hand side.
793 @c ===beg===
794 @c a: concat ('y, z/2);
795 @c a:: 123;
796 @c y44;
797 @c b^a;
798 @c %, numer;
799 @c ===end===
800 @example
801 (%i5) a: concat ('y, z/2);
802 (%o5) y44
803 (%i6) a:: 123;
804 (%o6) 123
805 (%i7) y44;
806 (%o7) 123
807 (%i8) b^a;
808 y44
809 (%o8) b
810 (%i9) %, numer;
811 123
812 (%o9) b
813 @end example
815 Note that although @code{concat (1, 2)} looks like a number, it is a string.
817 @c ===beg===
818 @c concat (1, 2) + 3;
819 @c ===end===
820 @example
821 (%i10) concat (1, 2) + 3;
822 (%o10) 12 + 3
823 @end example
825 @opencatbox{Categories:}
826 @category{Expressions}
827 @category{Strings}
828 @closecatbox
829 @end deffn
831 @c -----------------------------------------------------------------------------
832 @anchor{sconcat}
833 @deffn {Function} sconcat (@var{arg_1}, @var{arg_2}, @dots{})
835 Concatenates its arguments into a string. Unlike @mrefcomma{concat} the
836 arguments do @i{not} need to be atoms.
838 See also @mrefcomma{concat} @mrefcomma{simplode} @mref{string} and @mrefdot{eval_string}
839 For complex string conversions see also @mref{printf}.
841 @c ===beg===
842 @c sconcat ("xx[", 3, "]:", expand ((x+y)^3));
843 @c ===end===
844 @example
845 @group
846 (%i1) sconcat ("xx[", 3, "]:", expand ((x+y)^3));
847 (%o1) xx[3]:y^3+3*x*y^2+3*x^2*y+x^3
848 @end group
849 @end example
851 Another purpose for @code{sconcat} is to convert arbitrary objects to strings.
852 @c ===beg===
853 @c sconcat (x);
854 @c stringp(%);
855 @c ===end===
856 @example
857 @group
858 (%i1) sconcat (x);
859 (%o1) x
860 @end group
861 @group
862 (%i2) stringp(%);
863 (%o2) true
864 @end group
865 @end example
867 @opencatbox{Categories:}
868 @category{Expressions}
869 @category{Strings}
870 @closecatbox
871 @end deffn
873 @c NEEDS CLARIFICATION AND EXAMPLES
875 @c -----------------------------------------------------------------------------
876 @anchor{string}
877 @deffn {Function} string (@var{expr})
879 Converts @code{expr} to Maxima's linear notation just as if it had been typed
880 in.
882 The return value of @code{string} is a string, and thus it cannot be used in a
883 computation.
885 See also @mrefcomma{concat} @mrefcomma{sconcat} @mref{simplode} and
886 @mrefdot{eval_string}
888 @opencatbox{Categories:}
889 @category{Strings}
890 @closecatbox
891 @end deffn
893 @c SHOULD BE WRITTEN WITH LEADING ? BUT THAT CONFUSES CL-INFO SO WORK AROUND
895 @c -----------------------------------------------------------------------------
896 @anchor{stringdisp}
897 @defvr {Option variable} stringdisp
898 Default value: @code{false}
900 When @code{stringdisp} is @code{true}, strings are displayed enclosed in double
901 quote marks. Otherwise, quote marks are not displayed.
903 @code{stringdisp} is always @code{true} when displaying a function definition.
905 Examples:
907 @c ===beg===
908 @c stringdisp: false$
909 @c "This is an example string.";
910 @c foo () :=
911 @c print ("This is a string in a function definition.");
912 @c stringdisp: true$
913 @c "This is an example string.";
914 @c ===end===
915 @example
916 (%i1) stringdisp: false$
917 @group
918 (%i2) "This is an example string.";
919 (%o2) This is an example string.
920 @end group
921 @group
922 (%i3) foo () :=
923 print ("This is a string in a function definition.");
924 (%o3) foo() :=
925 print("This is a string in a function definition.")
926 @end group
927 (%i4) stringdisp: true$
928 @group
929 (%i5) "This is an example string.";
930 (%o5) "This is an example string."
931 @end group
932 @end example
934 @opencatbox{Categories:}
935 @category{Display flags and variables}
936 @closecatbox
937 @end defvr