@c Copyright (C) 1996, 1997 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

@node Numeric Data Types, Strings, Data Types, Top
@chapter Numeric Data Types
@cindex numeric constant
@cindex numeric value

A @dfn{numeric constant} may be a scalar, a vector, or a matrix, and it
may contain complex values.

The simplest form of a numeric constant, a scalar, is a single number
that can be an integer, a decimal fraction, a number in scientific
(exponential) notation, or a complex number.  Note that all numeric
constants are represented within Octave in double-precision floating
point format (complex constants are stored as pairs of double-precision
floating point values).  Here are some examples of real-valued numeric
constants, which all have the same value:

@example
@group
105
1.05e+2
1050e-1
@end group
@end example

To specify complex constants, you can write an expression of the form

@example
@group
3 + 4i
3.0 + 4.0i
0.3e1 + 40e-1i
@end group
@end example

all of which are equivalent.  The letter @samp{i} in the previous example
stands for the pure imaginary constant, defined as
@iftex
@tex
  $\sqrt{-1}$.
@end tex
@end iftex
@ifinfo
  @code{sqrt (-1)}.
@end ifinfo

For Octave to recognize a value as the imaginary part of a complex
constant, a space must not appear between the number and the @samp{i}.
If it does, Octave will print an error message, like this:

@example
@group
octave:13> 3 + 4 i

parse error:

  3 + 4 i
        ^
@end group
@end example

You may also use @samp{j}, @samp{I}, or @samp{J} in place of the
@samp{i} above.  All four forms are equivalent.

@menu
* Matrices::                    
* Ranges::                      
* Predicates for Numeric Objects::  
@end menu

@node Matrices, Ranges, Numeric Data Types, Numeric Data Types
@section Matrices
@cindex matrices

@opindex [
@opindex ]
@opindex ;
@opindex ,

It is easy to define a matrix of values in Octave.  The size of the
matrix is determined automatically, so it is not necessary to explicitly
state the dimensions.  The expression

@example
a = [1, 2; 3, 4]
@end example

@noindent
results in the matrix
@iftex
@tex
$$ a = \left[ \matrix{ 1 & 2 \cr 3 & 4 } \right] $$
@end tex
@end iftex
@ifinfo

@example
@group

        /      \
        | 1  2 |
  a  =  |      |
        | 3  4 |
        \      /

@end group
@end example
@end ifinfo

Elements of a matrix may be arbitrary expressions, provided that the
dimensions all make sense when combining the various pieces.  For
example, given the above matrix, the expression

@example
[ a, a ]
@end example

@noindent
produces the matrix

@example
@group
ans =

  1  2  1  2
  3  4  3  4
@end group
@end example

@noindent
but the expression

@example
[ a, 1 ]
@end example

@noindent
produces the error

@example
error: number of rows must match near line 13, column 6
@end example

@noindent
(assuming that this expression was entered as the first thing on line
13, of course).

Inside the square brackets that delimit a matrix expression, Octave
looks at the surrounding context to determine whether spaces and newline
characters should be converted into element and row separators, or
simply ignored, so commands like

@example
[ linspace (1, 2) ]
@end example

@noindent
and

@example
@group
a = [ 1 2
      3 4 ]
@end group
@end example

@noindent
will work.  However, some possible sources of confusion remain.  For
example, in the expression

@example
[ 1 - 1 ]
@end example

@noindent
the @samp{-} is treated as a binary operator and the result is the
scalar 0, but in the expression

@example
[ 1 -1 ]
@end example

@noindent
the @samp{-} is treated as a unary operator and the result is the
vector @code{[ 1, -1 ]}.

Given @code{a = 1}, the expression

