Geek Gadgets 1

home *** CD-ROM | disk | FTP | other *** search

/ Geek Gadgets 1 / ADE-1.bin / ade-bin / info / octave.info-2 < prev next >

Wrap

GNU Info File | 1996-10-12 | 48.6 KB | 1,511 lines

This is Info file octave.info, produced by Makeinfo-1.64 from the input file octave.texi. Copyright (C) 1993, 1994, 1995 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: Startup Files, Prev: Command Line Options, Up: Invoking Octave Startup Files ============= When Octave starts, it looks for commands to execute from the following files: `OCTAVE_HOME/lib/octave/VERSION/startup/octaverc' Where `OCTAVE_HOME' is the directory in which all of Octave is installed (the default is `/usr/local'), and `VERSION' is the version number of Octave. This file is provided so that changes to the default Octave environment can be made globally for all users. Some care should be taken when making changes to this file, since all users of Octave at your site will be affected. `~/.octaverc' This file is normally used to make personal changes to the default Octave environment. `.octaverc' This file can be used to make changes to the default Octave environment for a particular project. Octave searches for this file after it reads `~/.octaverc', so any use of the `cd' command in the `~/.octaverc' file will affect the directory that Octave searches for the file `.octaverc'. If you start Octave in your home directory, it will avoid executing commands from `~/.octaverc' twice. A message will be displayed as each of these files is read if you invoke Octave with the `--verbose' option but without the `--silent' option. Startup files may contain any valid Octave commands, including multiple function definitions. File: octave.info, Node: Expressions, Next: Statements, Prev: Invoking Octave, Up: Top 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: * Constant Expressions:: * Matrices:: * Ranges:: * Variables:: * Index Expressions:: * Data Structures:: * Calling Functions:: * Global Variables:: * Keywords:: * Arithmetic Ops:: * Comparison Ops:: * Boolean Expressions:: * Assignment Ops:: * Increment Ops:: * Operator Precedence:: File: octave.info, Node: Constant Expressions, Next: Matrices, Prev: Expressions, Up: Expressions Constant Expressions ==================== The simplest type of expression is the "constant", which always has the same value. There are two types of constants: numeric constants and string constants. * Menu: * Numeric Constants:: * String Constants:: File: octave.info, Node: Numeric Constants, Next: String Constants, Prev: Constant Expressions, Up: Constant Expressions Numeric Constants ----------------- A "numeric constant" may be a scalar, a vector, or a matrix, and it may contain complex values. The simplest form of a numeric constant, a scalar, is a single number that can be an integer, a decimal fraction, a number in scientific (exponential) notation, or a complex number. Note that all numeric values are represented within Octave in double-precision floating point format (complex constants are stored as pairs of double-precision floating point values). Here are some examples of real-valued numeric constants, which all have the same value: 105 1.05e+2 1050e-1 To specify complex constants, you can write an expression of the form 3 + 4i 3.0 + 4.0i 0.3e1 + 40e-1i all of which are equivalent. The letter `i' in the previous example stands for the pure imaginary constant, defined as `sqrt (-1)'. For Octave to recognize a value as the imaginary part of a complex constant, a space must not appear between the number and the `i'. If it does, Octave will print an error message, like this: octave:13> 3 + 4 i parse error: 3 + 4 i ^ You may also use `j', `I', or `J' in place of the `i' above. All four forms are equivalent. File: octave.info, Node: String Constants, Prev: Numeric Constants, Up: Constant Expressions String Constants ---------------- A "string constant" consists of a sequence of characters enclosed in either double-quote or single-quote marks. For example, both of the following expressions "parrot" 'parrot' represent the string whose contents are `parrot'. Strings in Octave can be of any length. Since the single-quote mark is also used for the transpose operator (*note Arithmetic Ops::.) but double-quote marks have no other purpose in Octave, it is best to use double-quote marks to denote strings. Some characters cannot be included literally in a string constant. You represent them instead with "escape sequences", which are character sequences beginning with a backslash (`\'). One use of an escape sequence is to include a double-quote (single-quote) character in a string constant that has been defined using double-quote (single-quote) marks. Since a plain double-quote would end the string, you must use `\"' to represent a single double-quote character as a part of the string. The backslash character itself is another character that cannot be included normally. You must write `\\' to put one backslash in the string. Thus, the string whose contents are the two characters `"\' must be written `"\"\\"'. Another use of backslash is to represent unprintable characters such as newline. While there is nothing to stop you from writing most of these characters directly in a string constant, they may look ugly. Here is a table of all the escape sequences used in Octave. They are the same as those used in the C programming langauge. `\\' Represents a literal backslash, `\'. `\"' Represents a literal double-quote character, `"'. `\'' Represents a literal single-quote character, `''. `\a' Represents the "alert" character, control-g, ASCII code 7. `\b' Represents a backspace, control-h, ASCII code 8. `\f' Represents a formfeed, control-l, ASCII code 12. `\n' Represents a newline, control-j, ASCII code 10. `\r' Represents a carriage return, control-m, ASCII code 13. `\t' Represents a horizontal tab, control-i, ASCII code 9. `\v' Represents a vertical tab, control-k, ASCII code 11. Strings may be concatenated using the notation for defining matrices. For example, the expression [ "foo" , "bar" , "baz" ] produces the string whose contents are `foobarbaz'. The next section explains more about how to create matrices. File: octave.info, Node: Matrices, Next: Ranges, Prev: Constant Expressions, Up: Expressions Matrices ======== It is easy to define a matrix of values in Octave. The size of the matrix is determined automatically, so it is not necessary to explicitly state the dimensions. The expression a = [1, 2; 3, 4] results in the matrix a = 1 2 3 4 The commas which separate the elements on a row may be omitted, and the semicolon that marks the beginning of a new row may be replaced by one or more new lines. The expression a = [ 1 2 3 4 ] is equivalent to the one above. Elements of a matrix may be arbitrary expressions, provided that the dimensions all agree. For example, given the above matrix, the expression [ a, a ] produces the matrix ans = 1 2 1 2 3 4 3 4 but the expression [ a 1 ] produces the error error: number of rows must match Inside the square brackets that delimit a matrix expression, Octave looks at the surrounding context to determine whether spaces should be converted into element separators, or simply ignored, so commands like [ linspace (1, 2) ] will work. However, some possible sources of confusion remain. For example, in the expression [ 1 - 1 ] the `-' is treated as a binary operator and the result is the scalar 0, but in the expression [ 1 -1 ] the `-' is treated as a unary operator and the result is the vector `[ 1 -1 ]'. Given `a = 1', the expression [ 1 a' ] results in the single quote character `'' being treated as a transpose operator and the result is the vector `[ 1 1 ]', but the expression [ 1 a ' ] produces the error message error: unterminated string constant because to not do so would make it impossible to correctly parse the valid expression [ a 'foo' ] For clarity, it is probably best to always use commas and semicolons to separate matrix elements and rows. It is possible to enforce this style by setting the built-in variable `whitespace_in_literal_matrix' to `"ignore"'. *Note Built-in Variables::. * Menu: * Empty Matrices:: File: octave.info, Node: Empty Matrices, Prev: Matrices, Up: Matrices Empty Matrices -------------- A matrix may have one or both dimensions zero, and operations on empty matrices are handled as described by Carl de Boor in `An Empty Exercise', SIGNUM, Volume 25, pages 2-6, 1990 and C. N. Nett and W. M. Haddad, in `A System-Theoretic Appropriate Realization of the Empty Matrix Concept', IEEE Transactions on Automatic Control, Volume 38, Number 5, May 1993. Briefly, given a scalar `s', and an M by N matrix `M(mxn)', and an M by N empty matrix `[](mxn)' (with either one or both dimensions equal to zero), the following are true: s * [](mxn) = [](mxn) * s = [](mxn) [](mxn) + [](mxn) = [](mxn) [](0xm) * M(mxn) = [](0xn) M(mxn) * [](nx0) = [](mx0) [](mx0) * [](0xn) = 0(mxn) By default, dimensions of the empty matrix are now printed along with the empty matrix symbol, `[]'. For example: octave:13> zeros (3, 0) ans = [](3x0) The built-in variable `print_empty_dimensions' controls this behavior (*note User Preferences::.). Empty matrices may also be used in assignment statements as a convenient way to delete rows or columns of matrices. *Note Assignment Expressions: Assignment Ops. File: octave.info, Node: Ranges, Next: Variables, Prev: Matrices, Up: Expressions Ranges ====== A "range" is a convenient way to write a row vector with evenly spaced elements. A range constant is defined by the value of the first element in the range, an optional value for the increment between elements, and a maximum value which the elements of the range will not exceed. The base, increment, and limit are separated by colons (the `:' character) and may contain any arithmetic expressions and function calls. If the increment is omitted, it is assumed to be 1. For example, the range 1 : 5 defines the set of values `[ 1 2 3 4 5 ]' (the increment has been omitted, so it is taken as 1), and the range 1 : 3 : 5 defines the set of values `[ 1 4 ]'. In this case, the base value is 1, the increment is 3, and the limit is 5. Although a range constant specifies a row vector, Octave does *not* convert range constants to vectors unless it is necessary to do so. This allows you to write a constant like `1 : 10000' without using up 80,000 bytes of storage on a typical 32-bit workstation. Note that the upper (or lower, if the increment is negative) bound on the range is not always included in the set of values, and that ranges defined by floating point values can produce surprising results because Octave uses floating point arithmetic to compute the values in the range. If it is important to include the endpoints of a range and the number of elements is known, you should use the `linspace' function instead (*note Special Matrices::.). File: octave.info, Node: Variables, Next: Index Expressions, Prev: Ranges, Up: Expressions Variables ========= Variables let you give names to values and refer to them later. You have already seen variables in many of the examples. The name of a variable must be a sequence of letters, digits and underscores, but it may not begin with a digit. Octave does not enforce a limit on the length of variable names, but it is seldom useful to have variables with names longer than about 30 characters. The following are all valid variable names x x15 __foo_bar_baz__ fucnrdthsucngtagdjb Case is significant in variable names. The symbols `a' and `A' are distinct variables. A variable name is a valid expression by itself. It represents the variable's current value. Variables are given new values with "assignment operators" and "increment operators". *Note Assignment Expressions: Assignment Ops. A number of variables have special built-in meanings. For example, `PWD' holds the current working directory, and `pi' names the ratio of the circumference of a circle to its diameter. *Note Built-in Variables::, for a list of all the predefined variables. Some of these built-in symbols are constants and may not be changed. Others can be used and assigned just like all other variables, but their values are also used or changed automatically by Octave. Variables in Octave can be assigned either numeric or string values. Variables may not be used before they have been given a value. Doing so results in an error. File: octave.info, Node: Index Expressions, Next: Data Structures, Prev: Variables, Up: Expressions 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 expression. Matrices require two indices unless the value of the built-in variable `do_fortran_indexing' is `"true"', in which case a matrix may also be indexed by a single expression (*note User Preferences::.). Given the matrix a = [1, 2; 3, 4] all of the following expressions are equivalent a (1, [1, 2]) a (1, 1:2) a (1, :) and select the first row of the matrix. A special form of indexing may be used to select elements of a matrix or vector. If the indices are vectors made up of only ones and zeros, the result is a new matrix whose elements correspond to the elements of the index vector that are equal to one. For example, a = [1, 2; 3, 4]; a ([1, 0], :) selects the first row of the matrix `a'. This operation can be useful for selecting elements of a matrix based on some condition, since the comparison operators return matrices of ones and zeros. Unfortunately, this special zero-one form of indexing leads to a conflict with the standard indexing operation. For example, should the following statements a = [1, 2; 3, 4]; a ([1, 1], :) return the original matrix, or the matrix formed by selecting the first row twice? Although this conflict is not likely to arise very often in practice, you may select the behavior you prefer by setting the built-in variable `prefer_zero_one_indexing' (*note User Preferences::.). Finally, indexing a scalar with a vector of ones can be used to create a vector the same size as the the index vector, with each element equal to the value of the original scalar. For example, the following statements a = 13; a ([1, 1, 1, 1]) produce a vector whose four elements are all equal to 13. Similarly, indexing a scalar with two vectors of ones can be used to create a matrix. For example the following statements a = 13; a ([1, 1], [1, 1, 1]) create a 2 by 3 matrix with all elements equal to 13. This is an obscure notation and should be avoided. It is better to use the function `ones' to generate a matrix of the appropriate size whose elements are all one, and then to scale it to produce the desired result. *Note Special Matrices::. File: octave.info, Node: Data Structures, Next: Calling Functions, Prev: Index Expressions, Up: Expressions Data Structures =============== Octave includes a limited amount of support for organizing data in structures. The current implementation uses an associative array with indices limited to strings, but the syntax is more like C-style structures. Here are some examples of using data structures in Octave. Elements of structures can be of any value type. octave:1> x.a = 1; x.b = [1, 2; 3, 4]; x.c = "string"; octave:2> x.a x.a = 1 octave:3> x.b x.b = 1 2 3 4 octave:4> x.c x.c = string Structures may be copied. octave:1> y = x y = <structure: a b c> Note that when the value of a structure is printed, Octave only displays the names of the elements. This prevents long and confusing output from large deeply nested structures, but makes it more difficult to view the values of simple structures, so this behavior may change in a future version of Octave. Since structures are themselves values, structure elements may reference other structures. The following statements change the value of the element `b' of the structure `x' to be a data structure containing the single element `d', which has a value of 3. octave:1> x.b.d = 3 x.b.d = 3 octave:2> x.b x.b = <structure: d> octave:3> x.b.d x.b.d = 3 Functions can return structures. For example, the following function separates the real and complex parts of a matrix and stores them in two elements of the same structure variable. octave:1> function y = f (x) > y.re = real (x); > y.im = imag (x); > endfunction When called with a complex-valued argument, `f' returns the data structure containing the real and imaginary parts of the original function argument. octave:1> f (rand (3) + rand (3) * I); ans = <structure: im re> octave:3> ans.im ans.im = 0.093411 0.229690 0.627585 0.415128 0.221706 0.850341 0.894990 0.343265 0.384018 octave:4> ans.re ans.re = 0.56234 0.14797 0.26416 0.72120 0.62691 0.20910 0.89211 0.25175 0.21081 Function return lists can include structure elements, and they may be indexed like any other variable. octave:1> [x.u, x.s(2:3,2:3), x.v] = svd ([1, 2; 3, 4]) x.u = -0.40455 -0.91451 -0.91451 0.40455 x.s = 0.00000 0.00000 0.00000 0.00000 5.46499 0.00000 0.00000 0.00000 0.36597 x.v = -0.57605 0.81742 -0.81742 -0.57605 octave:8> x x = <structure: s u v> You can also use the function `is_struct' to determine whether a given value is a data structure. For example is_struct (x) returns 1 if the value of the variable X is a data structure. This feature should be considered experimental, but you should expect it to work. Suggestions for ways to improve it are welcome. File: octave.info, Node: Calling Functions, Next: Global Variables, Prev: Data Structures, Up: Expressions 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, Prev: Calling Functions, Up: Calling Functions 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 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"'. File: octave.info, Node: Recursion, Prev: Call by Value, Up: Calling Functions Recursion --------- Recursive function calls are allowed. A "recursive function" is one which calls itself, either directly or indirectly. For example, here is an inefficient(1) 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. There is currently no limit on the recursion depth, so infinite recursion is possible. If this happens, Octave will consume more and more memory attempting to store intermediate values for each function call context until there are no more resources available. This is obviously undesirable, and will probably be fixed in some future version of Octave by allowing users to specify a maximum allowable recursion depth. ---------- Footnotes ---------- (1) 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: Global Variables, Next: Keywords, Prev: Calling Functions, Up: Expressions Global Variables ================ A variable that has been declared "global" may be accessed from within a function body without having to pass it as a formal parameter. A variable may be declared global using a `global' declaration statement. The following statements are all global declarations. global a global b = 2 global c = 3, d, e = 5 It is necessary declare a variable as global within a function body in order to access it. For example, global x function f () x = 1; endfunction f () does *not* set the value of the global variable `x' to 1. In order to change the value of the global variable `x', you must also declare it to be global within the function body, like this function f () global x; x = 1; endfunction Passing a global variable in a function parameter list will make a local copy and not modify the global value. For example: octave:1> function f (x) > x = 3 > endfunction octave:2> global x = 0 octave:3> x # This is the value of the global variable. x = 0 octave:4> f (x) x = 3 # The value of the local variable x is 3. octave:5> x # But it was a *copy* so the global variable x = 0 # remains unchanged. File: octave.info, Node: Keywords, Next: Arithmetic Ops, Prev: Global Variables, Up: Expressions Keywords ======== The following identifiers are keywords, and may not be used as variable or function names: break endfor function return continue endfunction global while else endif gplot elseif endwhile gsplot end for if The following command-like functions are also keywords, and may not be used as variable or function names: casesen document history set cd edit_history load show clear help ls who dir format run_history save File: octave.info, Node: Arithmetic Ops, Next: Comparison Ops, Prev: Keywords, Up: Expressions Arithmetic Operators ==================== The following arithmetic operators are available, and work on scalars and matrices. `X + Y' Addition. If both operands are matrices, the number of rows and columns must both agree. If one operand is a scalar, its value is added to all the elements of the other operand. `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. `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'. `X .* Y' Element by element multiplication. If both operands are matrices, the number of rows and columns must both agree. `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. `-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. File: octave.info, Node: Comparison Ops, Next: Boolean Expressions, Prev: Arithmetic Ops, Up: Expressions Comparison Operators ==================== "Comparison operators" compare numeric values for relationships such as equality. They are written using *relational operators*, which are a superset of those in C. 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. For example, evaluating the expression [1, 2; 3, 4] == [1, 3; 2, 4] returns the result ans = 1 0 0 1 `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' `X <> Y' True if X is not equal to Y. For matrix and vector arguments, the above table should be read as "an element of the result matrix (vector) is true if the corresponding elements of the argument matrices (vectors) satisfy the specified condition" String comparisons should be performed with the `strcmp' function, not with the comparison operators listed above. *Note Calling Functions::. File: octave.info, Node: Boolean Expressions, Next: Assignment Ops, Prev: Comparison Ops, Up: Expressions 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, Prev: Boolean Expressions, Up: Boolean Expressions Element-by-element Boolean Operators ------------------------------------ An element-by-element "boolean expression" is a combination of comparison expressions or matching 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, before being used in the condition of an `if' or `while' statement, an implicit conversion from a matrix value to a scalar value occurs using the equivalent of `all (all (X))'. That is, a 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. For matrix operands, 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, the dimensions of the operands must conform if both are matrices. 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. File: octave.info, Node: Short-circuit Boolean Operators, Prev: Element-by-element Boolean Operators, Up: Boolean Expressions 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 (all (BOOLEAN1))'. If it is false, the result of the expression is 0. If it is true, the expression BOOLEAN2 is evaluated and converted to a scalar using the equivalent of the operation `all (all (BOOLEAN1))'. If it is true, the result of the expression is 1. Otherwise, the result of the expression is 0. `BOOLEAN1 || BOOLEAN2' The expression BOOLEAN1 is evaluated and converted to a scalar using the equivalent of the operation `all (all (BOOLEAN1))'. If it is true, the result of the expression is 1. If it is false, the expression BOOLEAN2 is evaluated and converted to a scalar using the equivalent of the operation `all (all (BOOLEAN1))'. If it is true, the result of the expression is 1. Otherwise, the result of the expression is 0. 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 && isstr (c)) ... instead of having to use two `if' statements to avoid attempting to evaluate an argument that doesn't exist. function f (a, b, c) if (nargin > 2) if (isstr (c)) ... File: octave.info, Node: Assignment Ops, Next: Increment Ops, Prev: Boolean Expressions, Up: Expressions 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. 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.) The `=' sign is called an "assignment operator". It is the simplest assignment operator because the value of the right-hand operand is stored unchanged. 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. 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, c, d] = [u, s, v] = svd (a) is equivalent to the expression above, except that the value of the variable `d' is left unchanged, and the expression [a, b] = [u, s, v] = svd (a) is equivalent to [u, s, v] = svd (a) a = u b = s 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 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. It is not currently possible to increment index expressions. For example, you might expect that the expression `V(4)++' would increment the fourth element of the vector V, but instead it results in a parse error. This problem may be fixed in a future release of Octave. File: octave.info, Node: Operator Precedence, Prev: Increment Ops, Up: Expressions 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, and exponentiation 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 increasing precedence. `statement separators' `;', `,'. `assignment' `='. This operator groups right to left. `logical "or" and "and"' `||', `&&'. `element-wise "or" and "and"' `|', `&'. `relational' `<', `<=', `==', `>=', `>', `!=', `~=', `<>'. `colon' `:'. `add, subtract' `+', `-'. `multiply, divide' `*', `/', `\', `.\', `.*', `./'. `transpose' `'', `.'' `unary plus, minus, increment, decrement, and ``not''' `+', `-', `++', `--', `!', `~'. `exponentiation' `^', `**', `.^', `.**'. File: octave.info, Node: Statements, Next: Functions and Scripts, Prev: Expressions, Up: Top 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 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 while Statement:: * The for Statement:: * The break Statement:: * The continue Statement:: * The unwind_protect Statement:: * Continuation Lines:: File: octave.info, Node: The if Statement, Next: The while Statement, Prev: Statements, Up: Statements 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 non-zero, 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 *all* of the elements are non-zero. 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 satement. 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::.