jwe/octave: doc/interpreter/expr.txi annotate

annotate doc/interpreter/expr.txi @ 22620:74fb14727a30

doc: Remove DOCSTRING references to non-existent functions (bug #49329). * expr.txi: Remove DOCSTRING entries for allow_noninteger_range_as_index and do_braindead_shortcircuit_evaluation. * grammar.txi: Remove mention of allow_noninteger_range_as_index.

author	Rik <rik@octave.org>
date	Thu, 13 Oct 2016 08:20:10 -0700
parents	bac0d6f07a3e
children	3a2b891d0b33

rev	line source
22323 bac0d6f07a3e maint: Update copyright notices for 2016. John W. Eaton <jwe@octave.org> parents: 20745 diff changeset	1 @c Copyright (C) 1996-2016 John W. Eaton
7018 fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	2 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	3 @c This file is part of Octave.
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	4 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	5 @c Octave is free software; you can redistribute it and/or modify it
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	6 @c under the terms of the GNU General Public License as published by the
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	7 @c Free Software Foundation; either version 3 of the License, or (at
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	8 @c your option) any later version.
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	9 @c
7018 fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	10 @c Octave is distributed in the hope that it will be useful, but WITHOUT
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	11 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	12 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	13 @c for more details.
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	14 @c
7018 fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	15 @c You should have received a copy of the GNU General Public License
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	16 @c along with Octave; see the file COPYING. If not, see
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	17 @c <http://www.gnu.org/licenses/>.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	18
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	19 @node Expressions
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	20 @chapter Expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	21 @cindex expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	22
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	23 Expressions are the basic building block of statements in Octave. An
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	24 expression evaluates to a value, which you can print, test, store in a
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	25 variable, pass to a function, or assign a new value to a variable with
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	26 an assignment operator.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	27
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	28 An expression can serve as a statement on its own. Most other kinds of
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	29 statements contain one or more expressions which specify data to be
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	30 operated on. As in other languages, expressions in Octave include
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	31 variables, array references, constants, and function calls, as well as
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	32 combinations of these with various operators.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	33
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	34 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	35 * Index Expressions::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	36 * Calling Functions::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	37 * Arithmetic Ops::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	38 * Comparison Ops::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	39 * Boolean Expressions::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	40 * Assignment Ops::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	41 * Increment Ops::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	42 * Operator Precedence::
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	43 @end menu
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	44
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	45 @node Index Expressions
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	46 @section Index Expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	47
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	48 @opindex (
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	49 @opindex )
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	50 @opindex :
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	51
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	52 An @dfn{index expression} allows you to reference or extract selected
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	53 elements of a matrix or vector.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	54
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	55 Indices may be scalars, vectors, ranges, or the special operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	56 @samp{:}, which may be used to select entire rows or columns.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	57
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	58 Vectors are indexed using a single index expression. Matrices (2-D)
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	59 and higher multi-dimensional arrays are indexed using either one index
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	60 or @math{N} indices where @math{N} is the dimension of the array.
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	61 When using a single index expression to index 2-D or higher data the
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	62 elements of the array are taken in column-first order (like Fortran).
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	63
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	64 The output from indexing assumes the dimensions of the index
14038 b0cdd60db5e5 doc: Grammarcheck documentation ahead of 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14033 diff changeset	65 expression. For example:
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	66
5679 297b82335c7b [project @ 2006-03-16 16:44:12 by jwe] jwe parents: 5016 diff changeset	67 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9159 diff changeset	68 @group
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	69 a(2) # result is a scalar
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	70 a(1:2) # result is a row vector
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	71 a([1; 2]) # result is a column vector
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9159 diff changeset	72 @end group
5679 297b82335c7b [project @ 2006-03-16 16:44:12 by jwe] jwe parents: 5016 diff changeset	73 @end example
297b82335c7b [project @ 2006-03-16 16:44:12 by jwe] jwe parents: 5016 diff changeset	74
297b82335c7b [project @ 2006-03-16 16:44:12 by jwe] jwe parents: 5016 diff changeset	75 As a special case, when a colon is used as a single index, the output
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	76 is a column vector containing all the elements of the vector or
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	77 matrix. For example:
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	78
5679 297b82335c7b [project @ 2006-03-16 16:44:12 by jwe] jwe parents: 5016 diff changeset	79 @example
14038 b0cdd60db5e5 doc: Grammarcheck documentation ahead of 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14033 diff changeset	80 @group
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	81 a(:) # result is a column vector
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	82 a(:)' # result is a row vector
14038 b0cdd60db5e5 doc: Grammarcheck documentation ahead of 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14033 diff changeset	83 @end group
5679 297b82335c7b [project @ 2006-03-16 16:44:12 by jwe] jwe parents: 5016 diff changeset	84 @end example
297b82335c7b [project @ 2006-03-16 16:44:12 by jwe] jwe parents: 5016 diff changeset	85
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	86 The above two code idioms are often used in place of @code{reshape}
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	87 when a simple vector, rather than an arbitrarily sized array, is
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	88 needed.
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	89
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	90 Given the matrix
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	91
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	92 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	93 a = [1, 2; 3, 4]
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	94 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	95
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	96 @noindent
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	97 all of the following expressions are equivalent and select the first
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	98 row of the matrix.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	99
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	100 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	101 @group
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	102 a(1, [1, 2]) # row 1, columns 1 and 2
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	103 a(1, 1:2) # row 1, columns in range 1-2
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	104 a(1, :) # row 1, all columns
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	105 @end group
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	106 @end example
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	107
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	108 @cindex @code{end}, indexing
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	109 @cindex :end
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	110
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	111 In index expressions the keyword @code{end} automatically refers to
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	112 the last entry for a particular dimension. This magic index can also
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	113 be used in ranges and typically eliminates the needs to call
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	114 @code{size} or @code{length} to gather array bounds before indexing.
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	115 For example:
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	116
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	117 @example
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	118 @group
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	119 a = [1, 2, 3, 4];
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	120
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	121 a(1:end/2) # first half of a => [1, 2]
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	122 a(end + 1) = 5; # append element
446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	123 a(end) = []; # delete element
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	124 a(1:2:end) # odd elements of a => [1, 3]
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	125 a(2:2:end) # even elements of a => [2, 4]
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	126 a(end:-1:1) # reversal of a => [4, 3, 2 , 1]
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	127 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	128 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	129
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	130 @menu
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	131 * Advanced Indexing::
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	132 @end menu
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	133
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	134 @node Advanced Indexing
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	135 @subsection Advanced Indexing
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	136
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	137 An array with @samp{n} dimensions can be indexed using @samp{m}
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	138 indices. More generally, the set of index tuples determining the
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	139 result is formed by the Cartesian product of the index vectors (or
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	140 ranges or scalars).
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	141
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	142 For the ordinary and most common case, @w{@code{m == n}}, and each
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	143 index corresponds to its respective dimension. If @w{@code{m < n}}
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	144 and every index is less than the size of the array in the
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	145 @math{i^{th}} dimension, @code{m(i) < n(i)}, then the index expression
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	146 is padded with trailing singleton dimensions (@code{[ones (m-n, 1)]}).
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	147 If @w{@code{m < n}} but one of the indices @code{m(i)} is outside the
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	148 size of the current array, then the last @w{@code{n-m+1}} dimensions
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	149 are folded into a single dimension with an extent equal to the product
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	150 of extents of the original dimensions. This is easiest to understand
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	151 with an example.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	152
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	153 @example
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	154 a = reshape (1:8, 2, 2, 2) # Create 3-D array
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	155 a =
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	156
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	157 ans(:,:,1) =
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	158
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	159 1 3
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	160 2 4
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	161
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	162 ans(:,:,2) =
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	163
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	164 5 7
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	165 6 8
9159 c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	166
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	167 a(2,1,2); # Case (m == n): ans = 6
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	168 a(2,1); # Case (m < n), idx within array:
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	169 # equivalent to a(2,1,1), ans = 2
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	170 a(2,4); # Case (m < n), idx outside array:
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	171 # Dimension 2 & 3 folded into new dimension of size 2x2 = 4
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	172 # Select 2nd row, 4th element of [2, 4, 6, 8], ans = 8
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	173 @end example
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	174
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	175 One advanced use of indexing is to create arrays filled with a single
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	176 value. This can be done by using an index of ones on a scalar value.
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	177 The result is an object with the dimensions of the index expression
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	178 and every element equal to the original scalar. For example, the
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	179 following statements
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	180
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	181 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	182 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	183 a = 13;
12546 39ca02387a32 Improve docstrings for a number of functions. Rik <octave@nomad.inbox5.com> parents: 12544 diff changeset	184 a(ones (1, 4))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	185 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	186 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	187
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	188 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	189 produce a vector whose four elements are all equal to 13.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	190
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	191 Similarly, by indexing a scalar with two vectors of ones it is
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	192 possible to create a matrix. The following statements
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	193
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	194 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	195 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	196 a = 13;
12546 39ca02387a32 Improve docstrings for a number of functions. Rik <octave@nomad.inbox5.com> parents: 12544 diff changeset	197 a(ones (1, 2), ones (1, 3))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	198 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	199 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	200
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	201 @noindent
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	202 create a 2x3 matrix with all elements equal to 13.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	203
9159 c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	204 The last example could also be written as
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	205
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	206 @example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	207 @group
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	208 13(ones (2, 3))
9159 c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	209 @end group
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	210 @end example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	211
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	212 It is more efficient to use indexing rather than the code construction
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	213 @code{scalar * ones (N, M, @dots{})} because it avoids the unnecessary
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	214 multiplication operation. Moreover, multiplication may not be
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	215 defined for the object to be replicated whereas indexing an array is
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	216 always defined. The following code shows how to create a 2x3 cell
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	217 array from a base unit which is not itself a scalar.
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	218
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	219 @example
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	220 @group
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	221 @{"Hello"@}(ones (2, 3))
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	222 @end group
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	223 @end example
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	224
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	225 It should be, noted that @code{ones (1, n)} (a row vector of ones)
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	226 results in a range (with zero increment). A range is stored
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	227 internally as a starting value, increment, end value, and total number
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	228 of values; hence, it is more efficient for storage than a vector or
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	229 matrix of ones whenever the number of elements is greater than 4. In
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	230 particular, when @samp{r} is a row vector, the expressions
9159 c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	231
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	232 @example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	233 r(ones (1, n), :)
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	234 @end example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	235
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	236 @example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	237 r(ones (n, 1), :)
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	238 @end example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	239
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	240 @noindent
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	241 will produce identical results, but the first one will be
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	242 significantly faster, at least for @samp{r} and @samp{n} large enough.
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	243 In the first case the index is held in compressed form as a range
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	244 which allows Octave to choose a more efficient algorithm to handle the
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	245 expression.
9159 c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	246
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	247 A general recommendation, for a user unaware of these subtleties, is
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	248 to use the function @code{repmat} for replicating smaller arrays into
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	249 bigger ones.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	250
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	251 A second use of indexing is to speed up code. Indexing is a fast
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	252 operation and judicious use of it can reduce the requirement for
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	253 looping over individual array elements which is a slow operation.
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	254
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	255 Consider the following example which creates a 10-element row vector
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	256 @math{a} containing the values
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	257 @tex
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	258 $a_i = \sqrt{i}$.
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	259 @end tex
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	260 @ifnottex
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14171 diff changeset	261 a(i) = sqrt (i).
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	262 @end ifnottex
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	263
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	264 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9159 diff changeset	265 @group
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	266 for i = 1:10
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	267 a(i) = sqrt (i);
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	268 endfor
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9159 diff changeset	269 @end group
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	270 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	271
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	272 @noindent
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	273 It is quite inefficient to create a vector using a loop like this. In
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	274 this case, it would have been much more efficient to use the
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	275 expression
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	276
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	277 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	278 a = sqrt (1:10);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	279 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	280
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	281 @noindent
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	282 which avoids the loop entirely.
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	283
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	284 In cases where a loop cannot be avoided, or a number of values must be
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	285 combined to form a larger matrix, it is generally faster to set the
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	286 size of the matrix first (pre-allocate storage), and then insert
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	287 elements using indexing commands. For example, given a matrix
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	288 @code{a},
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	289
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	290 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	291 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	292 [nr, nc] = size (a);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	293 x = zeros (nr, n * nc);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	294 for i = 1:n
3602 83889344cbef [project @ 2000-02-25 08:52:20 by jwe] jwe parents: 3428 diff changeset	295 x(:,(i-1)nc+1:inc) = a;
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	296 endfor
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	297 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	298 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	299
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	300 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	301 is considerably faster than
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	302
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	303 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	304 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	305 x = a;
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	306 for i = 1:n-1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	307 x = [x, a];
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	308 endfor
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	309 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	310 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	311
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	312 @noindent
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	313 because Octave does not have to repeatedly resize the intermediate
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	314 result.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	315
6549 5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 6501 diff changeset	316 @DOCSTRING(sub2ind)
5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 6501 diff changeset	317
5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 6501 diff changeset	318 @DOCSTRING(ind2sub)
5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 6501 diff changeset	319
11431 0d9640d755b1 Improve docstrings for all isXXX functions. Rik <octave@nomad.inbox5.com> parents: 11403 diff changeset	320 @DOCSTRING(isindex)
0d9640d755b1 Improve docstrings for all isXXX functions. Rik <octave@nomad.inbox5.com> parents: 11403 diff changeset	321
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	322 @node Calling Functions
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	323 @section Calling Functions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	324
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	325 A @dfn{function} is a name for a particular calculation. Because it has
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	326 a name, you can ask for it by name at any point in the program. For
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	327 example, the function @code{sqrt} computes the square root of a number.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	328
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	329 A fixed set of functions are @dfn{built-in}, which means they are
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	330 available in every Octave program. The @code{sqrt} function is one of
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	331 these. In addition, you can define your own functions.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	332 @xref{Functions and Scripts}, for information about how to do this.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	333
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	334 @cindex arguments in function call
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	335 The way to use a function is with a @dfn{function call} expression,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	336 which consists of the function name followed by a list of
9037 4cb9f994dcec Documentation cleanup of var.texi, expr.texi, eval.texi Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	337 @dfn{arguments} in parentheses. The arguments are expressions which give
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	338 the raw materials for the calculation that the function will do. When
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	339 there is more than one argument, they are separated by commas. If there
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	340 are no arguments, you can omit the parentheses, but it is a good idea to
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	341 include them anyway, to clearly indicate that a function call was
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	342 intended. Here are some examples:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	343
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	344 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	345 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	346 sqrt (x^2 + y^2) # @r{One argument}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	347 ones (n, m) # @r{Two arguments}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	348 rand () # @r{No arguments}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	349 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	350 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	351
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	352 Each function expects a particular number of arguments. For example, the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	353 @code{sqrt} function must be called with a single argument, the number
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	354 to take the square root of:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	355
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	356 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	357 sqrt (@var{argument})
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	358 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	359
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	360 Some of the built-in functions take a variable number of arguments,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	361 depending on the particular usage, and their behavior is different
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	362 depending on the number of arguments supplied.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	363
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	364 Like every other expression, the function call has a value, which is
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	365 computed by the function based on the arguments you give it. In this
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	366 example, the value of @code{sqrt (@var{argument})} is the square root of
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	367 the argument. A function can also have side effects, such as assigning
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	368 the values of certain variables or doing input or output operations.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	369
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	370 Unlike most languages, functions in Octave may return multiple values.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	371 For example, the following statement
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	372
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	373 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	374 [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	375 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	376
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	377 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	378 computes the singular value decomposition of the matrix @code{a} and
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	379 assigns the three result matrices to @code{u}, @code{s}, and @code{v}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	380
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	381 The left side of a multiple assignment expression is itself a list of
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	382 expressions, and is allowed to be a list of variable names or index
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	383 expressions. See also @ref{Index Expressions}, and @ref{Assignment Ops}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	384
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	385 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	386 * Call by Value::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	387 * Recursion::
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	388 @end menu
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	389
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	390 @node Call by Value
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	391 @subsection Call by Value
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	392
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	393 In Octave, unlike Fortran, function arguments are passed by value, which
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	394 means that each argument in a function call is evaluated and assigned to
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	395 a temporary location in memory before being passed to the function.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	396 There is currently no way to specify that a function parameter should be
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	397 passed by reference instead of by value. This means that it is
8347 fa78cb8d8a5c corrections for typos Brian Gough<bjg@network-theory.co.uk> parents: 8235 diff changeset	398 impossible to directly alter the value of a function parameter in the
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	399 calling function. It can only change the local copy within the function
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	400 body. For example, the function
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	401
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	402 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	403 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	404 function f (x, n)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	405 while (n-- > 0)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	406 disp (x);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	407 endwhile
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	408 endfunction
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	409 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	410 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	411
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	412 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	413 displays the value of the first argument @var{n} times. In this
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	414 function, the variable @var{n} is used as a temporary variable without
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	415 having to worry that its value might also change in the calling
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	416 function. Call by value is also useful because it is always possible to
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	417 pass constants for any function parameter without first having to
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	418 determine that the function will not attempt to modify the parameter.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	419
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	420 The caller may use a variable as the expression for the argument, but
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	421 the called function does not know this: it only knows what value the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	422 argument had. For example, given a function called as
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	423
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	424 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	425 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	426 foo = "bar";
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	427 fcn (foo)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	428 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	429 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	430
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	431 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	432 you should not think of the argument as being ``the variable
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	433 @code{foo}.'' Instead, think of the argument as the string value,
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17170 diff changeset	434 @qcode{"bar"}.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	435
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	436 Even though Octave uses pass-by-value semantics for function arguments,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	437 values are not copied unnecessarily. For example,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	438
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	439 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	440 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	441 x = rand (1000);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	442 f (x);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	443 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	444 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	445
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	446 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	447 does not actually force two 1000 by 1000 element matrices to exist
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	448 @emph{unless} the function @code{f} modifies the value of its
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	449 argument. Then Octave must create a copy to avoid changing the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	450 value outside the scope of the function @code{f}, or attempting (and
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	451 probably failing!) to modify the value of a constant or the value of a
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	452 temporary result.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	453
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	454 @node Recursion
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	455 @subsection Recursion
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	456 @cindex factorial function
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	457
6939 46d1ad37d943 [project @ 2007-10-01 16:12:20 by jwe] jwe parents: 6778 diff changeset	458 With some restrictions@footnote{Some of Octave's functions are
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	459 implemented in terms of functions that cannot be called recursively.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	460 For example, the ODE solver @code{lsode} is ultimately implemented in a
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	461 Fortran subroutine that cannot be called recursively, so @code{lsode}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	462 should not be called either directly or indirectly from within the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	463 user-supplied function that @code{lsode} requires. Doing so will result
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	464 in an error.}, recursive function calls are allowed. A
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	465 @dfn{recursive function} is one which calls itself, either directly or
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	466 indirectly. For example, here is an inefficient@footnote{It would be
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	467 much better to use @code{prod (1:n)}, or @code{gamma (n+1)} instead,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	468 after first checking to ensure that the value @code{n} is actually a
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	469 positive integer.} way to compute the factorial of a given integer:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	470
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	471 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	472 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	473 function retval = fact (n)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	474 if (n > 0)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	475 retval = n * fact (n-1);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	476 else
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	477 retval = 1;
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	478 endif
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	479 endfunction
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	480 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	481 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	482
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	483 This function is recursive because it calls itself directly. It
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	484 eventually terminates because each time it calls itself, it uses an
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	485 argument that is one less than was used for the previous call. Once the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	486 argument is no longer greater than zero, it does not call itself, and
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	487 the recursion ends.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	488
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	489 The built-in variable @code{max_recursion_depth} specifies a limit to
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	490 the recursion depth and prevents Octave from recursing infinitely.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	491
3371 86873384cd10 [project @ 1999-11-21 17:31:07 by jwe] jwe parents: 3294 diff changeset	492 @DOCSTRING(max_recursion_depth)
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	493
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	494 @node Arithmetic Ops
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	495 @section Arithmetic Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	496 @cindex arithmetic operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	497 @cindex operators, arithmetic
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	498 @cindex addition
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	499 @cindex subtraction
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	500 @cindex multiplication
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	501 @cindex matrix multiplication
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	502 @cindex division
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	503 @cindex quotient
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	504 @cindex negation
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	505 @cindex unary minus
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	506 @cindex exponentiation
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	507 @cindex transpose
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	508 @cindex Hermitian operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	509 @cindex transpose, complex-conjugate
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	510 @cindex complex-conjugate transpose
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	511
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	512 The following arithmetic operators are available, and work on scalars
14119 94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14116 diff changeset	513 and matrices. The element-by-element operators and functions broadcast
14116 951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14038 diff changeset	514 (@pxref{Broadcasting}).
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	515
13780 990762e784fe Fix confusing interaction between @code macro and transpose operator (') in documentation (Bug #34661). Rik <octave@nomad.inbox5.com> parents: 12627 diff changeset	516 @table @asis
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	517 @item @var{x} + @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	518 @opindex +
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	519 Addition. If both operands are matrices, the number of rows and columns
14149 f1ff06a1d73a doc: Mention broadcasting in more relevant places. Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	520 must both agree, or they must be broadcastable to the same shape.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	521
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	522 @item @var{x} .+ @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	523 @opindex .+
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	524 Element-by-element addition. This operator is equivalent to @code{+}.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	525
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	526 @item @var{x} - @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	527 @opindex -
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	528 Subtraction. If both operands are matrices, the number of rows and
14149 f1ff06a1d73a doc: Mention broadcasting in more relevant places. Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	529 columns of both must agree, or they must be broadcastable to the same
f1ff06a1d73a doc: Mention broadcasting in more relevant places. Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	530 shape.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	531
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	532 @item @var{x} .- @var{y}
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	533 Element-by-element subtraction. This operator is equivalent to @code{-}.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	534
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	535 @item @var{x} * @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	536 @opindex *
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	537 Matrix multiplication. The number of columns of @var{x} must agree with
14149 f1ff06a1d73a doc: Mention broadcasting in more relevant places. Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	538 the number of rows of @var{y}, or they must be broadcastable to the same
f1ff06a1d73a doc: Mention broadcasting in more relevant places. Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	539 shape.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	540
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	541 @item @var{x} .* @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	542 @opindex .*
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	543 Element-by-element multiplication. If both operands are matrices, the
14149 f1ff06a1d73a doc: Mention broadcasting in more relevant places. Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	544 number of rows and columns must both agree, or they must be
f1ff06a1d73a doc: Mention broadcasting in more relevant places. Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	545 broadcastable to the same shape.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	546
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	547 @item @var{x} / @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	548 @opindex /
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	549 Right division. This is conceptually equivalent to the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	550
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	551 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	552 (inverse (y') * x')'
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	553 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	554
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	555 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	556 but it is computed without forming the inverse of @var{y'}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	557
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	558 If the system is not square, or if the coefficient matrix is singular,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	559 a minimum norm solution is computed.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	560
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	561 @item @var{x} ./ @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	562 @opindex ./
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	563 Element-by-element right division.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	564
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	565 @item @var{x} \ @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	566 @opindex \
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	567 Left division. This is conceptually equivalent to the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	568
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	569 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	570 inverse (x) * y
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	571 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	572
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	573 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	574 but it is computed without forming the inverse of @var{x}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	575
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	576 If the system is not square, or if the coefficient matrix is singular,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	577 a minimum norm solution is computed.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	578
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	579 @item @var{x} .\ @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	580 @opindex .\
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	581 Element-by-element left division. Each element of @var{y} is divided
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	582 by each corresponding element of @var{x}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	583
17170 d6499c14021c doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 17152 diff changeset	584 @item @var{x} ^ @var{y}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	585 @itemx @var{x} ** @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	586 @opindex **
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	587 @opindex ^
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	588 Power operator. If @var{x} and @var{y} are both scalars, this operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	589 returns @var{x} raised to the power @var{y}. If @var{x} is a scalar and
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	590 @var{y} is a square matrix, the result is computed using an eigenvalue
7001 8b0cfeb06365 [project @ 2007-10-10 18:02:59 by jwe] jwe parents: 6939 diff changeset	591 expansion. If @var{x} is a square matrix, the result is computed by
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	592 repeated multiplication if @var{y} is an integer, and by an eigenvalue
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	593 expansion if @var{y} is not an integer. An error results if both
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	594 @var{x} and @var{y} are matrices.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	595
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	596 The implementation of this operator needs to be improved.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	597
17170 d6499c14021c doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 17152 diff changeset	598 @item @var{x} .^ @var{y}
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	599 @itemx @var{x} .** @var{y}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	600 @opindex .**
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	601 @opindex .^
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	602 Element-by-element power operator. If both operands are matrices, the
14149 f1ff06a1d73a doc: Mention broadcasting in more relevant places. Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	603 number of rows and columns must both agree, or they must be
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	604 broadcastable to the same shape. If several complex results are
2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	605 possible, the one with smallest non-negative argument (angle) is taken.
2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	606 This rule may return a complex root even when a real root is also possible.
2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	607 Use @code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a
14169 c0ca47ab7641 doc: Better explain which complex result is chosen by .^ Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14149 diff changeset	608 real result is preferred.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	609
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	610 @item -@var{x}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	611 @opindex -
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	612 Negation.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	613
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	614 @item +@var{x}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	615 @opindex +
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	616 Unary plus. This operator has no effect on the operand.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	617
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	618 @item @var{x}'
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	619 @opindex '
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	620 Complex conjugate transpose. For real arguments, this operator is the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	621 same as the transpose operator. For complex arguments, this operator is
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	622 equivalent to the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	623
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	624 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	625 conj (x.')
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	626 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	627
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	628 @item @var{x}.'
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	629 @opindex .'
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	630 Transpose.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	631 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	632
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	633 Note that because Octave's element-by-element operators begin with a
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	634 @samp{.}, there is a possible ambiguity for statements like
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	635
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	636 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	637 1./m
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	638 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	639
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	640 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	641 because the period could be interpreted either as part of the constant
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	642 or as part of the operator. To resolve this conflict, Octave treats the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	643 expression as if you had typed
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	644
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	645 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	646 (1) ./ m
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	647 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	648
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	649 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	650 and not
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	651
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	652 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	653 (1.) / m
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	654 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	655
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	656 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	657 Although this is inconsistent with the normal behavior of Octave's
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	658 lexer, which usually prefers to break the input into tokens by
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	659 preferring the longest possible match at any given point, it is more
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	660 useful in this case.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	661
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	662 @opindex '
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	663 @DOCSTRING(ctranspose)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	664
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	665 @opindex .\
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	666 @DOCSTRING(ldivide)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	667
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	668 @opindex -
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	669 @DOCSTRING(minus)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	670
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	671 @opindex \
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	672 @DOCSTRING(mldivide)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	673
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	674 @opindex **
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	675 @opindex ^
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	676 @DOCSTRING(mpower)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	677
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	678 @opindex /
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	679 @DOCSTRING(mrdivide)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	680
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	681 @opindex *
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	682 @DOCSTRING(mtimes)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	683
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	684 @opindex +
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	685 @DOCSTRING(plus)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	686
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	687 @opindex .**
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	688 @opindex .^
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	689 @DOCSTRING(power)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	690
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	691 @opindex ./
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	692 @DOCSTRING(rdivide)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	693
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	694 @opindex .*
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	695 @DOCSTRING(times)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	696
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	697 @opindex .'
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	698 @DOCSTRING(transpose)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	699
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	700 @opindex -
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	701 @DOCSTRING(uminus)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	702
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	703 @opindex +
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	704 @DOCSTRING(uplus)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	705
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	706 @node Comparison Ops
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	707 @section Comparison Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	708 @cindex comparison expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	709 @cindex expressions, comparison
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	710 @cindex relational operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	711 @cindex operators, relational
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	712 @cindex less than operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	713 @cindex greater than operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	714 @cindex equality operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	715 @cindex tests for equality
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	716 @cindex equality, tests for
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	717
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	718 @dfn{Comparison operators} compare numeric values for relationships
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	719 such as equality. They are written using
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	720 @emph{relational operators}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	721
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	722 All of Octave's comparison operators return a value of 1 if the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	723 comparison is true, or 0 if it is false. For matrix values, they all
14116 951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14038 diff changeset	724 work on an element-by-element basis. Broadcasting rules apply.
14119 94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14116 diff changeset	725 @xref{Broadcasting}. For example:
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	726
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	727 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	728 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	729 [1, 2; 3, 4] == [1, 3; 2, 4]
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	730 @result{} 1 0
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	731 0 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	732 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	733 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	734
14116 951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14038 diff changeset	735 According to broadcasting rules, if one operand is a scalar and the
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14038 diff changeset	736 other is a matrix, the scalar is compared to each element of the matrix
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14038 diff changeset	737 in turn, and the result is the same size as the matrix.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	738
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	739 @table @code
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	740 @item @var{x} < @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	741 @opindex <
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	742 True if @var{x} is less than @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	743
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	744 @item @var{x} <= @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	745 @opindex <=
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	746 True if @var{x} is less than or equal to @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	747
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	748 @item @var{x} == @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	749 @opindex ==
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	750 True if @var{x} is equal to @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	751
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	752 @item @var{x} >= @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	753 @opindex >=
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	754 True if @var{x} is greater than or equal to @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	755
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	756 @item @var{x} > @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	757 @opindex >
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	758 True if @var{x} is greater than @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	759
17170 d6499c14021c doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 17152 diff changeset	760 @item @var{x} != @var{y}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	761 @itemx @var{x} ~= @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	762 @opindex !=
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	763 @opindex ~=
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	764 True if @var{x} is not equal to @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	765 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	766
9578 7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	767 For complex numbers, the following ordering is defined:
7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	768 @var{z1} < @var{z2}
16826 a4969508008e doc: Periodic spellcheck of the documentation. Rik <rik@octave.org> parents: 14856 diff changeset	769 if and only if
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	770
9578 7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	771 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9578 diff changeset	772 @group
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	773 abs (@var{z1}) < abs (@var{z2})
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14171 diff changeset	774 \|\| (abs (@var{z1}) == abs (@var{z2}) && arg (@var{z1}) < arg (@var{z2}))
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9578 diff changeset	775 @end group
9578 7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	776 @end example
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	777
322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	778 This is consistent with the ordering used by @dfn{max}, @dfn{min} and
322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	779 @dfn{sort}, but is not consistent with @sc{matlab}, which only compares the real
322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	780 parts.
9578 7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	781
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	782 String comparisons may also be performed with the @code{strcmp}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	783 function, not with the comparison operators listed above.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	784 @xref{Strings}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	785
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	786 @opindex ==
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	787 @DOCSTRING(eq)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	788
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	789 @opindex >=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	790 @DOCSTRING(ge)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	791
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	792 @opindex >
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	793 @DOCSTRING(gt)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	794
6550 1b7a6061a05d [project @ 2007-04-20 07:40:26 by jwe] jwe parents: 6549 diff changeset	795 @DOCSTRING(isequal)
1b7a6061a05d [project @ 2007-04-20 07:40:26 by jwe] jwe parents: 6549 diff changeset	796
16935 a7b2fc7fe1a9 binocdf.m: Reverse calling convention to betaincinv to preserve accuracy when p =~ 1. Rik <rik@octave.org> parents: 16826 diff changeset	797 @DOCSTRING(isequaln)
6550 1b7a6061a05d [project @ 2007-04-20 07:40:26 by jwe] jwe parents: 6549 diff changeset	798
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	799 @opindex <=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	800 @DOCSTRING(le)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	801
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	802 @opindex <
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	803 @DOCSTRING(lt)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	804
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	805 @opindex !=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	806 @opindex ~=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	807 @DOCSTRING(ne)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	808
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	809 @node Boolean Expressions
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	810 @section Boolean Expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	811 @cindex expressions, boolean
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	812 @cindex boolean expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	813 @cindex expressions, logical
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	814 @cindex logical expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	815 @cindex operators, boolean
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	816 @cindex boolean operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	817 @cindex logical operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	818 @cindex operators, logical
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	819 @cindex and operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	820 @cindex or operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	821 @cindex not operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	822
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	823 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	824 * Element-by-element Boolean Operators::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	825 * Short-circuit Boolean Operators::
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	826 @end menu
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	827
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	828 @node Element-by-element Boolean Operators
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	829 @subsection Element-by-element Boolean Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	830 @cindex element-by-element evaluation
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	831
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	832 An @dfn{element-by-element boolean expression} is a combination of
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	833 comparison expressions using the boolean
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	834 operators ``or'' (@samp{\|}), ``and'' (@samp{&}), and ``not'' (@samp{!}),
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	835 along with parentheses to control nesting. The truth of the boolean
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	836 expression is computed by combining the truth values of the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	837 corresponding elements of the component expressions. A value is
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	838 considered to be false if it is zero, and true otherwise.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	839
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	840 Element-by-element boolean expressions can be used wherever comparison
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	841 expressions can be used. They can be used in @code{if} and @code{while}
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9159 diff changeset	842 statements. However, a matrix value used as the condition in an
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	843 @code{if} or @code{while} statement is only true if @emph{all} of its
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	844 elements are nonzero.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	845
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	846 Like comparison operations, each element of an element-by-element
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	847 boolean expression also has a numeric value (1 if true, 0 if false) that
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	848 comes into play if the result of the boolean expression is stored in a
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	849 variable, or used in arithmetic.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	850
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	851 Here are descriptions of the three element-by-element boolean operators.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	852
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	853 @table @code
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	854 @item @var{boolean1} & @var{boolean2}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	855 @opindex &
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	856 Elements of the result are true if both corresponding elements of
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	857 @var{boolean1} and @var{boolean2} are true.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	858
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	859 @item @var{boolean1} \| @var{boolean2}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	860 @opindex \|
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	861 Elements of the result are true if either of the corresponding elements
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	862 of @var{boolean1} or @var{boolean2} is true.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	863
17170 d6499c14021c doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 17152 diff changeset	864 @item ! @var{boolean}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	865 @itemx ~ @var{boolean}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	866 @opindex ~
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	867 @opindex !
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	868 Each element of the result is true if the corresponding element of
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	869 @var{boolean} is false.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	870 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	871
14119 94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14116 diff changeset	872 These operators work on an element-by-element basis. For example, the
14116 951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14038 diff changeset	873 expression
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	874
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	875 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	876 [1, 0; 0, 1] & [1, 0; 2, 3]
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	877 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	878
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	879 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	880 returns a two by two identity matrix.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	881
14119 94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14116 diff changeset	882 For the binary operators, broadcasting rules apply. @xref{Broadcasting}.
14116 951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14038 diff changeset	883 In particular, if one of the operands is a scalar and the other a
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	884 matrix, the operator is applied to the scalar and each element of the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	885 matrix.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	886
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	887 For the binary element-by-element boolean operators, both subexpressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	888 @var{boolean1} and @var{boolean2} are evaluated before computing the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	889 result. This can make a difference when the expressions have side
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	890 effects. For example, in the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	891
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	892 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	893 a & b++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	894 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	895
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	896 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	897 the value of the variable @var{b} is incremented even if the variable
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	898 @var{a} is zero.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	899
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	900 This behavior is necessary for the boolean operators to work as
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	901 described for matrix-valued operands.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	902
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	903 @opindex &
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	904 @DOCSTRING(and)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	905
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	906 @opindex ~
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	907 @opindex !
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	908 @DOCSTRING(not)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	909
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	910 @opindex \|
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	911 @DOCSTRING(or)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	912
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	913 @node Short-circuit Boolean Operators
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	914 @subsection Short-circuit Boolean Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	915 @cindex short-circuit evaluation
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	916
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	917 Combined with the implicit conversion to scalar values in @code{if} and
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	918 @code{while} conditions, Octave's element-by-element boolean operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	919 are often sufficient for performing most logical operations. However,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	920 it is sometimes desirable to stop evaluating a boolean expression as
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	921 soon as the overall truth value can be determined. Octave's
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	922 @dfn{short-circuit} boolean operators work this way.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	923
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	924 @table @code
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	925 @item @var{boolean1} && @var{boolean2}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	926 @opindex &&
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	927 The expression @var{boolean1} is evaluated and converted to a scalar
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	928 using the equivalent of the operation @code{all (@var{boolean1}(:))}.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	929 If it is false, the result of the overall expression is 0. If it is
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	930 true, the expression @var{boolean2} is evaluated and converted to a
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	931 scalar using the equivalent of the operation @code{all
20659 4a82f565a669 doc: Fix typo in short-circuit operators documentation (bug #46280). Rik <rik@octave.org> parents: 19697 diff changeset	932 (@var{boolean2}(:))}. If it is true, the result of the overall expression
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	933 is 1. Otherwise, the result of the overall expression is 0.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	934
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	935 @strong{Warning:} there is one exception to the rule of evaluating
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	936 @code{all (@var{boolean1}(:))}, which is when @code{boolean1} is the
9037 4cb9f994dcec Documentation cleanup of var.texi, expr.texi, eval.texi Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	937 empty matrix. The truth value of an empty matrix is always @code{false}
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	938 so @code{[] && true} evaluates to @code{false} even though
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	939 @code{all ([])} is @code{true}.
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	940
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	941 @item @var{boolean1} \|\| @var{boolean2}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	942 @opindex \|\|
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	943 The expression @var{boolean1} is evaluated and converted to a scalar
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	944 using the equivalent of the operation @code{all (@var{boolean1}(:))}.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	945 If it is true, the result of the overall expression is 1. If it is
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	946 false, the expression @var{boolean2} is evaluated and converted to a
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	947 scalar using the equivalent of the operation @code{all
20659 4a82f565a669 doc: Fix typo in short-circuit operators documentation (bug #46280). Rik <rik@octave.org> parents: 19697 diff changeset	948 (@var{boolean2}(:))}. If it is true, the result of the overall expression
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	949 is 1. Otherwise, the result of the overall expression is 0.
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	950
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	951 @strong{Warning:} the truth value of an empty matrix is always @code{false},
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	952 see the previous list item for details.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	953 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	954
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	955 The fact that both operands may not be evaluated before determining the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	956 overall truth value of the expression can be important. For example, in
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	957 the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	958
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	959 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	960 a && b++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	961 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	962
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	963 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	964 the value of the variable @var{b} is only incremented if the variable
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	965 @var{a} is nonzero.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	966
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	967 This can be used to write somewhat more concise code. For example, it
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	968 is possible write
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	969
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	970 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	971 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	972 function f (a, b, c)
7768 a2d9f325b65a Use isschar instead of deprecated isstr Rafael Laboissiere <rafael@debian.org> parents: 7594 diff changeset	973 if (nargin > 2 && ischar (c))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	974 @dots{}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	975 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	976 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	977
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	978 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	979 instead of having to use two @code{if} statements to avoid attempting to
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	980 evaluate an argument that doesn't exist. For example, without the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	981 short-circuit feature, it would be necessary to write
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	982
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	983 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	984 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	985 function f (a, b, c)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	986 if (nargin > 2)
7768 a2d9f325b65a Use isschar instead of deprecated isstr Rafael Laboissiere <rafael@debian.org> parents: 7594 diff changeset	987 if (ischar (c))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	988 @dots{}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	989 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	990 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	991
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	992 @noindent
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	993 Writing
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	994
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	995 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	996 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	997 function f (a, b, c)
7768 a2d9f325b65a Use isschar instead of deprecated isstr Rafael Laboissiere <rafael@debian.org> parents: 7594 diff changeset	998 if (nargin > 2 & ischar (c))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	999 @dots{}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1000 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1001 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1002
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1003 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1004 would result in an error if @code{f} were called with one or two
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1005 arguments because Octave would be forced to try to evaluate both of the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1006 operands for the operator @samp{&}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1007
12543 f60f755ebfe4 Add do_braindead_shortcircuit_evaluation to documentation. Rik <octave@nomad.inbox5.com> parents: 11552 diff changeset	1008 @sc{matlab} has special behavior that allows the operators @samp{&} and
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	1009 @samp{\|} to short-circuit when used in the truth expression for @code{if} and
22620 74fb14727a30 doc: Remove DOCSTRING references to non-existent functions (bug #49329). Rik <rik@octave.org> parents: 22323 diff changeset	1010 @code{while} statements. Octave behaves the same way for compatibility,
74fb14727a30 doc: Remove DOCSTRING references to non-existent functions (bug #49329). Rik <rik@octave.org> parents: 22323 diff changeset	1011 however, the use of the @samp{&} and @samp{\|} operators in this way is
74fb14727a30 doc: Remove DOCSTRING references to non-existent functions (bug #49329). Rik <rik@octave.org> parents: 22323 diff changeset	1012 strongly discouraged and a warning will be issued. Instead, you should use
74fb14727a30 doc: Remove DOCSTRING references to non-existent functions (bug #49329). Rik <rik@octave.org> parents: 22323 diff changeset	1013 the @samp{&&} and @samp{\|\|} operators that always have short-circuit behavior.
20745 c4f79fc9281a doc: Resolve two undocumented functions in manual. Rik <rik@octave.org> parents: 20659 diff changeset	1014
12543 f60f755ebfe4 Add do_braindead_shortcircuit_evaluation to documentation. Rik <octave@nomad.inbox5.com> parents: 11552 diff changeset	1015 Finally, the ternary operator (?:) is not supported in Octave. If
f60f755ebfe4 Add do_braindead_shortcircuit_evaluation to documentation. Rik <octave@nomad.inbox5.com> parents: 11552 diff changeset	1016 short-circuiting is not important, it can be replaced by the @code{ifelse}
f60f755ebfe4 Add do_braindead_shortcircuit_evaluation to documentation. Rik <octave@nomad.inbox5.com> parents: 11552 diff changeset	1017 function.
10308 0d928dd9eeb8 extend parseparams Jaroslav Hajek <highegg@gmail.com> parents: 10228 diff changeset	1018
11552 6b6e9051ecb8 Add merge/ifelse function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	1019 @DOCSTRING(merge)
10308 0d928dd9eeb8 extend parseparams Jaroslav Hajek <highegg@gmail.com> parents: 10228 diff changeset	1020
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	1021 @node Assignment Ops
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1022 @section Assignment Expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1023 @cindex assignment expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1024 @cindex assignment operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1025 @cindex operators, assignment
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1026 @cindex expressions, assignment
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1027
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1028 @opindex =
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1029
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1030 An @dfn{assignment} is an expression that stores a new value into a
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1031 variable. For example, the following expression assigns the value 1 to
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1032 the variable @code{z}:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1033
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1034 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1035 z = 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1036 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1037
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1038 @noindent
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1039 After this expression is executed, the variable @code{z} has the value 1.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1040 Whatever old value @code{z} had before the assignment is forgotten.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1041 The @samp{=} sign is called an @dfn{assignment operator}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1042
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1043 Assignments can store string values also. For example, the following
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17170 diff changeset	1044 expression would store the value @qcode{"this food is good"} in the
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1045 variable @code{message}:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1046
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1047 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1048 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1049 thing = "food"
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1050 predicate = "good"
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1051 message = [ "this " , thing , " is " , predicate ]
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1052 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1053 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1054
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1055 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1056 (This also illustrates concatenation of strings.)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1057
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1058 @cindex side effect
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1059 Most operators (addition, concatenation, and so on) have no effect
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1060 except to compute a value. If you ignore the value, you might as well
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1061 not use the operator. An assignment operator is different. It does
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1062 produce a value, but even if you ignore the value, the assignment still
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1063 makes itself felt through the alteration of the variable. We call this
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1064 a @dfn{side effect}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1065
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1066 @cindex lvalue
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1067 The left-hand operand of an assignment need not be a variable
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1068 (@pxref{Variables}). It can also be an element of a matrix
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1069 (@pxref{Index Expressions}) or a list of return values
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1070 (@pxref{Calling Functions}). These are all called @dfn{lvalues}, which
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1071 means they can appear on the left-hand side of an assignment operator.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1072 The right-hand operand may be any expression. It produces the new value
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1073 which the assignment stores in the specified variable, matrix element,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1074 or list of return values.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1075
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1076 It is important to note that variables do @emph{not} have permanent types.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1077 The type of a variable is simply the type of whatever value it happens
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1078 to hold at the moment. In the following program fragment, the variable
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1079 @code{foo} has a numeric value at first, and a string value later on:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1080
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1081 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1082 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1083 octave:13> foo = 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1084 foo = 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1085 octave:13> foo = "bar"
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1086 foo = bar
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1087 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1088 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1089
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1090 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1091 When the second assignment gives @code{foo} a string value, the fact that
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1092 it previously had a numeric value is forgotten.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1093
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1094 Assignment of a scalar to an indexed matrix sets all of the elements
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1095 that are referenced by the indices to the scalar value. For example, if
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1096 @code{a} is a matrix with at least two columns,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1097
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1098 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1099 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1100 a(:, 2) = 5
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1101 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1102 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1103
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1104 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1105 sets all the elements in the second column of @code{a} to 5.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1106
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1107 Assigning an empty matrix @samp{[]} works in most cases to allow you to
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1108 delete rows or columns of matrices and vectors. @xref{Empty Matrices}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1109 For example, given a 4 by 5 matrix @var{A}, the assignment
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1110
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1111 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1112 A (3, :) = []
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1113 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1114
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1115 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1116 deletes the third row of @var{A}, and the assignment
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1117
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1118 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1119 A (:, 1:2:5) = []
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1120 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1121
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1122 @noindent
6672 2f0abcba669c [project @ 2007-05-30 06:42:22 by jwe] jwe parents: 6642 diff changeset	1123 deletes the first, third, and fifth columns.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1124
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1125 An assignment is an expression, so it has a value. Thus, @code{z = 1}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1126 as an expression has the value 1. One consequence of this is that you
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1127 can write multiple assignments together:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1128
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1129 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1130 x = y = z = 0
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1131 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1132
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1133 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1134 stores the value 0 in all three variables. It does this because the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1135 value of @code{z = 0}, which is 0, is stored into @code{y}, and then
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1136 the value of @code{y = z = 0}, which is 0, is stored into @code{x}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1137
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1138 This is also true of assignments to lists of values, so the following is
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1139 a valid expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1140
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1141 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1142 [a, b, c] = [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1143 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1144
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1145 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1146 that is exactly equivalent to
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1147
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1148 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1149 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1150 [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1151 a = u
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1152 b = s
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1153 c = v
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1154 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1155 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1156
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1157 In expressions like this, the number of values in each part of the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1158 expression need not match. For example, the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1159
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1160 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1161 [a, b] = [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1162 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1163
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1164 @noindent
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	1165 is equivalent to
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1166
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1167 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1168 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1169 [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1170 a = u
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1171 b = s
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1172 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1173 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1174
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1175 @noindent
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1176 The number of values on the left side of the expression can, however,
9037 4cb9f994dcec Documentation cleanup of var.texi, expr.texi, eval.texi Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	1177 not exceed the number of values on the right side. For example, the
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1178 following will produce an error.
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1179
9153 5247e89688e1 Eliminate most overfull errors when running texi2pdf for generating pdf documentation Rik <rdrider0-list@yahoo.com> parents: 9037 diff changeset	1180 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9159 diff changeset	1181 @group
8015 30629059b72d Update the manual to reflect the changes in error output sh@sh-laptop parents: 7768 diff changeset	1182 [a, b, c, d] = [u, s, v] = svd (a);
7031 120f3135952f [project @ 2007-10-15 15:30:03 by jwe] jwe parents: 7018 diff changeset	1183 @print{} error: element number 4 undefined in return list
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9159 diff changeset	1184 @end group
9153 5247e89688e1 Eliminate most overfull errors when running texi2pdf for generating pdf documentation Rik <rdrider0-list@yahoo.com> parents: 9037 diff changeset	1185 @end example
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1186
10209 ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1187 The symbol @code{~} may be used as a placeholder in the list of lvalues,
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1188 indicating that the corresponding return value should be ignored and not stored
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1189 anywhere:
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1190
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1191 @example
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1192 @group
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1193 [~, s, v] = svd (a);
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1194 @end group
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1195 @end example
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1196
10228 fa0c28aff439 update documentation Jaroslav Hajek <highegg@gmail.com> parents: 10209 diff changeset	1197 This is cleaner and more memory efficient than using a dummy variable.
fa0c28aff439 update documentation Jaroslav Hajek <highegg@gmail.com> parents: 10209 diff changeset	1198 The @code{nargout} value for the right-hand side expression is not affected.
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	1199 If the assignment is used as an expression, the return value is a
322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	1200 comma-separated list with the ignored values dropped.
10209 ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1201
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1202 @opindex +=
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1203 A very common programming pattern is to increment an existing variable
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1204 with a given value, like this
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1205
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1206 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1207 a = a + 2;
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1208 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1209
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1210 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1211 This can be written in a clearer and more condensed form using the
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1212 @code{+=} operator
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1213
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1214 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1215 a += 2;
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1216 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1217
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1218 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1219 @opindex -=
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1220 @opindex *=
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1221 @opindex /=
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1222 Similar operators also exist for subtraction (@code{-=}),
9037 4cb9f994dcec Documentation cleanup of var.texi, expr.texi, eval.texi Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	1223 multiplication (@code{*=}), and division (@code{/=}). An expression
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1224 of the form
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1225
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1226 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1227 @var{expr1} @var{op}= @var{expr2}
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1228 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1229
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1230 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1231 is evaluated as
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1232
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1233 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1234 @var{expr1} = (@var{expr1}) @var{op} (@var{expr2})
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1235 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1236
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1237 @noindent
18842 e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1238 where @var{op} can be either @code{+}, @code{-}, @code{*}, or @code{/},
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1239 as long as @var{expr2} is a simple expression with no side effects. If
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1240 @var{expr2} also contains an assignment operator, then this expression
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1241 is evaluated as
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1242
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1243 @example
19152 0f9c5a15c8fa doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 19131 diff changeset	1244 @group
18842 e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1245 @var{temp} = @var{expr2}
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1246 @var{expr1} = (@var{expr1}) @var{op} @var{temp}
19152 0f9c5a15c8fa doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 19131 diff changeset	1247 @end group
18842 e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1248 @end example
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1249
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1250 @noindent
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1251 where @var{temp} is a placeholder temporary value storing the computed
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1252 result of evaluating @var{expr2}. So, the expression
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1253
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1254 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1255 a *= b+1
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1256 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1257
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1258 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1259 is evaluated as
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1260
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1261 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1262 a = a * (b+1)
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1263 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1264
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1265 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1266 and @emph{not}
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1267
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1268 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1269 a = a * b + 1
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1270 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1271
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1272 You can use an assignment anywhere an expression is called for. For
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1273 example, it is valid to write @code{x != (y = 1)} to set @code{y} to 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1274 and then test whether @code{x} equals 1. But this style tends to make
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1275 programs hard to read. Except in a one-shot program, you should rewrite
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1276 it to get rid of such nesting of assignments. This is never very hard.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1277
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1278 @cindex increment operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1279 @cindex decrement operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1280 @cindex operators, increment
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1281 @cindex operators, decrement
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1282
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	1283 @node Increment Ops
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1284 @section Increment Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1285
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1286 @emph{Increment operators} increase or decrease the value of a variable
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1287 by 1. The operator to increment a variable is written as @samp{++}. It
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1288 may be used to increment a variable either before or after taking its
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1289 value.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1290
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1291 For example, to pre-increment the variable @var{x}, you would write
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1292 @code{++@var{x}}. This would add one to @var{x} and then return the new
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1293 value of @var{x} as the result of the expression. It is exactly the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1294 same as the expression @code{@var{x} = @var{x} + 1}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1295
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1296 To post-increment a variable @var{x}, you would write @code{@var{x}++}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1297 This adds one to the variable @var{x}, but returns the value that
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1298 @var{x} had prior to incrementing it. For example, if @var{x} is equal
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1299 to 2, the result of the expression @code{@var{x}++} is 2, and the new
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1300 value of @var{x} is 3.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1301
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1302 For matrix and vector arguments, the increment and decrement operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1303 work on each element of the operand.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1304
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1305 Here is a list of all the increment and decrement expressions.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1306
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1307 @table @code
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1308 @item ++@var{x}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1309 @opindex ++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1310 This expression increments the variable @var{x}. The value of the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1311 expression is the @emph{new} value of @var{x}. It is equivalent to the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1312 expression @code{@var{x} = @var{x} + 1}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1313
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1314 @item --@var{x}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1315 @opindex @code{--}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1316 This expression decrements the variable @var{x}. The value of the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1317 expression is the @emph{new} value of @var{x}. It is equivalent to the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1318 expression @code{@var{x} = @var{x} - 1}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1319
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1320 @item @var{x}++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1321 @opindex ++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1322 This expression causes the variable @var{x} to be incremented. The
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1323 value of the expression is the @emph{old} value of @var{x}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1324
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1325 @item @var{x}--
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1326 @opindex @code{--}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1327 This expression causes the variable @var{x} to be decremented. The
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1328 value of the expression is the @emph{old} value of @var{x}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1329 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1330
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	1331 @node Operator Precedence
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1332 @section Operator Precedence
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1333 @cindex operator precedence
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1334
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1335 @dfn{Operator precedence} determines how operators are grouped, when
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1336 different operators appear close by in one expression. For example,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1337 @samp{*} has higher precedence than @samp{+}. Thus, the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1338 @code{a + b * c} means to multiply @code{b} and @code{c}, and then add
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1339 @code{a} to the product (i.e., @code{a + (b * c)}).
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1340
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1341 You can overrule the precedence of the operators by using parentheses.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1342 You can think of the precedence rules as saying where the parentheses
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1343 are assumed if you do not write parentheses yourself. In fact, it is
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1344 wise to use parentheses whenever you have an unusual combination of
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1345 operators, because other people who read the program may not remember
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1346 what the precedence is in this case. You might forget as well, and then
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1347 you too could make a mistake. Explicit parentheses will help prevent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1348 any such mistake.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1349
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1350 When operators of equal precedence are used together, the leftmost
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1351 operator groups first, except for the assignment operators, which group
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1352 in the opposite order. Thus, the expression @code{a - b + c} groups as
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1353 @code{(a - b) + c}, but the expression @code{a = b = c} groups as
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1354 @code{a = (b = c)}.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1355
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1356 The precedence of prefix unary operators is important when another
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1357 operator follows the operand. For example, @code{-x^2} means
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1358 @code{-(x^2)}, because @samp{-} has lower precedence than @samp{^}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1359
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1360 Here is a table of the operators in Octave, in order of decreasing
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1361 precedence. Unless noted, all operators group left to right.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1362
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1363 @table @code
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1364 @item function call and array indexing, cell array indexing, and structure element indexing
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1365 @samp{()} @samp{@{@}} @samp{.}
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1366
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1367 @item postfix increment, and postfix decrement
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1368 @samp{++} @samp{--}
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1369
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1370 These operators group right to left.
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1371
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1372 @item transpose and exponentiation
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1373 @samp{'} @samp{.'} @samp{^} @samp{} @samp{.^} @samp{.}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1374
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1375 @item unary plus, unary minus, prefix increment, prefix decrement, and logical "not"
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1376 @samp{+} @samp{-} @samp{++} @samp{--} @samp{~} @samp{!}
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1377
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1378 @item multiply and divide
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1379 @samp{} @samp{/} @samp{\} @samp{.\} @samp{.} @samp{./}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1380
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1381 @item add, subtract
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1382 @samp{+} @samp{-}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1383
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1384 @item colon
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1385 @samp{:}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1386
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1387 @item relational
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1388 @samp{<} @samp{<=} @samp{==} @samp{>=} @samp{>} @samp{!=}
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1389 @samp{~=}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1390
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1391 @item element-wise "and"
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1392 @samp{&}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1393
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1394 @item element-wise "or"
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1395 @samp{\|}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1396
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1397 @item logical "and"
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1398 @samp{&&}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1399
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1400 @item logical "or"
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1401 @samp{\|\|}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1402
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1403 @item assignment
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1404 @samp{=} @samp{+=} @samp{-=} @samp{*=} @samp{/=} @samp{\=}
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1405 @samp{^=} @samp{.*=} @samp{./=} @samp{.\=} @samp{.^=} @samp{\|=}
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1406 @samp{&=}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1407
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1408 These operators group right to left.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1409 @end table

Mercurial > jwe > octave

annotate doc/interpreter/expr.txi @ 22620:74fb14727a30