--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/interpreter/numbers.txi	Tue Oct 19 10:08:42 1999 +0000
@@ -0,0 +1,571 @@
+@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