@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{Categories:}
@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})

@code{bfloat} replaces integers, rationals, floating point numbers, and some symbolic constants
in @var{expr} with bigfloat (variable-precision floating point) numbers.

The constants @code{%e}, @code{%gamma}, @code{%phi}, and @code{%pi}
are replaced by a numerical approximation.
However, @code{%e} in @code{%e^x} is not replaced by a numeric value
unless @code{bfloat(x)} is a number.

@code{bfloat} also causes numerical evaluation of some built-in functions,
namely trigonometric functions, exponential functions, @code{abs}, and @code{log}.
@c ALSO ENTIER BUT LET'S NOT GO INTO IT.

The number of significant digits in the resulting bigfloats is specified by the
global variable @mrefdot{fpprec}
Bigfloats already present in @var{expr} are replaced with values which have
precision specified by the current value of @mref{fpprec}.

When @mref{float2bf} is @code{false}, a warning message is printed when
a floating point number is replaced by a bigfloat number with less precision.

Examples:

@code{bfloat} replaces integers, rationals, floating point numbers, and some symbolic constants
in @var{expr} with bigfloat numbers.

@c ===beg===
@c bfloat([123, 17/29, 1.75]);
@c bfloat([%e, %gamma, %phi, %pi]);
@c bfloat((f(123) + g(h(17/29)))/(x + %gamma));
@c ===end===
@example
(%i1) bfloat([123, 17/29, 1.75]);
(%o1)        [1.23b2, 5.862068965517241b-1, 1.75b0]
(%i2) bfloat([%e, %gamma, %phi, %pi]);
(%o2) [2.718281828459045b0, 5.772156649015329b-1, 
                        1.618033988749895b0, 3.141592653589793b0]
(%i3) bfloat((f(123) + g(h(17/29)))/(x + %gamma));
         1.0b0 (g(h(5.862068965517241b-1)) + f(1.23b2))
(%o3)    ----------------------------------------------
                    x + 5.772156649015329b-1
@end example

@code{bfloat} also causes numerical evaluation of some built-in functions.

@c ===beg===
@c bfloat(sin(17/29));
@c bfloat(exp(%pi));
@c bfloat(abs(-%gamma));
@c bfloat(log(%phi));
@c ===end===
@example
(%i1) bfloat(sin(17/29));
(%o1)                 5.532051841609784b-1
(%i2) bfloat(exp(%pi));
(%o2)                  2.314069263277927b1
(%i3) bfloat(abs(-%gamma));
(%o3)                 5.772156649015329b-1
(%i4) bfloat(log(%phi));
(%o4)                 4.812118250596035b-1
@end example

@opencatbox{Categories:}
@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{Categories:}
@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:

@c ===beg===
@c ratepsilon:1e-4;
@c rat(bfloat(11111/111111)), bftorat:false;
@c rat(bfloat(11111/111111)), bftorat:true;
@c ===end===
@example
(%i1) ratepsilon:1e-4;
(%o1)                         1.0e-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{Categories:}
@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{Categories:}
@category{Numerical evaluation}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{bigfloat_bits}
@deffn {Function} bigfloat_bits ()
Returns the number of bits of precision in a bigfloat number.  This
value depends, of course, on the value of @mref{fpprec}. 

@c ===beg===
@c fpprec:16;
@c bigfloat_bits();
@c fpprec:32;
@c bigfloat_bits();
@c ===end===
@example
(%i1) fpprec:16;
(%o1)                                 16
(%i2) bigfloat_bits();
(%o2)                                 56
(%i3) fpprec:32;
(%o3)                                 32
(%i4) bigfloat_bits();
(%o4)                                 109
@end example

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

@c -----------------------------------------------------------------------------
@anchor{bigfloat_eps}
@deffn {Function} bigfloat_eps ()
Returns the smallest bigfloat value, @code{eps}, such that
@code{1+eps} is not equal to 1.  The value depends on @mref{fpprec},
of course.

