@menu
* Numbers::
* Strings::
* Constants::
* Lists::
* Arrays::
* Structures::
@end menu

@c -----------------------------------------------------------------------------
@node Numbers, Strings, Data Types and Structures, Data Types and Structures
@section Numbers
@c -----------------------------------------------------------------------------

@menu
* Introduction to Numbers::
* Functions and Variables for Numbers::
@end menu

@c -----------------------------------------------------------------------------
@node Introduction to Numbers, Functions and Variables for Numbers, Numbers, Numbers
@subsection Introduction to Numbers
@c -----------------------------------------------------------------------------

@c -----------------------------------------------------------------------------
@subheading Complex numbers
@c -----------------------------------------------------------------------------

A complex expression is specified in Maxima by adding the real part of the
expression to @code{%i} times the imaginary part.  Thus the roots of the
equation @code{x^2 - 4*x + 13 = 0} are @code{2 + 3*%i} and @code{2 - 3*%i}.
Note that simplification of products of complex expressions can be effected by
expanding the product.  Simplification of quotients, roots, and other functions
of complex expressions can usually be accomplished by using the @code{realpart},
@code{imagpart}, @code{rectform}, @code{polarform}, @code{abs}, @code{carg}
functions.

@opencatbox
@category{Complex variables}
@closecatbox

@c -----------------------------------------------------------------------------
@node Functions and Variables for Numbers, , Introduction to Numbers, Numbers
@subsection Functions and Variables for Numbers
@c -----------------------------------------------------------------------------

@c -----------------------------------------------------------------------------
@anchor{bfloat}
@deffn {Function} bfloat (@var{expr})

Converts all numbers and functions of numbers in @var{expr} to bigfloat numbers.
The number of significant digits in the resulting bigfloats is specified by the
global variable @mrefdot{fpprec}

When @mref{float2bf} is @code{false} a warning message is printed when
a floating point number is converted into a bigfloat number (since
this may lead to loss of precision).

@opencatbox
@category{Numerical evaluation}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{bfloatp}
@deffn {Function} bfloatp (@var{expr})

Returns @code{true} if @var{expr} is a bigfloat number, otherwise @code{false}.

@opencatbox
@category{Numerical evaluation} @category{Predicate functions}
@closecatbox
@end deffn

@c --- 03.11.2011 --------------------------------------------------------------
@anchor{bftorat}
@defvr {Option variable} bftorat
Default value: @code{false}

@code{bftorat} controls the conversion of bfloats to rational numbers.  When
@code{bftorat} is @code{false}, @mref{ratepsilon} will be used to control the
conversion (this results in relatively small rational numbers).  When
@code{bftorat} is @code{true}, the rational number generated will accurately
represent the bfloat.

Note: @code{bftorat} has no effect on the transformation to rational numbers
with the function @mrefdot{rationalize}

Example:

@example
(%i1) ratepsilon:1e-4;
(%o1)                         1.e-4
(%i2) rat(bfloat(11111/111111)), bftorat:false;
`rat' replaced 9.99990999991B-2 by 1/10 = 1.0B-1
                               1
(%o2)/R/                       --
                               10
(%i3) rat(bfloat(11111/111111)), bftorat:true;
`rat' replaced 9.99990999991B-2 by 11111/111111 = 9.99990999991B-2
                             11111
(%o3)/R/                     ------
                             111111
@end example

@opencatbox
@category{Numerical evaluation}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{bftrunc}
@defvr {Option variable} bftrunc
Default value: @code{true}

@code{bftrunc} causes trailing zeroes in non-zero bigfloat numbers not to be
displayed.  Thus, if @code{bftrunc} is @code{false}, @code{bfloat (1)}
displays as @code{1.000000000000000B0}.  Otherwise, this is displayed as
@code{1.0B0}.

@opencatbox
@category{Numerical evaluation}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{evenp}
@deffn {Function} evenp (@var{expr})

@c THIS IS STRANGE -- SHOULD RETURN NOUN FORM IF INDETERMINATE
Returns @code{true} if @var{expr} is a literal even integer, otherwise
@code{false}.

@code{evenp} returns @code{false} if @var{expr} is a symbol, even if @var{expr}
is declared @code{even}.

@opencatbox
@category{Predicate functions}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{float}
@deffn {Function} float (@var{expr})

Converts integers, rational numbers and bigfloats in @var{expr} to floating
point numbers.  It is also an @mrefcomma{evflag} @code{float} causes
non-integral rational numbers and bigfloat numbers to be converted to floating
point.

@opencatbox
@category{Numerical evaluation} @category{Evaluation flags}
@closecatbox
@end deffn

