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

@node Numeric Data Types
@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 by default numeric
constants are represented within Octave in double-precision floating
point format (complex constants are stored as pairs of double-precision
floating point values).  It is however possible to represent real
integers as described in @ref{Integer Data Types}. 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

@noindent
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
@ifnottex
  @code{sqrt (-1)}.
@end ifnottex

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

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

@DOCSTRING(double)

@DOCSTRING(single)

@DOCSTRING(complex)

@menu
* Matrices::                    
* Ranges::                      
* Integer Data Types::
* Logical Values::              
* Predicates for Numeric Objects::  
@end menu

@node Matrices
@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
@ifnottex

@example
@group

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

@end group
@end example
@end ifnottex

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 an expression like

@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 ]}.  Similarly, the expression

@example
[ sin (pi) ]
@end example

@noindent
will be parsed as

@example
[ sin, (pi) ]
@end example

@noindent
and will result in an error since the @code{sin} function will be
called with no arguments.  To get around this, you must omit the space
between @code{sin} and the opening parenthesis, or enclose the
expression in a set of parentheses:

@example
[ (sin (pi)) ]
@end example

Whitespace surrounding the single quote character (@samp{'}, used as a
transpose operator and for delimiting character strings) can also cause
confusion.  Given @code{a = 1}, the expression

@example
[ 1 a' ]
@end example

@noindent
results in the single quote character 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 not doing so would cause trouble when parsing 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.

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.

@DOCSTRING(output_max_field_width)

@DOCSTRING(output_precision)

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

@DOCSTRING(split_long_rows)

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.

@DOCSTRING(fixed_point_format)

@menu
* Empty Matrices::              
@end menu

@node Empty 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
@ifnottex
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 ifnottex

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.

@DOCSTRING(print_empty_dimensions)

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

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.

@node Ranges
@section Ranges
@cindex range expressions
@cindex expression, range

@opindex colon

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 Integer Data Types
@section Integer Data Types

Octave supports integer matrices as an alternative to using double
precision. It is possible to use both signed and unsigned integers
represented by 8, 16, 32, or 64 bits. It should be noted that most
computations require floating point data, meaning that integers will
often change type when involved in numeric computations. For this
reason integers are most often used to store data, and not for
calculations.

In general most integer matrices are created by casting
existing matrices to integers. The following example shows how to cast
a matrix into 32 bit integers.

@example
float = rand (2, 2)
     @result{} float = 0.37569   0.92982
                0.11962   0.50876
integer = int32 (float)
     @result{} integer = 0  1
                  0  1
@end example

@noindent
As can be seen, floating point values are rounded to the nearest integer
when converted.

@DOCSTRING(isinteger)

@DOCSTRING(int8)

@DOCSTRING(uint8)

@DOCSTRING(int16)

@DOCSTRING(uint16)

@DOCSTRING(int32)

@DOCSTRING(uint32)

@DOCSTRING(int64)

@DOCSTRING(uint64)

@DOCSTRING(intmax)

@DOCSTRING(intmin)

@menu
* Integer Arithmetic::
@end menu

@node Integer Arithmetic
@subsection Integer Arithmetic

While many numerical computations can't be carried out in integers,
Octave does support basic operations like addition and multiplication
on integers. The operators @code{+}, @code{-}, @code{.*}, and @code{./}
works on integers of the same type. So, it is possible to add two 32 bit
integers, but not to add a 32 bit integer and a 16 bit integer.

The arithmetic operations on integers are performed by casting the
integer values to double precision values, performing the operation, and
then re-casting the values back to the original integer type. As the
double precision type of Octave is only capable of representing integers
with up to 53 bits of precision, it is not possible to perform
arithmetic of the 64 bit integer types.

When doing integer arithmetic one should consider the possibility of
underflow and overflow. This happens when the result of the computation
can't be represented using the chosen integer type. As an example it is
not possible to represent the result of @math{10 - 20} when using
unsigned integers. Octave makes sure that the result of integer
computations is the integer that is closest to the true result. So, the
result of @math{10 - 20} when using unsigned integers is zero.

When doing integer division Octave will round the result to the nearest
integer. This is different from most programming languages, where the
result is often floored to the nearest integer. So, the result of
@code{int32(5)./int32(8)} is @code{1}.

@node Logical Values
@section Logical Values

Octave has built-in support for logical values, i.e. variables that
are either @code{true} or @code{false}. When comparing two variables,
the result will be a logical value whose value depends on whether or
not the comparison is true.

The basic logical operations are @code{&}, @code{|}, and @code{!},
that corresponds to ``Logical And'', ``Logical Or'', and ``Logical
Negation''. These operations all follow the rules of logic.

It is also possible to use logical values as part of standard numerical
calculations. In this case @code{true} is converted to @code{1}, and
@code{false} to 0, both represented using double precision floating
point numbers. So, the result of @code{true*22 - false/6} is @code{22}.

Logical values can also be used to index matrices and cell arrays.
When indexing with a logical array the result will be a vector containing
the values corresponding to @code{true} parts of the logical array.
The following example illustrates this.

@example
data = [ 1, 2; 3, 4 ];
idx = (data <= 2);
data(idx)
     @result{} ans = [ 1; 4 ]
@end example

@noindent
Instead of creating the @code{idx} array it is possible to replace
@code{data(idx)} with @code{data( data <= 2 )} in the above code.

Besides when doing comparisons, logical values can be constructed by
casting numeric objects to logical values, or by using the @code{true}
or @code{false} functions.

@DOCSTRING(logical)

@DOCSTRING(true)

@DOCSTRING(false)

@node Predicates for Numeric Objects
@section Predicates for Numeric Objects

Since the type of a variable may change during the execution of a
program, it can be necessary to type checking at run-time. Doing this
also allows you to change the behaviour of a function depending on the
type of the input. As an example, this naive implementation of @code{abs}
return the absolute value of the input if it is a real number, and the
length of the input if it is a complex number.

@example
function a = abs (x)
  if (isreal (x))
    a = sign (x) .* x;
  elseif (iscomplex (x))
    a = sqrt (real(x).^2 + imag(x).^2);
  endif
endfunction
@end example

The following functions are available for determining the type of a
variable.

@DOCSTRING(isnumeric)

@DOCSTRING(isreal)

@DOCSTRING(iscomplex)

@DOCSTRING(ismatrix)

@DOCSTRING(isvector)

@DOCSTRING(isscalar)

@DOCSTRING(issquare)

@DOCSTRING(issymmetric)

@DOCSTRING(isdefinite)

@DOCSTRING(islogical)

@DOCSTRING(isprime)