@example
[ 1 a' ]
@end example

@noindent
results in the single quote character @samp{'} being treated as a
transpose operator and the result is the vector @code{[ 1, 1 ]}, but the
expression

@example
[ 1 a ' ]
@end example

@noindent
produces the error message

@example
error: unterminated string constant
@end example

@noindent
because to not do so would make it impossible to correctly parse the
valid expression

@example
[ a 'foo' ]
@end example

For clarity, it is probably best to always use commas and semicolons to
separate matrix elements and rows.  It is possible to enforce this style
by setting the built-in variable @code{whitespace_in_literal_matrix} to
@code{"ignore"}.

@defvr {Built-in Variable} whitespace_in_literal_matrix
This variable allows some control over how Octave decides to convert
spaces to commas and semicolons in matrix expressions like
@code{[m (1)]} or

@example
[ 1, 2,
  3, 4 ]
@end example

If the value of @code{whitespace_in_literal_matrix} is @code{"ignore"},
Octave will never insert a comma or a semicolon in a literal matrix
list.  For example, the expression @code{[1 2]} will result in an error
instead of being treated the same as @code{[1, 2]}, and the expression

@example
[ 1, 2,
  3, 4 ]
@end example

@noindent
will result in the vector @code{[ 1, 2, 3, 4 ]} instead of a matrix.

If the value of @code{whitespace_in_literal_matrix} is @code{"traditional"},
Octave will convert spaces to a comma between identifiers and @samp{(}.  For
example, given the matrix

@example
m = [3 2]
@end example

@noindent
the expression

@example
[m (1)]
@end example

@noindent
will be parsed as

@example
[m, (1)]
@end example

@noindent
and will result in

@example
[3 2 1]
@end example

@noindent
and the expression

@example
[ 1, 2,
  3, 4 ]
@end example

@noindent
will result in a matrix because the newline character is converted to a
semicolon (row separator) even though there is a comma at the end of the
first line (trailing commas or semicolons are ignored).  This is
apparently how @sc{Matlab} behaves.

Any other value for @code{whitespace_in_literal_matrix} results in behavior
that is the same as traditional, except that Octave does not
convert spaces to a comma between identifiers and @samp{(}.  For
example, the expression

@example
[m (1)]
@end example

will produce @samp{3}.  This is the way Octave has always behaved.
@end defvr

When you type a matrix or the name of a variable whose value is a
matrix, Octave responds by printing the matrix in with neatly aligned
rows and columns.  If the rows of the matrix are too large to fit on the
screen, Octave splits the matrix and displays a header before each
section to indicate which columns are being displayed.  You can use the
following variables to control the format of the output.

@defvr {Built-in Variable} output_max_field_width
This variable specifies the maximum width of a numeric output field.
The default value is 10.
@end defvr

@defvr {Built-in Variable} output_precision
This variable specifies the minimum number of significant figures to
display for numeric output.  The default value is 5.
@end defvr

It is possible to achieve a wide range of output styles by using
different values of @code{output_precision} and
@code{output_max_field_width}.  Reasonable combinations can be set using
the @code{format} function.  @xref{Basic Input and Output}.

@defvr {Built-in Variable} split_long_rows
For large matrices, Octave may not be able to display all the columns of
a given row on one line of your screen.  This can result in missing
information or output that is nearly impossible to decipher, depending
on whether your terminal truncates or wraps long lines.

If the value of @code{split_long_rows} is nonzero, Octave will display
the matrix in a series of smaller pieces, each of which can fit within
the limits of your terminal width.  Each set of rows is labeled so that
you can easily see which columns are currently being displayed.
For example:

@smallexample
@group
octave:13> rand (2,10)
ans =

 Columns 1 through 6:

  0.75883  0.93290  0.40064  0.43818  0.94958  0.16467
  0.75697  0.51942  0.40031  0.61784  0.92309  0.40201

 Columns 7 through 10:

  0.90174  0.11854  0.72313  0.73326
  0.44672  0.94303  0.56564  0.82150
@end group
@end smallexample

@noindent
The default value of @code{split_long_rows} is nonzero.
@end defvr

Octave automatically switches to scientific notation when values become
very large or very small.  This guarantees that you will see several
significant figures for every value in a matrix.  If you would prefer to
see all values in a matrix printed in a fixed point format, you can set
the built-in variable @code{fixed_point_format} to a nonzero value.  But
doing so is not recommended, because it can produce output that can
easily be misinterpreted.

@defvr {Built-in Variable} fixed_point_format
If the value of this variable is nonzero, Octave will scale all values
in a matrix so that the largest may be written with one leading digit.
The scaling factor is printed on the first line of output.  For example,

@example
@group
octave:1> logspace (1, 7, 5)'
ans =

  1.0e+07  *

  0.00000
  0.00003
  0.00100
  0.03162
  1.00000
@end group
@end example

@noindent
Notice that first value appears to be zero when it is actually 1.  For
this reason, you should be careful when setting
@code{fixed_point_format} to a nonzero value.

The default value of @code{fixed_point_format} is 0.
@end defvr

@menu
* Empty Matrices::              
@end menu

@node Empty Matrices,  , Matrices, Matrices
@subsection Empty Matrices

A matrix may have one or both dimensions zero, and operations on empty
matrices are handled as described by Carl de Boor in @cite{An Empty
Exercise}, SIGNUM, Volume 25, pages 2--6, 1990 and C. N. Nett and W. M.
Haddad, in @cite{A System-Theoretic Appropriate Realization of the Empty
Matrix Concept}, IEEE Transactions on Automatic Control, Volume 38,
Number 5, May 1993.
@iftex
@tex
Briefly, given a scalar $s$, an $m\times n$ matrix $M_{m\times n}$,
and an $m\times n$ empty matrix $[\,]_{m\times n}$ (with either one or
both dimensions equal to zero), the following are true:
$$
\eqalign{%
s \cdot [\,]_{m\times n} = [\,]_{m\times n} \cdot s &= [\,]_{m\times n}\cr
[\,]_{m\times n} + [\,]_{m\times n} &= [\,]_{m\times n}\cr
[\,]_{0\times m} \cdot  M_{m\times n} &= [\,]_{0\times n}\cr
M_{m\times n} \cdot [\,]_{n\times 0} &= [\,]_{m\times 0}\cr
[\,]_{m\times 0} \cdot [\,]_{0\times n} &=  0_{m\times n}}
$$
@end tex
@end iftex
@ifinfo
Briefly, given a scalar @var{s}, an @var{m} by
@var{n} matrix @code{M(mxn)}, and an @var{m} by @var{n} empty matrix
@code{[](mxn)} (with either one or both dimensions equal to zero), the
following are true:

@example
@group
s * [](mxn) = [](mxn) * s = [](mxn)

    [](mxn) + [](mxn) = [](mxn)

    [](0xm) *  M(mxn) = [](0xn)

     M(mxn) * [](nx0) = [](mx0)

    [](mx0) * [](0xn) =  0(mxn)
@end group
@end example
@end ifinfo

By default, dimensions of the empty matrix are printed along with the
empty matrix symbol, @samp{[]}.  The built-in variable
@code{print_empty_dimensions} controls this behavior.

@defvr {Built-in Variable} print_empty_dimensions
If the value of @code{print_empty_dimensions} is nonzero, the
dimensions of empty matrices are printed along with the empty matrix
symbol, @samp{[]}.  For example, the expression

@example
zeros (3, 0)
@end example

@noindent
will print

@example
ans = [](3x0)
@end example
@end defvr

Empty matrices may also be used in assignment statements as a convenient
way to delete rows or columns of matrices.
@xref{Assignment Ops, ,Assignment Expressions}.

Octave will normally issue a warning if it finds an empty matrix in the
list of elements that make up another matrix.  You can use the variable
@code{empty_list_elements_ok} to suppress the warning or to treat it as
an error.

@defvr {Built-in Variable} empty_list_elements_ok
This variable controls whether Octave ignores empty matrices in a matrix
list.

For example, if the value of @code{empty_list_elements_ok} is
nonzero, Octave will ignore the empty matrices in the expression

@example
a = [1, [], 3, [], 5]
@end example

@noindent
and the variable @code{a} will be assigned the value @code{[ 1, 3, 5 ]}.

The default value is @code{"warn"}.
@end defvr

When Octave parses a matrix expression, it examines the elements of the
list to determine whether they are all constants.  If they are, it
replaces the list with a single matrix constant.

@defvr {Built-in Variable} propagate_empty_matrices
If the value of @code{propagate_empty_matrices} is nonzero,
functions like @code{inverse} and @code{svd} will return an empty matrix
if they are given one as an argument.  The default value is 1.
@end defvr

@node Ranges, Predicates for Numeric Objects, Matrices, Numeric Data Types
@section Ranges
@cindex range expressions
@cindex expression, range

@opindex :

A @dfn{range} is a convenient way to write a row vector with evenly
spaced elements.  A range expression is defined by the value of the first
element in the range, an optional value for the increment between
elements, and a maximum value which the elements of the range will not
exceed.  The base, increment, and limit are separated by colons (the
@samp{:} character) and may contain any arithmetic expressions and
function calls.  If the increment is omitted, it is assumed to be 1.
For example, the range

@example
1 : 5
@end example

@noindent
defines the set of values @samp{[ 1, 2, 3, 4, 5 ]}, and the range

@example
1 : 3 : 5
@end example

@noindent
defines the set of values @samp{[ 1, 4 ]}.

Although a range constant specifies a row vector, Octave does @emph{not}
convert range constants to vectors unless it is necessary to do so.
This allows you to write a constant like @samp{1 : 10000} without using
80,000 bytes of storage on a typical 32-bit workstation.

Note that the upper (or lower, if the increment is negative) bound on
the range is not always included in the set of values, and that ranges
defined by floating point values can produce surprising results because
Octave uses floating point arithmetic to compute the values in the
range.  If it is important to include the endpoints of a range and the
number of elements is known, you should use the @code{linspace} function
instead (@pxref{Special Utility Matrices}).

When Octave parses a range expression, it examines the elements of the
expression to determine whether they are all constants.  If they are, it
replaces the range expression with a single range constant.

@node Predicates for Numeric Objects,  , Ranges, Numeric Data Types
@section Predicates for Numeric Objects

@deftypefn {Function File} {} is_matrix (@var{a})
Return 1 if @var{a} is a matrix.  Otherwise, return 0.
@end deftypefn

@deftypefn {Function File} {} is_vector (@var{a})
Return 1 if @var{a} is a vector.  Otherwise, return 0.
@end deftypefn

@deftypefn {Function File} {} is_scalar (@var{a})
Return 1 if @var{a} is a scalar.  Otherwise, return 0.
@end deftypefn

@deftypefn {Function File} {} is_square (@var{x})
If @var{x} is a square matrix, then return the dimension of @var{x}.
Otherwise, return 0.
@end deftypefn

@deftypefn {Function File} {} is_symmetric (@var{x}, @var{tol})
If @var{x} is symmetric within the tolerance specified by @var{tol}, 
then return the dimension of @var{x}.  Otherwise, return 0.  If
@var{tol} is omitted, use a tolerance equal to the machine precision.
@end deftypefn