This is octave.info, produced by makeinfo version 5.2 from octave.texi. START-INFO-DIR-ENTRY * Octave: (octave). Interactive language for numerical computations. END-INFO-DIR-ENTRY Copyright (C) 1996-2013 John W. Eaton. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.  File: octave.info, Node: Expressions, Next: Evaluation, Prev: Variables, Up: Top 8 Expressions ************* Expressions are the basic building block of statements in Octave. An expression evaluates to a value, which you can print, test, store in a variable, pass to a function, or assign a new value to a variable with an assignment operator. An expression can serve as a statement on its own. Most other kinds of statements contain one or more expressions which specify data to be operated on. As in other languages, expressions in Octave include variables, array references, constants, and function calls, as well as combinations of these with various operators. * Menu: * Index Expressions:: * Calling Functions:: * Arithmetic Ops:: * Comparison Ops:: * Boolean Expressions:: * Assignment Ops:: * Increment Ops:: * Operator Precedence::  File: octave.info, Node: Index Expressions, Next: Calling Functions, Up: Expressions 8.1 Index Expressions ===================== An "index expression" allows you to reference or extract selected elements of a matrix or vector. Indices may be scalars, vectors, ranges, or the special operator ':', which may be used to select entire rows or columns. Vectors are indexed using a single index expression. Matrices (2-D) and higher multi-dimensional arrays are indexed using either one index or N indices where N is the dimension of the array. When using a single index expression to index 2-D or higher data the elements of the array are taken in column-first order (like Fortran). The output from indexing assumes the dimensions of the index expression. For example: a(2) # result is a scalar a(1:2) # result is a row vector a([1; 2]) # result is a column vector As a special case, when a colon is used as a single index, the output is a column vector containing all the elements of the vector or matrix. For example: a(:) # result is a column vector a(:)' # result is a row vector The above two code idioms are often used in place of 'reshape' when a simple vector, rather than an arbitrarily sized array, is needed. Given the matrix a = [1, 2; 3, 4] all of the following expressions are equivalent and select the first row of the matrix. a(1, [1, 2]) # row 1, columns 1 and 2 a(1, 1:2) # row 1, columns in range 1-2 a(1, :) # row 1, all columns In index expressions the keyword 'end' automatically refers to the last entry for a particular dimension. This magic index can also be used in ranges and typically eliminates the needs to call 'size' or 'length' to gather array bounds before indexing. For example: a = [1, 2, 3, 4]; a(1:end/2) # first half of a => [1, 2] a(end + 1) = 5; # append element a(end) = []; # delete element a(1:2:end) # odd elements of a => [1, 3] a(2:2:end) # even elements of a => [2, 4] a(end:-1:1) # reversal of a => [4, 3, 2 , 1] * Menu: * Advanced Indexing::  File: octave.info, Node: Advanced Indexing, Up: Index Expressions 8.1.1 Advanced Indexing ----------------------- An array with 'n' dimensions can be indexed using 'm' indices. More generally, the set of index tuples determining the result is formed by the Cartesian product of the index vectors (or ranges or scalars). For the ordinary and most common case, 'm == n', and each index corresponds to its respective dimension. If 'm < n' and every index is less than the size of the array in the i^{th} dimension, 'm(i) < n(i)', then the index expression is padded with trailing singleton dimensions ('[ones (m-n, 1)]'). If 'm < n' but one of the indices 'm(i)' is outside the size of the current array, then the last 'n-m+1' dimensions are folded into a single dimension with an extent equal to the product of extents of the original dimensions. This is easiest to understand with an example. a = reshape (1:8, 2, 2, 2) # Create 3-D array a = ans(:,:,1) = 1 3 2 4 ans(:,:,2) = 5 7 6 8 a(2,1,2); # Case (m == n): ans = 6 a(2,1); # Case (m < n), idx within array: # equivalent to a(2,1,1), ans = 2 a(2,4); # Case (m < n), idx outside array: # Dimension 2 & 3 folded into new dimension of size 2x2 = 4 # Select 2nd row, 4th element of [2, 4, 6, 8], ans = 8 One advanced use of indexing is to create arrays filled with a single value. This can be done by using an index of ones on a scalar value. The result is an object with the dimensions of the index expression and every element equal to the original scalar. For example, the following statements a = 13; a(ones (1, 4)) produce a vector whose four elements are all equal to 13. Similarly, by indexing a scalar with two vectors of ones it is possible to create a matrix. The following statements a = 13; a(ones (1, 2), ones (1, 3)) create a 2x3 matrix with all elements equal to 13. The last example could also be written as 13(ones (2, 3)) It is more efficient to use indexing rather than the code construction 'scalar * ones (N, M, ...)' because it avoids the unnecessary multiplication operation. Moreover, multiplication may not be defined for the object to be replicated whereas indexing an array is always defined. The following code shows how to create a 2x3 cell array from a base unit which is not itself a scalar. {"Hello"}(ones (2, 3)) It should be, noted that 'ones (1, n)' (a row vector of ones) results in a range (with zero increment). A range is stored internally as a starting value, increment, end value, and total number of values; hence, it is more efficient for storage than a vector or matrix of ones whenever the number of elements is greater than 4. In particular, when 'r' is a row vector, the expressions r(ones (1, n), :) r(ones (n, 1), :) will produce identical results, but the first one will be significantly faster, at least for 'r' and 'n' large enough. In the first case the index is held in compressed form as a range which allows Octave to choose a more efficient algorithm to handle the expression. A general recommendation, for a user unaware of these subtleties, is to use the function 'repmat' for replicating smaller arrays into bigger ones. A second use of indexing is to speed up code. Indexing is a fast operation and judicious use of it can reduce the requirement for looping over individual array elements which is a slow operation. Consider the following example which creates a 10-element row vector a containing the values a(i) = sqrt (i). for i = 1:10 a(i) = sqrt (i); endfor It is quite inefficient to create a vector using a loop like this. In this case, it would have been much more efficient to use the expression a = sqrt (1:10); which avoids the loop entirely. In cases where a loop cannot be avoided, or a number of values must be combined to form a larger matrix, it is generally faster to set the size of the matrix first (pre-allocate storage), and then insert elements using indexing commands. For example, given a matrix 'a', [nr, nc] = size (a); x = zeros (nr, n * nc); for i = 1:n x(:,(i-1)*nc+1:i*nc) = a; endfor is considerably faster than x = a; for i = 1:n-1 x = [x, a]; endfor because Octave does not have to repeatedly resize the intermediate result. -- Function File: IND = sub2ind (DIMS, I, J) -- Function File: IND = sub2ind (DIMS, S1, S2, ..., SN) Convert subscripts to a linear index. The following example shows how to convert the two-dimensional index '(2,3)' of a 3-by-3 matrix to a linear index. The matrix is linearly indexed moving from one column to next, filling up all rows in each column. linear_index = sub2ind ([3, 3], 2, 3) => 8 See also: *note ind2sub: XREFind2sub. -- Function File: [S1, S2, ..., SN] = ind2sub (DIMS, IND) Convert a linear index to subscripts. The following example shows how to convert the linear index '8' in a 3-by-3 matrix into a subscript. The matrix is linearly indexed moving from one column to next, filling up all rows in each column. [r, c] = ind2sub ([3, 3], 8) => r = 2 => c = 3 See also: *note sub2ind: XREFsub2ind. -- Built-in Function: isindex (IND) -- Built-in Function: isindex (IND, N) Return true if IND is a valid index. Valid indices are either positive integers (although possibly of real data type), or logical arrays. If present, N specifies the maximum extent of the dimension to be indexed. When possible the internal result is cached so that subsequent indexing using IND will not perform the check again. Implementation Note: Strings are first converted to double values before the checks for valid indices are made. Unless a string contains the NULL character "\0", it will always be a valid index. -- Built-in Function: VAL = allow_noninteger_range_as_index () -- Built-in Function: OLD_VAL = allow_noninteger_range_as_index (NEW_VAL) -- Built-in Function: allow_noninteger_range_as_index (NEW_VAL, "local") Query or set the internal variable that controls whether non-integer ranges are allowed as indices. This might be useful for MATLAB compatibility; however, it is still not entirely compatible because MATLAB treats the range expression differently in different contexts. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.  File: octave.info, Node: Calling Functions, Next: Arithmetic Ops, Prev: Index Expressions, Up: Expressions 8.2 Calling Functions ===================== A "function" is a name for a particular calculation. Because it has a name, you can ask for it by name at any point in the program. For example, the function 'sqrt' computes the square root of a number. A fixed set of functions are "built-in", which means they are available in every Octave program. The 'sqrt' function is one of these. In addition, you can define your own functions. *Note Functions and Scripts::, for information about how to do this. The way to use a function is with a "function call" expression, which consists of the function name followed by a list of "arguments" in parentheses. The arguments are expressions which give the raw materials for the calculation that the function will do. When there is more than one argument, they are separated by commas. If there are no arguments, you can omit the parentheses, but it is a good idea to include them anyway, to clearly indicate that a function call was intended. Here are some examples: sqrt (x^2 + y^2) # One argument ones (n, m) # Two arguments rand () # No arguments Each function expects a particular number of arguments. For example, the 'sqrt' function must be called with a single argument, the number to take the square root of: sqrt (ARGUMENT) Some of the built-in functions take a variable number of arguments, depending on the particular usage, and their behavior is different depending on the number of arguments supplied. Like every other expression, the function call has a value, which is computed by the function based on the arguments you give it. In this example, the value of 'sqrt (ARGUMENT)' is the square root of the argument. A function can also have side effects, such as assigning the values of certain variables or doing input or output operations. Unlike most languages, functions in Octave may return multiple values. For example, the following statement [u, s, v] = svd (a) computes the singular value decomposition of the matrix 'a' and assigns the three result matrices to 'u', 's', and 'v'. The left side of a multiple assignment expression is itself a list of expressions, and is allowed to be a list of variable names or index expressions. See also *note Index Expressions::, and *note Assignment Ops::. * Menu: * Call by Value:: * Recursion::  File: octave.info, Node: Call by Value, Next: Recursion, Up: Calling Functions 8.2.1 Call by Value ------------------- In Octave, unlike Fortran, function arguments are passed by value, which means that each argument in a function call is evaluated and assigned to a temporary location in memory before being passed to the function. There is currently no way to specify that a function parameter should be passed by reference instead of by value. This means that it is impossible to directly alter the value of a function parameter in the calling function. It can only change the local copy within the function body. For example, the function function f (x, n) while (n-- > 0) disp (x); endwhile endfunction displays the value of the first argument N times. In this function, the variable N is used as a temporary variable without having to worry that its value might also change in the calling function. Call by value is also useful because it is always possible to pass constants for any function parameter without first having to determine that the function will not attempt to modify the parameter. The caller may use a variable as the expression for the argument, but the called function does not know this: it only knows what value the argument had. For example, given a function called as foo = "bar"; fcn (foo) you should not think of the argument as being "the variable 'foo'." Instead, think of the argument as the string value, "bar". Even though Octave uses pass-by-value semantics for function arguments, values are not copied unnecessarily. For example, x = rand (1000); f (x); does not actually force two 1000 by 1000 element matrices to exist _unless_ the function 'f' modifies the value of its argument. Then Octave must create a copy to avoid changing the value outside the scope of the function 'f', or attempting (and probably failing!) to modify the value of a constant or the value of a temporary result.  File: octave.info, Node: Recursion, Prev: Call by Value, Up: Calling Functions 8.2.2 Recursion --------------- With some restrictions(1), recursive function calls are allowed. A "recursive function" is one which calls itself, either directly or indirectly. For example, here is an inefficient(2) way to compute the factorial of a given integer: function retval = fact (n) if (n > 0) retval = n * fact (n-1); else retval = 1; endif endfunction This function is recursive because it calls itself directly. It eventually terminates because each time it calls itself, it uses an argument that is one less than was used for the previous call. Once the argument is no longer greater than zero, it does not call itself, and the recursion ends. The built-in variable 'max_recursion_depth' specifies a limit to the recursion depth and prevents Octave from recursing infinitely. -- Built-in Function: VAL = max_recursion_depth () -- Built-in Function: OLD_VAL = max_recursion_depth (NEW_VAL) -- Built-in Function: max_recursion_depth (NEW_VAL, "local") Query or set the internal limit on the number of times a function may be called recursively. If the limit is exceeded, an error message is printed and control returns to the top level. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. ---------- Footnotes ---------- (1) Some of Octave's functions are implemented in terms of functions that cannot be called recursively. For example, the ODE solver 'lsode' is ultimately implemented in a Fortran subroutine that cannot be called recursively, so 'lsode' should not be called either directly or indirectly from within the user-supplied function that 'lsode' requires. Doing so will result in an error. (2) It would be much better to use 'prod (1:n)', or 'gamma (n+1)' instead, after first checking to ensure that the value 'n' is actually a positive integer.  File: octave.info, Node: Arithmetic Ops, Next: Comparison Ops, Prev: Calling Functions, Up: Expressions 8.3 Arithmetic Operators ======================== The following arithmetic operators are available, and work on scalars and matrices. The element-by-element operators and functions broadcast (*note Broadcasting::). X + Y Addition. If both operands are matrices, the number of rows and columns must both agree, or they must be broadcastable to the same shape. X .+ Y Element-by-element addition. This operator is equivalent to '+'. X - Y Subtraction. If both operands are matrices, the number of rows and columns of both must agree, or they must be broadcastable to the same shape. X .- Y Element-by-element subtraction. This operator is equivalent to '-'. X * Y Matrix multiplication. The number of columns of X must agree with the number of rows of Y, or they must be broadcastable to the same shape. X .* Y Element-by-element multiplication. If both operands are matrices, the number of rows and columns must both agree, or they must be broadcastable to the same shape. X / Y Right division. This is conceptually equivalent to the expression (inverse (y') * x')' but it is computed without forming the inverse of Y'. If the system is not square, or if the coefficient matrix is singular, a minimum norm solution is computed. X ./ Y Element-by-element right division. X \ Y Left division. This is conceptually equivalent to the expression inverse (x) * y but it is computed without forming the inverse of X. If the system is not square, or if the coefficient matrix is singular, a minimum norm solution is computed. X .\ Y Element-by-element left division. Each element of Y is divided by each corresponding element of X. X ^ Y X ** Y Power operator. If X and Y are both scalars, this operator returns X raised to the power Y. If X is a scalar and Y is a square matrix, the result is computed using an eigenvalue expansion. If X is a square matrix, the result is computed by repeated multiplication if Y is an integer, and by an eigenvalue expansion if Y is not an integer. An error results if both X and Y are matrices. The implementation of this operator needs to be improved. X .^ Y X .** Y Element-by-element power operator. If both operands are matrices, the number of rows and columns must both agree, or they must be broadcastable to the same shape. If several complex results are possible, the one with smallest non-negative argument (angle) is taken. This rule may return a complex root even when a real root is also possible. Use 'realpow', 'realsqrt', 'cbrt', or 'nthroot' if a real result is preferred. -X Negation. +X Unary plus. This operator has no effect on the operand. X' Complex conjugate transpose. For real arguments, this operator is the same as the transpose operator. For complex arguments, this operator is equivalent to the expression conj (x.') X.' Transpose. Note that because Octave's element-by-element operators begin with a '.', there is a possible ambiguity for statements like 1./m because the period could be interpreted either as part of the constant or as part of the operator. To resolve this conflict, Octave treats the expression as if you had typed (1) ./ m and not (1.) / m Although this is inconsistent with the normal behavior of Octave's lexer, which usually prefers to break the input into tokens by preferring the longest possible match at any given point, it is more useful in this case. -- Built-in Function: ctranspose (X) Return the complex conjugate transpose of X. This function and x' are equivalent. See also: *note transpose: XREFtranspose. -- Built-in Function: ldivide (X, Y) Return the element-by-element left division of X and Y. This function and x .\ y are equivalent. See also: *note rdivide: XREFrdivide, *note mldivide: XREFmldivide, *note times: XREFtimes, *note plus: XREFplus. -- Built-in Function: minus (X, Y) This function and x - y are equivalent. See also: *note plus: XREFplus, *note uminus: XREFuminus. -- Built-in Function: mldivide (X, Y) Return the matrix left division of X and Y. This function and x \ y are equivalent. See also: *note mrdivide: XREFmrdivide, *note ldivide: XREFldivide, *note rdivide: XREFrdivide. -- Built-in Function: mpower (X, Y) Return the matrix power operation of X raised to the Y power. This function and x ^ y are equivalent. See also: *note power: XREFpower, *note mtimes: XREFmtimes, *note plus: XREFplus, *note minus: XREFminus. -- Built-in Function: mrdivide (X, Y) Return the matrix right division of X and Y. This function and x / y are equivalent. See also: *note mldivide: XREFmldivide, *note rdivide: XREFrdivide, *note plus: XREFplus, *note minus: XREFminus. -- Built-in Function: mtimes (X, Y) -- Built-in Function: mtimes (X1, X2, ...) Return the matrix multiplication product of inputs. This function and x * y are equivalent. If more arguments are given, the multiplication is applied cumulatively from left to right: (...((x1 * x2) * x3) * ...) At least one argument is required. See also: *note times: XREFtimes, *note plus: XREFplus, *note minus: XREFminus, *note rdivide: XREFrdivide, *note mrdivide: XREFmrdivide, *note mldivide: XREFmldivide, *note mpower: XREFmpower. -- Built-in Function: plus (X, Y) -- Built-in Function: plus (X1, X2, ...) This function and x + y are equivalent. If more arguments are given, the summation is applied cumulatively from left to right: (...((x1 + x2) + x3) + ...) At least one argument is required. See also: *note minus: XREFminus, *note uplus: XREFuplus. -- Built-in Function: power (X, Y) Return the element-by-element operation of X raised to the Y power. This function and x .^ y are equivalent. If several complex results are possible, returns the one with smallest non-negative argument (angle). Use 'realpow', 'realsqrt', 'cbrt', or 'nthroot' if a real result is preferred. See also: *note mpower: XREFmpower, *note realpow: XREFrealpow, *note realsqrt: XREFrealsqrt, *note cbrt: XREFcbrt, *note nthroot: XREFnthroot. -- Built-in Function: rdivide (X, Y) Return the element-by-element right division of X and Y. This function and x ./ y are equivalent. See also: *note ldivide: XREFldivide, *note mrdivide: XREFmrdivide, *note times: XREFtimes, *note plus: XREFplus. -- Built-in Function: times (X, Y) -- Built-in Function: times (X1, X2, ...) Return the element-by-element multiplication product of inputs. This function and x .* y are equivalent. If more arguments are given, the multiplication is applied cumulatively from left to right: (...((x1 .* x2) .* x3) .* ...) At least one argument is required. See also: *note mtimes: XREFmtimes, *note rdivide: XREFrdivide. -- Built-in Function: transpose (X) Return the transpose of X. This function and x.' are equivalent. See also: *note ctranspose: XREFctranspose. -- Built-in Function: uminus (X) This function and - x are equivalent. See also: *note uplus: XREFuplus, *note minus: XREFminus. -- Built-in Function: uplus (X) This function and + x are equivalent. See also: *note uminus: XREFuminus, *note plus: XREFplus, *note minus: XREFminus.  File: octave.info, Node: Comparison Ops, Next: Boolean Expressions, Prev: Arithmetic Ops, Up: Expressions 8.4 Comparison Operators ======================== "Comparison operators" compare numeric values for relationships such as equality. They are written using _relational operators_. All of Octave's comparison operators return a value of 1 if the comparison is true, or 0 if it is false. For matrix values, they all work on an element-by-element basis. Broadcasting rules apply. *Note Broadcasting::. For example: [1, 2; 3, 4] == [1, 3; 2, 4] => 1 0 0 1 According to broadcasting rules, if one operand is a scalar and the other is a matrix, the scalar is compared to each element of the matrix in turn, and the result is the same size as the matrix. 'X < Y' True if X is less than Y. 'X <= Y' True if X is less than or equal to Y. 'X == Y' True if X is equal to Y. 'X >= Y' True if X is greater than or equal to Y. 'X > Y' True if X is greater than Y. 'X != Y' 'X ~= Y' True if X is not equal to Y. For complex numbers, the following ordering is defined: Z1 < Z2 if and only if abs (Z1) < abs (Z2) || (abs (Z1) == abs (Z2) && arg (Z1) < arg (Z2)) This is consistent with the ordering used by "max", "min" and "sort", but is not consistent with MATLAB, which only compares the real parts. String comparisons may also be performed with the 'strcmp' function, not with the comparison operators listed above. *Note Strings::. -- Built-in Function: eq (X, Y) Return true if the two inputs are equal. This function is equivalent to 'x == y'. See also: *note ne: XREFne, *note isequal: XREFisequal, *note le: XREFle, *note ge: XREFge, *note gt: XREFgt, *note ne: XREFne, *note lt: XREFlt. -- Built-in Function: ge (X, Y) This function is equivalent to 'x >= y'. See also: *note le: XREFle, *note eq: XREFeq, *note gt: XREFgt, *note ne: XREFne, *note lt: XREFlt. -- Built-in Function: gt (X, Y) This function is equivalent to 'x > y'. See also: *note le: XREFle, *note eq: XREFeq, *note ge: XREFge, *note ne: XREFne, *note lt: XREFlt. -- Function File: isequal (X1, X2, ...) Return true if all of X1, X2, ... are equal. See also: *note isequaln: XREFisequaln. -- Function File: isequaln (X1, X2, ...) Return true if all of X1, X2, ... are equal under the additional assumption that NaN == NaN (no comparison of NaN placeholders in dataset). See also: *note isequal: XREFisequal. -- Built-in Function: le (X, Y) This function is equivalent to 'x <= y'. See also: *note eq: XREFeq, *note ge: XREFge, *note gt: XREFgt, *note ne: XREFne, *note lt: XREFlt. -- Built-in Function: lt (X, Y) This function is equivalent to 'x < y'. See also: *note le: XREFle, *note eq: XREFeq, *note ge: XREFge, *note gt: XREFgt, *note ne: XREFne. -- Built-in Function: ne (X, Y) Return true if the two inputs are not equal. This function is equivalent to 'x != y'. See also: *note eq: XREFeq, *note isequal: XREFisequal, *note le: XREFle, *note ge: XREFge, *note lt: XREFlt.  File: octave.info, Node: Boolean Expressions, Next: Assignment Ops, Prev: Comparison Ops, Up: Expressions 8.5 Boolean Expressions ======================= * Menu: * Element-by-element Boolean Operators:: * Short-circuit Boolean Operators::  File: octave.info, Node: Element-by-element Boolean Operators, Next: Short-circuit Boolean Operators, Up: Boolean Expressions 8.5.1 Element-by-element Boolean Operators ------------------------------------------ An "element-by-element boolean expression" is a combination of comparison expressions using the boolean operators "or" ('|'), "and" ('&'), and "not" ('!'), along with parentheses to control nesting. The truth of the boolean expression is computed by combining the truth values of the corresponding elements of the component expressions. A value is considered to be false if it is zero, and true otherwise. Element-by-element boolean expressions can be used wherever comparison expressions can be used. They can be used in 'if' and 'while' statements. However, a matrix value used as the condition in an 'if' or 'while' statement is only true if _all_ of its elements are nonzero. Like comparison operations, each element of an element-by-element boolean expression also has a numeric value (1 if true, 0 if false) that comes into play if the result of the boolean expression is stored in a variable, or used in arithmetic. Here are descriptions of the three element-by-element boolean operators. 'BOOLEAN1 & BOOLEAN2' Elements of the result are true if both corresponding elements of BOOLEAN1 and BOOLEAN2 are true. 'BOOLEAN1 | BOOLEAN2' Elements of the result are true if either of the corresponding elements of BOOLEAN1 or BOOLEAN2 is true. '! BOOLEAN' '~ BOOLEAN' Each element of the result is true if the corresponding element of BOOLEAN is false. These operators work on an element-by-element basis. For example, the expression [1, 0; 0, 1] & [1, 0; 2, 3] returns a two by two identity matrix. For the binary operators, broadcasting rules apply. *Note Broadcasting::. In particular, if one of the operands is a scalar and the other a matrix, the operator is applied to the scalar and each element of the matrix. For the binary element-by-element boolean operators, both subexpressions BOOLEAN1 and BOOLEAN2 are evaluated before computing the result. This can make a difference when the expressions have side effects. For example, in the expression a & b++ the value of the variable B is incremented even if the variable A is zero. This behavior is necessary for the boolean operators to work as described for matrix-valued operands. -- Built-in Function: Z = and (X, Y) -- Built-in Function: Z = and (X1, X2, ...) Return the logical AND of X and Y. This function is equivalent to the operator syntax 'x & y'. If more than two arguments are given, the logical AND is applied cumulatively from left to right: (...((x1 & x2) & x3) & ...) At least one argument is required. See also: *note or: XREFor, *note not: XREFnot, *note xor: XREFxor. -- Built-in Function: Z = not (X) Return the logical NOT of X. This function is equivalent to the operator syntax '! x'. See also: *note and: XREFand, *note or: XREFor, *note xor: XREFxor. -- Built-in Function: Z = or (X, Y) -- Built-in Function: Z = or (X1, X2, ...) Return the logical OR of X and Y. This function is equivalent to the operator syntax 'x | y'. If more than two arguments are given, the logical OR is applied cumulatively from left to right: (...((x1 | x2) | x3) | ...) At least one argument is required. See also: *note and: XREFand, *note not: XREFnot, *note xor: XREFxor.  File: octave.info, Node: Short-circuit Boolean Operators, Prev: Element-by-element Boolean Operators, Up: Boolean Expressions 8.5.2 Short-circuit Boolean Operators ------------------------------------- Combined with the implicit conversion to scalar values in 'if' and 'while' conditions, Octave's element-by-element boolean operators are often sufficient for performing most logical operations. However, it is sometimes desirable to stop evaluating a boolean expression as soon as the overall truth value can be determined. Octave's "short-circuit" boolean operators work this way. 'BOOLEAN1 && BOOLEAN2' The expression BOOLEAN1 is evaluated and converted to a scalar using the equivalent of the operation 'all (BOOLEAN1(:))'. If it is false, the result of the overall expression is 0. If it is true, the expression BOOLEAN2 is evaluated and converted to a scalar using the equivalent of the operation 'all (BOOLEAN1(:))'. If it is true, the result of the overall expression is 1. Otherwise, the result of the overall expression is 0. *Warning:* there is one exception to the rule of evaluating 'all (BOOLEAN1(:))', which is when 'boolean1' is the empty matrix. The truth value of an empty matrix is always 'false' so '[] && true' evaluates to 'false' even though 'all ([])' is 'true'. 'BOOLEAN1 || BOOLEAN2' The expression BOOLEAN1 is evaluated and converted to a scalar using the equivalent of the operation 'all (BOOLEAN1(:))'. If it is true, the result of the overall expression is 1. If it is false, the expression BOOLEAN2 is evaluated and converted to a scalar using the equivalent of the operation 'all (BOOLEAN1(:))'. If it is true, the result of the overall expression is 1. Otherwise, the result of the overall expression is 0. *Warning:* the truth value of an empty matrix is always 'false', see the previous list item for details. The fact that both operands may not be evaluated before determining the overall truth value of the expression can be important. For example, in the expression a && b++ the value of the variable B is only incremented if the variable A is nonzero. This can be used to write somewhat more concise code. For example, it is possible write function f (a, b, c) if (nargin > 2 && ischar (c)) ... instead of having to use two 'if' statements to avoid attempting to evaluate an argument that doesn't exist. For example, without the short-circuit feature, it would be necessary to write function f (a, b, c) if (nargin > 2) if (ischar (c)) ... Writing function f (a, b, c) if (nargin > 2 & ischar (c)) ... would result in an error if 'f' were called with one or two arguments because Octave would be forced to try to evaluate both of the operands for the operator '&'. MATLAB has special behavior that allows the operators '&' and '|' to short-circuit when used in the truth expression for 'if' and 'while' statements. Octave also behaves the same way by default, though the use of the '&' and '|' operators in this way is strongly discouraged. Instead, you should use the '&&' and '||' operators that always have short-circuit behavior. Finally, the ternary operator (?:) is not supported in Octave. If short-circuiting is not important, it can be replaced by the 'ifelse' function. -- Built-in Function: merge (MASK, TVAL, FVAL) -- Built-in Function: ifelse (MASK, TVAL, FVAL) Merge elements of TRUE_VAL and FALSE_VAL, depending on the value of MASK. If MASK is a logical scalar, the other two arguments can be arbitrary values. Otherwise, MASK must be a logical array, and TVAL, FVAL should be arrays of matching class, or cell arrays. In the scalar mask case, TVAL is returned if MASK is true, otherwise FVAL is returned. In the array mask case, both TVAL and FVAL must be either scalars or arrays with dimensions equal to MASK. The result is constructed as follows: result(mask) = tval(mask); result(! mask) = fval(! mask); MASK can also be arbitrary numeric type, in which case it is first converted to logical. See also: *note logical: XREFlogical, *note diff: XREFdiff.  File: octave.info, Node: Assignment Ops, Next: Increment Ops, Prev: Boolean Expressions, Up: Expressions 8.6 Assignment Expressions ========================== An "assignment" is an expression that stores a new value into a variable. For example, the following expression assigns the value 1 to the variable 'z': z = 1 After this expression is executed, the variable 'z' has the value 1. Whatever old value 'z' had before the assignment is forgotten. The '=' sign is called an "assignment operator". Assignments can store string values also. For example, the following expression would store the value "this food is good" in the variable 'message': thing = "food" predicate = "good" message = [ "this " , thing , " is " , predicate ] (This also illustrates concatenation of strings.) Most operators (addition, concatenation, and so on) have no effect except to compute a value. If you ignore the value, you might as well not use the operator. An assignment operator is different. It does produce a value, but even if you ignore the value, the assignment still makes itself felt through the alteration of the variable. We call this a "side effect". The left-hand operand of an assignment need not be a variable (*note Variables::). It can also be an element of a matrix (*note Index Expressions::) or a list of return values (*note Calling Functions::). These are all called "lvalues", which means they can appear on the left-hand side of an assignment operator. The right-hand operand may be any expression. It produces the new value which the assignment stores in the specified variable, matrix element, or list of return values. It is important to note that variables do _not_ have permanent types. The type of a variable is simply the type of whatever value it happens to hold at the moment. In the following program fragment, the variable 'foo' has a numeric value at first, and a string value later on: octave:13> foo = 1 foo = 1 octave:13> foo = "bar" foo = bar When the second assignment gives 'foo' a string value, the fact that it previously had a numeric value is forgotten. Assignment of a scalar to an indexed matrix sets all of the elements that are referenced by the indices to the scalar value. For example, if 'a' is a matrix with at least two columns, a(:, 2) = 5 sets all the elements in the second column of 'a' to 5. Assigning an empty matrix '[]' works in most cases to allow you to delete rows or columns of matrices and vectors. *Note Empty Matrices::. For example, given a 4 by 5 matrix A, the assignment A (3, :) = [] deletes the third row of A, and the assignment A (:, 1:2:5) = [] deletes the first, third, and fifth columns. An assignment is an expression, so it has a value. Thus, 'z = 1' as an expression has the value 1. One consequence of this is that you can write multiple assignments together: x = y = z = 0 stores the value 0 in all three variables. It does this because the value of 'z = 0', which is 0, is stored into 'y', and then the value of 'y = z = 0', which is 0, is stored into 'x'. This is also true of assignments to lists of values, so the following is a valid expression [a, b, c] = [u, s, v] = svd (a) that is exactly equivalent to [u, s, v] = svd (a) a = u b = s c = v In expressions like this, the number of values in each part of the expression need not match. For example, the expression [a, b] = [u, s, v] = svd (a) is equivalent to [u, s, v] = svd (a) a = u b = s The number of values on the left side of the expression can, however, not exceed the number of values on the right side. For example, the following will produce an error. [a, b, c, d] = [u, s, v] = svd (a); -| error: element number 4 undefined in return list The symbol '~' may be used as a placeholder in the list of lvalues, indicating that the corresponding return value should be ignored and not stored anywhere: [~, s, v] = svd (a); This is cleaner and more memory efficient than using a dummy variable. The 'nargout' value for the right-hand side expression is not affected. If the assignment is used as an expression, the return value is a comma-separated list with the ignored values dropped. A very common programming pattern is to increment an existing variable with a given value, like this a = a + 2; This can be written in a clearer and more condensed form using the '+=' operator a += 2; Similar operators also exist for subtraction ('-='), multiplication ('*='), and division ('/='). An expression of the form EXPR1 OP= EXPR2 is evaluated as EXPR1 = (EXPR1) OP (EXPR2) where OP can be either '+', '-', '*', or '/', as long as EXPR2 is a simple expression with no side effects. If EXPR2 also contains an assignment operator, then this expression is evaluated as TEMP = EXPR2 EXPR1 = (EXPR1) OP TEMP where TEMP is a placeholder temporary value storing the computed result of evaluating EXPR2. So, the expression a *= b+1 is evaluated as a = a * (b+1) and _not_ a = a * b + 1 You can use an assignment anywhere an expression is called for. For example, it is valid to write 'x != (y = 1)' to set 'y' to 1 and then test whether 'x' equals 1. But this style tends to make programs hard to read. Except in a one-shot program, you should rewrite it to get rid of such nesting of assignments. This is never very hard.  File: octave.info, Node: Increment Ops, Next: Operator Precedence, Prev: Assignment Ops, Up: Expressions 8.7 Increment Operators ======================= _Increment operators_ increase or decrease the value of a variable by 1. The operator to increment a variable is written as '++'. It may be used to increment a variable either before or after taking its value. For example, to pre-increment the variable X, you would write '++X'. This would add one to X and then return the new value of X as the result of the expression. It is exactly the same as the expression 'X = X + 1'. To post-increment a variable X, you would write 'X++'. This adds one to the variable X, but returns the value that X had prior to incrementing it. For example, if X is equal to 2, the result of the expression 'X++' is 2, and the new value of X is 3. For matrix and vector arguments, the increment and decrement operators work on each element of the operand. Here is a list of all the increment and decrement expressions. '++X' This expression increments the variable X. The value of the expression is the _new_ value of X. It is equivalent to the expression 'X = X + 1'. '--X' This expression decrements the variable X. The value of the expression is the _new_ value of X. It is equivalent to the expression 'X = X - 1'. 'X++' This expression causes the variable X to be incremented. The value of the expression is the _old_ value of X. 'X--' This expression causes the variable X to be decremented. The value of the expression is the _old_ value of X.  File: octave.info, Node: Operator Precedence, Prev: Increment Ops, Up: Expressions 8.8 Operator Precedence ======================= "Operator precedence" determines how operators are grouped, when different operators appear close by in one expression. For example, '*' has higher precedence than '+'. Thus, the expression 'a + b * c' means to multiply 'b' and 'c', and then add 'a' to the product (i.e., 'a + (b * c)'). You can overrule the precedence of the operators by using parentheses. You can think of the precedence rules as saying where the parentheses are assumed if you do not write parentheses yourself. In fact, it is wise to use parentheses whenever you have an unusual combination of operators, because other people who read the program may not remember what the precedence is in this case. You might forget as well, and then you too could make a mistake. Explicit parentheses will help prevent any such mistake. When operators of equal precedence are used together, the leftmost operator groups first, except for the assignment operators, which group in the opposite order. Thus, the expression 'a - b + c' groups as '(a - b) + c', but the expression 'a = b = c' groups as 'a = (b = c)'. The precedence of prefix unary operators is important when another operator follows the operand. For example, '-x^2' means '-(x^2)', because '-' has lower precedence than '^'. Here is a table of the operators in Octave, in order of decreasing precedence. Unless noted, all operators group left to right. 'function call and array indexing, cell array indexing, and structure element indexing' '()' '{}' '.' 'postfix increment, and postfix decrement' '++' '--' These operators group right to left. 'transpose and exponentiation' ''' '.'' '^' '**' '.^' '.**' 'unary plus, unary minus, prefix increment, prefix decrement, and logical "not"' '+' '-' '++' '--' '~' '!' 'multiply and divide' '*' '/' '\' '.\' '.*' './' 'add, subtract' '+' '-' 'colon' ':' 'relational' '<' '<=' '==' '>=' '>' '!=' '~=' 'element-wise "and"' '&' 'element-wise "or"' '|' 'logical "and"' '&&' 'logical "or"' '||' 'assignment' '=' '+=' '-=' '*=' '/=' '\=' '^=' '.*=' './=' '.\=' '.^=' '|=' '&=' These operators group right to left.  File: octave.info, Node: Evaluation, Next: Statements, Prev: Expressions, Up: Top 9 Evaluation ************ Normally, you evaluate expressions simply by typing them at the Octave prompt, or by asking Octave to interpret commands that you have saved in a file. Sometimes, you may find it necessary to evaluate an expression that has been computed and stored in a string, which is exactly what the 'eval' function lets you do. -- Built-in Function: eval (TRY) -- Built-in Function: eval (TRY, CATCH) Parse the string TRY and evaluate it as if it were an Octave program. If execution fails, evaluate the optional string CATCH. The string TRY is evaluated in the current context, so any results remain available after 'eval' returns. The following example creates the variable A with the approximate value of 3.1416 in the current workspace. eval ("A = acos(-1);"); If an error occurs during the evaluation of TRY then the CATCH string is evaluated, as the following example shows: eval ('error ("This is a bad example");', 'printf ("This error occurred:\n%s\n", lasterr ());'); -| This error occurred: This is a bad example Programming Note: if you are only using 'eval' as an error-capturing mechanism, rather than for the execution of arbitrary code strings, Consider using try/catch blocks or unwind_protect/unwind_protect_cleanup blocks instead. These techniques have higher performance and don't introduce the security considerations that the evaluation of arbitrary code does. See also: *note evalin: XREFevalin. * Menu: * Calling a Function by its Name:: * Evaluation in a Different Context::  File: octave.info, Node: Calling a Function by its Name, Next: Evaluation in a Different Context, Up: Evaluation 9.1 Calling a Function by its Name ================================== The 'feval' function allows you to call a function from a string containing its name. This is useful when writing a function that needs to call user-supplied functions. The 'feval' function takes the name of the function to call as its first argument, and the remaining arguments are given to the function. The following example is a simple-minded function using 'feval' that finds the root of a user-supplied function of one variable using Newton's method. function result = newtroot (fname, x) # usage: newtroot (fname, x) # # fname : a string naming a function f(x). # x : initial guess delta = tol = sqrt (eps); maxit = 200; fx = feval (fname, x); for i = 1:maxit if (abs (fx) < tol) result = x; return; else fx_new = feval (fname, x + delta); deriv = (fx_new - fx) / delta; x = x - fx / deriv; fx = fx_new; endif endfor result = x; endfunction Note that this is only meant to be an example of calling user-supplied functions and should not be taken too seriously. In addition to using a more robust algorithm, any serious code would check the number and type of all the arguments, ensure that the supplied function really was a function, etc. *Note Predicates for Numeric Objects::, for a list of predicates for numeric objects, and *note Status of Variables::, for a description of the 'exist' function. -- Built-in Function: feval (NAME, ...) Evaluate the function named NAME. Any arguments after the first are passed as inputs to the named function. For example, feval ("acos", -1) => 3.1416 calls the function 'acos' with the argument '-1'. The function 'feval' can also be used with function handles of any sort (*note Function Handles::). Historically, 'feval' was the only way to call user-supplied functions in strings, but function handles are now preferred due to the cleaner syntax they offer. For example, F = @exp; feval (F, 1) => 2.7183 F (1) => 2.7183 are equivalent ways to call the function referred to by F. If it cannot be predicted beforehand whether F is a function handle, function name in a string, or inline function then 'feval' can be used instead. A similar function 'run' exists for calling user script files, that are not necessarily on the user path -- Command: run SCRIPT -- Function File: run ("SCRIPT") Run SCRIPT in the current workspace. Scripts which reside in directories specified in Octave's load path, and which end with the extension '".m"', can be run simply by typing their name. For scripts not located on the load path, use 'run'. The file name SCRIPT can be a bare, fully qualified, or relative filename and with or without a file extension. If no extension is specified, Octave will first search for a script with the '".m"' extension before falling back to the script name without an extension. Implementation Note: If SCRIPT includes a path component, then 'run' first changes the working directory to the directory where SCRIPT is found. Next, the script is executed. Finally, 'run' returns to the original working directory unless 'script' has specifically changed directories. See also: *note path: XREFpath, *note addpath: XREFaddpath, *note source: XREFsource.  File: octave.info, Node: Evaluation in a Different Context, Prev: Calling a Function by its Name, Up: Evaluation 9.2 Evaluation in a Different Context ===================================== Before you evaluate an expression you need to substitute the values of the variables used in the expression. These are stored in the symbol table. Whenever the interpreter starts a new function it saves the current symbol table and creates a new one, initializing it with the list of function parameters and a couple of predefined variables such as 'nargin'. Expressions inside the function use the new symbol table. Sometimes you want to write a function so that when you call it, it modifies variables in your own context. This allows you to use a pass-by-name style of function, which is similar to using a pointer in programming languages such as C. Consider how you might write 'save' and 'load' as m-files. For example: function create_data x = linspace (0, 10, 10); y = sin (x); save mydata x y endfunction With 'evalin', you could write 'save' as follows: function save (file, name1, name2) f = open_save_file (file); save_var (f, name1, evalin ("caller", name1)); save_var (f, name2, evalin ("caller", name2)); endfunction Here, 'caller' is the 'create_data' function and 'name1' is the string "x", which evaluates simply as the value of 'x'. You later want to load the values back from 'mydata' in a different context: function process_data load mydata ... do work ... endfunction With 'assignin', you could write 'load' as follows: function load (file) f = open_load_file (file); [name, val] = load_var (f); assignin ("caller", name, val); [name, val] = load_var (f); assignin ("caller", name, val); endfunction Here, 'caller' is the 'process_data' function. You can set and use variables at the command prompt using the context 'base' rather than 'caller'. These functions are rarely used in practice. One example is the 'fail ('code', 'pattern')' function which evaluates 'code' in the caller's context and checks that the error message it produces matches the given pattern. Other examples such as 'save' and 'load' are written in C++ where all Octave variables are in the 'caller' context and 'evalin' is not needed. -- Built-in Function: evalin (CONTEXT, TRY) -- Built-in Function: evalin (CONTEXT, TRY, CATCH) Like 'eval', except that the expressions are evaluated in the context CONTEXT, which may be either "caller" or "base". See also: *note eval: XREFeval, *note assignin: XREFassignin. -- Built-in Function: assignin (CONTEXT, VARNAME, VALUE) Assign VALUE to VARNAME in context CONTEXT, which may be either "base" or "caller". See also: *note evalin: XREFevalin.  File: octave.info, Node: Statements, Next: Functions and Scripts, Prev: Evaluation, Up: Top 10 Statements ************* Statements may be a simple constant expression or a complicated list of nested loops and conditional statements. "Control statements" such as 'if', 'while', and so on control the flow of execution in Octave programs. All the control statements start with special keywords such as 'if' and 'while', to distinguish them from simple expressions. Many control statements contain other statements; for example, the 'if' statement contains another statement which may or may not be executed. Each control statement has a corresponding "end" statement that marks the end of the control statement. For example, the keyword 'endif' marks the end of an 'if' statement, and 'endwhile' marks the end of a 'while' statement. You can use the keyword '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 'if' or 'while' and the corresponding end statement is called the "body" of a control statement. * Menu: * The if Statement:: * The switch Statement:: * The while Statement:: * The do-until Statement:: * The for Statement:: * The break Statement:: * The continue Statement:: * The unwind_protect Statement:: * The try Statement:: * Continuation Lines::  File: octave.info, Node: The if Statement, Next: The switch Statement, Up: Statements 10.1 The if Statement ===================== The 'if' statement is Octave's decision-making statement. There are three basic forms of an 'if' statement. In its simplest form, it looks like this: if (CONDITION) THEN-BODY endif CONDITION is an expression that controls what the rest of the statement will do. The THEN-BODY is executed only if CONDITION is true. The condition in an 'if' statement is considered true if its value is nonzero, and false if its value is zero. If the value of the conditional expression in an 'if' statement is a vector or a matrix, it is considered true only if it is non-empty and _all_ of the elements are nonzero. The second form of an if statement looks like this: if (CONDITION) THEN-BODY else ELSE-BODY endif If CONDITION is true, THEN-BODY is executed; otherwise, ELSE-BODY is executed. Here is an example: if (rem (x, 2) == 0) printf ("x is even\n"); else printf ("x is odd\n"); endif In this example, if the expression 'rem (x, 2) == 0' is true (that is, the value of 'x' is divisible by 2), then the first 'printf' statement is evaluated, otherwise the second 'printf' statement is evaluated. The third and most general form of the 'if' statement allows multiple decisions to be combined in a single statement. It looks like this: if (CONDITION) THEN-BODY elseif (CONDITION) ELSEIF-BODY else ELSE-BODY endif Any number of 'elseif' clauses may appear. Each condition is tested in turn, and if one is found to be true, its corresponding BODY is executed. If none of the conditions are true and the 'else' clause is present, its body is executed. Only one 'else' clause may appear, and it must be the last part of the statement. In the following example, if the first condition is true (that is, the value of 'x' is divisible by 2), then the first 'printf' statement is executed. If it is false, then the second condition is tested, and if it is true (that is, the value of 'x' is divisible by 3), then the second 'printf' statement is executed. Otherwise, the third 'printf' statement is performed. if (rem (x, 2) == 0) printf ("x is even\n"); elseif (rem (x, 3) == 0) printf ("x is odd and divisible by 3\n"); else printf ("x is odd\n"); endif Note that the 'elseif' keyword must not be spelled 'else if', as is allowed in Fortran. If it is, the space between the 'else' and 'if' will tell Octave to treat this as a new 'if' statement within another 'if' statement's 'else' clause. For example, if you write if (C1) BODY-1 else if (C2) BODY-2 endif Octave will expect additional input to complete the first 'if' statement. If you are using Octave interactively, it will continue to prompt you for additional input. If Octave is reading this input from a file, it may complain about missing or mismatched 'end' statements, or, if you have not used the more specific 'end' statements ('endif', 'endfor', etc.), it may simply produce incorrect results, without producing any warning messages. It is much easier to see the error if we rewrite the statements above like this, if (C1) BODY-1 else if (C2) BODY-2 endif using the indentation to show how Octave groups the statements. *Note Functions and Scripts::.  File: octave.info, Node: The switch Statement, Next: The while Statement, Prev: The if Statement, Up: Statements 10.2 The switch Statement ========================= It is very common to take different actions depending on the value of one variable. This is possible using the 'if' statement in the following way if (X == 1) do_something (); elseif (X == 2) do_something_else (); else do_something_completely_different (); endif This kind of code can however be very cumbersome to both write and maintain. To overcome this problem Octave supports the 'switch' statement. Using this statement, the above example becomes switch (X) case 1 do_something (); case 2 do_something_else (); otherwise do_something_completely_different (); endswitch This code makes the repetitive structure of the problem more explicit, making the code easier to read, and hence maintain. Also, if the variable 'X' should change its name, only one line would need changing compared to one line per case when 'if' statements are used. The general form of the 'switch' statement is switch (EXPRESSION) case LABEL COMMAND_LIST case LABEL COMMAND_LIST ... otherwise COMMAND_LIST endswitch where LABEL can be any expression. However, duplicate LABEL values are not detected, and only the COMMAND_LIST corresponding to the first match will be executed. For the 'switch' statement to be meaningful at least one 'case LABEL COMMAND_LIST' clause must be present, while the 'otherwise COMMAND_LIST' clause is optional. If LABEL is a cell array the corresponding COMMAND_LIST is executed if _any_ of the elements of the cell array match EXPRESSION. As an example, the following program will print 'Variable is either 6 or 7'. A = 7; switch (A) case { 6, 7 } printf ("variable is either 6 or 7\n"); otherwise printf ("variable is neither 6 nor 7\n"); endswitch As with all other specific 'end' keywords, 'endswitch' may be replaced by 'end', but you can get better diagnostics if you use the specific forms. One advantage of using the 'switch' statement compared to using 'if' statements is that the LABELs can be strings. If an 'if' statement is used it is _not_ possible to write if (X == "a string") # This is NOT valid since a character-to-character comparison between 'X' and the string will be made instead of evaluating if the strings are equal. This special-case is handled by the 'switch' statement, and it is possible to write programs that look like this switch (X) case "a string" do_something ... endswitch * Menu: * Notes for the C Programmer::  File: octave.info, Node: Notes for the C Programmer, Up: The switch Statement 10.2.1 Notes for the C Programmer --------------------------------- The 'switch' statement is also available in the widely used C programming language. There are, however, some differences between the statement in Octave and C * Cases are exclusive, so they don't 'fall through' as do the cases in the 'switch' statement of the C language. * The COMMAND_LIST elements are not optional. Making the list optional would have meant requiring a separator between the label and the command list. Otherwise, things like switch (foo) case (1) -2 ... would produce surprising results, as would switch (foo) case (1) case (2) doit (); ... particularly for C programmers. If 'doit()' should be executed if FOO is either '1' or '2', the above code should be written with a cell array like this switch (foo) case { 1, 2 } doit (); ...  File: octave.info, Node: The while Statement, Next: The do-until Statement, Prev: The switch Statement, Up: Statements 10.3 The while Statement ======================== In programming, a "loop" means a part of a program that is (or at least can be) executed two or more times in succession. The 'while' statement is the simplest looping statement in Octave. It repeatedly executes a statement as long as a condition is true. As with the condition in an 'if' statement, the condition in a 'while' statement is considered true if its value is nonzero, and false if its value is zero. If the value of the conditional expression in a 'while' statement is a vector or a matrix, it is considered true only if it is non-empty and _all_ of the elements are nonzero. Octave's 'while' statement looks like this: while (CONDITION) BODY endwhile Here BODY is a statement or list of statements that we call the "body" of the loop, and CONDITION is an expression that controls how long the loop keeps running. The first thing the 'while' statement does is test CONDITION. If CONDITION is true, it executes the statement BODY. After BODY has been executed, CONDITION is tested again, and if it is still true, BODY is executed again. This process repeats until CONDITION is no longer true. If CONDITION is initially false, the body of the loop is never executed. This example creates a variable 'fib' that contains the first ten elements of the Fibonacci sequence. fib = ones (1, 10); i = 3; while (i <= 10) fib (i) = fib (i-1) + fib (i-2); i++; endwhile Here the body of the loop contains two statements. The loop works like this: first, the value of 'i' is set to 3. Then, the 'while' tests whether 'i' is less than or equal to 10. This is the case when 'i' equals 3, so the value of the 'i'-th element of 'fib' is set to the sum of the previous two values in the sequence. Then the 'i++' increments the value of 'i' and the loop repeats. The loop terminates when 'i' reaches 11. A newline is not required between the condition and the body; but using one makes the program clearer unless the body is very simple.  File: octave.info, Node: The do-until Statement, Next: The for Statement, Prev: The while Statement, Up: Statements 10.4 The do-until Statement =========================== The 'do-until' statement is similar to the 'while' statement, except that it repeatedly executes a statement until a condition becomes true, and the test of the condition is at the end of the loop, so the body of the loop is always executed at least once. As with the condition in an 'if' statement, the condition in a 'do-until' statement is considered true if its value is nonzero, and false if its value is zero. If the value of the conditional expression in a 'do-until' statement is a vector or a matrix, it is considered true only if it is non-empty and _all_ of the elements are nonzero. Octave's 'do-until' statement looks like this: do BODY until (CONDITION) Here BODY is a statement or list of statements that we call the "body" of the loop, and CONDITION is an expression that controls how long the loop keeps running. This example creates a variable 'fib' that contains the first ten elements of the Fibonacci sequence. fib = ones (1, 10); i = 2; do i++; fib (i) = fib (i-1) + fib (i-2); until (i == 10) A newline is not required between the 'do' keyword and the body; but using one makes the program clearer unless the body is very simple.  File: octave.info, Node: The for Statement, Next: The break Statement, Prev: The do-until Statement, Up: Statements 10.5 The for Statement ====================== The 'for' statement makes it more convenient to count iterations of a loop. The general form of the 'for' statement looks like this: for VAR = EXPRESSION BODY endfor where BODY stands for any statement or list of statements, EXPRESSION is any valid expression, and VAR may take several forms. Usually it is a simple variable name or an indexed variable. If the value of EXPRESSION is a structure, VAR may also be a vector with two elements. *Note Looping Over Structure Elements::, below. The assignment expression in the '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 of the expression to VAR in turn. If EXPRESSION is a range, a row vector, or a scalar, the value of VAR will be a scalar each time the loop body is executed. If VAR is a column vector or a matrix, VAR will be a column vector each time the loop body is executed. The following example shows another way to create a vector containing the first ten elements of the Fibonacci sequence, this time using the 'for' statement: fib = ones (1, 10); for i = 3:10 fib (i) = fib (i-1) + fib (i-2); endfor This code works by first evaluating the expression '3:10', to produce a range of values from 3 to 10 inclusive. Then the variable 'i' is assigned the first element of the range and the body of the loop is executed once. When the end of the loop body is reached, the next value in the range is assigned to the variable 'i', and the loop body is executed again. This process continues until there are no more elements to assign. Within Octave is it also possible to iterate over matrices or cell arrays using the 'for' statement. For example consider disp ("Loop over a matrix") for i = [1,3;2,4] i endfor disp ("Loop over a cell array") for i = {1,"two";"three",4} i endfor In this case the variable 'i' takes on the value of the columns of the matrix or cell matrix. So the first loop iterates twice, producing two column vectors '[1;2]', followed by '[3;4]', and likewise for the loop over the cell array. This can be extended to loops over multi-dimensional arrays. For example: a = [1,3;2,4]; c = cat (3, a, 2*a); for i = c i endfor In the above case, the multi-dimensional matrix C is reshaped to a two-dimensional matrix as 'reshape (c, rows (c), prod (size (c)(2:end)))' and then the same behavior as a loop over a two dimensional matrix is produced. Although it is possible to rewrite all 'for' loops as 'while' loops, the Octave language has both statements because often a 'for' loop is both less work to type and more natural to think of. Counting the number of iterations is very common in loops and it can be easier to think of this counting as part of looping rather than as something to do inside the loop. * Menu: * Looping Over Structure Elements::  File: octave.info, Node: Looping Over Structure Elements, Up: The for Statement 10.5.1 Looping Over Structure Elements -------------------------------------- A special form of the 'for' statement allows you to loop over all the elements of a structure: for [ VAL, KEY ] = EXPRESSION BODY endfor In this form of the 'for' statement, the value of EXPRESSION must be a structure. If it is, KEY and VAL are set to the name of the element and the corresponding value in turn, until there are no more elements. For example: x.a = 1 x.b = [1, 2; 3, 4] x.c = "string" for [val, key] = x key val endfor -| key = a -| val = 1 -| key = b -| val = -| -| 1 2 -| 3 4 -| -| key = c -| val = string 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 'fieldnames' and sort the list yourself. The 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.  File: octave.info, Node: The break Statement, Next: The continue Statement, Prev: The for Statement, Up: Statements 10.6 The break Statement ======================== The 'break' statement jumps out of the innermost 'while', 'do-until', or 'for' loop that encloses it. The 'break' statement may only be used within the body of a loop. The following example finds the smallest divisor of a given integer, and also identifies prime numbers: num = 103; div = 2; while (div*div <= num) if (rem (num, div) == 0) break; endif div++; endwhile if (rem (num, div) == 0) printf ("Smallest divisor of %d is %d\n", num, div) else printf ("%d is prime\n", num); endif When the remainder is zero in the first 'while' statement, Octave immediately "breaks out" of the loop. This means that Octave proceeds immediately to the statement following the loop and continues processing. (This is very different from the 'exit' statement which stops the entire Octave program.) Here is another program equivalent to the previous one. It illustrates how the CONDITION of a 'while' statement could just as well be replaced with a 'break' inside an 'if': num = 103; div = 2; while (1) if (rem (num, div) == 0) printf ("Smallest divisor of %d is %d\n", num, div); break; endif div++; if (div*div > num) printf ("%d is prime\n", num); break; endif endwhile  File: octave.info, Node: The continue Statement, Next: The unwind_protect Statement, Prev: The break Statement, Up: Statements 10.7 The continue Statement =========================== The 'continue' statement, like 'break', is used only inside 'while', 'do-until', or 'for' loops. It skips over the rest of the loop body, causing the next cycle around the loop to begin immediately. Contrast this with 'break', which jumps out of the loop altogether. Here is an example: # print elements of a vector of random # integers that are even. # first, create a row vector of 10 random # integers with values between 0 and 100: vec = round (rand (1, 10) * 100); # print what we're interested in: for x = vec if (rem (x, 2) != 0) continue; endif printf ("%d\n", x); endfor If one of the elements of VEC is an odd number, this example skips the print statement for that element, and continues back to the first statement in the loop. This is not a practical example of the 'continue' statement, but it should give you a clear understanding of how it works. Normally, one would probably write the loop like this: for x = vec if (rem (x, 2) == 0) printf ("%d\n", x); endif endfor  File: octave.info, Node: The unwind_protect Statement, Next: The try Statement, Prev: The continue Statement, Up: Statements 10.8 The unwind_protect Statement ================================= Octave supports a limited form of exception handling modeled after the unwind-protect form of Lisp. The general form of an 'unwind_protect' block looks like this: unwind_protect BODY unwind_protect_cleanup CLEANUP end_unwind_protect where BODY and CLEANUP are both optional and may contain any Octave expressions or commands. The statements in CLEANUP are guaranteed to be executed regardless of how control exits BODY. This is useful to protect temporary changes to global variables from possible errors. For example, the following code will always restore the original value of the global variable 'frobnosticate' even if an error occurs in the first part of the 'unwind_protect' block. save_frobnosticate = frobnosticate; unwind_protect frobnosticate = true; ... unwind_protect_cleanup frobnosticate = save_frobnosticate; end_unwind_protect Without 'unwind_protect', the value of FROBNOSTICATE would not be restored if an error occurs while evaluating the first part of the 'unwind_protect' block because evaluation would stop at the point of the error and the statement to restore the value would not be executed. In addition to unwind_protect, Octave supports another form of exception handling, the 'try' block.  File: octave.info, Node: The try Statement, Next: Continuation Lines, Prev: The unwind_protect Statement, Up: Statements 10.9 The try Statement ====================== The original form of a 'try' block looks like this: try BODY catch CLEANUP end_try_catch where BODY and CLEANUP are both optional and may contain any Octave expressions or commands. The statements in CLEANUP are only executed if an error occurs in BODY. No warnings or error messages are printed while BODY is executing. If an error does occur during the execution of BODY, CLEANUP can use the functions 'lasterr' or 'lasterror' to access the text of the message that would have been printed, as well as its identifier. The alternative form, try BODY catch ERR CLEANUP end_try_catch will automatically store the output of 'lasterror' in the structure ERR. *Note Errors and Warnings::, for more information about the 'lasterr' and 'lasterror' functions.  File: octave.info, Node: Continuation Lines, Prev: The try Statement, Up: Statements 10.10 Continuation Lines ======================== In the Octave language, most statements end with a newline character and you must tell Octave to ignore the newline character in order to continue a statement from one line to the next. Lines that end with the characters '...' are joined with the following line before they are divided into tokens by Octave's parser. For example, the lines x = long_variable_name ... + longer_variable_name ... - 42 form a single statement. Any text between the continuation marker and the newline character is ignored. For example, the statement x = long_variable_name ... # comment one + longer_variable_name ...comment two - 42 # last comment is equivalent to the one shown above. Inside double-quoted string constants, the character '\' has to be used as continuation marker. The '\' must appear at the end of the line just before the newline character: s = "This text starts in the first line \ and is continued in the second line." Input that occurs inside parentheses can be continued to the next line without having to use a continuation marker. For example, it is possible to write statements like if (fine_dining_destination == on_a_boat || fine_dining_destination == on_a_train) seuss (i, will, not, eat, them, sam, i, am, i, will, not, eat, green, eggs, and, ham); endif without having to add to the clutter with continuation markers.  File: octave.info, Node: Functions and Scripts, Next: Errors and Warnings, Prev: Statements, Up: Top 11 Functions and Scripts ************************ Complicated Octave programs can often be simplified by defining functions. Functions can be defined directly on the command line during interactive Octave sessions, or in external files, and can be called just like built-in functions. * Menu: * Introduction to Function and Script Files:: * Defining Functions:: * Multiple Return Values:: * Variable-length Argument Lists:: * Ignoring Arguments:: * Variable-length Return Lists:: * Returning from a Function:: * Default Arguments:: * Function Files:: * Script Files:: * Function Handles Anonymous Functions Inline Functions:: * Commands:: * Organization of Functions::  File: octave.info, Node: Introduction to Function and Script Files, Next: Defining Functions, Up: Functions and Scripts 11.1 Introduction to Function and Script Files ============================================== There are seven different things covered in this section. 1. Typing in a function at the command prompt. 2. Storing a group of commands in a file -- called a script file. 3. Storing a function in a file--called a function file. 4. Subfunctions in function files. 5. Multiple functions in one script file. 6. Private functions. 7. Nested functions. Both function files and script files end with an extension of .m, for MATLAB compatibility. If you want more than one independent functions in a file, it must be a script file (*note Script Files::), and to use these functions you must execute the script file before you can use the functions that are in the script file.  File: octave.info, Node: Defining Functions, Next: Multiple Return Values, Prev: Introduction to Function and Script Files, Up: Functions and Scripts 11.2 Defining Functions ======================= In its simplest form, the definition of a function named NAME looks like this: function NAME BODY endfunction A valid function name is like a valid variable name: a sequence of letters, digits and underscores, not starting with a digit. Functions share the same pool of names as variables. The function BODY consists of Octave statements. It is the most important part of the definition, because it says what the function should actually _do_. For example, here is a function that, when executed, will ring the bell on your terminal (assuming that it is possible to do so): function wakeup printf ("\a"); endfunction The 'printf' statement (*note Input and Output::) simply tells Octave to print the string "\a". The special character '\a' stands for the alert character (ASCII 7). *Note Strings::. Once this function is defined, you can ask Octave to evaluate it by typing the name of the function. Normally, you will want to pass some information to the functions you define. The syntax for passing parameters to a function in Octave is function NAME (ARG-LIST) BODY endfunction where ARG-LIST is a comma-separated list of the function's arguments. When the function is called, the argument names are used to hold the argument values given in the call. The list of arguments may be empty, in which case this form is equivalent to the one shown above. To print a message along with ringing the bell, you might modify the 'wakeup' to look like this: function wakeup (message) printf ("\a%s\n", message); endfunction Calling this function using a statement like this wakeup ("Rise and shine!"); will cause Octave to ring your terminal's bell and print the message 'Rise and shine!', followed by a newline character (the '\n' in the first argument to the 'printf' statement). In most cases, you will also want to get some information back from the functions you define. Here is the syntax for writing a function that returns a single value: function RET-VAR = NAME (ARG-LIST) BODY endfunction The symbol RET-VAR is the name of the variable that will hold the value to be returned by the function. This variable must be defined before the end of the function body in order for the function to return a value. Variables used in the body of a function are local to the function. Variables named in ARG-LIST and RET-VAR are also local to the function. *Note Global Variables::, for information about how to access global variables inside a function. For example, here is a function that computes the average of the elements of a vector: function retval = avg (v) retval = sum (v) / length (v); endfunction If we had written 'avg' like this instead, function retval = avg (v) if (isvector (v)) retval = sum (v) / length (v); endif endfunction and then called the function with a matrix instead of a vector as the argument, Octave would have printed an error message like this: error: value on right hand side of assignment is undefined because the body of the 'if' statement was never executed, and 'retval' was never defined. To prevent obscure errors like this, it is a good idea to always make sure that the return variables will always have values, and to produce meaningful error messages when problems are encountered. For example, 'avg' could have been written like this: function retval = avg (v) retval = 0; if (isvector (v)) retval = sum (v) / length (v); else error ("avg: expecting vector argument"); endif endfunction There is still one additional problem with this function. What if it is called without an argument? Without additional error checking, Octave will probably print an error message that won't really help you track down the source of the error. To allow you to catch errors like this, Octave provides each function with an automatic variable called 'nargin'. Each time a function is called, 'nargin' is automatically initialized to the number of arguments that have actually been passed to the function. For example, we might rewrite the 'avg' function like this: function retval = avg (v) retval = 0; if (nargin != 1) usage ("avg (vector)"); endif if (isvector (v)) retval = sum (v) / length (v); else error ("avg: expecting vector argument"); endif endfunction Although Octave does not automatically report an error if you call a function with more arguments than expected, doing so probably indicates that something is wrong. Octave also does not automatically report an error if a function is called with too few arguments, but any attempt to use a variable that has not been given a value will result in an error. To avoid such problems and to provide useful messages, we check for both possibilities and issue our own error message. -- Built-in Function: nargin () -- Built-in Function: nargin (FCN) Report the number of input arguments to a function. Called from within a function, return the number of arguments passed to the function. At the top level, return the number of command line arguments passed to Octave. If called with the optional argument FCN--a function name or handle-- return the declared number of arguments that the function can accept. If the last argument to FCN is VARARGIN the returned value is negative. For example, the function 'union' for sets is declared as function [y, ia, ib] = union (a, b, varargin) and nargin ("union") => -3 Programming Note: 'nargin' does not work on built-in functions. See also: *note nargout: XREFnargout, *note narginchk: XREFnarginchk, *note varargin: XREFvarargin, *note inputname: XREFinputname. -- Function File: inputname (N) Return the name of the N-th argument to the calling function. If the argument is not a simple variable name, return an empty string. 'inputname' may only be used within a function body, not at the command line. See also: *note nargin: XREFnargin, *note nthargout: XREFnthargout. -- Built-in Function: VAL = silent_functions () -- Built-in Function: OLD_VAL = silent_functions (NEW_VAL) -- Built-in Function: silent_functions (NEW_VAL, "local") Query or set the internal variable that controls whether internal output from a function is suppressed. If this option is disabled, Octave will display the results produced by evaluating expressions within a function body that are not terminated with a semicolon. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.  File: octave.info, Node: Multiple Return Values, Next: Variable-length Argument Lists, Prev: Defining Functions, Up: Functions and Scripts 11.3 Multiple Return Values =========================== Unlike many other computer languages, Octave allows you to define functions that return more than one value. The syntax for defining functions that return multiple values is function [RET-LIST] = NAME (ARG-LIST) BODY endfunction where NAME, ARG-LIST, and BODY have the same meaning as before, and RET-LIST is a comma-separated list of variable names that will hold the values returned from the function. The list of return values must have at least one element. If RET-LIST has only one element, this form of the 'function' statement is equivalent to the form described in the previous section. Here is an example of a function that returns two values, the maximum element of a vector and the index of its first occurrence in the vector. function [max, idx] = vmax (v) idx = 1; max = v (idx); for i = 2:length (v) if (v (i) > max) max = v (i); idx = i; endif endfor endfunction In this particular case, the two values could have been returned as elements of a single array, but that is not always possible or convenient. The values to be returned may not have compatible dimensions, and it is often desirable to give the individual return values distinct names. It is possible to use the 'nthargout' function to obtain only some of the return values or several at once in a cell array. *Note Cell Array Objects::. -- Function File: nthargout (N, FUNC, ...) -- Function File: nthargout (N, NTOT, FUNC, ...) Return the Nth output argument of the function specified by the function handle or string FUNC. Any additional arguments are passed directly to FUNC. The total number of arguments to call FUNC with can be passed in NTOT; by default NTOT is N. The input N can also be a vector of indices of the output, in which case the output will be a cell array of the requested output arguments. The intended use 'nthargout' is to avoid intermediate variables. For example, when finding the indices of the maximum entry of a matrix, the following two compositions of nthargout M = magic (5); cell2mat (nthargout ([1, 2], @ind2sub, size (M), nthargout (2, @max, M(:)))) => 5 3 are completely equivalent to the following lines: M = magic (5); [~, idx] = max (M(:)); [i, j] = ind2sub (size (M), idx); [i, j] => 5 3 It can also be helpful to have all output arguments in a single cell in the following manner: USV = nthargout ([1:3], @svd, hilb (5)); See also: *note nargin: XREFnargin, *note nargout: XREFnargout, *note varargin: XREFvarargin, *note varargout: XREFvarargout, *note isargout: XREFisargout. In addition to setting 'nargin' each time a function is called, Octave also automatically initializes 'nargout' to the number of values that are expected to be returned. This allows you to write functions that behave differently depending on the number of values that the user of the function has requested. The implicit assignment to the built-in variable 'ans' does not figure in the count of output arguments, so the value of 'nargout' may be zero. The 'svd' and 'lu' functions are examples of built-in functions that behave differently depending on the value of 'nargout'. It is possible to write functions that only set some return values. For example, calling the function function [x, y, z] = f () x = 1; z = 2; endfunction as [a, b, c] = f () produces: a = 1 b = [](0x0) c = 2 along with a warning. -- Built-in Function: nargout () -- Built-in Function: nargout (FCN) Report the number of output arguments from a function. Called from within a function, return the number of values the caller expects to receive. At the top level, 'nargout' with no argument is undefined and will produce an error. If called with the optional argument FCN--a function name or handle--return the number of declared output values that the function can produce. If the final output argument is VARARGOUT the returned value is negative. For example, f () will cause 'nargout' to return 0 inside the function 'f' and [s, t] = f () will cause 'nargout' to return 2 inside the function 'f'. In the second usage, nargout (@histc) % or nargout ("histc") will return 2, because 'histc' has two outputs, whereas nargout (@imread) will return -2, because 'imread' has two outputs and the second is VARARGOUT. Programming Note. 'nargout' does not work for built-in functions and returns -1 for all anonymous functions. See also: *note nargin: XREFnargin, *note varargout: XREFvarargout, *note isargout: XREFisargout, *note nthargout: XREFnthargout. It is good practice at the head of a function to verify that it has been called correctly. In Octave the following idiom is seen frequently if (nargin < min_#_inputs || nargin > max_#_inputs) print_usage (); endif which stops the function execution and prints a message about the correct way to call the function whenever the number of inputs is wrong. For compatibility with MATLAB, 'narginchk' and 'nargoutchk' are available which provide similar error checking. -- Function File: narginchk (MINARGS, MAXARGS) Check for correct number of input arguments. Generate an error message if the number of arguments in the calling function is outside the range MINARGS and MAXARGS. Otherwise, do nothing. Both MINARGS and MAXARGS must be scalar numeric values. Zero, Inf, and negative values are all allowed, and MINARGS and MAXARGS may be equal. Note that this function evaluates 'nargin' on the caller. See also: *note nargoutchk: XREFnargoutchk, *note error: XREFerror, *note nargout: XREFnargout, *note nargin: XREFnargin. -- Function File: nargoutchk (MINARGS, MAXARGS) -- Function File: MSGSTR = nargoutchk (MINARGS, MAXARGS, NARGS) -- Function File: MSGSTR = nargoutchk (MINARGS, MAXARGS, NARGS, "string") -- Function File: MSGSTRUCT = nargoutchk (MINARGS, MAXARGS, NARGS, "struct") Check for correct number of output arguments. In the first form, return an error if the number of arguments is not between MINARGS and MAXARGS. Otherwise, do nothing. Note that this function evaluates the value of 'nargout' on the caller so its value must have not been tampered with. Both MINARGS and MAXARGS must be numeric scalars. Zero, Inf, and negative are all valid, and they can have the same value. For backwards compatibility, the other forms return an appropriate error message string (or structure) if the number of outputs requested is invalid. This is useful for checking to that the number of output arguments supplied to a function is within an acceptable range. See also: *note narginchk: XREFnarginchk, *note error: XREFerror, *note nargout: XREFnargout, *note nargin: XREFnargin. Besides the number of arguments, inputs can be checked for various properties. 'validatestring' is used for string arguments and 'validateattributes' for numeric arguments. -- Function File: VALIDSTR = validatestring (STR, STRARRAY) -- Function File: VALIDSTR = validatestring (STR, STRARRAY, FUNCNAME) -- Function File: VALIDSTR = validatestring (STR, STRARRAY, FUNCNAME, VARNAME) -- Function File: VALIDSTR = validatestring (..., POSITION) Verify that STR is an element, or substring of an element, in STRARRAY. When STR is a character string to be tested, and STRARRAY is a cellstr of valid values, then VALIDSTR will be the validated form of STR where validation is defined as STR being a member or substring of VALIDSTR. This is useful for both verifying and expanding short options, such as "r", to their longer forms, such as "red". If STR is a substring of VALIDSTR, and there are multiple matches, the shortest match will be returned if all matches are substrings of each other. Otherwise, an error will be raised because the expansion of STR is ambiguous. All comparisons are case insensitive. The additional inputs FUNCNAME, VARNAME, and POSITION are optional and will make any generated validation error message more specific. Examples: validatestring ("r", {"red", "green", "blue"}) => "red" validatestring ("b", {"red", "green", "blue", "black"}) => error: validatestring: multiple unique matches were found for 'b': blue, black See also: *note strcmp: XREFstrcmp, *note strcmpi: XREFstrcmpi, *note validateattributes: XREFvalidateattributes, *note inputParser: XREFinputParser. -- Function File: validateattributes (A, CLASSES, ATTRIBUTES) -- Function File: validateattributes (A, CLASSES, ATTRIBUTES, ARG_IDX) -- Function File: validateattributes (A, CLASSES, ATTRIBUTES, FUNC_NAME) -- Function File: validateattributes (A, CLASSES, ATTRIBUTES, FUNC_NAME, ARG_NAME) -- Function File: validateattributes (A, CLASSES, ATTRIBUTES, FUNC_NAME, ARG_NAME, ARG_IDX) Check validity of input argument. Confirms that the argument A is valid by belonging to one of CLASSES, and holding all of the ATTRIBUTES. If it does not, an error is thrown, with a message formatted accordingly. The error message can be made further complete by the function name FUN_NAME, the argument name ARG_NAME, and its position in the input ARG_IDX. CLASSES must be a cell array of strings (an empty cell array is allowed) with the name of classes (remember that a class name is case sensitive). In addition to the class name, the following categories names are also valid: "float" Floating point value comprising classes "double" and "single". "integer" Integer value comprising classes (u)int8, (u)int16, (u)int32, (u)int64. "numeric" Numeric value comprising either a floating point or integer value. ATTRIBUTES must be a cell array with names of checks for A. Some of them require an additional value to be supplied right after the name (see details for each below). "<=" All values are less than or equal to the following value in ATTRIBUTES. "<" All values are less than the following value in ATTRIBUTES. ">=" All values are greater than or equal to the following value in ATTRIBUTES. ">" All values are greater than the following value in ATTRIBUTES. "2d" A 2-dimensional matrix. Note that vectors and empty matrices have 2 dimensions, one of them being of length 1, or both length 0. "3d" Has no more than 3 dimensions. A 2-dimensional matrix is a 3-D matrix whose 3rd dimension is of length 1. "binary" All values are either 1 or 0. "column" Values are arranged in a single column. "decreasing" No value is NAN, and each is less than the preceding one. "even" All values are even numbers. "finite" All values are finite. "increasing" No value is NAN, and each is greater than the preceding one. "integer" All values are integer. This is different than using 'isinteger' which only checks its an integer type. This checks that each value in A is an integer value, i.e., it has no decimal part. "ncols" Has exactly as many columns as the next value in ATTRIBUTES. "ndims" Has exactly as many dimensions as the next value in ATTRIBUTES. "nondecreasing" No value is NAN, and each is greater than or equal to the preceding one. "nonempty" It is not empty. "nonincreasing" No value is NAN, and each is less than or equal to the preceding one. "nonnan" No value is a 'NaN'. "non-negative" All values are non negative. "nonsparse" It is not a sparse matrix. "nonzero" No value is zero. "nrows" Has exactly as many rows as the next value in ATTRIBUTES. "numel" Has exactly as many elements as the next value in ATTRIBUTES. "odd" All values are odd numbers. "positive" All values are positive. "real" It is a non-complex matrix. "row" Values are arranged in a single row. "scalar" It is a scalar. "size" Its size has length equal to the values of the next in ATTRIBUTES. The next value must is an array with the length for each dimension. To ignore the check for a certain dimension, the value of 'NaN' can be used. "square" Is a square matrix. "vector" Values are arranged in a single vector (column or vector). See also: *note isa: XREFisa, *note validatestring: XREFvalidatestring, *note inputParser: XREFinputParser. If none of the preceding functions is sufficient there is also the class 'inputParser' which can perform extremely complex input checking for functions. -- Function File: P = inputParser () Create object P of the inputParser class. This class is designed to allow easy parsing of function arguments. The class supports four types of arguments: 1. mandatory (see 'addRequired'); 2. optional (see 'addOptional'); 3. named (see 'addParamValue'); 4. switch (see 'addSwitch'). After defining the function API with these methods, the supplied arguments can be parsed with the 'parse' method and the parsing results accessed with the 'Results' accessor. -- Accessor method: inputParser.Parameters Return list of parameter names already defined. -- Accessor method: inputParser.Results Return structure with argument names as fieldnames and corresponding values. -- Accessor method: inputParser.Unmatched Return structure similar to 'Results', but for unmatched parameters. See the 'KeepUnmatched' property. -- Accessor method: inputParser.UsingDefaults Return cell array with the names of arguments that are using default values. -- Class property: inputParser.CaseSensitive = BOOLEAN Set whether matching of argument names should be case sensitive. Defaults to false. -- Class property: inputParser.FunctionName = NAME Set function name to be used in error messages; Defaults to empty string. -- Class property: inputParser.KeepUnmatched = BOOLEAN Set whether an error should be given for non-defined arguments. Defaults to false. If set to true, the extra arguments can be accessed through 'Unmatched' after the 'parse' method. Note that since 'Switch' and 'ParamValue' arguments can be mixed, it is not possible to know the unmatched type. If argument is found unmatched it is assumed to be of the 'ParamValue' type and it is expected to be followed by a value. -- Class property: inputParser.StructExpand = BOOLEAN Set whether a structure can be passed to the function instead of parameter/value pairs. Defaults to true. Not implemented yet. The following example shows how to use this class: function check (varargin) p = inputParser (); # create object p.FunctionName = "check"; # set function name p.addRequired ("pack", @ischar); # mandatory argument p.addOptional ("path", pwd(), @ischar); # optional argument ## create a function handle to anonymous functions for validators val_mat = @(x) isvector (x) && all (x <= 1) && all (x >= 0); p.addOptional ("mat", [0 0], val_mat); ## create two arguments of type "ParamValue" val_type = @(x) any (strcmp (x, {"linear", "quadratic"})); p.addParamValue ("type", "linear", val_type); val_verb = @(x) any (strcmp (x, {"low", "medium", "high"})); p.addParamValue ("tolerance", "low", val_verb); ## create a switch type of argument p.addSwitch ("verbose"); p.parse (varargin{:}); # Run created parser on inputs ## the rest of the function can access inputs by using p.Results. ## for example, get the tolerance input with p.Results.tolerance endfunction check ("mech"); # valid, use defaults for other arguments check (); # error, one argument is mandatory check (1); # error, since ! ischar check ("mech", "~/dev"); # valid, use defaults for other arguments check ("mech", "~/dev", [0 1 0 0], "type", "linear"); # valid ## following is also valid. Note how the Switch argument type can ## be mixed into or before the ParamValue argument type (but it ## must still appear after any Optional argument). check ("mech", "~/dev", [0 1 0 0], "verbose", "tolerance", "high"); ## following returns an error since not all optional arguments, ## `path' and `mat', were given before the named argument `type'. check ("mech", "~/dev", "type", "linear"); _Note 1_: A function can have any mixture of the four API types but they must appear in a specific order. 'Required' arguments must be first and can be followed by any 'Optional' arguments. Only the 'ParamValue' and 'Switch' arguments may be mixed together and they must appear at the end. _Note 2_: If both 'Optional' and 'ParamValue' arguments are mixed in a function API then once a string Optional argument fails to validate it will be considered the end of the 'Optional' arguments. The remaining arguments will be compared against any 'ParamValue' or 'Switch' arguments. See also: *note nargin: XREFnargin, *note validateattributes: XREFvalidateattributes, *note validatestring: XREFvalidatestring, *note varargin: XREFvarargin.  File: octave.info, Node: Variable-length Argument Lists, Next: Ignoring Arguments, Prev: Multiple Return Values, Up: Functions and Scripts 11.4 Variable-length Argument Lists =================================== Sometimes the number of input arguments is not known when the function is defined. As an example think of a function that returns the smallest of all its input arguments. For example: a = smallest (1, 2, 3); b = smallest (1, 2, 3, 4); In this example both 'a' and 'b' would be 1. One way to write the 'smallest' function is function val = smallest (arg1, arg2, arg3, arg4, arg5) BODY endfunction and then use the value of 'nargin' to determine which of the input arguments should be considered. The problem with this approach is that it can only handle a limited number of input arguments. If the special parameter name 'varargin' appears at the end of a function parameter list it indicates that the function takes a variable number of input arguments. Using 'varargin' the function looks like this function val = smallest (varargin) BODY endfunction In the function body the input arguments can be accessed through the variable 'varargin'. This variable is a cell array containing all the input arguments. *Note Cell Arrays::, for details on working with cell arrays. The 'smallest' function can now be defined like this function val = smallest (varargin) val = min ([varargin{:}]); endfunction This implementation handles any number of input arguments, but it's also a very simple solution to the problem. A slightly more complex example of 'varargin' is a function 'print_arguments' that prints all input arguments. Such a function can be defined like this function print_arguments (varargin) for i = 1:length (varargin) printf ("Input argument %d: ", i); disp (varargin{i}); endfor endfunction This function produces output like this print_arguments (1, "two", 3); -| Input argument 1: 1 -| Input argument 2: two -| Input argument 3: 3 -- Function File: [REG, PROP] = parseparams (PARAMS) -- Function File: [REG, VAR1, ...] = parseparams (PARAMS, NAME1, DEFAULT1, ...) Return in REG the cell elements of PARAM up to the first string element and in PROP all remaining elements beginning with the first string element. For example: [reg, prop] = parseparams ({1, 2, "linewidth", 10}) reg = { [1,1] = 1 [1,2] = 2 } prop = { [1,1] = linewidth [1,2] = 10 } The parseparams function may be used to separate regular numeric arguments from additional arguments given as property/value pairs of the VARARGIN cell array. In the second form of the call, available options are specified directly with their default values given as name-value pairs. If PARAMS do not form name-value pairs, or if an option occurs that does not match any of the available options, an error occurs. When called from an m-file function, the error is prefixed with the name of the caller function. The matching of options is case-insensitive. See also: *note varargin: XREFvarargin, *note inputParser: XREFinputParser.  File: octave.info, Node: Ignoring Arguments, Next: Variable-length Return Lists, Prev: Variable-length Argument Lists, Up: Functions and Scripts 11.5 Ignoring Arguments ======================= In the formal argument list, it is possible to use the dummy placeholder '~' instead of a name. This indicates that the corresponding argument value should be ignored and not stored to any variable. function val = pick2nd (~, arg2) val = arg2; endfunction The value of 'nargin' is not affected by using this declaration. Return arguments can also be ignored using the same syntax. Functions may take advantage of ignored outputs to reduce the number of calculations performed. To do so, use the 'isargout' function to query whether the output argument is wanted. For example: function [out1, out2] = long_function (x, y, z) if (isargout (1)) ## Long calculation ... out1 = result; endif ... endfunction -- Built-in Function: isargout (K) Within a function, return a logical value indicating whether the argument K will be assigned to a variable on output. If the result is false, the argument has been ignored during the function call through the use of the tilde (~) special output argument. Functions can use 'isargout' to avoid performing unnecessary calculations for outputs which are unwanted. If K is outside the range '1:max (nargout)', the function returns false. K can also be an array, in which case the function works element-by-element and a logical array is returned. At the top level, 'isargout' returns an error. See also: *note nargout: XREFnargout, *note varargout: XREFvarargout, *note nthargout: XREFnthargout.  File: octave.info, Node: Variable-length Return Lists, Next: Returning from a Function, Prev: Ignoring Arguments, Up: Functions and Scripts 11.6 Variable-length Return Lists ================================= It is possible to return a variable number of output arguments from a function using a syntax that's similar to the one used with the special 'varargin' parameter name. To let a function return a variable number of output arguments the special output parameter name 'varargout' is used. As with 'varargin', 'varargout' is a cell array that will contain the requested output arguments. As an example the following function sets the first output argument to 1, the second to 2, and so on. function varargout = one_to_n () for i = 1:nargout varargout{i} = i; endfor endfunction When called this function returns values like this [a, b, c] = one_to_n () => a = 1 => b = 2 => c = 3 If 'varargin' ('varargout') does not appear as the last element of the input (output) parameter list, then it is not special, and is handled the same as any other parameter name. -- Function File: [R1, R2, ..., RN] = deal (A) -- Function File: [R1, R2, ..., RN] = deal (A1, A2, ..., AN) Copy the input parameters into the corresponding output parameters. If only a single input parameter is supplied, its value is copied to each of the outputs. For example, [a, b, c] = deal (x, y, z); is equivalent to a = x; b = y; c = z; and [a, b, c] = deal (x); is equivalent to a = b = c = x; Programming Note: 'deal' is often used with comma separated lists derived from cell arrays or structures. This is unnecessary as the interpreter can perform the same action without the overhead of a function call. For example: c = {[1 2], "Three", 4}; [x, y, z ] = c{:} => x = 1 2 y = Three z = 4 See also: *note cell2struct: XREFcell2struct, *note struct2cell: XREFstruct2cell, *note repmat: XREFrepmat.  File: octave.info, Node: Returning from a Function, Next: Default Arguments, Prev: Variable-length Return Lists, Up: Functions and Scripts 11.7 Returning from a Function ============================== The body of a user-defined function can contain a 'return' statement. This statement returns control to the rest of the Octave program. It looks like this: return Unlike the 'return' statement in C, Octave's 'return' statement cannot be used to return a value from a function. Instead, you must assign values to the list of return variables that are part of the 'function' statement. The 'return' statement simply makes it easier to exit a function from a deeply nested loop or conditional statement. Here is an example of a function that checks to see if any elements of a vector are nonzero. function retval = any_nonzero (v) retval = 0; for i = 1:length (v) if (v (i) != 0) retval = 1; return; endif endfor printf ("no nonzero elements found\n"); endfunction Note that this function could not have been written using the 'break' statement to exit the loop once a nonzero value is found without adding extra logic to avoid printing the message if the vector does contain a nonzero element. -- Keyword: return When Octave encounters the keyword 'return' inside a function or script, it returns control to the caller immediately. At the top level, the return statement is ignored. A 'return' statement is assumed at the end of every function definition.  File: octave.info, Node: Default Arguments, Next: Function Files, Prev: Returning from a Function, Up: Functions and Scripts 11.8 Default Arguments ====================== Since Octave supports variable number of input arguments, it is very useful to assign default values to some input arguments. When an input argument is declared in the argument list it is possible to assign a default value to the argument like this function NAME (ARG1 = VAL1, ...) BODY endfunction If no value is assigned to ARG1 by the user, it will have the value VAL1. As an example, the following function implements a variant of the classic "Hello, World" program. function hello (who = "World") printf ("Hello, %s!\n", who); endfunction When called without an input argument the function prints the following hello (); -| Hello, World! and when it's called with an input argument it prints the following hello ("Beautiful World of Free Software"); -| Hello, Beautiful World of Free Software! Sometimes it is useful to explicitly tell Octave to use the default value of an input argument. This can be done writing a ':' as the value of the input argument when calling the function. hello (:); -| Hello, World!  File: octave.info, Node: Function Files, Next: Script Files, Prev: Default Arguments, Up: Functions and Scripts 11.9 Function Files =================== Except for simple one-shot programs, it is not practical to have to define all the functions you need each time you need them. Instead, you will normally want to save them in a file so that you can easily edit them, and save them for use at a later time. Octave does not require you to load function definitions from files before using them. You simply need to put the function definitions in a place where Octave can find them. When Octave encounters an identifier that is undefined, it first looks for variables or functions that are already compiled and currently listed in its symbol table. If it fails to find a definition there, it searches a list of directories (the "path") for files ending in '.m' that have the same base name as the undefined identifier.(1) Once Octave finds a file with a name that matches, the contents of the file are read. If it defines a _single_ function, it is compiled and executed. *Note Script Files::, for more information about how you can define more than one function in a single file. When Octave defines a function from a function file, it saves the full name of the file it read and the time stamp on the file. If the time stamp on the file changes, Octave may reload the file. When Octave is running interactively, time stamp checking normally happens at most once each time Octave prints the prompt. Searching for new function definitions also occurs if the current working directory changes. Checking the time stamp allows you to edit the definition of a function while Octave is running, and automatically use the new function definition without having to restart your Octave session. To avoid degrading performance unnecessarily by checking the time stamps on functions that are not likely to change, Octave assumes that function files in the directory tree 'OCTAVE-HOME/share/octave/VERSION/m' will not change, so it doesn't have to check their time stamps every time the functions defined in those files are used. This is normally a very good assumption and provides a significant improvement in performance for the function files that are distributed with Octave. If you know that your own function files will not change while you are running Octave, you can improve performance by calling 'ignore_function_time_stamp ("all")', so that Octave will ignore the time stamps for all function files. Passing "system" to this function resets the default behavior. -- Command: edit NAME -- Command: edit FIELD VALUE -- Command: VALUE = edit get FIELD Edit the named function, or change editor settings. If 'edit' is called with the name of a file or function as its argument it will be opened in the text editor defined by 'EDITOR'. * If the function NAME is available in a file on your path and that file is modifiable, then it will be edited in place. If it is a system function, then it will first be copied to the directory 'HOME' (see below) and then edited. If no file is found, then the m-file variant, ending with ".m", will be considered. If still no file is found, then variants with a leading "@" and then with both a leading "@" and trailing ".m" will be considered. * If NAME is the name of a function defined in the interpreter but not in an m-file, then an m-file will be created in 'HOME' to contain that function along with its current definition. * If 'NAME.cc' is specified, then it will search for 'NAME.cc' in the path and try to modify it, otherwise it will create a new '.cc' file in the current directory. If NAME happens to be an m-file or interpreter defined function, then the text of that function will be inserted into the .cc file as a comment. * If 'NAME.ext' is on your path then it will be edited, otherwise the editor will be started with 'NAME.ext' in the current directory as the filename. If 'NAME.ext' is not modifiable, it will be copied to 'HOME' before editing. *Warning:* You may need to clear NAME before the new definition is available. If you are editing a .cc file, you will need to execute 'mkoctfile NAME.cc' before the definition will be available. If 'edit' is called with FIELD and VALUE variables, the value of the control field FIELD will be set to VALUE. If an output argument is requested and the first input argument is 'get' then 'edit' will return the value of the control field FIELD. If the control field does not exist, edit will return a structure containing all fields and values. Thus, 'edit get all' returns a complete control structure. The following control fields are used: 'home' This is the location of user local m-files. Be sure it is in your path. The default is '~/octave'. 'author' This is the name to put after the "## Author:" field of new functions. By default it guesses from the 'gecos' field of the password database. 'email' This is the e-mail address to list after the name in the author field. By default it guesses '<$LOGNAME@$HOSTNAME>', and if '$HOSTNAME' is not defined it uses 'uname -n'. You probably want to override this. Be sure to use the format ''. 'license' 'gpl' GNU General Public License (default). 'bsd' BSD-style license without advertising clause. 'pd' Public domain. '"text"' Your own default copyright and license. Unless you specify 'pd', edit will prepend the copyright statement with "Copyright (C) yyyy Function Author". 'mode' This value determines whether the editor should be started in async mode (editor is started in the background and Octave continues) or sync mode (Octave waits until the editor exits). Set it to "sync" to start the editor in sync mode. The default is "async" (*note system: XREFsystem.). 'editinplace' Determines whether files should be edited in place, without regard to whether they are modifiable or not. The default is 'false'. -- Built-in Function: mfilename () -- Built-in Function: mfilename ("fullpath") -- Built-in Function: mfilename ("fullpathext") Return the name of the currently executing file. When called from outside an m-file return the empty string. Given the argument "fullpath", include the directory part of the file name, but not the extension. Given the argument "fullpathext", include the directory part of the file name and the extension. -- Built-in Function: VAL = ignore_function_time_stamp () -- Built-in Function: OLD_VAL = ignore_function_time_stamp (NEW_VAL) Query or set the internal variable that controls whether Octave checks the time stamp on files each time it looks up functions defined in function files. If the internal variable is set to "system", Octave will not automatically recompile function files in subdirectories of 'OCTAVE-HOME/lib/VERSION' if they have changed since they were last compiled, but will recompile other function files in the search path if they change. If set to "all", Octave will not recompile any function files unless their definitions are removed with 'clear'. If set to "none", Octave will always check time stamps on files to determine whether functions defined in function files need to recompiled. * Menu: * Manipulating the Load Path:: * Subfunctions:: * Private Functions:: * Nested Functions:: * Overloading and Autoloading:: * Function Locking:: * Function Precedence:: ---------- Footnotes ---------- (1) The '.m' suffix was chosen for compatibility with MATLAB.  File: octave.info, Node: Manipulating the Load Path, Next: Subfunctions, Up: Function Files 11.9.1 Manipulating the Load Path --------------------------------- When a function is called, Octave searches a list of directories for a file that contains the function declaration. This list of directories is known as the load path. By default the load path contains a list of directories distributed with Octave plus the current working directory. To see your current load path call the 'path' function without any input or output arguments. It is possible to add or remove directories to or from the load path using 'addpath' and 'rmpath'. As an example, the following code adds '~/Octave' to the load path. addpath ("~/Octave") After this the directory '~/Octave' will be searched for functions. -- Built-in Function: addpath (DIR1, ...) -- Built-in Function: addpath (DIR1, ..., OPTION) Add named directories to the function search path. If OPTION is "-begin" or 0 (the default), prepend the directory name to the current path. If OPTION is "-end" or 1, append the directory name to the current path. Directories added to the path must exist. In addition to accepting individual directory arguments, lists of directory names separated by 'pathsep' are also accepted. For example: addpath ("dir1:/dir2:~/dir3") See also: *note path: XREFpath, *note rmpath: XREFrmpath, *note genpath: XREFgenpath, *note pathdef: XREFpathdef, *note savepath: XREFsavepath, *note pathsep: XREFpathsep. -- Built-in Function: genpath (DIR) -- Built-in Function: genpath (DIR, SKIP, ...) Return a path constructed from DIR and all its subdirectories. If additional string parameters are given, the resulting path will exclude directories with those names. -- Built-in Function: rmpath (DIR1, ...) Remove DIR1, ... from the current function search path. In addition to accepting individual directory arguments, lists of directory names separated by 'pathsep' are also accepted. For example: rmpath ("dir1:/dir2:~/dir3") See also: *note path: XREFpath, *note addpath: XREFaddpath, *note genpath: XREFgenpath, *note pathdef: XREFpathdef, *note savepath: XREFsavepath, *note pathsep: XREFpathsep. -- Function File: savepath () -- Function File: savepath (FILE) -- Function File: STATUS = savepath (...) Save the unique portion of the current function search path that is not set during Octave's initialization process to FILE. If FILE is omitted, Octave looks in the current directory for a project-specific '.octaverc' file in which to save the path information. If no such file is present then the user's configuration file '~/.octaverc' is used. If successful, 'savepath' returns 0. The 'savepath' function makes it simple to customize a user's configuration file to restore the working paths necessary for a particular instance of Octave. Assuming no filename is specified, Octave will automatically restore the saved directory paths from the appropriate '.octaverc' file when starting up. If a filename has been specified then the paths may be restored manually by calling 'source FILE'. See also: *note path: XREFpath, *note addpath: XREFaddpath, *note rmpath: XREFrmpath, *note genpath: XREFgenpath, *note pathdef: XREFpathdef. -- Built-in Function: path (...) Modify or display Octave's load path. If NARGIN and NARGOUT are zero, display the elements of Octave's load path in an easy to read format. If NARGIN is zero and nargout is greater than zero, return the current load path. If NARGIN is greater than zero, concatenate the arguments, separating them with 'pathsep'. Set the internal search path to the result and return it. No checks are made for duplicate elements. See also: *note addpath: XREFaddpath, *note rmpath: XREFrmpath, *note genpath: XREFgenpath, *note pathdef: XREFpathdef, *note savepath: XREFsavepath, *note pathsep: XREFpathsep. -- Function File: VAL = pathdef () Return the default path for Octave. The path information is extracted from one of four sources. The possible sources, in order of preference, are: 1. '.octaverc' 2. '~/.octaverc' 3. '/...//m/startup/octaverc' 4. Octave's path prior to changes by any octaverc file. See also: *note path: XREFpath, *note addpath: XREFaddpath, *note rmpath: XREFrmpath, *note genpath: XREFgenpath, *note savepath: XREFsavepath. -- Built-in Function: VAL = pathsep () -- Built-in Function: OLD_VAL = pathsep (NEW_VAL) Query or set the character used to separate directories in a path. See also: *note filesep: XREFfilesep. -- Built-in Function: rehash () Reinitialize Octave's load path directory cache. -- Built-in Function: file_in_loadpath (FILE) -- Built-in Function: file_in_loadpath (FILE, "all") Return the absolute name of FILE if it can be found in the list of directories specified by 'path'. If no file is found, return an empty character string. If the first argument is a cell array of strings, search each directory of the loadpath for element of the cell array and return the first that matches. If the second optional argument "all" is supplied, return a cell array containing the list of all files that have the same name in the path. If no files are found, return an empty cell array. See also: *note file_in_path: XREFfile_in_path, *note dir_in_loadpath: XREFdir_in_loadpath, *note path: XREFpath. -- Built-in Function: restoredefaultpath (...) Restore Octave's path to its initial state at startup. See also: *note path: XREFpath, *note addpath: XREFaddpath, *note rmpath: XREFrmpath, *note genpath: XREFgenpath, *note pathdef: XREFpathdef, *note savepath: XREFsavepath, *note pathsep: XREFpathsep. -- Built-in Function: command_line_path (...) Return the command line path variable. See also: *note path: XREFpath, *note addpath: XREFaddpath, *note rmpath: XREFrmpath, *note genpath: XREFgenpath, *note pathdef: XREFpathdef, *note savepath: XREFsavepath, *note pathsep: XREFpathsep. -- Built-in Function: dir_in_loadpath (DIR) -- Built-in Function: dir_in_loadpath (DIR, "all") Return the full name of the path element matching DIR. The match is performed at the end of each path element. For example, if DIR is "foo/bar", it matches the path element "/some/dir/foo/bar", but not "/some/dir/foo/bar/baz" "/some/dir/allfoo/bar". If the optional second argument is supplied, return a cell array containing all name matches rather than just the first. See also: *note file_in_path: XREFfile_in_path, *note file_in_loadpath: XREFfile_in_loadpath, *note path: XREFpath.  File: octave.info, Node: Subfunctions, Next: Private Functions, Prev: Manipulating the Load Path, Up: Function Files 11.9.2 Subfunctions ------------------- A function file may contain secondary functions called "subfunctions". These secondary functions are only visible to the other functions in the same function file. For example, a file 'f.m' containing function f () printf ("in f, calling g\n"); g () endfunction function g () printf ("in g, calling h\n"); h () endfunction function h () printf ("in h\n") endfunction defines a main function 'f' and two subfunctions. The subfunctions 'g' and 'h' may only be called from the main function 'f' or from the other subfunctions, but not from outside the file 'f.m'.  File: octave.info, Node: Private Functions, Next: Nested Functions, Prev: Subfunctions, Up: Function Files 11.9.3 Private Functions ------------------------ In many cases one function needs to access one or more helper functions. If the helper function is limited to the scope of a single function, then subfunctions as discussed above might be used. However, if a single helper function is used by more than one function, then this is no longer possible. In this case the helper functions might be placed in a subdirectory, called "private", of the directory in which the functions needing access to this helper function are found. As a simple example, consider a function 'func1', that calls a helper function 'func2' to do much of the work. For example: function y = func1 (x) y = func2 (x); endfunction Then if the path to 'func1' is '/func1.m', and if 'func2' is found in the directory '/private/func2.m', then 'func2' is only available for use of the functions, like 'func1', that are found in ''.  File: octave.info, Node: Nested Functions, Next: Overloading and Autoloading, Prev: Private Functions, Up: Function Files 11.9.4 Nested Functions ----------------------- Nested functions are similar to subfunctions in that only the main function is visible outside the file. However, they also allow for child functions to access the local variables in their parent function. This shared access mimics using a global variable to share information -- but a global variable which is not visible to the rest of Octave. As a programming strategy, sharing data this way can create code which is difficult to maintain. It is recommended to use subfunctions in place of nested functions when possible. As a simple example, consider a parent function 'foo', that calls a nested child function 'bar', with a shared variable X. function y = foo () x = 10; bar (); y = x; function bar () x = 20; endfunction endfunction foo () => 20 Notice that there is no special syntax for sharing X. This can lead to problems with accidental variable sharing between a parent function and its child. While normally variables are inherited, child function parameters and return values are local to the child function. Now consider the function 'foobar' that uses variables X and Y. 'foobar' calls a nested function 'foo' which takes X as a parameter and returns Y. 'foo' then calls 'bat' which does some computation. function z = foobar () x = 0; y = 0; z = foo (5); z += x + y; function y = foo (x) y = x + bat (); function z = bat () z = x; endfunction endfunction endfunction foobar () => 10 It is important to note that the X and Y in 'foobar' remain zero, as in 'foo' they are a return value and parameter respectively. The X in 'bat' refers to the X in 'foo'. Variable inheritance leads to a problem for 'eval' and scripts. If a new variable is created in a parent function, it is not clear what should happen in nested child functions. For example, consider a parent function 'foo' with a nested child function 'bar': function y = foo (to_eval) bar (); eval (to_eval); function bar () eval ("x = 100;"); eval ("y = x;"); endfunction endfunction foo ("x = 5;") => error: can not add variable "x" to a static workspace foo ("y = 10;") => 10 foo ("") => 100 The parent function 'foo' is unable to create a new variable X, but the child function 'bar' was successful. Furthermore, even in an 'eval' statement Y in 'bar' is the same Y as in its parent function 'foo'. The use of 'eval' in conjunction with nested functions is best avoided. As with subfunctions, only the first nested function in a file may be called from the outside. Inside a function the rules are more complicated. In general a nested function may call: 0. Globally visible functions 1. Any function that the nested function's parent can call 2. Sibling functions (functions that have the same parents) 3. Direct children As a complex example consider a parent function 'ex_top' with two child functions, 'ex_a' and 'ex_b'. In addition, 'ex_a' has two more child functions, 'ex_aa' and 'ex_ab'. For example: function ex_top () ## Can call: ex_top, ex_a, and ex_b ## Can NOT call: ex_aa and ex_ab function ex_a () ## Call call everything function ex_aa () ## Can call everything endfunction function ex_ab () ## Can call everything endfunction endfunction function ex_b () ## Can call: ex_top, ex_a, and ex_b ## Can NOT call: ex_aa and ex_ab endfunction endfunction  File: octave.info, Node: Overloading and Autoloading, Next: Function Locking, Prev: Nested Functions, Up: Function Files 11.9.5 Overloading and Autoloading ---------------------------------- Functions can be overloaded to work with different input arguments. For example, the operator '+' has been overloaded in Octave to work with single, double, uint8, int32, and many other arguments. The preferred way to overload functions is through classes and object oriented programming (*note Function Overloading::). Occasionally, however, one needs to undo user overloading and call the default function associated with a specific type. The 'builtin' function exists for this purpose. -- Built-in Function: [...] = builtin (F, ...) Call the base function F even if F is overloaded to another function for the given type signature. This is normally useful when doing object-oriented programming and there is a requirement to call one of Octave's base functions rather than the overloaded one of a new class. A trivial example which redefines the 'sin' function to be the 'cos' function shows how 'builtin' works. sin (0) => 0 function y = sin (x), y = cos (x); endfunction sin (0) => 1 builtin ("sin", 0) => 0 A single dynamically linked file might define several functions. However, as Octave searches for functions based on the functions filename, Octave needs a manner in which to find each of the functions in the dynamically linked file. On operating systems that support symbolic links, it is possible to create a symbolic link to the original file for each of the functions which it contains. However, there is at least one well known operating system that doesn't support symbolic links. Making copies of the original file for each of the functions is undesirable as it increases the amount of disk space used by Octave. Instead Octave supplies the 'autoload' function, that permits the user to define in which file a certain function will be found. -- Built-in Function: AUTOLOAD_MAP = autoload () -- Built-in Function: autoload (FUNCTION, FILE) -- Built-in Function: autoload (..., "remove") Define FUNCTION to autoload from FILE. The second argument, FILE, should be an absolute file name or a file name in the same directory as the function or script from which the autoload command was run. FILE _should not_ depend on the Octave load path. Normally, calls to 'autoload' appear in PKG_ADD script files that are evaluated when a directory is added to Octave's load path. To avoid having to hardcode directory names in FILE, if FILE is in the same directory as the PKG_ADD script then autoload ("foo", "bar.oct"); will load the function 'foo' from the file 'bar.oct'. The above usage when 'bar.oct' is not in the same directory, or usages such as autoload ("foo", file_in_loadpath ("bar.oct")) are strongly discouraged, as their behavior may be unpredictable. With no arguments, return a structure containing the current autoload map. If a third argument "remove" is given, the function is cleared and not loaded anymore during the current Octave session. See also: *note PKG_ADD: XREFPKG_ADD.  File: octave.info, Node: Function Locking, Next: Function Precedence, Prev: Overloading and Autoloading, Up: Function Files 11.9.6 Function Locking ----------------------- It is sometime desirable to lock a function into memory with the 'mlock' function. This is typically used for dynamically linked functions in Oct-files or mex-files that contain some initialization, and it is desirable that calling 'clear' does not remove this initialization. As an example, function my_function () mlock (); ... prevents 'my_function' from being removed from memory after it is called, even if 'clear' is called. It is possible to determine if a function is locked into memory with the 'mislocked', and to unlock a function with 'munlock', which the following illustrates. my_function (); mislocked ("my_function") => ans = 1 munlock ("my_function"); mislocked ("my_function") => ans = 0 A common use of 'mlock' is to prevent persistent variables from being removed from memory, as the following example shows: function count_calls () mlock (); persistent calls = 0; printf ("'count_calls' has been called %d times\n", ++calls); endfunction count_calls (); -| 'count_calls' has been called 1 times clear count_calls count_calls (); -| 'count_calls' has been called 2 times 'mlock' might equally be used to prevent changes to a function from having effect in Octave, though a similar effect can be had with the 'ignore_function_time_stamp' function. -- Built-in Function: mlock () Lock the current function into memory so that it can't be cleared. See also: *note munlock: XREFmunlock, *note mislocked: XREFmislocked, *note persistent: XREFpersistent. -- Built-in Function: munlock () -- Built-in Function: munlock (FCN) Unlock the named function FCN. If no function is named then unlock the current function. See also: *note mlock: XREFmlock, *note mislocked: XREFmislocked, *note persistent: XREFpersistent. -- Built-in Function: mislocked () -- Built-in Function: mislocked (FCN) Return true if the named function FCN is locked. If no function is named then return true if the current function is locked. See also: *note mlock: XREFmlock, *note munlock: XREFmunlock, *note persistent: XREFpersistent.  File: octave.info, Node: Function Precedence, Prev: Function Locking, Up: Function Files 11.9.7 Function Precedence -------------------------- Given the numerous different ways that Octave can define a function, it is possible and even likely that multiple versions of a function, might be defined within a particular scope. The precedence of which function will be used within a particular scope is given by 1. Subfunction A subfunction with the required function name in the given scope. 2. Private function A function defined within a private directory of the directory which contains the current function. 3. Class constructor A function that constructs a user class as defined in chapter *note Object Oriented Programming::. 4. Class method An overloaded function of a class as in chapter *note Object Oriented Programming::. 5. Command-line Function A function that has been defined on the command-line. 6. Autoload function A function that is marked as autoloaded with *Note autoload: XREFautoload. 7. A Function on the Path A function that can be found on the users load-path. There can also be Oct-file, mex-file or m-file versions of this function and the precedence between these versions are in that order. 8. Built-in function A function that is a part of core Octave such as 'numel', 'size', etc.  File: octave.info, Node: Script Files, Next: Function Handles Anonymous Functions Inline Functions, Prev: Function Files, Up: Functions and Scripts 11.10 Script Files ================== A script file is a file containing (almost) any sequence of Octave commands. It is read and evaluated just as if you had typed each command at the Octave prompt, and provides a convenient way to perform a sequence of commands that do not logically belong inside a function. Unlike a function file, a script file must _not_ begin with the keyword 'function'. If it does, Octave will assume that it is a function file, and that it defines a single function that should be evaluated as soon as it is defined. A script file also differs from a function file in that the variables named in a script file are not local variables, but are in the same scope as the other variables that are visible on the command line. Even though a script file may not begin with the 'function' keyword, it is possible to define more than one function in a single script file and load (but not execute) all of them at once. To do this, the first token in the file (ignoring comments and other white space) must be something other than 'function'. If you have no other statements to evaluate, you can use a statement that has no effect, like this: # Prevent Octave from thinking that this # is a function file: 1; # Define function one: function one () ... To have Octave read and compile these functions into an internal form, you need to make sure that the file is in Octave's load path (accessible through the 'path' function), then simply type the base name of the file that contains the commands. (Octave uses the same rules to search for script files as it does to search for function files.) If the first token in a file (ignoring comments) is 'function', Octave will compile the function and try to execute it, printing a message warning about any non-whitespace characters that appear after the function definition. Note that Octave does not try to look up the definition of any identifier until it needs to evaluate it. This means that Octave will compile the following statements if they appear in a script file, or are typed at the command line, # not a function file: 1; function foo () do_something (); endfunction function do_something () do_something_else (); endfunction even though the function 'do_something' is not defined before it is referenced in the function 'foo'. This is not an error because Octave does not need to resolve all symbols that are referenced by a function until the function is actually evaluated. Since Octave doesn't look for definitions until they are needed, the following code will always print 'bar = 3' whether it is typed directly on the command line, read from a script file, or is part of a function body, even if there is a function or script file called 'bar.m' in Octave's path. eval ("bar = 3"); bar Code like this appearing within a function body could fool Octave if definitions were resolved as the function was being compiled. It would be virtually impossible to make Octave clever enough to evaluate this code in a consistent fashion. The parser would have to be able to perform the call to 'eval' at compile time, and that would be impossible unless all the references in the string to be evaluated could also be resolved, and requiring that would be too restrictive (the string might come from user input, or depend on things that are not known until the function is evaluated). Although Octave normally executes commands from script files that have the name 'FILE.m', you can use the function 'source' to execute commands from any file. -- Built-in Function: source (FILE) Parse and execute the contents of FILE. This is equivalent to executing commands from a script file, but without requiring the file to be named 'FILE.m'. See also: *note run: XREFrun.  File: octave.info, Node: Function Handles Anonymous Functions Inline Functions, Next: Commands, Prev: Script Files, Up: Functions and Scripts 11.11 Function Handles, Anonymous Functions, Inline Functions ============================================================= It can be very convenient store a function in a variable so that it can be passed to a different function. For example, a function that performs numerical minimization needs access to the function that should be minimized. * Menu: * Function Handles:: * Anonymous Functions:: * Inline Functions::  File: octave.info, Node: Function Handles, Next: Anonymous Functions, Up: Function Handles Anonymous Functions Inline Functions 11.11.1 Function Handles ------------------------ A function handle is a pointer to another function and is defined with the syntax @FUNCTION-NAME For example, f = @sin; creates a function handle called 'f' that refers to the function 'sin'. Function handles are used to call other functions indirectly, or to pass a function as an argument to another function like 'quad' or 'fsolve'. For example: f = @sin; quad (f, 0, pi) => 2 You may use 'feval' to call a function using function handle, or simply write the name of the function handle followed by an argument list. If there are no arguments, you must use an empty argument list '()'. For example: f = @sin; feval (f, pi/4) => 0.70711 f (pi/4) => 0.70711 -- Built-in Function: is_function_handle (X) Return true if X is a function handle. See also: *note isa: XREFisa, *note typeinfo: XREFtypeinfo, *note class: XREFclass, *note functions: XREFfunctions. -- Built-in Function: S = functions (FCN_HANDLE) Return a structure containing information about the function handle FCN_HANDLE. The structure S always contains these three fields: function The function name. For an anonymous function (no name) this will be the actual function definition. type Type of the function. anonymous The function is anonymous. private The function is private. overloaded The function overloads an existing function. simple The function is a built-in or m-file function. subfunction The function is a subfunction within an m-file. file The m-file that will be called to perform the function. This field is empty for anonymous and built-in functions. In addition, some function types may return more information in additional fields. *Warning:* 'functions' is provided for debugging purposes only. It's behavior may change in the future and programs should not depend on a particular output. -- Built-in Function: func2str (FCN_HANDLE) Return a string containing the name of the function referenced by the function handle FCN_HANDLE. See also: *note str2func: XREFstr2func, *note functions: XREFfunctions. -- Built-in Function: str2func (FCN_NAME) -- Built-in Function: str2func (FCN_NAME, "global") Return a function handle constructed from the string FCN_NAME. If the optional "global" argument is passed, locally visible functions are ignored in the lookup. See also: *note func2str: XREFfunc2str, *note inline: XREFinline.  File: octave.info, Node: Anonymous Functions, Next: Inline Functions, Prev: Function Handles, Up: Function Handles Anonymous Functions Inline Functions 11.11.2 Anonymous Functions --------------------------- Anonymous functions are defined using the syntax @(ARGUMENT-LIST) EXPRESSION Any variables that are not found in the argument list are inherited from the enclosing scope. Anonymous functions are useful for creating simple unnamed functions from expressions or for wrapping calls to other functions to adapt them for use by functions like 'quad'. For example, f = @(x) x.^2; quad (f, 0, 10) => 333.33 creates a simple unnamed function from the expression 'x.^2' and passes it to 'quad', quad (@(x) sin (x), 0, pi) => 2 wraps another function, and a = 1; b = 2; quad (@(x) betainc (x, a, b), 0, 0.4) => 0.13867 adapts a function with several parameters to the form required by 'quad'. In this example, the values of A and B that are passed to 'betainc' are inherited from the current environment. Note that for performance reasons it is better to use handles to existing Octave functions, rather than to define anonymous functions which wrap an existing function. The integration of 'sin (x)' is 5X faster if the code is written as quad (@sin, 0, pi) rather than using the anonymous function '@(x) sin (x)'. There are many operators which have functional equivalents that may be better choices than an anonymous function. Instead of writing f = @(x, y) x + y this should be coded as f = @plus *Note Operator Overloading::, for a list of operators which also have a functional form.  File: octave.info, Node: Inline Functions, Prev: Anonymous Functions, Up: Function Handles Anonymous Functions Inline Functions 11.11.3 Inline Functions ------------------------ An inline function is created from a string containing the function body using the 'inline' function. The following code defines the function f(x) = x^2 + 2. f = inline ("x^2 + 2"); After this it is possible to evaluate f at any x by writing 'f(x)'. *Caution*: MATLAB has begun the process of deprecating inline functions. At some point in the future support will be dropped and eventually Octave will follow MATLAB and also remove inline functions. Use anonymous functions in all new code. -- Built-in Function: inline (STR) -- Built-in Function: inline (STR, ARG1, ...) -- Built-in Function: inline (STR, N) Create an inline function from the character string STR. If called with a single argument, the arguments of the generated function are extracted from the function itself. The generated function arguments will then be in alphabetical order. It should be noted that i and j are ignored as arguments due to the ambiguity between their use as a variable or their use as an built-in constant. All arguments followed by a parenthesis are considered to be functions. If no arguments are found, a function taking a single argument named 'x' will be created. If the second and subsequent arguments are character strings, they are the names of the arguments of the function. If the second argument is an integer N, the arguments are "x", "P1", ..., "PN". Programming Note: The use of 'inline' is discouraged and it may be removed from a future version of Octave. The preferred way to create functions from strings is through the use of anonymous functions (*note Anonymous Functions::) or 'str2func'. See also: *note argnames: XREFargnames, *note formula: XREFformula, *note vectorize: XREFvectorize, *note str2func: XREFstr2func. -- Built-in Function: argnames (FUN) Return a cell array of character strings containing the names of the arguments of the inline function FUN. See also: *note inline: XREFinline, *note formula: XREFformula, *note vectorize: XREFvectorize. -- Built-in Function: formula (FUN) Return a character string representing the inline function FUN. Note that 'char (FUN)' is equivalent to 'formula (FUN)'. See also: *note char: XREFchar, *note argnames: XREFargnames, *note inline: XREFinline, *note vectorize: XREFvectorize. -- Function File: VARS = symvar (STR) Identify the symbolic variable names in the string STR. Common constant names such as 'i', 'j', 'pi', 'Inf' and Octave functions such as 'sin' or 'plot' are ignored. Any names identified are returned in a cell array of strings. The array is empty if no variables were found. Example: symvar ("x^2 + y^2 == 4") => { [1,1] = x [2,1] = y }  File: octave.info, Node: Commands, Next: Organization of Functions, Prev: Function Handles Anonymous Functions Inline Functions, Up: Functions and Scripts 11.12 Commands ============== Commands are a special class of functions that only accept string input arguments. A command can be called as an ordinary function, but it can also be called without the parentheses. For example, my_command hello world is equivalent to my_command ("hello", "world") The general form of a command call is CMDNAME ARG1 ARG2 ... which translates directly to CMDNAME ("ARG1", "ARG2", ...) Any regular function can be used as a command if it accepts string input arguments. For example: toupper lower_case_arg => ans = LOWER_CASE_ARG One difficulty of commands occurs when one of the string input arguments is stored in a variable. Because Octave can't tell the difference between a variable name and an ordinary string, it is not possible to pass a variable as input to a command. In such a situation a command must be called as a function. For example: strvar = "hello world"; toupper strvar => ans = STRVAR toupper (strvar) => ans = HELLO WORLD  File: octave.info, Node: Organization of Functions, Prev: Commands, Up: Functions and Scripts 11.13 Organization of Functions Distributed with Octave ======================================================= Many of Octave's standard functions are distributed as function files. They are loosely organized by topic, in subdirectories of 'OCTAVE-HOME/lib/octave/VERSION/m', to make it easier to find them. The following is a list of all the function file subdirectories, and the types of functions you will find there. 'audio' Functions for playing and recording sounds. 'deprecated' Out-of-date functions which will eventually be removed from Octave. 'elfun' Elementary functions, principally trigonometric. '@ftp' Class functions for the FTP object. 'general' Miscellaneous matrix manipulations, like 'flipud', 'rot90', and 'triu', as well as other basic functions, like 'ismatrix', 'narginchk', etc. 'geometry' Functions related to Delaunay triangulation. 'help' Functions for Octave's built-in help system. 'image' Image processing tools. These functions require the X Window System. 'io' Input-output functions. 'linear-algebra' Functions for linear algebra. 'miscellaneous' Functions that don't really belong anywhere else. 'optimization' Functions related to minimization, optimization, and root finding. 'path' Functions to manage the directory path Octave uses to find functions. 'pkg' Package manager for installing external packages of functions in Octave. 'plot' Functions for displaying and printing two- and three-dimensional graphs. 'polynomial' Functions for manipulating polynomials. 'prefs' Functions implementing user-defined preferences. 'set' Functions for creating and manipulating sets of unique values. 'signal' Functions for signal processing applications. 'sparse' Functions for handling sparse matrices. 'specfun' Special functions such as 'bessel' or 'factor'. 'special-matrix' Functions that create special matrix forms such as Hilbert or Vandermonde matrices. 'startup' Octave's system-wide startup file. 'statistics' Statistical functions. 'strings' Miscellaneous string-handling functions. 'testfun' Functions for performing unit tests on other functions. 'time' Functions related to time and date processing.  File: octave.info, Node: Errors and Warnings, Next: Debugging, Prev: Functions and Scripts, Up: Top 12 Errors and Warnings ********************** Octave includes several functions for printing error and warning messages. When you write functions that need to take special action when they encounter abnormal conditions, you should print the error messages using the functions described in this chapter. Since many of Octave's functions use these functions, it is also useful to understand them, so that errors and warnings can be handled. * Menu: * Handling Errors:: * Handling Warnings::  File: octave.info, Node: Handling Errors, Next: Handling Warnings, Up: Errors and Warnings 12.1 Handling Errors ==================== An error is something that occurs when a program is in a state where it doesn't make sense to continue. An example is when a function is called with too few input arguments. In this situation the function should abort with an error message informing the user of the lacking input arguments. Since an error can occur during the evaluation of a program, it is very convenient to be able to detect that an error occurred, so that the error can be fixed. This is possible with the 'try' statement described in *note The try Statement::. * Menu: * Raising Errors:: * Catching Errors:: * Recovering From Errors::  File: octave.info, Node: Raising Errors, Next: Catching Errors, Up: Handling Errors 12.1.1 Raising Errors --------------------- The most common use of errors is for checking input arguments to functions. The following example calls the 'error' function if the function 'f' is called without any input arguments. function f (arg1) if (nargin == 0) error ("not enough input arguments"); endif endfunction When the 'error' function is called, it prints the given message and returns to the Octave prompt. This means that no code following a call to 'error' will be executed. -- Built-in Function: error (TEMPLATE, ...) -- Built-in Function: error (ID, TEMPLATE, ...) Display an error message and stop m-file execution. Format the optional arguments under the control of the template string TEMPLATE using the same rules as the 'printf' family of functions (*note Formatted Output::) and print the resulting message on the 'stderr' stream. The message is prefixed by the character string 'error: '. Calling 'error' also sets Octave's internal error state such that control will return to the top level without evaluating any further commands. This is useful for aborting from functions or scripts. If the error message does not end with a newline character, Octave will print a traceback of all the function calls leading to the error. For example, given the following function definitions: function f () g (); end function g () h (); end function h () nargin == 1 || error ("nargin != 1"); end calling the function 'f' will result in a list of messages that can help you to quickly locate the exact location of the error: f () error: nargin != 1 error: called from: error: error at line -1, column -1 error: h at line 1, column 27 error: g at line 1, column 15 error: f at line 1, column 15 If the error message ends in a newline character, Octave will print the message but will not display any traceback messages as it returns control to the top level. For example, modifying the error message in the previous example to end in a newline causes Octave to only print a single message: function h () nargin == 1 || error ("nargin != 1\n"); end f () error: nargin != 1 A null string ("") input to 'error' will be ignored and the code will continue running as if the statement were a NOP. This is for compatibility with MATLAB. It also makes it possible to write code such as err_msg = ""; if (CONDITION 1) err_msg = "CONDITION 1 found"; elseif (CONDITION2) err_msg = "CONDITION 2 found"; ... endif error (err_msg); which will only stop execution if an error has been found. Implementation Note: For compatibility with MATLAB, escape sequences in TEMPLATE (e.g., "\n" => newline) are processed regardless of whether TEMPLATE has been defined with single quotes, as long as there are two or more input arguments. To disable escape sequence expansion use a second backslash before the sequence (e.g., "\\n") or use the 'regexptranslate' function. See also: *note warning: XREFwarning, *note lasterror: XREFlasterror. Since it is common to use errors when there is something wrong with the input to a function, Octave supports functions to simplify such code. When the 'print_usage' function is called, it reads the help text of the function calling 'print_usage', and presents a useful error. If the help text is written in Texinfo it is possible to present an error message that only contains the function prototypes as described by the '@deftypefn' parts of the help text. When the help text isn't written in Texinfo, the error message contains the entire help message. Consider the following function. ## -*- texinfo -*- ## @deftypefn {Function File} f (@var{arg1}) ## Function help text goes here... ## @end deftypefn function f (arg1) if (nargin == 0) print_usage (); endif endfunction When it is called with no input arguments it produces the following error. f () -| error: Invalid call to f. Correct usage is: -| -| -- Function File: f (ARG1) -| -| -| Additional help for built-in functions and operators is -| available in the online version of the manual. Use the command -| `doc ' to search the manual index. -| -| Help and information about Octave is also available on the WWW -| at http://www.octave.org and via the help@octave.org -| mailing list. -- Function File: print_usage () -- Function File: print_usage (NAME) Print the usage message for the function NAME. When called with no input arguments the 'print_usage' function displays the usage message of the currently executing function. See also: *note help: XREFhelp. -- Function File: beep () Produce a beep from the speaker (or visual bell). This function sends the alarm character "\a" to the terminal. Depending on the user's configuration this may produce an audible beep, a visual bell, or nothing at all. See also: *note puts: XREFputs, *note fputs: XREFfputs, *note printf: XREFprintf, *note fprintf: XREFfprintf. -- Built-in Function: VAL = beep_on_error () -- Built-in Function: OLD_VAL = beep_on_error (NEW_VAL) -- Built-in Function: beep_on_error (NEW_VAL, "local") Query or set the internal variable that controls whether Octave will try to ring the terminal bell before printing an error message. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.  File: octave.info, Node: Catching Errors, Next: Recovering From Errors, Prev: Raising Errors, Up: Handling Errors 12.1.2 Catching Errors ---------------------- When an error occurs, it can be detected and handled using the 'try' statement as described in *note The try Statement::. As an example, the following piece of code counts the number of errors that occurs during a 'for' loop. number_of_errors = 0; for n = 1:100 try ... catch number_of_errors++; end_try_catch endfor The above example treats all errors the same. In many situations it can however be necessary to discriminate between errors, and take different actions depending on the error. The 'lasterror' function returns a structure containing information about the last error that occurred. As an example, the code above could be changed to count the number of errors related to the '*' operator. number_of_errors = 0; for n = 1:100 try ... catch msg = lasterror.message; if (strfind (msg, "operator *")) number_of_errors++; endif end_try_catch endfor Alternatively, the output of the 'lasterror' function can be found in a variable indicated immediately after the 'catch' keyword, as in the example below showing how to redirect an error as a warning: try ... catch err warning(err.identifier, err.message); ... end_try_catch -- Built-in Function: LASTERR = lasterror () -- Built-in Function: lasterror (ERR) -- Built-in Function: lasterror ("reset") Query or set the last error message structure. When called without arguments, return a structure containing the last error message and other information related to this error. The elements of the structure are: 'message' The text of the last error message 'identifier' The message identifier of this error message 'stack' A structure containing information on where the message occurred. This may be an empty structure if the information cannot be obtained. The fields of the structure are: 'file' The name of the file where the error occurred 'name' The name of function in which the error occurred 'line' The line number at which the error occurred 'column' An optional field with the column number at which the error occurred The last error structure may be set by passing a scalar structure, ERR, as input. Any fields of ERR that match those above are set while any unspecified fields are initialized with default values. If 'lasterror' is called with the argument "reset", all fields are set to their default values. See also: *note lasterr: XREFlasterr, *note error: XREFerror, *note lastwarn: XREFlastwarn. -- Built-in Function: [MSG, MSGID] = lasterr () -- Built-in Function: lasterr (MSG) -- Built-in Function: lasterr (MSG, MSGID) Query or set the last error message. When called without input arguments, return the last error message and message identifier. With one argument, set the last error message to MSG. With two arguments, also set the last message identifier. See also: *note lasterror: XREFlasterror, *note error: XREFerror, *note lastwarn: XREFlastwarn. It is also possible to assign an identification string to an error. If an error has such an ID the user can catch this error as will be shown in the next example. To assign an ID to an error, simply call 'error' with two string arguments, where the first is the identification string, and the second is the actual error. Note that error IDs are in the format "NAMESPACE:ERROR-NAME". The namespace "Octave" is used for Octave's own errors. Any other string is available as a namespace for user's own errors. The next example counts indexing errors. The errors are caught using the field identifier of the structure returned by the function 'lasterror'. number_of_errors = 0; for n = 1:100 try ... catch id = lasterror.identifier; if (strcmp (id, "Octave:invalid-indexing")) number_of_errors++; endif end_try_catch endfor The functions distributed with Octave can issue one of the following errors. 'Octave:invalid-context' Indicates the error was generated by an operation that cannot be executed in the scope from which it was called. For example, the function 'print_usage ()' when called from the Octave prompt raises this error. 'Octave:invalid-input-arg' Indicates that a function was called with invalid input arguments. 'Octave:invalid-fun-call' Indicates that a function was called in an incorrect way, e.g., wrong number of input arguments. 'Octave:invalid-indexing' Indicates that a data-type was indexed incorrectly, e.g., real-value index for arrays, nonexistent field of a structure. 'Octave:bad-alloc' Indicates that memory couldn't be allocated. 'Octave:undefined-function' Indicates a call to a function that is not defined. The function may exist but Octave is unable to find it in the search path. When an error has been handled it is possible to raise it again. This can be useful when an error needs to be detected, but the program should still abort. This is possible using the 'rethrow' function. The previous example can now be changed to count the number of errors related to the '*' operator, but still abort if another kind of error occurs. number_of_errors = 0; for n = 1:100 try ... catch msg = lasterror.message; if (strfind (msg, "operator *")) number_of_errors++; else rethrow (lasterror); endif end_try_catch endfor -- Built-in Function: rethrow (ERR) Reissue a previous error as defined by ERR. ERR is a structure that must contain at least the "message" and "identifier" fields. ERR can also contain a field "stack" that gives information on the assumed location of the error. Typically ERR is returned from 'lasterror'. See also: *note lasterror: XREFlasterror, *note lasterr: XREFlasterr, *note error: XREFerror. -- Built-in Function: ERR = errno () -- Built-in Function: ERR = errno (VAL) -- Built-in Function: ERR = errno (NAME) Return the current value of the system-dependent variable errno, set its value to VAL and return the previous value, or return the named error code given NAME as a character string, or -1 if NAME is not found. See also: *note errno_list: XREFerrno_list. -- Built-in Function: errno_list () Return a structure containing the system-dependent errno values. See also: *note errno: XREFerrno.  File: octave.info, Node: Recovering From Errors, Prev: Catching Errors, Up: Handling Errors 12.1.3 Recovering From Errors ----------------------------- Octave provides several ways of recovering from errors. There are 'try'/'catch' blocks, 'unwind_protect'/'unwind_protect_cleanup' blocks, and finally the 'onCleanup' command. The 'onCleanup' command associates an ordinary Octave variable (the trigger) with an arbitrary function (the action). Whenever the Octave variable ceases to exist--whether due to a function return, an error, or simply because the variable has been removed with 'clear'--then the assigned function is executed. The function can do anything necessary for cleanup such as closing open file handles, printing an error message, or restoring global variables to their initial values. The last example is a very convenient idiom for Octave code. For example: function rand42 old_state = rand ("state"); restore_state = onCleanup (@() rand ("state", old_state)); rand ("state", 42); ... endfunction # rand generator state restored by onCleanup -- Built-in Function: OBJ = onCleanup (FUNCTION) Create a special object that executes a given function upon destruction. If the object is copied to multiple variables (or cell or struct array elements) or returned from a function, FUNCTION will be executed after clearing the last copy of the object. Note that if multiple local onCleanup variables are created, the order in which they are called is unspecified. For similar functionality *Note The unwind_protect Statement::.  File: octave.info, Node: Handling Warnings, Prev: Handling Errors, Up: Errors and Warnings 12.2 Handling Warnings ====================== Like an error, a warning is issued when something unexpected happens. Unlike an error, a warning doesn't abort the currently running program. A simple example of a warning is when a number is divided by zero. In this case Octave will issue a warning and assign the value 'Inf' to the result. a = 1/0 -| warning: division by zero => a = Inf * Menu: * Issuing Warnings:: * Enabling and Disabling Warnings::  File: octave.info, Node: Issuing Warnings, Next: Enabling and Disabling Warnings, Up: Handling Warnings 12.2.1 Issuing Warnings ----------------------- It is possible to issue warnings from any code using the 'warning' function. In its most simple form, the 'warning' function takes a string describing the warning as its input argument. As an example, the following code controls if the variable 'a' is non-negative, and if not issues a warning and sets 'a' to zero. a = -1; if (a < 0) warning ("'a' must be non-negative. Setting 'a' to zero."); a = 0; endif -| 'a' must be non-negative. Setting 'a' to zero. Since warnings aren't fatal to a running program, it is not possible to catch a warning using the 'try' statement or something similar. It is however possible to access the last warning as a string using the 'lastwarn' function. It is also possible to assign an identification string to a warning. If a warning has such an ID the user can enable and disable this warning as will be described in the next section. To assign an ID to a warning, simply call 'warning' with two string arguments, where the first is the identification string, and the second is the actual warning. Note that warning IDs are in the format "NAMESPACE:WARNING-NAME". The namespace "Octave" is used for Octave's own warnings. Any other string is available as a namespace for user's own warnings. -- Built-in Function: warning (TEMPLATE, ...) -- Built-in Function: warning (ID, TEMPLATE, ...) -- Built-in Function: warning ("on", ID) -- Built-in Function: warning ("off", ID) -- Built-in Function: warning ("query", ID) -- Built-in Function: warning ("error", ID) -- Built-in Function: warning (STATE, "backtrace") -- Built-in Function: warning (STATE, ID, "local") Display a warning message or control the behavior of Octave's warning system. Format the optional arguments under the control of the template string TEMPLATE using the same rules as the 'printf' family of functions (*note Formatted Output::) and print the resulting message on the 'stderr' stream. The message is prefixed by the character string 'warning: '. You should use this function when you want to notify the user of an unusual condition, but only when it makes sense for your program to go on. The optional message identifier allows users to enable or disable warnings tagged by ID. A message identifier is of the form "NAMESPACE:WARNING-NAME". Octave's own warnings use the "Octave" namespace (*note XREFwarning_ids::). The special identifier "all" may be used to set the state of all warnings. If the first argument is "on" or "off", set the state of a particular warning using the identifier ID. If the first argument is "query", query the state of this warning instead. If the identifier is omitted, a value of "all" is assumed. If you set the state of a warning to "error", the warning named by ID is handled as if it were an error instead. So, for example, the following handles all warnings as errors: warning ("error"); If the state is "on" or "off" and the third argument is "backtrace", then a stack trace is printed along with the warning message when warnings occur inside function calls. This option is enabled by default. If the state is "on", "off", or "error" and the third argument is "local", then the warning state will be set temporarily, until the end of the current function. Changes to warning states that are set locally affect the current function and all functions called from the current scope. The previous warning state is restored on return from the current function. The "local" option is ignored if used in the top-level workspace. Implementation Note: For compatibility with MATLAB, escape sequences in TEMPLATE (e.g., "\n" => newline) are processed regardless of whether TEMPLATE has been defined with single quotes, as long as there are two or more input arguments. To disable escape sequence expansion use a second backslash before the sequence (e.g., "\\n") or use the 'regexptranslate' function. See also: *note warning_ids: XREFwarning_ids, *note lastwarn: XREFlastwarn, *note error: XREFerror. -- Built-in Function: [MSG, MSGID] = lastwarn () -- Built-in Function: lastwarn (MSG) -- Built-in Function: lastwarn (MSG, MSGID) Query or set the last warning message. When called without input arguments, return the last warning message and message identifier. With one argument, set the last warning message to MSG. With two arguments, also set the last message identifier. See also: *note warning: XREFwarning, *note lasterror: XREFlasterror, *note lasterr: XREFlasterr. The functions distributed with Octave can issue one of the following warnings. 'Octave:abbreviated-property-match' By default, the 'Octave:abbreviated-property-match' warning is enabled. 'Octave:array-to-scalar' If the 'Octave:array-to-scalar' warning is enabled, Octave will warn when an implicit conversion from an array to a scalar value is attempted. By default, the 'Octave:array-to-scalar' warning is disabled. 'Octave:array-to-vector' If the 'Octave:array-to-vector' warning is enabled, Octave will warn when an implicit conversion from an array to a vector value is attempted. By default, the 'Octave:array-to-vector' warning is disabled. 'Octave:assign-as-truth-value' If the 'Octave:assign-as-truth-value' warning is enabled, a warning is issued for statements like if (s = t) ... since such statements are not common, and it is likely that the intent was to write if (s == t) ... instead. There are times when it is useful to write code that contains assignments within the condition of a 'while' or 'if' statement. For example, statements like while (c = getc ()) ... are common in C programming. It is possible to avoid all warnings about such statements by disabling the 'Octave:assign-as-truth-value' warning, but that may also let real errors like if (x = 1) # intended to test (x == 1)! ... 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 while ((c = getc ())) ... will prevent the warning from being printed for this statement, while allowing Octave to warn about other assignments used in conditional contexts. By default, the 'Octave:assign-as-truth-value' warning is enabled. 'Octave:associativity-change' If the 'Octave:associativity-change' warning is enabled, Octave will warn about possible changes in the meaning of some code due to changes in associativity for some operators. Associativity changes have typically been made for MATLAB compatibility. By default, the 'Octave:associativity-change' warning is enabled. 'Octave:autoload-relative-file-name' If the 'Octave:autoload-relative-file-name' is enabled, Octave will warn when parsing autoload() function calls with relative paths to function files. This usually happens when using autoload() calls in PKG_ADD files, when the PKG_ADD file is not in the same directory as the .oct file referred to by the autoload() command. By default, the 'Octave:autoload-relative-file-name' warning is enabled. 'Octave:built-in-variable-assignment' By default, the 'Octave:built-in-variable-assignment' warning is enabled. 'Octave:deprecated-keyword' If the 'Octave:deprecated-keyword' warning is enabled, a warning is issued when Octave encounters a keyword that is obsolete and scheduled for removal from Octave. By default, the 'Octave:deprecated-keyword' warning is enabled. 'Octave:divide-by-zero' If the 'Octave:divide-by-zero' warning is enabled, a warning is issued when Octave encounters a division by zero. By default, the 'Octave:divide-by-zero' warning is enabled. 'Octave:fopen-file-in-path' By default, the 'Octave:fopen-file-in-path' warning is enabled. 'Octave:function-name-clash' If the 'Octave:function-name-clash' warning is enabled, 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 names disagree, the name declared inside the file is ignored.) By default, the 'Octave:function-name-clash' warning is enabled. 'Octave:future-time-stamp' If the 'Octave:future-time-stamp' warning is enabled, Octave will print a warning if it finds a function file with a time stamp that is in the future. By default, the 'Octave:future-time-stamp' warning is enabled. 'Octave:glyph-render' By default, the 'Octave:glyph-render' warning is enabled. 'Octave:imag-to-real' If the 'Octave:imag-to-real' warning is enabled, a warning is printed for implicit conversions of complex numbers to real numbers. By default, the 'Octave:imag-to-real' warning is disabled. 'Octave:language-extension' Print warnings when using features that are unique to the Octave language and that may still be missing in MATLAB. By default, the 'Octave:language-extension' warning is disabled. The '--traditional' or '--braindead' startup options for Octave may also be of use, *note Command Line Options::. 'Octave:load-file-in-path' By default, the 'Octave:load-file-in-path' warning is enabled. 'Octave:logical-conversion' By default, the 'Octave:logical-conversion' warning is enabled. 'Octave:md5sum-file-in-path' By default, the 'Octave:md5sum-file-in-path' warning is enabled. 'Octave:missing-glyph' By default, the 'Octave:missing-glyph' warning is enabled. 'Octave:missing-semicolon' If the 'Octave:missing-semicolon' warning is enabled, Octave will warn when statements in function definitions don't end in semicolons. By default the 'Octave:missing-semicolon' warning is disabled. 'Octave:mixed-string-concat' If the 'Octave:mixed-string-concat' warning is enabled, print a warning when concatenating a mixture of double and single quoted strings. By default, the 'Octave:mixed-string-concat' warning is disabled. 'Octave:neg-dim-as-zero' If the 'Octave:neg-dim-as-zero' warning is enabled, print a warning for expressions like eye (-1) By default, the 'Octave:neg-dim-as-zero' warning is disabled. 'Octave:nested-functions-coerced' By default, the 'Octave:nested-functions-coerced' warning is enabled. 'Octave:noninteger-range-as-index' By default, the 'Octave:noninteger-range-as-index' warning is enabled. 'Octave:num-to-str' If the 'Octave:num-to-str' warning is enable, a warning is printed for implicit conversions of numbers to their ASCII character equivalents when strings are constructed using a mixture of strings and numbers in matrix notation. For example, [ "f", 111, 111 ] => "foo" elicits a warning if the 'Octave:num-to-str' warning is enabled. By default, the 'Octave:num-to-str' warning is enabled. 'Octave:possible-matlab-short-circuit-operator' If the 'Octave:possible-matlab-short-circuit-operator' warning is enabled, Octave will warn about using the not short circuiting operators '&' and '|' inside 'if' or 'while' conditions. They normally never short circuit, but MATLAB always short circuits if any logical operators are used in a condition. You can turn on the option do_braindead_shortcircuit_evaluation (1) if you would like to enable this short-circuit evaluation in Octave. Note that the '&&' and '||' operators always short circuit in both Octave and MATLAB, so it's only necessary to enable MATLAB-style short-circuiting if it's too arduous to modify existing code that relies on this behavior. By default, the 'Octave:possible-matlab-short-circuit-operator' warning is enabled. 'Octave:precedence-change' If the 'Octave:precedence-change' warning is enabled, Octave will warn about possible changes in the meaning of some code due to changes in precedence for some operators. Precedence changes have typically been made for MATLAB compatibility. By default, the 'Octave:precedence-change' warning is enabled. 'Octave:recursive-path-search' By default, the 'Octave:recursive-path-search' warning is enabled. 'Octave:remove-init-dir' The 'path' function changes the search path that Octave uses to find functions. It is possible to set the path to a value which excludes Octave's own built-in functions. If the 'Octave:remove-init-dir' warning is enabled then Octave will warn when the 'path' function has been used in a way that may render Octave unworkable. By default, the 'Octave:remove-init-dir' warning is enabled. 'Octave:reload-forces-clear' If several functions have been loaded from the same file, Octave must clear all the functions before any one of them can be reloaded. If the 'Octave:reload-forces-clear' warning is enabled, Octave will warn you when this happens, and print a list of the additional functions that it is forced to clear. By default, the 'Octave:reload-forces-clear' warning is enabled. 'Octave:resize-on-range-error' If the 'Octave:resize-on-range-error' warning is enabled, print a warning when a matrix is resized by an indexed assignment with indices outside the current bounds. By default, the ## 'Octave:resize-on-range-error' warning is disabled. 'Octave:separator-insert' Print warning if commas or semicolons might be inserted automatically in literal matrices. By default, the 'Octave:separator-insert' warning is disabled. 'Octave:shadowed-function' By default, the 'Octave:shadowed-function' warning is enabled. 'Octave:single-quote-string' Print warning if a single quote character is used to introduce a string constant. By default, the 'Octave:single-quote-string' warning is disabled. 'Octave:nearly-singular-matrix' 'Octave:singular-matrix' By default, the 'Octave:nearly-singular-matrix' and 'Octave:singular-matrix' warnings are enabled. 'Octave:sqrtm:SingularMatrix' By default, the 'Octave:sqrtm:SingularMatrix' warning is enabled. 'Octave:str-to-num' If the 'Octave:str-to-num' warning is enabled, a warning is printed for implicit conversions of strings to their numeric ASCII equivalents. For example, "abc" + 0 => 97 98 99 elicits a warning if the 'Octave:str-to-num' warning is enabled. By default, the 'Octave:str-to-num' warning is disabled. 'Octave:undefined-return-values' If the 'Octave:undefined-return-values' warning is disabled, print a warning if a function does not define all the values in the return list which are expected. By default, the 'Octave:undefined-return-values' warning is enabled. 'Octave:variable-switch-label' If the 'Octave:variable-switch-label' warning is enabled, Octave will print a warning if a switch label is not a constant or constant expression. By default, the 'Octave:variable-switch-label' warning is disabled.  File: octave.info, Node: Enabling and Disabling Warnings, Prev: Issuing Warnings, Up: Handling Warnings 12.2.2 Enabling and Disabling Warnings -------------------------------------- The 'warning' function also allows you to control which warnings are actually printed to the screen. If the 'warning' function is called with a string argument that is either "on" or "off" all warnings will be enabled or disabled. It is also possible to enable and disable individual warnings through their string identifications. The following code will issue a warning warning ("example:non-negative-variable", "'a' must be non-negative. Setting 'a' to zero."); while the following won't issue a warning warning ("off", "example:non-negative-variable"); warning ("example:non-negative-variable", "'a' must be non-negative. Setting 'a' to zero.");  File: octave.info, Node: Debugging, Next: Input and Output, Prev: Errors and Warnings, Up: Top 13 Debugging ************ Octave includes a built-in debugger to aid in the development of scripts. This can be used to interrupt the execution of an Octave script at a certain point, or when certain conditions are met. Once execution has stopped, and debug mode is entered, the symbol table at the point where execution has stopped can be examined and modified to check for errors. The normal command-line editing and history functions are available in debug mode. * Menu: * Entering Debug Mode:: * Leaving Debug Mode:: * Breakpoints:: * Debug Mode:: * Call Stack:: * Profiling:: * Profiler Example::  File: octave.info, Node: Entering Debug Mode, Next: Leaving Debug Mode, Up: Debugging 13.1 Entering Debug Mode ======================== There are two basic means of interrupting the execution of an Octave script. These are breakpoints (*note Breakpoints::), discussed in the next section, and interruption based on some condition. Octave supports three means to stop execution based on the values set in the functions 'debug_on_interrupt', 'debug_on_warning', and 'debug_on_error'. -- Built-in Function: VAL = debug_on_interrupt () -- Built-in Function: OLD_VAL = debug_on_interrupt (NEW_VAL) -- Built-in Function: debug_on_interrupt (NEW_VAL, "local") Query or set the internal variable that controls whether Octave will try to enter debugging mode when it receives an interrupt signal (typically generated with 'C-c'). If a second interrupt signal is received before reaching the debugging mode, a normal interrupt will occur. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note debug_on_error: XREFdebug_on_error, *note debug_on_warning: XREFdebug_on_warning. -- Built-in Function: VAL = debug_on_warning () -- Built-in Function: OLD_VAL = debug_on_warning (NEW_VAL) -- Built-in Function: debug_on_warning (NEW_VAL, "local") Query or set the internal variable that controls whether Octave will try to enter the debugger when a warning is encountered. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note debug_on_error: XREFdebug_on_error, *note debug_on_interrupt: XREFdebug_on_interrupt. -- Built-in Function: VAL = debug_on_error () -- Built-in Function: OLD_VAL = debug_on_error (NEW_VAL) -- Built-in Function: debug_on_error (NEW_VAL, "local") Query or set the internal variable that controls whether Octave will try to enter the debugger when an error is encountered. This will also inhibit printing of the normal traceback message (you will only see the top-level error message). When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note debug_on_warning: XREFdebug_on_warning, *note debug_on_interrupt: XREFdebug_on_interrupt.  File: octave.info, Node: Leaving Debug Mode, Next: Breakpoints, Prev: Entering Debug Mode, Up: Debugging 13.2 Leaving Debug Mode ======================= Use either 'dbcont' or 'return' to leave the debug mode and continue the normal execution of the script. -- Command: dbcont Leave command-line debugging mode and continue code execution normally. See also: *note dbstep: XREFdbstep, *note dbquit: XREFdbquit. To quit debug mode and return directly to the prompt without executing any additional code use 'dbquit'. -- Command: dbquit Quit debugging mode immediately without further code execution and return to the Octave prompt. See also: *note dbcont: XREFdbcont, *note dbstep: XREFdbstep. Finally, typing 'exit' or 'quit' at the debug prompt will result in Octave terminating normally.  File: octave.info, Node: Breakpoints, Next: Debug Mode, Prev: Leaving Debug Mode, Up: Debugging 13.3 Breakpoints ================ Breakpoints can be set in any m-file function by using the 'dbstop' function. -- Command: dbstop FUNC -- Command: dbstop FUNC LINE -- Command: dbstop FUNC LINE1 LINE2 ... -- Command: dbstop LINE ... -- Built-in Function: RLINE = dbstop ("FUNC") -- Built-in Function: RLINE = dbstop ("FUNC", LINE) -- Built-in Function: RLINE = dbstop ("FUNC", LINE1, LINE2, ...) -- Built-in Function: dbstop ("FUNC", [LINE1, ...]) -- Built-in Function: dbstop (LINE, ...) Set a breakpoint at line number LINE in function FUNC. Arguments are FUNC Function name as a string variable. When already in debug mode this argument can be omitted and the current function will be used. LINE Line number where the breakpoint should be set. Multiple lines may be given as separate arguments or as a vector. When called with a single argument FUNC, the breakpoint is set at the first executable line in the named function. The optional output RLINE is the real line number where the breakpoint was set. This can differ from the specified line if the line is not executable. For example, if a breakpoint attempted on a blank line then Octave will set the real breakpoint at the next executable line. See also: *note dbclear: XREFdbclear, *note dbstatus: XREFdbstatus, *note dbstep: XREFdbstep, *note debug_on_error: XREFdebug_on_error, *note debug_on_warning: XREFdebug_on_warning, *note debug_on_interrupt: XREFdebug_on_interrupt. Breakpoints in class methods are also supported (e.g., 'dbstop ("@class/method")'). However, breakpoints cannot be set in built-in functions (e.g., 'sin', etc.) or dynamically loaded functions (i.e., oct-files). To set a breakpoint immediately upon entering a function use line number 1, or omit the line number entirely and just give the function name. When setting the breakpoint Octave will ignore the leading comment block, and the breakpoint will be set on the first executable statement in the function. For example: dbstop ("asind", 1) => 29 Note that the return value of '29' means that the breakpoint was effectively set to line 29. The status of breakpoints in a function can be queried with 'dbstatus'. -- Built-in Function: dbstatus () -- Built-in Function: BRK_LIST = dbstatus () -- Built-in Function: BRK_LIST = dbstatus ("FUNC") Report the location of active breakpoints. When called with no input or output arguments, print the list of all functions with breakpoints and the line numbers where those breakpoints are set. If a function name FUNC is specified then only report breakpoints for the named function. The optional return argument BRK_LIST is a struct array with the following fields. name The name of the function with a breakpoint. file The name of the m-file where the function code is located. line A line number, or vector of line numbers, with a breakpoint. Note: When 'dbstatus' is called from the debug prompt within a function, the list of breakpoints is automatically trimmed to the breakpoints in the current function. See also: *note dbclear: XREFdbclear, *note dbwhere: XREFdbwhere. Reusing the previous example, 'dbstatus ("asind")' will return 29. The breakpoints listed can then be cleared with the 'dbclear' function. -- Command: dbclear FUNC -- Command: dbclear FUNC LINE -- Command: dbclear FUNC LINE1 LINE2 ... -- Command: dbclear LINE ... -- Command: dbclear all -- Built-in Function: dbclear ("FUNC") -- Built-in Function: dbclear ("FUNC", LINE) -- Built-in Function: dbclear ("FUNC", LINE1, LINE2, ...) -- Built-in Function: dbclear ("FUNC", [LINE1, ...]) -- Built-in Function: dbclear (LINE, ...) -- Built-in Function: dbclear ("all") Delete a breakpoint at line number LINE in the function FUNC. Arguments are FUNC Function name as a string variable. When already in debug mode this argument can be omitted and the current function will be used. LINE Line number from which to remove a breakpoint. Multiple lines may be given as separate arguments or as a vector. When called without a line number specification all breakpoints in the named function are cleared. If the requested line is not a breakpoint no action is performed. The special keyword "all" will clear all breakpoints from all files. See also: *note dbstop: XREFdbstop, *note dbstatus: XREFdbstatus, *note dbwhere: XREFdbwhere. A breakpoint may also be set in a subfunction. For example, if a file contains the functions function y = func1 (x) y = func2 (x); endfunction function y = func2 (x) y = x + 1; endfunction then a breakpoint can be set at the start of the subfunction directly with dbstop (["func1", filemarker(), "func2"]) => 5 Note that 'filemarker' returns the character that marks subfunctions from the file containing them. Unless the default has been changed this character is '>'. Thus, a quicker and more normal way to set the breakpoint would be dbstop func1>func2 Another simple way of setting a breakpoint in an Octave script is the use of the 'keyboard' function. -- Built-in Function: keyboard () -- Built-in Function: keyboard ("PROMPT") Stop m-file execution and enter debug mode. When the '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 if necessary. To leave the prompt and return to normal execution type 'return' or 'dbcont'. The 'keyboard' function does not return an exit status. If 'keyboard' is invoked without arguments, a default prompt of 'debug> ' is used. See also: *note dbstop: XREFdbstop, *note dbcont: XREFdbcont, *note dbquit: XREFdbquit. The 'keyboard' function is placed in a script at the point where the user desires that the execution be stopped. It automatically sets the running script into the debug mode.  File: octave.info, Node: Debug Mode, Next: Call Stack, Prev: Breakpoints, Up: Debugging 13.4 Debug Mode =============== There are three additional support functions that allow the user to find out where in the execution of a script Octave entered the debug mode, and to print the code in the script surrounding the point where Octave entered debug mode. -- Command: dbwhere In debugging mode, report the current file and line number where execution is stopped. See also: *note dbstatus: XREFdbstatus, *note dbcont: XREFdbcont, *note dbstep: XREFdbstep, *note dbup: XREFdbup. -- Command: dbtype -- Command: dbtype LINENO -- Command: dbtype STARTL:ENDL -- Command: dbtype STARTL:END -- Command: dbtype FUNC -- Command: dbtype FUNC LINENO -- Command: dbtype FUNC STARTL:ENDL -- Command: dbtype FUNC STARTL:END Display a script file with line numbers. When called with no arguments in debugging mode, display the script file currently being debugged. An optional range specification can be used to list only a portion of the file. The special keyword "end" is a valid line number specification for the last line of the file. When called with the name of a function, list that script file with line numbers. See also: *note dbwhere: XREFdbwhere, *note dbstatus: XREFdbstatus, *note dbstop: XREFdbstop. -- Command: dblist -- Command: dblist N In debugging mode, list N lines of the function being debugged centered around the current line to be executed. If unspecified N defaults to 10 (+/- 5 lines) See also: *note dbwhere: XREFdbwhere, *note dbtype: XREFdbtype. You may also use 'isdebugmode' to determine whether the debugger is currently active. -- Built-in Function: isdebugmode () Return true if in debugging mode, otherwise false. See also: *note dbwhere: XREFdbwhere, *note dbstack: XREFdbstack, *note dbstatus: XREFdbstatus. Debug mode also allows single line stepping through a function using the command 'dbstep'. -- Command: dbstep -- Command: dbstep N -- Command: dbstep in -- Command: dbstep out -- Command: dbnext ... In debugging mode, execute the next N lines of code. If N is omitted, execute the next single line of code. If the next line of code is itself defined in terms of an m-file remain in the existing function. Using 'dbstep in' will cause execution of the next line to step into any m-files defined on the next line. Using 'dbstep out' will cause execution to continue until the current function returns. 'dbnext' is an alias for 'dbstep'. See also: *note dbcont: XREFdbcont, *note dbquit: XREFdbquit. When in debug mode the key will execute the last entered command. This is useful, for example, after hitting a breakpoint and entering 'dbstep' once. After that, one can advance line by line through the code with only a single key stroke.  File: octave.info, Node: Call Stack, Next: Profiling, Prev: Debug Mode, Up: Debugging 13.5 Call Stack =============== The function being debugged may be the leaf node of a series of function calls. After examining values in the current subroutine it may turn out that the problem occurred in earlier pieces of code. Use 'dbup' and 'dbdown' to move up and down through the series of function calls to locate where variables first took on the wrong values. 'dbstack' shows the entire series of function calls and at what level debugging is currently taking place. -- Command: dbstack -- Command: dbstack N -- Command: dbstack -COMPLETENAMES -- Built-in Function: [STACK, IDX] = dbstack (...) Display or return current debugging function stack information. With optional argument N, omit the N innermost stack frames. Although accepted, the argument -COMPLETENAMES is silently ignored. Octave always returns absolute file names. The arguments N and -COMPLETENAMES can be both specified in any order. The optional return argument STACK is a struct array with the following fields: file The name of the m-file where the function code is located. name The name of the function with a breakpoint. line The line number of an active breakpoint. column The column number of the line where the breakpoint begins. scope Undocumented. context Undocumented. The return argument IDX specifies which element of the STACK struct array is currently active. See also: *note dbup: XREFdbup, *note dbdown: XREFdbdown, *note dbwhere: XREFdbwhere, *note dbstatus: XREFdbstatus. -- Command: dbup -- Command: dbup N In debugging mode, move up the execution stack N frames. If N is omitted, move up one frame. See also: *note dbstack: XREFdbstack, *note dbdown: XREFdbdown. -- Command: dbdown -- Command: dbdown N In debugging mode, move down the execution stack N frames. If N is omitted, move down one frame. See also: *note dbstack: XREFdbstack, *note dbup: XREFdbup.  File: octave.info, Node: Profiling, Next: Profiler Example, Prev: Call Stack, Up: Debugging 13.6 Profiling ============== Octave supports profiling of code execution on a per-function level. If profiling is enabled, each call to a function (supporting built-ins, operators, functions in oct- and mex-files, user-defined functions in Octave code and anonymous functions) is recorded while running Octave code. After that, this data can aid in analyzing the code behavior, and is in particular helpful for finding "hot spots" in the code which use up a lot of computation time and are the best targets to spend optimization efforts on. The main command for profiling is 'profile', which can be used to start or stop the profiler and also to query collected data afterwards. The data is returned in an Octave data structure which can then be examined or further processed by other routines or tools. -- Command: profile on -- Command: profile off -- Command: profile resume -- Command: profile clear -- Function File: S = profile ("status") -- Function File: T = profile ("info") Control the built-in profiler. 'profile on' Start the profiler, clearing all previously collected data if there is any. 'profile off' Stop profiling. The collected data can later be retrieved and examined with 'T = profile ("info")'. 'profile clear' Clear all collected profiler data. 'profile resume' Restart profiling without clearing the old data. All newly collected statistics are added to the existing ones. 'S = profile ("status")' Return a structure with information about the current status of the profiler. At the moment, the only field is 'ProfilerStatus' which is either "on" or "off". 'T = profile ("info")' Return the collected profiling statistics in the structure T. The flat profile is returned in the field 'FunctionTable' which is an array of structures, each entry corresponding to a function which was called and for which profiling statistics are present. In addition, the field 'Hierarchical' contains the hierarchical call tree. Each node has an index into the 'FunctionTable' identifying the function it corresponds to as well as data fields for number of calls and time spent at this level in the call tree. See also: *note profshow: XREFprofshow, *note profexplore: XREFprofexplore. An easy way to get an overview over the collected data is 'profshow'. This function takes the profiler data returned by 'profile' as input and prints a flat profile, for instance: Function Attr Time (s) Calls ---------------------------------------- >myfib R 2.195 13529 binary <= 0.061 13529 binary - 0.050 13528 binary + 0.026 6764 This shows that most of the run time was spent executing the function 'myfib', and some minor proportion evaluating the listed binary operators. Furthermore, it is shown how often the function was called and the profiler also records that it is recursive. -- Function File: profshow (DATA) -- Function File: profshow (DATA, N) -- Function File: profshow () -- Function File: profshow (N) Display flat per-function profiler results. Print out profiler data (execution time, number of calls) for the most critical N functions. The results are sorted in descending order by the total time spent in each function. If N is unspecified it defaults to 20. The input DATA is the structure returned by 'profile ("info")'. If unspecified, 'profshow' will use the current profile dataset. The attribute column displays 'R' for recursive functions, and is blank for all other function types. See also: *note profexplore: XREFprofexplore, *note profile: XREFprofile. -- Function File: profexplore () -- Function File: profexplore (DATA) Interactively explore hierarchical profiler output. Assuming DATA is the structure with profile data returned by 'profile ("info")', this command opens an interactive prompt that can be used to explore the call-tree. Type 'help' to get a list of possible commands. If DATA is omitted, 'profile ("info")' is called and used in its place. See also: *note profile: XREFprofile, *note profshow: XREFprofshow.  File: octave.info, Node: Profiler Example, Prev: Profiling, Up: Debugging 13.7 Profiler Example ===================== Below, we will give a short example of a profiler session. *Note Profiling::, for the documentation of the profiler functions in detail. Consider the code: global N A; N = 300; A = rand (N, N); function xt = timesteps (steps, x0, expM) global N; if (steps == 0) xt = NA (N, 0); else xt = NA (N, steps); x1 = expM * x0; xt(:, 1) = x1; xt(:, 2 : end) = timesteps (steps - 1, x1, expM); endif endfunction function foo () global N A; initial = @(x) sin (x); x0 = (initial (linspace (0, 2 * pi, N)))'; expA = expm (A); xt = timesteps (100, x0, expA); endfunction function fib = bar (N) if (N <= 2) fib = 1; else fib = bar (N - 1) + bar (N - 2); endif endfunction If we execute the two main functions, we get: tic; foo; toc; => Elapsed time is 2.37338 seconds. tic; bar (20); toc; => Elapsed time is 2.04952 seconds. But this does not give much information about where this time is spent; for instance, whether the single call to 'expm' is more expensive or the recursive time-stepping itself. To get a more detailed picture, we can use the profiler. profile on; foo; profile off; data = profile ("info"); profshow (data, 10); This prints a table like: # Function Attr Time (s) Calls --------------------------------------------- 7 expm 1.034 1 3 binary * 0.823 117 41 binary \ 0.188 1 38 binary ^ 0.126 2 43 timesteps R 0.111 101 44 NA 0.029 101 39 binary + 0.024 8 34 norm 0.011 1 40 binary - 0.004 101 33 balance 0.003 1 The entries are the individual functions which have been executed (only the 10 most important ones), together with some information for each of them. The entries like 'binary *' denote operators, while other entries are ordinary functions. They include both built-ins like 'expm' and our own routines (for instance 'timesteps'). From this profile, we can immediately deduce that 'expm' uses up the largest proportion of the processing time, even though it is only called once. The second expensive operation is the matrix-vector product in the routine 'timesteps'. (1) Timing, however, is not the only information available from the profile. The attribute column shows us that 'timesteps' calls itself recursively. This may not be that remarkable in this example (since it's clear anyway), but could be helpful in a more complex setting. As to the question of why is there a 'binary \' in the output, we can easily shed some light on that too. Note that 'data' is a structure array (*note Structure Arrays::) which contains the field 'FunctionTable'. This stores the raw data for the profile shown. The number in the first column of the table gives the index under which the shown function can be found there. Looking up 'data.FunctionTable(41)' gives: scalar structure containing the fields: FunctionName = binary \ TotalTime = 0.18765 NumCalls = 1 IsRecursive = 0 Parents = 7 Children = [](1x0) Here we see the information from the table again, but have additional fields 'Parents' and 'Children'. Those are both arrays, which contain the indices of functions which have directly called the function in question (which is entry 7, 'expm', in this case) or been called by it (no functions). Hence, the backslash operator has been used internally by 'expm'. Now let's take a look at 'bar'. For this, we start a fresh profiling session ('profile on' does this; the old data is removed before the profiler is restarted): profile on; bar (20); profile off; profshow (profile ("info")); This gives: # Function Attr Time (s) Calls ------------------------------------------------------- 1 bar R 2.091 13529 2 binary <= 0.062 13529 3 binary - 0.042 13528 4 binary + 0.023 6764 5 profile 0.000 1 8 false 0.000 1 6 nargin 0.000 1 7 binary != 0.000 1 9 __profiler_enable__ 0.000 1 Unsurprisingly, 'bar' is also recursive. It has been called 13,529 times in the course of recursively calculating the Fibonacci number in a suboptimal way, and most of the time was spent in 'bar' itself. Finally, let's say we want to profile the execution of both 'foo' and 'bar' together. Since we already have the run-time data collected for 'bar', we can restart the profiler without clearing the existing data and collect the missing statistics about 'foo'. This is done by: profile resume; foo; profile off; profshow (profile ("info"), 10); As you can see in the table below, now we have both profiles mixed together. # Function Attr Time (s) Calls --------------------------------------------- 1 bar R 2.091 13529 16 expm 1.122 1 12 binary * 0.798 117 46 binary \ 0.185 1 45 binary ^ 0.124 2 48 timesteps R 0.115 101 2 binary <= 0.062 13529 3 binary - 0.045 13629 4 binary + 0.041 6772 49 NA 0.036 101 ---------- Footnotes ---------- (1) We only know it is the binary multiplication operator, but fortunately this operator appears only at one place in the code and thus we know which occurrence takes so much time. If there were multiple places, we would have to use the hierarchical profile to find out the exact place which uses up the time which is not covered in this example.  File: octave.info, Node: Input and Output, Next: Plotting, Prev: Debugging, Up: Top 14 Input and Output ******************* Octave supports several ways of reading and writing data to or from the prompt or a file. The simplest functions for data Input and Output (I/O) are easy to use, but only provide limited control of how data is processed. For more control, a set of functions modeled after the C standard library are also provided by Octave. * Menu: * Basic Input and Output:: * C-Style I/O Functions::  File: octave.info, Node: Basic Input and Output, Next: C-Style I/O Functions, Up: Input and Output 14.1 Basic Input and Output =========================== * Menu: * Terminal Output:: * Terminal Input:: * Simple File I/O::  File: octave.info, Node: Terminal Output, Next: Terminal Input, Up: Basic Input and Output 14.1.1 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 value of 'pi' pi -| pi = 3.1416 This works well as long as it is acceptable to have the name of the variable (or 'ans') printed along with the value. To print the value of a variable without printing its name, use the function 'disp'. The 'format' command offers some control over the way Octave prints values with 'disp' and through the normal echoing mechanism. -- Built-in Function: disp (X) Display the value of X. For example: disp ("The value of pi is:"), disp (pi) -| the value of pi is: -| 3.1416 Note that the output from 'disp' always ends with a newline. If an output value is requested, 'disp' prints nothing and returns the formatted output in a string. See also: *note fdisp: XREFfdisp. -- Built-in Function: list_in_columns (ARG, WIDTH, PREFIX) Return a string containing the elements of ARG listed in columns with an overall maximum width of WIDTH and optional prefix PREFIX. The argument ARG must be a cell array of character strings or a character array. If WIDTH is not specified or is an empty matrix, or less than or equal to zero, the width of the terminal screen is used. Newline characters are used to break the lines in the output string. For example: list_in_columns ({"abc", "def", "ghijkl", "mnop", "qrs", "tuv"}, 20) => abc mnop def qrs ghijkl tuv whos ans => Variables in the current scope: Attr Name Size Bytes Class ==== ==== ==== ===== ===== ans 1x37 37 char Total is 37 elements using 37 bytes See also: *note terminal_size: XREFterminal_size. -- Built-in Function: terminal_size () Return a two-element row vector containing the current size of the terminal window in characters (rows and columns). See also: *note list_in_columns: XREFlist_in_columns. -- Command: format -- Command: format options Reset or specify the format of the output produced by 'disp' and Octave's normal echoing mechanism. This command only affects the display of numbers but not how they are stored or computed. To change the internal representation from the default double use one of the conversion functions such as 'single', 'uint8', 'int64', etc. By default, Octave displays 5 significant digits in a human readable form (option 'short' paired with 'loose' format for matrices). If 'format' is invoked without any options, this default format is restored. Valid formats for floating point numbers are listed in the following table. 'short' Fixed point format with 5 significant figures in a field that is a maximum of 10 characters wide. (default). If Octave is unable to format a matrix so that columns line up on the decimal point and all numbers fit within the maximum field width then it switches to an exponential 'e' format. 'long' Fixed point format with 15 significant figures in a field that is a maximum of 20 characters wide. As with the 'short' format, Octave will switch to an exponential 'e' format if it is unable to format a matrix properly using the current format. 'short e' 'long e' Exponential format. The number to be represented is split between a mantissa and an exponent (power of 10). The mantissa has 5 significant digits in the short format and 15 digits in the long format. For example, with the 'short e' format, 'pi' is displayed as '3.1416e+00'. 'short E' 'long E' Identical to 'short e' or 'long e' but displays an uppercase 'E' to indicate the exponent. For example, with the 'long E' format, 'pi' is displayed as '3.14159265358979E+00'. 'short g' 'long g' Optimally choose between fixed point and exponential format based on the magnitude of the number. For example, with the 'short g' format, 'pi .^ [2; 4; 8; 16; 32]' is displayed as ans = 9.8696 97.409 9488.5 9.0032e+07 8.1058e+15 'short eng' 'long eng' Identical to 'short e' or 'long e' but displays the value using an engineering format, where the exponent is divisible by 3. For example, with the 'short eng' format, '10 * pi' is displayed as '31.4159e+00'. 'long G' 'short G' Identical to 'short g' or 'long g' but displays an uppercase 'E' to indicate the exponent. 'free' 'none' Print output in free format, without trying to line up columns of matrices on the decimal point. This also causes complex numbers to be formatted as numeric pairs like this '(0.60419, 0.60709)' instead of like this '0.60419 + 0.60709i'. The following formats affect all numeric output (floating point and integer types). '"+"' '"+" CHARS' 'plus' 'plus CHARS' Print a '+' symbol for matrix elements greater than zero, a '-' symbol for elements less than zero and a space for zero matrix elements. This format can be very useful for examining the structure of a large sparse matrix. The optional argument CHARS specifies a list of 3 characters to use for printing values greater than zero, less than zero and equal to zero. For example, with the '"+" "+-."' format, '[1, 0, -1; -1, 0, 1]' is displayed as ans = +.- -.+ 'bank' Print in a fixed format with two digits to the right of the decimal point. 'native-hex' Print the hexadecimal representation of numbers as they are stored in memory. For example, on a workstation which stores 8 byte real values in IEEE format with the least significant byte first, the value of 'pi' when printed in 'native-hex' format is '400921fb54442d18'. 'hex' The same as 'native-hex', but always print the most significant byte first. 'native-bit' Print the bit representation of numbers as stored in memory. For example, the value of 'pi' is 01000000000010010010000111111011 01010100010001000010110100011000 (shown here in two 32 bit sections for typesetting purposes) when printed in native-bit format on a workstation which stores 8 byte real values in IEEE format with the least significant byte first. 'bit' The same as 'native-bit', but always print the most significant bits first. 'rat' Print a rational approximation, i.e., values are approximated as the ratio of small integers. For example, with the 'rat' format, 'pi' is displayed as '355/113'. The following two options affect the display of all matrices. 'compact' Remove blank lines around column number labels and between matrices producing more compact output with more data per page. 'loose' Insert blank lines above and below column number labels and between matrices to produce a more readable output with less data per page. (default). See also: *note fixed_point_format: XREFfixed_point_format, *note output_max_field_width: XREFoutput_max_field_width, *note output_precision: XREFoutput_precision, *note split_long_rows: XREFsplit_long_rows, *note print_empty_dimensions: XREFprint_empty_dimensions, *note rats: XREFrats. * Menu: * Paging Screen Output::  File: octave.info, Node: Paging Screen Output, Up: Terminal Output 14.1.1.1 Paging Screen Output ............................. When running interactively, Octave normally sends any output intended for your terminal that is more than one screen long to a paging program, such as 'less' or 'more'. This avoids the problem of having a large volume of output stream by before you can read it. With 'less' (and some versions of 'more') you can also scan forward and backward, and search for specific items. Normally, 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 (for example, by using the 'fscanf' or '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 'fflush' may be used to force output to be sent to the pager (or any other stream) immediately. You can select the program to run as the pager using the 'PAGER' function, and you can turn paging off by using the function 'more'. -- Command: more -- Command: more on -- Command: more off Turn output pagination on or off. Without an argument, 'more' toggles the current state. The current state can be determined via 'page_screen_output'. See also: *note page_screen_output: XREFpage_screen_output, *note page_output_immediately: XREFpage_output_immediately, *note PAGER: XREFPAGER, *note PAGER_FLAGS: XREFPAGER_FLAGS. -- Built-in Function: VAL = PAGER () -- Built-in Function: OLD_VAL = PAGER (NEW_VAL) -- Built-in Function: PAGER (NEW_VAL, "local") Query or set the internal variable that specifies the program to use to display terminal output on your system. The default value is normally "less", "more", or "pg", depending on what programs are installed on your system. *Note Installation::. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note PAGER_FLAGS: XREFPAGER_FLAGS, *note page_output_immediately: XREFpage_output_immediately, *note more: XREFmore, *note page_screen_output: XREFpage_screen_output. -- Built-in Function: VAL = PAGER_FLAGS () -- Built-in Function: OLD_VAL = PAGER_FLAGS (NEW_VAL) -- Built-in Function: PAGER_FLAGS (NEW_VAL, "local") Query or set the internal variable that specifies the options to pass to the pager. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note PAGER: XREFPAGER, *note more: XREFmore, *note page_screen_output: XREFpage_screen_output, *note page_output_immediately: XREFpage_output_immediately. -- Built-in Function: VAL = page_screen_output () -- Built-in Function: OLD_VAL = page_screen_output (NEW_VAL) -- Built-in Function: page_screen_output (NEW_VAL, "local") Query or set the internal variable that controls whether output intended for the terminal window 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 'less'--see *note Installation::) are also capable of moving backward on the output. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note more: XREFmore, *note page_output_immediately: XREFpage_output_immediately, *note PAGER: XREFPAGER, *note PAGER_FLAGS: XREFPAGER_FLAGS. -- Built-in Function: VAL = page_output_immediately () -- Built-in Function: OLD_VAL = page_output_immediately (NEW_VAL) -- Built-in Function: page_output_immediately (NEW_VAL, "local") Query or set the internal variable that controls whether 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. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note page_screen_output: XREFpage_screen_output, *note more: XREFmore, *note PAGER: XREFPAGER, *note PAGER_FLAGS: XREFPAGER_FLAGS. -- Built-in Function: fflush (FID) Flush output to file descriptor FID. 'fflush' returns 0 on success and an OS dependent error value (-1 on Unix) on error. Programming Note: Flushing 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 'input'. See also: *note fopen: XREFfopen, *note fclose: XREFfclose.  File: octave.info, Node: Terminal Input, Next: Simple File I/O, Prev: Terminal Output, Up: Basic Input and Output 14.1.2 Terminal Input --------------------- Octave has three functions that make it easy to prompt users for input. The 'input' and 'menu' functions are normally used for managing an interactive dialog with a user, and the 'keyboard' function is normally used for doing simple debugging. -- Built-in Function: ANS = input (PROMPT) -- Built-in Function: ANS = input (PROMPT, "s") Print PROMPT and wait for user input. For example, input ("Pick a number, any number! ") prints the prompt Pick a number, any number! and waits for the user to enter a value. The string entered by the user is evaluated as an expression, so it may be a literal constant, a variable name, or any other valid Octave code. The number of return arguments, their size, and their class depend on the expression entered. If you are only interested in getting a literal string value, you can call 'input' with the character string "s" as the second argument. This tells Octave to return the string entered by the user directly, without evaluating it first. Because there may be output waiting to be displayed by the pager, it is a good idea to always call 'fflush (stdout)' before calling 'input'. This will ensure that all pending output is written to the screen before your prompt. See also: *note yes_or_no: XREFyes_or_no, *note kbhit: XREFkbhit, *note pause: XREFpause, *note menu: XREFmenu, *note listdlg: XREFlistdlg. -- Function File: CHOICE = menu (TITLE, OPT1, ...) -- Function File: CHOICE = menu (TITLE, {OPT1, ...}) Display a menu with heading TITLE and options OPT1, ..., and wait for user input. If the GUI is running, or Java is available, the menu is displayed graphically using 'listdlg'. Otherwise, the title and menu options are printed on the console. TITLE is a string and the options may be input as individual strings or as a cell array of strings. The return value CHOICE is the number of the option selected by the user counting from 1. 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. See also: *note input: XREFinput, *note listdlg: XREFlistdlg. -- Built-in Function: ANS = yes_or_no ("PROMPT") Ask the user a yes-or-no question. Return logical true if the answer is yes or false if the answer is no. Takes one argument, PROMPT, which is the string to display when asking the question. PROMPT should end in a space; 'yes-or-no' adds the string '(yes or no) ' to it. The user must confirm the answer with and can edit it until it has been confirmed. See also: *note input: XREFinput. For 'input', the normal command line history and editing functions are available at the prompt. Octave also has a function that makes it possible to get a single character from the keyboard without requiring the user to type a carriage return. -- Built-in Function: kbhit () -- Built-in Function: kbhit (1) Read a single keystroke from the keyboard. If called with an argument, don't wait for a keypress. For example, x = kbhit (); will set X to the next character typed at the keyboard as soon as it is typed. x = kbhit (1); is identical to the above example, but doesn't wait for a keypress, returning the empty string if no key is available. See also: *note input: XREFinput, *note pause: XREFpause.  File: octave.info, Node: Simple File I/O, Prev: Terminal Input, Up: Basic Input and Output 14.1.3 Simple File I/O ---------------------- The 'save' and 'load' commands allow data to be written to and read from disk files in various formats. The default format of files written by the 'save' command can be controlled using the functions 'save_default_options' and 'save_precision'. As an example the following code creates a 3-by-3 matrix and saves it to the file 'myfile.mat'. A = [ 1:3; 4:6; 7:9 ]; save myfile.mat A Once one or more variables have been saved to a file, they can be read into memory using the 'load' command. load myfile.mat A -| A = -| -| 1 2 3 -| 4 5 6 -| 7 8 9 -- Command: save file -- Command: save options file -- Command: save options file V1 V2 ... -- Command: save options file -struct STRUCT F1 F2 ... -- Command: save '"-"' V1 V2 ... -- Built-in Function: S = save ('"-"' V1 V2 ...) Save the named variables V1, V2, ..., in the file FILE. The special filename '-' may be used to return the content of the variables as a string. If no variable names are listed, Octave saves all the variables in the current scope. Otherwise, full variable names or pattern syntax can be used to specify the variables to save. If the '-struct' modifier is used, fields F1 F2 ... of the scalar structure STRUCT are saved as if they were variables with corresponding names. Valid options for the 'save' command are listed in the following table. Options that modify the output format override the format specified by 'save_default_options'. If save is invoked using the functional form save ("-option1", ..., "file", "v1", ...) then the OPTIONS, FILE, and variable name arguments (V1, ...) must be specified as character strings. If called with a filename of "-", write the output to stdout if nargout is 0, otherwise return the output in a character string. '-append' Append to the destination instead of overwriting. '-ascii' Save a single matrix in a text file without header or any other information. '-binary' Save the data in Octave's binary data format. '-float-binary' Save the data in Octave's binary data format but only using single precision. Only use this format if you know that all the values to be saved can be represented in single precision. '-hdf5' Save the data in HDF5 format. (HDF5 is a free, portable binary format developed by the National Center for Supercomputing Applications at the University of Illinois.) This format is only available if Octave was built with a link to the HDF5 libraries. '-float-hdf5' Save the data in HDF5 format but only using single precision. Only use this format if you know that all the values to be saved can be represented in single precision. '-V7' '-v7' '-7' '-mat7-binary' Save the data in MATLAB's v7 binary data format. '-V6' '-v6' '-6' '-mat' '-mat-binary' Save the data in MATLAB's v6 binary data format. '-V4' '-v4' '-4' '-mat4-binary' Save the data in the binary format written by MATLAB version 4. '-text' Save the data in Octave's text data format. (default). '-zip' '-z' Use the gzip algorithm to compress the file. This works equally on files that are compressed with gzip outside of octave, and gzip can equally be used to convert the files for backward compatibility. This option is only available if Octave was built with a link to the zlib libraries. The list of variables to save may use wildcard patterns containing the following special characters: '?' Match any single character. '*' Match zero or more characters. '[ LIST ]' Match the list of characters specified by LIST. If the first character is '!' or '^', match all characters except those specified by LIST. For example, the pattern '[a-zA-Z]' will match all lower and uppercase alphabetic characters. Wildcards may also be used in the field name specifications when using the '-struct' modifier (but not in the struct name itself). Except when using the MATLAB binary data file format or the '-ascii' format, saving global variables also saves the global status of the variable. If the variable is restored at a later time using 'load', it will be restored as a global variable. The command save -binary data a b* saves the variable 'a' and all variables beginning with 'b' to the file 'data' in Octave's binary format. See also: *note load: XREFload, *note save_default_options: XREFsave_default_options, *note save_header_format_string: XREFsave_header_format_string, *note dlmread: XREFdlmread, *note csvread: XREFcsvread, *note fread: XREFfread. There are three functions that modify the behavior of 'save'. -- Built-in Function: VAL = save_default_options () -- Built-in Function: OLD_VAL = save_default_options (NEW_VAL) -- Built-in Function: save_default_options (NEW_VAL, "local") Query or set the internal variable that specifies the default options for the 'save' command, and defines the default format. Typical values include "-ascii", "-text -zip". The default value is '-text'. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note save: XREFsave. -- Built-in Function: VAL = save_precision () -- Built-in Function: OLD_VAL = save_precision (NEW_VAL) -- Built-in Function: save_precision (NEW_VAL, "local") Query or set the internal variable that specifies the number of digits to keep when saving data in text format. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. -- Built-in Function: VAL = save_header_format_string () -- Built-in Function: OLD_VAL = save_header_format_string (NEW_VAL) -- Built-in Function: save_header_format_string (NEW_VAL, "local") Query or set the internal variable that specifies the format string used for the comment line written at the beginning of text-format data files saved by Octave. The format string is passed to 'strftime' and should begin with the character '#' and contain no newline characters. If the value of 'save_header_format_string' is the empty string, the header comment is omitted from text-format data files. The default value is "# Created by Octave VERSION, %a %b %d %H:%M:%S %Y %Z " When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note strftime: XREFstrftime, *note save: XREFsave. -- Command: load file -- Command: load options file -- Command: load options file v1 v2 ... -- Command: S = load ("options", "file", "v1", "v2", ...) -- Command: load file options -- Command: load file options v1 v2 ... -- Command: S = load ("file", "options", "v1", "v2", ...) Load the named variables V1, V2, ..., from the file FILE. If no variables are specified then all variables found in the file will be loaded. As with 'save', the list of variables to extract can be full names or use a pattern syntax. The format of the file is automatically detected but may be overridden by supplying the appropriate option. If load is invoked using the functional form load ("-option1", ..., "file", "v1", ...) then the OPTIONS, FILE, and variable name arguments (V1, ...) must be specified as character strings. If a variable that is not marked as global is loaded from a file when a global symbol with the same name already exists, it is loaded in the global symbol table. Also, if a variable is marked as global in a file and a local symbol exists, the local symbol is moved to the global symbol table and given the value from the file. If invoked with a single output argument, Octave returns data instead of inserting variables in the symbol table. If the data file contains only numbers (TAB- or space-delimited columns), a matrix of values is returned. Otherwise, 'load' returns a structure with members corresponding to the names of the variables in the file. The 'load' command can read data stored in Octave's text and binary formats, and MATLAB's binary format. If compiled with zlib support, it can also load gzip-compressed files. 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 be added in the future). Valid options for 'load' are listed in the following table. '-force' This option is accepted for backward compatibility but is ignored. Octave now overwrites variables currently in memory with those of the same name found in the file. '-ascii' Force Octave to assume the file contains columns of numbers in text format without any header or other information. Data in the file will be loaded as a single numeric matrix with the name of the variable derived from the name of the file. '-binary' Force Octave to assume the file is in Octave's binary format. '-hdf5' Force Octave to assume the file is in HDF5 format. (HDF5 is a free, portable binary format developed by the National Center for Supercomputing Applications at the University of Illinois.) Note that Octave can read HDF5 files not created by itself, but may skip some datasets in formats that it cannot support. This format is only available if Octave was built with a link to the HDF5 libraries. '-import' This option is accepted for backward compatibility but is ignored. Octave can now support multi-dimensional HDF data and automatically modifies variable names if they are invalid Octave identifiers. '-mat' '-mat-binary' '-6' '-v6' '-7' '-v7' Force Octave to assume the file is in MATLAB's version 6 or 7 binary format. '-mat4-binary' '-4' '-v4' '-V4' Force Octave to assume the file is in the binary format written by MATLAB version 4. '-text' Force Octave to assume the file is in Octave's text format. See also: *note save: XREFsave, *note dlmwrite: XREFdlmwrite, *note csvwrite: XREFcsvwrite, *note fwrite: XREFfwrite. -- Function File: STR = fileread (FILENAME) Read the contents of FILENAME and return it as a string. See also: *note fread: XREFfread, *note textread: XREFtextread, *note sscanf: XREFsscanf. -- Built-in Function: native_float_format () Return the native floating point format as a string. It is possible to write data to a file in a similar way to the 'disp' function for writing data to the screen. The 'fdisp' works just like 'disp' except its first argument is a file pointer as created by 'fopen'. As an example, the following code writes to data 'myfile.txt'. fid = fopen ("myfile.txt", "w"); fdisp (fid, "3/8 is "); fdisp (fid, 3/8); fclose (fid); *Note Opening and Closing Files::, for details on how to use 'fopen' and 'fclose'. -- Built-in Function: fdisp (FID, X) Display the value of X on the stream FID. For example: fdisp (stdout, "The value of pi is:"), fdisp (stdout, pi) -| the value of pi is: -| 3.1416 Note that the output from 'fdisp' always ends with a newline. See also: *note disp: XREFdisp. Octave can also read and write matrices text files such as comma separated lists. -- Function File: dlmwrite (FILE, M) -- Function File: dlmwrite (FILE, M, DELIM, R, C) -- Function File: dlmwrite (FILE, M, KEY, VAL ...) -- Function File: dlmwrite (FILE, M, "-append", ...) -- Function File: dlmwrite (FID, ...) Write the matrix M to the named file using delimiters. FILE should be a file name or writable file ID given by 'fopen'. The parameter DELIM specifies the delimiter to use to separate values on a row. The value of R specifies the number of delimiter-only lines to add to the start of the file. The value of C specifies the number of delimiters to prepend to each line of data. If the argument "-append" is given, append to the end of FILE. In addition, the following keyword value pairs may appear at the end of the argument list: "append" Either "on" or "off". See "-append" above. "delimiter" See DELIM above. "newline" The character(s) to use to separate each row. Three special cases exist for this option. "unix" is changed into "\n", "pc" is changed into "\r\n", and "mac" is changed into "\r". Any other value is used directly as the newline separator. "roffset" See R above. "coffset" See C above. "precision" The precision to use when writing the file. It can either be a format string (as used by fprintf) or a number of significant digits. dlmwrite ("file.csv", reshape (1:16, 4, 4)); dlmwrite ("file.tex", a, "delimiter", "&", "newline", "\n") See also: *note dlmread: XREFdlmread, *note csvread: XREFcsvread, *note csvwrite: XREFcsvwrite. -- Built-in Function: DATA = dlmread (FILE) -- Built-in Function: DATA = dlmread (FILE, SEP) -- Built-in Function: DATA = dlmread (FILE, SEP, R0, C0) -- Built-in Function: DATA = dlmread (FILE, SEP, RANGE) -- Built-in Function: DATA = dlmread (..., "emptyvalue", EMPTYVAL) Read the matrix DATA from a text file which uses the delimiter SEP between data values. If SEP is not defined the separator between fields is determined from the file itself. Given two scalar arguments R0 and C0, these define the starting row and column of the data to be read. These values are indexed from zero, such that the first row corresponds to an index of zero. The RANGE parameter may be a 4-element vector containing the upper left and lower right corner '[R0,C0,R1,C1]' where the lowest index value is zero. Alternatively, a spreadsheet style range such as "A2..Q15" or "T1:AA5" can be used. The lowest alphabetical index 'A' refers to the first column. The lowest row index is 1. FILE should be a file name or file id given by 'fopen'. In the latter case, the file is read until end of file is reached. The "emptyvalue" option may be used to specify the value used to fill empty fields. The default is zero. See also: *note csvread: XREFcsvread, *note textscan: XREFtextscan, *note textread: XREFtextread, *note dlmwrite: XREFdlmwrite. -- Function File: csvwrite (FILENAME, X) -- Function File: csvwrite (FILENAME, X, DLM_OPTS) Write the matrix X to the file FILENAME in comma-separated-value format. This function is equivalent to dlmwrite (FILENAME, X, ",", ...) See also: *note csvread: XREFcsvread, *note dlmwrite: XREFdlmwrite, *note dlmread: XREFdlmread. -- Function File: X = csvread (FILENAME) -- Function File: X = csvread (FILENAME, DLM_OPTS) Read the comma-separated-value file FILENAME into the matrix X. This function is equivalent to X = dlmread (FILENAME, "," , ...) See also: *note csvwrite: XREFcsvwrite, *note dlmread: XREFdlmread, *note dlmwrite: XREFdlmwrite. Formatted data from can be read from, or written to, text files as well. -- Function File: [A, ...] = textread (FILENAME) -- Function File: [A, ...] = textread (FILENAME, FORMAT) -- Function File: [A, ...] = textread (FILENAME, FORMAT, N) -- Function File: [A, ...] = textread (FILENAME, FORMAT, PROP1, VALUE1, ...) -- Function File: [A, ...] = textread (FILENAME, FORMAT, N, PROP1, VALUE1, ...) Read data from a text file. The file FILENAME is read and parsed according to FORMAT. The function behaves like 'strread' except it works by parsing a file instead of a string. See the documentation of 'strread' for details. In addition to the options supported by 'strread', this function supports two more: * "headerlines": The first VALUE number of lines of FILENAME are skipped. * "endofline": Specify a single character or "\r\n". If no value is given, it will be inferred from the file. If set to "" (empty string) EOLs are ignored as delimiters. The optional input N (format repeat count) specifies the number of times the format string is to be used or the number of lines to be read, whichever happens first while reading. The former is equivalent to requesting that the data output vectors should be of length N. Note that when reading files with format strings referring to multiple lines, N should rather be the number of lines to be read than the number of format string uses. If the format string is empty (not just omitted) and the file contains only numeric data (excluding headerlines), textread will return a rectangular matrix with the number of columns matching the number of numeric fields on the first data line of the file. Empty fields are returned as zero values. Examples: Assume a data file like: 1 a 2 b 3 c 4 d 5 e [a, b] = textread (f, "%f %s") returns two columns of data, one with doubles, the other a cellstr array: a = [1; 2; 3; 4; 5] b = {"a"; "b"; "c"; "d"; "e"} [a, b] = textread (f, "%f %s", 3) (read data into two culumns, try to use the format string three times) returns a = [1; 2; 3] b = {"a"; "b"; "c"} With a data file like: 1 a 2 b [a, b] = textread (f, "%f %s", 2) returns a = 1 and b = {"a"}; i.e., the format string is used only once because the format string refers to 2 lines of the data file. To obtain 2x1 data output columns, specify N = 4 (number of data lines containing all requested data) rather than 2. See also: *note strread: XREFstrread, *note load: XREFload, *note dlmread: XREFdlmread, *note fscanf: XREFfscanf, *note textscan: XREFtextscan. -- Function File: C = textscan (FID, FORMAT) -- Function File: C = textscan (FID, FORMAT, N) -- Function File: C = textscan (FID, FORMAT, PARAM, VALUE, ...) -- Function File: C = textscan (FID, FORMAT, N, PARAM, VALUE, ...) -- Function File: C = textscan (STR, ...) -- Function File: [C, POSITION] = textscan (FID, ...) Read data from a text file or string. The string STR or file associated with FID is read from and parsed according to FORMAT. The function behaves like 'strread' except it can also read from file instead of a string. See the documentation of 'strread' for details. In addition to the options supported by 'strread', this function supports a few more: * "collectoutput": A value of 1 or true instructs textscan to concatenate consecutive columns of the same class in the output cell array. A value of 0 or false (default) leaves output in distinct columns. * "endofline": Specify "\r", "\n" or "\r\n" (for CR, LF, or CRLF). If no value is given, it will be inferred from the file. If set to "" (empty string) EOLs are ignored as delimiters and added to whitespace. * "headerlines": The first VALUE number of lines of FID are skipped. * "returnonerror": If set to numerical 1 or true (default), return normally when read errors have been encountered. If set to 0 or false, return an error and no data. As the string or file is read by columns rather than by rows, and because textscan is fairly forgiving as regards read errors, setting this option may have little or no actual effect. When reading from a character string, optional input argument N specifies the number of times FORMAT should be used (i.e., to limit the amount of data read). When reading from file, N specifies the number of data lines to read; in this sense it differs slightly from the format repeat count in strread. The output C is a cell array whose second dimension is determined by the number of format specifiers. The second output, POSITION, provides the position, in characters, from the beginning of the file. If the format string is empty (not: omitted) and the file contains only numeric data (excluding headerlines), textscan will return data in a number of columns matching the number of numeric fields on the first data line of the file. See also: *note dlmread: XREFdlmread, *note fscanf: XREFfscanf, *note load: XREFload, *note strread: XREFstrread, *note textread: XREFtextread. The 'importdata' function has the ability to work with a wide variety of data. -- Function File: A = importdata (FNAME) -- Function File: A = importdata (FNAME, DELIMITER) -- Function File: A = importdata (FNAME, DELIMITER, HEADER_ROWS) -- Function File: [A, DELIMITER] = importdata (...) -- Function File: [A, DELIMITER, HEADER_ROWS] = importdata (...) Import data from the file FNAME. Input parameters: * FNAME The name of the file containing data. * DELIMITER The character separating columns of data. Use '\t' for tab. (Only valid for ASCII files) * HEADER_ROWS The number of header rows before the data begins. (Only valid for ASCII files) Different file types are supported: * ASCII table Import ASCII table using the specified number of header rows and the specified delimiter. * Image file * MATLAB file * Spreadsheet files (depending on external software) * WAV file See also: *note textscan: XREFtextscan, *note dlmread: XREFdlmread, *note csvread: XREFcsvread, *note load: XREFload. * Menu: * Saving Data on Unexpected Exits::  File: octave.info, Node: Saving Data on Unexpected Exits, Up: Simple File I/O 14.1.3.1 Saving Data on Unexpected Exits ........................................ If Octave for some reason exits unexpectedly it will by default save the variables available in the workspace to a file in the current directory. By default this file is named 'octave-workspace' and can be loaded into memory with the 'load' command. While the default behavior most often is reasonable it can be changed through the following functions. -- Built-in Function: VAL = crash_dumps_octave_core () -- Built-in Function: OLD_VAL = crash_dumps_octave_core (NEW_VAL) -- Built-in Function: crash_dumps_octave_core (NEW_VAL, "local") Query or set the internal variable that controls whether Octave tries to save all current variables to the file 'octave-workspace' if it crashes or receives a hangup, terminate or similar signal. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note octave_core_file_limit: XREFoctave_core_file_limit, *note octave_core_file_name: XREFoctave_core_file_name, *note octave_core_file_options: XREFoctave_core_file_options. -- Built-in Function: VAL = sighup_dumps_octave_core () -- Built-in Function: OLD_VAL = sighup_dumps_octave_core (NEW_VAL) -- Built-in Function: sighup_dumps_octave_core (NEW_VAL, "local") Query or set the internal variable that controls whether Octave tries to save all current variables to the file 'octave-workspace' if it receives a hangup signal. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. -- Built-in Function: VAL = sigterm_dumps_octave_core () -- Built-in Function: OLD_VAL = sigterm_dumps_octave_core (NEW_VAL) -- Built-in Function: sigterm_dumps_octave_core (NEW_VAL, "local") Query or set the internal variable that controls whether Octave tries to save all current variables to the file 'octave-workspace' if it receives a terminate signal. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. -- Built-in Function: VAL = octave_core_file_options () -- Built-in Function: OLD_VAL = octave_core_file_options (NEW_VAL) -- Built-in Function: octave_core_file_options (NEW_VAL, "local") Query or set the internal variable that specifies the options used for saving the workspace data if Octave aborts. The value of 'octave_core_file_options' should follow the same format as the options for the 'save' function. The default value is Octave's binary format. When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note crash_dumps_octave_core: XREFcrash_dumps_octave_core, *note octave_core_file_name: XREFoctave_core_file_name, *note octave_core_file_limit: XREFoctave_core_file_limit. -- Built-in Function: VAL = octave_core_file_limit () -- Built-in Function: OLD_VAL = octave_core_file_limit (NEW_VAL) -- Built-in Function: octave_core_file_limit (NEW_VAL, "local") Query or set the internal variable that specifies the maximum amount of memory (in kilobytes) of the top-level workspace that Octave will attempt to save when writing data to the crash dump file (the name of the file is specified by OCTAVE_CORE_FILE_NAME). If OCTAVE_CORE_FILE_OPTIONS flags specify a binary format, then OCTAVE_CORE_FILE_LIMIT will be approximately the maximum size of the file. If a text file format is used, then the file could be much larger than the limit. The default value is -1 (unlimited) When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note crash_dumps_octave_core: XREFcrash_dumps_octave_core, *note octave_core_file_name: XREFoctave_core_file_name, *note octave_core_file_options: XREFoctave_core_file_options. -- Built-in Function: VAL = octave_core_file_name () -- Built-in Function: OLD_VAL = octave_core_file_name (NEW_VAL) -- Built-in Function: octave_core_file_name (NEW_VAL, "local") Query or set the internal variable that specifies the name of the file used for saving data from the top-level workspace if Octave aborts. The default value is "octave-workspace" When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. See also: *note crash_dumps_octave_core: XREFcrash_dumps_octave_core, *note octave_core_file_name: XREFoctave_core_file_name, *note octave_core_file_options: XREFoctave_core_file_options.  File: octave.info, Node: C-Style I/O Functions, Prev: Basic Input and Output, Up: Input and Output 14.2 C-Style I/O Functions ========================== 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, FILE refers to a file name and 'fid' refers to an integer file number, as returned by 'fopen'. There are three files that are always available. Although these files can be accessed using their corresponding numeric file ids, you should always use the symbolic names given in the table below, since it will make your programs easier to understand. -- Built-in Function: stdin () Return the numeric value corresponding to the standard input stream. When Octave is used interactively, stdin is filtered through the command line editing functions. See also: *note stdout: XREFstdout, *note stderr: XREFstderr. -- Built-in Function: stdout () Return the numeric value corresponding to the standard output stream. Data written to the standard output is normally filtered through the pager. See also: *note stdin: XREFstdin, *note stderr: XREFstderr. -- Built-in Function: stderr () Return the numeric value corresponding to the standard error stream. Even if paging is turned on, the standard error is not sent to the pager. It is useful for error messages and prompts. See also: *note stdin: XREFstdin, *note stdout: XREFstdout. * Menu: * Opening and Closing Files:: * Simple Output:: * Line-Oriented Input:: * Formatted Output:: * Output Conversion for Matrices:: * Output Conversion Syntax:: * Table of Output Conversions:: * Integer Conversions:: * Floating-Point Conversions:: * Other Output Conversions:: * Formatted Input:: * Input Conversion Syntax:: * Table of Input Conversions:: * Numeric Input Conversions:: * String Input Conversions:: * Binary I/O:: * Temporary Files:: * EOF and Errors:: * File Positioning::  File: octave.info, Node: Opening and Closing Files, Next: Simple Output, Up: C-Style I/O Functions 14.2.1 Opening and Closing Files -------------------------------- When reading data from a file it must be opened for reading first, and likewise when writing to a file. The 'fopen' function returns a pointer to an open file that is ready to be read or written. Once all data has been read from or written to the opened file it should be closed. The 'fclose' function does this. The following code illustrates the basic pattern for writing to a file, but a very similar pattern is used when reading a file. filename = "myfile.txt"; fid = fopen (filename, "w"); # Do the actual I/O here... fclose (fid); -- Built-in Function: FID = fopen (NAME) -- Built-in Function: FID = fopen (NAME, MODE) -- Built-in Function: FID = fopen (NAME, MODE, ARCH) -- Built-in Function: [FID, MSG] = fopen (...) -- Built-in Function: FID_LIST = fopen ("all") -- Built-in Function: [FILE, MODE, ARCH] = fopen (FID) Open a file for low-level I/O or query open files and file descriptors. The first form of the 'fopen' function opens the named file with the specified mode (read-write, read-only, etc.) and architecture interpretation (IEEE big endian, IEEE little endian, etc.), and returns an integer value that may be used to refer to the file later. If an error occurs, FID is set to -1 and MSG contains the corresponding system error message. The MODE is a one or two character string that specifies whether the file is to be opened for reading, writing, or both. The second form of the 'fopen' function returns a vector of file ids corresponding to all the currently open files, excluding the 'stdin', 'stdout', and 'stderr' streams. The third form of the 'fopen' function returns information about the open file given its file id. For example, myfile = fopen ("splat.dat", "r", "ieee-le"); opens the file 'splat.dat' for reading. If necessary, binary numeric values will be read assuming they are stored in IEEE format with the least significant bit first, and then converted to the native representation. Opening a file that is already open simply opens it again and returns a separate file id. It is not an error to open a file several times, though writing to the same file through several different file ids may produce unexpected results. The possible values 'mode' may have are 'r' (default) Open a file for reading. 'w' Open a file for writing. The previous contents are discarded. 'a' Open or create a file for writing at the end of the file. 'r+' Open an existing file for reading and writing. 'w+' Open a file for reading or writing. The previous contents are discarded. 'a+' Open or create a file for reading or writing at the end of the file. Append a "t" to the mode string to open the file in text mode or a "b" to open in binary mode. On Windows and Macintosh systems, text mode reading and writing automatically converts linefeeds to the appropriate line end character for the system (carriage-return linefeed on Windows, carriage-return on Macintosh). The default when no mode is specified is binary mode. Additionally, you may append a "z" to the mode string to open a gzipped file for reading or writing. For this to be successful, you must also open the file in binary mode. The parameter ARCH is a string specifying the default data format for the file. Valid values for ARCH are: 'native (default)' The format of the current machine. 'ieee-be' IEEE big endian format. 'ieee-le' IEEE little endian format. however, conversions are currently only supported for 'native' 'ieee-be', and 'ieee-le' formats. When opening a new file that does not yet exist, permissions will be set to '0666 - UMASK'. See also: *note fclose: XREFfclose, *note fgets: XREFfgets, *note fgetl: XREFfgetl, *note fscanf: XREFfscanf, *note fread: XREFfread, *note fputs: XREFfputs, *note fdisp: XREFfdisp, *note fprintf: XREFfprintf, *note fwrite: XREFfwrite, *note fskipl: XREFfskipl, *note fseek: XREFfseek, *note frewind: XREFfrewind, *note ftell: XREFftell, *note feof: XREFfeof, *note ferror: XREFferror, *note fclear: XREFfclear, *note fflush: XREFfflush, *note freport: XREFfreport, *note umask: XREFumask. -- Built-in Function: fclose (FID) -- Built-in Function: fclose ("all") -- Built-in Function: STATUS = fclose ("all") Close the file specified by the file descriptor FID. If successful, 'fclose' returns 0, otherwise, it returns -1. The second form of the 'fclose' call closes all open files except 'stdout', 'stderr', and 'stdin'. Programming Note: When using "all" the file descriptors associated with gnuplot will also be closed. This will prevent further plotting with gnuplot until Octave is closed and restarted. See also: *note fopen: XREFfopen, *note fflush: XREFfflush, *note freport: XREFfreport. -- Function File: is_valid_file_id (FID) Return true if FID refers to an open file. See also: *note freport: XREFfreport, *note fopen: XREFfopen.  File: octave.info, Node: Simple Output, Next: Line-Oriented Input, Prev: Opening and Closing Files, Up: C-Style I/O Functions 14.2.2 Simple Output -------------------- Once a file has been opened for writing a string can be written to the file using the 'fputs' function. The following example shows how to write the string 'Free Software is needed for Free Science' to the file 'free.txt'. filename = "free.txt"; fid = fopen (filename, "w"); fputs (fid, "Free Software is needed for Free Science"); fclose (fid); -- Built-in Function: fputs (FID, STRING) -- Built-in Function: STATUS = fputs (FID, STRING) Write the string STRING to the file with file descriptor FID. The string is written to the file with no additional formatting. Use 'fdisp' instead to automatically append a newline character appropriate for the local machine. Return a non-negative number on success or EOF on error. See also: *note fdisp: XREFfdisp, *note fprintf: XREFfprintf, *note fwrite: XREFfwrite, *note fopen: XREFfopen. A function much similar to 'fputs' is available for writing data to the screen. The 'puts' function works just like 'fputs' except it doesn't take a file pointer as its input. -- Built-in Function: puts (STRING) -- Built-in Function: STATUS = puts (STRING) Write a string to the standard output with no formatting. The string is written verbatim to the standard output. Use 'disp' to automatically append a newline character appropriate for the local machine. Return a non-negative number on success and EOF on error. See also: *note fputs: XREFfputs, *note disp: XREFdisp.  File: octave.info, Node: Line-Oriented Input, Next: Formatted Output, Prev: Simple Output, Up: C-Style I/O Functions 14.2.3 Line-Oriented Input -------------------------- To read from a file it must be opened for reading using 'fopen'. Then a line can be read from the file using 'fgetl' as the following code illustrates fid = fopen ("free.txt"); txt = fgetl (fid) -| Free Software is needed for Free Science fclose (fid); This of course assumes that the file 'free.txt' exists and contains the line 'Free Software is needed for Free Science'. -- Built-in Function: STR = fgetl (FID) -- Built-in Function: STR = fgetl (FID, LEN) Read characters from a file, stopping after a newline, or EOF, or LEN characters have been read. The characters read, excluding the possible trailing newline, are returned as a string. If LEN is omitted, 'fgetl' reads until the next newline character. If there are no more characters to read, 'fgetl' returns -1. To read a line and return the terminating newline see 'fgets'. See also: *note fgets: XREFfgets, *note fscanf: XREFfscanf, *note fread: XREFfread, *note fopen: XREFfopen. -- Built-in Function: STR = fgets (FID) -- Built-in Function: STR = fgets (FID, LEN) Read characters from a file, stopping after a newline, or EOF, or LEN characters have been read. The characters read, including the possible trailing newline, are returned as a string. If LEN is omitted, 'fgets' reads until the next newline character. If there are no more characters to read, 'fgets' returns -1. To read a line and discard the terminating newline see 'fgetl'. See also: *note fputs: XREFfputs, *note fgetl: XREFfgetl, *note fscanf: XREFfscanf, *note fread: XREFfread, *note fopen: XREFfopen. -- Built-in Function: NLINES = fskipl (FID) -- Built-in Function: NLINES = fskipl (FID, COUNT) -- Built-in Function: NLINES = fskipl (FID, Inf) Read and skip COUNT lines from the file specified by the file descriptor FID. 'fskipl' discards characters until an end-of-line is encountered exactly COUNT-times, or until the end-of-file marker is found. If COUNT is omitted, it defaults to 1. COUNT may also be 'Inf', in which case lines are skipped until the end of the file. This form is suitable for counting the number of lines in a file. Returns the number of lines skipped (end-of-line sequences encountered). See also: *note fgetl: XREFfgetl, *note fgets: XREFfgets, *note fscanf: XREFfscanf, *note fopen: XREFfopen.  File: octave.info, Node: Formatted Output, Next: Output Conversion for Matrices, Prev: Line-Oriented Input, Up: C-Style I/O Functions 14.2.4 Formatted Output ----------------------- This section describes how to call 'printf' and related functions. The following functions are available for formatted output. They are modeled after the C language functions of the same name, but they interpret the format template differently in order to improve the performance of printing vector and matrix values. Implementation Note: For compatibility with MATLAB, escape sequences in the template string (e.g., "\n" => newline) are expanded even when the template string is defined with single quotes. -- Built-in Function: printf (TEMPLATE, ...) Print optional arguments under the control of the template string TEMPLATE to the stream 'stdout' and return the number of characters printed. See the Formatted Output section of the GNU Octave manual for a complete description of the syntax of the template string. Implementation Note: For compatibility with MATLAB, escape sequences in the template string (e.g., "\n" => newline) are expanded even when the template string is defined with single quotes. See also: *note fprintf: XREFfprintf, *note sprintf: XREFsprintf, *note scanf: XREFscanf. -- Built-in Function: fprintf (FID, TEMPLATE, ...) -- Built-in Function: fprintf (TEMPLATE, ...) -- Built-in Function: NUMBYTES = fprintf (...) This function is equivalent to 'printf', except that the output is written to the file descriptor FID instead of 'stdout'. If FID is omitted, the output is written to 'stdout' making the function exactly equivalent to 'printf'. The optional output returns the number of bytes written to the file. Implementation Note: For compatibility with MATLAB, escape sequences in the template string (e.g., "\n" => newline) are expanded even when the template string is defined with single quotes. See also: *note fputs: XREFfputs, *note fdisp: XREFfdisp, *note fwrite: XREFfwrite, *note fscanf: XREFfscanf, *note printf: XREFprintf, *note sprintf: XREFsprintf, *note fopen: XREFfopen. -- Built-in Function: sprintf (TEMPLATE, ...) This is like 'printf', except that the output is returned as a string. Unlike the C library function, which requires you to provide a suitably sized string as an argument, Octave's 'sprintf' function returns the string, automatically sized to hold all of the items converted. Implementation Note: For compatibility with MATLAB, escape sequences in the template string (e.g., "\n" => newline) are expanded even when the template string is defined with single quotes. See also: *note printf: XREFprintf, *note fprintf: XREFfprintf, *note sscanf: XREFsscanf. The 'printf' function can be used to print any number of arguments. The template string argument you supply in a call provides information not only about the number of additional arguments, but also about their types and what style should be used for printing them. Ordinary characters in the template string are simply written to the output stream as-is, while "conversion specifications" introduced by a '%' character in the template cause subsequent arguments to be formatted and written to the output stream. For example, pct = 37; filename = "foo.txt"; printf ("Processed %d%% of '%s'.\nPlease be patient.\n", pct, filename); produces output like Processed 37% of 'foo.txt'. Please be patient. This example shows the use of the '%d' conversion to specify that a scalar argument should be printed in decimal notation, the '%s' conversion to specify printing of a string argument, and the '%%' conversion to print a literal '%' character. There are also conversions for printing an integer argument as an unsigned value in octal, decimal, or hexadecimal radix ('%o', '%u', or '%x', respectively); or as a character value ('%c'). Floating-point numbers can be printed in normal, fixed-point notation using the '%f' conversion or in exponential notation using the '%e' conversion. The '%g' conversion uses either '%e' or '%f' format, depending on what is more appropriate for the magnitude of the particular number. You can control formatting more precisely by writing "modifiers" between the '%' and the character that indicates which conversion to apply. These slightly alter the ordinary behavior of the conversion. For example, most conversion specifications permit you to specify a minimum field width and a flag indicating whether you want the result left- or right-justified within the field. The specific flags and modifiers that are permitted and their interpretation vary depending on the particular conversion. They're all described in more detail in the following sections.  File: octave.info, Node: Output Conversion for Matrices, Next: Output Conversion Syntax, Prev: Formatted Output, Up: C-Style I/O Functions 14.2.5 Output Conversion for Matrices ------------------------------------- When given a matrix value, Octave's formatted output functions cycle through the format template until all the values in the matrix have been printed. For example: printf ("%4.2f %10.2e %8.4g\n", hilb (3)); -| 1.00 5.00e-01 0.3333 -| 0.50 3.33e-01 0.25 -| 0.33 2.50e-01 0.2 If more than one value is to be printed in a single call, the output functions do not return to the beginning of the format template when moving on from one value to the next. This can lead to confusing output if the number of elements in the matrices are not exact multiples of the number of conversions in the format template. For example: printf ("%4.2f %10.2e %8.4g\n", [1, 2], [3, 4]); -| 1.00 2.00e+00 3 -| 4.00 If this is not what you want, use a series of calls instead of just one.  File: octave.info, Node: Output Conversion Syntax, Next: Table of Output Conversions, Prev: Output Conversion for Matrices, Up: C-Style I/O Functions 14.2.6 Output Conversion Syntax ------------------------------- This section provides details about the precise syntax of conversion specifications that can appear in a 'printf' template string. Characters in the template string that are not part of a conversion specification are printed as-is to the output stream. The conversion specifications in a 'printf' template string have the general form: % FLAGS WIDTH [ . PRECISION ] TYPE CONVERSION For example, in the conversion specifier '%-10.8ld', the '-' is a flag, '10' specifies the field width, the precision is '8', the letter 'l' is a type modifier, and 'd' specifies the conversion style. (This particular type specifier says to print a numeric argument in decimal notation, with a minimum of 8 digits left-justified in a field at least 10 characters wide.) In more detail, output conversion specifications consist of an initial '%' character followed in sequence by: * Zero or more "flag characters" that modify the normal behavior of the conversion specification. * An optional decimal integer specifying the "minimum field width". If the normal conversion produces fewer characters than this, the field is padded with spaces to the specified width. This is a _minimum_ value; if the normal conversion produces more characters than this, the field is _not_ truncated. Normally, the output is right-justified within the field. You can also specify a field width of '*'. This means that the next argument in the argument list (before the actual value to be printed) is used as the field width. The value is rounded to the nearest integer. If the value is negative, this means to set the '-' flag (see below) and to use the absolute value as the field width. * An optional "precision" to specify the number of digits to be written for the numeric conversions. If the precision is specified, it consists of a period ('.') followed optionally by a decimal integer (which defaults to zero if omitted). You can also specify a precision of '*'. This means that the next argument in the argument list (before the actual value to be printed) is used as the precision. The value must be an integer, and is ignored if it is negative. * An optional "type modifier character". This character is ignored by Octave's 'printf' function, but is recognized to provide compatibility with the C language 'printf'. * A character that specifies the conversion to be applied. The exact options that are permitted and how they are interpreted vary between the different conversion specifiers. See the descriptions of the individual conversions for information about the particular options that they use.