doc/info/DataTypes.texi

   1 @menu
   2 * Numbers::
   3 * Strings::
   4 * Constants::
   5 * Lists::
   6 * Arrays::
   7 * Structures::
   8 @end menu
   9
  10 @c -----------------------------------------------------------------------------
  11 @node Numbers, Strings, Data Types and Structures, Data Types and Structures
  12 @section Numbers
  13 @c -----------------------------------------------------------------------------
  14
  15 @menu
  16 * Introduction to Numbers::
  17 * Functions and Variables for Numbers::
  18 @end menu
  19
  20 @c -----------------------------------------------------------------------------
  21 @node Introduction to Numbers, Functions and Variables for Numbers, Numbers, Numbers
  22 @subsection Introduction to Numbers
  23 @c -----------------------------------------------------------------------------
  24
  25 @c -----------------------------------------------------------------------------
  26 @subheading Complex numbers
  27 @c -----------------------------------------------------------------------------
  28
  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.
  37
  38 @opencatbox{Categories:}
  39 @category{Complex variables}
  40 @closecatbox
  41
  42 @c -----------------------------------------------------------------------------
  43 @node Functions and Variables for Numbers, , Introduction to Numbers, Numbers
  44 @subsection Functions and Variables for Numbers
  45 @c -----------------------------------------------------------------------------
  46
  47 @c -----------------------------------------------------------------------------
  48 @anchor{bfloat}
  49 @deffn {Function} bfloat (@var{expr})
  50
  51 @code{bfloat} replaces integers, rationals, floating point numbers, and some symbolic constants
  52 in @var{expr} with bigfloat (variable-precision floating point) numbers.
  53
  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.
  58
  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.
  62
  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}.
  67
  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.
  70
  71 Examples:
  72
  73 @code{bfloat} replaces integers, rationals, floating point numbers, and some symbolic constants
  74 in @var{expr} with bigfloat numbers.
  75
  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
  92
  93 @code{bfloat} also causes numerical evaluation of some built-in functions.
  94
  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
 111
 112 @opencatbox{Categories:}
 113 @category{Numerical evaluation}
 114 @closecatbox
 115 @end deffn
 116
 117 @c -----------------------------------------------------------------------------
 118 @anchor{bfloatp}
 119 @deffn {Function} bfloatp (@var{expr})
 120
 121 Returns @code{true} if @var{expr} is a bigfloat number, otherwise @code{false}.
 122
 123 @opencatbox{Categories:}
 124 @category{Numerical evaluation}
 125 @category{Predicate functions}
 126 @closecatbox
 127 @end deffn
 128
 129 @c --- 03.11.2011 --------------------------------------------------------------
 130 @anchor{bftorat}
 131 @defvr {Option variable} bftorat
 132 Default value: @code{false}
 133
 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.
 139
 140 Note: @code{bftorat} has no effect on the transformation to rational numbers
 141 with the function @mrefdot{rationalize}
 142
 143 Example:
 144
 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
 164
 165 @opencatbox{Categories:}
 166 @category{Numerical evaluation}
 167 @closecatbox
 168 @end defvr
 169
 170 @c -----------------------------------------------------------------------------
 171 @anchor{bftrunc}
 172 @defvr {Option variable} bftrunc
 173 Default value: @code{true}
 174
 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}.
 179
 180 @opencatbox{Categories:}
 181 @category{Numerical evaluation}
 182 @closecatbox
 183 @end defvr
 184
 185 @c -----------------------------------------------------------------------------
 186 @anchor{bigfloat_bits}
 187 @deffn {Function} bigfloat_bits ()
 188 Returns the number of bits of precision in a bigfloat number.  This
 189 value depends, of course, on the value of @mref{fpprec}.
 190
 191 @c ===beg===
 192 @c fpprec:16;
 193 @c bigfloat_bits();
 194 @c fpprec:32;
 195 @c bigfloat_bits();
 196 @c ===end===
 197 @example
 198 (%i1) fpprec:16;
 199 (%o1)                                 16
 200 (%i2) bigfloat_bits();
 201 (%o2)                                 56
 202 (%i3) fpprec:32;
 203 (%o3)                                 32
 204 (%i4) bigfloat_bits();
 205 (%o4)                                 109
 206 @end example
 207
 208 @opencatbox{Categories:}
 209 @category{Numerical evaluation}
 210 @closecatbox
 211 @end deffn
 212
 213 @c -----------------------------------------------------------------------------
 214 @anchor{bigfloat_eps}
 215 @deffn {Function} bigfloat_eps ()
 216 Returns the smallest bigfloat value, @code{eps}, such that
 217 @code{1+eps} is not equal to 1.  The value depends on @mref{fpprec},
 218 of course.
 219
 220 @c ===beg===
 221 @c fpprec:16;
 222 @c bigfloat_eps();
 223 @c fpprec:32;
 224 @c bigfloat_eps();
 225 @c ===end===
 226 @example
 227 (%i1) fpprec:16;
 228 (%o1)                                 16
 229 (%i2) bigfloat_eps();
 230 (%o2)                        1.387778780781446b-17
 231 (%i3) fpprec:32;
 232 (%o3)                                 32
 233 (%i4) bigfloat_eps();
 234 (%o4)                1.5407439555097886824447823540679b-33
 235 @end example
 236 @opencatbox{Categories:}
 237 @category{Numerical evaluation}
 238 @closecatbox
 239 @end deffn
 240
 241 @c -----------------------------------------------------------------------------
 242 @anchor{decode_float}
 243 @deffn {Function} decode_float (@var{f})
 244 @code{decode_float} takes a float @var{f} and returns a list of three
 245 values that characterizes @var{f}, which must be either a @code{float}
 246 or @code{bfloat}.  The first value has the same type as @var{f}, but
 247 is a number in the range @code{[1, 2)}.  The second value is an
 248 exponent.  The third value is a float of the same type as @var{f} and
 249 has the value of 1 if @var{f} is greater than or equal to 0;
 250 otherwise, -1.
 251
 252 If the returned list is @code{[mantissa, expo, sign]}, then
 253 @code{scale_float(mantissa, exp)*sign} is identical to @var{f}.
 254
 255 @example
 256 (%i1) decode_float(4e0);
 257 (%o1)                            [1.0, 2, 1.0]
 258 (%i2) decode_float(4b0);
 259 (%o2)                          [1.0b0, 2, 1.0b0]
 260 (%i3) decode_float(%pi);
 261
 262 decode_float is only defined for floats and bfloats: %pi
 263  -- an error. To debug this try: debugmode(true);
 264 (%i4) decode_float(float(%pi));
 265 (%o4)                     [1.570796326794897, 1, 1.0]
 266 (%i5) decode_float(1.1e-5);
 267 (%o5)                        [1.441792, - 17, 1.0]
 268 (%i6) %[1]*2^%[2];
 269 (%o6)                               1.1e-5
 270 @end example
 271
 272 This is a relatively simple interface to Common Lisp
 273 @url{http://www.lispworks.com/documentation/HyperSpec/Body/f_dec_fl.htm,
 274 decode_float}.  However we return a signficand in the range
 275 @code{[1,2)} instead of @code{[0.5, 1)}.  The former matches
 276 IEEE-754.  Of course, this is extended to support bfloats.
 277
 278 @opencatbox{Categories:}
 279 @category{Numerical evaluation}
 280 @closecatbox
 281 @end deffn
 282
 283 @c -----------------------------------------------------------------------------
 284 @anchor{evenp}
 285 @deffn {Function} evenp (@var{expr})
 286
 287 @c THIS IS STRANGE -- SHOULD RETURN NOUN FORM IF INDETERMINATE
 288 Returns @code{true} if @var{expr} is a literal even integer, otherwise
 289 @code{false}.
 290
 291 @code{evenp} returns @code{false} if @var{expr} is a symbol, even if @var{expr}
 292 is declared @code{even}.
 293
 294 @opencatbox{Categories:}
 295 @category{Predicate functions}
 296 @closecatbox
 297 @end deffn
 298
 299 @c -----------------------------------------------------------------------------
 300 @anchor{float}
 301 @deffn {Function} float (@var{expr})
 302
 303 Converts integers, rational numbers and bigfloats in @var{expr} to floating
 304 point numbers.  It is also an @mrefcomma{evflag} @code{float} causes
 305 non-integral rational numbers and bigfloat numbers to be converted to floating
 306 point.
 307
 308 @opencatbox{Categories:}
 309 @category{Numerical evaluation}
 310 @category{Evaluation flags}
 311 @closecatbox
 312 @end deffn
 313
 314 @c --- 08.10.2010 DK -----------------------------------------------------------
 315 @anchor{float2bf}
 316 @defvr {Option variable} float2bf
 317 Default value: @code{true}
 318
 319 When @mref{float2bf} is @code{false}, a warning message is printed when
 320 a floating point number is replaced by a bigfloat number with less precision.
 321 @c DOES THAT APPLY ONLY TO BFLOAT, OR DO OTHER FUNCTIONS CALL IT ??
 322
 323 @opencatbox{Categories:}
 324 @category{Numerical evaluation}
 325 @closecatbox
 326 @end defvr
 327
 328 @c -----------------------------------------------------------------------------
 329 @anchor{float_bits}
 330 @deffn {Function} float_bits ()
 331 Returns the number of bits of precision of a floating-point number.
 332
 333 @opencatbox{Categories:}
 334 @category{Numerical evaluation}
 335 @closecatbox
 336 @end deffn
 337
 338 @c -----------------------------------------------------------------------------
 339 @anchor{float_eps}
 340 @deffn {Function} float_eps ()
 341 Returns the smallest floating-point value, @code{eps}, such that
 342 @code{1+eps} is not equal to 1.
 343
 344 @opencatbox{Categories:}
 345 @category{Numerical evaluation}
 346 @closecatbox
 347 @end deffn
 348
 349 @c -----------------------------------------------------------------------------
 350 @anchor{float_precision}
 351 @deffn {Function} float_precision (@var{f})
 352 Returns the number of bits of precision of a floating-point number,
 353 which can be either a float or bigfloat.  This is basically the number
 354 of bits used to represent the mantissa of a floating-point number.
 355 For floats, this is 53 (for IEEE double-floats), but can be less when
 356 denormal numbers occur.  For bigfloats, this is equal to
 357 @mref{fpprec}, when converted from digits to bits.
 358
 359 @opencatbox{Categories:}
 360 @category{Numerical evaluation}
 361 @closecatbox
 362 @end deffn
 363
 364 @c -----------------------------------------------------------------------------
 365 @anchor{float_sign}
 366 @deffn {Function} float_sign (@var{f})
 367 Returns the sign of @var{f}.  It is @math{+1} or @math{-1} of the same
 368 type as @var{f}.  It is an error if @var{f} is not a float or
 369 bigfloat.  Note that some lisps do not support signed zeros for
 370 floating-point numbers.  Bigfloats do not support signed zeroes.  The
 371 examples below assume signed zeroes are supported.
 372 @example
 373 (%i1) float_sign(1.0);
 374 (%o1)                                 1.0
 375 (%i2) float_sign(-5.0);
 376 (%o2)                                - 1.0
 377 (%i3) float_sign(-0.0);
 378 (%o3)                                - 1.0
 379 (%i4) float_sign(1b0);
 380 (%o4)                                1.0b0
 381 (%i5) float_sign(-5b0);
 382 (%o5)                               - 1.0b0
 383 (%o6) float_sign(-0b0);
 384 (%o6)                                1.0b0
 385 (%i7) float_sign(%pi);
 386
 387 float_sign is only defined for floats and bfloats: %pi
 388  -- an error. To debug this try: debugmode(true);
 389 @end example
 390 @end deffn
 391
 392 @c -----------------------------------------------------------------------------
 393 @anchor{float_infinity_p}
 394 @deffn {Function} float_infinity_p (@var{x})
 395
 396 Returns @code{true} if @var{x} is floating point positive infinity or floating point negative infinity,
 397 and returns @code{false} for all other arguments;
 398 arguments which are not numbers are allowed,
 399 and @code{float_infinity_p} returns @code{false} for all such arguments.
 400
 401 Positive and negative floating point infinity may be distinguished by @code{sign},
 402 which returns @code{pos} for positive infinity and @code{neg} for negative infinity.
 403
 404 @code{float_infinity_p} is defined whether or not the Lisp implementation supports float infinity.
 405 When float infinity does not exist in the Lisp implementation's number system,
 406 @code{float_infinity_p} returns @code{false} for all arguments.
 407
 408 A Lisp implementation may support more than one precision of floating point numbers.
 409 @code{float_infinity_p} only recognizes double precision floating point infinity,
 410 and not any other precision.
 411
 412 @opencatbox{Categories:}
 413 @category{Numerical evaluation}
 414 @category{Predicate functions}
 415 @closecatbox
 416
 417 @end deffn
 418
 419 @c -----------------------------------------------------------------------------
 420 @anchor{float_nan_p}
 421 @deffn {Function} float_nan_p (@var{x})
 422
 423 Returns @code{true} if @var{x} is a floating point not-a-number (NaN) value,
 424 and returns @code{false} for all other arguments;
 425 arguments which are not numbers are allowed,
 426 and @code{float_nan_p} returns @code{false} for all such arguments.
 427
 428 @code{float_nan_p} is defined whether or not the Lisp implementation supports floating point not-a-number values.
 429 When floating point not-a-number does not exist in the Lisp implementation's number system,
 430 @code{float_nan_p} returns @code{false} for all arguments.
 431
 432 A Lisp implementation may support more than one precision of floating point numbers.
 433 @code{float_nan_p} only recognizes double precision floating point not-a-number,
 434 and not any other precision.
 435
 436 @opencatbox{Categories:}
 437 @category{Numerical evaluation}
 438 @category{Predicate functions}
 439 @closecatbox
 440
 441 @end deffn
 442
 443 @c -----------------------------------------------------------------------------
 444 @anchor{floatnump}
 445 @deffn {Function} floatnump (@var{expr})
 446
 447 Returns @code{true} if @var{expr} is a floating point number, otherwise
 448 @code{false}.
 449
 450 @opencatbox{Categories:}
 451 @category{Numerical evaluation}
 452 @category{Predicate functions}
 453 @closecatbox
 454 @end deffn
 455
 456 @c -----------------------------------------------------------------------------
 457 @anchor{fpprec}
 458 @defvr {Option variable} fpprec
 459 Default value: 16
 460
 461 @code{fpprec} is the number of significant digits for arithmetic on bigfloat
 462 numbers.  @code{fpprec} does not affect computations on ordinary floating point
 463 numbers.
 464
 465 See also @mref{bfloat} and @mrefdot{fpprintprec}
 466
 467 @opencatbox{Categories:}
 468 @category{Numerical evaluation}
 469 @closecatbox
 470 @end defvr
 471
 472 @c -----------------------------------------------------------------------------
 473 @anchor{fpprintprec}
 474 @defvr {Option variable} fpprintprec
 475 Default value: 0
 476
 477 @code{fpprintprec} is the number of digits to print when printing an ordinary
 478 float or bigfloat number.
 479
 480 For ordinary floating point numbers,
 481 when @code{fpprintprec} has a value between 2 and 16 (inclusive),
 482 the number of digits printed is equal to @code{fpprintprec}.
 483 Otherwise, @code{fpprintprec} is 0, or greater than 16,
 484 and the number is printed "readably":
 485 that is, it is printed with sufficient digits to exactly reconstruct the number on input.
 486
 487 For bigfloat numbers,
 488 when @code{fpprintprec} has a value between 2 and @code{fpprec} (inclusive),
 489 the number of digits printed is equal to @code{fpprintprec}.
 490 Otherwise, @code{fpprintprec} is 0, or greater than @code{fpprec},
 491 and the number of digits printed is equal to @code{fpprec}.
 492
 493 For both ordinary floats and bigfloats,
 494 trailing zero digits are suppressed.
 495 The actual number of digits printed is less than @code{fpprintprec}
 496 if there are trailing zero digits.
 497
 498 @code{fpprintprec} cannot be 1.
 499
 500 @opencatbox{Categories:}
 501 @category{Numerical evaluation}
 502 @category{Display flags and variables}
 503 @closecatbox
 504 @end defvr
 505
 506 @c -----------------------------------------------------------------------------
 507 @anchor{integerp}
 508 @deffn {Function} integerp (@var{expr})
 509
 510 Returns @code{true} if @var{expr} is a literal numeric integer, otherwise
 511 @code{false}.
 512
 513 @code{integerp} returns @code{false} if @var{expr} is a symbol, even if @var{expr}
 514 is declared @code{integer}.
 515
 516 Examples:
 517
 518 @c ===beg===
 519 @c integerp (0);
 520 @c integerp (1);
 521 @c integerp (-17);
 522 @c integerp (0.0);
 523 @c integerp (1.0);
 524 @c integerp (%pi);
 525 @c integerp (n);
 526 @c declare (n, integer);
 527 @c integerp (n);
 528 @c ===end===
 529 @example
 530 (%i1) integerp (0);
 531 (%o1)                         true
 532 (%i2) integerp (1);
 533 (%o2)                         true
 534 (%i3) integerp (-17);
 535 (%o3)                         true
 536 (%i4) integerp (0.0);
 537 (%o4)                         false
 538 (%i5) integerp (1.0);
 539 (%o5)                         false
 540 (%i6) integerp (%pi);
 541 (%o6)                         false
 542 (%i7) integerp (n);
 543 (%o7)                         false
 544 (%i8) declare (n, integer);
 545 (%o8)                         done
 546 (%i9) integerp (n);
 547 (%o9)                         false
 548 @end example
 549
 550 @opencatbox{Categories:}
 551 @category{Predicate functions}
 552 @closecatbox
 553 @end deffn
 554
 555 @c -----------------------------------------------------------------------------
 556 @anchor{integer_decode_float}
 557 @deffn {Function} integer_decode_float (@var{f})
 558 @code{integer_decode_float} takes a float @var{f} and returns a list of three
 559 values that characterizes @var{f}, which must be either a @code{float}
 560 or @code{bfloat}.  The first value is an integer.  The second value is an
 561 exponent.  The third value is 1 if @var{f} is positive or zero;
 562 otherwise, -1.
 563
 564 If the returned list is @code{[mantissa, expo, sign]}, then
 565 @code{scale_float(fl(mantissa), expo)*sign} is identical to @var{f}.
 566 Here, @code{fl} is either @code{float} or @code{bfloat} depending on
 567 whether @var{f} is a @code{float} or a @code{bfloat}.
 568
 569 @example
 570 (%i1) integer_decode_float(4.0);
 571 (%o1)                     [4503599627370496, - 50, 1]
 572 (%i2) integer_decode_float(4b0);
 573 (%o2)                    [36028797018963968, - 53, 1]
 574 (%i3) scale_float(float(%o1[1]), %o1[2]);
 575 (%o3)                                 4.0
 576 (%i4) scale_float(bfloat(%o2[1]), %o2[2]);
 577 (%o4)                                4.0b0
 578 (%i5) integer_decode_float(4);
 579
 580 decode_float is only defined for floats and bfloats: 4
 581  -- an error. To debug this try: debugmode(true);
 582 (%i6) integer_decode_float(1e-7);
 583 (%o6)                     [7555786372591432, - 76, 1]
 584 (%i7) integer_decode_float(1b-7);
 585 (%o7)                    [60446290980731459, - 79, 1]
 586 (%i8) scale_float(float(%o6[1]), %o6[2]);
 587 (%o8)                               1.0e-7
 588 @end example
 589
 590 For lisps that support denormal numbers, we have the following results.
 591 @example
 592 (%i1) integer_decode_float(least_positive_float);
 593 (%o1)                           [1, - 1074, 1]
 594 (%i2) integer_decode_float(100*least_positive_float);
 595 (%o2)                          [100, - 1074, 1]
 596 (%i3) integer_decode_float(least_positive_normalized_float);
 597 (%o3)                    [4503599627370496, - 1074, 1]
 598 @end example
 599 The number of bits in the integer part decreases as the denormal
 600 number decreases.  Bfloat numbers do not have denormals because the
 601 exponent is not bounded.
 602
 603 This is a relatively simple interface to Common Lisp
 604 @url{http://www.lispworks.com/documentation/HyperSpec/Body/f_dec_fl.htm,
 605 integer_decode_float}.  However, the integer part can vary depending
 606 on the Lisp implementation; we return the same value, independent of
 607 the Lisp implementation.  Of course, this is extended to support bfloats.
 608
 609 @opencatbox{Categories:}
 610 @category{Numerical evaluation}
 611 @closecatbox
 612 @end deffn
 613
 614 @c -----------------------------------------------------------------------------
 615 @anchor{is_power_of_two}
 616 @deffn {Function} is_power_of_two (@var{n})
 617 @code{is_power_to_two} returns @code{true} if @var{n} is a power of
 618 two and @code{false} otherwise.  @var{n} may be an integer, a
 619 rational, a float, or a big float.
 620
 621 Some examples:
 622 @example
 623 (%i1) is_power_of_two(0);
 624 (%o1)                                false
 625 (%i2) is_power_of_two(4);
 626 (%o2)                                true
 627 (%i3) is_power_of_two(355/113);
 628 (%o3)                                false
 629 (%i4) is_power_of_two(1/32);
 630 (%o4)                                true
 631 (%i5) is_power_of_two(1048576);
 632 (%o5)                                true
 633 (%i6) is_power_of_two(1048575);
 634 (%o6)                                false
 635 (%i7) is_power_of_two(0.0);
 636 (%o7)                                false
 637 (%i8) is_power_of_two(1048576.0);
 638 (%o8)                                true
 639 (%i9) is_power_of_two(1048575.0);
 640 (%o9)                                false
 641 (%i10) is_power_of_two(1/256.0);
 642 (%o10)                               true
 643 (%i11) is_power_of_two(0b0);
 644 (%o11)                               false
 645 (%i12) is_power_of_two(1048576b0);
 646 (%o12)                               true
 647 (%i13) is_power_of_two(1048575b0);
 648 (%o13)                               false
 649 (%i14) is_power_of_two(1/256b0);
 650 (%o14)                               true
 651 @end example
 652
 653 @opencatbox{Categories:}
 654 @category{Predicate functions}
 655 @closecatbox
 656 @end deffn
 657
 658 @c -----------------------------------------------------------------------------
 659 @anchor{m1pbranch}
 660 @defvr {Option variable} m1pbranch
 661 Default value: @code{false}
 662
 663 @code{m1pbranch} is the principal branch for @code{-1} to a power.
 664 Quantities such as @code{(-1)^(1/3)} (that is, an "odd" rational exponent) and
 665 @code{(-1)^(1/4)} (that is, an "even" rational exponent) are handled as follows:
 666
 667 @c REDRAW THIS AS A TABLE
 668 @example
 669               domain:real
 670
 671 (-1)^(1/3):      -1
 672 (-1)^(1/4):   (-1)^(1/4)
 673
 674              domain:complex
 675 m1pbranch:false          m1pbranch:true
 676 (-1)^(1/3)               1/2+%i*sqrt(3)/2
 677 (-1)^(1/4)              sqrt(2)/2+%i*sqrt(2)/2
 678 @end example
 679
 680 @opencatbox{Categories:}
 681 @category{Expressions}
 682 @category{Global flags}
 683 @closecatbox
 684 @end defvr
 685
 686 @c -----------------------------------------------------------------------------
 687 @anchor{nonnegintegerp}
 688 @deffn {Function} nonnegintegerp (@var{n})
 689
 690 Return @code{true} if and only if @code{@var{n} >= 0} and @var{n} is an integer.
 691
 692 @opencatbox{Categories:}
 693 @category{Predicate functions}
 694 @closecatbox
 695 @end deffn
 696
 697 @c -----------------------------------------------------------------------------
 698 @anchor{numberp}
 699 @deffn {Function} numberp (@var{expr})
 700
 701 Returns @code{true} if @var{expr} is a literal integer, rational number,
 702 floating point number, or bigfloat, otherwise @code{false}.
 703
 704 @code{numberp} returns @code{false} if @var{expr} is a symbol, even if @var{expr}
 705 is a symbolic number such as @code{%pi} or @code{%i}, or declared to be
 706 @code{even}, @code{odd}, @code{integer}, @code{rational}, @code{irrational},
 707 @code{real}, @code{imaginary}, or @code{complex}.
 708
 709 Examples:
 710
 711 @c ===beg===
 712 @c numberp (42);
 713 @c numberp (-13/19);
 714 @c numberp (3.14159);
 715 @c numberp (-1729b-4);
 716 @c map (numberp, [%e, %pi, %i, %phi, inf, minf]);
 717 @c declare (a, even, b, odd, c, integer, d, rational,
 718 @c     e, irrational, f, real, g, imaginary, h, complex);
 719 @c map (numberp, [a, b, c, d, e, f, g, h]);
 720 @c ===end===
 721 @example
 722 (%i1) numberp (42);
 723 (%o1)                         true
 724 (%i2) numberp (-13/19);
 725 (%o2)                         true
 726 (%i3) numberp (3.14159);
 727 (%o3)                         true
 728 (%i4) numberp (-1729b-4);
 729 (%o4)                         true
 730 (%i5) map (numberp, [%e, %pi, %i, %phi, inf, minf]);
 731 (%o5)      [false, false, false, false, false, false]
 732 (%i6) declare (a, even, b, odd, c, integer, d, rational,
 733      e, irrational, f, real, g, imaginary, h, complex);
 734 (%o6)                         done
 735 (%i7) map (numberp, [a, b, c, d, e, f, g, h]);
 736 (%o7) [false, false, false, false, false, false, false, false]
 737 @end example
 738
 739 @opencatbox{Categories:}
 740 @category{Predicate functions}
 741 @closecatbox
 742 @end deffn
 743
 744 @c NEEDS CLARIFICATION, EXAMPLES
 745 @c WHAT ARE THE FUNCTIONS WHICH ARE EVALUATED IN FLOATING POINT ??
 746 @c WHAT IS A "NUMERVAL" ?? (SOMETHING DIFFERENT FROM A NUMERIC VALUE ??)
 747 @c NEED TO MENTION THIS IS AN evflag
 748
 749 @c -----------------------------------------------------------------------------
 750 @anchor{numer}
 751 @defvr {Option variable} numer
 752
 753 @code{numer} causes some mathematical functions (including exponentiation)
 754 with numerical arguments to be evaluated in floating point.  It causes
 755 variables in @code{expr} which have been given numerals to be replaced by
 756 their values.  It also sets the @mref{float} switch on.
 757
 758 See also @mrefdot{%enumer}
 759
 760 Examples:
 761
 762 @c ===beg===
 763 @c [sqrt(2), sin(1), 1/(1+sqrt(3))];
 764 @c [sqrt(2), sin(1), 1/(1+sqrt(3))],numer;
 765 @c ===end===
 766 @example
 767 @group
 768 (%i1) [sqrt(2), sin(1), 1/(1+sqrt(3))];
 769                                         1
 770 (%o1)            [sqrt(2), sin(1), -----------]
 771                                    sqrt(3) + 1
 772 @end group
 773 @group
 774 (%i2) [sqrt(2), sin(1), 1/(1+sqrt(3))],numer;
 775 (%o2) [1.414213562373095, 0.8414709848078965, 0.3660254037844387]
 776 @end group
 777 @end example
 778
 779 @opencatbox{Categories:}
 780 @category{Numerical evaluation}
 781 @category{Evaluation flags}
 782 @closecatbox
 783 @end defvr
 784
 785 @c -----------------------------------------------------------------------------
 786 @anchor{numer_pbranch}
 787 @defvr {Option variable} numer_pbranch
 788 Default value: @code{false}
 789
 790 The option variable @code{numer_pbranch} controls the numerical evaluation of
 791 the power of a negative integer, rational, or floating point number.  When
 792 @code{numer_pbranch} is @code{true} and the exponent is a floating point number
 793 or the option variable @mref{numer} is @code{true} too, Maxima evaluates
 794 the numerical result using the principal branch.  Otherwise a simplified, but
 795 not an evaluated result is returned.
 796
 797 Examples:
 798
 799 @c ===beg===
 800 @c (-2)^0.75;
 801 @c (-2)^0.75,numer_pbranch:true;
 802 @c (-2)^(3/4);
 803 @c (-2)^(3/4),numer;
 804 @c (-2)^(3/4),numer,numer_pbranch:true;
 805 @c ===end===
 806 @example
 807 @group
 808 (%i1) (-2)^0.75;
 809                                  0.75
 810 (%o1)                       (- 2)
 811 @end group
 812 @group
 813 (%i2) (-2)^0.75,numer_pbranch:true;
 814 (%o2)       1.189207115002721 %i - 1.189207115002721
 815 @end group
 816 @group
 817 (%i3) (-2)^(3/4);
 818                                3/4  3/4
 819 (%o3)                     (- 1)    2
 820 @end group
 821 @group
 822 (%i4) (-2)^(3/4),numer;
 823                                           0.75
 824 (%o4)              1.681792830507429 (- 1)
 825 @end group
 826 @group
 827 (%i5) (-2)^(3/4),numer,numer_pbranch:true;
 828 (%o5)       1.189207115002721 %i - 1.189207115002721
 829 @end group
 830 @end example
 831
 832 @opencatbox{Categories:}
 833 @category{Numerical evaluation}
 834 @closecatbox
 835 @end defvr
 836
 837 @c NEEDS CLARIFICATION, EXAMPLES
 838 @c HOW TO FIND ALL VARIABLES WHICH HAVE NUMERVALS ??
 839
 840 @c -----------------------------------------------------------------------------
 841 @anchor{numerval}
 842 @deffn {Function} numerval (@var{x_1}, @var{expr_1}, @dots{}, @var{var_n}, @var{expr_n})
 843
 844 Declares the variables @code{x_1}, @dots{}, @var{x_n} to have
 845 numeric values equal to @code{expr_1}, @dots{}, @code{expr_n}.
 846 The numeric value is evaluated and substituted for the variable
 847 in any expressions in which the variable occurs if the @code{numer} flag is
 848 @code{true}.  See also @mrefdot{ev}
 849
 850 The expressions @code{expr_1}, @dots{}, @code{expr_n} can be any expressions,
 851 not necessarily numeric.
 852
 853 @opencatbox{Categories:}
 854 @category{Declarations and inferences}
 855 @category{Numerical evaluation}
 856 @closecatbox
 857 @end deffn
 858
 859 @c -----------------------------------------------------------------------------
 860 @anchor{oddp}
 861 @deffn {Function} oddp (@var{expr})
 862
 863 @c THIS IS STRANGE -- SHOULD RETURN NOUN FORM IF INDETERMINATE
 864 Returns @code{true} if @var{expr} is a literal odd integer, otherwise
 865 @code{false}.
 866
 867 @code{oddp} returns @code{false} if @var{expr} is a symbol, even if @var{expr}
 868 is declared @code{odd}.
 869
 870 @opencatbox{Categories:}
 871 @category{Predicate functions}
 872 @closecatbox
 873 @end deffn
 874
 875 @c --- 03.11.2011 --------------------------------------------------------------
 876 @anchor{ratepsilon}
 877 @defvr {Option variable} ratepsilon
 878 Default value: @code{2.0e-15}
 879
 880 @code{ratepsilon} is the tolerance used in the conversion
 881 of floating point numbers to rational numbers, when the option variable
 882 @mref{bftorat} has the value @code{false}.  See @code{bftorat} for an example.
 883
 884 @opencatbox{Categories:}
 885 @category{Numerical evaluation}
 886 @category{Rational expressions}
 887 @closecatbox
 888 @end defvr
 889
 890 @c -----------------------------------------------------------------------------
 891 @anchor{rationalize}
 892 @deffn {Function} rationalize (@var{expr})
 893
 894 Convert all double floats and big floats in the Maxima expression @var{expr} to
 895 their exact rational equivalents.  If you are not familiar with the binary
 896 representation of floating point numbers, you might be surprised that
 897 @code{rationalize (0.1)} does not equal 1/10.  This behavior isn't special to
 898 Maxima -- the number 1/10 has a repeating, not a terminating, binary
 899 representation.
 900
 901 @c ===beg===
 902 @c rationalize (0.5);
 903 @c rationalize (0.1);
 904 @c fpprec : 5$
 905 @c rationalize (0.1b0);
 906 @c fpprec : 20$
 907 @c rationalize (0.1b0);
 908 @c rationalize (sin (0.1*x + 5.6));
 909 @c ===end===
 910 @example
 911 @group
 912 (%i1) rationalize (0.5);
 913                                 1
 914 (%o1)                           -
 915                                 2
 916 @end group
 917 @group
 918 (%i2) rationalize (0.1);
 919                         3602879701896397
 920 (%o2)                   -----------------
 921                         36028797018963968
 922 @end group
 923 (%i3) fpprec : 5$
 924 @group
 925 (%i4) rationalize (0.1b0);
 926                              209715
 927 (%o4)                        -------
 928                              2097152
 929 @end group
 930 (%i5) fpprec : 20$
 931 @group
 932 (%i6) rationalize (0.1b0);
 933                      236118324143482260685
 934 (%o6)                ----------------------
 935                      2361183241434822606848
 936 @end group
 937 @group
 938 (%i7) rationalize (sin (0.1*x + 5.6));
 939                3602879701896397 x   3152519739159347
 940 (%o7)      sin(------------------ + ----------------)
 941                36028797018963968    562949953421312
 942 @end group
 943 @end example
 944
 945 @opencatbox{Categories:}
 946 @category{Numerical evaluation}
 947 @closecatbox
 948 @end deffn
 949
 950 @c -----------------------------------------------------------------------------
 951 @anchor{ratnump}
 952 @deffn {Function} ratnump (@var{expr})
 953
 954 Returns @code{true} if @var{expr} is a literal integer or ratio of literal
 955 integers, otherwise @code{false}.
 956
 957 @opencatbox{Categories:}
 958 @category{Predicate functions}
 959 @category{Rational expressions}
 960 @closecatbox
 961 @end deffn
 962
 963 @c -----------------------------------------------------------------------------
 964 @anchor{scale_float}
 965 @deffn {Function} scale_float (@var{f}, @var{n})
 966 @code{scale_float} scales the float @var{f} by the value
 967 @code{2^@var{n}}.  This is done carefully so that no round-off every
 968 occurs.  If @var{f} is a float, then it is possible to underflow to 0
 969 or overflow, depending on the value of @var{f} and @var{n}.  Bigfloats
 970 cannot underflow or overflow.
 971
 972 @example
 973 (%i1) scale_float(2d0, 2);
 974 (%o1)                                 8.0
 975 (%i2) scale_float(2d0, -2);
 976 (%o2)                                 0.5
 977 (%i3) scale_float(-2d0, -10);
 978 (%o3)                            - 0.001953125
 979 (%i4) scale_float(1d0, -2000);
 980 (%o4)                                 0.0
 981 (%i5) scale_float(2b0, 2);
 982 (%o5)                                8.0b0
 983 (%i6) scale_float(1b0, -2000);
 984 (%o6)                       8.709809816217217b-603
 985 (%i7) scale_float(1, 5);
 986
 987 scale_float: first arg must be a float or bfloat: 1
 988  -- an error. To debug this try: debugmode(true);
 989 (%i8) scale_float(1.0, n);
 990
 991 scale_float: second arg must be an integer: n
 992  -- an error. To debug this try: debugmode(true);
 993 @end example
 994
 995 This is a relatively simple interface to Common Lisp
 996 @url{http://www.lispworks.com/documentation/HyperSpec/Body/f_dec_fl.htm,
 997 scale_float}.  Of course, this is extended to support bfloats.
 998
 999 @end deffn
