@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 -----------------------------------------------------------------------------
@subheading Floating point numbers
@c -----------------------------------------------------------------------------

Maxima has two types of floating point number. The first is just
called a ``float'' (but will be called a ``machine float'' for the
rest of this section to avoid ambiguity). This is stored in the
underlying lisp's DOUBLE-FLOAT type which will almost certainly be
IEEE 754 double precision floating point. To type a literal floating
point number, just type its decimal expansion (for example,
@code{0.01}) or type it with an explicit exponent (such as @code{1e-2}
or @code{0.1e-1}).

The second type of floating point number in Maxima is called a
``bigfloat''. Bigfloats are stored as a mantissa and exponent in the
same way as machine floats but the exponent is an arbitrary precision
integer, so they can represent arbitrarily large or small numbers. The
user can also customise the precision of bigfloat arithmetic (which
corresponds to choosing the range of the mantissa). See @mref{fpprec}
for more information. To type a literal bigfloat, use the exponent
notation as above but with the character @code{b} in place of
@code{e}. The example of @code{0.01} from above could be entered as a
bigfloat with @code{1b-2} or @code{0.001b0}.

Calculations using machine floats can be significantly faster than
using bigfloats since modern computer processors have dedicated
hardware for them. This is particularly noticeable with compiled
Maxima code. However, machine floats suffer from the problem of
overflow, where a number can become too large for its exponent to be
represented in the bits available. In interpreted code, the default
behaviour is that a calculation that would cause a floating point
overflow instead generates a bigfloat number. To configure this, see
the @mref{promote_float_to_bigfloat} variable.

@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})

Returns @code{true} if @var{expr} is an even integer.
@c THIS IS STRANGE -- SHOULD RETURN NOUN FORM IF INDETERMINATE
@code{false} is returned in all other cases.

@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}.

@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 its argument is a symbol,
even if the argument is declared 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 its argument is a symbol, even if the
argument 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
(%i1) [sqrt(2), sin(1), 1/(1+sqrt(3))];
                                        1
(%o1)            [sqrt(2), sin(1), -----------]
                                   sqrt(3) + 1
(%i2) [sqrt(2), sin(1), 1/(1+sqrt(3))],numer;
(%o2) [1.414213562373095, .8414709848078965, .3660254037844387]
@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
(%i1) (-2)^0.75;
(%o1) (-2)^0.75

(%i2) (-2)^0.75,numer_pbranch:true;
(%o2) 1.189207115002721*%i-1.189207115002721

(%i3) (-2)^(3/4);
(%o3) (-1)^(3/4)*2^(3/4)

(%i4) (-2)^(3/4),numer;
(%o4) 1.681792830507429*(-1)^0.75

(%i5) (-2)^(3/4),numer,numer_pbranch:true;
(%o5) 1.189207115002721*%i-1.189207115002721
@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})

is @code{true} if @var{expr} is an odd integer.
@c THIS IS STRANGE -- SHOULD RETURN NOUN FORM IF INDETERMINATE
@code{false} is returned in all other cases.

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

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

When @code{promote_float_to_bigfloat} is true, the result of any
floating point calculation that would normally cause a floating point
overflow is replaced by a bigfloat number that represents the
result. Note that this automatic promotion only happens in interpreted
code: compiled code is not affected.

This automatic conversion is often convenient, but can be unhelpful in
some cases. For example, it can actually cause a loss of precision if
@mref{fpprec} is currently smaller than the precision in a floating
point number. To disable this behaviour, set
@code{promote_float_to_bigfloat} to false.

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

@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
(%i1) rationalize (0.5);
                                1
(%o1)                           -
                                2
(%i2) rationalize (0.1);
                               1
(%o2)                          --
                               10
(%i3) fpprec : 5$
(%i4) rationalize (0.1b0);
                             209715
(%o4)                        -------
                             2097152
(%i5) fpprec : 20$
(%i6) rationalize (0.1b0);
                     236118324143482260685
(%o6)                ----------------------
                     2361183241434822606848
(%i7) rationalize (sin (0.1*x + 5.6));
                              x    28
(%o7)                     sin(-- + --)
                              10   5
@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
@ifnotinfo
@cindex \
@end ifnotinfo
@ifinfo
@cindex \\
@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
(%i1) s_1 : "This is a string.";
(%o1)               This is a string.
(%i2) s_2 : "Embedded \"double quotes\" and backslash \\ characters.";
(%o2) Embedded "double quotes" and backslash \ characters.
(%i3) s_3 : "Embedded line termination
in this string.";
(%o3) Embedded line termination
in this string.
(%i4) s_4 : "Ignore the \
line termination \
characters in \
this string.";
(%o4) Ignore the line termination characters in this string.
(%i5) stringdisp : false;
(%o5)                         false
(%i6) s_1;
(%o6)                   This is a string.
(%i7) stringdisp : true;
(%o7)                         true
(%i8) s_1;
(%o8)                  "This is a string."
@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.

@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.

@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$
(%i2) "This is an example string.";
(%o2)              This is an example string.
@group
(%i3) foo () :=
      print ("This is a string in a function definition.");
@end group
(%o3) foo() := 
              print("This is a string in a function definition.")
(%i4) stringdisp: true$
(%i5) "This is an example string.";
(%o5)             "This is an example string."
@end example

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