@c --- 08.10.2010 DK -----------------------------------------------------------
@anchor{float2bf}
@defvr {Option variable} float2bf
Default value: @code{true}
 
When @code{float2bf} is @code{false}, a warning message is printed when
a floating point number is converted into a bigfloat number (since
this may lead to loss of precision).

@opencatbox
@category{Numerical evaluation}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{floatnump}
@deffn {Function} floatnump (@var{expr})

Returns @code{true} if @var{expr} is a floating point number, otherwise
@code{false}.

@opencatbox
@category{Numerical evaluation} @category{Predicate functions}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{fpprec}
@defvr {Option variable} fpprec
Default value: 16

@code{fpprec} is the number of significant digits for arithmetic on bigfloat
numbers.  @code{fpprec} does not affect computations on ordinary floating point
numbers.

See also @mref{bfloat} and @mrefdot{fpprintprec}

@opencatbox
@category{Numerical evaluation}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{fpprintprec}
@defvr {Option variable} fpprintprec
Default value: 0

@code{fpprintprec} is the number of digits to print when printing an ordinary
float or bigfloat number.

For ordinary floating point numbers,
when @code{fpprintprec} has a value between 2 and 16 (inclusive),
the number of digits printed is equal to @code{fpprintprec}.
Otherwise, @code{fpprintprec} is 0, or greater than 16,
and the number of digits printed is 16.

For bigfloat numbers,
when @code{fpprintprec} has a value between 2 and @code{fpprec} (inclusive),
the number of digits printed is equal to @code{fpprintprec}.
Otherwise, @code{fpprintprec} is 0, or greater than @code{fpprec},
and the number of digits printed is equal to @code{fpprec}.

For both ordinary floats and bigfloats,
trailing zero digits are suppressed.
The actual number of digits printed is less than @code{fpprintprec}
if there are trailing zero digits.

@code{fpprintprec} cannot be 1.

@opencatbox
@category{Numerical evaluation} @category{Display flags and variables}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{integerp}
@deffn {Function} integerp (@var{expr})

Returns @code{true} if @var{expr} is a literal numeric integer, otherwise
@code{false}.

@code{integerp} returns @code{false} if @var{expr} is a symbol, even if @var{expr}
is declared @code{integer}.

Examples:

@example
(%i1) integerp (0);
(%o1)                         true
(%i2) integerp (1);
(%o2)                         true
(%i3) integerp (-17);
(%o3)                         true
(%i4) integerp (0.0);
(%o4)                         false
(%i5) integerp (1.0);
(%o5)                         false
(%i6) integerp (%pi);
(%o6)                         false
(%i7) integerp (n);
(%o7)                         false
(%i8) declare (n, integer);
(%o8)                         done
(%i9) integerp (n);
(%o9)                         false
@end example

@opencatbox
@category{Predicate functions}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{m1pbranch}
@defvr {Option variable} m1pbranch
Default value: @code{false}

@code{m1pbranch} is the principal branch for @code{-1} to a power.
Quantities such as @code{(-1)^(1/3)} (that is, an "odd" rational exponent) and 
@code{(-1)^(1/4)} (that is, an "even" rational exponent) are handled as follows:

@c REDRAW THIS AS A TABLE
@example
              domain:real
                            
(-1)^(1/3):      -1         
(-1)^(1/4):   (-1)^(1/4)   

             domain:complex              
m1pbranch:false          m1pbranch:true
(-1)^(1/3)               1/2+%i*sqrt(3)/2
(-1)^(1/4)              sqrt(2)/2+%i*sqrt(2)/2
@end example

@opencatbox
@category{Expressions} @category{Global flags}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@deffn {Function} nonnegintegerp (@var{n})

Return @code{true} if and only if @code{@var{n} >= 0} and @var{n} is an integer.

@opencatbox
@category{Package linearalgebra} @category{Predicate functions}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{numberp}
@deffn {Function} numberp (@var{expr})

Returns @code{true} if @var{expr} is a literal integer, rational number, 
floating point number, or bigfloat, otherwise @code{false}.

@code{numberp} returns @code{false} if @var{expr} is a symbol, even if @var{expr}
is a symbolic number such as @code{%pi} or @code{%i}, or declared to be
@code{even}, @code{odd}, @code{integer}, @code{rational}, @code{irrational},
@code{real}, @code{imaginary}, or @code{complex}.

Examples:

@example
(%i1) numberp (42);
(%o1)                         true
(%i2) numberp (-13/19);
(%o2)                         true
(%i3) numberp (3.14159);
(%o3)                         true
(%i4) numberp (-1729b-4);
(%o4)                         true
(%i5) map (numberp, [%e, %pi, %i, %phi, inf, minf]);
(%o5)      [false, false, false, false, false, false]
(%i6) declare (a, even, b, odd, c, integer, d, rational,
     e, irrational, f, real, g, imaginary, h, complex);
(%o6)                         done
(%i7) map (numberp, [a, b, c, d, e, f, g, h]);
(%o7) [false, false, false, false, false, false, false, false]
@end example

@opencatbox
@category{Predicate functions}
@closecatbox
@end deffn

@c NEEDS CLARIFICATION, EXAMPLES
@c WHAT ARE THE FUNCTIONS WHICH ARE EVALUATED IN FLOATING POINT ??
@c WHAT IS A "NUMERVAL" ?? (SOMETHING DIFFERENT FROM A NUMERIC VALUE ??)
@c NEED TO MENTION THIS IS AN evflag

@c -----------------------------------------------------------------------------
@anchor{numer}
@defvr {Option variable} numer

@code{numer} causes some mathematical functions (including exponentiation)
with numerical arguments to be evaluated in floating point.  It causes
variables in @code{expr} which have been given numerals to be replaced by
their values.  It also sets the @mref{float} switch on.

See also @mrefdot{%enumer}

Examples:

@c ===beg===
@c [sqrt(2), sin(1), 1/(1+sqrt(3))];
@c [sqrt(2), sin(1), 1/(1+sqrt(3))],numer;
@c ===end===
@example
@group
(%i1) [sqrt(2), sin(1), 1/(1+sqrt(3))];
                                        1
(%o1)            [sqrt(2), sin(1), -----------]
                                   sqrt(3) + 1
@end group
@group
(%i2) [sqrt(2), sin(1), 1/(1+sqrt(3))],numer;
(%o2) [1.414213562373095, 0.8414709848078965, 0.3660254037844387]
@end group
@end example

@opencatbox
@category{Numerical evaluation} @category{Evaluation flags}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{numer_pbranch}
@defvr {Option variable} numer_pbranch
Default value: @code{false}

The option variable @code{numer_pbranch} controls the numerical evaluation of 
the power of a negative integer, rational, or floating point number.  When
@code{numer_pbranch} is @code{true} and the exponent is a floating point number
or the option variable @mref{numer} is @code{true} too, Maxima evaluates
the numerical result using the principal branch.  Otherwise a simplified, but
not an evaluated result is returned.

Examples:

@c ===beg===
@c (-2)^0.75;
@c (-2)^0.75,numer_pbranch:true;
@c (-2)^(3/4);
@c (-2)^(3/4),numer;
@c (-2)^(3/4),numer,numer_pbranch:true;
@c ===end===
@example
@group
(%i1) (-2)^0.75;
                                 0.75
(%o1)                       (- 2)
@end group
@group
(%i2) (-2)^0.75,numer_pbranch:true;
(%o2)       1.189207115002721 %i - 1.189207115002721
@end group
@group
(%i3) (-2)^(3/4);
                               3/4  3/4
(%o3)                     (- 1)    2
@end group
@group
(%i4) (-2)^(3/4),numer;
                                          0.75
(%o4)              1.681792830507429 (- 1)
@end group
@group
(%i5) (-2)^(3/4),numer,numer_pbranch:true;
(%o5)       1.189207115002721 %i - 1.189207115002721
@end group
@end example

@opencatbox
@category{Numerical evaluation}
@closecatbox
@end defvr

@c NEEDS CLARIFICATION, EXAMPLES
@c HOW TO FIND ALL VARIABLES WHICH HAVE NUMERVALS ??

@c -----------------------------------------------------------------------------
@anchor{numerval}
@deffn {Function} numerval (@var{x_1}, @var{expr_1}, @dots{}, @var{var_n}, @var{expr_n})

Declares the variables @code{x_1}, @dots{}, @var{x_n} to have
numeric values equal to @code{expr_1}, @dots{}, @code{expr_n}.
The numeric value is evaluated and substituted for the variable
in any expressions in which the variable occurs if the @code{numer} flag is
@code{true}.  See also @mrefdot{ev}

The expressions @code{expr_1}, @dots{}, @code{expr_n} can be any expressions,
not necessarily numeric.

@opencatbox
@category{Declarations and inferences} @category{Numerical evaluation}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{oddp}
@deffn {Function} oddp (@var{expr})

@c THIS IS STRANGE -- SHOULD RETURN NOUN FORM IF INDETERMINATE
Returns @code{true} if @var{expr} is a literal odd integer, otherwise
@code{false}.

