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.

Constant Expressions
====================

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

Numeric Constants
-----------------

A numeric constant may be a scalar, a vector, or a matrix, and it may contain complex values.

The simplest form of a numeric constant, a scalar, is a single number that can be an integer, a decimal fraction, a number in scientific (exponential) notation, or a complex number.  Note that all numeric values are represented within Octave in double-precision floating point format (complex constants are stored as pairs of double-precision floating point values).  Here are some examples of real-valued numeric constants, which all have the same value:

     105
     1.05e+2
     1050e-1

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

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

all of which are equivalent.  The letter i in the previous example stands for the pure imaginary constant, defined as sqrt (-1).

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

     octave:13> 3 + 4 i

     parse error:

       3 + 4 i
             ^

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

String Constants
----------------

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

     "parrot"
     'parrot'

represent the string whose contents are parrot.  Strings in Octave can be of any length.

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

Some characters cannot be included literally in a string constant.  You represent them instead with escape sequences, which are character sequences beginning with a backslash (\).

One use of an escape sequence is to include a double-quote (single-quote) character in a string constant that has been defined using double-quote (single-quote) marks.  Since a plain double-quote would end the string, you must use \" to represent a single double-quote character as a part of the string.  The backslash character itself is another character that cannot be included normally.  You must write \\ to put one backslash in the string.  Thus, the string whose contents are the two characters "\ must be written "\"\\".

Another use of backslash is to represent unprintable characters such as newline.  While there is nothing to stop you from writing most of these characters directly in a string constant, they may look ugly.

Here is a table of all the escape sequences used in awk:

\\
     Represents a literal backslash, \.

\"
     Represents a literal double-quote character, ".

\'
     Represents a literal single-quote character, '.

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

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

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

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

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

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

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

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

     [ "foo" , "bar" , "baz" ]

produces the string whose contents are foobarbaz

Matrices
========

Ranges
======

A range is a convenient way to write a row vector with evenly spaced elements.  A range constant is defined by the value of the first element in the range, 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 : character) and may contain any arithmetic expressions and function calls.  If the increment is omitted, it is assumed to be 1. For example,

     1 : 5

defines the set of values [ 1 2 3 4 5 ], and the range

     1 : 3 : 5

