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

@node Expressions, Statements, Introduction, Top
@chapter Expressions
@cindex 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::           
* Calling Functions::           
* Global Variables::            
* Keywords::                    
* Arithmetic Ops::              
* Comparison Ops::              
* Boolean Expressions::         
* Assignment Ops::              
* Increment Ops::               
* Operator Precedence::         
@end menu

@node Constant Expressions, Matrices,  , Expressions
@section Constant Expressions

The simplest type of expression is the @dfn{constant}, which always has
the same value.  There are two types of constants: numeric constants and
string constants.

@unnumberedsubsec Numeric Constants
@cindex numeric constant
@cindex numeric value

A @dfn{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:

@example
105
1.05e+2
1050e-1
@end example

To specify complex constants, you can write an expression of the form

@example
3 + 4i
3.0 + 4.0i
0.3e1 + 40e-1i
@end example

all of which are equivalent.  The letter @samp{i} in the previous example
stands for the pure imaginary constant, defined as
@iftex
@tex
  $\sqrt{-1}$.
@end tex
@end iftex
@ifinfo
  @code{sqrt (-1)}.
@end ifinfo

For Octave to recognize a value as the imaginary part of a complex
constant, a space must not appear between the number and the @samp{i}.
If it does, Octave will print an error message, like this:

@example
octave:13> 3 + 4 i

parse error:

  3 + 4 i
        ^
@end example

You may also use @samp{j}, @samp{I}, or @samp{J} in place of the
@samp{i} above.  All four forms are equivalent.

@unnumberedsubsec String Constants
@cindex strings
@cindex character strings

A @dfn{string constant} consists of a sequence of characters enclosed in
either double-quote or single-quote marks.  For example, both of the
following expressions

@example
"parrot"
'parrot'
@end example

@noindent
represent the string whose contents are @samp{parrot}.  Strings in
Octave can be of any length.

Since the single-quote mark is also used for the transpose operator
(@pxref{Arithmetic Ops}) but double-quote marks have no other purpose in
Octave, it is best to use double-quote marks to denote strings.

@c XXX FIXME XXX -- this is probably pretty confusing.

@cindex escape sequence notation
Some characters cannot be included literally in a string constant.  You
represent them instead with @dfn{escape sequences}, which are character
sequences beginning with a backslash (@samp{\}).

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 @samp{\"} 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 @samp{\\} to put one backslash in the string.  Thus, the string
whose contents are the two characters @samp{"\} must be written
@code{"\"\\"}.

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 @code{awk}:

@table @code
@item \\
Represents a literal backslash, @samp{\}.

@item \"
Represents a literal double-quote character, @samp{"}.

@item \'
Represents a literal single-quote character, @samp{'}.

@item \a
Represents the ``alert'' character, control-g, ASCII code 7.

@item \b
Represents a backspace, control-h, ASCII code 8.

@item \f
Represents a formfeed, control-l, ASCII code 12.

@item \n
Represents a newline, control-j, ASCII code 10.

@item \r
Represents a carriage return, control-m, ASCII code 13.

@item \t
Represents a horizontal tab, control-i, ASCII code 9.

@item \v
Represents a vertical tab, control-k, ASCII code 11.

@c We don't do octal or hex this way yet.
@c
@c @item \@var{nnn}
@c Represents the octal value @var{nnn}, where @var{nnn} are one to three
@c digits between 0 and 7.  For example, the code for the ASCII ESC
@c (escape) character is @samp{\033}.@refill
@c 
@c @item \x@var{hh}@dots{}
@c Represents the hexadecimal value @var{hh}, where @var{hh} are hexadecimal
@c digits (@samp{0} through @samp{9} and either @samp{A} through @samp{F} or
@c @samp{a} through @samp{f}).  Like the same construct in @sc{ansi} C,
@c the escape 
@c sequence continues until the first non-hexadecimal digit is seen.  However,
@c using more than two hexadecimal digits produces undefined results.  (The
@c @samp{\x} escape sequence is not allowed in @sc{posix} @code{awk}.)@refill
@end table

Strings may be concatenated using the notation for defining matrices.
For example, the expression

@example
[ "foo" , "bar" , "baz" ]
@end example

@noindent
produces the string whose contents are @samp{foobarbaz}

@node Matrices, Ranges, Constant Expressions, Expressions
@section Matrices
@cindex matrices

@node Ranges, Variables, Matrices, Expressions
@section Ranges
@cindex range expressions
@cindex expression, range

A @dfn{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, a maximum value which the elements of the range
will not exceed, and an optional value for the increment between
elements.  The base, limit, and increment are separated by colons (the
@samp{:} character) and may contain any arithmetic expressions and
function calls.  If the increment is omitted, it is assumed to be 1.
For example,

@example
1 : 5
@end example

@noindent
defines the set of values @samp{[ 1 2 3 4 5 ]}, and the range

@example
1 : 3 : 5
@end example

@noindent
defines the set of values @samp{[ 1 4 ]}.

The increment is specified between the base and the limit in order to
be compatible with Matlab.

Note that the upper 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 @code{linspace} function instead @xref{Built-in Functions}.

@node Variables, Index Expressions, Ranges, Expressions
@section Variables
@cindex variables, user-defined
@cindex user-defined 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.  Case is significant in variable names.  The symbols
@code{a} and @code{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
@dfn{assignment operators} and @dfn{increment operators}.
@xref{Assignment Ops, ,Assignment Expressions}.

A number of variables have special built-in meanings, such as
@code{PWD}, which holds the current working directory, and @code{pi},
the ratio of the circumference of a circle to its diameter.
@xref{Built-in Variables}, for a list of them.  Most of these built-in
variables 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.

@node Index Expressions, Calling Functions, Variables, Expressions
@section Index Expressions

@node Calling Functions, Global Variables, Index Expressions, Expressions
@section Calling Functions

A @dfn{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 @code{sqrt} computes the square root of a number.

A fixed set of functions are @dfn{built-in}, which means they are
available in every Octave program.  The @code{sqrt} function is one of
these.  @xref{Built-in Functions}, for a list of built-in functions and
their descriptions.  In addition, you can define your own functions in
the program for use elsewhere in the same program.  @xref{Defining
Functions}, for how to do this.

@cindex arguments in function call
The way to use a function is with a @dfn{function call} expression,
which consists of the function name followed by a list of
@dfn{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, write just @samp{()} after the function name
@footnote{You can omit the parenthesis for functions that do not require
any arguments, but it is a good idea to include them anyway, to clearly
indicate that a function call was intended.}.  Here are some examples:

@example
sqrt (x^2 + y^2)      # @r{One argument}
ones (n, m)           # @r{Two arguments}
rand ()               # @r{No arguments}
@end example

Each function expects a particular number of arguments.  For example, the
@code{sqrt} function must be called with a single argument, the number
to take the square root of:

@example
sqrt (@var{argument})
@end example

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 @code{sqrt (@var{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.
@c XXX FIXME XXX -- explain that here.

@node Global Variables, Keywords, Calling Functions, Expressions
@section Global Variables

Passing a global variable in a function parameter list will make a local
copy and not modify the global value.  For example:

@example
octave:1> function f (x)
> x = 3
> end
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.
@end example

@node Keywords, Arithmetic Ops, Global Variables, Expressions
@section Keywords
@cindex keywords

The following identifiers are keywords, and may not be used as variable
or function names:

@example
break       endfor         function    return
continue    endfunction    global      while
else        endif          gplot    
elseif      endwhile       gsplot   
end         for            if       
@end example

The following text-style functions are also keywords, and may not be
used as variable or function names:

@example
casesen     document       history     set
cd          edit           load        show
clear       help           ls          who
dir         format         save
@end example

@node Arithmetic Ops, Comparison Ops, Keywords, Expressions
@section Arithmetic Operators
@cindex arithmetic operators
@cindex operators, arithmetic
@cindex addition
@cindex subtraction
@cindex multiplication
@cindex matrix multiplication
@cindex division
@cindex quotient
@cindex negation
@cindex unary minus
@cindex exponentiation
@cindex transpose
@cindex Hermitian operator
@cindex transpose, complex-conjugate
@cindex complex-conjugate transpose

The arithmetic operators in Octave are:

@table @code
@item @var{x} + @var{y}
Addition.

@item @var{x} .+ @var{y}
Element by element addition.  This operator is equivalent to @code{+}.

@item @var{x} - @var{y}
Subtraction.

@item @var{x} .- @var{y}
Element by element subtraction.  This operator is equivalent to @code{-}.

@item @var{x} * @var{y}
Matrix multiplication.

@item @var{x} .* @var{y}
Element by element multiplication.

@item @var{x} / @var{y}
Right division.

@item @var{x} ./ @var{y}
Element by element right division.

@item @var{x} \ @var{y}
Left division.

@item @var{x} .\ @var{y}
Element by element left division.

@item @var{x} ^ @var{y}
@itemx @var{x} ** @var{y}
Power operator.

@item @var{x} .^ @var{y}
@item @var{x} .** @var{y}
Element by element power operator.

@item -@var{x}
Negation.

@item +@var{x}
Unary plus.  This operator has no effect on the operand.

@item @var{x}'
Complex conjugate transpose.

@item @var{x}.'
Transpose.
@end table

@node Comparison Ops, Boolean Expressions, Arithmetic Ops, Expressions
@section Comparison Operators
@cindex comparison expressions
@cindex expressions, comparison
@cindex relational operators
@cindex operators, relational
@cindex less than operator
@cindex greater than operator
@cindex equality operator
@cindex tests for equality
@cindex equality, tests for

@emph{Comparison operators} compare numeric values for relationships
such as equality.  They are written using @emph{relational operators},
which are a superset of those in C.

For matrix values, they all work on an element by element basis.  For
example, evaluating the expression

@example
[1, 2; 3, 4] == [1, 3; 2, 4]
@end example

@noindent
returns the result

@example
ans =

  1  0
  0  1
@end example

@table @code
@item @var{x} < @var{y}
True if @var{x} is less than @var{y}.

@item @var{x} <= @var{y}
True if @var{x} is less than or equal to @var{y}.

@item @var{x} == @var{y}
True if @var{x} is equal to @var{y}.

@item @var{x} >= @var{y}
True if @var{x} is greater than or equal to @var{y}.

@item @var{x} > @var{y}
True if @var{x} is greater than @var{y}.

@item @var{x} != @var{y}
@itemx @var{x} ~= @var{y}
@itemx @var{x} <> @var{y}
True if @var{x} is not equal to @var{y}.
@end table

String comparisons should be performed with the @code{strcmp} function,
not with the comparison operators listed above.
@xref{Calling Functions}.

@node Boolean Expressions, Assignment Ops, Comparison Ops, Expressions
@section Boolean Expressions
@cindex expressions, boolean
@cindex boolean expressions
@cindex expressions, logical
@cindex logical expressions
@cindex operators, boolean
@cindex boolean operators
@cindex logical operators
@cindex operators, logical
@cindex and operator
@cindex or operator
@cindex not operator

A @dfn{boolean expression} is a combination of comparison expressions or
matching expressions, using the boolean operators ``or'' (@samp{||}),
``and'' (@samp{&&}), and ``not'' (@samp{!}), along with parentheses to
control nesting.  The truth of the boolean expression is computed by
combining the truth values of the component expressions.

Boolean expressions can be used wherever comparison and matching
expressions can be used.  They can be used in @code{if} and @code{while}
statements.  They have numeric values (1 if true, 0 if false), which
come into play if the result of the boolean expression is stored in a
variable, or used in arithmetic.

In addition, every boolean expression is also a valid boolean pattern, so
you can use it as a pattern to control the execution of rules.

Here are descriptions of the three boolean operators, with an example of
each.  It may be instructive to compare these examples with the
analogous examples of boolean patterns
(@pxref{Boolean Expressions}), which use
the same boolean operators in patterns instead of expressions.@refill

@table @code
@item @var{boolean1} & @var{boolean2}
@itemx @var{boolean1} && @var{boolean2}
True if both @var{boolean1} and @var{boolean2} are true.

The subexpression @var{boolean2} is evaluated only if @var{boolean1} is
true.  This can make a difference when @var{boolean2} is an expression
that has side effects.  For example, in the expression

@example
a && b++
@end example

@noindent
the value of the variable @var{b} is only incremented if @var{a} is
nonzero.

@item @var{boolean1} | @var{boolean2}
@item @var{boolean1} || @var{boolean2}
True if at least one of @var{boolean1} or @var{boolean2} is true.

The subexpression @var{boolean2} is evaluated only if @var{boolean1} is
false.  This can make a difference when @var{boolean2} is an expression
that has side effects.

@item ! @var{boolean}
@itemx ~ @var{boolean}
True if @var{boolean} is false.
@end table

@node Assignment Ops, Increment Ops, Boolean Expressions, Expressions
@section Assignment Expressions
@cindex assignment expressions
@cindex assignment operators
@cindex operators, assignment
@cindex expressions, assignment

An @dfn{assignment} is an expression that stores a new value into a
variable.  For example, let's assign the value 1 to the variable
@code{z}:

@example
z = 1
@end example

After this expression is executed, the variable @code{z} has the value 1.
Whatever old value @code{z} had before the assignment is forgotten.

Assignments can store string values also.  For example, this would store
the value @code{"this food is good"} in the variable @code{message}:

@example
thing = "food"
predicate = "good"
message = [ "this " , thing , " is " , predicate ]
@end example

@noindent
(This also illustrates concatenation of strings.)

The @samp{=} sign is called an @dfn{assignment operator}.  It is the
simplest assignment operator because the value of the right-hand
operand is stored unchanged.

@cindex side effect
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 @dfn{side effect}.

@cindex lvalue
The left-hand operand of an assignment need not be a variable
(@pxref{Variables}).  It can also be an element of a matrix
(@pxref{Index Expressions}) or a list of return values
(@pxref{Calling Functions}).  These are all called @dfn{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 @emph{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
@code{foo} has a numeric value at first, and a string value later on:

@example
octave:13> foo = 1
foo = 1
octave:13> foo = "bar"
foo = bar
@end example

@noindent
When the second assignment gives @code{foo} a string value, the fact that
it previously had a numeric value is forgotten.

An assignment is an expression, so it has a value: the same value that
is assigned.  Thus, @code{z = 1} as an expression has the value 1.
One consequence of this is that you can write multiple assignments
together:

@example
x = y = z = 0
@end example

@noindent
stores the value 0 in all three variables.  It does this because the
value of @code{z = 0}, which is 0, is stored into @code{y}, and then
the value of @code{y = z = 0}, which is 0, is stored into @code{x}.

This is also true of assignments to lists of values, so the following is
a valid expression

@example
[a, b, c] = [u, s, v] = svd (a)
@end example

@noindent
that is exactly equivalent to

@example
[u, s, v] = svd (a)
a = u
b = s
c = v
@end example

In expressions like this, the number of values in each part of the
expression need not match.  Extra values on the the right or left of the
@samp{=} sign are ignored.  For example, the expression

@example
[a, b, c, d] = [u, s, v] = svd (a)
@end example

@noindent
is equivalent to the expression above, except that the value of the
variable @samp{d} is left unchanged, and the expression

@example
[a, b] = [u, s, v] = svd (a)
@end example

@noindent
is equivalent to 

@example
[u, s, v] = svd (a)
a = u
b = s
@end example

You can use an assignment anywhere an expression is called for.  For
example, it is valid to write @code{x != (y = 1)} to set @code{y} to 1
and then test whether @code{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.

@node Increment Ops, Operator Precedence, Assignment Ops, Expressions
@section Increment Operators

@emph{Increment operators} increase or decrease the value of a variable
by 1.  

The operator to increment a variable is written as @samp{++}.  It may be
used to increment a variable either before or after taking its value.

For example, to pre-increment the variable @var{x}, you would write
@code{++@var{x}}.  This would add one to @var{x} and then return the new
value of @var{x} as the result of the expression.  It is exactly the
same as the expression @code{@var{x} = @var{x} + 1}.

To post-increment a variable @var{x}, you would write @code{@var{x}++}.
This adds one to the variable @var{x}, but returns the value that
@var{x} had prior to incrementing it.  For example, if @var{x} is equal
to 2, the result of the expression @code{@var{x}++} is 2, and the new
value of @var{x} is 3.

Here is a list of all the increment and decrement expressions.

@table @code
@item ++@var{x}
This expression increments the variable @var{x}.  The value of the
expression is the @emph{new} value of @var{x}.  It is equivalent to the
expression @code{@var{x} = @var{x} + 1}.

@item --@var{x}
This expression decrements the variable @var{x}.  The value of the
expression is the @emph{new} value of @var{x}.  It is equivalent to the
expression @code{@var{x} = @var{x} - 1}.

@item @var{x}++
This expression causes the variable @var{x} to be incremented.  The
value of the expression is the @emph{old} value of @var{x}.

@item @var{x}--
This expression causes the variable @var{x} to be decremented.  The
value of the expression is the @emph{old} value of @var{x}.
@end table

@node Operator Precedence,  , Increment Ops, Expressions
@section Operator Precedence

@dfn{Operator precedence} determines how operators are grouped, when
different operators appear close by in one expression.  For example,
@samp{*} has higher precedence than @samp{+}.  Thus, the expression
@code{a + b * c} means to multiply @code{b} and @code{c}, and then add
@code{a} to the product (i.e., @code{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 always 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
@code{a - b + c} groups as @code{(a - b) + c}, but the expression
@code{a = b = c} groups as @code{a = (b = c)}.

The precedence of prefix unary operators is important when another
operator follows the operand.  For example, @code{-x^2} means
@code{-(x^2)}, because @samp{-} has lower precedence than @samp{^}.

Here is a table of the operators in @code{octave}, in order of
increasing precedence.

@table @code
@item statement separators
@samp{;}, @samp{,}.

@item assignment
@samp{=}.  This operator groups right to left.

@item logical ``or'' and ``and''
@samp{|}, @samp{||}, @samp{&}, @samp{&&}.

@item relational
@samp{<}, @samp{<=}, @samp{==}, @samp{>=}, @samp{>}, @samp{!=},
@samp{~=}, @samp{<>}.

@item colon
@samp{:}.

@item add, subtract
@samp{+}, @samp{-}.

@item multiply, divide
@samp{*}, @samp{/}, @samp{\}, @samp{.\}, @samp{.*}, @samp{./}.

@item transpose
@samp{'}, @samp{.'}

@item unary plus, minus, increment, decrement, and ``not''
@samp{+}, @samp{-}, @samp{++}, @samp{--}, @samp{!}, @samp{~}.

@item exponentiation
@samp{^}, @samp{**}, @samp{.^}, @samp{.**}.
@end table
