This is Info file octave.info, produced by Makeinfo version 1.67 from the input file ./octave.texi. START-INFO-DIR-ENTRY * Octave: (octave). Interactive language for numerical computations. END-INFO-DIR-ENTRY Copyright (C) 1996, 1997 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: Evaluation, Next: Statements, Prev: Expressions, Up: Top 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, or use a string as the name of a function to call. The `eval' and `feval' functions allow you to do just that, and are necessary in order to evaluate commands that are not known until run time, or to write functions that will need to call user-supplied functions. - Built-in Function: eval (COMMAND) Parse the string COMMAND and evaluate it as if it were an Octave program, returning the last value computed. The COMMAND is evaluated in the current context, so any results remain available after `eval' returns. For example, eval ("a = 13") -| a = 13 => 13 In this case, the value of the evaluated expression is printed and it is also returned returned from `eval'. Just as with any other expression, you can turn printing off by ending the expression in a semicolon. For example, eval ("a = 13;") => 13 In this example, the variable `a' has been given the value 13, but the value of the expression is not printed. You can also turn off automatic printing for all expressions executed by `eval' using the variable `default_eval_print_flag'. - Built-in Variable: default_eval_print_flag If the value of this variable is nonzero, Octave prints the results of commands executed by `eval' that do not end with semicolons. If it is zero, automatic printing is suppressed. The default value is 1. - Built-in Function: feval (NAME, ...) Evaluate the function named NAME. Any arguments after the first are passed on to the named function. For example, feval ("acos", -1) => 3.1416 calls the function `acos' with the argument `-1'. The function `feval' is necessary in order to be able to write functions that call user-supplied functions, because Octave does not have a way to declare a pointer to a function (like C) or to declare a special kind of variable that can be used to hold the name of a function (like `EXTERNAL' in Fortran). Instead, you must refer to functions by name, and use `feval' to call them. Here 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.  File: octave.info, Node: Statements, Next: Functions and Scripts, Prev: Evaluation, Up: Top 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 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 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, 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 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::. - Built-in Variable: warn_assign_as_truth_value If the value of `warn_assign_as_truth_value' is nonzero, 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 setting `warn_assign_as_truth_value' to 0, 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. The default value of `warn_assign_as_truth_value' is 1.  File: octave.info, Node: The switch Statement, Next: The while Statement, Prev: The if Statement, Up: Statements The `switch' Statement ====================== The `switch' statement was introduced in Octave 2.0.5. It should be considered experimental, and details of the implementation may change slightly in future versions of Octave. If you have comments or would like to share your experiences in trying to use this new command in real programs, please send them to . (But if you think you've found a bug, please report it to . The general form of the `switch' statement is switch EXPRESSION case LABEL COMMAND_LIST case LABEL COMMAND_LIST ... otherwise COMMAND_LIST endswitch * The identifiers `switch', `case', `otherwise', and `endswitch' are now keywords. * The LABEL may be any expression. * Duplicate LABEL values are not detected. The COMMAND_LIST corresponding to the first match will be executed. * You must have at least one `case LABEL COMMAND_LIST' clause. * The `otherwise COMMAND_LIST' clause is optional. * 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. * 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. * The implementation is simple-minded and currently offers no real performance improvement over an equivalent `if' block, even if all the labels are integer constants. Perhaps a future variation on this could detect all constant integer labels and improve performance by using a jump table.  File: octave.info, Node: The while Statement, Next: The for Statement, Prev: The switch Statement, Up: Statements 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 non-zero, 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 *all* of the elements are non-zero. 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. *Note The if Statement:: for a description of the variable `warn_assign_as_truth_value'.  File: octave.info, Node: The for Statement, Next: The break Statement, Prev: The while Statement, Up: Statements 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 list. *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. 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, Prev: The for Statement, Up: The for Statement 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 `struct_elements' 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 The `break' Statement ===================== The `break' statement jumps out of the innermost `for' or `while' 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 The `continue' Statement ======================== The `continue' statement, like `break', is used only inside `for' or `while' 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 The `unwind_protect' Statement ============================== Octave supports a limited form of exception handling modelled 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 built-in variable `do_fortran_indexing' even if an error occurs while performing the indexing operation. save_do_fortran_indexing = do_fortran_indexing; unwind_protect do_fortran_indexing = "true"; elt = a (idx) unwind_protect_cleanup do_fortran_indexing = save_do_fortran_indexing; end_unwind_protect Without `unwind_protect', the value of DO_FORTRAN_INDEXING would not be restored if an error occurs while performing the indexing operation because evaluation would stop at the point of the error and the statement to restore the value would not be executed.  File: octave.info, Node: The try Statement, Next: Continuation Lines, Prev: The unwind_protect Statement, Up: Statements The `try' Statement =================== In addition to unwind_protect, Octave supports another limited form of exception handling. The general 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 access the text of the message that would have been printed in the builtin constant `__error_text__'. This is the same as `eval (TRY, CATCH)' (which may now also use `__error_text__') but it is more efficient since the commands do not need to be parsed each time the TRY and CATCH statements are evaluated. *Note Error Handling::, for more information about the `__error_text__' variable. Octave's TRY block is a very limited variation on the Lisp condition-case form (limited because it cannot handle different classes of errors separately). Perhaps at some point Octave can have some sort of classification of errors and try-catch can be improved to be as powerful as condition-case in Lisp.  File: octave.info, Node: Continuation Lines, Prev: The try Statement, Up: Statements 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 `...' or `\' 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. The backslash character on the second line above is interpreted a continuation character, *not* as a division operator. For continuation lines that do not occur inside string constants, whitespace and comments may appear between the continuation marker and the newline character. 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 string constants, the continuation marker must appear at the end of the line just before the newline character. 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) suess (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: Error Handling, Prev: Statements, Up: Top Functions and Script Files ************************** 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: * Defining Functions:: * Multiple Return Values:: * Variable-length Argument Lists:: * Variable-length Return Lists:: * Returning From a Function:: * Function Files:: * Script Files:: * Dynamically Linked Functions:: * Organization of Functions::  File: octave.info, Node: Defining Functions, Next: Multiple Return Values, Prev: Functions and Scripts, Up: Functions and Scripts 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 `beep' 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 (is_vector (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: `retval' undefined near line 1 column 10 error: evaluating index expression near line 7, column 1 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 (is_vector (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 (is_vector (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. - Automatic Variable: nargin When a function is called, this local variable is automatically initialized to the number of arguments passed to the function. At the top level, `nargin' holds the number of command line arguments that were passed to Octave. - Built-in Variable: silent_functions If the value of `silent_functions' is nonzero, internal output from a function is suppressed. Otherwise, the results of expressions within a function body that are not terminated with a semicolon will have their values printed. The default value is 0. For example, if the function function f () 2 + 2 endfunction is executed, Octave will either print `ans = 4' or nothing depending on the value of `silent_functions'. - Built-in Variable: warn_missing_semicolon If the value of this variable is nonzero, Octave will warn when statements in function definitions don't end in semicolons. The default value is 0.  File: octave.info, Node: Multiple Return Values, Next: Variable-length Argument Lists, Prev: Defining Functions, Up: Functions and Scripts 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. 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 provided that the built-in variable `define_all_return_values' is nonzero and the value of `default_return_value' is `[]'. *Note Summary of Built-in Variables::. - Automatic Variable: nargout When a function is called, this local variable is automatically initialized to the number of arguments expected to be returned. For example, f () will result in `nargout' being set to 0 inside the function `f' and [s, t] = f () will result in `nargout' being set to 2 inside the function `f'. At the top level, `nargout' is undefined. - Built-in Variable: default_return_value The value given to otherwise uninitialized return values if `define_all_return_values' is nonzero. The default value is `[]'. - Built-in Variable: define_all_return_values If the value of `define_all_return_values' is nonzero, Octave will substitute the value specified by `default_return_value' for any return values that remain undefined when a function returns. The default value is 0. - Function File: nargchk (NARGIN_MIN, NARGIN_MAX, N) If N is in the range NARGIN_MIN through NARGIN_MAX inclusive, return the empty matrix. Otherwise, return a message indicating whether N is too large or too small. This is useful for checking to see that the number of arguments supplied to a function is within an acceptable range.  File: octave.info, Node: Variable-length Argument Lists, Next: Variable-length Return Lists, Prev: Multiple Return Values, Up: Functions and Scripts Variable-length Argument Lists ============================== Octave has a real mechanism for handling functions that take an unspecified number of arguments, so it is not necessary to place an upper bound on the number of optional arguments that a function can accept. Here is an example of a function that uses the new syntax to print a header followed by an unspecified number of values: function foo (heading, ...) disp (heading); va_start (); ## Pre-decrement to skip `heading' arg. while (--nargin) disp (va_arg ()); endwhile endfunction The ellipsis that marks the variable argument list may only appear once and must be the last element in the list of arguments. - Built-in Function: va_start () Position an internal pointer to the first unnamed argument and allows you to cycle through the arguments more than once. It is not necessary to call `va_start' if you do not plan to cycle through the arguments more than once. This function may only be called inside functions that have been declared to accept a variable number of input arguments. - Built-in Function: va_arg () Return the value of the next available argument and move the internal pointer to the next argument. It is an error to call `va_arg()' when there are no more arguments available. Sometimes it is useful to be able to pass all unnamed arguments to another function. The keyword ALL_VA_ARGS makes this very easy to do. For example, function f (...) while (nargin--) disp (va_arg ()) endwhile endfunction function g (...) f ("begin", all_va_args, "end") endfunction g (1, 2, 3) -| begin -| 1 -| 2 -| 3 -| end - Keyword: all_va_args This keyword stands for the entire list of optional argument, so it is possible to use it more than once within the same function without having to call `va_start'. It can only be used within functions that take a variable number of arguments. It is an error to use it in other contexts.  File: octave.info, Node: Variable-length Return Lists, Next: Returning From a Function, Prev: Variable-length Argument Lists, Up: Functions and Scripts Variable-length Return Lists ============================ Octave also has a real mechanism for handling functions that return an unspecified number of values, so it is no longer necessary to place an upper bound on the number of outputs that a function can produce. Here is an example of a function that uses a variable-length return list to produce N values: function [...] = f (n, x) for i = 1:n vr_val (i * x); endfor endfunction [dos, quatro] = f (2, 2) => dos = 2 => quatro = 4 As with variable argument lists, the ellipsis that marks the variable return list may only appear once and must be the last element in the list of returned values. - Built-in Function: vr_val (VAL) Each time this function is called, it places the value of its argument at the end of the list of values to return from the current function. Once `vr_val' has been called, there is no way to go back to the beginning of the list and rewrite any of the return values. This function may only be called within functions that have been declared to return an unspecified number of output arguments (by using the special ellipsis notation described above).  File: octave.info, Node: Returning From a Function, Next: Function Files, Prev: Variable-length Return Lists, Up: Functions and Scripts 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 be caller immediately. At the top level, the return statement is ignored. A `return' statement is assumed at the end of every function definition. - Built-in Variable: return_last_computed_value If the value of `return_last_computed_value' is true, and a function is defined without explicitly specifying a return value, the function will return the value of the last expression. Otherwise, no value will be returned. The default value is 0. For example, the function function f () 2 + 2; endfunction will either return nothing, if the value of `return_last_computed_value' is 0, or 4, if the value of `return_last_computed_value' is nonzero.  File: octave.info, Node: Function Files, Next: Script Files, Prev: Returning From a Function, Up: Functions and Scripts 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 the list of directories specified by the built-in variable `LOADPATH' 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. After that, it checks the time stamp on the file every time it needs the function. If the time stamp indicates that the file has changed since the last time it was read, Octave reads it again. 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. Checking the time stamp every time a function is used is rather inefficient, but it has to be done to ensure that the correct function definition is used. 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 setting the variable `ignore_function_time_stamp' to `"all"', so that Octave will ignore the time stamps for all function files. Setting it to `"system"' gives the default behavior. If you set it to anything else, Octave will check the time stamps on all function files. - Built-in Variable: LOADPATH A colon separated list of directories in which to search for function files. *Note Functions and Scripts::. The value of `LOADPATH' overrides the environment variable `OCTAVE_PATH'. *Note Installation::. `LOADPATH' is now handled in the same way as TeX handles `TEXINPUTS'. If the path starts with `:', the standard path is prepended to the value of `LOADPATH'. If it ends with `:' the standard path is appended to the value of `LOADPATH'. In addition, if any path element ends in `//', that directory and all subdirectories it contains are searched recursively for function files. This can result in a slight delay as Octave caches the lists of files found in the `LOADPATH' the first time Octave searches for a function. After that, searching is usually much faster because Octave normally only needs to search its internal cache for files. To improve performance of recursive directory searching, it is best for each directory that is to be searched recursively to contain *either* additional subdirectories *or* function files, but not a mixture of both. *Note Organization of Functions:: for a description of the function file directories that are distributed with Octave. - Built-in Variable: ignore_function_time_stamp This variable can be used to prevent Octave from making the system call `stat' each time it looks up functions defined in function files. If `ignore_function_time_stamp' 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 `LOADPATH' if they change. If set to `"all"', Octave will not recompile any function files unless their definitions are removed with `clear'. For any other value of `ignore_function_time_stamp', Octave will always check to see if functions defined in function files need to recompiled. The default value of `ignore_function_time_stamp' is `"system"'. - Built-in Variable: warn_function_name_clash If the value of `warn_function_name_clash' is nonzero, a warning is issued when Octave finds that the name of a function defined in a function file differs from the name of the file. (If the names disagree, the name declared inside the file is ignored.) If the value is 0, the warning is omitted. The default value is 1. ---------- Footnotes ---------- (1) The `.m' suffix was chosen for compatibility with MATLAB.