@c ===beg===
@c fpprec:16;
@c bigfloat_eps();
@c fpprec:32;
@c bigfloat_eps();
@c ===end===
@example
(%i1) fpprec:16;
(%o1)                                 16
(%i2) bigfloat_eps();
(%o2)                        1.387778780781446b-17
(%i3) fpprec:32;
(%o3)                                 32
(%i4) bigfloat_eps();
(%o4)                1.5407439555097886824447823540679b-33
@end example
@opencatbox{Categories:}
@category{Numerical evaluation}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{decode_float}
@deffn {Function} decode_float (@var{f})
@code{decode_float} takes a float @var{f} and returns a list of three
values that characterizes @var{f}, which must be either a @code{float}
or @code{bfloat}.  The first value has the same type as @var{f}, but
is a number in the range @code{[1, 2)}.  The second value is an
exponent.  The third value is a float of the same type as @var{f} and
has the value of 1 if @var{f} is greater than or equal to 0;
otherwise, -1.

If the returned list is @code{[mantissa, expo, sign]}, then
@code{scale_float(mantissa, exp)*sign} is identical to @var{f}.

@example
(%i1) decode_float(4e0);
(%o1)                            [1.0, 2, 1.0]
(%i2) decode_float(4b0);
(%o2)                          [1.0b0, 2, 1.0b0]
(%i3) decode_float(%pi);

decode_float is only defined for floats and bfloats: %pi
 -- an error. To debug this try: debugmode(true);
(%i4) decode_float(float(%pi));
(%o4)                     [1.570796326794897, 1, 1.0]
(%i5) decode_float(1.1e-5);
(%o5)                        [1.441792, - 17, 1.0]
(%i6) %[1]*2^%[2];
(%o6)                               1.1e-5
@end example

This is a relatively simple interface to Common Lisp
@url{http://www.lispworks.com/documentation/HyperSpec/Body/f_dec_fl.htm,
decode_float}.  However we return a signficand in the range
@code{[1,2)} instead of @code{[0.5, 1)}.  The former matches
IEEE-754.  Of course, this is extended to support bfloats.

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

@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{Categories:}
@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{Categories:}
@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 @mref{float2bf} is @code{false}, a warning message is printed when
a floating point number is replaced by a bigfloat number with less precision.
@c DOES THAT APPLY ONLY TO BFLOAT, OR DO OTHER FUNCTIONS CALL IT ??

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

@c -----------------------------------------------------------------------------
@anchor{float_bits}
@deffn {Function} float_bits ()
Returns the number of bits of precision of a floating-point number.

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

@c -----------------------------------------------------------------------------
@anchor{float_eps}
@deffn {Function} float_eps ()
Returns the smallest floating-point value, @code{eps}, such that
@code{1+eps} is not equal to 1.

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

@c -----------------------------------------------------------------------------
@anchor{float_precision}
@deffn {Function} float_precision (@var{f})
Returns the number of bits of precision of a floating-point number,
which can be either a float or bigfloat.  This is basically the number
of bits used to represent the mantissa of a floating-point number.
For floats, this is 53 (for IEEE double-floats), but can be less when
denormal numbers occur.  For bigfloats, this is equal to
@mref{fpprec}, when converted from digits to bits.

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

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

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

@opencatbox{Categories:}
@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{Categories:}
@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 is printed "readably":
that is, it is printed with sufficient digits to exactly reconstruct the number on input.

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{Categories:}
@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:

@c ===beg===
@c integerp (0);
@c integerp (1);
@c integerp (-17);
@c integerp (0.0);
@c integerp (1.0);
@c integerp (%pi);
@c integerp (n);
@c declare (n, integer);
@c integerp (n);
@c ===end===
@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{Categories:}
@category{Predicate functions}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{integer_decode_float}
@deffn {Function} integer_decode_float (@var{f})
@code{integer_decode_float} takes a float @var{f} and returns a list of three
values that characterizes @var{f}, which must be either a @code{float}
or @code{bfloat}.  The first value is an integer.  The second value is an
exponent.  The third value is 1 if @var{f} is positive or zero;
otherwise, -1.

If the returned list is @code{[mantissa, expo, sign]}, then
@code{scale_float(fl(mantissa), expo)*sign} is identical to @var{f}.
Here, @code{fl} is either @code{float} or @code{bfloat} depending on
whether @var{f} is a @code{float} or a @code{bfloat}.

@example
(%i1) integer_decode_float(4.0);
(%o1)                     [4503599627370496, - 50, 1]
(%i2) integer_decode_float(4b0);
(%o2)                    [36028797018963968, - 53, 1]
(%i3) scale_float(float(%o1[1]), %o1[2]);
(%o3)                                 4.0
(%i4) scale_float(bfloat(%o2[1]), %o2[2]);
(%o4)                                4.0b0
(%i5) integer_decode_float(4);

