Mercurial > jwe > octave
changeset 2449:31d5588dbb61
[project @ 1996-10-30 22:58:44 by jwe]
line wrap: on
line diff
--- a/doc/interpreter/amuse.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/amuse.texi Wed Oct 30 23:00:41 1996 +0000 @@ -6,22 +6,24 @@ @node Amusements, Emacs, Programming Utilities, Top @chapter Amusements -@findex texas_lotto @cindex lottery numbers @cindex numbers, lottery +@deftypefn {Function File} {} texas_lotto () Octave cannot promise that you will actually win the lotto, but it can pick your numbers for you. The function @code{texas_lotto} will select six numbers between 1 and 50. +@end deftypefn -@findex list_primes @cindex prime numbers @cindex numbers, prime -The function @code{list_primes (@var{n})} uses a brute-force algorithm to -compute the first @var{n} primes. +@deftypefn {Function File} {} list_primes (@var{n}) +Computes the first @var{n} primes using a brute-force algorithm. +@end deftypefn @findex casesen @findex flops @findex exit @findex quit +@findex warranty Other amusing functions include @code{casesen}, @code{flops}, -@code{sombrero}, @code{exit}, and @code{quit}. +@code{sombrero}, @code{exit}, @code{quit}, and @code{warranty}.
--- a/doc/interpreter/arith.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/arith.texi Wed Oct 30 23:00:41 1996 +0000 @@ -14,33 +14,38 @@ * Trigonometry:: * Sums and Products:: * Special Functions:: +* Mathematical Constants:: @end menu @node Utility Functions, Complex Arithmetic, Arithmetic, Arithmetic @section Utility Functions The following functions are available for working with complex numbers. -Each expects a single argument, and given a matrix, they work on an -element by element basis. +Each expects a single argument. They are called @dfn{mapping functions} +because when given a matrix argument, they apply the given function to +each element of the matrix. -@ftable @code -@item ceil (@var{x}) +@deftypefn {Mapping Function} {} ceil (@var{x}) Return the smallest integer not less than @var{x}. If @var{x} is complex, return @code{ceil (real (@var{x})) + ceil (imag (@var{x})) * I}. +@end deftypefn -@item floor (@var{x}) +@deftypefn {Mapping Function} {} floor (@var{x}) Return the largest integer not greater than @var{x}. If @var{x} is complex, return @code{floor (real (@var{x})) + floor (imag (@var{x})) * I}. +@end deftypefn -@item fix (@var{x}) +@deftypefn {Mapping Function} {} fix (@var{x}) Truncate @var{x} toward zero. If @var{x} is complex, return @code{fix (real (@var{x})) + fix (imag (@var{x})) * I}. +@end deftypefn -@item round (@var{x}) +@deftypefn {Mapping Function} {} round (@var{x}) Return the integer nearest to @var{x}. If @var{x} is complex, return @code{round (real (@var{x})) + round (imag (@var{x})) * I}. +@end deftypefn -@item sign (@var{x}) +@deftypefn {Mapping Function} {} sign (@var{x}) Compute the @dfn{signum} function, which is defined as @iftex @tex @@ -59,12 +64,14 @@ @end ifinfo For complex arguments, @code{sign} returns @code{x ./ abs (@var{x})}. +@end deftypefn -@item exp (@var{x}) +@deftypefn {Mapping Function} {} exp (@var{x}) Compute the exponential of @var{x}. To compute the matrix exponential, see @ref{Linear Algebra}. +@end deftypefn -@item gcd (@var{x}, @code{...}) +@deftypefn {Mapping Function} {} gcd (@var{x}, @code{...}) Compute the greatest common divisor of the elements of @var{x}, or the list of all the arguments. For example, @@ -85,8 +92,9 @@ @example g = v(1) * a(k) + ... + v(k) * a(k) @end example +@end deftypefn -@item lcm (@var{x}, @code{...}) +@deftypefn {Mapping Function} {} lcm (@var{x}, @code{...}) Compute the least common multiple of the elements elements of @var{x}, or the list of all the arguments. For example, @@ -100,22 +108,27 @@ @example lcm ([a1, ..., ak]). @end example +@end deftypefn -@item log (@var{x}) +@deftypefn {Mapping Function} {} log (@var{x}) Compute the natural logarithm of @var{x}. To compute the matrix logarithm, see @ref{Linear Algebra}. +@end deftypefn -@item log2 (@var{x}) +@deftypefn {Mapping Function} {} log2 (@var{x}) Compute the base-2 logarithm of @var{x}. +@end deftypefn -@item log10 (@var{x}) +@deftypefn {Mapping Function} {} log10 (@var{x}) Compute the base-10 logarithm of @var{x}. +@end deftypefn -@item sqrt (@var{x}) +@deftypefn {Mapping Function} {} sqrt (@var{x}) Compute the square root of @var{x}. To compute the matrix square root, see @ref{Linear Algebra}. +@end deftypefn -@item max (@var{x}) +@deftypefn {Mapping Function} {} max (@var{x}) For a vector argument, return the maximum value. For a matrix argument, return the maximum value from each column, as a row vector. Thus, @@ -128,11 +141,13 @@ For complex arguments, the magnitude of the elements are used for comparison. +@end deftypefn -@item min (@var{x}) +@deftypefn {Mapping Function} {} min (@var{x}) Like @code{max}, but return the minimum value. +@end deftypefn -@item rem (@var{x}, @var{y}) +@deftypefn {Mapping Function} {} rem (@var{x}, @var{y}) Return the remainder of @code{@var{x} / @var{y}}, computed using the expression @@ -142,7 +157,7 @@ An error message is printed if the dimensions of the arguments do not agree, or if either of the arguments is complex. -@end ftable +@end deftypefn @node Complex Arithmetic, Trigonometry, Utility Functions, Arithmetic @section Complex Arithmetic @@ -151,86 +166,82 @@ numbers. Each expects a single argument. Given a matrix they work on an element by element basis. -@ftable @code -@item abs (@var{x}) -Compute the magnitude of @var{x}. +@deftypefn {Mapping Function} {} abs (@var{z}) +Compute the magnitude of @var{z}. +@end deftypefn -@item angle (@var{x}) -@itemx arg (@var{x}) -Compute the argument of @var{x}. +@deftypefn {Mapping Function} {} arg (@var{z}) +@deftypefnx {Mapping Function} {} angle (@var{z}) +Compute the argument of @var{z}. +@end deftypefn -@item conj (@var{x}) -Return the complex conjugate of @var{x}. +@deftypefn {Mapping Function} {} conj (@var{z}) +Return the complex conjugate of @var{z}. +@end deftypefn -@item imag (@var{x}) -Return the imaginary part of @var{x}. +@deftypefn {Mapping Function} {} imag (@var{z}) +Return the imaginary part of @var{z}. +@end deftypefn -@item real (@var{x}) -Return the real part of @var{x}. -@end ftable +@deftypefn {Mapping Function} {} real (@var{z}) +Return the real part of @var{z}. +@end deftypefn @node Trigonometry, Sums and Products, Complex Arithmetic, Arithmetic @section Trigonometry Octave provides the following trigonometric functions: +@deftypefn {Mapping Function} {} sin (@var{z}) +@deftypefnx {Mapping Function} {} cos (@var{z}) +@deftypefnx {Mapping Function} {} tan (@var{z}) +@deftypefnx {Mapping Function} {} sec (@var{z}) +@deftypefnx {Mapping Function} {} csc (@var{z}) +@deftypefnx {Mapping Function} {} cot (@var{z}) +The ordinary trigonometric functions. +@end deftypefn + +@deftypefn {Mapping Function} {} asin (@var{z}) +@deftypefnx {Mapping Function} {} acos (@var{z}) +@deftypefnx {Mapping Function} {} atan (@var{z}) +@deftypefnx {Mapping Function} {} asec (@var{z}) +@deftypefnx {Mapping Function} {} acsc (@var{z}) +@deftypefnx {Mapping Function} {} acot (@var{z}) +The ordinary inverse trigonometric functions. +@end deftypefn + +@deftypefn {Mapping Function} {} sinh (@var{z}) +@deftypefnx {Mapping Function} {} cosh (@var{z}) +@deftypefnx {Mapping Function} {} tanh (@var{z}) +@deftypefnx {Mapping Function} {} sech (@var{z}) +@deftypefnx {Mapping Function} {} csch (@var{z}) +@deftypefnx {Mapping Function} {} coth (@var{z}) +Hyperbolic trigonometric functions. +@end deftypefn + +@deftypefn {Mapping Function} {} asinh (@var{z}) +@deftypefnx {Mapping Function} {} acosh (@var{z}) +@deftypefnx {Mapping Function} {} atanh (@var{z}) +@deftypefnx {Mapping Function} {} asech (@var{z}) +@deftypefnx {Mapping Function} {} acsch (@var{z}) +@deftypefnx {Mapping Function} {} acoth (@var{z}) +Inverse hyperbolic trigonometric functions. +@end deftypefn + +Each of these functions expect a single argument. For matrix arguments, +they work on an element by element basis. For example, + @example -sin asin sinh asinh -cos acos cosh acosh -tan atan tanh atanh - -sec asec sech asech -csc acsc csch acsch -cot acot coth acoth +@group +sin ([1, 2; 3, 4]) + @result{} 0.84147 0.90930 + 0.14112 -0.75680 +@end group @end example -@findex sin -@findex cos -@findex tan -@findex asin -@findex acos -@findex atan -@findex sinh -@findex cosh -@findex tanh -@findex asinh -@findex acosh -@findex atanh -@findex sec -@findex csc -@findex cot -@findex asec -@findex acsc -@findex acot -@findex sech -@findex csch -@findex coth -@findex asech -@findex acsch -@findex acoth - -@noindent -Each of these functions expect a single argument. For matrix arguments, -they work on an element by element basis. For example, the expression - -@example -sin ([1, 2; 3, 4]) -@end example - -@noindent -produces - -@example -ans = - - 0.84147 0.90930 - 0.14112 -0.75680 -@end example - -@findex atan2 -In addition, the function @code{atan2 (@var{y}, @var{x})} computes the -arctangent of @var{y}/@var{x} and uses the signs of the arguments to -determine the quadrant of the result, which is in the range +@deftypefn {Mapping Function} {} atan2 (@var{y}, @var{x}) +Return the arctangent of @var{y}/@var{x}. The signs of the arguments +are used to determine the quadrant of the result, which is in the range @iftex @tex $\pi$ to $-\pi$. @@ -239,68 +250,59 @@ @ifinfo @code{pi} to -@code{pi}. @end ifinfo +@end deftypefn @node Sums and Products, Special Functions, Trigonometry, Arithmetic @section Sums and Products -@ftable @code -@item sum (@var{x}) +@deftypefn {Built-in Function} {} sum (@var{x}) For a vector argument, return the sum of all the elements. For a matrix argument, return the sum of the elements in each column, as a row vector. The sum of an empty matrix is 0 if it has no columns, or a vector of zeros if it has no rows (@pxref{Empty Matrices}). +@end deftypefn -@item prod (@var{x}) +@deftypefn {Built-in Function} {} prod (@var{x}) For a vector argument, return the product of all the elements. For a matrix argument, return the product of the elements in each column, as a row vector. The product of an empty matrix is 1 if it has no columns, or a vector of ones if it has no rows (@pxref{Empty Matrices}). +@end deftypefn -@item cumsum (@var{x}) +@deftypefn {Built-in Function} {} cumsum (@var{x}) Return the cumulative sum of each column of @var{x}. For example, @example +@group cumsum ([1, 2; 3, 4]) + @result{} 1 2 + 4 6 +@end group @end example - -@noindent -produces +@end deftypefn -@example -ans = - - 1 2 - 4 6 -@end example - -@item cumprod (@var{x}) +@deftypefn {Built-in Function} {} cumprod (@var{x}) Return the cumulative product of each column of @var{x}. For example, @example +@group cumprod ([1, 2; 3, 4]) + @result{} 1 2 + 3 8 +@end group @end example - -@noindent -produces +@end deftypefn -@example -ans = - - 1 2 - 3 8 -@end example - -@item sumsq (@var{x}) +@deftypefn {Built-in Function} {} sumsq (@var{x}) For a vector argument, return the sum of the squares of all the elements. For a matrix argument, return the sum of the squares of the elements in each column, as a row vector. -@end ftable +@end deftypefn -@node Special Functions, , Sums and Products, Arithmetic +@node Special Functions, Mathematical Constants, Sums and Products, Arithmetic @section Special Functions -@ftable @code -@item beta +@deftypefn {Mapping Function} {} beta (@var{a}, @var{b}) Returns the Beta function, @iftex @tex @@ -315,8 +317,9 @@ beta (a, b) = gamma (a) * gamma (b) / gamma (a + b). @end example @end ifinfo +@end deftypefn -@item betai (@var{a}, @var{b}, @var{x}) +@deftypefn {Mapping Function} {} betai (@var{a}, @var{b}, @var{x}) Returns the incomplete Beta function, @iftex @tex @@ -339,8 +342,9 @@ If x has more than one component, both @var{a} and @var{b} must be scalars. If @var{x} is a scalar, @var{a} and @var{b} must be of compatible dimensions. +@end deftypefn -@item erf +@deftypefn {Mapping Function} {} erf (@var{z}) Computes the error function, @iftex @tex @@ -359,16 +363,18 @@ t=0 @end smallexample @end ifinfo +@end deftypefn -@item erfc (@var{z}) +@deftypefn {Mapping Function} {} erfc (@var{z}) Computes the complementary error function, @code{1 - erf (@var{z})}. +@end deftypefn @c XXX FIXME XXX -- this isn't actually distributed with Octave yet. @c @c @item erfinv @c Computes the inverse of the error function. -@item gamma (@var{z}) +@deftypefn {Mapping Function} {} gamma (@var{z}) Computes the Gamma function, @iftex @tex @@ -387,8 +393,9 @@ t=0 @end example @end ifinfo +@end deftypefn -@item gammai (@var{a}, @var{x}) +@deftypefn {Mapping Function} {} gammai (@var{a}, @var{x}) Computes the incomplete gamma function, @iftex @tex @@ -413,8 +420,113 @@ If neither @var{a} nor @var{x} is scalar, the sizes of @var{a} and @var{x} must agree, and @var{gammai} is applied element-by-element. +@end deftypefn -@item lgamma +@deftypefn {Mapping Function} {} lgamma (@var{a}, @var{x}) Returns the natural logarithm of the gamma function. -@end ftable +@end deftypefn + +@node Mathematical Constants, , Special Functions, Arithmetic +@section Mathematical Constants + +@defvr {Built-in Variable} I +@defvrx {Built-in Variable} J +@defvrx {Built-in Variable} i +@defvrx {Built-in Variable} j +A pure imaginary number, defined as +@iftex +@tex + $\sqrt{-1}$. +@end tex +@end iftex +@ifinfo + @code{sqrt (-1)}. +@end ifinfo +The @code{I} and @code{J} forms are true constants, and cannot be +modified. The @code{i} and @code{j} forms are like ordinary variables, +and may be used for other purposes. However, unlike other variables, +they once again assume their special predefined values if they are +cleared @xref{Miscellaneous Utilities}. +@end defvr + +@defvr {Built-in Variable} Inf +@defvrx {Built-in Variable} inf +Infinity. This is the result of an operation like 1/0, or an operation +that results in a floating point overflow. +@end defvr + +@defvr {Built-in Variable} NaN +@defvrx {Built-in Variable} nan +Not a number. This is the result of an operation like @samp{0/0}, or +@samp{Inf - Inf}, or any operation with a NaN. +@end defvr + +@defvr {Built-in Variable} eps +The machine precision. More precisely, @code{eps} is the largest +relative spacing between any two adjacent numbers in the machine's +floating point system. This number is obviously system-dependent. On +machines that support 64 bit IEEE floating point arithmetic, @code{eps} +is approximately +@ifinfo + 2.2204e-16. +@end ifinfo +@iftex +@tex + $2.2204\times10^{-16}$. +@end tex +@end iftex +@end defvr +@defvr {Built-in Variable} pi +The ratio of the circumference of a circle to its diameter. +Internally, @code{pi} is computed as @samp{4.0 * atan (1.0)}. +@end defvr + +@defvr {Built-in Variable} e +The base of natural logarithms. The constant +@iftex +@tex + $e$ +@end tex +@end iftex +@ifinfo + @var{e} +@end ifinfo + satisfies the equation +@iftex +@tex + $\log (e) = 1$. +@end tex +@end iftex +@ifinfo + @code{log} (@var{e}) = 1. +@end ifinfo +@end defvr + +@defvr {Built-in Variable} realmax +The largest floating point number that is representable. The actual +value is system-dependent. On machines that support 64 bit IEEE +floating point arithmetic, @code{realmax} is approximately +@ifinfo + 1.7977e+308 +@end ifinfo +@iftex +@tex + $1.7977\times10^{308}$. +@end tex +@end iftex +@end defvr + +@defvr {Built-in Variable} realmin +The smallest floating point number that is representable. The actual +value is system-dependent. On machines that support 64 bit IEEE +floating point arithmetic, @code{realmin} is approximately +@ifinfo + 2.2251e-308 +@end ifinfo +@iftex +@tex + $2.2251\times10^{-308}$. +@end tex +@end iftex +@end defvr
--- a/doc/interpreter/audio.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/audio.texi Wed Oct 30 23:00:41 1996 +0000 @@ -28,24 +28,25 @@ files holding data in mu-law encoding end in @file{au}, @file{mu}, or @file{snd}. -The basic functions are as follows. - -@ftable @code -@item lin2mu +@deftypefn {Function File} {} lin2mu (@var{x}) If the vector @var{x} represents mono audio data in 8- or 16-bit -linear encoding, @kbd{lin2mu (@var{x})} is the correspoding mu-law +linear encoding, @code{lin2mu (@var{x})} is the correspoding mu-law encoding. +@end deftypefn -@item mu2lin +@deftypefn {Function File} {} mu2lin (@var{x}, @var{bps}) If the vector @var{x} represents mono audio data in mu-law encoding, @code{mu2lin (@var{x} [, @var{bps}])} converts it to linear encoding. The optional argument @var{bps} specifies whether the input data uses 8 bit per sample (default) or 16 bit. +@end deftypefn -@item loadaudio -@kbd{@var{x} = loadaudio (@var{name} [, @var{ext} [, @var{bps}]])} loads -audio data from the file @file{@var{name}.@var{ext}} into the vector -@var{x}. +@c XXX FIXME XXX -- ext and bps are optional, but we need to note the +@c default values here too. + +@deftypefn {Function File} {} loadaudio (@var{name}, @var{ext}, @var{bps}) +Loads audio data from the file @file{@var{name}.@var{ext}} into the +vector @var{x}. The extension @var{ext} determines how the data in the audio file is interpreted; the extensions @file{lin} (default) and @file{raw} @@ -54,14 +55,15 @@ The argument @var{bps} can be either 8 (default) or 16, and specifies the number of bits per sample used in the audio file. +@end deftypefn -@item saveaudio -@kbd{saveaudio (@var{name}, @var{x}, [, @var{ext} [, @var{bps}]])} saves -a vector @var{x} of audio data to the file @file{@var{name}.@var{ext}}. -The optional parameters @var{ext} and @var{bps} determine the encoding -and the number of bits per sample used in the audio file (see -@code{loadaudio}); defaults are @file{lin} and 8, respectively. -@end ftable +@deftypefn {Function File} {} saveaudio (@var{name}, @var{x}, @var{ext}, @var{bps}) +Saves a vector @var{x} of audio data to the file +@file{@var{name}.@var{ext}}. The optional parameters @var{ext} and +@var{bps} determine the encoding and the number of bits per sample used +in the audio file (see @code{loadaudio}); defaults are @file{lin} and +8, respectively. +@end deftypefn The following functions for audio I/O require special A/D hardware and operating system support. It is assumed that audio data in linear @@ -71,38 +73,29 @@ on Suns. If your hardware is accessed differently, please contact Andreas Weingessel <Andreas.Weingessel@@ci.tuwien.ac.at>. -@ftable @code -@item playaudio -@kbd{playaudio (@var{name} [, @var{ext}])} plays the audio file -@file{@var{name}.@var{ext}}. - -@kbd{playaudio (@var{x})} plays the audio data contained in the vector -@var{x}. +@deftypefn {Function File} {} playaudio (@var{name}, @var{ext}) +@deftypefnx {Function File} {} playaudio (@var{x}) +Plays the audio file @file{@var{name}.@var{ext}} or in the vector +@var{x}. +@end deftypefn -@item record -@kbd{@var{x} = record (@var{sec} [, @var{sampling_rate}])} records -@var{sec} seconds of audio input into the vector @var{x}. The default -value for @var{sampling_rate} is 8000 samples per second, or 8kHz. The -program waits until the @key{ENTER} key is hit, and then immediately -starts to record. +@deftypefn {Function File} {} record (@var{sec}, @var{sampling_rate}) +Records @var{sec} seconds of audio input into the vector @var{x}. The +default value for @var{sampling_rate} is 8000 samples per second, or +8kHz. The program waits until the @key{ENTER} key is hit, and then +immediately starts to record. +@end deftypefn -@item setaudio -@kbd{setaudio ([@var{type}])} displays the current value of the -@var{type} property of your mixer hardware. - -@kbd{setaudio ([@var{type} [, @var{value}]])} sets the @var{type} -property to @var{value}. +@deftypefn {Function File} {} setaudio (@var{type}) +@deftypefnx {Function File} {} setaudio (@var{type}, @var{value}) +Set or display various properties of your mixer hardware. For example, if @code{vol} corresponds to the volume property, you can set it to 50 (percent) by @code{setaudio ("vol", 50)}. This is an simple experimental program to control the audio hardware settings. It assumes that there is a @code{mixer} program which can be -used as @kbd{mixer @var{type} @var{value}}, and simply executes -@kbd{system ("mixer @var{type} @var{value}")}. Future releases might +used as @code{mixer @var{type} @var{value}}, and simply executes +@code{system ("mixer @var{type} @var{value}")}. Future releases might get rid of this assumption by using the @code{fcntl} interface. -@end ftable - -@c Local Variables: -@c TeX-command-default: "Texinfo" -@c End: +@end deftypefn
--- a/doc/interpreter/control.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/control.texi Wed Oct 30 23:00:41 1996 +0000 @@ -5,9 +5,7 @@ @node Control Theory, Signal Processing, Quadrature, Top @chapter Control Theory -@ftable @code -@item abcddim (@var{a}, @var{b}, @var{c}, @var{d}) - +@deftypefn {Function File} {} abcddim (@var{a}, @var{b}, @var{c}, @var{d}) Check for compatibility of the dimensions of the matrices defining the linear system [A, B, C, D] corresponding to @iftex @@ -34,8 +32,9 @@ @var{n} = number of system states, @var{m} = number of system inputs, and @var{p} = number of system outputs. Otherwise @code{abcddim} returns @var{n} = @var{m} = @var{p} = @minus{}1. +@end deftypefn -@item are (@var{a}, @var{b}, @var{c}, @var{opt}) +@deftypefn {Function File} {} are (@var{a}, @var{b}, @var{c}, @var{opt}) Returns the solution, @var{x}, of the algebraic Riccati equation @@ -53,8 +52,9 @@ @var{opt} is an option passed to the eigenvalue balancing routine. Default is @code{"B"}. +@end deftypefn -@item c2d (@var{a}, @var{b}, @var{t}) +@deftypefn {Function File} {} c2d (@var{a}, @var{b}, @var{t}) Converts the continuous time system described by: @iftex @tex @@ -88,8 +88,9 @@ @noindent via the matrix exponential assuming a zero-order hold on the input and sample time @var{t}. +@end deftypefn -@item dare (@var{a}, @var{b}, @var{c}, @var{r}, @var{opt}) +@deftypefn {Function File} {} dare (@var{a}, @var{b}, @var{c}, @var{r}, @var{opt}) Returns the solution, @var{x} of the discrete-time algebraic Riccati equation @@ -120,8 +121,9 @@ @var{opt} is an option passed to the eigenvalue balancing routine. The default is @code{"B"}. +@end deftypefn -@item dgram (@var{a}, @var{b}) +@deftypefn {Function File} {} dgram (@var{a}, @var{b}) Returns the discrete controllability and observability gramian for the discrete time system described by @iftex @@ -145,8 +147,9 @@ @code{dgram (@var{a}, @var{b})} returns the discrete controllability gramian and @code{dgram (@var{a}', @var{c}')} returns the observability gramian. +@end deftypefn -@item dlqe (@var{a}, @var{g}, @var{c}, @var{sigw}, @var{sigv} [, @var{z}]) +@deftypefn {Function File} {} dlqe (@var{a}, @var{g}, @var{c}, @var{sigw}, @var{sigv} [, @var{z}]) Linear quadratic estimator (Kalman filter) design for the discrete time system @iftex @@ -199,9 +202,9 @@ @var{p} is the estimate error covariance after the measurement update. @var{e} are the closed loop poles of @code{(A - A L C)}. - +@end deftypefn -@item dlqr (@var{a}, @var{b}, @var{q}, @var{r} [, @var{z}]) +@deftypefn {Function File} {} dlqr (@var{a}, @var{b}, @var{q}, @var{r} [, @var{z}]) Linear quadratic regulator design for the discrete time system @iftex @tex @@ -238,8 +241,9 @@ @var{p} is the solution of algebraic Riccati equation. @var{e} are the closed loop poles of @var{(A - B K)}. +@end deftypefn -@item dlyap (@var{a}, @var{b}) +@deftypefn {Function File} {} dlyap (@var{a}, @var{b}) Solve the discrete-time Lyapunov equation @example @@ -267,8 +271,9 @@ Uses Schur decomposition method as in Kitagawa, International Journal of Control (1977); column-by-column solution method as suggested in Hammarling, IMA Journal of Numerical Analysis, (1982). +@end deftypefn -@item is_controllable (@var{a}, @var{b}, @var{tol}) +@deftypefn {Function File} {} is_controllable (@var{a}, @var{b}, @var{tol}) If the pair (a, b) is controllable, then return value 1. Otherwise, returns a value of 0. @@ -294,13 +299,15 @@ span ([b, a*b, ..., a^ *b]). @end example @end ifinfo +@end deftypefn -@item is_observable (@var{a}, @var{c}, @var{tol}) +@deftypefn {Function File} {} is_observable (@var{a}, @var{c}, @var{tol}) Returns 1 if the pair @code{(a, c)} is observable. Otherwise, returns a value of 0. +@end deftypefn -@item lqe (@var{a}, @var{g}, @var{c}, @var{sigw}, @var{sigv}, @var{z}) +@deftypefn {Function File} {} lqe (@var{a}, @var{g}, @var{c}, @var{sigw}, @var{sigv}, @var{z}) @example [k, p, e] = lqe (a, g, c, sigw, sigv, z) @@ -351,9 +358,10 @@ @var{p} is solution of algebraic Riccati equation. @var{e} is the vector of closed loop poles of @code{(A - K C)}. +@end deftypefn -@item lqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{z}) -@itemx [@var{k}, @var{p}, @var{e}] = lqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{z}) +@deftypefn {Function File} {} lqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{z}) +@deftypefnx {Function File} {[@var{k}, @var{p}, @var{e}] =} lqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{z}) Linear quadratic regulator design for the continuous time system @iftex @tex @@ -421,9 +429,9 @@ equation. @var{e} is the vector of the closed loop poles of @code{(A - B K)}. +@end deftypefn -@item lyap (@var{a}, @var{b}, @var{c}) - +@deftypefn {Function File} {} lyap (@var{a}, @var{b}, @var{c}) Solve the Lyapunov (or Sylvester) equation via the Bartels-Stewart algorithm (Communications of the ACM, 1972). @@ -458,9 +466,9 @@ whichever is appropriate. Solves by using the Bartels-Stewart algorithm (1972). +@end deftypefn -@item tzero (@var{a}, @var{b}, @var{c}, @var{d}, @var{bal}) - +@deftypefn {Function File} {} tzero (@var{a}, @var{b}, @var{c}, @var{d}, @var{bal}) Compute the transmission zeros of [A, B, C, D]. @var{bal} = balancing option (see balance); default is @code{"B"}. @@ -468,4 +476,4 @@ Needs to incorporate @code{mvzero} algorithm to isolate finite zeros; see Hodel, @cite{Computation of System Zeros with Balancing}, Linear Algebra and its Applications, July 1993. -@end ftable +@end deftypefn
--- a/doc/interpreter/cp-idx.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/cp-idx.texi Wed Oct 30 23:00:41 1996 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Concept Index, Variable Index, Using Info, Top +@node Concept Index, Variable Index, Copying, Top @unnumbered Concept Index @printindex cp
--- a/doc/interpreter/diffeq.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/diffeq.texi Wed Oct 30 23:00:41 1996 +0000 @@ -20,7 +20,6 @@ @node Ordinary Differential Equations, Differential-Algebraic Equations, Differential Equations, Differential Equations @section Ordinary Differential Equations -@findex lsode The function @code{lsode} can be used Solve ODEs of the form @iftex @tex @@ -41,10 +40,7 @@ @noindent using Hindmarsh's ODE solver LSODE. -@example -lsode (@var{fcn}, @var{x0}, @var{t_out}, @var{t_crit}) -@end example - +@deftypefn {Built-in Function} {} lsode (@var{fcn}, @var{x0}, @var{t_out}, @var{t_crit}) The first argument is the name of the function to call to compute the vector of right hand sides. It must have the form @@ -64,10 +60,6 @@ avoiding difficulties with singularities and points where there is a discontinuity in the derivative. -@findex lsode_options -Tolerances and other options for @code{lsode} may be specified using the -function @code{lsode_options}. - Here is an example of solving a set of two differential equations using @code{lsode}. The function @@ -104,6 +96,15 @@ @example plot (t, x) @end example +@end deftypefn + +@deftypefn {Built-in Function} {} lsode_options (@var{opt}, @var{val}) +When called with two arguments, this function allows you set options +parameters for the function @code{lsode}. Given one argument, +@code{lsode_options} returns the value of the corresponding option. If +no arguments are supplied, the names of all the available options and +their current values are displayed. +@end deftypefn See Alan C. Hindmarsh, @cite{ODEPACK, A Systematized Collection of ODE Solvers}, in Scientific Computing, R. S. Stepleman, editor, (1983) for @@ -112,7 +113,6 @@ @node Differential-Algebraic Equations, , Ordinary Differential Equations, Differential Equations @section Differential-Algebraic Equations -@findex dassl The function @code{dassl} can be used Solve DAEs of the form @iftex @tex @@ -128,10 +128,7 @@ @end example @end ifinfo -@example -dassl (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t_out}, @var{t_crit}) -@end example - +@deftypefn {Built-in Function} {[@var{x}, @var{xdot}] =} dassl (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t_out}, @var{t_crit}) The first argument is the name of the function to call to compute the vector of residuals. It must have the form @@ -157,10 +154,15 @@ times that the DAE solver should not integrate past. It is useful for avoiding difficulties with singularities and points where there is a discontinuity in the derivative. +@end deftypefn -@findex dassl_options -Tolerances and other options for @code{dassl} may be specified using the -function @code{dassl_options}. +@deftypefn {Built-in Function} {} dassl_options (@var{opt}, @var{val}) +When called with two arguments, this function allows you set options +parameters for the function @code{lsode}. Given one argument, +@code{dassl_options} returns the value of the corresponding option. If +no arguments are supplied, the names of all the available options and +their current values are displayed. +@end deftypefn See K. E. Brenan, et al., @cite{Numerical Solution of Initial-Value Problems in Differential-Algebraic Equations}, North-Holland (1989) for
--- a/doc/interpreter/emacs.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/emacs.texi Wed Oct 30 23:00:41 1996 +0000 @@ -4,7 +4,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Emacs +@node Emacs, Installation, Amusements, Top @chapter Using Emacs With Octave The development of Octave code can greatly be facilitated using Emacs
--- a/doc/interpreter/expr.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/expr.texi Wed Oct 30 23:00:41 1996 +0000 @@ -64,17 +64,21 @@ 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 @@ -93,12 +97,14 @@ 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 @@ -117,8 +123,10 @@ following expressions @example +@group "parrot" 'parrot' +@end group @end example @noindent @@ -232,28 +240,28 @@ @noindent results in the matrix +@iftex +@tex +$$ a = \left[ \matrix{ 1 & 2 \cr 3 & 4 } \right] $$ +@end tex +@end iftex +@ifinfo @example -a = - - 1 2 - 3 4 -@end example +@group -The commas which separate the elements on a row may be omitted, and the -semicolon that marks the beginning of a new row may be replaced by one -or more new lines. The expression + / \ + | 1 2 | + a = | | + | 3 4 | + \ / -@example -a = [ 1 2 - 3 4 ] +@end group @end example - -@noindent -is equivalent to the one above. +@end ifinfo Elements of a matrix may be arbitrary expressions, provided that the -dimensions all agree. For example, given the above matrix, the -expression +dimensions all make sense when combining the various pieces. For +example, given the above matrix, the expression @example [ a, a ] @@ -263,37 +271,65 @@ 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 ] +[ a, 1 ] @end example @noindent produces the error -@c XXX FIXME XXX -- this error should eventually have line and column -@c information associated with it. @example -error: number of rows must match +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). + +Commas and semicolons are not always required to separate matrix +elements and rows. The expression + +@example +@group +a = [ 1 2 + 3 4 ] +@end group +@end example + +@noindent +is equivalent to the one above. + Inside the square brackets that delimit a matrix expression, Octave -looks at the surrounding context to determine whether spaces should be -converted into element separators, or simply ignored, so commands like +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 +octave:13> a = [ 1 2 +> 3 4 ] +@end group +@end example + +@noindent will work. However, some possible sources of confusion remain. For example, in the expression @@ -346,7 +382,142 @@ 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"}. @xref{Built-in Variables}. +@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 +@samp{[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 @samp{[1 2]} will result in an error +instead of being treated the same as @samp{[1, 2]}, and the expression + +@example +[ 1, 2, + 3, 4 ] +@end example + +@noindent +will result in the vector [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. + +@noindent +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 @menu * Empty Matrices:: @@ -366,34 +537,79 @@ following are true: @example +@group s * [](mxn) = [](mxn) * s = [](mxn) [](mxn) + [](mxn) = [](mxn) - [](0xm) * M(mxn) = [](0xn) + [](0xm) * M(mxn) = [](0xn) - M(mxn) * [](nx0) = [](mx0) + M(mxn) * [](nx0) = [](mx0) - [](mx0) * [](0xn) = 0(mxn) + [](mx0) * [](0xn) = 0(mxn) +@end group @end example -By default, dimensions of the empty matrix are now printed along -with the empty matrix symbol, @samp{[]}. For example: +By default, dimensions of the empty matrix are printed along with the +empty matrix symbol, @samp{[]}. For example: @example +@group octave:13> zeros (3, 0) ans = [](3x0) +@end group @end example The built-in variable @code{print_empty_dimensions} controls this -behavior (@pxref{User Preferences}). +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 @samp{a} will be assigned the value @samp{[ 1 3 5 ]}. + +The default value is @code{"warn"}. +@end defvr + @node Ranges, Variables, Matrices, Expressions @section Ranges @cindex range expressions @@ -415,16 +631,14 @@ @end example @noindent -defines the set of values @samp{[ 1 2 3 4 5 ]} (the increment has been -omitted, so it is taken as 1), and the range +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 ]}. In this case, the base value -is 1, the increment is 3, and the limit is 5. +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. @@ -455,13 +669,20 @@ @cindex getting a good job @cindex flying high and fast @example +@group x x15 __foo_bar_baz__ fucnrdthsucngtagdjb +@end group @end example @noindent +However, names like @code{__foo_bar_baz__} that begin and end with two +underscores are understood to be reserved for internal use by Octave. +You should not use them in code you write, except to access Octave's +documented internal variables and built-in symbolic constants. + Case is significant in variable names. The symbols @code{a} and @code{A} are distinct variables. @@ -478,9 +699,10 @@ used and assigned just like all other variables, but their values are also used or changed automatically by Octave. -Variables in Octave can be assigned either numeric or string values. -Variables may not be used before they have been given a value. Doing so -results in an error. +Variables in Octave do not have fixed types, so it is possible to first +store a numeric value in a variable and then to later use the same name +to hold a string value in the same program. Variables may not be used +before they have been given a value. Doing so results in an error. @node Index Expressions, Data Structures, Variables, Expressions @section Index Expressions @@ -493,8 +715,15 @@ Vectors are indexed using a single expression. Matrices require two indices unless the value of the built-in variable -@code{do_fortran_indexing} is @code{"true"}, in which case a matrix may -also be indexed by a single expression (@pxref{User Preferences}). +@code{do_fortran_indexing} is nonzero, in which case matrices may +also be indexed by a single expression. + +@defvr {Built-in Variable} do_fortran_indexing +If the value of @code{do_fortran_indexing} is nonzero, Octave allows +you to select elements of a two-dimensional matrix using a single index +by treating the matrix as a single vector created from the columns of +the matrix. The default value is 0. +@end defvr Given the matrix @@ -506,9 +735,11 @@ all of the following expressions are equivalent @example +@group a (1, [1, 2]) a (1, 1:2) a (1, :) +@end group @end example @noindent @@ -520,8 +751,10 @@ index vector that are equal to one. For example, @example +@group a = [1, 2; 3, 4]; a ([1, 0], :) +@end group @end example @noindent @@ -531,28 +764,62 @@ some condition, since the comparison operators return matrices of ones and zeros. -Unfortunately, this special zero-one form of indexing leads to a -conflict with the standard indexing operation. For example, should the -following statements +This special zero-one form of indexing leads to a conflict with the +standard indexing operation. For example, should the following +statements @example +@group a = [1, 2; 3, 4]; a ([1, 1], :) +@end group @end example @noindent return the original matrix, or the matrix formed by selecting the first row twice? Although this conflict is not likely to arise very often in practice, you may select the behavior you prefer by setting the built-in -variable @code{prefer_zero_one_indexing} (@pxref{User Preferences}). +variable @code{prefer_zero_one_indexing}. + +@defvr {Built-in Variable} prefer_zero_one_indexing +If the value of @code{prefer_zero_one_indexing} is nonzero, Octave +will perform zero-one style indexing when there is a conflict with the +normal indexing rules. @xref{Index Expressions}. For example, given a +matrix + +@example +a = [1, 2, 3, 4] +@end example + +@noindent +with @code{prefer_zero_one_indexing} is set to nonzero, the +expression + +@example +a ([1, 1, 1, 1]) +@end example + +@noindent +results in the matrix @samp{[ 1 2 3 4 ]}. If the value of +@code{prefer_zero_one_indexing} set to 0, the result would be +the matrix @samp{[ 1 1 1 1 ]}. + +In the first case, Octave is selecting each element corresponding to a +@samp{1} in the index vector. In the second, Octave is selecting the +first element multiple times. + +The default value for @code{prefer_zero_one_indexing} is 0. +@end defvr Finally, indexing a scalar with a vector of ones can be used to create a vector the same size as the the index vector, with each element equal to the value of the original scalar. For example, the following statements @example +@group a = 13; a ([1, 1, 1, 1]) +@end group @end example @noindent @@ -562,8 +829,10 @@ create a matrix. For example the following statements @example +@group a = 13; a ([1, 1], [1, 1, 1]) +@end group @end example @noindent @@ -574,46 +843,100 @@ size whose elements are all one, and then to scale it to produce the desired result. @xref{Special Matrices}. +@defvr {Built-in Variable} prefer_column_vectors +If @code{prefer_column_vectors} is nonzero, operations like + +@example +for i = 1:10 + a (i) = i; +endfor +@end example + +@noindent +(for @samp{a} previously undefined) produce column vectors. Otherwise, row +vectors are preferred. The default value is 0. + +If a variable is already defined to be a vector (a matrix with a single +row or column), the original orientation is respected, regardless of the +value of @code{prefer_column_vectors}. +@end defvr + +@defvr {Built-in Variable} resize_on_range_error +If the value of @code{resize_on_range_error} is nonzero, expressions +like + +@example +for i = 1:10 + a (i) = i; +endfor +@end example + +@noindent +(for @samp{a} previously undefined) result in the variable @samp{a} +being resized to be just large enough to hold the new value. Otherwise +uninitialized elements are set to zero. If the value of +@code{resize_on_range_error} is 0, an error message is +printed and control is returned to the top level. The default value is +1. +@end defvr + @node Data Structures, Calling Functions, Index Expressions, Expressions @section Data Structures @cindex structures @cindex data structures -Octave includes a limited amount of support for organizing data in -structures. The current implementation uses an associative array -with indices limited to strings, but the syntax is more like C-style -structures. Here are some examples of using data structures in Octave. +Octave includes support for organizing data in structures. The current +implementation uses an associative array with indices limited to +strings, but the syntax is more like C-style structures. Here are some +examples of using data structures in Octave. -Elements of structures can be of any value type. +Elements of structures can be of any value type. For example, the list +of statements @example octave:1> x.a = 1; x.b = [1, 2; 3, 4]; x.c = "string"; -octave:2> x.a -x.a = 1 -octave:3> x.b -x.b = +@end example + +@noindent +creates a structure with three elements. To print the value of the +structure, you can type its name, just as for any other variable: - 1 2 - 3 4 +@example +@group +octave:2> x +x = +@{ + a = 1 + b = -octave:4> x.c -x.c = string + 1 2 + 3 4 + + c = string +@} +@end group @end example +@noindent +Note that Octave may print the elements in any order. + Structures may be copied. @example +@group octave:1> y = x y = - -<structure: a b c> -@end example +@{ + a = 1 + b = -Note that when the value of a structure is printed, Octave only displays -the names of the elements. This prevents long and confusing output from -large deeply nested structures, but makes it more difficult to view the -values of simple structures, so this behavior may change in a future -version of Octave. + 1 2 + 3 4 + + c = string +@} +@end group +@end example Since structures are themselves values, structure elements may reference other structures. The following statements change the value of the @@ -621,26 +944,65 @@ containing the single element @code{d}, which has a value of 3. @example +@group octave:1> x.b.d = 3 x.b.d = 3 octave:2> x.b -x.b = +ans = +@{ + d = 3 +@} +octave:3> x +x = +@{ + a = 1 + b = + @{ + d = 3 + @} -<structure: d> + c = string +@} +@end group +@end example + +Note that when Octave prints the value of a structure that contains +other structures, only a few levels are displayed. For example, -octave:3> x.b.d -x.b.d = 3 +@example +@group +octave:1> a.b.c.d.e = 1; +octave:2> a +a = +@{ + b = + @{ + c = <structure> + @} +@} +@end group @end example +@noindent +This prevents long and confusing output from large deeply nested +structures. + +@defvr {Built-in Variable} struct_levels_to_print +You can tell Octave how many structure levels to display by setting the +built-in variable @code{struct_levels_to_print}. The default value is 2. +@end defvr + Functions can return structures. For example, the following function separates the real and complex parts of a matrix and stores them in two elements of the same structure variable. @example +@group octave:1> function y = f (x) > y.re = real (x); > y.im = imag (x); > endfunction +@end group @end example When called with a complex-valued argument, @code{f} returns the data @@ -648,31 +1010,29 @@ function argument. @example -octave:1> f (rand (3) + rand (3) * I); +@group +octave:2> f (rand (3) + rand (3) * I); ans = - -<structure: im re> - -octave:3> ans.im -ans.im = +@{ + im = - 0.093411 0.229690 0.627585 - 0.415128 0.221706 0.850341 - 0.894990 0.343265 0.384018 + 0.26475 0.14828 + 0.18436 0.83669 + + re = -octave:4> ans.re -ans.re = - - 0.56234 0.14797 0.26416 - 0.72120 0.62691 0.20910 - 0.89211 0.25175 0.21081 + 0.040239 0.242160 + 0.238081 0.402523 +@} +@end group @end example Function return lists can include structure elements, and they may be -indexed like any other variable. +indexed like any other variable. For example, @example -octave:1> [x.u, x.s(2:3,2:3), x.v] = svd ([1, 2; 3, 4]) +@group +octave:1> [ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4]) x.u = -0.40455 -0.91451 @@ -688,27 +1048,31 @@ -0.57605 0.81742 -0.81742 -0.57605 - -octave:8> x -x = - -<structure: s u v> +@end group @end example -@findex is_struct +It is also possible to cycle through all the elements of a structure in +a loop, using a special form of the @code{for} statement +(@pxref{The for Statement}) -You can also use the function @code{is_struct} to determine whether a -given value is a data structure. For example +The following functions and variableare available to +give you information about structures. + +@deftypefn {Built-in Function} {} is_struct (@var{expr}) +Returns 1 if the value of the expression @var{expr} is a structure. +@end deftypefn -@example -is_struct (x) -@end example +@deftypefn {Built-in Function} {} struct_contains (@var{expr}, @var{name}) +This function returns 1 if the expression @var{expr} is a structure and it +includes an element named @var{name}. The first argument must be a +structure and the second must be a string. +@end deftypefn -@noindent -returns 1 if the value of the variable @var{x} is a data structure. - -This feature should be considered experimental, but you should expect it -to work. Suggestions for ways to improve it are welcome. +@deftypefn {Built-in Function} {} struct_elements (@var{expr}) +If the expression @var{expr} is a structure, this function returns a +list of strings naming the elements of the structure. It is an error to +call @code{struct_elements} with an argument that is not a structure. +@end deftypefn @node Calling Functions, Global Variables, Data Structures, Expressions @section Calling Functions @@ -733,9 +1097,11 @@ intended. Here are some examples: @example +@group sqrt (x^2 + y^2) # @r{One argument} ones (n, m) # @r{Two arguments} rand () # @r{No arguments} +@end group @end example Each function expects a particular number of arguments. For example, the @@ -789,11 +1155,13 @@ body. For example, the function @example +@group function f (x, n) while (n-- > 0) disp (x); endwhile endfunction +@end group @end example @noindent @@ -809,8 +1177,10 @@ argument had. For example, given a function called as @example +@group foo = "bar"; fcn (foo) +@end group @end example @noindent @@ -818,18 +1188,43 @@ @code{foo}.'' Instead, think of the argument as the string value, @code{"bar"}. +Even though Octave uses pass-by-value semantics for function arguments, +values are not copied unnecessarily. For example, + +@example +@group +x = rand (1000); +f (x); +@end group +@end example + +@noindent +does not actually force two 1000 by 1000 element matrices to exist +@emph{unless} the function @code{f} modifies the value of its +argument. Then Octave must create a copy to avoid changing the +value outside the scope of the function @code{f}, or attempting (and +probably failing!) to modify the value of a constant or the value of a +temporary result. + @node Recursion, , Call by Value, Calling Functions @subsection Recursion @cindex factorial function -Recursive function calls are allowed. A @dfn{recursive function} is one -which calls itself, either directly or indirectly. For example, here is -an inefficient@footnote{It would be much better to use @code{prod -(1:n)}, or @code{gamma (n+1)} instead, after first checking to ensure -that the value @code{n} is actually a positive integer.} way to compute -the factorial of a given integer: +With some restrictions@footnote{Some of Octave's function are +implemented in terms of functions that cannot be called recursively. +For example, the ODE solver @code{lsode} is ultimiately implemented in a +Fortran subroutine which cannot be called recursively, so @code{lsode} +should not be called either directly or indirectly from within the +user-supplied function that @code{lsode} requires. Doing so will result +in undefined behavior.}, recursive function calls are allowed. A +@dfn{recursive function} is one which calls itself, either directly or +indirectly. For example, here is an inefficient@footnote{It would be +much better to use @code{prod (1:n)}, or @code{gamma (n+1)} instead, +after first checking to ensure that the value @code{n} is actually a +positive integer.} way to compute the factorial of a given integer: @example +@group function retval = fact (n) if (n > 0) retval = n * fact (n-1); @@ -837,6 +1232,7 @@ retval = 1; endif endfunction +@end group @end example This function is recursive because it calls itself directly. It @@ -854,6 +1250,7 @@ depth. @cindex global variables +@cindex @code{global} statement @cindex variables, global @node Global Variables, Keywords, Calling Functions, Expressions @@ -866,20 +1263,24 @@ statement. The following statements are all global declarations. @example +@group global a global b = 2 global c = 3, d, e = 5 +@end group @end example It is necessary declare a variable as global within a function body in order to access it. For example, @example +@group global x function f () x = 1; endfunction f () +@end group @end example @noindent @@ -888,16 +1289,19 @@ declare it to be global within the function body, like this @example +@group function f () global x; x = 1; endfunction +@end group @end example Passing a global variable in a function parameter list will make a local copy and not modify the global value. For example: @example +@group octave:1> function f (x) > x = 3 > endfunction @@ -908,8 +1312,25 @@ x = 3 # The value of the local variable x is 3. octave:5> x # But it was a *copy* so the global variable x = 0 # remains unchanged. +@end group @end example +@defvr {Built-in Variable} warn_comma_in_global_decl +If the value of @code{warn_comma_in_global_decl} is nonzero, a +warning is issued for statements like + +@example +global a = 1, b +@end example + +@noindent +which makes the variables @samp{a} and @samp{b} global and assigns the +value 1 to the variable @samp{a}, because in this context, the comma is +not interpreted as a statement separator. + +The default value of @code{warn_comma_in_global_decl} is nonzero. +@end defvr + @node Keywords, Arithmetic Ops, Global Variables, Expressions @section Keywords @cindex keywords @@ -918,21 +1339,34 @@ or function names: @example -break endfor function return -continue endfunction global while -else endif gplot -elseif endwhile gsplot -end for if +@group +all_va_args endwhile +break for +catch function +continue global +else gplot +elseif gsplot +end if +end_try_catch return +end_unwind_protect try +endfor unwind_protect +endfunction unwind_protect_cleanup +endif while +@end group @end example -The following command-like functions are also keywords, and may not be +The following command-like functions are also reserved, and may not be used as variable or function names: @example -casesen document history set -cd edit_history load show -clear help ls who -dir format run_history save +@group +casesen echo load show +cd edit_history ls type +chdir format more which +clear help run_history who +diary history save whos +dir hold set +@end group @end example @node Arithmetic Ops, Comparison Ops, Keywords, Expressions @@ -1095,6 +1529,12 @@ preferring the longest possible match at any given point, it is more useful in this case. +@defvr {Built-in Variable} warn_divide_by_zero +If the value of @code{warn_divide_by_zero} is nonzero, a warning +is issued when Octave encounters a division by zero. If the value is +0, the warning is omitted. The default value is 1. +@end defvr + @node Comparison Ops, Boolean Expressions, Arithmetic Ops, Expressions @section Comparison Operators @cindex comparison expressions @@ -1133,10 +1573,12 @@ returns the result @example +@group ans = 1 0 0 1 +@end group @end example @table @code @@ -1168,7 +1610,7 @@ String comparisons should be performed with the @code{strcmp} function, not with the comparison operators listed above. -@xref{Calling Functions}. +@xref{String Functions}. @node Boolean Expressions, Assignment Ops, Comparison Ops, Expressions @section Boolean Expressions @@ -1198,7 +1640,7 @@ @opindex ~ @opindex ! -An element-by-element @dfn{boolean expression} is a combination of +An @dfn{element-by-element boolean expression} is a combination of comparison expressions or matching expressions, using the boolean operators ``or'' (@samp{|}), ``and'' (@samp{&}), and ``not'' (@samp{!}), along with parentheses to control nesting. The truth of the boolean @@ -1318,9 +1760,11 @@ is possible write @example +@group function f (a, b, c) if (nargin > 2 && isstr (c)) ... +@end group @end example @noindent @@ -1328,10 +1772,12 @@ evaluate an argument that doesn't exist. @example +@group function f (a, b, c) if (nargin > 2) if (isstr (c)) ... +@end group @end example @node Assignment Ops, Increment Ops, Boolean Expressions, Expressions @@ -1359,9 +1805,11 @@ variable @code{message}: @example +@group thing = "food" predicate = "good" message = [ "this " , thing , " is " , predicate ] +@end group @end example @noindent @@ -1395,10 +1843,12 @@ @code{foo} has a numeric value at first, and a string value later on: @example +@group octave:13> foo = 1 foo = 1 octave:13> foo = "bar" foo = bar +@end group @end example @noindent @@ -1447,10 +1897,12 @@ that is exactly equivalent to @example +@group [u, s, v] = svd (a) a = u b = s c = v +@end group @end example In expressions like this, the number of values in each part of the @@ -1472,9 +1924,11 @@ is equivalent to @example +@group [u, s, v] = svd (a) a = u b = s +@end group @end example You can use an assignment anywhere an expression is called for. For
--- a/doc/interpreter/func.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/func.texi Wed Oct 30 23:00:41 1996 +0000 @@ -28,6 +28,8 @@ @node Defining Functions, Multiple Return Values, Functions and Scripts, Functions and Scripts @section Defining Functions +@cindex @code{function} statement +@cindex @code{endfunction} statement In its simplest form, the definition of a function named @var{name} looks like this: @@ -188,7 +190,6 @@ automatically initialized to the number of arguments that have actually been passed to the function. For example, we might rewrite the @code{avg} function like this: -@vindex nargout @example @group @@ -214,10 +215,50 @@ To avoid such problems and to provide useful messages, we check for both possibilities and issue our own error message. -The body of a user-defined function can contain a @code{return} -statement. This statement returns control to the rest of the Octave -program. A @code{return} statement is assumed at the end of every -function definition. +@defvr {Automatic Variable} nargin +When a function is called, this local variable is automatically +initialized to the number of arguments passed to the function. At the +top level, it holds the number of command line arguments that were +passed to Octave. +@end defvr + +@defvr {Automatic Variable} nargout +When a function is called, this local variable is automatically +initialized to the number of arguments expected to be returned. For +example, + +@example +@group +f () # nargout is 0 +[s, t] = f () # nargout is 2 +@end group +@end example +@end defvr + +@defvr {Built-in Variable} silent_functions +If the value of @code{silent_functions} is nonzero, internal output +from a function is suppressed. Otherwise, the results of expressions +within a function body that are not terminated with a semicolon will +have their values printed. The default value is 0. + +For example, if the function + +@example +function f () + 2 + 2 +endfunction +@end example + +@noindent +is executed, Octave will either print @samp{ans = 4} or nothing +depending on the value of @code{silent_functions}. +@end defvr + +@defvr {Built-in Variable} warn_missing_semicolon +If the value of this variable is nonzero, Octave will warn when +statements in function definitions don't end in semicolons. The default +value is 0. +@end defvr @node Multiple Return Values, Variable-length Argument Lists, Defining Functions, Functions and Scripts @section Multiple Return Values @@ -308,12 +349,23 @@ provided that the built-in variable @code{define_all_return_values} is nonzero. @xref{Built-in Variables}. +@defvr {Built-in Variable} default_return_value +The value given to otherwise unitialized return values if +@code{define_all_return_values} is nonzero. The default value is +@code{[]}. +@end defvr + +@defvr {Built-in Variable} define_all_return_values +If the value of @code{define_all_return_values} is nonzero, Octave +will substitute the value specified by @code{default_return_value} for +any return values that remain undefined when a function returns. The +default value is 0. +@end defvr + @node Variable-length Argument Lists, Variable-length Return Lists, Multiple Return Values, Functions and Scripts @section Variable-length Argument Lists @cindex Variable-length argument lists @cindex @code{...} -@findex va_arg -@findex va_start Octave has a real mechanism for handling functions that take an unspecified number of arguments, so it is not necessary to place an @@ -336,15 +388,20 @@ The ellipsis that marks the variable argument list may only appear once and must be the last element in the list of arguments. -Calling @code{va_start()} positions an internal pointer to the first -unnamed argument and allows you to cycle through the arguments more than -once. It is not necessary to call @code{va_start()} if you do not plan -to cycle through the arguments more than once. +@deftypefn {Built-in Function} {} va_start () +Position an internal pointer to the first unnamed argument and allows +you to cycle through the arguments more than once. It is not necessary +to call @code{va_start()} if you do not plan to cycle through the +arguments more than once. This function may only be called inside +functions that have been declared to accept a variable number of input +arguments. +@end deftypefn -The function @code{va_arg()} returns the value of the next available -argument and moves the internal pointer to the next argument. It is an -error to call @code{va_arg()} when there are no more arguments -available. +@deftypefn {Built-in Function} {} va_arg () +Return the value of the next available argument and moves the internal +pointer to the next argument. It is an error to call @code{va_arg()} +when there are no more arguments available. +@end deftypefn Sometimes it is useful to be able to pass all unnamed arguments to another function. The keyword @var{all_va_args} makes this very easy to @@ -379,17 +436,18 @@ end @end example -The keyword @code{all_va_args} always stands for the entire list of -optional argument, so it is possible to use it more than once within the -same function without having to call @code{va_start ()}. It can only -be used within functions that take a variable number of arguments. It -is an error to use it in other contexts. +@defvr {Keyword} all_va_args +This keyword stands for the entire list of optional argument, so it is +possible to use it more than once within the same function without +having to call @code{va_start ()}. It can only be used within functions +that take a variable number of arguments. It is an error to use it in +other contexts. +@end defvr @node Variable-length Return Lists, Returning From a Function, Variable-length Argument Lists, Functions and Scripts @section Variable-length Return Lists @cindex Variable-length return lists @cindex @code{...} -@findex vr_val Octave also has a real mechanism for handling functions that return an unspecified number of values, so it is no longer necessary to place an @@ -406,15 +464,20 @@ endfunction @end example -Each time @code{vr_val()} is called, it places the value of its argument -at the end of the list of values to return from the function. Once -@code{vr_val()} has been called, there is no way to go back to the -beginning of the list and rewrite any of the return values. - As with variable argument lists, the ellipsis that marks the variable return list may only appear once and must be the last element in the list of returned values. +@deftypefn {Built-in Function} {} vr_val (@var{val}) +Each time this function is called, it places the value of its argument +at the end of the list of values to return from the current function. +Once @code{vr_val()} has been called, there is no way to go back to the +beginning of the list and rewrite any of the return values. This +function may only be called within functions that have been declared to +return an unspecified number of output arguments (by using the special +ellipsis notation described above). +@end deftypefn + @node Returning From a Function, Function Files, Variable-length Return Lists, Functions and Scripts @section Returning From a Function @@ -456,6 +519,32 @@ without adding extra logic to avoid printing the message if the vector does contain a nonzero element. +@defvr {Keyword} return +When Octave encounters the keyword return, it returns control to be +calling function immediately. It is only valid within a function and +will result in an error if used at the top level. A @code{return} +statement is assumed at the end of every function definition. +@end defvr + +@defvr {Built-in Variable} return_last_computed_value +If the value of @code{return_last_computed_value} is true, and a +function is defined without explicitly specifying a return value, the +function will return the value of the last expression. Otherwise, no +value will be returned. The default value is 0. + +For example, the function + +@example +function f () + 2 + 2; +endfunction +@end example + +@noindent +will either return nothing, if @code{return_last_computed_value} is +0, or 4, if it is nonzero. +@end defvr + @node Function Files, Script Files, Returning From a Function, Functions and Scripts @section Function Files @cindex function file @@ -475,8 +564,7 @@ searches the list of directories specified by the built-in variable @code{LOADPATH} for files ending in @file{.m} that have the same base name as the undefined identifier.@footnote{The @samp{.m} suffix was -chosen for compatibility with @sc{Matlab}.} @xref{User Preferences} -for a description of @code{LOADPATH}. Once Octave finds a file +chosen for compatibility with @sc{Matlab}.} Once Octave finds a file with a name that matches, the contents of the file are read. If it defines a @emph{single} function, it is compiled and executed. @xref{Script Files}, for more information about how you can define more @@ -508,6 +596,54 @@ @code{"system"} gives the default behavior. If you set it to anything else, Octave will check the time stamps on all function files. +@defvr {Built-in Variable} LOADPATH +A colon separated list of directories in which to search for function +files. @xref{Functions and Scripts}. The value of @code{LOADPATH} +overrides the environment variable @code{OCTAVE_PATH}. @xref{Installation}. + +@code{LOADPATH} is now handled in the same way as @TeX{} handles +@code{TEXINPUTS}. If the path starts with @samp{:}, the standard path +is prepended to the value of @code{LOADPATH}. If it ends with @samp{:} +the standard path is appended to the value of @code{LOADPATH}. + +In addition, if any path element ends in @samp{//}, that directory and +all subdirectories it contains are searched recursively for function +files. This can result in a slight delay as Octave caches the lists of +files found in the @code{LOADPATH} the first time Octave searches for a +function. After that, searching is usually much faster because Octave +normally only needs to search its internal cache for files. + +To improve performance of recursive directory searching, it is best for +each directory that is to be searched recursively to contain +@emph{either} additional subdirectories @emph{or} function files, but +not a mixture of both. + +@xref{Organization of Functions} for a description of the function file +directories that are distributed with Octave. +@end defvr + +@defvr {Built-in Variable} ignore_function_time_stamp +This variable can be used to prevent Octave from making the system call +@code{stat()} each time it looks up functions defined in function files. +If @code{ignore_function_time_stamp} to @code{"system"}, Octave will not +automatically recompile function files in subdirectories of +@code{@value{OCTAVEHOME}/lib/@value{VERSION}} if they have changed since +they were last compiled, but will recompile other function files in the +@code{LOADPATH} if they change. If set to @code{"all"}, Octave will not +recompile any function files unless their definitions are removed with +@code{clear}. For any other value of @code{ignore_function_time_stamp}, +Octave will always check to see if functions defined in function files +need to recompiled. The default value of +@code{ignore_function_time_stamp} is @code{"system"}. +@end defvr + +@defvr {Built-in Variable} warn_function_name_clash +If the value of @code{warn_function_name_clash} is nonzero, a +warning is issued when Octave finds that the name of a function defined +in a function file differs from the name of the file. If the value is +0, the warning is omitted. The default value is 1. +@end defvr + @node Script Files, Dynamically Linked Functions, Function Files, Functions and Scripts @section Script Files @@ -605,6 +741,12 @@ string might come from user input, or depend on things that are not known until the function is evaluated). +@deftypefn {Built-in Function} {} source (@var{file}) +Parse and execute the contents of @var{file}. This is equivalent to +executing commands from a script file, but without requiring the file ot +be name @var{file}.m. +@end deftypefn + @node Dynamically Linked Functions, Organization of Functions, Script Files, Functions and Scripts @section Dynamically Linked Functions @@ -729,8 +871,3 @@ @item strings Miscellaneous string-handling functions. @end table - -@xref{User Preferences} for an explanation of the built-in variable -@code{LOADPATH}, and @ref{Function Files} for a description of the way -Octave resolves undefined variable and function names. -
--- a/doc/interpreter/gnuinfo.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/gnuinfo.texi Wed Oct 30 23:00:41 1996 +0000 @@ -10,7 +10,7 @@ @c This file documents the use of the standalone GNU Info program, @c versions 2.7 and later. -@node Using Info, Concept Index, Command Line Editing, Top +@node Using Info, Copying, Command Line Editing, Top @appendix Using Info @menu
--- a/doc/interpreter/gpl.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/gpl.texi Wed Oct 30 23:00:41 1996 +0000 @@ -4,8 +4,8 @@ @cindex warranty @cindex copyright -@node Copying, Introduction, Preface, Top -@unnumbered GNU GENERAL PUBLIC LICENSE +@node Copying, Concept Index, Using Info, Top +@appendix GNU GENERAL PUBLIC LICENSE @center Version 2, June 1991 @display @@ -16,7 +16,7 @@ of this license document, but changing it is not allowed. @end display -@unnumberedsec Preamble +@appendixsec Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public @@ -67,7 +67,7 @@ modification follow. @iftex -@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION @end iftex @ifinfo @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION @@ -329,7 +329,7 @@ @end ifinfo @page -@unnumberedsec Appendix: How to Apply These Terms to Your New Programs +@appendixsec Appendix: How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it
--- a/doc/interpreter/help.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/help.texi Wed Oct 30 23:00:41 1996 +0000 @@ -5,8 +5,7 @@ @node Help, Programming Utilities, Command History Functions, Top @chapter Help -@findex help - +@deffn {Command} help Octave's @code{help} command can be used to print brief usage-style messages, or to display information directly from an on-line version of the printed manual, using the GNU Info browser. If invoked without any @@ -34,3 +33,25 @@ @xref{Using Info}, for complete details about how to use the GNU Info browser to read the on-line version of the manual. +@end deffn + +@defvr {Built-in Variable} INFO_FILE +The variable @code{INFO_FILE} names the location of the Octave info file. +The default value is @code{"@value{OCTAVEHOME}/info/octave.info"}. +@end defvr + +@defvr {Built-in Variable} INFO_PROGRAM +The variable @code{INFO_PROGRAM} names the info program to run. Its +initial value is +@code{@value{OCTAVEHOME}/libexec/octave/VERSION/exec/ARCH/info}, but +that value can be overridden by the environment variable +@code{OCTAVE_INFO_PROGRAM}, or the command line argument +@code{--info-program NAME}, or by setting the value of +@code{INFO_PROGRAM} in a startup script. +@end defvr + +@defvr {Built-in Variable} suppress_verbose_help_message +If the value of @code{suppress_verbose_help_message} is nonzero, Octave +will not add additional help information to the end of the output from +the @code{help} command and usage messages for built-in commands. +@end defvr
--- a/doc/interpreter/history.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/history.texi Wed Oct 30 23:00:41 1996 +0000 @@ -5,17 +5,12 @@ @node Command History Functions, Help, System Utilities, Top @chapter Command History Functions -@findex edit_history -@findex run_history -@findex history - Octave provides three functions for viewing, editing, and re-running chunks of commands from the history list. -The function @code{history} displays a list of commands that you have -executed. It also allows you to write the current history to a file for -safe keeping, and to replace the history list with the commands stored -in a named file. Valid arguments are: +@deffn {Command} history options +If invoked with no arguments, @code{history} displays a list of commands +that you have executed. Valid options are: @table @code @item -w file @@ -38,11 +33,14 @@ For example, to display the five most recent commands that you have typed without displaying line numbers, use the command @samp{history -q 5}. +@end deffn -The function @code{edit_history} allows you to edit a block of commands -from the history list using the editor named by the environment -variable @code{EDITOR}, or the default editor (normally @code{vi}). It -is often more convenient to use @code{edit_history} to define functions +@deffn {Command} edit_history options +If invoked with no arguments, @code{edit_history} allows you to edit the +history list using the editor named by the variable @code{EDITOR}. The +commands to be edited are first copied to a temporary file. When you +exit the editor, Octave executes the commands that remain in the file. +It is often more convenient to use @code{edit_history} to define functions rather than attempting to enter them directly on the command line. By default, the block of commands is executed as soon as you exit the editor. To avoid executing any commands, simply delete all the lines @@ -69,13 +67,39 @@ the first command than the last command reverses the list of commands before placing them in the buffer to be edited. If both arguments are omitted, the previous command in the history list is used. +@end deffn -The command @code{run_history} is like @code{edit_history}, except that -the editor is not invoked, and the commands are simply executed as they -appear in the history list. +@defvr {Built-in Variable} EDITOR +A string naming the editor to use with the @code{edit_history} command. +If the environment variable @code{EDITOR} is set when Octave starts, its +value is used as the default. Otherwise, @code{EDITOR} is set to +@code{"vi"}. +@end defvr + +@deffn {Command} run_history +Similar to @code{edit_history}, except that the editor is not invoked, +and the commands are simply executed as they appear in the history list. +@end deffn -@findex diary +@defvr {Built-in Variable} history_file +This variable specifies the name of the file used to store command +history. The default value is @code{"~/.octave_hist"}, but may be +overridden by the environment variable @code{OCTAVE_HISTFILE}. +@end defvr +@defvr {Built-in Variable} history_size +This variable specifies how many entries to store in the history file. +The default value is @code{1024}, but may be overridden by the +environment variable @code{OCTAVE_HISTSIZE}. +@end defvr + +@defvr {Built-in Variable} saving_history +If the value of @code{saving_history} is @code{"true"}, command entered +on the command line are saved in the file specified by the variable +@code{history_file}. +@end defvr + +@deffn {Command} diary The @code{diary} command allows you to create a list of all commands @emph{and} the output they produce, mixed together just as you see them on your terminal. @@ -107,3 +131,32 @@ @noindent Without any arguments, @code{diary} toggles the current diary state. +@end deffn + +@deffn {Command} echo options +Control whether commands are displayed as they are executed. Valid +options are: + +@table @code +@item on +Enable echoing of commands as they are executed in script files. + +@item off +Disable echoing of commands as they are executed in script files. + +@item on all +Enable echoing of commands as they are executed in script files and +functions. + +@item off all +Disable echoing of commands as they are executed in script files and +functions. +@end table + +@noindent +If invoked without any arguments, @code{echo} toggles the current echo +state. +@end deffn + +@defvr {Built-in Variable} echo_executing_commands +@end defvr
--- a/doc/interpreter/image.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/image.texi Wed Oct 30 23:00:41 1996 +0000 @@ -11,8 +11,7 @@ manipulate images, however, so some of these functions may be useful even if you are not able to view the results. -@ftable @code -@item colormap +@deftypefn {Function File} {} colormap Set the current colormap. @code{colormap (@var{map})} sets the current colormap to @var{map}. The @@ -24,15 +23,18 @@ colormap with 64 entries). The default colormap is returned. With no arguments, @code{colormap} returns the current color map. +@end deftypefn -@item gray (@var{n}) +@deftypefn {Function File} {} gray (@var{n}) Create a gray colormap with values from 0 to @var{n}. The argument @var{n} should be a scalar. If it is omitted, 64 is assumed. +@end deftypefn -@item gray2ind +@deftypefn {Function File} {} gray2ind Convert a gray scale intensity image to an Octave indexed image. +@end deftypefn -@item image +@deftypefn {Function File} {} image Display an Octave image matrix. @code{image (@var{x})} displays a matrix as a color image. The elements @@ -41,8 +43,9 @@ @code{image (@var{x}, @var{zoom})} changes the zoom factor. The default value is 4. +@end deftypefn -@item imagesc +@deftypefn {Function File} {} imagesc Scale and display a matrix as an image. @code{imagesc (@var{x})} displays a scaled version of the matrix @@ -51,8 +54,9 @@ @code{imagesc (@var{x}, @var{zoom})} sets the magnification, the default value is 4. +@end deftypefn -@item imshow +@deftypefn {Function File} {} imshow Display images. @code{imshow (@var{x})} displays an indexed image using the current @@ -64,8 +68,9 @@ @code{imshow (@var{i}, @var{n})} displays a gray scale intensity image. @code{imshow (@var{r}, @var{g}, @var{b})} displays an RGB image. +@end deftypefn -@item ind2gray +@deftypefn {Function File} {} ind2gray Convert an Octave indexed image to a gray scale intensity image. @code{@var{y} = ind2gray (@var{x})} converts an indexed image to a gray @@ -74,8 +79,9 @@ @code{@var{y} = ind2gray (@var{x}, @var{map})} uses the specified colormap instead of the current one in the conversion process. +@end deftypefn -@item ind2rgb +@deftypefn {Function File} {} ind2rgb Convert an indexed image to red, green, and blue color components. @code{[@var{r}, @var{g}, @var{b}] = ind2rgb (@var{x})} uses the current @@ -83,27 +89,34 @@ @code{[@var{r}, @var{g}, @var{b}] = ind2rgb (@var{x}, @var{map})} uses the specified colormap. +@end deftypefn -@item loadimage +@deftypefn {Function File} {} loadimage Load an image file. @code{[@var{x}, @var{map}] = loadimage (@var{file})} loads an image and it's associated color map from the specified @var{file}. The image must be stored in Octave's image format. +@end deftypefn -@c @item rgb2ntsc -@c @item ntsc2rgb +@c @deftypefn {Function File} {} rgb2ntsc +@c @end deftypefn -@item ocean (@var{n}) +@c @c @deftypefn {Function File} {} ntsc2rgb +@c @end deftypefn + +@deftypefn {Function File} {} ocean (@var{n}) Create color colormap. The argument @var{n} should be a scalar. If it is omitted, 64 is assumed. +@end deftypefn -@item rgb2ind +@deftypefn {Function File} {} rgb2ind Convert and RGB image to an Octave indexed image. @code{[@var{x}, @var{map}] = rgb2ind (@var{r}, @var{g}, @var{b})} +@end deftypefn -@item saveimage +@deftypefn {Function File} {} saveimage Save a matrix to disk in image format. @code{saveimage (@var{file}, @var{x})} saves matrix @var{x} to @var{file} @@ -128,4 +141,9 @@ image is a gray scale image (the entries within each row of the colormap are equal) the gray scale ppm and PostScript image formats are used, otherwise the full color formats are used. -@end ftable +@end deftypefn + +@defvr {Built-in Variable} IMAGEPATH +A colon separated list of directories in which to search for image +files. +@end defvr
--- a/doc/interpreter/intro.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/intro.texi Wed Oct 30 23:00:41 1996 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Introduction, Invoking Octave, Copying, Top +@node Introduction, Invoking Octave, Preface, Top @chapter A Brief Introduction to Octave @cindex introduction @@ -15,6 +15,11 @@ other numerical experiments. It may also be used as a batch-oriented language. +Octave is also freely redistributable software. You may redistribute it +and/or modify it under the terms of the GNU General Public License as +published by the Free Software Foundation. The GPL is included in this +manual in @ref{Copying}. + This document corresponds to Octave version @value{VERSION}. @c XXX FIXME XXX -- add explanation about how and why Octave was written. @@ -25,8 +30,8 @@ @menu * Running Octave:: * Simple Examples:: +* Comments:: * Executable Octave Programs:: -* Comments:: * Errors:: @end menu @@ -44,17 +49,21 @@ key and then pressing @kbd{c}. Doing this will normally return you to Octave's prompt. +@cindex exiting octave +@cindex quitting octave To exit Octave, type @samp{quit}, or @samp{exit} at the Octave prompt. -@cindex exiting octave -@cindex quitting octave -@findex exit -@findex quit +@deftypefn {Built-in Function} {} exit (@var{status}) +@deftypefnx {Built-in Function} {} quit (@var{status}) +Exit the current Octave session. If the optional integer value +@var{status} is supplied, pass that value to the operating system as the +Octave's exit status. +@end deftypefn On systems that support job control, you can suspend Octave by sending it a @code{SIGTSTP} signal, usually by typing @kbd{C-z}. -@node Simple Examples, Executable Octave Programs, Running Octave, Introduction +@node Simple Examples, Comments, Running Octave, Introduction @section Simple Examples The following chapters describe all of Octave's features in detail, but @@ -99,7 +108,7 @@ @unnumberedsubsec Matrix Arithmetic Octave has a convenient operator notation for performing matrix -arithmetic. For example, to multiply the matrix @code{a} by a scalar +arithmetic. For example, to multiply the matrix @var{a} by a scalar value, type the command @example @@ -173,9 +182,11 @@ @ifinfo @example +@group dx -- = f (x, t) dt +@end group @end example @noindent @@ -205,6 +216,7 @@ is waiting for you to complete your input. @example +@group octave:8> function xdot = f (x, t) > > r = 0.25; @@ -218,6 +230,7 @@ > xdot(2) = c*a*x(1)*x(2)/(1 + b*x(1)) - d*x(2); > > endfunction +@end group @end example @noindent @@ -350,62 +363,7 @@ that contains the entire Octave manual. Help for using Info is provided in this manual in @ref{Using Info}. -@node Executable Octave Programs, Comments, Simple Examples, Introduction -@section Executable Octave Programs -@cindex executable scripts -@cindex scripts, executable -@cindex self contained programs -@cindex program, self contained -@cindex @samp{#!} - -Once you have learned Octave, you may want to write self-contained -Octave scripts, using the @samp{#!} script mechanism. You can do this -on many Unix systems @footnote{The @samp{#!} mechanism works on Unix -systems derived from Berkeley Unix, System V Release 4, and some System -V Release 3 systems.} (and someday on GNU). - -For example, you could create a text file named @file{hello}, containing -the following lines: - -@example -#! /usr/local/bin/octave -qf - -# a sample Octave program -printf ("Hello, world!\n"); -@end example - -@noindent -After making this file executable (with the @code{chmod} command), you -can simply type: - -@example -hello -@end example - -@noindent -at the shell, and the system will arrange to run Octave @footnote{The -line beginning with @samp{#!} lists the full file name of an interpreter -to be run, and an optional initial command line argument to pass to that -interpreter. The operating system then runs the interpreter with the -given argument and the full argument list of the executed program. The -first argument in the list is the full file name of the Octave program. -The rest of the argument list will either be options to Octave, or data -files, or both. The @code{-qf} option is usually specified in -stand-alone Octave programs to prevent them from printing the normal -startup message, and to keep them from behaving differently depending on -the contents of a particular user's @file{~/.octaverc} file. -@xref{Invoking Octave}.} as if you had typed: - -@example -octave hello -@end example - -@noindent -Self-contained Octave scripts are useful when you want to write a -program which users can invoke without knowing that the program is -written in the Octave language. - -@node Comments, Errors, Executable Octave Programs, Introduction +@node Comments, Executable Octave Programs, Simple Examples, Introduction @section Comments in Octave Programs @cindex @samp{#} @cindex @samp{%} @@ -467,7 +425,64 @@ purpose of a comment is to help you or another person understand the program at a later time. -@node Errors, , Comments, Introduction +@node Executable Octave Programs, Errors, Comments, Introduction +@section Executable Octave Programs +@cindex executable scripts +@cindex scripts, executable +@cindex self contained programs +@cindex program, self contained +@cindex @samp{#!} + +Once you have learned Octave, you may want to write self-contained +Octave scripts, using the @samp{#!} script mechanism. You can do this +on GNU systems and on many Unix systems @footnote{The @samp{#!} +mechanism works on Unix systems derived from Berkeley Unix, System V +Release 4, and some System V Release 3 systems.} + +For example, you could create a text file named @file{hello}, containing +the following lines: + +@example +@group +#! @value{OCTAVEHOME}/bin/octave -qf + +# a sample Octave program +printf ("Hello, world!\n"); +@end group +@end example + +@noindent +After making this file executable (with the @code{chmod} command), you +can simply type: + +@example +hello +@end example + +@noindent +at the shell, and the system will arrange to run Octave @footnote{The +line beginning with @samp{#!} lists the full file name of an interpreter +to be run, and an optional initial command line argument to pass to that +interpreter. The operating system then runs the interpreter with the +given argument and the full argument list of the executed program. The +first argument in the list is the full file name of the Octave program. +The rest of the argument list will either be options to Octave, or data +files, or both. The @code{-qf} option is usually specified in +stand-alone Octave programs to prevent them from printing the normal +startup message, and to keep them from behaving differently depending on +the contents of a particular user's @file{~/.octaverc} file. +@xref{Invoking Octave}.} as if you had typed: + +@example +octave hello +@end example + +@noindent +Self-contained Octave scripts are useful when you want to write a +program which users can invoke without knowing that the program is +written in the Octave language. + +@node Errors, , Executable Octave Programs, Introduction @section Errors There are two classes of errors that Octave produces when it encounters @@ -514,30 +529,32 @@ Octave will respond with @example +@group error: `x' undefined near line 1 column 24 error: evaluating expression near line 1, column 24 error: evaluating assignment expression near line 1, column 22 error: called from `f' +@end group @end example This error message has several parts, and gives you quite a bit of information to help you locate the source of the error. The messages are generated from the point of the innermost error, and provide a -traceback of enclosing expression and function calls. +traceback of enclosing expressions and function calls. In the example above, the first line indicates that a variable named @samp{x} was found to be undefined near line 1 and column 24 of some function or expression. For errors occurring within functions, lines -are numbered beginning with the line containing the @samp{function} -keyword. For errors occurring at the top level, the line number -indicates the input line number, which is usually displayed in the -prompt string. +from the beginning of the file containing the function definition. For +errors occurring at the top level, the line number indicates the input +line number, which is usually displayed in the prompt string. The second and third lines in the example indicate that the error occurred within an assignment expression, and the last line of the error message indicates that the error occurred within the function @samp{f}. -If the function @samp{f} had been called from another function, say -@samp{g}, the list of errors would have ended with one more line: +If the function @samp{f} had been called from another function, for +example, @samp{g}, the list of errors would have ended with one more +line: @example error: called from `g'
--- a/doc/interpreter/invoke.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/invoke.texi Wed Oct 30 23:00:41 1996 +0000 @@ -67,14 +67,6 @@ @cindex @code{-?} Print short help message and exit. -@item --ignore-init-file -@itemx --norc -@itemx -f -@cindex @code{--ignore-init-file} -@cindex @code{--norc} -@cindex @code{-f} -Don't read any of the system or user initialization files at startup. - @item --info-file @var{filename} @cindex @code{--info-file @var{filename}} Specify the name of the info file to use. The value of @var{filename} @@ -97,10 +89,26 @@ @cindex @code{-i} Force interactive behavior. +@item --no-init-file +@cindex @code{--no-init-file} +Don't read the @file{~/.octaverc} or @file{.octaverc} files. + @item --no-line-editing @cindex @code{--no-line-editing} Disable command-line editing and history. +@item --no-site-file +@cindex @code{--no-site-file} +Don't read the site-wide @file{octaverc} file. + +@item --norc +@itemx -f +@cindex @code{--norc} +@cindex @code{-f} +Don't read any of the system or user initialization files at startup. +This is equivalent to using both of the options @code{--no-init-file} +and @code{--no-site-file}. + @item --path @var{path} @itemx -p @var{path} @cindex @code{--path @var{path}} @@ -120,9 +128,11 @@ Don't print message at startup. @item --traditional +@itemx --braindead @cindex @code{--traditional} +@cindex @code{--braindead} Set initial values for user-preference variables to the following -values for compatibility with Matlab. +values for compatibility with @sc{Matlab}. @example PS1 = ">> " @@ -159,6 +169,56 @@ Execute commands from @var{file}. @end table +@defvr {Built-in Variable} argv +The command line arguments passed to Octave are available in this +variable. For example, if you invoked Octave using the command + +@example +octave --no-line-editing --silent +@end example + +@noindent +@code{argv} would be a string vector with the elements +@code{--no-line-editing} and @code{--silent}. +@end defvr + +@defvr {Built-in Variable} nargin +At the top level, this variable is defined as the number of command line +arguments that were passed to Octave. +@end defvr + +@defvr {Built-in Variable} program_invocation_name +@defvrx {Built-in Variable} program_name +When Octave starts, the value of @code{program_invocation_name} is +automatically set to the name that was typed at the shell prompt to run +Octave, and the value of @code{program_name} is automatically set to the +final component of @code{program_invocation_name}. For example, if you +typed @file{/usr/local/bin/octave} to start Octave, +@code{program_invocation_name} would have the value +@file{/usr/local/bin/octave}, and @code{program_name} would have the +value @code{octave}. + +If executing a script from the command line (e.g., @code{octave foo.m} +or using an executable Octave script, the program name is set to the +name of the script. @xref{Executable Octave Programs} for an example of +how to create an executable Octave script. +@end defvr + +Here is an example of using these variables to reproduce Octave's +command line. + +@example +printf ("%s", program_name); +for i = 1:nargin + printf (" %s", i, argv(i,:)); +endfor +printf ("\n"); +@end example + +@noindent +@xref{Index Expressions} for an explanation of how to properly index +arrays of strings and substrings in Octave. + @node Startup Files, , Command Line Options, Invoking Octave @section Startup Files @cindex initialization @@ -186,18 +246,18 @@ @item .octaverc @cindex @code{.octaverc} This file can be used to make changes to the default Octave environment -for a particular project. Octave searches for this file after it reads -@file{~/.octaverc}, so any use of the @code{cd} command in the -@file{~/.octaverc} file will affect the directory that Octave searches -for the file @file{.octaverc}. +for a particular project. Octave searches for this file in the current +directory after it reads @file{~/.octaverc}. Any use of the @code{cd} +command in the @file{~/.octaverc} file will affect the directory that +Octave searches for the file @file{.octaverc}. If you start Octave in your home directory, commands from from the file @file{~/.octaverc} will only be executed once. @end table -A message will be displayed as each of these files is read if you invoke -Octave with the @code{--verbose} option but without the @code{--silent} -option. +A message will be displayed as each of the startup files is read if you +invoke Octave with the @code{--verbose} option but without the +@code{--silent} option. Startup files may contain any valid Octave commands, including multiple function definitions.
--- a/doc/interpreter/io.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/io.texi Wed Oct 30 23:00:41 1996 +0000 @@ -19,19 +19,42 @@ @code{less} (and some versions of @code{more}) it also allows you to scan forward and backward, and search for specific items. -@findex fflush No output is displayed by the pager until just before Octave is ready to -print the top level prompt, or read from the standard input using the -@code{fscanf} or @code{scanf} functions. This means that there may be -some delay before any output appears on your screen if you have asked -Octave to perform a significant amount of work with a single command -statement. The function @code{fflush} may be used to force output to be -sent to the pager immediately. @xref{C-Style I/O Functions}. +print the top level prompt, or read from the standard input (for +example, by using the @code{fscanf} or @code{scanf} functions). This +means that there may be some delay before any output appears on your +screen if you have asked Octave to perform a significant amount of work +with a single command statement. The function @code{fflush} may be used +to force output to be sent to the pager immediately. @xref{C-Style I/O +Functions}. You can select the program to run as the pager by setting the variable @code{PAGER}, and you can turn paging off by setting the value of the -variable @code{page_screen_output} to the string @samp{"false"}. -@xref{User Preferences}. +variable @code{page_screen_output} to 0. + +@deffn {Command} more +Turn output pagination on or off. +@end deffn + +@defvr {Built-in Variable} PAGER +The default value is @code{"less"}, or, if @code{less} is not available +on your system, @code{"more"}. @xref{Installation}. +@end defvr + +@defvr {Built-in Variable} page_screen_output +If the value of @code{page_screen_output} is nonzero, all output +intended for the screen that is longer than one page is sent through a +pager. This allows you to view one screenful at a time. Some pagers +(such as @code{less}---see @ref{Installation}) are also capable of moving +backward on the output. The default value is 1. +@end defvr + +@defvr {Built-in Variable} page_output_immediately +If the value of @code{page_output_immediately} is nonzero, Octave sends +output to the pager as soon as it is available. Otherwise, Octave +buffers its output and waits until just before the prompt is printed to +flush it to the pager. The default value is 0. +@end defvr @menu * Basic Input and Output:: @@ -41,6 +64,15 @@ @node Basic Input and Output, C-Style I/O Functions, Input and Output, Input and Output @section Basic Input and Output +@menu +* Terminal Output:: +* Terminal Input:: +* Simple File I/O:: +@end menu + +@node Terminal Output, Terminal Input, Basic Input and Output, Basic Input and Output +@subsection Terminal Output + Since Octave normally prints the value of an expression as soon as it has been evaluated, the simplest of all I/O functions is a simple expression. For example, the following expression will display the @@ -54,9 +86,13 @@ This works well as long as it is acceptable to have the name of the variable (or @samp{ans}) printed along with the value. To print the value of a variable without printing its name, use the function -@code{disp}. For example, the following expression +@code{disp}. -@findex disp +The @code{format} command offers some control over the way Octave prints +values with @code{disp} and through the normal echoing mechanism. + +@deftypefn {Built-in Function} {} disp (@var{x}) +Display the value of @var{x}. For example, the following expression @example disp ("The value of pi is:"), disp (pi) @@ -72,26 +108,12 @@ @noindent Note that the output from @code{disp} always ends with a newline. - -A simple way to control the output format is with the @code{format} -statement. For example, to print more digits for pi you can use the -command - -@example -format long -@end example +@end deftypefn -@noindent -Then the expression above will print - -@example -The value of pi is: -3.14159265358979 -@end example - -@findex format - -Here is a summary of the options for @code{format}: +@deffn {Command} format options +Control the format of the output produced by @code{disp} and Octave's +normal echoing mechanism. Valid options are listed in the following +table. @table @code @item short @@ -157,15 +179,27 @@ @item bit Print the bit representation of numbers as stored in memory. For example, the value of @code{pi} is -@code{0100000000001001001000011111101101010100010001000010110100011000} -when printed in bit format on a workstation which stores 8 byte real -values in IEEE format with the least significant byte first. -This format only works for numeric types. + +@example +@group +01000000000010010010000111111011 +01010100010001000010110100011000 +@end group +@end example + +(shown here in two 32 bit sections for typesetting purposes) when +printed in bit format on a workstation which stores 8 byte real values +in IEEE format with the least significant byte first. This format only +works for numeric types. @end table +@end deffn -The @code{input} function may be used for prompting the user for a -value and storing the result in a variable. For example, -@findex input +@node Terminal Input, Simple File I/O, Terminal Output, Basic Input and Output +@subsection Terminal Input + +@deftypefn {Built-in Function} {} input (@var{prompt}) +@deftypefnx {Built-in Function} {} input (@var{prompt}, "s") +Print a prompt and wait for user input. For example, @example input ("Pick a number, any number! ") @@ -187,7 +221,7 @@ of values produced by the evaluation of the expression. If you are only interested in getting a literal string value, you can -call @code{input} with the character string @samp{s} as the second +call @code{input} with the character string @code{"s"} as the second argument. This tells Octave to return the string entered by the user directly, without evaluating it first. @@ -195,64 +229,38 @@ a good idea to always call @code{fflush (stdout)} before calling @code{input}. This will ensure that all pending output is written to the screen before your prompt. @xref{C-Style I/O Functions}. - -@findex keyboard +@end deftypefn -The second input function, @code{keyboard}, is normally used for simple -debugging. Using @code{keyboard}, it is possible to examine the values -of variables within a function, and to assign newassign new variables -Like @code{input}, it prompts the user for input, but no value is -returned, and it continues to prompt for input until the user types -@samp{quit}, or @samp{exit}. +@deftypefn {Built-in Function} {} keyboard (@var{prompt}) +This function is normally used for simple debugging. When the +@code{keyboard} function is executed, Octave prints a prompt and waits +for user input. The input strings are then evaluated and the results +are printed. This makes it possible to examine the values of variables +within a function, and to assign new values to variables. No value is +returned from the @code{keyboard} function, and it continues to prompt +for input until the user types @samp{quit}, or @samp{exit}. If @code{keyboard} is invoked without any arguments, a default prompt of @samp{debug> } is used. - -For both of these functions, the normal command line history and editing -functions are available at the prompt. - -@findex save -To save variables in a file, use the @code{save} command. For example, -the command +@end deftypefn -@example -save data a b c -@end example +For both @code{input} and @code{keyboard}, the normal command line +history and editing functions are available at the prompt. -@noindent -saves the variables @samp{a}, @samp{b}, and @samp{c} in the file -@file{data}. - -@vindex default_save_format -The @var{save} command can read files in Octave's text and binary -formats as well as @sc{Matlab}'s binary format. You can specify the default -format with the built-in variable @var{default_save_format} using one of -the following values: @code{"binary"} or @code{"mat-binary"}. The -initial default save format is Octave's text format. +@node Simple File I/O, , Terminal Input, Basic Input and Output +@subsection Simple File I/O -@vindex save_precision -You can use the built-in variable @code{save_precision} to specify the -number of digits to keep when saving data in text format. - -The list of variables to save may include wildcard patterns containing -the following special characters: -@table @code -@item ? -Match any single character. +The @code{save} and @code{load} commands allow data to be written to and +read from disk files in various formats. -@item * -Match zero or more characters. +@deffn {Command} save options file v1 v2 @dots{} +Save the named variables @var{v1}, @var{v2}, @dots{} in the file +@var{file}. The special filename @samp{-} can be used to write the +output to your terminal. If no variable names are listed, Octave saves +all the variables in the current scope. Valid options for the +@code{save} command are listed in the following table. -@item [ @var{list} ] -Match the list of characters specified by @var{list}. If the first -character is @code{!} or @code{^}, match all characters except those -specified by @var{list}. For example, the pattern @samp{[a-zA-Z]} will -match all lower and upper case alphabetic characters. -@end table - -The following options may be specified for @code{save}. - -@ftable @code +@table @code @item -ascii Save the data in Octave's text data format. Using this flag overrides the value of the built-in variable @code{default_save_format}. @@ -275,16 +283,58 @@ @item -save-builtins Force Octave to save the values of built-in variables too. By default, Octave does not save built-in variables. -@end ftable +@end table + +The list of variables to save may include wildcard patterns containing +the following special characters: +@table @code +@item ? +Match any single character. -@findex load +@item * +Match zero or more characters. + +@item [ @var{list} ] +Match the list of characters specified by @var{list}. If the first +character is @code{!} or @code{^}, match all characters except those +specified by @var{list}. For example, the pattern @samp{[a-zA-Z]} will +match all lower and upper case alphabetic characters. +@end table + Saving global variables also saves the global status of the variable, so that if it is restored at a later time using @samp{load}, it will be restored as a global variable. -To restore the values from a file, use the @code{load} command. For -example, to restore the variables saved in the file @file{data}, use the -command +The command + +@example +save -binary data a b* +@end example + +@noindent +saves the variable @samp{a} and all variables beginning with @samp{b} to +the file @file{data} in Octave's binary format. +@end deffn + +There are two variables that modify the behavior of @code{save}. + +@defvr {Built-in Variable} default_save_format +This variable specifies the default format for the @code{save} command. +It should have one of the following values: @code{"ascii"}, +@code{"binary"}, @code{float-binary}, or @code{"mat-binary"}. The +initial default save format is Octave's text format. +@end defvr + +@defvr {Built-in Variable} save_precision +This variable specifies the number of digits to keep when saving data in +text format. The default value is 17. +@end defvr + +@deffn {Command} load options file v1 v2 @dots{} +To restore the values from a file, use the @code{load} command. As with +@code{save}, you may specify a list of variables and @code{load} will +only extract those variables with names that match. For example, to +restore the variables saved in the file @file{data}, use the command @example load data @@ -301,18 +351,15 @@ both of these cases are likely to be the result of some sort of error, they will generate warnings. -As with @code{save}, you may specify a list of variables and @code{load} -will only extract those variables with names that match. - The @code{load} command can read data stored in Octave's text and binary formats, and @sc{Matlab}'s binary format. It will automatically detect the type of file and do conversion from different floating point formats (currently only IEEE big and little endian, though other formats may added in the future). -The following options may be specified for @code{load}. +Valid options for @code{load} are listed in the following table. -@ftable @code +@table @code @item -force Force variables currently in memory to be overwritten by variables with the same name found in the file. @@ -325,36 +372,38 @@ @item -mat-binary Force Octave to assume the file is in @sc{Matlab}'s binary format. -@end ftable +@end table +@end deffn @node C-Style I/O Functions, , Basic Input and Output, Input and Output @section C-Style I/O Functions -The C-style input and output functions provide most of the functionality -of the C programming language's standard I/O library. The argument -lists for some of the input functions are slightly different, however, -because Octave has no way of passing arguments by reference. +Octave's C-style input and output functions provide most of the +functionality of the C programming language's standard I/O library. The +argument lists for some of the input functions are slightly different, +however, because Octave has no way of passing arguments by reference. In the following, @var{file} refers either to an integer file number (as returned by @file{fopen}) or a file name. There are three files that are always available: -@table @code -@item stdin +@defvr {Built-in Variable} stdin The standard input stream (file number 0). When Octave is used interactively, this is filtered through the command line editing functions. +@end defvr -@item stdout +@defvr {Built-in Variable} stdout The standard output stream (file number 1). Data written to the standard output is normally filtered through the pager. +@end defvr -@item stderr +@defvr {Built-in Variable} stderr The standard error stream (file number 2). Even if paging is turned on, the standard error is not sent to the pager. It is useful for error messages and prompts. -@end table +@end defvr You should always use the symbolic names given in the table above, rather than referring to these files by number, since it will make @@ -380,13 +429,11 @@ @node Opening and Closing Files, Formatted Output, C-Style I/O Functions, C-Style I/O Functions @subsection Opening and Closing Files -@findex fopen -To open a file, use the function @code{fopen (name, mode)}. It returns -an integer value that may be used to refer to the file later. The -second argument is a one or two character string that specifies whether -the file is to be opened for reading, writing, or both. - -For example, +@deftypefn {Built-in Function} {fid =} fopen (@var{name}, @var{mode}) +Opens the named file with the specified mode. Returns an integer value +that may be used to refer to the file later. The @var{mode} is a +one or two character string that specifies whether the file is to be +opened for reading, writing, or both. For example, @example myfile = fopen ("splat.dat", "r"); @@ -396,12 +443,6 @@ opens the file @file{splat.dat} for reading. Opening a file that is already open has no effect. -@c XXX FIXME XXX -- There still seem to be some minor bugs with fopen. -@c You should probably get an error if you try to reopen a file with a -@c different mode. You should probably get a warning if the file is -@c already open, etc. - - The possible values @samp{mode} may have are @table @asis @@ -425,12 +466,13 @@ Open or create a file for reading or writing at the end of the file. @end table +@end deftypefn -@findex fclose -To close a file once you are finished with it, use the function -@code{fclose (@var{file})}. If an error is encountered while trying to close -the file, an error message is printed and @code{fclose} returns 0. -Otherwise, it returns 1. +@deftypefn {Built-in Function} {} fclose (@var{fid}) +Closes the specified file. If an error is encountered while trying to +close the file, an error message is printed and @code{fclose} returns +0. Otherwise, it returns 1. +@end deftypefn @node Formatted Output, Output Conversion Syntax, Opening and Closing Files, C-Style I/O Functions @subsection Formatted Output @@ -440,23 +482,24 @@ The following functions are available for formatted output. They are modelled after the C language functions of the same name. -@ftable @code -@item printf (@var{template}, ...) +@deftypefn {Function File} {} printf (@var{template}, @dots{}) The @code{printf} function prints the optional arguments under the control of the template string @var{template} to the stream @code{stdout}. +@end deftypefn -@item fprintf (@var{file}, @var{template}, ...) +@deftypefn {Built-in Function} {} fprintf (@var{fid}, @var{template}, @dots{}) This function is just like @code{printf}, except that the output is -written to the stream @var{file} instead of @code{stdout}. +written to the stream @var{fid} instead of @code{stdout}. +@end deftypefn -@item sprintf (@var{template}, ...) +@deftypefn {Built-in Function} {} sprintf (@var{template}, @dots{}) This is like @code{printf}, except that the output is written to a string. Unlike the C library function, which requires you to provide a suitably sized string as an argument, Octave's @code{sprintf} function returns the string, automatically sized to hold all of the items converted. -@end ftable +@end deftypefn The @code{printf} function can be used to print any number of arguments. The template string argument you supply in a call provides @@ -801,21 +844,22 @@ Here are the descriptions of the functions for performing formatted input. -@ftable @code -@item scanf (@var{template}) +@deftypefn {Built-in Function} {} scanf (@var{template}) The @code{scanf} function reads formatted input from the stream @code{stdin} under the control of the template string @var{template}. The resulting values are returned. +@end deftypefn -@item fscanf (@var{file}, @var{template}) +@deftypefn {Built-in Function} {} fscanf (@var{fid}, @var{template}) This function is just like @code{scanf}, except that the input is read -from the stream @var{file} instead of @code{stdin}. +from the stream @var{fid} instead of @code{stdin}. +@end deftypefn -@item sscanf (@var{string}, @var{template}) +@deftypefn {Built-in Function} {} sscanf (@var{string}, @var{template}) This is like @code{scanf}, except that the characters are taken from the string @var{string} instead of from a stream. Reaching the end of the string is treated as an end-of-file condition. -@end ftable +@end deftypefn Calls to @code{scanf} are superficially similar to calls to @code{printf} in that arbitrary arguments are read under the control of @@ -1017,10 +1061,9 @@ They are @code{fread} and @code{fwrite} and are patterned after the standard C functions with the same names. -@ftable @code -@item fread (@var{file}, @var{size}, @var{precision}) +@deftypefn {Built-in Function} {} fread (@var{fid}, @var{size}, @var{precision}) This function reads data in binary form of type @var{precision} from the -specified @var{file}, which may be either a file name, or a file number +specified @var{fid}, which may be either a file name, or a file number as returned from @code{fopen}. The argument @var{size} specifies the size of the matrix to return. It @@ -1039,10 +1082,11 @@ The @code{fread} function returns two values, @code{data}, which is the data read from the file, and @code{count}, which is the number of elements read. +@end deftypefn -@item fwrite (@var{file}, @var{data}, @var{precision}) +@deftypefn {Built-in Function} {} fwrite (@var{fid}, @var{data}, @var{precision}) This function writes data in binary form of type @var{precision} to the -specified @var{file}, which may be either a file name, or a file number +specified @var{fid}, which may be either a file name, or a file number as returned from @code{fopen}. The argument @var{data} is a matrix of values that are to be written to @@ -1058,44 +1102,56 @@ The behavior of @code{fwrite} is undefined if the values in @var{data} are too large to fit in the specified precision. -@end ftable +@end deftypefn @node Other I/O Functions, , Binary I/O, C-Style I/O Functions @subsection Other I/O Functions -@findex fgets -@example -fgets (@var{file}, len) -@end example +@deftypefn {Built-in Function} {} fgetl (@var{fid}, @var{len}) +Read @samp{len} characters from a file. +@end deftypefn + +@deftypefn {Built-in Function} {} fgets (@var{fid}, @var{len}) Read @samp{len} characters from a file. +@end deftypefn -To flush output to a stream, use the function @code{fflush (@var{file})}. -This is useful for ensuring that all pending output makes it to the -screen before some other event occurs. For example, it is always a good -idea to flush the standard output stream before calling @code{input}. +@deftypefn {Built-in Function} {} fflush (@var{fid}) +Flush output to @var{fid}. This is useful for ensuring that all +pending output makes it to the screen before some other event occurs. +For example, it is always a good idea to flush the standard output +stream before calling @code{input}. +@end deftypefn Three functions are available for setting and determining the position of the file pointer for a given file. -@findex ftell -The position of the file pointer (as the number of characters from the -beginning of the file) can be obtained using the the function -@code{ftell (@var{file})}. +@deftypefn {Built-in Function} {} ftell (@var{fid}) +Return the position of the file pointer as the number of characters +from the beginning of the file @var{fid}. +@end deftypefn -@findex fseek -To set the file pointer to any location within the file, use the -function @code{fseek (@var{file}, offset, origin)}. The pointer is placed -@code{offset} characters from the @code{origin}, which may be one of the -predefined variables @code{SEEK_CUR} (current position), @code{SEEK_SET} -(beginning), or @code{SEEK_END} (end of file). If @code{origin} is -omitted, @code{SEEK_SET} is assumed. The offset must be zero, or a -value returned by @code{ftell} (in which case @code{origin} must be -@code{SEEK_SET}. @xref{Predefined Constants}. +@deftypefn {Built-in Function} {} fseek (@var{fid}, offset, origin) +Set the file pointer to any location within the file @var{fid}. The +pointer is positioned @code{offset} characters from the @code{origin}, +which may be one of the predefined variables @code{SEEK_CUR} (current +position), @code{SEEK_SET} (beginning), or @code{SEEK_END} (end of +file). If @code{origin} is omitted, @code{SEEK_SET} is assumed. The +offset must be zero, or a value returned by @code{ftell} (in which case +@code{origin} must be @code{SEEK_SET}. +@end deftypefn -@findex frewind -The function @code{frewind (@var{file})} moves the file pointer to the -beginning of a file, returning 1 for success, and 0 if an error was -encountered. It is equivalent to @code{fseek (@var{file}, 0, SEEK_SET)}. +@defvr {Built-in Variable} SEEK_SET +@defvrx {Built-in Variable} SEEK_CUR +@defvrx {Built-in Variable} SEEK_END +These variables may be used as the optional third argument for the +function @code{fseek}. +@end defvr + +@deftypefn {Built-in Function} {} frewind (@var{fid}) +Move the file pointer to the beginning of the file @var{fid}, returning +1 for success, and 0 if an error was encountered. It is equivalent to +@code{fseek (@var{fid}, 0, SEEK_SET)}. +@end deftypefn The following example stores the current file position in the variable @samp{marker}, moves the pointer to the beginning of the file, reads @@ -1108,22 +1164,22 @@ fseek (myfile, marker, SEEK_SET); @end example -@findex feof -The function @code{feof (@var{file})} allows you to find out if an -end-of-file condition has been encountered for a given file. Note that -it will only return 1 if the end of the file has already been -encountered, not if the next read operation will result in an -end-of-file condition. +@deftypefn {Built-in Function} {} feof (@var{fid}) +Returns 1 if an end-of-file condition has been encountered for a given +file and 0 otherwise. Note that it will only return 1 if the end of the +file has already been encountered, not if the next read operation will +result in an end-of-file condition. +@end deftypefn -@findex ferror -Similarly, the function @code{ferror (@var{file})} allows you to find -out if an error condition has been encountered for a given file. Note -that it will only return 1 if an error has already been encountered, not -if the next operation will result in an error condition. +@deftypefn {Built-in Function} {} ferror (@var{fid}) +Returns 1 if an error condition has been encountered for a given file +and 0 otherwise. Note that it will only return 1 if an error has +already been encountered, not if the next operation will result in an +error condition. +@end deftypefn -@findex kbhit -The function @code{kbhit} may be usd to read a single keystroke from the -keyboard. For example, +@deftypefn {Built-in Function} {} kbhit () +Read a single keystroke from the keyboard. For example, @example x = kbhit (); @@ -1132,8 +1188,9 @@ @noindent will set @var{x} to the next character typed at the keyboard, without requiring a carriage return to be typed. +@end deftypefn -@findex freport +@deftypefn {Built-in Function} {} freport () Finally, it is often useful to know exactly which files have been opened, and whether they are open for reading, writing, or both. The command @code{freport} prints this information for all open files. For @@ -1151,3 +1208,25 @@ 3 r myfile @end group @end example +@end deftypefn + +@deftypefn {Built-in Function} {} fputs (@var{fid}, @var{string}) +Write a string to a file with no formatting. +@end deftypefn + +@deftypefn {Built-in Function} {} puts (@var{string}) +Write a string to the standard output with no formatting. +@end deftypefn + +@deftypefn {Built-in Function} {[@var{in}, @var{out}, @var{pid}] =} popen2 (@var{command}, @var{args}) +Start a subprocess with 2-way communication. +@end deftypefn + +@deftypefn {Built-in Function} {fid =} popen (@var{command}, @var{mode}) +Open a pipe to a subprocess. +@end deftypefn + +@deftypefn {Built-in Function} {} pclose (@var{fid}) +Close a pipe from a subprocess. +@end deftypefn +
--- a/doc/interpreter/linalg.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/linalg.texi Wed Oct 30 23:00:41 1996 +0000 @@ -19,15 +19,9 @@ @node Basic Matrix Functions, Matrix Factorizations, Linear Algebra, Linear Algebra @section Basic Matrix Functions -@ftable @code -@item balance - -@example -aa = balance (a, opt) -[dd, aa] = balance(a, opt) -[dd, aa] = balance (a, opt) -[cc, dd, aa, bb] = balance (a, b, opt) -@end example +@deftypefn {Built-in Function} {@var{aa} =} balance (@var{a}, @var{opt}) +@deftypefnx {Built-in Function} {[@var{dd}, @var{aa}] =} balance (@var{a}, @var{opt}) +@deftypefnx {Built-in Function} {[@var{cc}, @var{dd}, @var{aa}, @var{bb]} =} balance (@var{a}, @var{b}, @var{opt}) @code{[dd, aa] = balance (a)} returns @code{aa = dd \ a * dd}. @code{aa} is a matrix whose row/column norms are roughly equal in @@ -64,22 +58,20 @@ Generalized eigenvalue problem balancing uses Ward's algorithm (SIAM Journal on Scientific and Statistical Computing, 1981). +@end deftypefn -@item cond (@var{a}) +@deftypefn {} {} cond (@var{a}) Compute the (two-norm) condition number of a matrix. @code{cond (a)} is defined as @code{norm (a) * norm (inv (a))}, and is computed via a singular value decomposition. - -@item det (@var{a}) -Compute the determinant of @var{a} using LINPACK. - -@item eig +@end deftypefn -@example - = eig (a) -[v, lambda] = eig (a) -@end example +@deftypefn {Built-in Function} {} det (@var{a}) +Compute the determinant of @var{a} using LINPACK. +@end deftypefn +@deftypefn {Built-in Function} {@var{lambda} =} eig (@var{a}) +@deftypefnx {Built-in Function} {[@var{v}, @var{lambda}] =} eig (@var{a}) The eigenvalues (and eigenvectors) of a matrix are computed in a several step process which begins with a Hessenberg decomposition (see @code{hess}), followed by a Schur decomposition (see @code{schur}), from @@ -87,14 +79,10 @@ computed by further manipulations of the Schur decomposition. See also: @code{hess}, @code{schur}. - -@item givens +@end deftypefn -@example -[c, s] = givens (x, y) -G = givens (x, y) -@end example - +@deftypefn {Built-in Function} {@var{G} =} givens (@var{x}, @var{y}) +@deftypefnx {Built-in Function} {[@var{c}, @var{s}] =} givens (@var{x}, @var{y}) @code{G = givens(x, y)} returns a @iftex @tex @@ -106,12 +94,14 @@ @end ifinfo orthogonal matrix @code{G = [c s; -s' c]} such that @code{G [x; y] = [*; 0]} (x, y scalars) +@end deftypefn -@item inv (@var{a}) -@itemx inverse (@var{a}) +@deftypefn {Built-in Function} {} inv (@var{a}) +@deftypefnx {Built-in Function} {} inverse (@var{a}) Compute the inverse of the square matrix @var{a}. +@end deftypefn -@item norm (@var{a}, @var{p}) +@deftypefn {Function File} {} norm (@var{a}, @var{p}) Compute the p-norm of the matrix @var{a}. If the second argument is missing, @code{p = 2} is assumed. @@ -143,8 +133,9 @@ @item other p-norm of @var{a}, @code{(sum (abs (a) .^ p)) ^ (1/p)}. @end table +@end deftypefn -@item null (@var{a}, @var{tol}) +@deftypefn {Function File} {} null (@var{a}, @var{tol}) Returns an orthonormal basis of the null space of @var{a}. The dimension of the null space is taken as the number of singular @@ -154,8 +145,9 @@ @example max (size (a)) * max (svd (a)) * eps @end example +@end deftypefn -@item orth (@var{a}, @var{tol}) +@deftypefn {Function File} {} orth (@var{a}, @var{tol}) Returns an orthonormal basis of the range of @var{a}. The dimension of the range space is taken as the number of singular @@ -165,8 +157,9 @@ @example max (size (a)) * max (svd (a)) * eps @end example +@end deftypefn -@item pinv (@var{X}, @var{tol}) +@deftypefn {Function File} {} pinv (@var{X}, @var{tol}) Returns the pseudoinverse of @var{X}. Singular values less than @var{tol} are ignored. @@ -178,31 +171,31 @@ @noindent where @code{sigma_max (@var{X})} is the maximal singular value of @var{X}. +@end deftypefn -@item rank (@var{a}, @var{tol}) +@deftypefn {Function File} {} rank (@var{a}, @var{tol}) Compute the rank of @var{a}, using the singular value decomposition. The rank is taken to be the number of singular values of @var{a} that are greater than the specified tolerance @var{tol}. If the second argument is omitted, it is taken to be @example -tol = max (size (a)) * sigma (1) * eps; +tol = max (size (a)) * sigma (1) * eps; @end example @noindent where @code{eps} is machine precision and @code{sigma} is the largest singular value of @code{a}. +@end deftypefn -@item trace (@var{a}) +@deftypefn {Function File} {} trace (@var{a}) Compute the trace of @var{a}, @code{sum (diag (a))}. - -@end ftable +@end deftypefn @node Matrix Factorizations, Functions of a Matrix, Basic Matrix Functions, Linear Algebra @section Matrix Factorizations -@ftable @code -@item chol (@var{a}) +@deftypefn {Built-in Function} {} chol (@var{a}) Compute the Cholesky factor, @var{r}, of the symmetric positive definite matrix @var{a}, where @iftex @@ -216,14 +209,11 @@ r' * r = a. @end example @end ifinfo - -@item hess (@var{a}) -Compute the Hessenberg decomposition of the matrix @var{a}. +@end deftypefn -@example - h = hess (a) -[p, h] = hess (a) -@end example +@deftypefn {Built-in Function} {@var{h} =} hess (@var{a}) +@deftypefnx {Built-in Function} {[@var{p}, @var{h}] =} hess (@var{a}) +Compute the Hessenberg decomposition of the matrix @var{a}. The Hessenberg decomposition is usually used as the first step in an eigenvalue computation, but has other applications as well (see Golub, @@ -232,8 +222,9 @@ square unitary matrix (@code{p' * p = I}, using complex-conjugate transposition) and @code{h} is upper Hessenberg (@code{i >= j+1 => h (i, j) = 0}). +@end deftypefn -@item lu (@var{a}) +@deftypefn {Built-in Function} {[@var{l}, @var{u}, @var{p}] =} lu (@var{a}) Compute the LU decomposition of @var{a}, using subroutines from LAPACK. The result is returned in a permuted form, according to the optional return value @var{p}. For example, given the matrix @@ -262,8 +253,9 @@ 0 1 1 0 @end example +@end deftypefn -@item qr (@var{a}) +@deftypefn {Built-in Function} {[@var{q}, @var{r}] =} qr (@var{a}) Compute the QR factorization of @var{a}, using standard LAPACK subroutines. For example, given the matrix @code{a = [1, 2; 3, 4]}, @@ -346,14 +338,10 @@ The permuted @code{qr} factorization @code{[q, r, pi] = qr (a)} factorization allows the construction of an orthogonal basis of @code{span (a)}. - -@item schur +@end deftypefn -@example -[u, s] = schur (a, opt) opt = "a", "d", or "u" - s = schur (a) -@end example - +@deftypefn {Built-in Function} {@var{s}} schur (@var{a}) +@deftypefnx {Built-in Function} {[@var{u}, @var{s}] =} schur (@var{a}, @var{opt}) The Schur decomposition is used to compute eigenvalues of a square matrix, and has applications in the solution of algebraic Riccati equations in control (see @code{are} and @code{dare}). @@ -556,8 +544,10 @@ @ifinfo @code{s}. @end ifinfo +@end deftypefn -@item svd (@var{a}) +@deftypefn {Built-in Function} {@var{s} =} svd (@var{a}) +@deftypefnx {Built-in Function} {[@var{u}, @var{s}, @var{v}] =} svd (@var{a}) Compute the singular value decomposition of @var{a} @iftex @tex @@ -633,18 +623,12 @@ If given a second argument, @code{svd} returns an economy-sized decomposition, eliminating the unnecessary rows or columns of @var{u} or @var{v}. -@end ftable +@end deftypefn @node Functions of a Matrix, , Matrix Factorizations, Linear Algebra @section Functions of a Matrix -@ftable @code -@item expm - -@example -expm (a) -@end example - +@deftypefn {Built-in Function} {} expm (@var{a}) Returns the exponential of a matrix, defined as the infinite Taylor series @iftex @@ -728,26 +712,29 @@ @code{Dq(a)} @end ifinfo is ill-conditioned. +@end deftypefn -@item logm (@var{a}) +@deftypefn {Built-in Function} {} logm (@var{a}) Compute the matrix logarithm of the square matrix @var{a}. Note that this is currently implemented in terms of an eigenvalue expansion and needs to be improved to be more robust. +@end deftypefn -@item sqrtm (@var{a}) +@deftypefn {Built-in Function} {} sqrtm (@var{a}) Compute the matrix square root of the square matrix @var{a}. Note that this is currently implemented in terms of an eigenvalue expansion and needs to be improved to be more robust. +@end deftypefn -@item kron (@var{a}, @var{b}) - +@deftypefn {Function File} {} kron (@var{a}, @var{b}) Form the kronecker product of two matrices, defined block by block as @example x = [a(i, j) b] @end example +@end deftypefn -@item qzhess (@var{a}, @var{b}) +@deftypefn {Function File} {} qzhess (@var{a}, @var{b}) Compute the Hessenberg-triangular decomposition of the matrix pencil @code{(a, b)}. This function returns @code{aa = q * a * z}, @code{bb = q * b * z}, @code{q}, @code{z} orthogonal. For example, @@ -762,11 +749,13 @@ Algorithm taken from Golub and Van Loan, @cite{Matrix Computations, 2nd edition}. +@end deftypefn -@item qzval (@var{a}, @var{b}) +@deftypefn {Built-in Function} {} qzval (@var{a}, @var{b}) Compute generalized eigenvalues. +@end deftypefn -@item syl (@var{a}, @var{b}, @var{c}) +@deftypefn {Built-in Function} {} syl (@var{a}, @var{b}, @var{c}) Solve the Sylvester equation @iftex @tex @@ -783,4 +772,4 @@ @end ifinfo using standard LAPACK subroutines. -@end ftable +@end deftypefn
--- a/doc/interpreter/matrix.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/matrix.texi Wed Oct 30 23:00:41 1996 +0000 @@ -20,26 +20,25 @@ @node Finding Elements and Checking Conditions, Rearranging Matrices, Matrix Manipulation, Matrix Manipulation @section Finding Elements and Checking Conditions -@findex any -@findex all - The functions @code{any} and @code{all} are useful for determining whether any or all of the elements of a matrix satisfy some condition. The @code{find} function is also useful in determining which elements of a matrix meet a specified condition. -Given a vector, the function @code{any} returns 1 if any element of the -vector is nonzero. +@deftypefn {Built-in Function} {} any (@var{x}) +For a vector argument, return 1 if any element of the vector is +nonzero. -For a matrix argument, @code{any} returns a row vector of ones and +For a matrix argument, return a row vector of ones and zeros with each element indicating whether any of the elements of the corresponding column of the matrix are nonzero. For example, @example -octave:13> any (eye (2, 4)) -ans = +@group +any (eye (2, 4)) - 1 1 0 0 + @result{} [ 1, 1, 0, 0 ] +@end group @end example To see if any of the elements of a matrix are nonzero, you can use a @@ -48,18 +47,24 @@ @example any (any (a)) @end example +@end deftypefn +@deftypefn {Built-in Function} {} all (@var{x}) The function @code{all} behaves like the function @code{any}, except that it returns true only if all the elements of a vector, or all the elements in a column of a matrix, are nonzero. +@end deftypefn Since the comparison operators (@pxref{Comparison Ops}) return matrices of ones and zeros, it is easy to test a matrix for many things, not just whether the elements are nonzero. For example, @example -octave:13> all (all (rand (5) < 0.9)) -ans = 0 +@group +all (all (rand (5) < 0.9)) + + @result{} 0 +@end group @end example @noindent @@ -70,100 +75,133 @@ @code{while} statements) Octave treats the test as if you had typed @code{all (all (condition))}. -@findex isinf -@findex finite -@findex isnan +@deftypefn {Mapping Function} {} isinf (@var{x}) +Return 1 for elements of @var{x} that are infinite and zero +otherwise. For example, + +@example +@group +isinf ([13, Inf, NaN]) -The functions @code{isinf}, @code{finite}, and @code{isnan} return 1 if -their arguments are infinite, finite, or not a number, respectively, and -return 0 otherwise. For matrix values, they all work on an element by -element basis. For example, evaluating the expression + @result{} [ 0, 1, 0 ] +@end group +@end example +@end deftypefn + +@deftypefn {Mapping Function} {} isnan (@var{x}) +Return 1 for elements of @var{x} that are NaN values and zero +otherwise. For example, @example -isinf ([1, 2; Inf, 4]) -@end example +@group +isnan ([13, Inf, NaN]) -@noindent -produces the matrix + @result{} [ 0, 0, 1 ] +@end group +@end example +@end deftypefn + +@deftypefn {Mapping Function} {} finite (@var{x}) +Return 1 for elements of @var{x} that are NaN values and zero +otherwise. For example, @example -ans = +@group +finite ([13, Inf, NaN]) - 0 0 - 1 0 + @result{} [ 1, 0, 0 ] +@end group @end example +@end deftypefn -@findex find - +@deftypefn {Built-in Function} {} find (@var{x}) The function @code{find} returns a vector of indices of nonzero elements of a matrix. To obtain a single index for each matrix element, Octave pretends that the columns of a matrix form one long vector (like Fortran arrays are stored). For example, @example -octave:13> find (eye (2)) -ans = +@group +find (eye (2)) - 1 - 4 + @result{} [ 1; 4 ] +@end group @end example If two outputs are requested, @code{find} returns the row and column indices of nonzero elements of a matrix. For example, @example -octave:13> [i, j] = find (eye (2)) -i = +@group +[i, j] = find (2 * eye (2)) - 1 - 2 + @result{} i = [ 1; 2 ] -j = - - 1 - 2 + @result{} j = [ 1; 2 ] +@end group @end example -If three outputs are requested, @code{find} also returns the nonzero -values in a vector. +If three outputs are requested, @code{find} also returns a vector +containing the the nonzero values. For example, + +@example +@group +[i, j, v] = find (3 * eye (2)) + + @result{} i = [ 1; 2 ] + + @result{} j = [ 1; 2 ] + + @result{} v = [ 3; 3 ] +@end group +@end example +@end deftypefn @node Rearranging Matrices, , Finding Elements and Checking Conditions, Matrix Manipulation @section Rearranging Matrices -@findex fliplr -@findex flipud +@deftypefn {Function File} {} fliplr (@var{x}) +Return a copy of @var{x} with the order of the columns reversed. For +example, + +@example +@group +fliplr ([1, 2; 3, 4]) -The function @code{fliplr} reverses the order of the columns in a -matrix, and @code{flipud} reverses the order of the rows. For example, + @result{} 2 1 + 4 3 +@end group +@end example +@end deftypefn + +@deftypefn {Function File} {} flipud (@var{x}) +Return a copy of @var{x} with the order of the rows reversed. For +example, @example -octave:13> fliplr ([1, 2; 3, 4]) -ans = - - 2 1 - 4 3 - -octave:13> flipud ([1, 2; 3, 4]) -ans = +@group +flipud ([1, 2; 3, 4]) - 3 4 - 1 2 + @result{} 3 4 + 1 2 +@end group @end example - -@findex rot90 +@end deftypefn -The function @code{rot90 (@var{a}, @var{n})} rotates a matrix -counterclockwise in 90-degree increments. The second argument is -optional, and specifies how many 90-degree rotations are to be applied -(the default value is 1). Negative values of @var{n} rotate the matrix -in a clockwise direction. For example, +@deftypefn {Function File} {} rot90 (@var{x}, @var{n}) +Returns a copy of @var{x} with the elements rotated counterclockwise in +90-degree increments. The second argument is optional, and specifies +how many 90-degree rotations are to be applied (the default value is 1). +Negative values of @var{n} rotate the matrix in a clockwise direction. +For example, @example +@group rot90 ([1, 2; 3, 4], -1) -ans = - 3 1 - 4 2 + @result{} 3 1 + 4 2 +@end group @end example @noindent @@ -171,58 +209,62 @@ equivalent statements: @example +@group rot90 ([1, 2; 3, 4], -1) rot90 ([1, 2; 3, 4], 3) rot90 ([1, 2; 3, 4], 7) +@end group @end example - -@findex reshape +@end deftypefn -The function @code{reshape (@var{a}, @var{m}, @var{n})} returns a matrix -with @var{m} rows and @var{n} columns whose elements are taken from the -matrix @var{a}. To decide how to order the elements, Octave pretends -that the elements of a matrix are stored in column-major order (like -Fortran arrays are stored). +@deftypefn {Function File} {} reshape (@var{a}, @var{m}, @var{n}) +Return a matrix with @var{m} rows and @var{n} columns whose elements are +taken from the matrix @var{a}. To decide how to order the elements, +Octave pretends that the elements of a matrix are stored in column-major +order (like Fortran arrays are stored). For example, @example -octave:13> reshape ([1, 2, 3, 4], 2, 2) -ans = +@group +reshape ([1, 2, 3, 4], 2, 2) - 1 3 - 2 4 + @result{} 1 3 + 2 4 +@end group @end example -If the variable @code{do_fortran_indexing} is @code{"true"}, the +If the variable @code{do_fortran_indexing} is nonzero, the @code{reshape} function is equivalent to @example +@group retval = zeros (m, n); retval (:) = a; +@end group @end example @noindent but it is somewhat less cryptic to use @code{reshape} instead of the colon operator. Note that the total number of elements in the original matrix must match the total number of elements in the new matrix. - -@findex sort +@end deftypefn -The function @samp{sort} can be used to arrange the elements of a vector -in increasing order. For matrices, @code{sort} orders the elements in -each column. +@deftypefn {Built-in Function} {[s, i] =} sort (@var{x}) +Returns a copy of @var{x} with the elements elements arranged in +increasing order. For matrices, @code{sort} orders the elements in each +column. For example, @example -octave:13> sort (rand (4)) -ans = +@group +sort ([1, 2; 2, 3; 3, 1]) - 0.065359 0.039391 0.376076 0.384298 - 0.111486 0.140872 0.418035 0.824459 - 0.269991 0.274446 0.421374 0.938918 - 0.580030 0.975784 0.562145 0.954964 + @result{} 1 1 + 2 2 + 3 3 +@end group @end example The @code{sort} function may also be used to produce a matrix @@ -230,64 +272,49 @@ matrix. For example, @example -s = +@group +[s, i] = sort ([1, 2; 2, 3; 3, 1]) - 0.051724 0.485904 0.253614 0.348008 - 0.391608 0.526686 0.536952 0.600317 - 0.733534 0.545522 0.691719 0.636974 - 0.986353 0.976130 0.868598 0.713884 - -i = + @result{} s = 1 1 + 2 2 + 3 3 - 2 4 2 3 - 4 1 3 4 - 1 2 4 1 - 3 3 1 2 + @result{} i = 1 3 + 2 1 + 3 2 +@end group @end example +@end deftypefn -@noindent -These values may be used to recover the original matrix from the sorted -version. For example, - -@example -@end example - -The @code{sort} function does not allow sort keys to be specified, so it -can't be used to order the rows of a matrix according to the values of -the elements in various columns@footnote{For example, to first sort -based on the values in column 1, and then, for any values that are +Since the @code{sort} function does not allow sort keys to be specified, +so it can't be used to order the rows of a matrix according to the +values of the elements in various columns@footnote{For example, to first +sort based on the values in column 1, and then, for any values that are repeated in column 1, sort based on the values found in column 2, etc.} in a single call. Using the second output, however, it is possible to sort all rows based on the values in a given column. Here's an example -that sorts the rows of a matrix based on the values in the third column. +that sorts the rows of a matrix based on the values in the second +column. @example -octave:13> a = rand (4) -a = - - 0.080606 0.453558 0.835597 0.437013 - 0.277233 0.625541 0.447317 0.952203 - 0.569785 0.528797 0.319433 0.747698 - 0.385467 0.124427 0.883673 0.226632 +@group +a = [1, 2; 2, 3; 3, 1]; +[s, i] = sort (a (:, 2)); +a (i, :) -octave:14> [s, i] = sort (a (:, 3)); -octave:15> a (i, :) -ans = - - 0.569785 0.528797 0.319433 0.747698 - 0.277233 0.625541 0.447317 0.952203 - 0.080606 0.453558 0.835597 0.437013 - 0.385467 0.124427 0.883673 0.226632 + @result{} 3 1 + 1 2 + 2 3 +@end group @end example -@findex triu -@findex tril - -The functions @code{triu (@var{a}, @var{k})} and @code{tril (@var{a}, -@var{k})} extract the upper or lower triangular part of the matrix -@var{a}, and set all other elements to zero. The second argument is -optional, and specifies how many diagonals above or below the main -diagonal should also be set to zero. +@deftypefn {Function File} {} tril (@var{a}, @var{k}) +@deftypefnx {Function File} {} triu (@var{a}, @var{k}) +Return a new matrix form by extracting extract the lower (@code{tril}) +or upper (@code{triu}) triangular part of the matrix @var{a}, and +setting all other elements to zero. The second argument is optional, +and specifies how many diagonals above or below the main diagonal should +also be set to zero. The default value of @var{k} is zero, so that @code{triu} and @code{tril} normally include the main diagonal as part of the result @@ -304,32 +331,24 @@ @example @group -octave:13> tril (rand (4), -1) -ans = +tril (ones (3), -1) - 0.00000 0.00000 0.00000 0.00000 - 0.09012 0.00000 0.00000 0.00000 - 0.01215 0.34768 0.00000 0.00000 - 0.00302 0.69518 0.91940 0.00000 + @result{} 0 0 0 + 1 0 0 + 1 1 0 @end group @end example @noindent -forms a lower triangular matrix from a random 4 by 4 matrix, omitting -the main diagonal, and +and @example @group -octave:13> tril (rand (4), 1) -ans = +tril (ones (3), 1) - 0.06170 0.51396 0.00000 0.00000 - 0.96199 0.11986 0.35714 0.00000 - 0.16185 0.61442 0.79343 0.52029 - 0.68016 0.48835 0.63609 0.72113 + @result{} 1 1 0 + 1 1 1 + 1 1 1 @end group @end example - -@noindent -forms a lower triangular matrix from a random 4 by 4 matrix, including -the main diagonal and the first super-diagonal. +@end deftypefn
--- a/doc/interpreter/nonlin.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/nonlin.texi Wed Oct 30 23:00:41 1996 +0000 @@ -7,8 +7,6 @@ @cindex nonlinear equations @cindex equations, nonlinear -@findex fsolve - Octave can solve sets of nonlinear equations of the form @iftex @tex @@ -28,7 +26,21 @@ using the function @code{fsolve}, which is based on the MINPACK subroutine @code{hybrd}. -For example, to solve the set of equations +@deftypefn {Built-in Function} {[@var{x}, @var{info}] =} fsolve (@var{fcn}, @var{x0}) +Given @var{fcn}, the name of a function of the form @code{f (@var{x})} +and an initial starting point @var{x0}, @code{fsolve} solves the set of +equations such that @code{f(@var{x}) == 0}. +@end deftypefn + +@deftypefn {Built-in Function} {} fsolve_options (@var{opt}, @var{val}) +When called with two arguments, this function allows you set options +parameters for the function @code{fsolve}. Given one argument, +@code{fsolve_options} returns the value of the corresponding option. If +no arguments are supplied, the names of all the available options and +their current values are displayed. +@end deftypefn + +Here is a complete example. To solve the set of equations @iftex @tex $$ @@ -93,7 +105,3 @@ @example solution converged to requested tolerance @end example - -@findex fsolve_options -Tolerances and other options for @code{fsolve} may be specified using the -function @code{fsolve_options}.
--- a/doc/interpreter/octave.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/octave.texi Wed Oct 30 23:00:41 1996 +0000 @@ -16,6 +16,7 @@ @c Settings for printing on 8-1/2 by 11 inch paper: @c ----------------------------------------------- +@c @ignore @setchapternewpage odd @iftex @tex @@ -25,16 +26,19 @@ \global\parskip 5pt plus 1pt @end tex @end iftex +@c @end ignore @c Settings for small book format: @c ------------------------------ -@c -@c @smallbook -@c @setchapternewpage odd -@c @finalout -@c @iftex -@c @cropmarks -@c @end iftex + +@ignore +@smallbook +@setchapternewpage odd +@finalout +@iftex +@cropmarks +@end iftex +@end ignore @defindex op @@ -42,7 +46,7 @@ @c This file doesn't include a chapter, so it must not be included @c if you want to run the Emacs function texinfo-multiple-files-update. -@include conf.texi +@c @include conf.texi @settitle Octave @@ -74,14 +78,14 @@ @titlepage @title{Octave} @subtitle{A high-level interactive language for numerical computations} -@subtitle{Edition 1.1 for Octave version @value{VERSION}} -@subtitle{January 1995} +@subtitle{Edition 2 for Octave version @value{VERSION}} +@subtitle{October 1996} @author{John W. Eaton} @page @vskip 0pt plus 1filll Copyright @copyright{} 1996 John W. Eaton. -This is the first edition of the Octave documentation, +This is the second edition of the Octave documentation, and is consistent with version @value{VERSION} of Octave. Permission is granted to make and distribute verbatim copies of @@ -108,7 +112,6 @@ @menu * Preface:: -* Copying:: * Introduction:: A brief introduction to Octave. * Invoking Octave:: Command options supported by Octave. * Expressions:: Expressions. @@ -143,6 +146,7 @@ * Trouble:: If you have trouble installing Octave. * Command Line Editing:: Command history and editing. * Using Info:: +* Copying:: The GNU General Public License. * Concept Index:: An item for each concept. * Variable Index:: An item for each documented variable. * Function Index:: An item for each documented function. @@ -156,8 +160,8 @@ * Running Octave:: * Simple Examples:: +* Comments:: * Executable Octave Programs:: -* Comments:: * Errors:: Invoking Octave @@ -213,6 +217,10 @@ * The try Statement:: * Continuation Lines:: +The @code{for} Statement + +* Looping Over Structure Elements:: + Functions and Script Files * Defining Functions:: @@ -227,9 +235,7 @@ Built-in Variables -* Predefined Constants:: -* User Preferences:: -* Other Built-in Variables:: +* Miscellaneous Built-in Variables * Summary of Preference Variables:: Arithmetic @@ -239,6 +245,7 @@ * Trigonometry:: * Sums and Products:: * Special Functions:: +* Mathematical Constants:: Linear Algebra @@ -273,6 +280,12 @@ * Basic Input and Output:: * C-Style I/O Functions:: +Basic Input and Output + +* Terminal Output:: +* Terminal Input:: +* Simple File I/O:: + C-Style I/O Functions * Opening and Closing Files:: @@ -317,7 +330,8 @@ * Setting Up Octave Mode:: * Using Octave Mode:: -* GIM:: +* Running Octave From Within Emacs:: +* Using the Emacs Info Reader for Octave:: Installing Octave @@ -417,7 +431,6 @@ @end menu @include preface.texi -@include gpl.texi @include intro.texi @include invoke.texi @include expr.texi @@ -475,6 +488,7 @@ @syncodeindex vr in @include gnuinfo.texi +@include gpl.texi @include cp-idx.texi @include vr-idx.texi
--- a/doc/interpreter/optim.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/optim.texi Wed Oct 30 23:00:41 1996 +0000 @@ -22,47 +22,39 @@ @node Quadratic Programming, Nonlinear Programming, Optimization, Optimization @section Quadratic Programming -@ftable @code -@item qpsol - -@example -[x, obj, info, lambda] - = qpsol (x, H, c, lb, ub, lb, A, ub) -@end example +@deftypefn {Built-in Function} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qpsol (@var{x}, @var{H}, @var{c}, @var{lb}, @var{ub}, @var{lb}, @var{A}, @var{ub}) Solve quadratic programs using Gill and Murray's QPSOL. Because QPSOL is not freely redistributable, this function is only available if you have obtained your own copy of QPSOL. @xref{Installation}. -@end ftable +@end deftypefn -@findex qpsol_options -Tolerances and other options for @code{qpsol} may be specified using the -function @code{qpsol_options}. +@deftypefn {Built-in Function} {} qpsol_options (@var{opt}, @var{val}) +When called with two arguments, this function allows you set options +parameters for the function @code{qpsol}. Given one argument, +@code{qpsol_options} returns the value of the corresponding option. If +no arguments are supplied, the names of all the available options and +their current values are displayed. +@end deftypefn @node Nonlinear Programming, Linear Least Squares, Quadratic Programming, Optimization @section Nonlinear Programming @ignore -@ftable @code -@item fsqp +@deftypefn {Built-in Function} {} fsqp () +@end deftypefn -@example -fsqp () -@end example - -@findex fsqp_options -Tolerances and other options for @code{fsqp} may be specified using the -function @code{fsqp_options}. +@deftypefn {Built-in Function} {} fsqp_options (@var{opt}, @var{val}) +When called with two arguments, this function allows you set options +parameters for the function @code{fsqp}. Given one argument, +@code{fsqp_options} returns the value of the corresponding option. If +no arguments are supplied, the names of all the available options and +their current values are displayed. +@end deftypefn Sorry, this hasn't been implemented yet. @end ignore -@ftable @code -@item npsol - -@example -[x, obj, info, lambda] - = npsol (x, 'phi', lb, ub, lb, A, ub, lb, 'g', ub) -@end example +@deftypefn {Built-in Function} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} npsol (@var{x}, @var{phi}, @var{lb}, @var{ub}, @var{lb}, @var{A}, @var{ub}, @var{lb}, @var{g}, @var{ub}) Solve nonlinear programs using Gill and Murray's NPSOL. Because NPSOL is not freely redistributable, this function is only available if you have obtained your own copy of NPSOL. @xref{Installation}. @@ -76,17 +68,20 @@ @noindent where x is a vector and y is a scalar. -@end ftable +@end deftypefn -@findex npsol_options -Tolerances and other options for @code{npsol} may be specified using the -function @code{npsol_options}. +@deftypefn {Built-in Function} {} npsol_options (@var{opt}, @var{val}) +When called with two arguments, this function allows you set options +parameters for the function @code{npsol}. Given one argument, +@code{npsol_options} returns the value of the corresponding option. If +no arguments are supplied, the names of all the available options and +their current values are displayed. +@end deftypefn @node Linear Least Squares, , Nonlinear Programming, Optimization @section Linear Least Squares -@ftable @code -@item gls (@var{Y}, @var{X}, @var{O}) +@deftypefn {Function File} {} gls (@var{Y}, @var{X}, @var{O}) Generalized least squares (GLS) estimation for the multivariate model @example @@ -109,8 +104,9 @@ Returns BETA, v, and, R, where BETA is the GLS estimator for B, v is the GLS estimator for s^2, and R = Y - X*BETA is the matrix of GLS residuals. +@end deftypefn -@item ols (@var{Y}, @var{X}) +@deftypefn {Function File} {} ols (@var{Y}, @var{X}) Ordinary Least Squares (OLS) estimation for the multivariate model @example @@ -145,4 +141,4 @@ @end example and R = Y - X*BETA is the matrix of OLS residuals. -@end ftable +@end deftypefn
--- a/doc/interpreter/plot.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/plot.texi Wed Oct 30 23:00:41 1996 +0000 @@ -5,9 +5,6 @@ @node Plotting, Image Processing, Statistics, Top @chapter Plotting -@findex gplot -@findex gsplot - All of Octave's plotting functions use @code{gnuplot} to handle the actual graphics. There are two low-level functions, @code{gplot} and @code{gsplot}, that behave almost exactly like the corresponding @@ -26,16 +23,11 @@ @node Two-Dimensional Plotting, Three-Dimensional Plotting, Plotting, Plotting @section Two-Dimensional Plotting -The syntax for Octave's two-dimensional plotting function, -@code{gplot}, is +@deffn {Command} gplot @var{ranges} @var{expression} @var{using} @var{title} @var{style} +Generate a 2-dimensional plot. -@example -gplot @var{ranges} @var{expression} @var{using} @var{title} @var{style} -@end example - -@noindent -where the @var{ranges}, @var{using}, @var{title}, and @var{style} -arguments are optional, and the @var{using}, @var{title} and @var{style} +The @var{ranges}, @var{using}, @var{title}, and @var{style} arguments +are optional, and the @var{using}, @var{title} and @var{style} qualifiers may appear in any order after the expression. You may plot multiple expressions with a single command by separating them with commas. Each expression may have its own set of qualifiers. @@ -105,11 +97,11 @@ In this example, the ranges have been explicitly specified to be a bit larger than the actual range of the data so that the curves do not touch the border of the plot. +@end deffn -@findex set -@findex show -@findex replot - +@deffn {Command} set options +@deffnx {Command} show options +@deffnx {Command} replot options In addition to the basic plotting commands, the whole range of @code{set} and @code{show} commands from @code{gnuplot} are available, as is @code{replot}. @@ -142,13 +134,14 @@ lines with a replot command, gnuplot always redraws the entire plot, and you probably don't want to have a completely new plot generated every time something as minor as an axis label changes. - -@vindex automatic_replot +@end deffn -Since this may not matter as much on faster terminals, you can tell -Octave to redisplay the plot each time anything about it changes by -setting the value of the builtin variable @code{automatic_replot} to the -value @code{"true"}. +@defvr {Built-in Variable} automatic_replot +You can tell Octave to redisplay the plot each time anything about it +changes by setting the value of the builtin variable +@code{automatic_replot} to a nonzero value. Since this is fairly +inefficient, the default value is 0. +@end defvr Note that NaN values in the plot data are automatically omitted, and Inf values are converted to a very large value before calling gnuplot. @@ -164,8 +157,7 @@ @cindex plotting @cindex graphics -@ftable @code -@item plot (@var{args}) +@deftypefn {Function File} {} plot (@var{args}) This function produces two-dimensional plots. Many different combinations of arguments are possible. The simplest form is @@ -300,8 +292,9 @@ This command will plot the data in @var{b} will be plotted with points displayed as @code{*}. +@end deftypefn -@item hold +@deftypefn {Function File} {} hold @var{args} Tell Octave to `hold' the current data on the plot when executing subsequent plotting commands. This allows you to execute a series of plot commands and have all the lines end up on the same figure. The @@ -315,49 +308,50 @@ @noindent turns the hold state on. An argument of @code{off} turns the hold state off, and @code{hold} with no arguments toggles the current hold state. +@end deftypefn -@item ishold +@deftypefn {Function File} {} ishold Returns 1 if the next line will be added to the current plot, or 0 if the plot device will be cleared before drawing the next line. +@end deftypefn -@item loglog (@var{args}) +@deftypefn {Function File} {} loglog (@var{args}) Make a two-dimensional plot using log scales for both axes. See the description of @code{plot} above for a description of the arguments that @code{loglog} will accept. +@end deftypefn -@item semilogx (@var{args}) +@deftypefn {Function File} {} semilogx (@var{args}) Make a two-dimensional plot using a log scale for the @var{x} axis. See the description of @code{plot} above for a description of the arguments that @code{semilogx} will accept. +@end deftypefn -@item semilogy (@var{args}) +@deftypefn {Function File} {} semilogy (@var{args}) Make a two-dimensional plot using a log scale for the @var{y} axis. See the description of @code{plot} above for a description of the arguments that @code{semilogy} will accept. +@end deftypefn -@item contour (@var{z}, @var{n}, @var{x}, @var{y}) +@deftypefn {Function File} {} contour (@var{z}, @var{n}, @var{x}, @var{y}) Make a contour plot of the three-dimensional surface described by @var{z}. Someone needs to improve @code{gnuplot}'s contour routines before this will be very useful. +@end deftypefn -@item polar (@var{theta}, @var{rho}) +@deftypefn {Function File} {} polar (@var{theta}, @var{rho}) Make a two-dimensional plot given polar the coordinates @var{theta} and @var{rho}. -@end ftable +@end deftypefn @node Three-Dimensional Plotting, Miscellaneous Plotting Functions, Two-Dimensional Plotting, Plotting @section Three-Dimensional Plotting -The syntax for Octave's three-dimensional plotting function, -@code{gsplot}, is +@deffn {Command} gsplot @var{ranges} @var{expression} @var{using} @var{title} @var{style} +Generate a 3-dimensional plot. -@example -gsplot @var{ranges} @var{expression} @var{using} @var{title} @var{style} -@end example - -@noindent -where the @var{ranges}, @var{using}, @var{title}, and @var{style} -arguments are optional, and the @var{using}, @var{title} and @var{style} +The @var{ranges}, @var{using}, @var{title}, and @var{style} arguments +are optional, and the @var{using}, @var{title} and @var{style} qualifiers may appear in any order after the expression. You may plot multiple expressions with a single command by separating them with commas. Each expression may have its own set of qualifiers. @@ -423,28 +417,49 @@ @noindent but not @code{rand (5, 30)}. +@end deffn The @sc{Matlab}-style three-dimensional plotting commands are: -@ftable @code -@item mesh (@var{x}, @var{y}, @var{z}) +@deftypefn {Function File} {} mesh (@var{x}, @var{y}, @var{z}) Plot a mesh given matrices @code{x}, and @var{y} from @code{meshdom} and a matrix @var{z} corresponding to the @var{x} and @var{y} coordinates of the mesh. +@end deftypefn -@item meshdom (@var{x}, @var{y}) +@deftypefn {Function File} {} meshdom (@var{x}, @var{y}) Given vectors of @var{x} and @var{y} coordinates, return two matrices corresponding to the @var{x} and @var{y} coordinates of the mesh. See the file @file{sombrero.m} for an example of using @code{mesh} and @code{meshdom}. -@end ftable +@end deftypefn + +@defvr {Built-in Variable} gnuplot_binary +The name of the program invoked by the plot command. The default value +is @code{"gnuplot"}. @xref{Installation}. +@end defvr + +@defvr {Built-in Variable} gnuplot_has_frames +If the value of this variable is nonzero, Octave assumes that your copy +of gnuplot has support for multiple frames that is included in recent +3.6beta releases. It's initial value is determined by configure, but it +can be changed in your startup script or at the command line in case +configure got it wrong, or if you upgrade your gnuplot installation. +@end defvr + +@defvr {Built-in Variable} gnuplot_has_multiplot +If the value of this variable is nonzero, Octave assumes that your copy +of gnuplot has the multiplot support that is included in recent +3.6beta releases. It's initial value is determined by configure, but it +can be changed in your startup script or at the command line in case +configure got it wrong, or if you upgrade your gnuplot installation. +@end defvr @node Miscellaneous Plotting Functions, , Three-Dimensional Plotting, Plotting @section Miscellaneous Plotting Functions -@ftable @code -@item bar (@var{x}, @var{y}) +@deftypefn {Function File} {} bar (@var{x}, @var{y}) Given two vectors of x-y data, @code{bar} produces a bar graph. If only one argument is given, it is taken as a vector of y-values @@ -467,11 +482,13 @@ @noindent are equivalent. +@end deftypefn -@item grid +@deftypefn {Function File} {} grid For two-dimensional plotting, force the display of a grid on the plot. +@end deftypefn -@item stairs (@var{x}, @var{y}) +@deftypefn {Function File} {} stairs (@var{x}, @var{y}) Given two vectors of x-y data, bar produces a `stairstep' plot. If only one argument is given, it is taken as a vector of y-values @@ -494,23 +511,27 @@ @noindent are equivalent. +@end deftypefn -@item title (@var{string}) +@deftypefn {Function File} {} title (@var{string}) Specify a title for the plot. If you already have a plot displayed, use the command @code{replot} to redisplay it with the new title. +@end deftypefn -@item xlabel (@var{string}) -@itemx ylabel (@var{string}) +@deftypefn {Function File} {} xlabel (@var{string}) +@deftypefnx {Function File} {} ylabel (@var{string}) Specify x and y axis labels for the plot. If you already have a plot displayed, use the command @code{replot} to redisplay it with the new labels. +@end deftypefn -@item sombrero (@var{n}) +@deftypefn {Function File} {} sombrero (@var{n}) Display a classic three-dimensional mesh plot. The parameter @var{n} allows you to increase the resolution. +@end deftypefn -@item clearplot -@itemx clg +@deftypefn {Function File} {} clearplot +@deftypefnx {Function File} {} clg Clear the plot window and any titles or axis labels. The name @code{clg} is aliased to @code{clearplot} for compatibility with @sc{Matlab}. @@ -518,12 +539,14 @@ clear} are equivalent to @samp{clearplot}. (Previously, commands like @samp{gplot clear} would evaluate @samp{clear} as an ordinary expression and clear all the visible variables.) +@end deftypefn -@item closeplot +@deftypefn {Function File} {} closeplot Close stream to the @code{gnuplot} subprocess. If you are using X11, this will close the plot window. +@end deftypefn -@item purge_tmp_files +@deftypefn {Function File} {} purge_tmp_files Delete the temporary files created by the plotting commands. Octave creates temporary data files for @code{gnuplot} and then sends @@ -533,8 +556,9 @@ A future version of Octave will eliminate the need to use temporary files to hold the plot data. +@end deftypefn -@item axis (@var{limits}) +@deftypefn {Function File} {} axis (@var{limits}) Sets the axis limits for plots. The argument @var{limits} should be a 2, 4, or 6 element vector. The @@ -547,9 +571,10 @@ If your plot is already drawn, then you need to use @code{replot} before the new axis limits will take effect. You can get this to happen automatically by setting the built-in variable @code{automatic_replot} -to @code{"true"}. @xref{User Preferences}. +to a nonzero value. +@end deftypefn -@item hist (@var{y}, @var{x}) +@deftypefn {Function File} {} hist (@var{y}, @var{x}) Produce histogram counts or plots. With one vector input argument, plot a histogram of the values with @@ -566,4 +591,4 @@ With two output arguments, produce the values @var{nn} and @var{xx} such that @code{bar (@var{xx}, @var{nn})} will plot the histogram. -@end ftable +@end deftypefn
--- a/doc/interpreter/poly.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/poly.texi Wed Oct 30 23:00:41 1996 +0000 @@ -6,24 +6,45 @@ @chapter Polynomial Manipulations In Octave, a polynomial is represented by its coefficients (arranged -in descending order). For example, a vector @var{c} of length @var{n+1} -corresponds to the following @var{n}-th order polynomial +in descending order). For example, a vector +@iftex +@end iftex +@ifinfo + $c$ +@end ifinfo +of length +@iftex +@tex + $N+1$ +@end tex +@ifinfo + @var{N+1} +@end ifinfo + corresponds to the following +@iftex +@tex + $N^{th}$ +@end tex +@end iftex +@ifinfo + @var{N}-th +@end ifinfo + order polynomial @iftex @tex $$ - p (x) = c_1 x^n + ... + c_n x + c_{n+1}. + p (x) = c_1 x^N + ... + c_N x + c_{N+1}. $$ @end tex @end iftex @ifinfo @example -p(x) = c(1) x^n + ... + c(n) x + c(n+1). +p(x) = @var{c}(1) x^@var{N} + ... + @var{c}(@var{N}) x + @var{c}(@var{N}+1). @end example @end ifinfo -@ftable @code -@item compan (@var{c}) +@deftypefn {Function File} {} compan (@var{c}) Compute the companion matrix corresponding to polynomial coefficient vector @var{c}. @@ -32,10 +53,10 @@ @tex $$ A = \left[\matrix{ - -c_2/c_1 & -c_3/c_1 & \cdots & -c_n/c_1 & -c_{n+1}/c_1\cr + -c_2/c_1 & -c_3/c_1 & \cdots & -c_N/c_1 & -c_{N+1}/c_1\cr 1 & 0 & \cdots & 0 & 0 \cr 0 & 1 & \cdots & 0 & 0 \cr - \vdots & & \ddots & \vdots & \vdots \cr + \vdots & \vdots & \ddots & \vdots & \vdots \cr 0 & 0 & \cdots & 1 & 0}\right]. $$ @end tex @@ -44,7 +65,7 @@ @smallexample _ _ - | -c(2)/c(1) -c(3)/c(1) ... -c(n)/c(1) -c(n+1)/c(1) | + | -c(2)/c(1) -c(3)/c(1) ... -c(N)/c(1) -c(N+1)/c(1) | | 1 0 ... 0 0 | | 0 1 ... 0 0 | A = | . . . . . | @@ -56,16 +77,18 @@ The eigenvalues of the companion matrix are equal to the roots of the polynomial. +@end deftypefn -@item conv (@var{a}, @var{b}) +@deftypefn {Function File} {} conv (@var{a}, @var{b}) Convolve two vectors. @code{y = conv (a, b)} returns a vector of length equal to @code{length (a) + length (b) - 1}. If @var{a} and @var{b} are polynomial coefficient vectors, @code{conv} returns the coefficients of the product polynomial. +@end deftypefn -@item deconv (@var{y}, @var{a}) +@deftypefn {Function File} {} deconv (@var{y}, @var{a}) Deconvolve two vectors. @code{[b, r] = deconv (y, a)} solves for @var{b} and @var{r} such that @@ -74,29 +97,34 @@ If @var{y} and @var{a} are polynomial coefficient vectors, @var{b} will contain the coefficients of the polynomial quotient and @var{r} will be a remander polynomial of lowest order. +@end deftypefn -@item poly (@var{a}) -If @var{a} is a square @var{n}-by-@var{n} matrix, @code{poly (@var{a})} -is the row vector of the coefficients of @code{det (z * eye (n) - a)}, +@deftypefn {Function File} {} poly (@var{a}) +If @var{a} is a square @var{N}-by-@var{N} matrix, @code{poly (@var{a})} +is the row vector of the coefficients of @code{det (z * eye (N) - a)}, the characteristic polynomial of @var{a}. If @var{x} is a vector, @code{poly (@var{x})} is a vector of coefficients of the polynomial whose roots are the elements of @var{x}. +@end deftypefn -@item polyderiv (@var{c}) +@deftypefn {Function File} {} polyderiv (@var{c}) Returns the coefficients of the derivative of the polynomial whose coefficients are given by vector @var{c}. +@end deftypefn -@item polyinteg (@var{c}) +@deftypefn {Function File} {} polyinteg (@var{c}) Returns the coefficients of the integral the polynomial whose coefficients are represented by the vector @var{c}. The constant of integration is set to zero. +@end deftypefn -@item polyreduce (@var{c}) +@deftypefn {Function File} {} polyreduce (@var{c}) Reduces a polynomial coefficient vector to a minimum number of terms by stripping off any leading zeros. +@end deftypefn -@item polyval (@var{c}, @var{x}) +@deftypefn {Function File} {} polyval (@var{c}, @var{x}) Evaluate a polynomial. @code{polyval (@var{c}, @var{x})} will evaluate the polynomial at the @@ -104,8 +132,9 @@ If @var{x} is a vector or matrix, the polynomial is evaluated at each of the elements of @var{x}. +@end deftypefn -@item polyvalm (@var{c}, @var{x}) +@deftypefn {Function File} {} polyvalm (@var{c}, @var{x}) Evaluate a polynomial in the matrix sense. @code{polyvalm (@var{c}, @var{x})} will evaluate the polynomial in the @@ -113,8 +142,9 @@ element multiplication as is used in polyval. The argument @var{x} must be a square matrix. +@end deftypefn -@item residue (@var{b}, @var{a}, @var{tol}) +@deftypefn {Function File} {} residue (@var{b}, @var{a}, @var{tol}) If @var{b} and @var{a} are vectors of polynomial coefficients, then residue calculates the partial fraction expansion corresponding to the ratio of the two polynomials. @@ -139,7 +169,7 @@ @tex $$ {P(s)\over Q(s)} = \sum_{m=1}^M {r_m\over (s-p_m)^e_m} - + \sum_{n=1}^N k_n s^{N-n}. + + \sum_{i=1}^N k_i s^{N-i}. $$ @end tex @end iftex @@ -147,8 +177,8 @@ @example P(s) M r(m) N - ---- = SUM ------------- + SUM k(n)*s^(N-n) - Q(s) m=1 (s-p(m))^e(m) n=1 + ---- = SUM ------------- + SUM k(i)*s^(N-i) + Q(s) m=1 (s-p(m))^e(m) i=1 @end example @end ifinfo @@ -204,22 +234,23 @@ s^3 - 5s^2 + 8s - 4 (s-2) (s-2)^2 (s-1) @end example @end ifinfo +@end deftypefn -@item roots (@var{v}) +@deftypefn {Function File} {} roots (@var{v}) -For a vector @var{v} with @var{n} components, return +For a vector @var{v} with @var{N} components, return the roots of the polynomial @iftex @tex $$ -v_1 z^{n-1} + \cdots + v_{n-1} z + v_n. +v_1 z^{N-1} + \cdots + v_{N-1} z + v_N. $$ @end tex @end iftex @ifinfo @example -v(1) * z^(n-1) + ... + v(n-1) * z + v(n). +v(1) * z^(N-1) + ... + v(N-1) * z + v(N). @end example @end ifinfo -@end ftable +@end deftypefn
--- a/doc/interpreter/preface.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/preface.texi Wed Oct 30 23:00:41 1996 +0000 @@ -2,7 +2,7 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Preface, Copying, Top, Top +@node Preface, Introduction, Top, Top @unnumbered Preface @cindex acknowledgements @cindex contributors @@ -81,6 +81,10 @@ documents it. @item +Klaus Gebhardt <gebhardt@@crunch.ikp.physik.th-darmstadt.de> ported +Octave to OS/2. + +@item A. Scottedward Hodel (scotte@@eng.auburn.edu) contributed a number of functions including @code{expm}, @code{qzval}, @code{qzhess}, @code{syl}, @code{lyap}, and @code{balance}. @@ -94,12 +98,16 @@ Octave code and provided its documentation, and has helped tremendously with testing. He has also been a constant source of new ideas for improving Octave. - + @item Phil Johnson (johnsonp@@nicco.sscnet.ucla.edu) has helped to make Linux releases available. @item +Michel Juillard <juillard@@msh-paris.fr> ported Octave to DOS and OS/2 +systems. + +@item Friedrich Leisch (leisch@@ci.tuwien.ac.at) provided the @code{mahalanobis} function. @@ -182,7 +190,8 @@ Portions of this document have been adapted from the @code{gawk}, @code{readline}, @code{gcc}, and C library manuals, published by the Free -Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +Software Foundation, 59 Temple Place---Suite 330, Boston, MA +02111--1307, USA. This project would not have been possible without the GNU software used in and used to produce Octave.
--- a/doc/interpreter/program.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/program.texi Wed Oct 30 23:00:41 1996 +0000 @@ -13,18 +13,17 @@ @node Evaluating Strings as Commands, Miscellaneous Utilities, Programming Utilities, Programming Utilities @section Evaluating Strings as Commands -@findex eval - It is often useful to evaluate a string as if it were an Octave program, or use a string as the name of a function to call. These functions are necessary in order to evaluate commands that are not known until run time, or to write functions that will need to call user-supplied functions. -The function @code{eval (@var{command})} parses @var{command} and -evaluates it as if it were an Octave program, returning the last value -computed. The @var{command} is evaluated in the current context, so any -results remain available after @code{eval} returns. For example, +@deftypefn {Built-in Function} {} eval (@var{command}) +Parse the string @var{command} and evaluate it as if it were an Octave +program, returning the last value computed. The @var{command} is +evaluated in the current context, so any results remain available after +@code{eval} returns. For example, @example octave:13> a @@ -49,12 +48,11 @@ octave:15> a a = 13 @end example - -@findex feval +@end deftypefn -The function @code{feval (@var{name}, ...)} can be used to evaluate -the function named @var{name}. Any arguments after the first are passed -on to the named function. For example, +@deftypefn {Built-in Function} {} feval (@var{name}, @dots{}) +Evaluate the function named @var{name}. Any arguments after the first +are passed on to the named function. For example, @example octave:12> feval ("acos", -1) @@ -70,13 +68,12 @@ special kind of variable that can be used to hold the name of a function (like @code{EXTERNAL} in Fortran). Instead, you must refer to functions by name, and use @code{feval} to call them. - -For example, here is a -simple-minded function for finding the root of a function of one -variable: +@end deftypefn @cindex Fordyce, A. P. @findex newtroot +Here is a simple-minded function using @code{feval} that finds the root +of a user-supplied function of one variable. @example @group @@ -121,18 +118,20 @@ expression, find out whether a variable exists, print error messages, or delete variable names from the symbol table. -@ftable @code -@item columns (@var{a}) +@deftypefn {Function File} {} columns (@var{a}) Return the number of columns of @var{a}. +@end deftypefn -@item rows (@var{a}) +@deftypefn {Function File} {} rows (@var{a}) Return the number of rows of @var{a}. +@end deftypefn -@item length (@var{a}) +@deftypefn {Function File} {} length (@var{a}) Return the number of rows of @var{a} or the number of columns of @var{a}, whichever is larger. +@end deftypefn -@item size (@var{a} [, @var{n}]) +@deftypefn {Function File} {} size (@var{a}, @var{n}) Return the number rows and columns of @var{a}. With one input argument and one output argument, the result is returned @@ -164,36 +163,45 @@ @noindent returns the number of columns in the given matrix. +@end deftypefn -@item is_global (@var{a}) +@deftypefn {Built-in Function} {} is_global (@var{a}) Return 1 if @var{a} is globally visible. Otherwise, return 0. +@end deftypefn -@item is_matrix (@var{a}) +@deftypefn {Function File} {} is_matrix (@var{a}) Return 1 if @var{a} is a matrix. Otherwise, return 0. +@end deftypefn -@item is_vector (@var{a}) +@deftypefn {Function File} {} is_vector (@var{a}) Return 1 if @var{a} is a vector. Otherwise, return 0. +@end deftypefn -@item is_scalar (@var{a}) +@deftypefn {Function File} {} is_scalar (@var{a}) Return 1 if @var{a} is a scalar. Otherwise, return 0. +@end deftypefn -@item is_square (@var{x}) +@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 -@item is_symmetric (@var{x}, @var{tol}) +@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 -@item isstr (@var{a}) +@deftypefn {Built-in Function} {} isstr (@var{a}) Return 1 if @var{a} is a string. Otherwise, return 0. +@end deftypefn -@item isempty (@var{a}) +@deftypefn {Function File} {} isempty (@var{a}) Return 1 if @var{a} is an empty matrix (either the number of rows, or the number of columns, or both are zero). Otherwise, return 0. +@end deftypefn -@item clear @var{pattern} ... +@deffn {Command} clear pattern @dots{} Delete the names matching the given patterns from the symbol table. The pattern may contain the following special characters: @table @code @@ -231,8 +239,10 @@ clear the function definition. This command may not be used within a function body. +@end deffn -@item who @var{options} @var{pattern} ... +@deffn {Command} who options pattern @dots{} +@deffnx {Command} whos options pattern @dots{} List currently defined symbols matching the given patterns. The following are valid options. They may be shortened to one character but may not be combined. @@ -264,16 +274,16 @@ are listed. By default, only user defined functions and variables visible in the local scope are displayed. -@findex whos +The command @code{whos} is equivalent to @code{who -long}. +@end deffn -The command @code{whos} is equivalent to @code{who -long}. - -@item exist (@var{name}) +@deftypefn {Built-in Function} {} exist (@var{name}) Return 1 if the name exists as a variable, and 2 if the name (after appending @samp{.m}) is a function file in the path. Otherwise, return 0. +@end deftypefn -@item error (@var{msg}) +@deftypefn {Built-in Function} {} error (@var{msg}) Print the message @var{msg}, prefixed by the string @samp{error: }, and set Octave's internal error state such that control will return to the top level without evaluating any more commands. This is useful for @@ -310,11 +320,22 @@ f () error: nargin != 1 @end example +@end deftypefn -@item warning (@var{msg}) +@defvr {Built-in Variable} error_text +@end defvr + +@defvr {Built-in Variable} beep_on_error +If the value of @code{beep_on_error} is nonzero, Octave will try +to ring your terminal's bell before printing an error message. The +default value is 0. +@end defvr + +@deftypefn {Built-in Function} {} warning (@var{msg}) Print the message @var{msg} prefixed by the string @samp{warning: }. +@end deftypefn -@item usage (@var{msg}) +@deftypefn {Built-in Function} {} usage (@var{msg}) Print the message @var{msg}, prefixed by the string @samp{usage: }, and set Octave's internal error state such that control will return to the top level without evaluating any more commands. This is useful for @@ -322,25 +343,29 @@ After @code{usage} is evaluated, Octave will print a traceback of all the function calls leading to the usage message. +@end deftypefn -@item perror (@var{name}, @var{num}) +@deftypefn {Function File} {} perror (@var{name}, @var{num}) Print the error message for function @var{name} corresponding to the error number @var{num}. This function is intended to be used to print useful error messages for those functions that return numeric error codes. +@end deftypefn -@item menu (@var{title}, @var{opt1}, @dots{}) +@deftypefn {Function File} {} menu (@var{title}, @var{opt1}, @dots{}) Print a title string followed by a series of options. Each option will be printed along with a number. The return value is the number of the option selected by the user. This function is useful for interactive programs. There is no limit to the number of options that may be passed in, but it may be confusing to present more than will fit easily on one screen. +@end deftypefn -@item document @var{symbol} @var{text} +@deftypefn {Built-in Function} {} document (@var{symbol}, @var{text}) Set the documentation string for @var{symbol} to @var{text}. +@end deftypefn -@item file_in_path (@var{path}, @var{file}) +@deftypefn {Built-in Function} {} file_in_path (@var{path}, @var{file}) Return the absolute name name of @var{file} if it can be found in @var{path}. The value of @var{path} should be a colon-separated list of directories in the format described for the built-in variable @@ -353,24 +378,36 @@ octave:13> file_in_path (LOADPATH, "nargchk.m") ans = /usr/local/lib/octave/1.1.0/m/general/nargchk.m @end example +@end deftypefn -@item nargchk (@var{nargin_min}, @var{nargin_max}, @var{n}) +@deftypefn {Built-in Function} completion_matches (@var{hint}) +Generate possible completions given @var{hint}. + +This function is provided for the benefit of programs like Emacs which +might be controlling Octave and handling user input. The current +command number is not incremented when this function is called. This is +a feature, not a bug. +@end deftypefn + +@deftypefn {Function File} {} nargchk (@var{nargin_min}, @var{nargin_max}, @var{n}) If @var{n} is in the range @var{nargin_min} through @var{nargin_max} inclusive, return the empty matrix. Otherwise, return a message indicating whether @var{n} is too large or too small. This is useful for checking to see that the number of arguments supplied to a function is within an acceptable range. +@end deftypefn -@item octave_tmp_file_name +@deftypefn {Built-in Function} {} octave_tmp_file_name () Return a unique temporary file name. Since the named file is not opened, by @code{octave_tmp_file_name}, it is possible (though relatively unlikely) that it will not be available by the time your program attempts to open it. +@end deftypefn -@item type @var{name} ... -@item type [-q] @var{name} ... +@deffn {Command} type name @dots{} +@deffnx {Command} type [-q] name @dots{} Display the definition of each @var{name} that refers to a function. Normally also displays if each @var{name} is user-defined or builtin; @@ -383,8 +420,14 @@ Comments are not displayed because Octave's parser currently discards them as it converts the text of a function file to its internal representation. This problem may be fixed in a future release. +@end deffn -@item which @var{name} ... +@deffn {Command} which name @dots{} Display the type of each @var{name}. If @var{name} is defined from a function file, the full name of the file is also displayed. -@end ftable +@end deffn + +@deftypefn {Built-in Function} octave_config_info () +Return a structure containing configuration and installation +information. +@end deftypefn
--- a/doc/interpreter/quad.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/quad.texi Wed Oct 30 23:00:41 1996 +0000 @@ -13,31 +13,22 @@ @node Functions of one Variable, Orthogonal Collocation, Quadrature, Quadrature @section Functions of one Variable -@ftable @code -@item quad - -@example -[v, ier, nfun] = quad ("f", a, b) -[v, ier, nfun] = quad ("f", a, b, tol) -[v, ier, nfun] = quad ("f", a, b, tol, sing) -@end example - +@deftypefn {Built-in Function} {[@var{v}, @var{ier}, @var{nfun}] =} quad (@var{f}, @var{a}, @var{b}, @var{tol}, @var{sing}) Integrate a nonlinear function of one variable using Quadpack. - -Where the first argument is the name of the function to call to -compute the value of the integrand. It must have the form +The first argument is the name of the function to call to compute the +value of the integrand. It must have the form @example y = f (x) @end example @noindent -where y and x are scalars. +where @var{y} and @var{x} are scalars. The second and third arguments are limits of integration. Either or both may be infinite. -The optional argument tol is a vector that specifies the desired +The optional argument @var{tol} is a vector that specifies the desired accuracy of the result. The first element of the vector is the desired absolute tolerance, and the second element is the desired relative tolerance. To choose a relative test only, set the absolute @@ -45,28 +36,23 @@ tolerance to zero. The optional argument @var{sing} is a vector of values at which the -integrand is singular. +integrand is known to be singular. +@end deftypefn -@findex quad_options -Tolerances and other options for @code{quad} may be specified using the -function @code{quad_options}. - -@end ftable +@deftypefn {Built-in Function} {} quad_options (@var{opt}, @var{val}) +When called with two arguments, this function allows you set options +parameters for the function @code{quad}. Given one argument, +@code{quad_options} returns the value of the corresponding option. If +no arguments are supplied, the names of all the available options and +their current values are displayed. +@end deftypefn @node Orthogonal Collocation, , Functions of one Variable, Quadrature @section Orthogonal Collocation -@ftable @code -@item colloc - -@example -[r, A, B, q] = colloc (n) -[r, A, B, q] = colloc (n, "left") -[r, A, B, q] = colloc (n, "left", "right") -@end example - +@deftypefn {Built-in Function} {[@var{r}, @var{A}, @var{B}, @var{q}] =} colloc (@var{n}, "left", "right") Compute derivative and integral weight matrices for orthogonal collocation using the subroutines given in J. Villadsen and M. L. Michelsen, @cite{Solution of Differential Equation Models by Polynomial Approximation}. -@end ftable +@end deftypefn
--- a/doc/interpreter/set.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/set.texi Wed Oct 30 23:00:41 1996 +0000 @@ -8,20 +8,51 @@ Octave has a limited set of functions for managing sets of data, where a set is defined as a collection unique elements. -@findex create_set +@deftypefn {Function File} {} create_set (@var{x}) Given a matrix or vector of values, the function @code{create_set} returns a row vector containing unique values, sorted in ascending -order. For example, @samp{create_set ([1, 2; 3, 4; 4, 2])} returns -the vector @samp{[1, 2, 3, 4]}. +order. For example, + +@example +create_set ([ 1, 2; 3, 4; 4, 2 ]) +@end example + +@noindent +returns the vector + +@example +[ 1, 2, 3, 4 ] +@end example +@end deftypefn + +@deftypefn {Function File} {} union (@var{x}, @var{y}) +Return the set of elements that are in either of the sets @var{x} and +@var{y}. For example, + +@example +union ([ 1, 2, 3 ], [ 2, 3, 5 ]) +@end example -@findex union -@findex intersection -The functions @code{union} and @code{intersection} take two sets as -arguments and return the union and interection, respectively. For -example, @samp{union ([1, 2, 3], [2, 3, 5])} returns the vector -@samp{[1, 2, 5]}. +@noindent +returns the vector + +@example +[ 1, 2, 5 ] +@end example +@end deftypefn + +@deftypefn {Function File} {} intersection (@var{x}, @var{y}) +Return the set of elements that are in both sets @var{x} and @var{y}. +@end deftypefn -@findex complement -The function @code{complement (@var{a}, @var{b})} returns the elements -of set @var{b} that are not in set @var{a}. For example, -@samp{complement ([1, 2, 3], [2, 3, 5])} returns the value @samp{5}. +@deftypefn {Function File} {} complement (@var{x}, @var{y}) +Returns the elements of set @var{y} that are not in set @var{x}. For +example, + +@example +complement ([ 1, 2, 3 ], [ 2, 3, 5 ]) +@end example + +@noindent +returns the value @samp{5}. +@end deftypefn
--- a/doc/interpreter/signal.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/signal.texi Wed Oct 30 23:00:41 1996 +0000 @@ -9,8 +9,7 @@ functions. If you would like to help improve Octave in this area, please contact @code{bug-octave@@bevo.che.wisc.edu}. -@ftable @code -@item fft (@var{a} [, @var{n}]) +@deftypefn {Function} {} fft (@var{a} [, @var{n}]) Compute the FFT of @var{a} using subroutines from FFTPACK. If @var{a} is a matrix, @code{fft} computes the FFT for each column of @var{a}. @@ -19,16 +18,39 @@ matrix, @var{n} specifies the number of rows of @var{a} to use. If @var{n} is larger than the size of @var{a}, @var{a} is resized and padded with zeros. +@end deftypefn -@item fft2 (@var{a} [, @var{n} [, @var{m}]]) +@deftypefn {Built-in Function} {} ifft (@var{a} [, @var{n}]) +Compute the inverse FFT of @var{a} using subroutines from FFTPACK. If +@var{a} is a matrix, @code{fft} computes the inverse FFT for each column +of @var{a}. + +If called with two arguments, @var{n} is expected to be an integer +specifying the number of elements of @var{a} to use. If @var{a} is a +matrix, @var{n} specifies the number of rows of @var{a} to use. If +@var{n} is larger than the size of @var{a}, @var{a} is resized and +padded with zeros. +@end deftypefn + +@deftypefn {Built-in Function} {} fft2 (@var{a} [, @var{n} [, @var{m}]]) Compute the two dimensional FFT of @var{a}. The optional arguments @var{n} and @var{m} may be used specify the number of rows and columns of @var{a} to use. If either of these is larger than the size of @var{a}, @var{a} is resized and padded with zeros. +@end deftypefn -@item fftconv (@var{a}, @var{b}, @var{N}) +@deftypefn {Built-in Function} {} ifft2 (@var{a} [, @var{n} [, @var{m}]]) +Compute the two dimensional inverse FFT of @var{a}. + +The optional arguments @var{n} and @var{m} may be used specify the +number of rows and columns of @var{a} to use. If either of these is +larger than the size of @var{a}, @var{a} is resized and padded with +zeros. +@end deftypefn + +@deftypefn {Built-in Function} {} fftconv (@var{a}, @var{b}, @var{N}) This function returns the convolution of the vectors @var{a} and @var{b}, a vector with length equal to the @code{length (a) + length (b) - 1}. If @var{a} and @var{b} are the coefficient vectors of two @@ -37,16 +59,18 @@ The computation uses the FFT by calling the function @code{fftfilt}. If the optional argument @var{N} is specified, an N-point FFT is used. +@end deftypefn -@item fftfilt (@var{b}, @var{x}, @var{N}) +@deftypefn {Function File} {} fftfilt (@var{b}, @var{x}, @var{N}) With two arguments, @code{fftfilt} filters @var{x} with the FIR filter @var{b} using the FFT. Given the optional third argument, @var{N}, @code{fftfilt} uses the overlap-add method to filter @var{x} with @var{b} using an N-point FFT. +@end deftypefn -@item filter (@var{b}, @var{a}, @var{x}) +@deftypefn {Built-in Function} {y =} filter (@var{b}, @var{a}, @var{x}) This function returns the solution to the following linear, time-invariant difference equation: @iftex @@ -127,21 +151,18 @@ k=1 @end example @end ifinfo - -When called as - -@example -[y, sf] = filter (b, a, x, si) -@end example +@end deftypefn -@noindent -@code{filter} uses the argument @var{si} as the initial state of the -system and and returns the final state in @var{sf}. The state vector is -a column vector whose length is equal to the length of the longest -coefficient vector minus one. If @var{si} is not set, the initial state -vector is set to all zeros. +@deftypefn {Built-in Function} {[@var{y}, @var{sf}] =} filter (@var{b}, @var{a}, @var{x}, @var{si}) +This is the same as the @code{filter} function described above, except +that @var{si} is taken as the initial state of the system and the final +state is returned as @var{sf}. The state vector is a column vector +whose length is equal to the length of the longest coefficient vector +minus one. If @var{si} is not set, the initial state vector is set to +all zeros. +@end deftypefn -@item freqz +@deftypefn {Function File} {} freqz Compute the frequency response of a filter. @code{[@var{h}, @var{w}] = freqz (@var{b})} returns the complex frequency @@ -179,27 +200,9 @@ $2\pi$. @end tex @end iftex - -@item ifft (@var{a} [, @var{n}]) -Compute the inverse FFT of @var{a} using subroutines from FFTPACK. If -@var{a} is a matrix, @code{fft} computes the inverse FFT for each column -of @var{a}. +@end deftypefn -If called with two arguments, @var{n} is expected to be an integer -specifying the number of elements of @var{a} to use. If @var{a} is a -matrix, @var{n} specifies the number of rows of @var{a} to use. If -@var{n} is larger than the size of @var{a}, @var{a} is resized and -padded with zeros. - -@item ifft2 (@var{a} [, @var{n} [, @var{m}]]) -Compute the two dimensional inverse FFT of @var{a}. - -The optional arguments @var{n} and @var{m} may be used specify the -number of rows and columns of @var{a} to use. If either of these is -larger than the size of @var{a}, @var{a} is resized and padded with -zeros. - -@item sinc (@var{x}) +@deftypefn {Function File} {} sinc (@var{x}) Returns @iftex @tex @@ -209,5 +212,4 @@ @ifinfo sin(pi*x)/(pi*x). @end ifinfo - -@end ftable +@end deftypefn
--- a/doc/interpreter/special.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/special.texi Wed Oct 30 23:00:41 1996 +0000 @@ -17,75 +17,43 @@ @node Special Utility Matrices, Famous Matrices, Special Matrices, Special Matrices @section Special Utility Matrices -@findex eye - -The function @code{eye} returns an identity matrix. If invoked with a -single scalar argument, @code{eye} returns a square matrix with the -dimension specified. If you supply two scalar arguments, @code{eye} -takes them to be the number of rows and columns. If given a matrix or -vector argument, @code{eye} returns an identity matrix with the same -dimensions as the given argument. - -For example, +@deftypefn {Built-in Function} {} eye (@var{x}) +@deftypefnx {Built-in Function} {} eye (@var{n}, @var{m}) +Returns an identity matrix. If invoked with a single scalar argument, +@code{eye} returns a square matrix with the dimension specified. If you +supply two scalar arguments, @code{eye} takes them to be the number of +rows and columns. If given a vector with two elements, @code{eye} uses +the values of the elements as the number of rows and columns, +respecively. For example, @example +@group eye (3) -@end example - -@noindent -creates an identity matrix with three rows and three columns, -@example -eye (5, 8) -@end example - -@noindent -creates an identity matrix with five rows and eight columns, and - -@example -eye ([13, 21; 34, 55]) + @result{} 1 0 0 + 0 1 0 + 0 0 1 +@end group @end example -@noindent -creates an identity matrix with two rows and two columns. - -Normally, @code{eye} expects any scalar arguments you provide to be real -and non-negative. The variables @code{ok_to_lose_imaginary_part} and -@code{treat_neg_dim_as_zero} control the behavior of @code{eye} for -complex and negative arguments. @xref{User Preferences}. Any -non-integer arguments are rounded to the nearest integer value. - -There is an ambiguity when these functions are called with a single -argument. You may have intended to create a matrix with the same -dimensions as another variable, but ended up with something quite -different, because the variable that you used as an argument was a -scalar instead of a matrix. - -For example, if you need to create an identity matrix with the same -dimensions as another variable in your program, it is best to use code -like this +The following expressions all produce the same result: @example -eye (rows (a), columns (a)) -@end example - -@noindent -instead of just - -@example -eye (a) +@group +eye (2) +eye (2, 2) +eye (size ([1, 2; 3, 4]) +@end group @end example -@noindent -unless you know that the variable @var{a} will @emph{always} be a matrix. +For compatibility with @sc{Matlab}, calling @code{eye} with no arguments +is equivalent to calling it with an argument of 1. +@end deftypefn -@findex ones -@findex zeros -@findex rand - -The functions @code{ones}, @code{zeros}, and @code{rand} all work like -@code{eye}, except that they fill the resulting matrix with all ones, -all zeros, or a set of random values. +@deftypefn {Built-in Function} {} ones (@var{x}) +@deftypefnx {Built-in Function} {} ones (@var{n}, @var{m}) +Returns a matrix whose elements are all 1. The arguments are handled +the same as the arguments for @code{eye}. If you need to create a matrix whose values are all the same, you should use an expression like @@ -93,80 +61,143 @@ @example val_matrix = val * ones (n, m) @end example +@end deftypefn -The @code{rand} function also takes some additional arguments that allow -you to control its behavior. For example, the function call +@deftypefn {Built-in Function} {} zeros (@var{x}) +@deftypefnx {Built-in Function} {} zeros (@var{n}, @var{m}) +Returns a matrix whose elements are all 0. The arguments are handled +the same as the arguments for @code{eye}. +@end deftypefn + +@deftypefn {Built-in Function} {} rand (@var{x}) +@deftypefnx {Built-in Function} {} rand (@var{n}, @var{m}) +@deftypefnx {Built-in Function} {} rand (@code{"seed"}, @var{x}) +Returns a matrix with random elements uniformly distributed on the +interval (0, 1). The arguments are handled the same as the arguments +for @code{eye}. In +addition, you can set the seed for the random number generator using the +form @example -rand ("normal") +randn ("seed", @var{x}) @end example @noindent -causes the sequence of numbers to be normally distributed. You may also -use an argument of @code{"uniform"} to select a uniform distribution. To -find out what the current distribution is, use an argument of -@code{"dist"}. - -Normally, @code{rand} obtains the seed from the system clock, so that -the sequence of random numbers is not the same each time you run Octave. -If you really do need for to reproduce a sequence of numbers exactly, -you can set the seed to a specific value. For example, the function call +where @var{x} is a scalar value. If called as @example -rand ("seed", 13) +rand ("seed") +@end example + +@noindent +@code{rand} returns the current value of the seed. +@end deftypefn + +@deftypefn {Built-in Function} {} randn (@var{x}) +@deftypefnx {Built-in Function} {} randn (@var{n}, @var{m}) +@deftypefnx {Built-in Function} {} randn (@code{"seed"}, @var{x}) +Returns a matrix with normally distributed random elements. The +arguments are handled the same as the arguments for @code{eye}. In +addition, you can set the seed for the random number generator using the +form + +@example +randn ("seed", @var{x}) +@end example + +@noindent +where @var{x} is a scalar value. If called as + +@example +randn ("seed") @end example @noindent -sets the seed to the number 13. To see what the current seed is, use -the argument @code{"seed"}. - -If it is invoked without arguments, @code{rand} returns a -single element of a random sequence. +@code{randn} returns the current value of the seed. +@end deftypefn -The @code{rand} function uses Fortran code from RANLIB, a library -of fortran routines for random number generation, compiled by Barry W. -Brown and James Lovato of the Department of Biomathematics at The -University of Texas, M.D. Anderson Cancer Center, Houston, TX 77030. - -@findex diag - -To create a diagonal matrix with vector @var{v} on diagonal @var{k}, use -the function diag (@var{v}, @var{k}). The second argument is optional. -If it is positive, the vector is placed on the @var{k}-th -super-diagonal. If it is negative, it is placed on the @var{-k}-th -sub-diagonal. The default value of @var{k} is 0, and the vector is -placed on the main diagonal. For example, +The @code{rand} and @code{randn} functions use separate generators. +This ensures that @example -octave:13> diag ([1, 2, 3], 1) -ans = - - 0 1 0 0 - 0 0 2 0 - 0 0 0 3 - 0 0 0 0 +@group +rand ("seed", 13); +randn ("seed", 13); +u = rand (100, 1); +n = randn (100, 1); +@end group @end example -@findex linspace -@findex logspace - -The functions @code{linspace} and @code{logspace} make it very easy to -create vectors with evenly or logarithmically spaced elements. For -example, +@noindent +and @example -linspace (@var{base}, @var{limit}, @var{n}) +@group +rand ("seed", 13); +randn ("seed", 13); +u = zeros (100, 1); +n = zeros (100, 1); +for i = 1:100 + u(i) = rand (); + n(i) = randn (); +end +@end group @end example @noindent -creates a row vector with @var{n} (@var{n} greater than 2) linearly +produce equivalent results. + +Normally, @code{rand} and @code{randn} obtain their initial +seeds from the system clock, so that the sequence of random numbers is +not the same each time you run Octave. If you really do need for to +reproduce a sequence of numbers exactly, you can set the seed to a +specific value. + +If it is invoked without arguments, @code{rand} and @code{randn} return a +single element of a random sequence. + +The @code{rand} and @code{randn} functions use Fortran code from RANLIB, +a library of fortran routines for random number generation, compiled by +Barry W. Brown and James Lovato of the Department of Biomathematics at +The University of Texas, M.D. Anderson Cancer Center, Houston, TX 77030. + +@deftypefn {Built-in Function} {} diag (@var{v}, @var{k}) +Returns a diagonal matrix with vector @var{v} on diagonal @var{k}. The +second argument is optional. If it is positive, the vector is placed on +the @var{k}-th super-diagonal. If it is negative, it is placed on the +@var{-k}-th sub-diagonal. The default value of @var{k} is 0, and the +vector is placed on the main diagonal. For example, + +@example +@group +diag ([1, 2, 3], 1) + + @result{} 0 1 0 0 + 0 0 2 0 + 0 0 0 3 + 0 0 0 0 +@end group +@end example +@end deftypefn + +The functions @code{linspace} and @code{logspace} make it very easy to +create vectors with evenly or logarithmically spaced elements. +@xref{Ranges}. + +@deftypefn {Function File} {} linspace (@var{base}, @var{limit}, @var{n}) +creates a row vector with @var{n} (@var{n} greater than 1) linearly spaced elements between @var{base} and @var{limit}. The @var{base} and @var{limit} are always included in the range. If @var{base} is greater than @var{limit}, the elements are stored in decreasing order. If the number of points is not specified, a value of 100 is used. -The function @code{logspace} is similar to @code{linspace} except that -the values are logarithmically spaced. +The @code{linspace} function always returns a row vector, regardless of +the value of @code{prefer_column_vectors}. +@end deftypefn + +@deftypefn {Function File} {} logspace (@var{base}, @var{limit}, @var{n}) +Similar to @code{linspace} except that the values are logarithmically +spaced. If @var{limit} is equal to @iftex @@ -196,21 +227,18 @@ 10^base and 10^pi, @end ifinfo in order to be compatible with the corresponding @sc{Matlab} function. - -The @code{linspace} and @code{logspace} functions always return row -vectors, regardless of the value of @code{prefer_column_vectors}. -@xref{Ranges}. +@end deftypefn @node Famous Matrices, , Special Utility Matrices, Special Matrices @section Famous Matrices The following functions return famous matrix forms. -@ftable @code -@item hadamard (@var{k}) +@deftypefn {Function File} {} hadamard (@var{k}) Return the Hadamard matrix of order n = 2^k. +@end deftypefn -@item hankel (@var{c}, @var{r}) +@deftypefn {Function File} {} hankel (@var{c}, @var{r}) Return the Hankel matrix constructed given the first column @var{c}, and (optionally) the last row @var{r}. If the last element of @var{c} is not the same as the first element of @var{r}, the last element of @@ -234,10 +262,10 @@ H (i, j) = r (i+j-m), otherwise @end group @end example +@end ifinfo +@end deftypefn -@end ifinfo - -@item hilb (@var{n}) +@deftypefn {Function File} {} hilb (@var{n}) Return the Hilbert matrix of order @var{n}. The @iftex @tex @@ -261,14 +289,16 @@ H (i, j) = 1 / (i + j - 1) @end example @end ifinfo +@end deftypefn -@item invhilb (@var{n}) +@deftypefn {Function File} {} invhilb (@var{n}) Return the inverse of a Hilbert matrix of order @var{n}. This is exact. Compare with the numerical calculation of @code{inverse (hilb (n))}, which suffers from the ill-conditioning of the Hilbert matrix, and the finite precision of your computer's floating point arithmetic. +@end deftypefn -@item toeplitz (@var{c}, @var{r}) +@deftypefn {Function File} {} toeplitz (@var{c}, @var{r}) Return the Toeplitz matrix constructed given the first column @var{c}, and (optionally) the first row @var{r}. If the first element of @var{c} is not the same as the first element of @var{r}, the first element of @@ -302,8 +332,9 @@ @end group @end example @end ifinfo +@end deftypefn -@item vander (@var{c}) +@deftypefn {Function File} {} vander (@var{c}) Return the Vandermonde matrix whose next to last column is @var{c}. A Vandermonde matrix has the form @@ -331,4 +362,4 @@ @end group @end example @end ifinfo -@end ftable +@end deftypefn
--- a/doc/interpreter/stats.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/stats.texi Wed Oct 30 23:00:41 1996 +0000 @@ -9,60 +9,131 @@ you would like to help improve Octave in this area, please contact @code{bug-octave@@bevo.che.wisc.edu}. -@ftable @code -@item corrcoef (@var{x} [, @var{y}]) +@deftypefn {Function File} {} mean (@var{x}) +If @var{x} is a vector, compute the mean of the elements of @var{x} +@iftex +@tex +$$ {\rm mean}(x) = \bar{x} = {1\over N} \sum_{i=1}^N x_i $$ +@end tex +@end iftex +@ifinfo + +@example +mean (x) = SUM_i x(i) / N +@end example +@end ifinfo +If @var{x} is a matrix, compute the mean for each column and return them +in a row vector. +@end deftypefn + +@deftypefn {Function File} {} median (@var{x}) +If @var{x} is a vector, compute the median value of the elements of +@var{x}. +@iftex +@tex +$$ +{\rm median} (x) = + \cases{x(\lceil N/2\rceil), & $N$ odd;\cr + (x(N/2)+x((N/2)+1))/2, & $N$ even.} +$$ +@end tex +@end iftex +@ifinfo + +@example +@group + x(ceil(N/2)), N odd +median(x) = + (x(N/2) + x((N/2)+1))/2, N even +@end group +@end example +@end ifinfo +If @var{x} is a matrix, compute the median value for each +column and return them in a row vector. +@end deftypefn + +@deftypefn {Function File} {} std (@var{x}) +If @var{x} is a vector, compute the standard deviation of the elements +of @var{x}. +@iftex +@tex +$$ +{\rm std} (x) = \sigma (x) = \sqrt{{\sum_{i=1}^N (x_i - \bar{x}) \over N - 1}} +$$ +@end tex +@end iftex +@ifinfo + +@example +@group +std (x) = sqrt (sumsq (x - mean (x)) / (n - 1)) +@end group +@end example +@end ifinfo +If @var{x} is a matrix, compute the standard deviation for +each column and return them in a row vector. +@end deftypefn + +@deftypefn {Function File} {} cov (@var{x} [, @var{y}]) +If each row of @var{x} and @var{y} is an observation and each column is +a variable, the (@var{i},@var{j})-th entry of +@code{cov (@var{x}, @var{y})} is the covariance between the @var{i}-th +variable in @var{x} and the @var{j}-th variable in @var{y}. If called +with one argument, compute @code{cov (@var{x}, @var{x})}. +@end deftypefn + +@deftypefn {Function File} {} corrcoef (@var{x} [, @var{y}]) If each row of @var{x} and @var{y} is an observation and each column is a variable, the (@var{i},@var{j})-th entry of @code{corrcoef (@var{x}, @var{y})} is the correlation between the @var{i}-th variable in @var{x} and the @var{j}-th variable in @var{y}. -If invoked with one argument, compute @code{corrcoef (@var{x}, @var{x})}. +If called with one argument, compute @code{corrcoef (@var{x}, @var{x})}. +@end deftypefn -@item cov (@var{x} [, @var{y}]) -If each row of @var{x} and @var{y} is an observation and each column is -a variable, the (@var{i},@var{j})-th entry of -@code{cov (@var{x}, @var{y})} is the covariance between the @var{i}-th -variable in @var{x} and the @var{j}-th variable in @var{y}. If invoked -with one argument, compute @code{cov (@var{x}, @var{x})}. - -@item kurtosis (@var{x}) +@deftypefn {Function File} {} kurtosis (@var{x}) If @var{x} is a vector of length @var{N}, return the kurtosis +@iftex +@tex +$$ + {\rm kurtosis} (x) = {1\over N \sigma(x)^4} \sum_{i=1}^N (x_i-\bar{x})^4 - 3 +$$ +@end tex +@end iftex +@ifinfo @example -kurtosis(x) = N^(-1) std(x)^(-4) SUM_i (x(i)-mean(x))^4 - 3 +kurtosis (x) = N^(-1) std(x)^(-4) sum ((x - mean(x)).^4) - 3 @end example +@end ifinfo @noindent of @var{x}. If @var{x} is a matrix, return the row vector containing the kurtosis of each column. +@end deftypefn -@item mahalanobis (@var{x}, @var{y}) +@deftypefn {Function File} {} mahalanobis (@var{x}, @var{y}) Returns Mahalanobis' D-square distance between the multivariate samples @var{x} and @var{y}, which must have the same number of components (columns), but may have a different number of observations (rows). - -@item mean (@var{a}) -If @var{a} is a vector, compute the mean of the elements of @var{a}. If -@var{a} is a matrix, compute the mean for each column and return them in -a row vector. +@end deftypefn -@item median (@var{a}) -If @var{a} is a vector, compute the median value of the elements of -@var{a}. If @var{a} is a matrix, compute the median value for each -column and return them in a row vector. - -@item skewness (@var{x}) +@deftypefn {Function File} {} skewness (@var{x}) If @var{x} is a vector of length @var{N}, return the skewness +@iftex +@tex +$$ +{\rm skewness} (x) = {1\over N \sigma(x)^3} \sum_{i=1}^N (x_i)-\bar{x})^3 +$$ +@end tex +@end iftex +@ifinfo @example -skewness (x) = N^(-1) std(x)^(-3) SUM_i (x(i)-mean(x))^3 +skewness (x) = N^(-1) std(x)^(-3) sum ((x - mean(x)).^3) @end example +@end ifinfo @noindent of @var{x}. If @var{x} is a matrix, return the row vector containing the skewness of each column. - -@item std (@var{a}) -If @var{a} is a vector, compute the standard deviation of the elements -of @var{a}. If @var{a} is a matrix, compute the standard deviation for -each column and return them in a row vector. -@end ftable +@end deftypefn
--- a/doc/interpreter/stmt.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/stmt.texi Wed Oct 30 23:00:41 1996 +0000 @@ -6,22 +6,26 @@ @chapter Statements @cindex statements +Statements may be a simple constant expression or a complicated list of +nested loops and conditional statements. + @dfn{Control statements} such as @code{if}, @code{while}, and so on control the flow of execution in Octave programs. All the control statements start with special keywords such as @code{if} and @code{while}, to distinguish them from simple expressions. - -@cindex @code{end} statement Many control statements contain other statements; for example, the @code{if} statement contains another statement which may or may not be -executed. Each control statement has a corresponding @dfn{end} -statement that marks the end of the end of the control statement. For -example, the keyword @code{endif} marks the end of an @code{if} -statement, and @code{endwhile} marks the end of a @code{while} -statement. You can use the keyword @code{end} anywhere a more specific -end keyword is expected, but using the more specific keywords is -preferred because if you use them, Octave is able to provide better -diagnostics for mismatched or missing end tokens. +executed. + +@cindex @code{end} statement +Each control statement has a corresponding @dfn{end} statement that +marks the end of the end of the control statement. For example, the +keyword @code{endif} marks the end of an @code{if} statement, and +@code{endwhile} marks the end of a @code{while} statement. You can use +the keyword @code{end} anywhere a more specific end keyword is expected, +but using the more specific keywords is preferred because if you use +them, Octave is able to provide better diagnostics for mismatched or +missing end tokens. The list of statements contained between keywords like @code{if} or @code{while} and the corresponding end statement is called the @@ -50,7 +54,11 @@ it looks like this: @example -if (@var{condition}) @var{then-body} endif +@group +if (@var{condition}) + @var{then-body} +endif +@end group @end example @noindent @@ -67,7 +75,13 @@ The second form of an if statement looks like this: @example -if (@var{condition}) @var{then-body} else @var{else-body} endif +@group +if (@var{condition}) + @var{then-body} +else + @var{else-body} +endif +@end group @end example @noindent @@ -96,7 +110,15 @@ this: @example -if (@var{condition}) @var{then-body} elseif (@var{condition}) @var{elseif-body} else @var{else-body} endif +@group +if (@var{condition}) + @var{then-body} +elseif (@var{condition}) + @var{elseif-body} +else + @var{else-body} +endif +@end group @end example @noindent @@ -169,6 +191,68 @@ using the indentation to show how Octave groups the statements. @xref{Functions and Scripts}. +@defvr {Built-in Variable} warn_assign_as_truth_value +If the value of @code{warn_assign_as_truth_value} is nonzero, a +warning is issued for statements like + +@example +if (s = t) + ... +@end example + +@noindent +since such statements are not common, and it is likely that the intent +was to write + +@example +if (s == t) + ... +@end example + +@noindent +instead. + +There are times when it is useful to write code that contains +assignments within the condition of a @code{while} or @code{if} +statement. For example, statements like + +@example +while (c = getc()) + ... +@end example + +@noindent +are common in C programming. + +It is possible to avoid all warnings about such statements by setting +@code{warn_assign_as_truth_value} to 0, but that may also +let real errors like + +@example +if (x = 1) # intended to test (x == 1)! + ... +@end example + +@noindent +slip by. + +In such cases, it is possible suppress errors for specific statements by +writing them with an extra set of parentheses. For example, writing the +previous example as + +@example +while ((c = getc())) + ... +@end example + +@noindent +will prevent the warning from being printed for this statement, while +allowing Octave to warn about other assignments used in conditional +contexts. + +The default value of @code{warn_assign_as_truth_value} is 1. +@end defvr + @node The while Statement, The for Statement, The if Statement, Statements @section The @code{while} Statement @cindex @code{while} statement @@ -238,6 +322,9 @@ body; but using one makes the program clearer unless the body is very simple. +@xref{The if Statement} for a description of the variable +@code{warn_assign_as_truth_value}. + @node The for Statement, The break Statement, The while Statement, Statements @section The @code{for} Statement @cindex @code{for} statement @@ -255,6 +342,12 @@ @end example @noindent +where @var{body} stands for any statement or list of statements, +@var{expression} is any valid expression, and @var{var} may take several +forms. Usually it is a simple variable name or an indexed variable. If +the value of @var{expression} is a structure, @var{var} may also be a +list. @xref{Looping Over Structure Elements}, below. + The assignment expression in the @code{for} statement works a bit differently than Octave's normal assignment statement. Instead of assigning the complete result of the expression, it assigns each column @@ -286,9 +379,6 @@ loop body is executed again. This process continues until there are no more elements to assign. -In the @code{for} statement, @var{body} stands for any statement or list -of statements. - Although it is possible to rewrite all @code{for} loops as @code{while} loops, the Octave language has both statements because often a @code{for} loop is both less work to type and more natural to think of. @@ -296,6 +386,65 @@ easier to think of this counting as part of looping rather than as something to do inside the loop. +@menu +* Looping Over Structure Elements:: +@end menu + +@node Looping Over Structure Elements, , The for Statement, The for Statement +@subsection Looping Over Structure Elements +@cindex structure elements, looping over +@cindex looping over structure elements + +A special form of the @code{for} statement allows you to loop over all +the elements of a structure: + +@example +@group +for [ @var{val}, @var{key} ] = @var{expression} + @var{body} +endfor +@end group +@end example + +@noindent +In this form of the @code{for} statement, the value of @var{expression} +must be a structure. If it is, @var{key} and @var{val} are set to the +name of the element and the corresponding value in turn, until there are +no more elements. For example, + +@example +@group +octave:1> x.a = 1; x.b = [1, 2; 3, 4]; x.c = "string"; +octave:2> for [val, key] = x; key, val, endfor +@end group +@end example + +@noindent will print + +@example +@group +key = a +val = 1 +key = b +val = + + 1 2 + 3 4 + +key = c +val = string +@end group +@end example + +The elements are not accessed in any particular order. If you need to +cycle through the list in a particular way, you will have to use the +function @code{struct_elements} and sort the list yourself. + +The @var{key} variable may also be omitted. If it is, the brackets are +also optional. This is useful for cycling through the values of all the +structure elements when the names of the elements do not need to be +known. + @node The break Statement, The continue Statement, The for Statement, Statements @section The @code{break} Statement @cindex @code{break} statement @@ -335,7 +484,6 @@ @example @group -@group num = 103; div = 2; while (1) @@ -350,7 +498,6 @@ endif endwhile @end group -@end group @end example @node The continue Statement, The unwind_protect Statement, The break Statement, Statements @@ -434,6 +581,7 @@ even if an error occurs while performing the indexing operation. @example +@group save_do_fortran_indexing = do_fortran_indexing; unwind_protect do_fortran_indexing = "true"; @@ -441,6 +589,7 @@ unwind_protect_cleanup do_fortran_indexing = save_do_fortran_indexing; end_unwind_protect +@end group @end example Without @code{unwind_protect}, the value of @var{do_fortran_indexing} @@ -503,9 +652,11 @@ the lines @example +@group x = long_variable_name ... + longer_variable_name \ - 42 +@end group @end example @noindent @@ -518,9 +669,11 @@ the newline character. For example, the statement @example +@group x = long_variable_name ... % comment one + longer_variable_name \ % comment two - 42 % last comment +@end group @end example @noindent @@ -531,11 +684,13 @@ statements like @example +@group if (big_long_variable_name == other_long_variable_name || not_so_short_variable_name > 4 && y > x) some (code, here); endif +@end group @end example @noindent
--- a/doc/interpreter/strings.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/strings.texi Wed Oct 30 23:00:41 1996 +0000 @@ -7,29 +7,24 @@ @node String Functions, System Utilities, Matrix Manipulation, Top @chapter String Functions -Octave currently has a limited ability to work with strings. - -@findex strcmp - -The function @code{strcmp (@var{s1}, @var{s2})} compares two strings, -returning 1 if they are the same, and 0 otherwise. +@deftypefn {Function File} {} strcmp (@var{s1}, @var{s2}) +Compares two strings, returning 1 if they are the same, and 0 otherwise. @strong{Note: For compatibility with @sc{Matlab}, Octave's strcmp function returns 1 if the strings are equal, and 0 otherwise. This is just the opposite of the corresponding C library function.} - -@findex int2str -@findex num2str +@end deftypefn -The functions @code{int2str} and @code{num2str} convert a numeric -argument to a string. These functions are not very flexible, but are -provided for compatibility with @sc{Matlab}. For better control over -the results, use @code{sprintf} (@pxref{Formatted Output}). +@deftypefn {Function File} {} int2str (@var{n}) +@deftypefnx {Function File} {} num2str (@var{x}) +Convert a number to a string. These functions are not very flexible, +but are provided for compatibility with @sc{Matlab}. For better control +over the results, use @code{sprintf} (@pxref{Formatted Output}). +@end deftypefn -@findex setstr - -The function @code{setstr} can be used to convert a vector to a string. -Each element of the vector is converted to the corresponding ASCII +@deftypefn {Built-in Function} {} setstr (@var{x}) +Convert a matrix to a string. Each element of the matrix is converted +to the corresponding ASCII character. For example, @example @@ -42,12 +37,18 @@ @example abc @end example - -@findex undo_string_escapes +@end deftypefn -The function @code{undo_string_escapes (@var{string})} converts special -characters in strings back to their escaped forms. For example, the -expression +@defvr {Built-in Variable} implicit_str_to_num_ok +If the value of @code{implicit_str_to_num_ok} is nonzero, implicit +conversions of strings to their numeric ASCII equivalents are allowed. +Otherwise, an error message is printed and control is returned to the +top level. The default value is 0. +@end defvr + +@deftypefn {Built-in Function} {} undo_string_escapes (@var{s}) +Converts special characters in strings back to their escaped forms. For +example, the expression @example bell = "\a"; @@ -70,202 +71,235 @@ replaces the unprintable alert character with its printable representation. @xref{String Constants}, for a description of string escapes. - -Here is a list of some other string functions. +@end deftypefn -@ftable @code -@item bin2dec -Given a binary number @var{x} represented as a 0/1-string, -@code{bin2dec (@var{x})} returns the decimal number represented by -@var{x}. +@deftypefn {Function File} {} bin2dec (@var{s}) +Given a binary number represented as a string of zeros and ones, +returns the corresponding decimal number. For example, + @example bin2dec ("1110") - @result{} 14 + @result{} 14 @end example +@end deftypefn -@item blanks -@code{blanks (@var{n})} returns a string of @var{n} blanks. +@deftypefn {Function File} {} blanks (var{n}) +Returns a string of @var{n} blanks. +@end deftypefn -@item deblank -@code{deblank (@var{s})} removes the trailing blanks from the string -@var{s}. +@deftypefn {Function File} {} deblank (@var{s}) +Removes the trailing blanks from the string @var{s}. +@end deftypefn -@item dec2bin -If @var{x} is a nonnegative integer, @kbd{bin2dec (@var{x})} returns the -binary number corresponding to @var{x}. +@deftypefn {Function File} {} dec2bin (@var{n}) +Given a nonnegative integer, returns the corresponding binary number as +a string of ones and zeros. For example, -For example, @example dec2bin (14) @result{} "1110" @end example +@end deftypefn -@item dec2hex -If @var{x} is a nonnegative integer, @kbd{dec2hex (@var{x})} returns the -hex number corresponding to @var{x}. +@deftypefn {Function File} {} dec2hex (@var{n}) +Given a nonnegative integer, returns the corresponding hexadecimal +number as a string. For example, -For example, @example dec2hex (2748) @result{} "abc" @end example +@end deftypefn -@item findstr -@kbd{findstr (@var{s}, @var{t} [,@var{overlap}])} returns the vector of -all positions in the longer of the two strings @var{s} and @var{t} where -an occurence of the shorter of the two starts. +@deftypefn {Function File} {} findstr (@var{s}, @var{t}, @var{overlap}) +Returns the vector of all positions in the longer of the two strings +@var{s} and @var{t} where an occurence of the shorter of the two starts. +If the optional argument @var{overlap} is nonzero, the returned vector +can include overlapping positions (this is the default). For example, -If the optional argument @var{overlap} is nonzero, the returned vector -can include overlapping positions (this is the default). - -For example, @example findstr ("ababab", "a") @result{} [1 3 5] findstr ("abababa", "aba", 0) @result{} [1, 5] @end example +@end deftypefn -@item hex2dec -For a hex number @var{x} represented as a hex string, @kbd{hex2dec -(@var{x})} returns the decimal number corresponding to @var{x}. +@deftypefn {Function File} {} hex2dec (@var{s}) +Given a hexadecimal number represented as a string, returns the +corresponding decimal number. For example, -For example, @example hex2dec ("12B") @result{} 299 hex2dec ("12b") @result{} 299 @end example +@end deftypefn -@item index -@kbd{index (@var{s}, @var{t})} returns the position of the first -occurence of the string @var{t} in the string @var{s}, or 0 if no -occurence is found. +@deftypefn {Function File} {} index (@var{s}, @var{t}) +Returns the position of the first occurence of the string @var{t} in the +string @var{s}, or 0 if no occurence is found. For example, -For example, @example index ("Teststring", "t") @result{} 4 @end example @strong{Note:} This function does not work for arrays of strings. +@end deftypefn -@item rindex -@kbd{rindex (@var{s}, @var{t})} returns the position of the last -occurence of the string @var{t} in the string @var{s}, or 0 if no -occurence is found. +@deftypefn {Function File} {} rindex (@var{s}, @var{t}) +Returns the position of the last occurence of the string @var{t} in the +string @var{s}, or 0 if no occurence is found. For example, -For example, @example rindex ("Teststring", "t") @result{} 6 @end example @strong{Note:} This function does not work for arrays of strings. +@end deftypefn -@item split -@kbd{@var{m} = split (@var{s}, @var{t})} divides the string @var{s} into -pieces separated by @var{t}, and stores the pieces as the rows of @var{m} -(padded with blanks to form a valid matrix). +@deftypefn {Function File} {} split (@var{s}, @var{t}) +Divides the string @var{s} into pieces separated by @var{t}, returning +the result in a string array (padded with blanks to form a valid +matrix). For example, -For example, @example split ("Test string", "t") @result{} Tes s ring @end example +@end deftypefn -@item str2mat -@kbd{str2mat (@var{s_1}, @dots{}, @var{s_n})} returns a matrix -containing the strings @var{s_1}, @dots{}, @var{s_n} as its rows. -Each string is padded with blanks in order to form a valid matrix. +@deftypefn {Function File} {} str2mat (@var{s_1}, @dots{}, @var{s_n}) +Returns a matrix containing the strings @var{s_1}, @dots{}, @var{s_n} as +its rows. Each string is padded with blanks in order to form a valid +matrix. @quotation @strong{Note:} This function is modelled after @sc{MATLAB}. In Octave, you can create a matrix of strings by @kbd{[@var{s_1}; @dots{}; @var{s_n}]}. @end quotation +@end deftypefn -@item strrep -@kbd{strrep (@var{s}, @var{x}, @var{y})} replaces all occurences of the -substring @var{x} of the string @var{s} with the string @var{y}. +@defvr {Built-in Variable} string_fill_char +@end defvr -For example, +@deftypefn {Function File} {} strrep (@var{s}, @var{x}, @var{y}) +Replaces all occurences of the substring @var{x} of the string @var{s} +with the string @var{y}. For example, + @example strrep ("This is a test string", "is", "&%$") @result{} Th&%$ &%$ a test string @end example +@end deftypefn -@item substr -@kbd{substr (@var{s}, @var{beg}, @var{len})} returns the substring of -@var{s} which starts at character number @var{beg} and is @var{len} -characters long. +@deftypefn {Function File} {} substr (@var{s}, @var{beg}, @var{len}) +Returns the substring of @var{s} which starts at character number +@var{beg} and is @var{len} characters long. For example, + +@example +substr ("This is a test string", 6, 9) + @result{} is a test +@end example @quotation @strong{Note:} This function is patterned after AWK. You can get the same result by @kbd{@var{s} (@var{beg} : (@var{beg} + @var{len} - 1))}. @end quotation - -For example, -@example -substr ("This is a test string", 6, 9) - @result{} is a test -@end example +@end deftypefn -@item tolower -@kbd{tolower (@var{s})} returns a copy of the string @var{s}, with each -upper-case character replaced by the corresponding lower-case one; -nonalphabetic characters are left unchanged. +@deftypefn {Function File} {} tolower (@var{s}) +Return a copy of the string @var{s}, with each upper-case character +replaced by the corresponding lower-case one; nonalphabetic characters +are left unchanged. For example, -For example, @example tolower ("MiXeD cAsE 123") @result{} "mixed case 123" @end example +@end deftypefn -@item toupper -@kbd{toupper (@var{s})} returns a copy of the string @var{s}, with each -lower-case character replaced by the corresponding upper-case one; -nonalphabetic characters are left unchanged. +@deftypefn {Function File} {} toupper (@var{s}) +Returns a copy of the string @var{s}, with each lower-case character +replaced by the corresponding upper-case one; nonalphabetic characters +are left unchanged. For example, -For example, @example +@group toupper ("MiXeD cAsE 123") @result{} "MIXED CASE 123" +@end group @end example -@end ftable +@end deftypefn + +@deftypefn {Function File} {} toascii (@var{s}) +Return ASCII representation of @var{s} in a matrix. For example, + +@example +@group +toascii ("ASCII") + @result{} [ 65, 83, 67, 73, 73 ] +@end group + +@end example +@end deftypefn Octave also provides the following C-type character class test functions. They all operate on string arrays and return matrices of zeros and ones. Elements that are nonzero indicate that the condition was true for the corresponding character in the string array. -@ftable @code -@item isalnum +@deftypefn {Mapping Function} {} isalnum (@var{s}) letter or a digit -@item isalpha +@end deftypefn + +@deftypefn {Mapping Function} {} isalpha (@var{s}) letter -@item isascii +@end deftypefn + +@deftypefn {Mapping Function} {} isascii (@var{s}) ascii -@item iscntrl +@end deftypefn + +@deftypefn {Mapping Function} {} iscntrl (@var{s}) control character -@item isdigit +@end deftypefn + +@deftypefn {Mapping Function} {} isdigit (@var{s}) digit -@item isgraph +@end deftypefn + +@deftypefn {Mapping Function} {} isgraph (@var{s}) printable (but not space character) -@item islower +@end deftypefn + +@deftypefn {Mapping Function} {} islower (@var{s}) lower case -@item isprint +@end deftypefn + +@deftypefn {Mapping Function} {} isprint (@var{s}) printable (including space character) -@item ispunct +@end deftypefn + +@deftypefn {Mapping Function} {} ispunct (@var{s}) punctuation -@item isspace +@end deftypefn + +@deftypefn {Mapping Function} {} isspace (@var{s}) whitespace -@item isupper +@end deftypefn + +@deftypefn {Mapping Function} {} isupper (@var{s}) upper case -@item isxdigit +@end deftypefn + +@deftypefn {Mapping Function} {} isxdigit (@var{s}) hexadecimal digit -@end ftable +@end deftypefn
--- a/doc/interpreter/system.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/system.texi Wed Oct 30 23:00:41 1996 +0000 @@ -22,11 +22,11 @@ @node Timing Utilities, Filesystem Utilities, System Utilities, System Utilities @section Timing Utilities -@findex time - -The function @code{time} returns the current time as the number of -seconds since the epoch. The epoch is referenced to 00:00:00 CUT -(Coordinated Universal Time) 1 Jan 1970. +@deftypefn {Built-in Function} {} time () +Return the current time as the number of seconds since the epoch. The +epoch is referenced to 00:00:00 CUT (Coordinated Universal Time) 1 Jan +1970. +@end deftypefn Several of Octave's time functions a data structure for time that includes the following elements: @@ -67,31 +67,35 @@ Time zone. @end table -@findex localtime -@findex gmtime +@deftypefn {Built-in Function} {} mktime (@var{time_struct}) +Convert a time structure to the number of seconds since the epoch. +@end deftypefn -Given a value returned from time (or any nonnegative integer) the -function @code{localtime} returns a time structure corresponding to the -local time zone, and @code{gmtime} returns a time structure -corresponding to CUT. +@deftypefn {Built-in Function} {} localtime (@var{t}) +Given a value returned from time (or any nonnegative integer), +return a time structure corresponding to the local time zone. +@end deftypefn -@findex asctime -@findex ctime +@deftypefn {Built-in Function} {} gmtime (@var{t}) +Given a value returned from time (or any nonnegative integer), +return a time structure corresponding to CUT. +@end deftypefn -The function @code{asctime} formats a time structure the following -five-field format: Thu Mar 28 08:40:14 1996. The function -@code{ctime (time)} is equivalent to @code{asctime (localtime (time))}. - -@findex strftime +@deftypefn {Function File} {} asctime (@var{time_struct}) +Convert a time structure to a string using the following five-field +format: Thu Mar 28 08:40:14 1996. The function @code{ctime (time)} is +equivalent to @code{asctime (localtime (time))}. +@end deftypefn -The function @code{strftime} can be used to format a time structure in a -very flexible way using @samp{%} substitutions similar to those in printf. -Except where noted, substituted fields have a fixed size; numeric fields -are padded if necessary. Padding is with zeros by default; for fields -that display a single number, padding can be changed or inhibited by -following the @samp{%} with one of the modifiers described below. Unknown -field specifiers are copied as normal characters. All other characters -are copied to the output without change. +@deftypefn {Built-in Function} {} strftime (@var{time_struct}) +Format a time structure in a flexible way using @samp{%} substitutions +similar to those in @code{printf}. Except where noted, substituted +fields have a fixed size; numeric fields are padded if necessary. +Padding is with zeros by default; for fields that display a single +number, padding can be changed or inhibited by following the @samp{%} +with one of the modifiers described below. Unknown field specifiers are +copied as normal characters. All other characters are copied to the +output without change. Octave's @code{strftime} function supports a superset of the ANSI C field specifiers. @@ -223,12 +227,11 @@ @item %Y Year (1970-). @end table - -@findex clock +@end deftypefn -The function @code{clock} returns a vector containing the current year, -month (1-12), day (1-31), hour (0-23), minute (0-59) and second (0-61). -For example, +@deftypefn {Function File} {} clock () +Return a vector containing the current year, month (1-12), day (1-31), +hour (0-23), minute (0-59) and second (0-61). For example, @example octave:13> clock @@ -239,24 +242,21 @@ The function clock is more accurate on systems that have the @code{gettimeofday} function. - -@findex date +@end deftypefn -To get the date as a character string in the form DD-MMM-YY, use -the command @code{date}. For example, +@deftypefn {Function File} {} date () +Returns the date as a character string in the form DD-MMM-YY. For +example, @example octave:13> date ans = 20-Aug-93 @end example +@end deftypefn -@findex tic -@findex toc -@findex etime - -Octave also has functions for computing time intervals and CPU time -used. The functions @code{tic} and @code{toc} can be used to set and -check a wall-clock timer. For example, +@deftypefn {Function File} {} tic () +@deftypefnx {Function File} {} toc () +These functions set and check a wall-clock timer. For example, @example tic (); @@ -267,10 +267,11 @@ @noindent will set the variable @code{elapsed_time} to the number of seconds since the most recent call to the function @code{tic}. +@end deftypefn -The function @code{etime} provides another way to get elapsed wall-clock -time by returning the difference (in seconds) between two time values -returned from @code{clock}. For example: +@deftypefn {Function File} {} etime (@var{t1}, @var{t2}) +Return the difference (in seconds) between two time values returned from +@code{clock}. For example: @example t0 = clock (); @@ -281,38 +282,27 @@ @noindent will set the variable @code{elapsed_time} to the number of seconds since the variable @code{t0} was set. - -@findex cputime - -The function @code{cputime} allows you to obtain information about the -amount of CPU time your Octave session is using. For example, +@end deftypefn -@example -[total, user, system] = cputime (); -@end example - -@noindent -returns the CPU time used by your Octave session. The first output is +@deftypefn {Built-in Function} {[@var{total}, @var{user}, @var{system}] =} cputime (); +Return the CPU time used by your Octave session. The first output is the total time spent executing your process and is equal to the sum of second and third outputs, which are the number of CPU seconds spent executing in user mode and the number of CPU seconds spent executing in system mode, respectively. If your system does not have a way to report CPU time usage, @code{cputime} returns 0 for each of its output values. - -@findex is_leap_year +@end deftypefn -Finally, Octave's function @code{is_leap_year} returns 1 if the given -year is a leap year and 0 otherwise. If no arguments are provided, -@code{is_leap_year} will use the current year. For example, +@deftypefn {Function File} {} is_leap_year (@var{year}) +Return 1 if the given year is a leap year and 0 otherwise. If no +arguments are provided, @code{is_leap_year} will use the current year. +For example, @example octave:13> is_leap_year (2000) ans = 1 @end example - -@noindent -Contrary to what many people who post misinformation to Usenet -apparently believe, Octave knows that the year 2000 will be a leap year. +@end deftypefn @node Filesystem Utilities, Interacting with the OS, Timing Utilities, System Utilities @section Filesystem Utilities @@ -321,78 +311,135 @@ creating, deleting, and reading directories, and for getting information about the status of files. -@ftable @code -@item rename (@var{from}, @var{to}) +@deftypefn {Built-in Function} {} rename (@var{from}, @var{to}) Rename a file. +@end deftypefn -@item unlink (@var{file}) +@deftypefn {Built-in Function} {} unlink (@var{file}) Delete a file. +@end deftypefn -@item readdir (@var{dir}) +@deftypefn {Built-in Function} {} readdir (@var{dir}) Returns names of files in the directory @var{dir} as an array of strings. - -@item mkdir (@var{dir}) -Create a directory +@end deftypefn -@item rmdir (@var{dir}) -Remove a directory. +@deftypefn {Built-in Function} {} mkdir (@var{dir}) +Create a directory +@end deftypefn -@item umask (@var{mask}) -Set permission mask for file creation. +@deftypefn {Built-in Function} {} rmdir (@var{dir}) +Remove a directory. +@end deftypefn + @c XXX FIXME XXX -- this needs to be explained, but I don't feel up to @c it just now... -@item stat (@var{file}) +@deftypefn {Built-in Function} {} umask (@var{mask}) +Set permission mask for file creation. +@end deftypefn + +@deftypefn {Built-in Function} {} stat (@var{file}) Get information about a file. If @var{file} is a symbolic link, @code{stat} returns information about the file that the symbolic link references. +@end deftypefn -@item lstat (@var{file}) +@deftypefn {Built-in Function} {} lstat (@var{file}) Get information about a symbolic link. If @var{file} is not a symbolic link, @code{lstat} is equivalent to @code{stat}. -@end ftable +@end deftypefn @node Interacting with the OS, System Information, Filesystem Utilities, System Utilities @section Interacting with the OS -@findex shell_cmd -@findex system +@deftypefn {Built-in Function} {} fork () +Create a copy of the current process. +@end deftypefn + +@deftypefn {Built-in Function} {} exec (@var{file}, @var{args}) +Replace current process with a new process. +@end deftypefn + +@deftypefn {Built-in Function} {fid =} dup2 (@var{old}, @var{new}) +Duplicate a file descriptor. +@end deftypefn + +@deftypefn {Built-in Function} {[@var{file_ids}, @var{status}] =} pipe () +Create an interprocess channel. +@end deftypefn + +@deftypefn {Built-in Function} {} fcntl (@var{fid}, @var{request}, @var{argument}) +Control open file descriptors. + +@vtable @code +@item F_DUPFD +@item F_GETFD +@item F_GETFL +@item F_SETFD +@item F_SETFL +@item O_APPEND +@item O_CREAT +@item O_EXCL +@item O_NONBLOCK +@item O_RDONLY +@item O_RDWR +@item O_TRUNC +@item O_WRONLY +@end vtable +@end deftypefn -You can execute any shell command using the function -@code{system (@var{cmd}, @var{flag})}. The second argument is optional. -If it is present, the output of the command is returned by -@code{system} as a string. If it is not supplied, any output from -the command is printed, with the standard output filtered through the -pager. For example, +@deftypefn {Built-in Function} {} getpgrp () +Return the process group id of the current process. +@end deftypefn + +@deftypefn {Built-in Function} {} getpid () +Return the process id of the current process. +@end deftypefn + +@deftypefn {Built-in Function} {} getppid () +Return the process id of the parent process. +@end deftypefn + +@deftypefn {Built-in Function} {} mkfifo +Create a FIFO special file. +@end deftypefn + +@deftypefn {Built-in Function} {} waitpid +Check the status of or wait for subprocesses. +@end deftypefn -@c XXX FIXME XXX -- perhaps there should be another possible value for -@c the second argument, to indicate that the command is to be run -@c interactively, with the standard input and output connected to -@c /dev/tty. +@deftypefn {Built-in Function} {} atexit (@var{fcn}) +Register function to be called when Octave exits. +@end deftypefn + +@deftypefn {Built-in Function} {} system (@var{string}, @var{return_output}, @var{type}) +Execute a shell command specified by @var{string}. The second argument is optional. +If @var{type} is @code{"async"}, the process is started in the +background and the process id of the child proces is returned +immediately. Otherwise, the process is started, and Octave waits until +it exits. If @var{type} argument is omitted, a value of @code{"sync"} +is assumed. + +If two input arguments are given (the actual value of +@var{return_output} is irrelevant) and the subprocess is started +synchronously, or if @var{system} is called with one input argument and +one or more output arguments, the output from the command is returned. +Otherwise, if the subprocess is executed synchronously, it's output is +sent to the standard output. To send the output of a command executed +with @var{system} through the pager, use a command like @example -users = system ("finger", 1) +disp (system (cmd, 1)); @end example @noindent -places the output of the command @code{finger} in the variable -@code{users}. - -If you want to execute a shell command and have it behave as if it were -typed directly from the shell prompt, you may need to specify extra -arguments for the command. For example, to get @code{bash} to behave as -an interactive shell, you can type +or @example -system ("bash -i >/dev/tty"); +printf ("%s\n", system (cmd, 1)); @end example -The first argument, @samp{-i}, tells @code{bash} to behave as an -interactive shell, and the redirection of the standard output stream -prevents any output produced by @code{bash} from being sent back to -Octave, where it would be buffered until Octave displays another prompt. - The @code{system} function can return two values. The first is any output from the command that was written to the standard output stream, and the second is the output status of the command. For example, @@ -404,14 +451,24 @@ @noindent will set the variable @code{output} to the string @samp{foo}, and the variable @code{status} to the integer @samp{2}. - -The name @code{shell_cmd} exists for compatibility with earlier versions -of Octave. +@end deftypefn -@findex getenv +@defvr {Built-in Variable} EXEC_PATH +The variable @code{EXEC_PATH} is a colon separated list of directories +to search when executing subprograms. Its initial value is taken from +the environment variable @code{OCTAVE_EXEC_PATH} (if it exists) or +@code{PATH}, but that value can be overridden by the the command line +argument @code{--exec-path PATH}, or by setting the value of +@code{EXEC_PATH} in a startup script. If the value of @code{EXEC_PATH} +begins (ends) with a colon, the directories +@code{OCTAVE_HOME/libexec/octave/VERSION/exec/ARCH} and +@code{OCTAVE_HOME/bin} are prepended (appended) to @code{EXEC_PATH} (if +you don't specify a value for @code{EXEC_PATH} explicitly, these special +directories are prepended to your shell path). +@end defvr -You can find the values of environment variables using the function -@code{getenv}. For example, +@deftypefn {Built-in Function} {} getenv (@var{var}) +Returns the value of the environment variable @var{var}. For example, @example getenv ("PATH") @@ -419,22 +476,20 @@ @noindent returns a string containing the value of your path. - -@findex putenv +@end deftypefn -The function @code{putenv (@var{var}, @var{value})} sets the value of -the environment variable @var{var} to @var{value}. +@deftypefn {Built-in Function} {} putenv (@var{var}, @var{value}) +Set the value of the environment variable @var{var} to @var{value}. +@end deftypefn -@findex clc -@findex home +@deftypefn {Built-in Function} {} clc () +@deftypefnx {Built-in Function} {} home () +Clear the terminal screen and move the cursor to the upper left corner. +@end deftypefn -The functions @code{clc}, and @code{home} clear your -terminal screen and move the cursor to the upper left corner. - -@findex cd - -You can change the current working directory using the @code{cd} -command. Tilde expansion is performed on the path. For example, +@deffn {Command} cd dir +@deffnx {Command} chdir dir +Change the current working directory to @var{dir}. For example, @example cd ~/octave @@ -444,20 +499,21 @@ Changes the current working directory to @file{~/octave}. If the directory does not exist, an error message is printed and the working directory is not changed. - -@findex chdir +@end deffn -The name @code{chdir} is an alias for @code{cd}. - -@findex pwd +@deftypefn {Built-in Function} {} pwd () +Returns the current working directory. +@end deftypefn -The command @code{pwd} prints the current working directory. +@defvr {Built-in Variable} PWD +The current working directory. The value of @code{PWD} is updated each +time the current working directory is changed with the @samp{cd} +command. +@end defvr -@findex dir -@findex ls - -The functions @code{dir} and @code{ls} list directory contents. For -example, +@deffn {Command} ls +@deffnx {Command} dir +List directory contents. For example, @example octave:13> ls -l @@ -469,39 +525,38 @@ The @code{dir} and @code{ls} commands are implemented by calling your system's directory listing command, so the available options may vary from system to system. +@end deffn @node System Information, Other Functions, Interacting with the OS, System Utilities @section System Information -@findex computer - -If possible, @code{computer} prints a string of the form -@var{cpu}-@var{vendor}-@var{os} that identifies the kind of computer -Octave is running on. For example, +@deftypefn {Built-in Function} {} computer () +Returns a string of the form @var{cpu}-@var{vendor}-@var{os} that +identifies the kind of computer Octave is running on. For example, @example octave:13> computer sparc-sun-sunos4.1.2 @end example - -@findex isieee +@end deftypefn -The function @code{isieee} returns 1 if your computer claims to conform -to the IEEE standard for floating point calculations. +@deftypefn {Built-in Function} {} isieee () +Return 1 if your computer claims to conform to the IEEE standard for +floating point calculations. +@end deftypefn -@findex version -The function @code{version} returns Octave's version number as a string. -This is also the value of the built-in variable @code{OCTAVE_VERSION}. -@xref{Built-in Variables}. - -@findex getrusage +@deftypefn {Built-in Function} {} version () +Returns Octave's version number as a string. This is also the value of +the built-in variable @code{OCTAVE_VERSION}. @xref{Built-in Variables}. +@end deftypefn -The function @code{getrusage} returns a structure containing a number of -statistics about the current Octave process. Not all fields are -available on all systems. If it is not possible to get CPU time -statistics, the CPU time slots are set to zero. Other missing data are -replaced by NaN. Here is a list of all the possible fields that can be -present in the structure returned by @code{getrusage}: +@deftypefn {Built-in Function} {} getrusage () +Return a structure containing a number of statistics about the current +Octave process. Not all fields are available on all systems. If it is +not possible to get CPU time statistics, the CPU time slots are set to +zero. Other missing data are replaced by NaN. Here is a list of all +the possible fields that can be present in the structure returned by +@code{getrusage}: @table @code @item @@ -555,23 +610,29 @@ A structure containing the user CPU time used. The structure has the elements @code{sec} (seconds) @code{usec} (microseconds). @end table +@end deftypefn @node Other Functions, , System Information, System Utilities @section Other Functions -@findex tilde_expand - -The function @code{tilde_expand (@var{string})} performs tilde expansion -on @var{string}. +@c XXX FIXME XXX -- need to define tilde expansion. + +@deftypefn {Built-in Function} {} tilde_expand (@var{string}) +Performs tilde expansion on @var{string}. +@end deftypefn -@findex pause - -The function @code{pause} allows you to suspend the execution of a -program. If invoked without any arguments, Octave waits until you type -a character. With a numeric argument, it pauses for the given number of -seconds. For example, the following statement prints a message and then -waits 5 seconds before clearing the screen. +@deftypefn {Built-in Function} {} pause (@var{seconds}) +Suspend the execution of the program. If invoked without any arguments, +Octave waits until you type a character. With a numeric argument, it +pauses for the given number of seconds. For example, the following +statement prints a message and then waits 5 seconds before clearing the +screen. @example -fprintf (stderr, "wait please...\n"), pause (5), clc +@group +fprintf (stderr, "wait please...\n"); +pause (5); +clc; +@end group @end example +@end deftypefn
--- a/doc/interpreter/var.texi Wed Oct 30 22:27:19 1996 +0000 +++ b/doc/interpreter/var.texi Wed Oct 30 23:00:41 1996 +0000 @@ -20,159 +20,18 @@ and @code{PWD}, that are set automatically and carry information from the internal workings of Octave to your program. -This chapter documents all the built-in variables of Octave. -Most of them are also documented in the chapters that describe functions -that use them, or are affected by their values. -@c XXX FIXME XXX -- this should eventually happen. +This chapter documents the built-in variables of Octave that don't seem +to belong anywhere else. Many more of Octave's built-in variables are +documented in the chapters that describe functions that use them, or are +affected by their values. @menu -* Predefined Constants:: -* User Preferences:: -* Other Built-in Variables:: +* Miscellaneous Built-in Variables:: * Summary of Preference Variables:: @end menu -@node Predefined Constants, User Preferences, Built-in Variables, Built-in Variables -@section Predefined Constants - -@vtable @code -@item I@r{,} i@r{,} J@r{,} j -A pure imaginary number, defined as -@iftex -@tex - $\sqrt{-1}$. -@end tex -@end iftex -@ifinfo - @code{sqrt (-1)}. -@end ifinfo -The @code{I} and @code{J} forms are true constants, and cannot be -modified. The @code{i} and @code{j} forms are like ordinary variables, -and may be used for other purposes. However, unlike other variables, -they once again assume their special predefined values if they are -cleared @xref{Miscellaneous Utilities}. - -@item Inf@r{,} inf -Infinity. This is the result of an operation like 1/0, or an operation -that results in a floating point overflow. - -@item NaN@r{,} nan -Not a number. This is the result of an operation like @samp{0/0}, or -@samp{Inf - Inf}, or any operation with a NaN. - -@item SEEK_SET -@itemx SEEK_CUR -@itemx SEEK_END -These variables may be used as the optional third argument for the -function @code{fseek}. - -@item argv -The command line arguments passed to Octave are available in this -variable. For example, if you invoked Octave using the command - -@example -octave --no-line-editing --silent -@end example - -@noindent -@code{argv} would be a string vector with the elements -@code{--no-line-editing} and @code{--silent}. The following code will -print the command line arguments: - -@example -for i = 1:nargin - printf ("argv(%d) = %s\n", i, argv(i,:)); -endfor -@end example - -@noindent -@xref{Index Expressions} for an explanation of how to properly index -arrays of strings and substrings in Octave. - -@item eps -The machine precision. More precisely, @code{eps} is the largest -relative spacing between any two adjacent numbers in the machine's -floating point system. This number is obviously system-dependent. On -machines that support 64 bit IEEE floating point arithmetic, @code{eps} -is approximately -@ifinfo - 2.2204e-16. -@end ifinfo -@iftex -@tex - $2.2204\times10^{-16}$. -@end tex -@end iftex - -@item nargin -The value of @code{nargin} is automatically set to the number of command -line arguments. It is also used in the context of user-defined -functions to indicate the number of arguments that were passed to the -function. If you need to know the number of command line arguments -inside a function, you must define a global variable and save the -initial value of nargin in the global variable. - -@item pi -The ratio of the circumference of a circle to its diameter. -Internally, @code{pi} is computed as @samp{4.0 * atan (1.0)}. - -@item program_invocation_name -@itemx program_name -When Octave starts, the value of @code{program_invocation_name} is -automatically set to the name that was typed at the shell prompt to run -Octave, and the value of @code{program_name} is automatically set to the -final component of @code{program_invocation_name}. For example, if you -typed @file{/usr/local/bin/octave} to start Octave, -@code{program_invocation_name} would have the value -@file{/usr/local/bin/octave}, and @code{program_name} would have the -value @code{octave}. - -If executing a script from the command line (e.g., @code{octave foo.m} -or using an executable Octave script, the program name is set to the -name of the script. @xref{Executable Octave Programs} for an example of -how to create an executable Octave script. - -@ignore -@item read_only_constants -XXX FIXME XXX -- need description here. -@end ignore - -@item realmax -The largest floating point number that is representable. The actual -value is system-dependent. On machines that support 64 bit IEEE -floating point arithmetic, @code{realmax} is approximately -@ifinfo - 1.7977e+308 -@end ifinfo -@iftex -@tex - $1.7977\times10^{308}$. -@end tex -@end iftex - -@item realmin -The smallest floating point number that is representable. The actual -value is system-dependent. On machines that support 64 bit IEEE -floating point arithmetic, @code{realmin} is approximately -@ifinfo - 2.2251e-308 -@end ifinfo -@iftex -@tex - $2.2251\times10^{-308}$. -@end tex -@end iftex - -@item stdin -@itemx stdout -@itemx stderr -These variables are the file numbers corresponding to the standard -input, standard output, and standard error streams. These streams are -preconnected and available when Octave starts. -@end vtable - -@node User Preferences, Other Built-in Variables, Predefined Constants, Built-in Variables -@section User Preferences +@node Miscellaneous Built-in Variables, Summary of Preference Variables, Built-in Variables, Built-in Variables +@section Miscellaneous Built-in Variables This section describes the variables that you can use to customize Octave's behavior. @@ -182,81 +41,11 @@ Octave without having to remember and retype all the necessary commands. @xref{Startup Files} for more information. -XXX FIXME XXX -- say something here to explain @code{"true"}, -@code{"false"}, etc. - -@vtable @code -@item EDITOR -A string naming the editor to use with the @code{edit_history} command. -If the environment variable @code{EDITOR} is set when Octave starts, its -value is used as the default. Otherwise, @code{EDITOR} is set to -@code{"vi"}. - -@item EXEC_PATH -The variable @code{EXEC_PATH} is a colon separated list of directories -to search when executing subprograms. Its initial value is taken from -the environment variable @code{OCTAVE_EXEC_PATH} (if it exists) or -@code{PATH}, but that value can be overridden by the the command line -argument @code{--exec-path PATH}, or by setting the value of -@code{EXEC_PATH} in a startup script. If the value of @code{EXEC_PATH} -begins (ends) with a colon, the directories -@code{OCTAVE_HOME/libexec/octave/VERSION/exec/ARCH} and -@code{OCTAVE_HOME/bin} are prepended (appended) to @code{EXEC_PATH} (if -you don't specify a value for @code{EXEC_PATH} explicitly, these special -directories are prepended to your shell path). - -@item IMAGEPATH -A colon separated list of directories in which to search for image -files. @xref{Image Processing} for a description of Octave's image -processing capabilities. - -@item INFO_FILE -The variable @code{INFO_FILE} names the location of the Octave info file. -The default value is @code{"@value{OCTAVEHOME}/info/octave.info"}. +@defvr {Built-in Variable} OCTAVE_VERSION +The version number of Octave, as a string. +@end defvr -@item INFO_PROGRAM -The variable @code{INFO_PROGRAM} names the info program to run. Its -initial value is -@code{@value{OCTAVEHOME}/libexec/octave/VERSION/exec/ARCH/info}, but -that value can be overridden by the environment variable -@code{OCTAVE_INFO_PROGRAM}, or the command line argument -@code{--info-program NAME}, or by setting the value of -@code{INFO_PROGRAM} in a startup script. - -@item LOADPATH -A colon separated list of directories in which to search for function -files. @xref{Functions and Scripts}. The value of @code{LOADPATH} -overrides the environment variable @code{OCTAVE_PATH}. @xref{Installation}. - -@code{LOADPATH} is now handled in the same way as @TeX{} handles -@code{TEXINPUTS}. If the path starts with @samp{:}, the standard path -is prepended to the value of @code{LOADPATH}. If it ends with @samp{:} -the standard path is appended to the value of @code{LOADPATH}. - -In addition, if any path element ends in @samp{//}, that directory and -all subdirectories it contains are searched recursively for function -files. This can result in a slight delay as Octave caches the lists of -files found in the @code{LOADPATH} the first time Octave searches for a -function. After that, searching is usually much faster because Octave -normally only needs to search its internal cache for files. - -To improve performance of recursive directory searching, it is best for -each directory that is to be searched recursively to contain -@emph{either} additional subdirectories @emph{or} function files, but -not a mixture of both. - -@xref{Organization of Functions} for a description of the function file -directories that are distributed with Octave. - -@item OCTAVE_VERSION -The version number of Octave, as a string. - -@item PAGER -The default value is @code{"less"}, or, if @code{less} is not available -on your system, @code{"more"}. @xref{Installation}, and -@ref{Input and Output}. - -@item PS1 +@defvr {Built-in Variable} PS1 The primary prompt string. When executing interactively, Octave displays the primary prompt @code{PS1} when it is ready to read a command. Octave allows the prompt to be customized by inserting a @@ -308,330 +97,66 @@ @samp{boris} logged in on the host @samp{kremvax.kgb.su}. Note that two backslashes are required to enter a backslash into a string. @xref{String Constants}. +@end defvr -@item PS2 +@defvr {Built-in Variable} PS2 The secondary prompt string, which is printed when Octave is expecting additional input to complete a command. For example, when defining a function over several lines, Octave will print the value of @code{PS1} at the beginning of each line after the first. Octave allows @code{PS2} to be customized in the same way as @code{PS1}. The default value of @code{PS2} is @code{"> "}. +@end defvr -@item PS4 +@defvr {Built-in Variable} PS4 If Octave is invoked with the @code{--echo-input} option, the value of @code{PS4} is printed before each line of input that is echoed. Octave allows @code{PS4} to be customized in the same way as @code{PS1}. The default value of @code{PS4} is @code{"+ "}. @xref{Invoking Octave}, for a description of @code{--echo-input}. +@end defvr -@item automatic_replot -If this variable is @code{"true"}, Octave will automatically send a -@code{replot} command to @code{gnuplot} each time the plot changes. -Since this is fairly inefficient, the default value is @code{"false"}. +@defvr {Built-in Variable} ans +This variable holds the most recently computed result that was not +explicitly assigned to a variable. For example, after the expression -@item beep_on_error -If the value of @code{beep_on_error} is @code{"true"}, Octave will try -to ring your terminal's bell before printing an error message. The -default value is @code{"false"}. +@example +3^2 + 4^2 +@end example -@item completion_append_char +@noindent +is evaluated, the value of @code{ans} is @samp{25}. +@end defvr + +@defvr {Built-in Variable} completion_append_char The value of @code{completion_append_char} is used as the character to append to successful command-line completion attempts. The default value is @code{" "} (a single space). - -@item default_return_value -The value given to otherwise unitialized return values if -@code{define_all_return_values} is @code{"true"}. The default value is -@code{[]}. - -@item default_save_format -Specify the default format used by the @code{save} command. Options are -@code{"ascii"}, @code{"binary"}, @code{"mat-binary"}, or -@code{"float-binary"}. The default value is @code{ascii}. - -@item define_all_return_values -If the value of @code{define_all_return_values} is @code{"true"}, Octave -will substitute the value specified by @code{default_return_value} for -any return values that remain undefined when a function returns. The -default value is @code{"false"}. - -@item do_fortran_indexing -If the value of @code{do_fortran_indexing} is @code{"true"}, Octave allows -you to select elements of a two-dimensional matrix using a single index -by treating the matrix as a single vector created from the columns of -the matrix. The default value is @code{"false"}. - -@item 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 -@code{"true"}, Octave will ignore the empty matrices in the expression - -@example -a = [1, [], 3, [], 5] -@end example - -@noindent -and the variable @samp{a} will be assigned the value @samp{[ 1 3 5 ]}. - -The default value is @code{"warn"}. +@end defvr -@item gnuplot_binary -The name of the program invoked by the plot command. The default value -is @code{"gnuplot"}. @xref{Installation}. - -@item gnuplot_has_multiplot -If the value of this variable is nonzero, Octave assumes that your copy -of gnuplot has the multiplot support that is included in recent -3.6beta releases. It's initial value is determined by configure, but it -can be changed in your startup script or at the command line in case -configure got it wrong, or if you upgrade your gnuplot installation. - -@item history_file -This variable specifies the name of the file used to store command -history. The default value is @code{"~/.octave_hist"}, but may be -overridden by the environment variable @code{OCTAVE_HISTFILE}. - -@item history_size -This variable specifies how many entries to store in the history file. -The default value is @code{1024}, but may be overridden by the -environment variable @code{OCTAVE_HISTSIZE}. - -@item ignore_function_time_stamp -This variable can be used to prevent Octave from making the system call -@code{stat()} each time it looks up functions defined in function files. -If @code{ignore_function_time_stamp} to @code{"system"}, Octave will not -automatically recompile function files in subdirectories of -@code{@value{OCTAVEHOME}/lib/@value{VERSION}} if they have changed since -they were last compiled, but will recompile other function files in the -@code{LOADPATH} if they change. If set to @code{"all"}, Octave will not -recompile any function files unless their definitions are removed with -@code{clear}. For any other value of @code{ignore_function_time_stamp}, -Octave will always check to see if functions defined in function files -need to recompiled. The default value of -@code{ignore_function_time_stamp} is @code{"system"}. - -@item implicit_str_to_num_ok -If the value of @code{implicit_str_to_num_ok} is @code{"true"}, implicit -conversions of strings to their numeric ASCII equivalents are allowed. -Otherwise, an error message is printed and control is returned to the -top level. The default value is @code{"false"}. - -@item ok_to_lose_imaginary_part -If the value of @code{ok_to_lose_imaginary_part} is @code{"true"}, +@defvr {Built-in Variable} ok_to_lose_imaginary_part +If the value of @code{ok_to_lose_imaginary_part} is nonzero, implicit conversions of complex numbers to real numbers are allowed (for example, by fsolve). If the value is @code{"warn"}, the conversion is allowed, but a warning is printed. Otherwise, an error message is printed and control is returned to the top level. The default value is @code{"warn"}. - -@item output_max_field_width -This variable specifies the maximum width of a numeric output field. -The default value is 10. - -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}. - -@item output_precision -This variable specifies the minimum number of significant figures to -display for numeric output. The default value is 5. - -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}. - -@item page_screen_output -If the value of @code{page_screen_output} is @code{"true"}, all output -intended for the screen that is longer than one page is sent through a -pager. This allows you to view one screenful at a time. Some pagers -(such as @code{less}---see @ref{Installation}) are also capable of moving -backward on the output. The default value is @code{"true"}. -@xref{Input and Output}. - -You can choose the program to use as the pager by setting the variable -@code{PAGER}. - -@item prefer_column_vectors -If @code{prefer_column_vectors} is @code{"true"}, operations like - -@example -for i = 1:10 - a (i) = i; -endfor -@end example - -@noindent -(for @samp{a} previously undefined) produce column vectors. Otherwise, row -vectors are preferred. The default value is @code{"false"}. - -If a variable is already defined to be a vector (a matrix with a single -row or column), the original orientation is respected, regardless of the -value of @code{prefer_column_vectors}. +@end defvr -@item prefer_zero_one_indexing -If the value of @code{prefer_zero_one_indexing} is @code{"true"}, Octave -will perform zero-one style indexing when there is a conflict with the -normal indexing rules. @xref{Index Expressions}. For example, given a -matrix - -@example -a = [1, 2, 3, 4] -@end example - -@noindent -with @code{prefer_zero_one_indexing} is set to @code{"true"}, the -expression - -@example -a ([1, 1, 1, 1]) -@end example - -@noindent -results in the matrix @samp{[ 1 2 3 4 ]}. If the value of -@code{prefer_zero_one_indexing} set to @code{"false"}, the result would be -the matrix @samp{[ 1 1 1 1 ]}. - -In the first case, Octave is selecting each element corresponding to a -@samp{1} in the index vector. In the second, Octave is selecting the -first element multiple times. +@defvr {Built-in Variable} print_answer_id_name +If the value of @code{print_answer_id_name} is nonzero, variable +names are printed along with the result. Otherwise, only the result +values are printed. The default value is 1. +@end defvr -The default value for @code{prefer_zero_one_indexing} is @code{"false"}. - -@item print_answer_id_name -If the value of @code{print_answer_id_name} is @code{"true"}, variable -names are printed along with the result. Otherwise, only the result -values are printed. The default value is @code{"true"}. - -@item print_empty_dimensions -If the value of @code{print_empty_dimensions} is @code{"true"}, 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 - -@item propagate_empty_matrices -If the value of @code{propagate_empty_matrices} is @code{"true"}, +@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 @code{"true"}. +if they are given one as an argument. The default value is 1. @xref{Empty Matrices}. - -@item resize_on_range_error -If the value of @code{resize_on_range_error} is @code{"true"}, expressions -like - -@example -for i = 1:10 - a (i) = i; -endfor -@end example - -@noindent -(for @samp{a} previously undefined) result in the variable @samp{a} -being resized to be just large enough to hold the new value. Otherwise -uninitialized elements are set to zero. If the value of -@code{resize_on_range_error} is @code{"false"}, an error message is -printed and control is returned to the top level. The default value is -@code{"true"}. - -@item return_last_computed_value -If the value of @code{return_last_computed_value} is true, and a -function is defined without explicitly specifying a return value, the -function will return the value of the last expression. Otherwise, no -value will be returned. The default value is @code{"false"}. - -For example, the function - -@example -function f () - 2 + 2; -endfunction -@end example - -@noindent -will either return nothing, if @code{return_last_computed_value} is -@code{"false"}, or 4, if it is @code{"true"}. - -@item save_precision -This variable specifies the number of digits to keep when saving data -with the @code{save} command. The default value is 17. - -@item saving_history -If the value of @code{saving_history} is @code{"true"}, command entered -on the command line are saved in the file specified by the variable -@code{history_file}. - -@item silent_functions -If the value of @code{silent_functions} is @code{"true"}, internal output -from a function is suppressed. Otherwise, the results of expressions -within a function body that are not terminated with a semicolon will -have their values printed. The default value is @code{"false"}. +@end defvr -For example, if the function - -@example -function f () - 2 + 2 -endfunction -@end example - -@noindent -is executed, Octave will either print @samp{ans = 4} or nothing -depending on the value of @code{silent_functions}. - -@item 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 @code{"true"}, 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 -octave:13> rand (2, 9) -ans = - - Columns 1 through 7: - - 0.92205 0.72628 0.99841 0.62590 0.82422 0.77486 0.30258 - 0.15999 0.79484 0.75443 0.86995 0.91430 0.23980 0.64591 - - Columns 8 and 9: - - 0.08894 0.13266 - 0.28008 0.65575 -@end smallexample - -The default value of @code{split_long_rows} is @code{"true"}. - -@item struct_levels_to_print -This variable controls the depth of nested structures to print. The -default is 2. - -@item suppress_verbose_help_message -If the value of @code{suppress_verbose_help_message} is @code{"true"}, -Octave will not add additional help information to the end of the output -from the @code{help} command and usage messages for built-in commands. - -@item treat_neg_dim_as_zero -If the value of @code{treat_neg_dim_as_zero} is @code{"true"}, expressions +@defvr {Built-in Variable} treat_neg_dim_as_zero +If the value of @code{treat_neg_dim_as_zero} is nonzero, expressions like @example @@ -641,206 +166,10 @@ @noindent produce an empty matrix (i.e., row and column dimensions are zero). Otherwise, an error message is printed and control is returned to the -top level. The default value is @code{"false"}. - -@item warn_assign_as_truth_value -If the value of @code{warn_assign_as_truth_value} is @code{"true"}, a -warning is issued for statements like - -@example -if (s = t) - ... -@end example - -@noindent -since such statements are not common, and it is likely that the intent -was to write - -@example -if (s == t) - ... -@end example - -@noindent -instead. - -There are times when it is useful to write code that contains -assignments within the condition of a @code{while} or @code{if} -statement. For example, statements like - -@example -while (c = getc()) - ... -@end example - -@noindent -are common in C programming. - -It is possible to avoid all warnings about such statements by setting -@code{warn_assign_as_truth_value} to @code{"false"}, but that may also -let real errors like - -@example -if (x = 1) # intended to test (x == 1)! - ... -@end example - -@noindent -slip by. - -In such cases, it is possible suppress errors for specific statements by -writing them with an extra set of parentheses. For example, writing the -previous example as - -@example -while ((c = getc())) - ... -@end example - -@noindent -will prevent the warning from being printed for this statement, while -allowing Octave to warn about other assignments used in conditional -contexts. - -The default value of @code{warn_assign_as_truth_value} is @code{"true"}. - -@item warn_comma_in_global_decl -If the value of @code{warn_comma_in_global_decl} is @code{"true"}, a -warning is issued for statements like - -@example -global a = 1, b -@end example - -@noindent -which makes the variables @samp{a} and @samp{b} global and assigns the -value 1 to the variable @samp{a}, because in this context, the comma is -not interpreted as a statement separator. - -The default value of @code{warn_comma_in_global_decl} is @code{"true"}. - -@item warn_divide_by_zero -If the value of @code{warn_divide_by_zero} is @code{"true"}, a warning -is issued when Octave encounters a division by zero. If the value is -@code{"false"}, the warning is omitted. The default value is -@code{"true"}. - -@item warn_function_name_clash -If the value of @code{warn_function_name_clash} is @code{"true"}, a -warning is issued when Octave finds that the name of a function defined -in a function file differs from the name of the file. If the value is -@code{"false"}, the warning is omitted. The default value is -@code{"true"}. - -@item warn_missing_semicolon -If the value of this variable is nonzero, Octave will warn when -statements in function definitions don't end in semicolons. The default -value is 0. +top level. The default value is 0. +@end defvr -@item whitespace_in_literal_matrix -This variable allows some control over how Octave decides to convert -spaces to commas and semicolons in matrix expressions like -@samp{[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 @samp{[1 2]} will result in an error -instead of being treated the same as @samp{[1, 2]}, and the expression - -@example -[ 1, 2, - 3, 4 ] -@end example - -@noindent -will result in the vector [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 vtable - -@node Other Built-in Variables, Summary of Preference Variables, User Preferences, Built-in Variables -@section Other Built-in Variables - -In addition to predefined constants and preference variables, there are -two other special built-in variables whose values are automatically -updated. - -@vtable @code -@item ans -This variable holds the most recently computed result that was not -explicitly assigned to a variable. For example, after the expression - -@example -3^2 + 4^2 -@end example - -@noindent -is evaluated, the value of @code{ans} is @samp{25}. - -@item PWD -The current working directory. The value of @code{PWD} is updated each -time the current working directory is changed with the @samp{cd} -command. @xref{System Utilities}. -@end vtable - -@node Summary of Preference Variables, , Other Built-in Variables, Built-in Variables +@node Summary of Preference Variables, , Miscellaneous Built-in Variables, Built-in Variables @section Summary of Preference Variables Here is a summary of all of Octave's preference variables and their
--- a/src/ChangeLog Wed Oct 30 22:27:19 1996 +0000 +++ b/src/ChangeLog Wed Oct 30 23:00:41 1996 +0000 @@ -1,5 +1,12 @@ Wed Oct 30 01:06:19 1996 John W. Eaton <jwe@bevo.che.wisc.edu> + * ov-range.cc (octave_range::convert_to_str): New function. + + * ov-str-mat.h (octave_char_matrix_str::char_matrix_value): + Delete function. Already handled by octave_char_matrix class. + + * ov-ch-mat.h (octave_char_matrix::convert_to_str): New function. + * pager.cc (Fmore): Set page_screen_output to 1.0 or 0.0, not "true" or "false".
--- a/src/ov-ch-mat.h Wed Oct 30 22:27:19 1996 +0000 +++ b/src/ov-ch-mat.h Wed Oct 30 23:00:41 1996 +0000 @@ -111,6 +111,9 @@ charMatrix char_matrix_value (bool = false) const { return matrix; } + octave_value convert_to_str (void) const + { return octave_value (matrix); } + void print (ostream& os); int type_id (void) const { return t_id; }
--- a/src/ov-range.cc Wed Oct 30 22:27:19 1996 +0000 +++ b/src/ov-range.cc Wed Oct 30 23:00:41 1996 +0000 @@ -171,17 +171,24 @@ octave_value octave_range::transpose (void) const { - Matrix tmp (matrix_value ()); + Matrix tmp (range.matrix_value ()); return tmp.transpose (); } octave_value octave_range::hermitian (void) const { - Matrix tmp (matrix_value ()); + Matrix tmp (range.matrix_value ()); return tmp.transpose (); } +octave_value +octave_range::convert_to_str (void) const +{ + octave_value tmp (range.matrix_value ()); + return tmp.convert_to_str (); +} + void octave_range::print (ostream& os) {
--- a/src/ov-range.h Wed Oct 30 22:27:19 1996 +0000 +++ b/src/ov-range.h Wed Oct 30 23:00:41 1996 +0000 @@ -139,6 +139,8 @@ octave_value hermitian (void) const; + octave_value convert_to_str (void) const; + void print (ostream& os); int type_id (void) const { return t_id; }
--- a/src/ov-str-mat.h Wed Oct 30 22:27:19 1996 +0000 +++ b/src/ov-str-mat.h Wed Oct 30 23:00:41 1996 +0000 @@ -102,8 +102,6 @@ Matrix matrix_value (bool = false) const; - charMatrix char_matrix_value (bool = false) const { return matrix; } - charMatrix all_strings (void) const; string string_value (void) const;