1000
1001 @c -----------------------------------------------------------------------------
1002 @anchor{unit_in_last_place}
1003 @deffn {Function} unit_in_last_place (@var{n})
1004
1005 @code{unit_in_last_place} returns a value that is the gap between
1006 @var{n} and the nearest other number.  See, for example,
1007 @url{https://people.eecs.berkeley.edu/~wkahan/LOG10HAF.TXT,
1008 Kahan@comma{} FOOTNOTE 1}.  @code{unit_in_last_place} supports rational numbers,
1009 floating-point numbers and bigfloat numbers.  For integer, the result
1010 is always 1, and for rational numbers the result is always 0.
1011
1012 The examples below assume
1013 @url{https://en.wikipedia.org/wiki/IEEE_754,IEEE-754} arithmetic that
1014 supports
1015 @url{https://en.wikipedia.org/wiki/IEEE_754-1985#Denormalized_numbers,denormal}
1016 numbers.  Some lisps like @url{https://clisp.sourceforge.io/, Clisp}
1017 do not have denormal numbers.
1018
1019 @example
1020 (%i1) unit_in_last_place(0);
1021 (%o1)                                  1
1022 (%i2) unit_in_last_place(-123);
1023 (%o2)                                  1
1024 (%i3) unit_in_last_place(2/3);
1025 (%o3)                                  0
1026 (%i4) unit_in_last_place(355/113);
1027 (%o4)                                  0
1028 (%i5) unit_in_last_place(0b0);
1029 (%o5)                                0.0b0
1030 (%i6) unit_in_last_place(0.0);
1031 (%o6)                       4.940656458412465e-324
1032 (%i7) unit_in_last_place(1.0);
1033 (%o7)                        1.110223024625157e-16
1034 (%i8) unit_in_last_place(1b0);
1035 (%o8)                        1.387778780781446b-17
1036 (%i9) unit_in_last_place(100.0);
1037 (%o9)                         1.4210854715202e-14
1038 (%i10) unit_in_last_place(100b0);
1039 (%o10)                       1.77635683940025b-15
1040 (%i11) fpprec:32;
1041 (%o11)                                32
1042 (%i12) unit_in_last_place(1b0);
1043 (%o12)               1.5407439555097886824447823540679b-33
1044 (%i13) unit_in_last_place(100b0);
1045 (%o13)               1.972152263052529513529321413207b-31
1046 @end example
1047
1048 @opencatbox{Categories:}
1049 @category{Numerical evaluation}
1050 @closecatbox
1051
1052 @end deffn
1053
1054 @c -----------------------------------------------------------------------------
1055 @page
1056 @node Strings, Constants, Numbers, Data Types and Structures
1057 @section Strings
1058 @c -----------------------------------------------------------------------------
1059
1060 @menu
1061 * Introduction to Strings::
1062 * Functions and Variables for Strings::
1063 @end menu
1064
1065 @c -----------------------------------------------------------------------------
1066 @node Introduction to Strings, Functions and Variables for Strings, Strings, Strings
1067 @subsection Introduction to Strings
1068 @c -----------------------------------------------------------------------------
1069
1070 @cindex backslash
1071 @c The following three lines were commented out since they made "make pdf" abort
1072 @c with an error:
1073 @c @ifnotinfo
1074 @c @cindex \
1075 @c @end ifnotinfo
1076 @ifinfo
1077 @c adding the backslash to the index here breaks the LaTeX syntax of the file
1078 @c maxima.fns that is created by the first pdfLaTeX run by "make pdf".
1079 @end ifinfo
1080
1081 Strings (quoted character sequences) are enclosed in double quote marks @code{"}
1082 for input, and displayed with or without the quote marks, depending on the
1083 global variable @mrefdot{stringdisp}
1084
1085 Strings may contain any characters, including embedded tab, newline, and
1086 carriage return characters.  The sequence @code{\"} is recognized as a literal
1087 double quote, and @code{\\} as a literal backslash.  When backslash appears at
1088 the end of a line, the backslash and the line termination (either newline or
1089 carriage return and newline) are ignored, so that the string continues with the
1090 next line.  No other special combinations of backslash with another character
1091 are recognized; when backslash appears before any character other than @code{"},
1092 @code{\}, or a line termination, the backslash is ignored.  There is no way to
1093 represent a special character (such as tab, newline, or carriage return)
1094 except by embedding the literal character in the string.
1095
1096 There is no character type in Maxima; a single character is represented as a
1097 one-character string.
1098
1099 The @code{stringproc} add-on package contains many functions for working with
1100 strings.
1101
1102 Examples:
1103
1104 @c ===beg===
1105 @c s_1 : "This is a string.";
1106 @c s_2 : "Embedded \"double quotes\" and backslash \\ characters.";
1107 @c s_3 : "Embedded line termination
1108 @c in this string.";
1109 @c s_4 : "Ignore the \
1110 @c line termination \
1111 @c characters in \
1112 @c this string.";
1113 @c stringdisp : false;
1114 @c s_1;
1115 @c stringdisp : true;
1116 @c s_1;
1117 @c ===end===
1118 @example
1119 @group
1120 (%i1) s_1 : "This is a string.";
1121 (%o1)                   This is a string.
1122 @end group
1123 @group
1124 (%i2) s_2 : "Embedded \"double quotes\" and backslash \\ characters.";
1125 (%o2) Embedded "double quotes" and backslash \ characters.
1126 @end group
1127 @group
1128 (%i3) s_3 : "Embedded line termination
1129 in this string.";
1130 (%o3) Embedded line termination
1131 in this string.
1132 @end group
1133 @group
1134 (%i4) s_4 : "Ignore the \
1135 line termination \
1136 characters in \
1137 this string.";
1138 (%o4) Ignore the line termination characters in this string.
1139 @end group
1140 @group
1141 (%i5) stringdisp : false;
1142 (%o5)                         false
1143 @end group
1144 @group
1145 (%i6) s_1;
1146 (%o6)                   This is a string.
1147 @end group
1148 @group
1149 (%i7) stringdisp : true;
1150 (%o7)                         true
1151 @end group
1152 @group
1153 (%i8) s_1;
1154 (%o8)                  "This is a string."
1155 @end group
1156 @end example
1157
1158 @opencatbox{Categories:}
1159 @category{Syntax}
1160 @closecatbox
1161
1162 @c -----------------------------------------------------------------------------
1163 @node Functions and Variables for Strings, , Introduction to Strings, Strings
1164 @subsection Functions and Variables for Strings
1165 @c -----------------------------------------------------------------------------
1166
1167 @c -----------------------------------------------------------------------------
1168 @anchor{concat}
1169 @deffn {Function} concat (@var{arg_1}, @var{arg_2}, @dots{})
1170
1171 Concatenates its arguments.  The arguments must evaluate to atoms.  The return
1172 value is a symbol if the first argument is a symbol and a string otherwise.
1173
1174 @code{concat} evaluates its arguments.  The single quote @code{'} prevents
1175 evaluation.
1176
1177 See also @mrefcomma{sconcat} that works on non-atoms, too, @mrefcomma{simplode}
1178 @mref{string} and @mrefdot{eval_string}
1179 For complex string conversions see also @mref{printf}.
1180
1181 @c ===beg===
1182 @c y: 7$
1183 @c z: 88$
1184 @c concat (y, z/2);
1185 @c concat ('y, z/2);
1186 @c ===end===
1187 @example
1188 (%i1) y: 7$
1189 (%i2) z: 88$
1190 (%i3) concat (y, z/2);
1191 (%o3)                          744
1192 (%i4) concat ('y, z/2);
1193 (%o4)                          y44
1194 @end example
1195
1196 A symbol constructed by @code{concat} may be assigned a value and appear in
1197 expressions.  The @mref{::} (double colon) assignment operator evaluates its
1198 left-hand side.
1199
1200 @c ===beg===
1201 @c a: concat ('y, z/2);
1202 @c a:: 123;
1203 @c y44;
1204 @c b^a;
1205 @c %, numer;
1206 @c ===end===
1207 @example
1208 (%i5) a: concat ('y, z/2);
1209 (%o5)                          y44
1210 (%i6) a:: 123;
1211 (%o6)                          123
1212 (%i7) y44;
1213 (%o7)                          123
1214 (%i8) b^a;
1215                                y44
1216 (%o8)                         b
1217 (%i9) %, numer;
1218                                123
1219 (%o9)                         b
1220 @end example
1221
1222 Note that although @code{concat (1, 2)} looks like a number, it is a string.
1223
1224 @c ===beg===
1225 @c concat (1, 2) + 3;
1226 @c ===end===
1227 @example
1228 (%i10) concat (1, 2) + 3;
1229 (%o10)                       12 + 3
1230 @end example
1231
1232 @opencatbox{Categories:}
1233 @category{Expressions}
1234 @category{Strings}
1235 @closecatbox
1236 @end deffn
1237
1238 @c -----------------------------------------------------------------------------
1239 @anchor{sconcat}
1240 @deffn {Function} sconcat (@var{arg_1}, @var{arg_2}, @dots{})
1241
1242 Concatenates its arguments into a string.  Unlike @mrefcomma{concat} the
1243 arguments do @i{not} need to be atoms.
1244
1245 See also @mrefcomma{concat} @mrefcomma{simplode} @mref{string} and @mrefdot{eval_string}
1246 For complex string conversions see also @mref{printf}.
1247
1248 @c ===beg===
1249 @c sconcat ("xx[", 3, "]:", expand ((x+y)^3));
1250 @c ===end===
1251 @example
1252 @group
1253 (%i1) sconcat ("xx[", 3, "]:", expand ((x+y)^3));
1254 (%o1)             xx[3]:y^3+3*x*y^2+3*x^2*y+x^3
1255 @end group
1256 @end example
1257
1258 Another purpose for @code{sconcat} is to convert arbitrary objects to strings.
1259 @c ===beg===
1260 @c sconcat (x);
1261 @c stringp(%);
1262 @c ===end===
1263 @example
1264 @group
1265 (%i1) sconcat (x);
1266 (%o1)                           x
1267 @end group
1268 @group
1269 (%i2) stringp(%);
1270 (%o2)                         true
1271 @end group
1272 @end example
1273
1274 @opencatbox{Categories:}
1275 @category{Expressions}
1276 @category{Strings}
1277 @closecatbox
1278 @end deffn
1279
1280 @c NEEDS CLARIFICATION AND EXAMPLES
1281
1282 @c -----------------------------------------------------------------------------
1283 @anchor{string}
1284 @deffn {Function} string (@var{expr})
1285
1286 Converts @code{expr} to Maxima's linear notation just as if it had been typed
1287 in.
1288
1289 The return value of @code{string} is a string, and thus it cannot be used in a
1290 computation.
1291
1292 See also @mrefcomma{concat} @mrefcomma{sconcat} @mref{simplode} and
1293 @mrefdot{eval_string}
1294
1295 @opencatbox{Categories:}
1296 @category{Strings}
1297 @closecatbox
1298 @end deffn
1299
1300 @c SHOULD BE WRITTEN WITH LEADING ? BUT THAT CONFUSES CL-INFO SO WORK AROUND
1301
1302 @c -----------------------------------------------------------------------------
1303 @anchor{stringdisp}
1304 @defvr {Option variable} stringdisp
1305 Default value: @code{false}
1306
1307 When @code{stringdisp} is @code{true}, strings are displayed enclosed in double
1308 quote marks.  Otherwise, quote marks are not displayed.
1309
1310 @code{stringdisp} is always @code{true} when displaying a function definition.
1311
1312 Examples:
1313
1314 @c ===beg===
1315 @c stringdisp: false$
1316 @c "This is an example string.";
1317 @c foo () :=
1318 @c       print ("This is a string in a function definition.");
1319 @c stringdisp: true$
1320 @c "This is an example string.";
1321 @c ===end===
1322 @example
1323 (%i1) stringdisp: false$
1324 @group
1325 (%i2) "This is an example string.";
1326 (%o2)              This is an example string.
1327 @end group
1328 @group
1329 (%i3) foo () :=
1330       print ("This is a string in a function definition.");
1331 (%o3) foo() :=
1332               print("This is a string in a function definition.")
1333 @end group
1334 (%i4) stringdisp: true$
1335 @group
1336 (%i5) "This is an example string.";
1337 (%o5)             "This is an example string."
1338 @end group
1339 @end example
1340
1341 @opencatbox{Categories:}
1342 @category{Display flags and variables}
1343 @closecatbox
1344 @end defvr
1345