decode_float is only defined for floats and bfloats: 4
 -- an error. To debug this try: debugmode(true);
(%i6) integer_decode_float(1e-7);
(%o6)                     [7555786372591432, - 76, 1]
(%i7) integer_decode_float(1b-7);
(%o7)                    [60446290980731459, - 79, 1]
(%i8) scale_float(float(%o6[1]), %o6[2]);
(%o8)                               1.0e-7
@end example

For lisps that support denormal numbers, we have the following results.
@example
(%i1) integer_decode_float(least_positive_float);
(%o1)                           [1, - 1074, 1]
(%i2) integer_decode_float(100*least_positive_float);
(%o2)                          [100, - 1074, 1]
(%i3) integer_decode_float(least_positive_normalized_float);
(%o3)                    [4503599627370496, - 1074, 1]
@end example
The number of bits in the integer part decreases as the denormal
number decreases.  Bfloat numbers do not have denormals because the
exponent is not bounded.

This is a relatively simple interface to Common Lisp
@url{http://www.lispworks.com/documentation/HyperSpec/Body/f_dec_fl.htm,
integer_decode_float}.  However, the integer part can vary depending
on the Lisp implementation; we return the same value, independent of
the Lisp implementation.  Of course, this is extended to support bfloats.

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

@c -----------------------------------------------------------------------------
@anchor{is_power_of_two}
@deffn {Function} is_power_of_two (@var{n})
@code{is_power_to_two} returns @code{true} if @var{n} is a power of
two and @code{false} otherwise.  @var{n} may be an integer, a
rational, a float, or a big float.

Some examples:
@example
(%i1) is_power_of_two(0);
(%o1)                                false
(%i2) is_power_of_two(4);
(%o2)                                true
(%i3) is_power_of_two(355/113);
(%o3)                                false
(%i4) is_power_of_two(1/32);
(%o4)                                true
(%i5) is_power_of_two(1048576);
(%o5)                                true
(%i6) is_power_of_two(1048575);
(%o6)                                false
(%i7) is_power_of_two(0.0);
(%o7)                                false
(%i8) is_power_of_two(1048576.0);
(%o8)                                true
(%i9) is_power_of_two(1048575.0);
(%o9)                                false
(%i10) is_power_of_two(1/256.0);
(%o10)                               true
(%i11) is_power_of_two(0b0);
(%o11)                               false
(%i12) is_power_of_two(1048576b0);
(%o12)                               true
(%i13) is_power_of_two(1048575b0);
(%o13)                               false
(%i14) is_power_of_two(1/256b0);
(%o14)                               true
@end example

@opencatbox{Categories:}
@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{Categories:}
@category{Expressions}
@category{Global flags}
@closecatbox
@end defvr

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

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

@opencatbox{Categories:}
@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:

@c ===beg===
@c numberp (42);
@c numberp (-13/19);
@c numberp (3.14159);
@c numberp (-1729b-4);
@c map (numberp, [%e, %pi, %i, %phi, inf, minf]);
@c declare (a, even, b, odd, c, integer, d, rational,
@c     e, irrational, f, real, g, imaginary, h, complex);
@c map (numberp, [a, b, c, d, e, f, g, h]);
@c ===end===
@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{Categories:}
@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{Categories:}
@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{Categories:}
@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{Categories:}
@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{Categories:}
@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{Categories:}
@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{Categories:}
@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{Categories:}
@category{Predicate functions}
@category{Rational expressions}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{scale_float}
@deffn {Function} scale_float (@var{f}, @var{n})
@code{scale_float} scales the float @var{f} by the value
@code{2^@var{n}}.  This is done carefully so that no round-off every
occurs.  If @var{f} is a float, then it is possible to underflow to 0
or overflow, depending on the value of @var{f} and @var{n}.  Bigfloats
cannot underflow or overflow.

@example
(%i1) scale_float(2d0, 2);
(%o1)                                 8.0
(%i2) scale_float(2d0, -2);
(%o2)                                 0.5
(%i3) scale_float(-2d0, -10);
(%o3)                            - 0.001953125
(%i4) scale_float(1d0, -2000);
(%o4)                                 0.0
(%i5) scale_float(2b0, 2);
(%o5)                                8.0b0
(%i6) scale_float(1b0, -2000);
(%o6)                       8.709809816217217b-603
(%i7) scale_float(1, 5);

