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.

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 it is non-empty and 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. See Functions and Scripts.

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

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 ();
            ...

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 it is non-empty and 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.

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 non-zero, 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 non-zero.

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.

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.  See 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.

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.

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

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

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 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.

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 use the function lasterr to access the text of the message that would have been printed.  This is the same as eval (TRY, CATCH) but it is more efficient since the commands do not need to be parsed each time the TRY and CATCH statements are evaluated.  See Errors and Warnings, for more information about the lasterr function.

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 as 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)
       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.