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

annotate doc/interpreter/expr.txi @ 24454:b9d482dd90f3 stable

doc: Fix mistaken use of space between function and '(' in documentation (bug #52723). * expr.txi: Reword section on Advanced Indexing for clarity. *ezmesh.m, ezmeshc.m, ezsurf.m, ezsurfc.m: Fix use of space between function '(' in documentation.

author	Rik <rik@octave.org>
date	Fri, 22 Dec 2017 15:29:45 -0800
parents	3ac9f9ecfae5
children	6558d0d3fdac abe0b0e08897

rev	line source
23219 3ac9f9ecfae5 maint: Update copyright dates. John W. Eaton <jwe@octave.org> parents: 22323 diff changeset	1 @c Copyright (C) 1996-2017 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
24454 b9d482dd90f3 doc: Fix mistaken use of space between function and '(' in documentation (bug #52723). Rik <rik@octave.org> parents: 23219 diff changeset	137 An array with @samp{nd} dimensions can be indexed using @samp{m}
14033 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
24454 b9d482dd90f3 doc: Fix mistaken use of space between function and '(' in documentation (bug #52723). Rik <rik@octave.org> parents: 23219 diff changeset	142 For the ordinary and most common case, @w{@code{m == nd}}, and each
b9d482dd90f3 doc: Fix mistaken use of space between function and '(' in documentation (bug #52723). Rik <rik@octave.org> parents: 23219 diff changeset	143 index corresponds to its respective dimension. If @w{@code{m < nd}},
b9d482dd90f3 doc: Fix mistaken use of space between function and '(' in documentation (bug #52723). Rik <rik@octave.org> parents: 23219 diff changeset	144 and every index is less than the size of the array in the @math{i^{th}}
b9d482dd90f3 doc: Fix mistaken use of space between function and '(' in documentation (bug #52723). Rik <rik@octave.org> parents: 23219 diff changeset	145 dimension (@code{m(i) < size (@var{array}, i)}), then the index expression
b9d482dd90f3 doc: Fix mistaken use of space between function and '(' in documentation (bug #52723). Rik <rik@octave.org> parents: 23219 diff changeset	146 is padded with @w{@code{n - m}} trailing singleton dimensions.
b9d482dd90f3 doc: Fix mistaken use of space between function and '(' in documentation (bug #52723). Rik <rik@octave.org> parents: 23219 diff changeset	147 If @w{@code{m < nd}} but one of the indices @code{m(i)} is outside the
14033 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
12544 3ba6e702e6fd Add allow_noninteger_range_as_index to documentation. Rik <octave@nomad.inbox5.com> parents: 12543 diff changeset	322 @DOCSTRING(allow_noninteger_range_as_index)
3ba6e702e6fd Add allow_noninteger_range_as_index to documentation. Rik <octave@nomad.inbox5.com> parents: 12543 diff changeset	323
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	324 @node Calling Functions
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	325 @section Calling Functions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	326
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	327 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	328 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	329 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	330
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	331 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	332 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	333 these. In addition, you can define your own functions.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	334 @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	335
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	336 @cindex arguments in function call
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	337 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	338 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	339 @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	340 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	341 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	342 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	343 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	344 intended. Here are some examples:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	345
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	346 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	347 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	348 sqrt (x^2 + y^2) # @r{One argument}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	349 ones (n, m) # @r{Two arguments}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	350 rand () # @r{No arguments}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	351 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	352 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	353
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	354 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	355 @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	356 to take the square root of:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	357
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	358 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	359 sqrt (@var{argument})
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	360 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	361
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	362 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	363 depending on the particular usage, and their behavior is different
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	364 depending on the number of arguments supplied.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	365
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	366 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	367 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	368 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	369 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	370 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	371
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	372 Unlike most languages, functions in Octave may return multiple values.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	373 For example, the following statement
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	374
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	375 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	376 [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	377 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	378
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	379 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	380 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	381 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	382
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	383 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	384 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	385 expressions. See also @ref{Index Expressions}, and @ref{Assignment Ops}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	386
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	387 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	388 * Call by Value::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	389 * Recursion::
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	390 @end menu
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	391
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	392 @node Call by Value
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	393 @subsection Call by Value
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	394
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	395 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	396 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	397 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	398 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	399 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	400 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	401 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	402 body. For example, the function
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	403
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	404 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	405 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	406 function f (x, n)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	407 while (n-- > 0)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	408 disp (x);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	409 endwhile
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	410 endfunction
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	411 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	412 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	413
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	414 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	415 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	416 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	417 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	418 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	419 pass constants for any function parameter without first having to
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	420 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	421
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	422 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	423 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	424 argument had. For example, given a function called as
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	425
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	426 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	427 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	428 foo = "bar";
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	429 fcn (foo)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	430 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	431 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	432
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	433 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	434 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	435 @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	436 @qcode{"bar"}.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	437
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	438 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	439 values are not copied unnecessarily. For example,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	440
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	441 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	442 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	443 x = rand (1000);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	444 f (x);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	445 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	446 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	447
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	448 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	449 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	450 @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	451 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	452 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	453 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	454 temporary result.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	455
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	456 @node Recursion
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	457 @subsection Recursion
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	458 @cindex factorial function
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	459
6939 46d1ad37d943 [project @ 2007-10-01 16:12:20 by jwe] jwe parents: 6778 diff changeset	460 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	461 implemented in terms of functions that cannot be called recursively.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	462 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	463 Fortran subroutine that cannot be called recursively, so @code{lsode}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	464 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	465 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	466 in an error.}, recursive function calls are allowed. A
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	467 @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	468 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	469 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	470 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	471 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	472
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	473 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	474 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	475 function retval = fact (n)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	476 if (n > 0)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	477 retval = n * fact (n-1);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	478 else
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	479 retval = 1;
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	480 endif
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	481 endfunction
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	482 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	483 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	484
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	485 This function is recursive because it calls itself directly. It
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	486 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	487 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	488 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	489 the recursion ends.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	490
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	491 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	492 the recursion depth and prevents Octave from recursing infinitely.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	493
3371 86873384cd10 [project @ 1999-11-21 17:31:07 by jwe] jwe parents: 3294 diff changeset	494 @DOCSTRING(max_recursion_depth)
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	495
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	496 @node Arithmetic Ops
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	497 @section Arithmetic Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	498 @cindex arithmetic operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	499 @cindex operators, arithmetic
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	500 @cindex addition
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	501 @cindex subtraction
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	502 @cindex multiplication
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	503 @cindex matrix multiplication
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	504 @cindex division
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	505 @cindex quotient
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	506 @cindex negation
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	507 @cindex unary minus
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	508 @cindex exponentiation
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	509 @cindex transpose
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	510 @cindex Hermitian operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	511 @cindex transpose, complex-conjugate
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	512 @cindex complex-conjugate transpose
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	513
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	514 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	515 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	516 (@pxref{Broadcasting}).
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	517
13780 990762e784fe Fix confusing interaction between @code macro and transpose operator (') in documentation (Bug #34661). Rik <octave@nomad.inbox5.com> parents: 12627 diff changeset	518 @table @asis
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	519 @item @var{x} + @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	520 @opindex +
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	521 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	522 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	523
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	524 @item @var{x} .+ @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	525 @opindex .+
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	526 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	527
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	528 @item @var{x} - @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	529 @opindex -
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	530 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	531 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	532 shape.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	533
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	534 @item @var{x} .- @var{y}
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	535 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	536
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	537 @item @var{x} * @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	538 @opindex *
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	539 Matrix multiplication. The number of columns of @var{x} must agree with
24454 b9d482dd90f3 doc: Fix mistaken use of space between function and '(' in documentation (bug #52723). Rik <rik@octave.org> parents: 23219 diff changeset	540 the number of rows of @var{y}.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	541
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	542 @item @var{x} .* @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	543 @opindex .*
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	544 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	545 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	546 broadcastable to the same shape.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	547
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	548 @item @var{x} / @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	549 @opindex /
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	550 Right division. This is conceptually equivalent to the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	551
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	552 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	553 (inverse (y') * x')'
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	554 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	555
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	556 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	557 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	558
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	559 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	560 a minimum norm solution is computed.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	561
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	562 @item @var{x} ./ @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	563 @opindex ./
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	564 Element-by-element right division.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	565
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	566 @item @var{x} \ @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	567 @opindex \
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	568 Left division. This is conceptually equivalent to the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	569
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	570 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	571 inverse (x) * y
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	572 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	573
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	574 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	575 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	576
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	577 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	578 a minimum norm solution is computed.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	579
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	580 @item @var{x} .\ @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	581 @opindex .\
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	582 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	583 by each corresponding element of @var{x}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	584
17170 d6499c14021c doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 17152 diff changeset	585 @item @var{x} ^ @var{y}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	586 @itemx @var{x} ** @var{y}
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 @opindex ^
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	589 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	590 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	591 @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	592 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	593 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	594 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	595 @var{x} and @var{y} are matrices.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	596
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	597 The implementation of this operator needs to be improved.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	598
17170 d6499c14021c doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 17152 diff changeset	599 @item @var{x} .^ @var{y}
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	600 @itemx @var{x} .** @var{y}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	601 @opindex .**
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	602 @opindex .^
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	603 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	604 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	605 broadcastable to the same shape. If several complex results are
2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	606 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	607 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	608 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	609 real result is preferred.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	610
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	611 @item -@var{x}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	612 @opindex -
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	613 Negation.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	614
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	615 @item +@var{x}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	616 @opindex +
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	617 Unary plus. This operator has no effect on the operand.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	618
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	619 @item @var{x}'
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	620 @opindex '
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	621 Complex conjugate transpose. For real arguments, this operator is the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	622 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	623 equivalent to the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	624
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	625 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	626 conj (x.')
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	627 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	628
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	629 @item @var{x}.'
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	630 @opindex .'
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	631 Transpose.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	632 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	633
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	634 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	635 @samp{.}, there is a possible ambiguity for statements like
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	636
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	637 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	638 1./m
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	639 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	640
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	641 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	642 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	643 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	644 expression as if you had typed
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	645
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	646 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	647 (1) ./ m
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	648 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	649
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	650 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	651 and not
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	652
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	653 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	654 (1.) / m
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	655 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	656
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	657 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	658 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	659 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	660 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	661 useful in this case.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	662
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	663 @opindex '
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	664 @DOCSTRING(ctranspose)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	665
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	666 @opindex .\
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	667 @DOCSTRING(ldivide)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	668
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	669 @opindex -
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	670 @DOCSTRING(minus)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	671
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	672 @opindex \
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	673 @DOCSTRING(mldivide)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	674
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 @opindex ^
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	677 @DOCSTRING(mpower)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	678
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	679 @opindex /
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	680 @DOCSTRING(mrdivide)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	681
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	682 @opindex *
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	683 @DOCSTRING(mtimes)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	684
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	685 @opindex +
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	686 @DOCSTRING(plus)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	687
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 @opindex .^
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	690 @DOCSTRING(power)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	691
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	692 @opindex ./
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	693 @DOCSTRING(rdivide)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	694
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	695 @opindex .*
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	696 @DOCSTRING(times)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	697
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	698 @opindex .'
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	699 @DOCSTRING(transpose)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	700
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	701 @opindex -
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	702 @DOCSTRING(uminus)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	703
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	704 @opindex +
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	705 @DOCSTRING(uplus)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	706
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	707 @node Comparison Ops
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	708 @section Comparison Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	709 @cindex comparison expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	710 @cindex expressions, comparison
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	711 @cindex relational operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	712 @cindex operators, relational
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	713 @cindex less than operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	714 @cindex greater than operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	715 @cindex equality operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	716 @cindex tests for equality
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	717 @cindex equality, tests for
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	718
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	719 @dfn{Comparison operators} compare numeric values for relationships
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	720 such as equality. They are written using
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	721 @emph{relational operators}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	722
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	723 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	724 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	725 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	726 @xref{Broadcasting}. For example:
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	727
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	728 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	729 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	730 [1, 2; 3, 4] == [1, 3; 2, 4]
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	731 @result{} 1 0
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	732 0 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	733 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	734 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	735
14116 951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14038 diff changeset	736 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	737 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	738 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	739
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	740 @table @code
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	741 @item @var{x} < @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	742 @opindex <
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	743 True if @var{x} is less than @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	744
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	745 @item @var{x} <= @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	746 @opindex <=
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	747 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	748
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	749 @item @var{x} == @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	750 @opindex ==
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	751 True if @var{x} is equal to @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	752
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	753 @item @var{x} >= @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	754 @opindex >=
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	755 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	756
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	757 @item @var{x} > @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	758 @opindex >
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	759 True if @var{x} is greater than @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	760
17170 d6499c14021c doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 17152 diff changeset	761 @item @var{x} != @var{y}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	762 @itemx @var{x} ~= @var{y}
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 @opindex ~=
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	765 True if @var{x} is not equal to @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	766 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	767
9578 7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	768 For complex numbers, the following ordering is defined:
7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	769 @var{z1} < @var{z2}
16826 a4969508008e doc: Periodic spellcheck of the documentation. Rik <rik@octave.org> parents: 14856 diff changeset	770 if and only if
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	771
9578 7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	772 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9578 diff changeset	773 @group
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	774 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	775 \|\| (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	776 @end group
9578 7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	777 @end example
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	778
322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	779 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	780 @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	781 parts.
9578 7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	782
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	783 String comparisons may also be performed with the @code{strcmp}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	784 function, not with the comparison operators listed above.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	785 @xref{Strings}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	786
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	787 @opindex ==
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	788 @DOCSTRING(eq)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	789
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	790 @opindex >=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	791 @DOCSTRING(ge)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	792
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	793 @opindex >
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	794 @DOCSTRING(gt)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	795
6550 1b7a6061a05d [project @ 2007-04-20 07:40:26 by jwe] jwe parents: 6549 diff changeset	796 @DOCSTRING(isequal)
1b7a6061a05d [project @ 2007-04-20 07:40:26 by jwe] jwe parents: 6549 diff changeset	797
16935 a7b2fc7fe1a9 binocdf.m: Reverse calling convention to betaincinv to preserve accuracy when p =~ 1. Rik <rik@octave.org> parents: 16826 diff changeset	798 @DOCSTRING(isequaln)
6550 1b7a6061a05d [project @ 2007-04-20 07:40:26 by jwe] jwe parents: 6549 diff changeset	799
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	800 @opindex <=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	801 @DOCSTRING(le)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	802
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	803 @opindex <
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	804 @DOCSTRING(lt)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	805
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 @opindex ~=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	808 @DOCSTRING(ne)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	809
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	810 @node Boolean Expressions
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	811 @section Boolean Expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	812 @cindex expressions, boolean
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	813 @cindex boolean expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	814 @cindex expressions, logical
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	815 @cindex logical expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	816 @cindex operators, boolean
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	817 @cindex boolean operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	818 @cindex logical operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	819 @cindex operators, logical
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	820 @cindex and operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	821 @cindex or operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	822 @cindex not operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	823
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	824 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	825 * Element-by-element Boolean Operators::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	826 * Short-circuit Boolean Operators::
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	827 @end menu
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	828
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	829 @node Element-by-element Boolean Operators
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	830 @subsection Element-by-element Boolean Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	831 @cindex element-by-element evaluation
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	832
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	833 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	834 comparison expressions using the boolean
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	835 operators ``or'' (@samp{\|}), ``and'' (@samp{&}), and ``not'' (@samp{!}),
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	836 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	837 expression is computed by combining the truth values of the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	838 corresponding elements of the component expressions. A value is
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	839 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	840
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	841 Element-by-element boolean expressions can be used wherever comparison
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	842 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	843 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	844 @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	845 elements are nonzero.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	846
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	847 Like comparison operations, each element of an element-by-element
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	848 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	849 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	850 variable, or used in arithmetic.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	851
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	852 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	853
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	854 @table @code
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	855 @item @var{boolean1} & @var{boolean2}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	856 @opindex &
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	857 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	858 @var{boolean1} and @var{boolean2} are true.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	859
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	860 @item @var{boolean1} \| @var{boolean2}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	861 @opindex \|
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	862 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	863 of @var{boolean1} or @var{boolean2} is true.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	864
17170 d6499c14021c doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 17152 diff changeset	865 @item ! @var{boolean}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	866 @itemx ~ @var{boolean}
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 @opindex !
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	869 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	870 @var{boolean} is false.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	871 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	872
14119 94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14116 diff changeset	873 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	874 expression
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	875
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	876 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	877 [1, 0; 0, 1] & [1, 0; 2, 3]
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	878 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	879
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	880 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	881 returns a two by two identity matrix.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	882
14119 94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14116 diff changeset	883 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	884 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	885 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	886 matrix.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	887
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	888 For the binary element-by-element boolean operators, both subexpressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	889 @var{boolean1} and @var{boolean2} are evaluated before computing the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	890 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	891 effects. For example, in the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	892
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	893 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	894 a & b++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	895 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	896
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	897 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	898 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	899 @var{a} is zero.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	900
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	901 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	902 described for matrix-valued operands.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	903
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	904 @opindex &
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	905 @DOCSTRING(and)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	906
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 @opindex !
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	909 @DOCSTRING(not)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	910
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	911 @opindex \|
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	912 @DOCSTRING(or)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	913
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	914 @node Short-circuit Boolean Operators
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	915 @subsection Short-circuit Boolean Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	916 @cindex short-circuit evaluation
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	917
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	918 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	919 @code{while} conditions, Octave's element-by-element boolean operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	920 are often sufficient for performing most logical operations. However,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	921 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	922 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	923 @dfn{short-circuit} boolean operators work this way.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	924
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	925 @table @code
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	926 @item @var{boolean1} && @var{boolean2}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	927 @opindex &&
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	928 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	929 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	930 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	931 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	932 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	933 (@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	934 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	935
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	936 @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	937 @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	938 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	939 so @code{[] && true} evaluates to @code{false} even though
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	940 @code{all ([])} is @code{true}.
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	941
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	942 @item @var{boolean1} \|\| @var{boolean2}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	943 @opindex \|\|
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	944 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	945 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	946 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	947 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	948 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	949 (@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	950 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	951
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	952 @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	953 see the previous list item for details.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	954 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	955
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	956 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	957 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	958 the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	959
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	960 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	961 a && b++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	962 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	963
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	964 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	965 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	966 @var{a} is nonzero.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	967
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	968 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	969 is possible write
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	970
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	971 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	972 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	973 function f (a, b, c)
7768 a2d9f325b65a Use isschar instead of deprecated isstr Rafael Laboissiere <rafael@debian.org> parents: 7594 diff changeset	974 if (nargin > 2 && ischar (c))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	975 @dots{}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	976 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	977 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	978
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	979 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	980 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	981 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	982 short-circuit feature, it would be necessary to write
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	983
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	984 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	985 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	986 function f (a, b, c)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	987 if (nargin > 2)
7768 a2d9f325b65a Use isschar instead of deprecated isstr Rafael Laboissiere <rafael@debian.org> parents: 7594 diff changeset	988 if (ischar (c))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	989 @dots{}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	990 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	991 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	992
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	993 @noindent
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	994 Writing
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	995
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	996 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	997 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	998 function f (a, b, c)
7768 a2d9f325b65a Use isschar instead of deprecated isstr Rafael Laboissiere <rafael@debian.org> parents: 7594 diff changeset	999 if (nargin > 2 & ischar (c))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1000 @dots{}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1001 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1002 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1003
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1004 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1005 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	1006 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	1007 operands for the operator @samp{&}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1008
12543 f60f755ebfe4 Add do_braindead_shortcircuit_evaluation to documentation. Rik <octave@nomad.inbox5.com> parents: 11552 diff changeset	1009 @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	1010 @samp{\|} to short-circuit when used in the truth expression for @code{if} and
19131 cbd55a4e549b update documentation for do_braindead_shortcircuit_evaluation (bug #43177) John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	1011 @code{while} statements. Octave also behaves the same way by default,
cbd55a4e549b update documentation for do_braindead_shortcircuit_evaluation (bug #43177) John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	1012 though the use of the @samp{&} and @samp{\|} operators in this way is
cbd55a4e549b update documentation for do_braindead_shortcircuit_evaluation (bug #43177) John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	1013 strongly discouraged. Instead, you should use the @samp{&&} and @samp{\|\|}
cbd55a4e549b update documentation for do_braindead_shortcircuit_evaluation (bug #43177) John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	1014 operators that always have short-circuit behavior.
12543 f60f755ebfe4 Add do_braindead_shortcircuit_evaluation to documentation. Rik <octave@nomad.inbox5.com> parents: 11552 diff changeset	1015
20745 c4f79fc9281a doc: Resolve two undocumented functions in manual. Rik <rik@octave.org> parents: 20659 diff changeset	1016 @DOCSTRING(do_braindead_shortcircuit_evaluation)
c4f79fc9281a doc: Resolve two undocumented functions in manual. Rik <rik@octave.org> parents: 20659 diff changeset	1017
12543 f60f755ebfe4 Add do_braindead_shortcircuit_evaluation to documentation. Rik <octave@nomad.inbox5.com> parents: 11552 diff changeset	1018 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	1019 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	1020 function.
10308 0d928dd9eeb8 extend parseparams Jaroslav Hajek <highegg@gmail.com> parents: 10228 diff changeset	1021
11552 6b6e9051ecb8 Add merge/ifelse function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	1022 @DOCSTRING(merge)
10308 0d928dd9eeb8 extend parseparams Jaroslav Hajek <highegg@gmail.com> parents: 10228 diff changeset	1023
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	1024 @node Assignment Ops
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1025 @section Assignment Expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1026 @cindex assignment expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1027 @cindex assignment operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1028 @cindex operators, assignment
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1029 @cindex expressions, assignment
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1030
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1031 @opindex =
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1032
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1033 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	1034 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	1035 the variable @code{z}:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1036
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1037 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1038 z = 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1039 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1040
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1041 @noindent
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1042 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	1043 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	1044 The @samp{=} sign is called an @dfn{assignment operator}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1045
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1046 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	1047 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	1048 variable @code{message}:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1049
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1050 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1051 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1052 thing = "food"
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1053 predicate = "good"
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1054 message = [ "this " , thing , " is " , predicate ]
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1055 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1056 @end example
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 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1059 (This also illustrates concatenation of strings.)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1060
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1061 @cindex side effect
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1062 Most operators (addition, concatenation, and so on) have no effect
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1063 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	1064 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	1065 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	1066 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	1067 a @dfn{side effect}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1068
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1069 @cindex lvalue
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1070 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	1071 (@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	1072 (@pxref{Index Expressions}) or a list of return values
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1073 (@pxref{Calling Functions}). These are all called @dfn{lvalues}, which
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1074 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	1075 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	1076 which the assignment stores in the specified variable, matrix element,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1077 or list of return values.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1078
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1079 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	1080 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	1081 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	1082 @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	1083
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1084 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1085 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1086 octave:13> foo = 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1087 foo = 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1088 octave:13> foo = "bar"
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1089 foo = bar
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1090 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1091 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1092
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1093 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1094 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	1095 it previously had a numeric value is forgotten.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1096
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1097 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	1098 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	1099 @code{a} is a matrix with at least two columns,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1100
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1101 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1102 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1103 a(:, 2) = 5
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1104 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1105 @end example
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 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1108 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	1109
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1110 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	1111 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	1112 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	1113
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1114 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1115 A (3, :) = []
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1116 @end example
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 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1119 deletes the third row of @var{A}, and the assignment
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1120
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1121 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1122 A (:, 1:2:5) = []
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1123 @end example
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 @noindent
6672 2f0abcba669c [project @ 2007-05-30 06:42:22 by jwe] jwe parents: 6642 diff changeset	1126 deletes the first, third, and fifth columns.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1127
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1128 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	1129 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	1130 can write multiple assignments together:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1131
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1132 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1133 x = y = z = 0
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1134 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1135
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1136 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1137 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	1138 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	1139 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	1140
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1141 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	1142 a valid expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1143
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1144 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1145 [a, b, c] = [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1146 @end example
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 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1149 that is exactly equivalent to
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1150
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1151 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1152 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1153 [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1154 a = u
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1155 b = s
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1156 c = v
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1157 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1158 @end example
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 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	1161 expression need not match. For example, the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1162
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1163 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1164 [a, b] = [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1165 @end example
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 @noindent
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	1168 is equivalent to
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1169
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1170 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1171 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1172 [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1173 a = u
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1174 b = s
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1175 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1176 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1177
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1178 @noindent
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1179 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	1180 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	1181 following will produce an error.
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1182
9153 5247e89688e1 Eliminate most overfull errors when running texi2pdf for generating pdf documentation Rik <rdrider0-list@yahoo.com> parents: 9037 diff changeset	1183 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9159 diff changeset	1184 @group
8015 30629059b72d Update the manual to reflect the changes in error output sh@sh-laptop parents: 7768 diff changeset	1185 [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	1186 @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	1187 @end group
9153 5247e89688e1 Eliminate most overfull errors when running texi2pdf for generating pdf documentation Rik <rdrider0-list@yahoo.com> parents: 9037 diff changeset	1188 @end example
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1189
10209 ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1190 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	1191 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	1192 anywhere:
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1193
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1194 @example
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1195 @group
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1196 [~, s, v] = svd (a);
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1197 @end group
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1198 @end example
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1199
10228 fa0c28aff439 update documentation Jaroslav Hajek <highegg@gmail.com> parents: 10209 diff changeset	1200 This is cleaner and more memory efficient than using a dummy variable.
fa0c28aff439 update documentation Jaroslav Hajek <highegg@gmail.com> parents: 10209 diff changeset	1201 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	1202 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	1203 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	1204
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1205 @opindex +=
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1206 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	1207 with a given value, like this
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1208
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1209 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1210 a = a + 2;
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1211 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1212
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1213 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1214 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	1215 @code{+=} operator
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1216
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1217 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1218 a += 2;
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1219 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1220
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1221 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1222 @opindex -=
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1223 @opindex *=
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1224 @opindex /=
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1225 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	1226 multiplication (@code{*=}), and division (@code{/=}). An expression
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1227 of the form
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1228
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1229 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1230 @var{expr1} @var{op}= @var{expr2}
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1231 @end example
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 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1234 is evaluated as
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1235
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1236 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1237 @var{expr1} = (@var{expr1}) @var{op} (@var{expr2})
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1238 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1239
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1240 @noindent
18842 e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1241 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	1242 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	1243 @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	1244 is evaluated as
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1245
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1246 @example
19152 0f9c5a15c8fa doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 19131 diff changeset	1247 @group
18842 e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1248 @var{temp} = @var{expr2}
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1249 @var{expr1} = (@var{expr1}) @var{op} @var{temp}
19152 0f9c5a15c8fa doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 19131 diff changeset	1250 @end group
18842 e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1251 @end example
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1252
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1253 @noindent
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1254 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	1255 result of evaluating @var{expr2}. So, the expression
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1256
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1257 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1258 a *= b+1
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1259 @end example
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 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1262 is evaluated as
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1263
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1264 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1265 a = a * (b+1)
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1266 @end example
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 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1269 and @emph{not}
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1270
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1271 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1272 a = a * b + 1
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1273 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1274
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1275 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	1276 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	1277 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	1278 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	1279 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	1280
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1281 @cindex increment operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1282 @cindex decrement operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1283 @cindex operators, increment
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1284 @cindex operators, decrement
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1285
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	1286 @node Increment Ops
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1287 @section Increment Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1288
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1289 @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	1290 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	1291 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	1292 value.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1293
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1294 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	1295 @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	1296 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	1297 same as the expression @code{@var{x} = @var{x} + 1}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1298
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1299 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	1300 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	1301 @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	1302 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	1303 value of @var{x} is 3.
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 For matrix and vector arguments, the increment and decrement operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1306 work on each element of the operand.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1307
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1308 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	1309
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1310 @table @code
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1311 @item ++@var{x}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1312 @opindex ++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1313 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	1314 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	1315 expression @code{@var{x} = @var{x} + 1}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1316
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1317 @item --@var{x}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1318 @opindex @code{--}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1319 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	1320 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	1321 expression @code{@var{x} = @var{x} - 1}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1322
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1323 @item @var{x}++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1324 @opindex ++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1325 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	1326 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	1327
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1328 @item @var{x}--
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1329 @opindex @code{--}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1330 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	1331 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	1332 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1333
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	1334 @node Operator Precedence
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1335 @section Operator Precedence
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1336 @cindex operator precedence
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1337
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1338 @dfn{Operator precedence} determines how operators are grouped, when
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1339 different operators appear close by in one expression. For example,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1340 @samp{*} has higher precedence than @samp{+}. Thus, the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1341 @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	1342 @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	1343
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1344 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	1345 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	1346 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	1347 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	1348 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	1349 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	1350 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	1351 any such mistake.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1352
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1353 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	1354 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	1355 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	1356 @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	1357 @code{a = (b = c)}.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1358
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1359 The precedence of prefix unary operators is important when another
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1360 operator follows the operand. For example, @code{-x^2} means
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1361 @code{-(x^2)}, because @samp{-} has lower precedence than @samp{^}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1362
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1363 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	1364 precedence. Unless noted, all operators group left to right.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1365
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1366 @table @code
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1367 @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	1368 @samp{()} @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 @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	1371 @samp{++} @samp{--}
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1372
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1373 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	1374
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1375 @item transpose and exponentiation
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{.}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1377
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1378 @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	1379 @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	1380
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1381 @item multiply and divide
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1382 @samp{} @samp{/} @samp{\} @samp{.\} @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 add, subtract
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1385 @samp{+} @samp{-}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1386
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1387 @item colon
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1388 @samp{:}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1389
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1390 @item relational
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1391 @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	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 "and"
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 element-wise "or"
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 "and"
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 logical "or"
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1404 @samp{\|\|}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1405
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1406 @item assignment
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1407 @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	1408 @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	1409 @samp{&=}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1410
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1411 These operators group right to left.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1412 @end table

Mercurial > jwe > octave

annotate doc/interpreter/expr.txi @ 24454:b9d482dd90f3 stable