defines the set of values [ 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 linspace function instead see Built-in Functions.

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 a and A are distinct variables.

A variable name is a valid expression by itself.  It represents the variable's current value.  Variables are given new values with assignment operators and increment operators. See Assignment Expressions.

A number of variables have special built-in meanings, such as PWD, which holds the current working directory, and pi, the ratio of the circumference of a circle to its diameter. See 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.

Index Expressions
=================

Calling Functions
=================

A function is a name for a particular calculation.  Because it has a name, you can ask for it by name at any point in the program.  For example, the function sqrt computes the square root of a number.

A fixed set of functions are built-in, which means they are available in every Octave program.  The sqrt function is one of these.  See 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.  See Defining Functions, for how to do this.

The way to use a function is with a function call expression, which consists of the function name followed by a list of arguments in parentheses. The arguments are expressions which give the raw materials for the calculation that the function will do.  When there is more than one argument, they are separated by commas.  If there are no arguments, write just () after the function name (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:

     sqrt (x^2 + y^2)      # One argument
     ones (n, m)           # Two arguments
     rand ()               # No arguments

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

     sqrt (ARGUMENT)

Some of the built-in functions take a variable number of arguments, depending on the particular usage, and their behavior is different depending on the number of arguments supplied.

Like every other expression, the function call has a value, which is computed by the function based on the arguments you give it.  In this example, the value of sqrt (ARGUMENT) is the square root of the argument.  A function can also have side effects, such as assigning the values of certain variables or doing input or output operations.

Unlike most languages, functions in Octave may return multiple values.

Global Variables
================

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

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

Keywords
========

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

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

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

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

Arithmetic Operators
====================

The arithmetic operators in Octave are:

X + Y
     Addition.

X .+ Y
     Element by element addition.  This operator is equivalent to +.

X - Y
     Subtraction.

X .- Y
     Element by element subtraction.  This operator is equivalent to -.

X * Y
     Matrix multiplication.

X .* Y
     Element by element multiplication.

X / Y
     Right division.

X ./ Y
     Element by element right division.

X \ Y
     Left division.

X .\ Y
     Element by element left division.

X ^ Y
X ** Y
     Power operator.

X .^ Y

X .** Y
     Element by element power operator.

-X
     Negation.

+X
     Unary plus.  This operator has no effect on the operand.

X'
     Complex conjugate transpose.

X.'
     Transpose.

Comparison Operators
====================

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

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

     [1, 2; 3, 4] == [1, 3; 2, 4]

returns the result

     ans =

       1  0
       0  1

X < Y
     True if X is less than Y.

X <= Y
     True if X is less than or equal to Y.

X == Y
     True if X is equal to Y.

X >= Y
     True if X is greater than or equal to Y.

X > Y
     True if X is greater than Y.

X != Y
X ~= Y
X <> Y
     True if X is not equal to Y.

String comparisons should be performed with the strcmp function, not with the comparison operators listed above. See Calling Functions.

Boolean Expressions
===================

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

Boolean expressions can be used wherever comparison and matching expressions can be used.  They can be used in if and 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 (see Boolean Expressions), which use the same boolean operators in patterns instead of expressions.

BOOLEAN1 & BOOLEAN2
BOOLEAN1 && BOOLEAN2
     True if both BOOLEAN1 and BOOLEAN2 are true.

     The subexpression BOOLEAN2 is evaluated only if BOOLEAN1 is true.  This can make a difference when BOOLEAN2 is an expression that has side effects.  For example, in the expression

          a && b++

     the value of the variable B is only incremented if A is nonzero.

BOOLEAN1 | BOOLEAN2

BOOLEAN1 || BOOLEAN2
     True if at least one of BOOLEAN1 or BOOLEAN2 is true.

     The subexpression BOOLEAN2 is evaluated only if BOOLEAN1 is false.  This can make a difference when BOOLEAN2 is an expression that has side effects.

! BOOLEAN
~ BOOLEAN
     True if BOOLEAN is false.

Assignment Expressions
======================

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

     z = 1

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

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

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

(This also illustrates concatenation of strings.)

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

Most operators (addition, concatenation, and so on) have no effect except to compute a value.  If you ignore the value, you might as well not use the operator.  An assignment operator is different.  It does produce a value, but even if you ignore the value, the assignment still makes itself felt through the alteration of the variable.  We call this a side effect.

The left-hand operand of an assignment need not be a variable (see Variables).  It can also be an element of a matrix (see Index Expressions) or a list of return values (see Calling Functions).  These are all called lvalues, which means they can appear on the left-hand side of an assignment operator. The right-hand operand may be any expression.  It produces the new value which the assignment stores in the specified variable, matrix element, or list of return values.

It is important to note that variables do not have permanent types. The type of a variable is simply the type of whatever value it happens to hold at the moment.  In the following program fragment, the variable foo has a numeric value at first, and a string value later on:

     octave:13> foo = 1
     foo = 1
     octave:13> foo = "bar"
     foo = bar

When the second assignment gives foo a string value, the fact that it previously had a numeric value is forgotten.

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

     x = y = z = 0

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

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

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

that is exactly equivalent to

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

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

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

is equivalent to the expression above, except that the value of the variable d is left unchanged, and the expression

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

is equivalent to

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

You can use an assignment anywhere an expression is called for.  For example, it is valid to write x != (y = 1) to set y to 1 and then test whether x equals 1.  But this style tends to make programs hard to read.  Except in a one-shot program, you should rewrite it to get rid of such nesting of assignments.  This is never very hard.

Increment Operators
===================

Increment operators increase or decrease the value of a variable by 1.

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

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

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

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

++X
     This expression increments the variable X.  The value of the expression is the new value of X.  It is equivalent to the expression X = X + 1.

--X
     This expression decrements the variable X.  The value of the expression is the new value of X.  It is equivalent to the expression X = X - 1.

X++
     This expression causes the variable X to be incremented.  The value of the expression is the old value of X.

X--
     This expression causes the variable X to be decremented.  The value of the expression is the old value of X.

Operator Precedence
===================

Operator precedence determines how operators are grouped, when different operators appear close by in one expression.  For example, * has higher precedence than +.  Thus, the expression a + b * c means to multiply b and c, and then add a to the product (i.e., a + (b * c)).

You can overrule the precedence of the operators by using parentheses. You can think of the precedence rules as saying where the parentheses are assumed if you do not write parentheses yourself.  In fact, it is wise to 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 a - b + c groups as (a - b) + c, but the expression a = b = c groups as a = (b = c).

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

Here is a table of the operators in octave, in order of increasing precedence.

statement separators
     ;, ,.

assignment
     =.  This operator groups right to left.

logical ``or'' and ``and''
     |, ||, &, &&.

relational
     <, <=, ==, >=, >, !=, ~=, <>.

colon
     :.

add, subtract
     +, -.

multiply, divide
     *, /, \, .\, .*, ./.

transpose
     ', .'

unary plus, minus, increment, decrement, and ``not''
     +, -, ++, --, !, ~.

exponentiation
     ^, **, .^, .**.