@c Copyright (C) 1996, 1997 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

@node Statements, Functions and Scripts, Evaluation, Top
@chapter Statements
@cindex statements

Statements may be a simple constant expression or a complicated list of
nested loops and conditional statements.

@dfn{Control statements} such as @code{if}, @code{while}, and so on
control the flow of execution in Octave programs.  All the control
statements start with special keywords such as @code{if} and
@code{while}, to distinguish them from simple expressions.
Many control statements contain other statements; for example, the
@code{if} statement contains another statement which may or may not be
executed.

@cindex @code{end} statement
Each control statement has a corresponding @dfn{end} statement that
marks the end of the end of the control statement.  For example, the
keyword @code{endif} marks the end of an @code{if} statement, and
@code{endwhile} marks the end of a @code{while} statement.  You can use
the keyword @code{end} anywhere a more specific end keyword is expected,
but using the more specific keywords is preferred because if you use
them, Octave is able to provide better diagnostics for mismatched or
missing end tokens.

The list of statements contained between keywords like @code{if} or
@code{while} and the corresponding end statement is called the
@dfn{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::          
@end menu

@node The if Statement, The switch Statement, Statements, Statements
@section The @code{if} Statement
@cindex @code{if} statement
@cindex @code{else} statement
@cindex @code{elseif} statement
@cindex @code{endif} statement

The @code{if} statement is Octave's decision-making statement.  There
are three basic forms of an @code{if} statement.  In its simplest form,
it looks like this:

@example
@group
if (@var{condition})
  @var{then-body}
endif
@end group
@end example

@noindent
@var{condition} is an expression that controls what the rest of the
statement will do.  The @var{then-body} is executed only if
@var{condition} is true.

The condition in an @code{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 @code{if} statement is a vector or a
matrix, it is considered true only if @emph{all} of the elements are
non-zero.

The second form of an if statement looks like this:

@example
@group
if (@var{condition})
  @var{then-body}
else
  @var{else-body}
endif
@end group
@end example

@noindent
If @var{condition} is true, @var{then-body} is executed; otherwise,
@var{else-body} is executed.

Here is an example:

@example
@group
if (rem (x, 2) == 0)
  printf ("x is even\n");
else
  printf ("x is odd\n");
endif
@end group
@end example

In this example, if the expression @code{rem (x, 2) == 0} is true (that
is, the value of @code{x} is divisible by 2), then the first
@code{printf} statement is evaluated, otherwise the second @code{printf}
statement is evaluated.

The third and most general form of the @code{if} statement allows
multiple decisions to be combined in a single statement.  It looks like
this:

@example
@group
if (@var{condition})
  @var{then-body}
elseif (@var{condition})
  @var{elseif-body}
else
  @var{else-body}
endif
@end group
@end example

@noindent
Any number of @code{elseif} clauses may appear.  Each condition is
tested in turn, and if one is found to be true, its corresponding
@var{body} is executed.  If none of the conditions are true and the
@code{else} clause is present, its body is executed.  Only one
@code{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 @code{x} is divisible by 2), then the first @code{printf}
statement is executed.  If it is false, then the second condition is
tested, and if it is true (that is, the value of @code{x} is divisible
by 3), then the second @code{printf} statement is executed.  Otherwise,
the third @code{printf} statement is performed.

@example
@group
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
@end group
@end example

Note that the @code{elseif} keyword must not be spelled @code{else if},
as is allowed in Fortran.  If it is, the space between the @code{else}
and @code{if} will tell Octave to treat this as a new @code{if}
statement within another @code{if} statement's @code{else} clause.  For
example, if you write

@example
@group
if (@var{c1})
  @var{body-1}
else if (@var{c2})
  @var{body-2}
endif
@end group
@end example

@noindent
Octave will expect additional input to complete the first @code{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 @code{end} statements,
or, if you have not used the more specific @code{end} statements
(@code{endif}, @code{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,

@example
@group
if (@var{c1})
  @var{body-1}
else
  if (@var{c2})
    @var{body-2}
  endif
@end group
@end example

@noindent
using the indentation to show how Octave groups the statements.
@xref{Functions and Scripts}.

@defvr {Built-in Variable} warn_assign_as_truth_value
If the value of @code{warn_assign_as_truth_value} is nonzero, a
warning is issued for statements like

@example
if (s = t)
  ...
@end example

@noindent
since such statements are not common, and it is likely that the intent
was to write

@example
if (s == t)
  ...
@end example

@noindent
instead.

There are times when it is useful to write code that contains
assignments within the condition of a @code{while} or @code{if}
statement.  For example, statements like

@example
while (c = getc())
  ...
@end example

@noindent
are common in C programming.

It is possible to avoid all warnings about such statements by setting
@code{warn_assign_as_truth_value} to 0, but that may also
let real errors like

@example
if (x = 1)  # intended to test (x == 1)!
  ...
@end example

@noindent
slip by.

In such cases, it is possible suppress errors for specific statements by
writing them with an extra set of parentheses.  For example, writing the
previous example as

@example
while ((c = getc()))
  ...
@end example

@noindent
will prevent the warning from being printed for this statement, while
allowing Octave to warn about other assignments used in conditional
contexts.

The default value of @code{warn_assign_as_truth_value} is 1.
@end defvr

@node The switch Statement, The while Statement, The if Statement, Statements
@section The @code{switch} Statement
@cindex @code{switch} statement
@cindex @code{case} statement
@cindex @code{otherwise} statement
@cindex @code{endswitch} statement

The @code{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
@email{octave-maintainers@@bevo.che.wisc.edu}.  (But if you think you've
found a bug, please report it to @email{bug-octave@@bevo.che.wisc.edu}.

The general form of the @code{switch} statement is

@example
@group
switch @var{expression}
  case @var{label}
    @var{command_list}
  case @var{label}
    @var{command_list}
  @dots{}

  otherwise
    @var{command_list}
endswitch
@end group
@end example

@itemize @bullet
@item
The identifiers @code{switch}, @code{case}, @code{otherwise}, and
@code{endswitch} are now keywords. 

@item
The @var{label} may be any expression.

@item
Duplicate @var{label} values are not detected.  The @var{command_list}
corresponding to the first match will be executed.

@item
You must have at least one @code{case @var{label} @var{command_list}}
clause.

@item
The @code{otherwise @var{command_list}} clause is optional.

@item
As with all other specific @code{end} keywords, @code{endswitch} may be
replaced by @code{end}, but you can get better diagnostics if you use
the specific forms.

@item
Cases are exclusive, so they don't `fall through' as do the cases
in the switch statement of the C language.

@item
The @var{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

@example
@group
switch (foo)
  case (1) -2
  @dots{}
@end group
@end example

@noindent
would produce surprising results, as would

@example
@group
switch (foo)
  case (1)
  case (2)
    doit ();
  @dots{}
@end group
@end example

@noindent
particularly for C programmers.

@item
The implementation is simple-minded and currently offers no real
performance improvement over an equivalent @code{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.
@end itemize

@defvr {Built-in Variable} warn_variable_switch_label
If the value of this variable is nonzero, Octave will print a warning if
a switch label is not a constant or constant expression
@end defvr

@node The while Statement, The for Statement, The switch Statement, Statements
@section The @code{while} Statement
@cindex @code{while} statement
@cindex @code{endwhile} statement
@cindex loop
@cindex body of a loop

In programming, a @dfn{loop} means a part of a program that is (or at least can
be) executed two or more times in succession.

The @code{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 @code{if} statement, the condition in a
@code{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 @code{while} statement is a vector or a matrix, it is considered
true only if @emph{all} of the elements are non-zero.

Octave's @code{while} statement looks like this:

@example
@group
while (@var{condition})
  @var{body}
endwhile
@end group
@end example

@noindent
Here @var{body} is a statement or list of statements that we call the
@dfn{body} of the loop, and @var{condition} is an expression that
controls how long the loop keeps running.

The first thing the @code{while} statement does is test @var{condition}.
If @var{condition} is true, it executes the statement @var{body}.  After
@var{body} has been executed, @var{condition} is tested again, and if it
is still true, @var{body} is executed again.  This process repeats until
@var{condition} is no longer true.  If @var{condition} is initially
false, the body of the loop is never executed.

This example creates a variable @code{fib} that contains the first ten
elements of the Fibonacci sequence.

@example
@group
fib = ones (1, 10);
i = 3;
while (i <= 10)
  fib (i) = fib (i-1) + fib (i-2);
  i++;
endwhile
@end group
@end example

@noindent
Here the body of the loop contains two statements.

The loop works like this: first, the value of @code{i} is set to 3.
Then, the @code{while} tests whether @code{i} is less than or equal to
10.  This is the case when @code{i} equals 3, so the value of the
@code{i}-th element of @code{fib} is set to the sum of the previous two
values in the sequence.  Then the @code{i++} increments the value of
@code{i} and the loop repeats.  The loop terminates when @code{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.

@xref{The if Statement} for a description of the variable
@code{warn_assign_as_truth_value}.

@node The for Statement, The break Statement, The while Statement, Statements
@section The @code{for} Statement
@cindex @code{for} statement
@cindex @code{endfor} statement

The @code{for} statement makes it more convenient to count iterations of a
loop.  The general form of the @code{for} statement looks like this:

@example
@group
for @var{var} = @var{expression}
  @var{body}
endfor
@end group
@end example

@noindent
where @var{body} stands for any statement or list of statements,
@var{expression} is any valid expression, and @var{var} may take several
forms.  Usually it is a simple variable name or an indexed variable.  If
the value of @var{expression} is a structure, @var{var} may also be a
list.  @xref{Looping Over Structure Elements}, below.

The assignment expression in the @code{for} statement works a bit
differently than Octave's normal assignment statement.  Instead of
assigning the complete result of the expression, it assigns each column
of the expression to @var{var} in turn.  If @var{expression} is a range,
a row vector, or a scalar, the value of @var{var} will be a scalar each
time the loop body is executed.  If @var{var} is a column vector or a
matrix, @var{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
@code{for} statement:

@example
@group
fib = ones (1, 10);
for i = 3:10
  fib (i) = fib (i-1) + fib (i-2);
endfor
@end group
@end example

@noindent
This code works by first evaluating the expression @code{3:10}, to
produce a range of values from 3 to 10 inclusive.  Then the variable
@code{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 @code{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 @code{for} loops as @code{while}
loops, the Octave language has both statements because often a
@code{for} loop is both less work to type and more natural to think of.
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::  
@end menu

@node Looping Over Structure Elements,  , The for Statement, The for Statement
@subsection Looping Over Structure Elements
@cindex structure elements, looping over
@cindex looping over structure elements

A special form of the @code{for} statement allows you to loop over all
the elements of a structure:

@example
@group
for [ @var{val}, @var{key} ] = @var{expression}
  @var{body}
endfor
@end group
@end example

@noindent
In this form of the @code{for} statement, the value of @var{expression}
must be a structure.  If it is, @var{key} and @var{val} are set to the
name of the element and the corresponding value in turn, until there are
no more elements. For example,

@example
@group
x.a = 1
x.b = [1, 2; 3, 4]
x.c = "string"
for [val, key] = x
  key
  val
endfor

     @print{} key = a
     @print{} val = 1
     @print{} key = b
     @print{} val =
     @print{} 
     @print{}   1  2
     @print{}   3  4
     @print{} 
     @print{} key = c
     @print{} val = string
@end group
@end example

The elements are not accessed in any particular order.  If you need to
cycle through the list in a particular way, you will have to use the
function @code{struct_elements} and sort the list yourself.

The @var{key} variable may also be omitted.  If it is, the brackets are
also optional.  This is useful for cycling through the values of all the
structure elements when the names of the elements do not need to be
known.

@node The break Statement, The continue Statement, The for Statement, Statements
@section The @code{break} Statement
@cindex @code{break} statement

The @code{break} statement jumps out of the innermost @code{for} or
@code{while} loop that encloses it.  The @code{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:

@example
@group
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
@end group
@end example

When the remainder is zero in the first @code{while} statement, Octave
immediately @dfn{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 @code{exit} statement
which stops the entire Octave program.)

Here is another program equivalent to the previous one.  It illustrates
how the @var{condition} of a @code{while} statement could just as well
be replaced with a @code{break} inside an @code{if}:

@example
@group
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
@end group
@end example

@node The continue Statement, The unwind_protect Statement, The break Statement, Statements
@section The @code{continue} Statement
@cindex @code{continue} statement

The @code{continue} statement, like @code{break}, is used only inside
@code{for} or @code{while} loops.  It skips over the rest of the loop
body, causing the next cycle around the loop to begin immediately.
Contrast this with @code{break}, which jumps out of the loop altogether.
Here is an example:

@example
@group
# 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
@end group
@end example

If one of the elements of @var{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 @code{continue} statement, but it
should give you a clear understanding of how it works.  Normally, one
would probably write the loop like this:

@example
@group
for x = vec
  if (rem (x, 2) == 0)
    printf ("%d\n", x);
  endif
endfor
@end group
@end example

@node The unwind_protect Statement, The try Statement, The continue Statement, Statements
@section The @code{unwind_protect} Statement
@cindex @code{unwind_protect} statement
@cindex @code{unwind_protect_cleanup}
@cindex @code{end_unwind_protect}

Octave supports a limited form of exception handling modelled after the
unwind-protect form of Lisp.  

The general form of an @code{unwind_protect} block looks like this:

@example
@group
unwind_protect
  @var{body}
unwind_protect_cleanup
  @var{cleanup}
end_unwind_protect
@end group
@end example

@noindent
Where @var{body} and @var{cleanup} are both optional and may contain any
Octave expressions or commands.  The statements in @var{cleanup} are 
guaranteed to be executed regardless of how control exits @var{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 @code{do_fortran_indexing}
even if an error occurs while performing the indexing operation.

@example
@group
save_do_fortran_indexing = do_fortran_indexing;
unwind_protect
  do_fortran_indexing = 1;
  elt = a (idx)
unwind_protect_cleanup
  do_fortran_indexing = save_do_fortran_indexing;
end_unwind_protect
@end group
@end example

Without @code{unwind_protect}, the value of @var{do_fortran_indexing}
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.

@node The try Statement, Continuation Lines, The unwind_protect Statement, Statements
@section The @code{try} Statement
@cindex @code{try} statement
@cindex @code{catch}
@cindex @code{end_try_catch}

In addition to unwind_protect, Octave supports another limited form of
exception handling.

The general form of a @code{try} block looks like this:

@example
@group
try
  @var{body}
catch
  @var{cleanup}
end_try_catch
@end group
@end example

Where @var{body} and @var{cleanup} are both optional and may contain any
Octave expressions or commands.  The statements in @var{cleanup} are
only executed if an error occurs in @var{body}.

No warnings or error messages are printed while @var{body} is
executing.  If an error does occur during the execution of @var{body},
@var{cleanup} can access the text of the message that would have been
printed in the builtin constant @code{__error_text__}.  This is the same
as @code{eval (@var{try}, @var{catch})} (which may now also use
@code{__error_text__}) but it is more efficient since the commands do
not need to be parsed each time the @var{try} and @var{catch} statements
are evaluated.  @xref{Error Handling}, for more information about the
@code{__error_text__} variable.

Octave's @var{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.

@cindex continuation lines
@cindex @code{...} continuation marker
@cindex @code{\} continuation marker

@node Continuation Lines,  , The try Statement, Statements
@section 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 @code{...} or @code{\} are joined with the following line
before they are divided into tokens by Octave's parser.  For example,
the lines

@example
@group
x = long_variable_name ...
    + longer_variable_name \
    - 42
@end group
@end example

@noindent
form a single statement.  The backslash character on the second line
above is interpreted a continuation character, @emph{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

@example
@group
x = long_variable_name ...     # comment one
    + longer_variable_name \   # comment two
    - 42                       # last comment
@end group
@end example

@noindent
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

@example
@group
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
@end group
@end example

@noindent
without having to add to the clutter with continuation markers.