@code{oddp} returns @code{false} if @var{expr} is a symbol, even if @var{expr}
is declared @code{odd}.

@opencatbox
@category{Predicate functions}
@closecatbox
@end deffn

@c --- 03.11.2011 --------------------------------------------------------------
@anchor{ratepsilon}
@defvr {Option variable} ratepsilon
Default value: @code{2.0e-15}

@code{ratepsilon} is the tolerance used in the conversion
of floating point numbers to rational numbers, when the option variable
@mref{bftorat} has the value @code{false}.  See @code{bftorat} for an example.

@opencatbox
@category{Numerical evaluation} @category{Rational expressions}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{rationalize}
@deffn {Function} rationalize (@var{expr})

Convert all double floats and big floats in the Maxima expression @var{expr} to
their exact rational equivalents.  If you are not familiar with the binary
representation of floating point numbers, you might be surprised that
@code{rationalize (0.1)} does not equal 1/10.  This behavior isn't special to
Maxima -- the number 1/10 has a repeating, not a terminating, binary
representation.

@c ===beg===
@c rationalize (0.5);
@c rationalize (0.1);
@c fpprec : 5$
@c rationalize (0.1b0);
@c fpprec : 20$
@c rationalize (0.1b0);
@c rationalize (sin (0.1*x + 5.6));
@c ===end===
@example
@group
(%i1) rationalize (0.5);
                                1
(%o1)                           -
                                2
@end group
@group
(%i2) rationalize (0.1);
                        3602879701896397
(%o2)                   -----------------
                        36028797018963968
@end group
(%i3) fpprec : 5$
@group
(%i4) rationalize (0.1b0);
                             209715
(%o4)                        -------
                             2097152
@end group
(%i5) fpprec : 20$
@group
(%i6) rationalize (0.1b0);
                     236118324143482260685
(%o6)                ----------------------
                     2361183241434822606848
@end group
@group
(%i7) rationalize (sin (0.1*x + 5.6));
               3602879701896397 x   3152519739159347
(%o7)      sin(------------------ + ----------------)
               36028797018963968    562949953421312
@end group
@end example

@opencatbox
@category{Numerical evaluation}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{ratnump}
@deffn {Function} ratnump (@var{expr})

Returns @code{true} if @var{expr} is a literal integer or ratio of literal
integers, otherwise @code{false}.

@opencatbox
@category{Predicate functions} @category{Rational expressions}
@closecatbox
@end deffn


@c -----------------------------------------------------------------------------
@page
@node Strings, Constants, Numbers, Data Types and Structures
@section Strings
@c -----------------------------------------------------------------------------

@menu
* Introduction to Strings::
* Functions and Variables for Strings::
@end menu

@c -----------------------------------------------------------------------------
@node Introduction to Strings, Functions and Variables for Strings, Strings, Strings
@subsection Introduction to Strings
@c -----------------------------------------------------------------------------

@cindex backslash
@c The following three lines were commented out since they made "make pdf" abort
@c with an error:
@c @ifnotinfo
@c @cindex \
@c @end ifnotinfo
@ifinfo
@c adding the backslash to the index here breaks the LaTeX syntax of the file
@c maxima.fns that is created by the first pdfLaTeX run by "make pdf".
@end ifinfo