scale_float: first arg must be a float or bfloat: 1
 -- an error. To debug this try: debugmode(true);
(%i8) scale_float(1.0, n);

scale_float: second arg must be an integer: n
 -- an error. To debug this try: debugmode(true);
@end example

This is a relatively simple interface to Common Lisp
@url{http://www.lispworks.com/documentation/HyperSpec/Body/f_dec_fl.htm,
scale_float}.  Of course, this is extended to support bfloats.

@end deffn

@c -----------------------------------------------------------------------------
@anchor{unit_in_last_place}
@deffn {Function} unit_in_last_plase (@var{n})

@code{unit_in_last_place} returns a value that is the gap between
@var{n} and the nearest other number.  See, for example,
@url{https://people.eecs.berkeley.edu/~wkahan/LOG10HAF.TXT,
Kahan@comma{} FOOTNOTE 1}.  @code{unit_in_last_place} supports rational numbers,
floating-point numbers and bigfloat numbers.  For integer, the result
is always 1, and for rational numbers the result is always 0.

The examples below assume
@url{https://en.wikipedia.org/wiki/IEEE_754,IEEE-754} arithmetic that
supports
@url{https://en.wikipedia.org/wiki/IEEE_754-1985#Denormalized_numbers,denormal}
numbers.  Some lisps like @url{https://clisp.sourceforge.io/, Clisp}
do not have denormal numbers.

@example
(%i1) unit_in_last_place(0);
(%o1)                                  1
(%i2) unit_in_last_place(-123);
(%o2)                                  1
(%i3) unit_in_last_place(2/3);
(%o3)                                  0
(%i4) unit_in_last_place(355/113);
(%o4)                                  0
(%i5) unit_in_last_place(0b0);
(%o5)                                0.0b0
(%i6) unit_in_last_place(0.0);
(%o6)                       4.940656458412465e-324
(%i7) unit_in_last_place(1.0);
(%o7)                        1.110223024625157e-16
(%i8) unit_in_last_place(1b0);
(%o8)                        1.387778780781446b-17
(%i9) unit_in_last_place(100.0);
(%o9)                         1.4210854715202e-14
(%i10) unit_in_last_place(100b0);
(%o10)                       1.77635683940025b-15
(%i11) fpprec:32;
(%o11)                                32
(%i12) unit_in_last_place(1b0);
(%o12)               1.5407439555097886824447823540679b-33
(%i13) unit_in_last_place(100b0);
(%o13)               1.972152263052529513529321413207b-31
@end example

@opencatbox{Categories:}
@category{Numerical evaluation}
@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
in this string.";
(%o3) Embedded line termination
in this string.
@end group
@group
(%i4) s_4 : "Ignore the \
line termination \
characters in \
this string.";
(%o4) Ignore the line termination characters in this string.
@end group
@group
(%i5) stringdisp : false;
(%o5)                         false
@end group
@group
(%i6) s_1;
(%o6)                   This is a string.
@end group
@group
(%i7) stringdisp : true;
(%o7)                         true
@end group
@group
(%i8) s_1;
(%o8)                  "This is a string."
@end group
@end example

@opencatbox{Categories:}
@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 @mrefcomma{sconcat} that works on non-atoms, too, @mrefcomma{simplode}
@mref{string} and @mrefdot{eval_string}
For complex string conversions see also @mref{printf}.

@c ===beg===
@c y: 7$
@c z: 88$
@c concat (y, z/2);
@c concat ('y, z/2);
@c ===end===
@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.

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

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

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

@opencatbox{Categories:}
@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 @mrefcomma{concat} @mrefcomma{simplode} @mref{string} and @mrefdot{eval_string}
For complex string conversions see also @mref{printf}.

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

Another purpose for @code{sconcat} is to convert arbitrary objects to strings. 
@c ===beg===
@c sconcat (x);
@c stringp(%);
@c ===end===
@example
@group
(%i1) sconcat (x);
(%o1)                           x
@end group
@group
(%i2) stringp(%);
(%o2)                         true
@end group
@end example

@opencatbox{Categories:}
@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.

See also @mrefcomma{concat} @mrefcomma{sconcat} @mref{simplode} and
@mrefdot{eval_string}

@opencatbox{Categories:}
@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{Categories:}
@category{Display flags and variables}
@closecatbox
@end defvr