Strings (quoted character sequences) are enclosed in double quote marks @code{"}
for input, and displayed with or without the quote marks, depending on the
global variable @mrefdot{stringdisp}

Strings may contain any characters, including embedded tab, newline, and
carriage return characters.  The sequence @code{\"} is recognized as a literal
double quote, and @code{\\} as a literal backslash.  When backslash appears at
the end of a line, the backslash and the line termination (either newline or
carriage return and newline) are ignored, so that the string continues with the
next line.  No other special combinations of backslash with another character
are recognized; when backslash appears before any character other than @code{"},
@code{\}, or a line termination, the backslash is ignored.  There is no way to
represent a special character (such as tab, newline, or carriage return)
except by embedding the literal character in the string.

There is no character type in Maxima; a single character is represented as a
one-character string.

The @code{stringproc} add-on package contains many functions for working with
strings.

Examples:

@c ===beg===
@c s_1 : "This is a string.";
@c s_2 : "Embedded \"double quotes\" and backslash \\ characters.";
@c s_3 : "Embedded line termination
@c in this string.";
@c s_4 : "Ignore the \
@c line termination \
@c characters in \
@c this string.";
@c stringdisp : false;
@c s_1;
@c stringdisp : true;
@c s_1;
@c ===end===
@example
@group
(%i1) s_1 : "This is a string.";
(%o1)                   This is a string.
@end group
@group
(%i2) s_2 : "Embedded \"double quotes\" and backslash \\ characters.";
(%o2) Embedded "double quotes" and backslash \ characters.
@end group
@group
(%i3) s_3 : "Embedded line termination
(%o3) Embedded line termination
in this string.
@end group
@group
(%i4) in this string.";
(%o4) Ignore the line termination characters in this string.
@end group
@group
(%i5) s_4 : "Ignore the \
(%o5)                         false
@end group
@group
(%i6) line termination \
(%o6)                   This is a string.
@end group
@group
(%i7) characters in \
(%o7)                         true
@end group
@group
(%i8) this string.";
(%o8)                  "This is a string."
@end group
(%i9) stringdisp : false;
@end example

@opencatbox
@category{Syntax}
@closecatbox

@c -----------------------------------------------------------------------------
@node Functions and Variables for Strings, , Introduction to Strings, Strings
@subsection Functions and Variables for Strings
@c -----------------------------------------------------------------------------

@c -----------------------------------------------------------------------------
@anchor{concat}
@deffn {Function} concat (@var{arg_1}, @var{arg_2}, @dots{})

Concatenates its arguments.  The arguments must evaluate to atoms.  The return
value is a symbol if the first argument is a symbol and a string otherwise.

@code{concat} evaluates its arguments.  The single quote @code{'} prevents
evaluation.

See also @mref{sconcat} and @mrefdot{eval_string}

@example
(%i1) y: 7$
(%i2) z: 88$
(%i3) concat (y, z/2);
(%o3)                          744
(%i4) concat ('y, z/2);
(%o4)                          y44
@end example

A symbol constructed by @code{concat} may be assigned a value and appear in
expressions.  The @mref{::} (double colon) assignment operator evaluates its
left-hand side.

@example
(%i5) a: concat ('y, z/2);
(%o5)                          y44
(%i6) a:: 123;
(%o6)                          123
(%i7) y44;
(%o7)                          123
(%i8) b^a;
@group
                               y44
(%o8)                         b
@end group
(%i9) %, numer;
                               123
(%o9)                         b
@end example

Note that although @code{concat (1, 2)} looks like a number, it is a string.

@example
(%i10) concat (1, 2) + 3;
(%o10)                       12 + 3
@end example

@opencatbox
@category{Expressions} @category{Strings}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{sconcat}
@deffn {Function} sconcat (@var{arg_1}, @var{arg_2}, @dots{})

Concatenates its arguments into a string.  Unlike @mrefcomma{concat} the
arguments do @i{not} need to be atoms.

See also @mref{concat} and @mrefdot{eval_string}

@example
(%i1) sconcat ("xx[", 3, "]:", expand ((x+y)^3));
(%o1)               xx[3]:y^3+3*x*y^2+3*x^2*y+x^3
@end example

@opencatbox
@category{Expressions} @category{Strings}
@closecatbox
@end deffn

@c NEEDS CLARIFICATION AND EXAMPLES

@c -----------------------------------------------------------------------------
@anchor{string}
@deffn {Function} string (@var{expr})

Converts @code{expr} to Maxima's linear notation just as if it had been typed
in.

The return value of @code{string} is a string, and thus it cannot be used in a
computation.

@opencatbox
@category{Strings}
@closecatbox
@end deffn

@c SHOULD BE WRITTEN WITH LEADING ? BUT THAT CONFUSES CL-INFO SO WORK AROUND

@c -----------------------------------------------------------------------------
@anchor{stringdisp}
@defvr {Option variable} stringdisp
Default value: @code{false}

When @code{stringdisp} is @code{true}, strings are displayed enclosed in double
quote marks.  Otherwise, quote marks are not displayed.

@code{stringdisp} is always @code{true} when displaying a function definition.

Examples:

@c ===beg===
@c stringdisp: false$
@c "This is an example string.";
@c foo () := 
@c       print ("This is a string in a function definition.");
@c stringdisp: true$
@c "This is an example string.";
@c ===end===
@example
(%i1) stringdisp: false$
@group
(%i2) "This is an example string.";
(%o2)              This is an example string.
@end group
@group
(%i3) foo () :=
      print ("This is a string in a function definition.");
(%o3) foo() := 
              print("This is a string in a function definition.")
@end group
(%i4) stringdisp: true$
@group
(%i5) "This is an example string.";
(%o5)             "This is an example string."
@end group
@end example

@opencatbox
@category{Display flags and variables}
@closecatbox
@end defvr

