octave-lyh: doc/interpreter/expr.txi annotate

annotate doc/interpreter/expr.txi @ 17483:bddb9688e41c

feather.m: Overhaul function for Matlab visual compatibility. * scripts/plot/feather.m: Reduce length of arrowhead size to 0.20 of arrow shaft. Change arrow head angle with shaft from 45 to 30 degrees. Use variable 'h' instead of 'retval' to match documentation. Redo input validation. Add %!error input validation tests.

author	Rik <rik@octave.org>
date	Tue, 24 Sep 2013 13:17:04 -0700
parents	bc924baa2c4e
children

rev	line source
14138 72c96de7a403 maint: update copyright notices for 2012 John W. Eaton <jwe@octave.org> parents: 14119 diff changeset	1 @c Copyright (C) 1996-2012 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.
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	9 @c
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.
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	14 @c
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
17160 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]
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	122 a(end + 1) = 5; # append element
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	123 a(end) = []; # delete element
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	124 a(1:2:end) # odd elements of a => [1, 3]
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	125 a(2:2:end) # even elements of a => [2, 4]
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	126 a(end:-1:1) # reversal of a => [4, 3, 2 , 1]
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	127 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	128 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	129
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	130 @menu
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	131 * Advanced Indexing::
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	132 @end menu
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	133
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	134 @node Advanced Indexing
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	135 @subsection Advanced Indexing
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	136
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	137 An array with @samp{n} dimensions can be indexed using @samp{m}
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	138 indices. More generally, the set of index tuples determining the
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	139 result is formed by the Cartesian product of the index vectors (or
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	140 ranges or scalars).
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	141
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	142 For the ordinary and most common case, @w{@code{m == n}}, and each
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	143 index corresponds to its respective dimension. If @w{@code{m < n}}
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	144 and every index is less than the size of the array in the
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	145 @math{i^{th}} dimension, @code{m(i) < n(i)}, then the index expression
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	146 is padded with trailing singleton dimensions (@code{[ones (m-n, 1)]}).
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	147 If @w{@code{m < n}} but one of the indices @code{m(i)} is outside the
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	148 size of the current array, then the last @w{@code{n-m+1}} dimensions
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	149 are folded into a single dimension with an extent equal to the product
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	150 of extents of the original dimensions. This is easiest to understand
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	151 with an example.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	152
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	153 @example
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	154 a = reshape (1:8, 2, 2, 2) # Create 3-D array
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	155 a =
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	156
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	157 ans(:,:,1) =
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	158
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	159 1 3
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	160 2 4
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	161
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	162 ans(:,:,2) =
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	163
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	164 5 7
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	165 6 8
9159 c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	166
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	167 a(2,1,2); # Case (m == n): ans = 6
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	168 a(2,1); # Case (m < n), idx within array:
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	169 # equivalent to a(2,1,1), ans = 2
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	170 a(2,4); # Case (m < n), idx outside array:
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	171 # Dimension 2 & 3 folded into new dimension of size 2x2 = 4
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	172 # Select 2nd row, 4th element of [2, 4, 6, 8], ans = 8
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	173 @end example
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	174
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	175 One advanced use of indexing is to create arrays filled with a single
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	176 value. This can be done by using an index of ones on a scalar value.
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	177 The result is an object with the dimensions of the index expression
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	178 and every element equal to the original scalar. For example, the
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	179 following statements
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	180
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	181 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	182 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	183 a = 13;
12546 39ca02387a32 Improve docstrings for a number of functions. Rik <octave@nomad.inbox5.com> parents: 12544 diff changeset	184 a(ones (1, 4))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	185 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	186 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	187
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	188 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	189 produce a vector whose four elements are all equal to 13.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	190
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	191 Similarly, by indexing a scalar with two vectors of ones it is
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	192 possible to create a matrix. The following statements
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	193
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	194 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	195 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	196 a = 13;
12546 39ca02387a32 Improve docstrings for a number of functions. Rik <octave@nomad.inbox5.com> parents: 12544 diff changeset	197 a(ones (1, 2), ones (1, 3))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	198 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	199 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	200
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	201 @noindent
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	202 create a 2x3 matrix with all elements equal to 13.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	203
9159 c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	204 The last example could also be written as
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	205
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	206 @example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	207 @group
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	208 13(ones (2, 3))
9159 c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	209 @end group
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	210 @end example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	211
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	212 It is more efficient to use indexing rather than the code construction
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	213 @code{scalar * ones (N, M, @dots{})} because it avoids the unnecessary
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	214 multiplication operation. Moreover, multiplication may not be
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	215 defined for the object to be replicated whereas indexing an array is
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	216 always defined. The following code shows how to create a 2x3 cell
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	217 array from a base unit which is not itself a scalar.
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	218
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	219 @example
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	220 @group
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	221 @{"Hello"@}(ones (2, 3))
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	222 @end group
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	223 @end example
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	224
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	225 It should be, noted that @code{ones (1, n)} (a row vector of ones)
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	226 results in a range (with zero increment). A range is stored
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	227 internally as a starting value, increment, end value, and total number
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	228 of values; hence, it is more efficient for storage than a vector or
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	229 matrix of ones whenever the number of elements is greater than 4. In
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	230 particular, when @samp{r} is a row vector, the expressions
9159 c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	231
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	232 @example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	233 r(ones (1, n), :)
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	234 @end example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	235
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	236 @example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	237 r(ones (n, 1), :)
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	238 @end example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	239
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	240 @noindent
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	241 will produce identical results, but the first one will be
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	242 significantly faster, at least for @samp{r} and @samp{n} large enough.
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	243 In the first case the index is held in compressed form as a range
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	244 which allows Octave to choose a more efficient algorithm to handle the
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	245 expression.
9159 c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	246
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	247 A general recommendation, for a user unaware of these subtleties, is
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	248 to use the function @code{repmat} for replicating smaller arrays into
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	249 bigger ones.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	250
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	251 A second use of indexing is to speed up code. Indexing is a fast
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	252 operation and judicious use of it can reduce the requirement for
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	253 looping over individual array elements which is a slow operation.
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	254
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	255 Consider the following example which creates a 10-element row vector
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	256 @math{a} containing the values
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	257 @tex
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	258 $a_i = \sqrt{i}$.
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	259 @end tex
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	260 @ifnottex
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14171 diff changeset	261 a(i) = sqrt (i).
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	262 @end ifnottex
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	263
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	264 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9159 diff changeset	265 @group
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	266 for i = 1:10
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	267 a(i) = sqrt (i);
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	268 endfor
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9159 diff changeset	269 @end group
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	270 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	271
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	272 @noindent
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	273 It is quite inefficient to create a vector using a loop like this. In
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	274 this case, it would have been much more efficient to use the
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	275 expression
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	276
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	277 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	278 a = sqrt (1:10);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	279 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	280
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	281 @noindent
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	282 which avoids the loop entirely.
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	283
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	284 In cases where a loop cannot be avoided, or a number of values must be
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	285 combined to form a larger matrix, it is generally faster to set the
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	286 size of the matrix first (pre-allocate storage), and then insert
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	287 elements using indexing commands. For example, given a matrix
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	288 @code{a},
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	289
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	290 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	291 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	292 [nr, nc] = size (a);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	293 x = zeros (nr, n * nc);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	294 for i = 1:n
3602 83889344cbef [project @ 2000-02-25 08:52:20 by jwe] jwe parents: 3428 diff changeset	295 x(:,(i-1)nc+1:inc) = a;
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	296 endfor
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	297 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	298 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	299
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	300 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	301 is considerably faster than
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	302
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	303 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	304 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	305 x = a;
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	306 for i = 1:n-1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	307 x = [x, a];
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	308 endfor
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	309 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	310 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	311
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	312 @noindent
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	313 because Octave does not have to repeatedly resize the intermediate
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	314 result.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	315
6549 5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 6501 diff changeset	316 @DOCSTRING(sub2ind)
5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 6501 diff changeset	317
5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 6501 diff changeset	318 @DOCSTRING(ind2sub)
5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 6501 diff changeset	319
11431 0d9640d755b1 Improve docstrings for all isXXX functions. Rik <octave@nomad.inbox5.com> parents: 11403 diff changeset	320 @DOCSTRING(isindex)
0d9640d755b1 Improve docstrings for all isXXX functions. Rik <octave@nomad.inbox5.com> parents: 11403 diff changeset	321
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
17160 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,
17289 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17178 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
14149 f1ff06a1d73a doc: Mention broadcasting in more relevant places. Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	540 the number of rows of @var{y}, or they must be broadcastable to the same
f1ff06a1d73a doc: Mention broadcasting in more relevant places. Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14138 diff changeset	541 shape.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	542
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	543 @item @var{x} .* @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	544 @opindex .*
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	545 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	546 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	547 broadcastable to the same shape.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	548
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	549 @item @var{x} / @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	550 @opindex /
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	551 Right division. This is conceptually equivalent to the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	552
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	553 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	554 (inverse (y') * x')'
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	555 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	556
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	557 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	558 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	559
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	560 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	561 a minimum norm solution is computed.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	562
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	563 @item @var{x} ./ @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	564 @opindex ./
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	565 Element-by-element right division.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	566
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	567 @item @var{x} \ @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	568 @opindex \
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	569 Left division. This is conceptually equivalent to the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	570
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	571 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	572 inverse (x) * y
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	573 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	574
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	575 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	576 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	577
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	578 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	579 a minimum norm solution is computed.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	580
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	581 @item @var{x} .\ @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	582 @opindex .\
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	583 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	584 by each corresponding element of @var{x}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	585
17178 d6499c14021c doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 17160 diff changeset	586 @item @var{x} ^ @var{y}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	587 @itemx @var{x} ** @var{y}
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 @opindex ^
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	590 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	591 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	592 @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	593 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	594 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	595 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	596 @var{x} and @var{y} are matrices.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	597
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	598 The implementation of this operator needs to be improved.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	599
17178 d6499c14021c doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 17160 diff changeset	600 @item @var{x} .^ @var{y}
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	601 @itemx @var{x} .** @var{y}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	602 @opindex .**
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	603 @opindex .^
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	604 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	605 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	606 broadcastable to the same shape. If several complex results are
2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	607 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	608 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	609 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	610 real result is preferred.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	611
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	612 @item -@var{x}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	613 @opindex -
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	614 Negation.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	615
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	616 @item +@var{x}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	617 @opindex +
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	618 Unary plus. This operator has no effect on the operand.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	619
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	620 @item @var{x}'
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	621 @opindex '
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	622 Complex conjugate transpose. For real arguments, this operator is the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	623 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	624 equivalent to the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	625
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	626 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	627 conj (x.')
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	628 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	629
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	630 @item @var{x}.'
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	631 @opindex .'
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	632 Transpose.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	633 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	634
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	635 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	636 @samp{.}, there is a possible ambiguity for statements like
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	637
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	638 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	639 1./m
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	640 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	641
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	642 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	643 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	644 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	645 expression as if you had typed
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	646
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	647 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	648 (1) ./ m
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	649 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	650
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	651 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	652 and not
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	653
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	654 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	655 (1.) / m
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	656 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	657
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	658 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	659 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	660 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	661 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	662 useful in this case.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	663
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	664 @opindex '
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	665 @DOCSTRING(ctranspose)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	666
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	667 @opindex .\
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	668 @DOCSTRING(ldivide)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	669
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	670 @opindex -
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	671 @DOCSTRING(minus)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	672
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	673 @opindex \
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	674 @DOCSTRING(mldivide)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	675
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 @opindex ^
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	678 @DOCSTRING(mpower)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	679
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	680 @opindex /
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	681 @DOCSTRING(mrdivide)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	682
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	683 @opindex *
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	684 @DOCSTRING(mtimes)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	685
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	686 @opindex +
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	687 @DOCSTRING(plus)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	688
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 @opindex .^
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	691 @DOCSTRING(power)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	692
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	693 @opindex ./
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	694 @DOCSTRING(rdivide)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	695
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	696 @opindex .*
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	697 @DOCSTRING(times)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	698
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	699 @opindex .'
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	700 @DOCSTRING(transpose)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	701
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	702 @opindex -
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	703 @DOCSTRING(uminus)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	704
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	705 @opindex +
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	706 @DOCSTRING(uplus)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	707
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	708 @node Comparison Ops
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	709 @section Comparison Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	710 @cindex comparison expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	711 @cindex expressions, comparison
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	712 @cindex relational operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	713 @cindex operators, relational
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	714 @cindex less than operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	715 @cindex greater than operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	716 @cindex equality operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	717 @cindex tests for equality
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	718 @cindex equality, tests for
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	719
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	720 @dfn{Comparison operators} compare numeric values for relationships
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	721 such as equality. They are written using
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	722 @emph{relational operators}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	723
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	724 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	725 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	726 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	727 @xref{Broadcasting}. For example:
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	728
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	729 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	730 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	731 [1, 2; 3, 4] == [1, 3; 2, 4]
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	732 @result{} 1 0
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	733 0 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	734 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	735 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	736
14116 951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14038 diff changeset	737 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	738 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	739 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	740
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	741 @table @code
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	742 @item @var{x} < @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	743 @opindex <
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	744 True if @var{x} is less than @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	745
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	746 @item @var{x} <= @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	747 @opindex <=
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	748 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	749
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	750 @item @var{x} == @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	751 @opindex ==
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	752 True if @var{x} is equal to @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	753
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	754 @item @var{x} >= @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	755 @opindex >=
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	756 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	757
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	758 @item @var{x} > @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	759 @opindex >
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	760 True if @var{x} is greater than @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	761
17178 d6499c14021c doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 17160 diff changeset	762 @item @var{x} != @var{y}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	763 @itemx @var{x} ~= @var{y}
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 @opindex ~=
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	766 True if @var{x} is not equal to @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	767 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	768
9578 7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	769 For complex numbers, the following ordering is defined:
7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	770 @var{z1} < @var{z2}
16826 a4969508008e doc: Periodic spellcheck of the documentation. Rik <rik@octave.org> parents: 14856 diff changeset	771 if and only if
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	772
9578 7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	773 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9578 diff changeset	774 @group
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})
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14171 diff changeset	776 \|\| (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	777 @end group
9578 7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	778 @end example
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	779
322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	780 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	781 @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	782 parts.
9578 7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	783
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	784 String comparisons may also be performed with the @code{strcmp}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	785 function, not with the comparison operators listed above.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	786 @xref{Strings}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	787
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	788 @opindex ==
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	789 @DOCSTRING(eq)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	790
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	791 @opindex >=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	792 @DOCSTRING(ge)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	793
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	794 @opindex >
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	795 @DOCSTRING(gt)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	796
6550 1b7a6061a05d [project @ 2007-04-20 07:40:26 by jwe] jwe parents: 6549 diff changeset	797 @DOCSTRING(isequal)
1b7a6061a05d [project @ 2007-04-20 07:40:26 by jwe] jwe parents: 6549 diff changeset	798
16935 a7b2fc7fe1a9 binocdf.m: Reverse calling convention to betaincinv to preserve accuracy when p =~ 1. Rik <rik@octave.org> parents: 16826 diff changeset	799 @DOCSTRING(isequaln)
6550 1b7a6061a05d [project @ 2007-04-20 07:40:26 by jwe] jwe parents: 6549 diff changeset	800
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	801 @opindex <=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	802 @DOCSTRING(le)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	803
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	804 @opindex <
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	805 @DOCSTRING(lt)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	806
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 @opindex ~=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	809 @DOCSTRING(ne)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	810
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	811 @node Boolean Expressions
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	812 @section Boolean Expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	813 @cindex expressions, boolean
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	814 @cindex boolean expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	815 @cindex expressions, logical
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	816 @cindex logical expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	817 @cindex operators, boolean
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	818 @cindex boolean operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	819 @cindex logical operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	820 @cindex operators, logical
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	821 @cindex and operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	822 @cindex or operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	823 @cindex not operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	824
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	825 @menu
17160 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	826 * Element-by-element Boolean Operators::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	827 * Short-circuit Boolean Operators::
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	828 @end menu
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	829
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	830 @node Element-by-element Boolean Operators
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	831 @subsection Element-by-element Boolean Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	832 @cindex element-by-element evaluation
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	833
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	834 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	835 comparison expressions using the boolean
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	836 operators ``or'' (@samp{\|}), ``and'' (@samp{&}), and ``not'' (@samp{!}),
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	837 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	838 expression is computed by combining the truth values of the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	839 corresponding elements of the component expressions. A value is
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	840 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	841
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	842 Element-by-element boolean expressions can be used wherever comparison
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	843 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	844 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	845 @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	846 elements are nonzero.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	847
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	848 Like comparison operations, each element of an element-by-element
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	849 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	850 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	851 variable, or used in arithmetic.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	852
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	853 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	854
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	855 @table @code
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	856 @item @var{boolean1} & @var{boolean2}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	857 @opindex &
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	858 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	859 @var{boolean1} and @var{boolean2} are true.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	860
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	861 @item @var{boolean1} \| @var{boolean2}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	862 @opindex \|
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	863 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	864 of @var{boolean1} or @var{boolean2} is true.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	865
17178 d6499c14021c doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 17160 diff changeset	866 @item ! @var{boolean}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	867 @itemx ~ @var{boolean}
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 @opindex !
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	870 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	871 @var{boolean} is false.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	872 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	873
14119 94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14116 diff changeset	874 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	875 expression
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	876
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	877 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	878 [1, 0; 0, 1] & [1, 0; 2, 3]
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	879 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	880
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	881 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	882 returns a two by two identity matrix.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	883
14119 94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14116 diff changeset	884 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	885 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	886 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	887 matrix.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	888
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	889 For the binary element-by-element boolean operators, both subexpressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	890 @var{boolean1} and @var{boolean2} are evaluated before computing the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	891 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	892 effects. For example, in the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	893
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	894 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	895 a & b++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	896 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	897
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	898 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	899 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	900 @var{a} is zero.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	901
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	902 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	903 described for matrix-valued operands.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	904
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	905 @opindex &
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	906 @DOCSTRING(and)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	907
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 @opindex !
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	910 @DOCSTRING(not)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	911
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	912 @opindex \|
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	913 @DOCSTRING(or)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	914
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	915 @node Short-circuit Boolean Operators
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	916 @subsection Short-circuit Boolean Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	917 @cindex short-circuit evaluation
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	918
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	919 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	920 @code{while} conditions, Octave's element-by-element boolean operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	921 are often sufficient for performing most logical operations. However,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	922 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	923 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	924 @dfn{short-circuit} boolean operators work this way.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	925
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	926 @table @code
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	927 @item @var{boolean1} && @var{boolean2}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	928 @opindex &&
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	929 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	930 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	931 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	932 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	933 scalar using the equivalent of the operation @code{all
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	934 (@var{boolean1}(:))}. 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	935 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	936
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	937 @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	938 @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	939 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	940 so @code{[] && true} evaluates to @code{false} even though
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	941 @code{all ([])} is @code{true}.
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	942
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	943 @item @var{boolean1} \|\| @var{boolean2}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	944 @opindex \|\|
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	945 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	946 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	947 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	948 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	949 scalar using the equivalent of the operation @code{all
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	950 (@var{boolean1}(:))}. 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	951 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	952
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	953 @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	954 see the previous list item for details.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	955 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	956
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	957 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	958 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	959 the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	960
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	961 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	962 a && b++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	963 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	964
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	965 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	966 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	967 @var{a} is nonzero.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	968
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	969 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	970 is possible write
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	971
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	972 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	973 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	974 function f (a, b, c)
7768 a2d9f325b65a Use isschar instead of deprecated isstr Rafael Laboissiere <rafael@debian.org> parents: 7594 diff changeset	975 if (nargin > 2 && ischar (c))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	976 @dots{}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	977 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	978 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	979
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	980 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	981 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	982 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	983 short-circuit feature, it would be necessary to write
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	984
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	985 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	986 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	987 function f (a, b, c)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	988 if (nargin > 2)
7768 a2d9f325b65a Use isschar instead of deprecated isstr Rafael Laboissiere <rafael@debian.org> parents: 7594 diff changeset	989 if (ischar (c))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	990 @dots{}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	991 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	992 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	993
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	994 @noindent
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	995 Writing
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	996
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	997 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	998 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	999 function f (a, b, c)
7768 a2d9f325b65a Use isschar instead of deprecated isstr Rafael Laboissiere <rafael@debian.org> parents: 7594 diff changeset	1000 if (nargin > 2 & ischar (c))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1001 @dots{}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1002 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1003 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1004
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1005 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1006 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	1007 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	1008 operands for the operator @samp{&}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1009
12543 f60f755ebfe4 Add do_braindead_shortcircuit_evaluation to documentation. Rik <octave@nomad.inbox5.com> parents: 11552 diff changeset	1010 @sc{matlab} has special behavior that allows the operators @samp{&} and
f60f755ebfe4 Add do_braindead_shortcircuit_evaluation to documentation. Rik <octave@nomad.inbox5.com> parents: 11552 diff changeset	1011 @samp{\|} to short-circuit when used in the truth expression for @code{if} and
f60f755ebfe4 Add do_braindead_shortcircuit_evaluation to documentation. Rik <octave@nomad.inbox5.com> parents: 11552 diff changeset	1012 @code{while} statements. The Octave parser may be instructed to behave in the
12601 99babbf683ff doc: Correct use of it's -> its in documentation. Rik <octave@nomad.inbox5.com> parents: 12546 diff changeset	1013 same manner, but its use is strongly discouraged.
12543 f60f755ebfe4 Add do_braindead_shortcircuit_evaluation to documentation. Rik <octave@nomad.inbox5.com> parents: 11552 diff changeset	1014
f60f755ebfe4 Add do_braindead_shortcircuit_evaluation to documentation. Rik <octave@nomad.inbox5.com> parents: 11552 diff changeset	1015 @DOCSTRING(do_braindead_shortcircuit_evaluation)
f60f755ebfe4 Add do_braindead_shortcircuit_evaluation to documentation. Rik <octave@nomad.inbox5.com> parents: 11552 diff changeset	1016
f60f755ebfe4 Add do_braindead_shortcircuit_evaluation to documentation. Rik <octave@nomad.inbox5.com> parents: 11552 diff changeset	1017 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	1018 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	1019 function.
10308 0d928dd9eeb8 extend parseparams Jaroslav Hajek <highegg@gmail.com> parents: 10228 diff changeset	1020
11552 6b6e9051ecb8 Add merge/ifelse function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	1021 @DOCSTRING(merge)
10308 0d928dd9eeb8 extend parseparams Jaroslav Hajek <highegg@gmail.com> parents: 10228 diff changeset	1022
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	1023 @node Assignment Ops
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1024 @section Assignment Expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1025 @cindex assignment expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1026 @cindex assignment operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1027 @cindex operators, assignment
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1028 @cindex expressions, assignment
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1029
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1030 @opindex =
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1031
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1032 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	1033 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	1034 the variable @code{z}:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1035
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1036 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1037 z = 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1038 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1039
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1040 @noindent
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1041 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	1042 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	1043 The @samp{=} sign is called an @dfn{assignment operator}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1044
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1045 Assignments can store string values also. For example, the following
17289 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17178 diff changeset	1046 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	1047 variable @code{message}:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1048
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1049 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1050 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1051 thing = "food"
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1052 predicate = "good"
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1053 message = [ "this " , thing , " is " , predicate ]
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1054 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1055 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1056
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1057 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1058 (This also illustrates concatenation of strings.)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1059
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1060 @cindex side effect
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1061 Most operators (addition, concatenation, and so on) have no effect
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1062 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	1063 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	1064 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	1065 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	1066 a @dfn{side effect}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1067
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1068 @cindex lvalue
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1069 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	1070 (@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	1071 (@pxref{Index Expressions}) or a list of return values
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1072 (@pxref{Calling Functions}). These are all called @dfn{lvalues}, which
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1073 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	1074 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	1075 which the assignment stores in the specified variable, matrix element,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1076 or list of return values.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1077
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1078 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	1079 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	1080 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	1081 @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	1082
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1083 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1084 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1085 octave:13> foo = 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1086 foo = 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1087 octave:13> foo = "bar"
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1088 foo = bar
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1089 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1090 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1091
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1092 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1093 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	1094 it previously had a numeric value is forgotten.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1095
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1096 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	1097 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	1098 @code{a} is a matrix with at least two columns,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1099
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1100 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1101 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1102 a(:, 2) = 5
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1103 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1104 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1105
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1106 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1107 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	1108
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1109 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	1110 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	1111 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	1112
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1113 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1114 A (3, :) = []
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1115 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1116
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1117 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1118 deletes the third row of @var{A}, and the assignment
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1119
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1120 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1121 A (:, 1:2:5) = []
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1122 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1123
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1124 @noindent
6672 2f0abcba669c [project @ 2007-05-30 06:42:22 by jwe] jwe parents: 6642 diff changeset	1125 deletes the first, third, and fifth columns.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1126
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1127 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	1128 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	1129 can write multiple assignments together:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1130
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1131 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1132 x = y = z = 0
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1133 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1134
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1135 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1136 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	1137 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	1138 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	1139
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1140 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	1141 a valid expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1142
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1143 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1144 [a, b, c] = [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1145 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1146
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1147 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1148 that is exactly equivalent to
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1149
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1150 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1151 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1152 [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1153 a = u
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1154 b = s
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1155 c = v
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1156 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1157 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1158
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1159 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	1160 expression need not match. For example, the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1161
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1162 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1163 [a, b] = [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1164 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1165
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1166 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1167 is equivalent to
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1168
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1169 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1170 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1171 [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1172 a = u
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1173 b = s
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1174 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1175 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1176
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1177 @noindent
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1178 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	1179 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	1180 following will produce an error.
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1181
9153 5247e89688e1 Eliminate most overfull errors when running texi2pdf for generating pdf documentation Rik <rdrider0-list@yahoo.com> parents: 9037 diff changeset	1182 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9159 diff changeset	1183 @group
8015 30629059b72d Update the manual to reflect the changes in error output sh@sh-laptop parents: 7768 diff changeset	1184 [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	1185 @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	1186 @end group
9153 5247e89688e1 Eliminate most overfull errors when running texi2pdf for generating pdf documentation Rik <rdrider0-list@yahoo.com> parents: 9037 diff changeset	1187 @end example
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1188
10209 ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1189 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	1190 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	1191 anywhere:
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1192
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1193 @example
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1194 @group
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1195 [~, s, v] = svd (a);
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1196 @end group
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1197 @end example
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1198
10228 fa0c28aff439 update documentation Jaroslav Hajek <highegg@gmail.com> parents: 10209 diff changeset	1199 This is cleaner and more memory efficient than using a dummy variable.
fa0c28aff439 update documentation Jaroslav Hajek <highegg@gmail.com> parents: 10209 diff changeset	1200 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	1201 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	1202 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	1203
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1204 @opindex +=
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1205 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	1206 with a given value, like this
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1207
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1208 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1209 a = a + 2;
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1210 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1211
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1212 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1213 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	1214 @code{+=} operator
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1215
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1216 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1217 a += 2;
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1218 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1219
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1220 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1221 @opindex -=
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1222 @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 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	1225 multiplication (@code{*=}), and division (@code{/=}). An expression
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1226 of the form
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1227
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1228 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1229 @var{expr1} @var{op}= @var{expr2}
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1230 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1231
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1232 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1233 is evaluated as
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1234
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1235 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1236 @var{expr1} = (@var{expr1}) @var{op} (@var{expr2})
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1237 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1238
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1239 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1240 where @var{op} can be either @code{+}, @code{-}, @code{*}, or @code{/}.
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1241 So, the expression
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1242
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1243 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1244 a *= b+1
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1245 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1246
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1247 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1248 is evaluated as
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1249
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1250 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1251 a = a * (b+1)
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1252 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1253
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1254 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1255 and @emph{not}
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 = 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
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1261 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	1262 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	1263 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	1264 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	1265 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	1266
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1267 @cindex increment operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1268 @cindex decrement operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1269 @cindex operators, increment
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1270 @cindex operators, decrement
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1271
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	1272 @node Increment Ops
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1273 @section Increment Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1274
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1275 @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	1276 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	1277 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	1278 value.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1279
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1280 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	1281 @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	1282 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	1283 same as the expression @code{@var{x} = @var{x} + 1}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1284
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1285 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	1286 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	1287 @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	1288 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	1289 value of @var{x} is 3.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1290
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1291 For matrix and vector arguments, the increment and decrement operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1292 work on each element of the operand.
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 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	1295
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1296 @table @code
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1297 @item ++@var{x}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1298 @opindex ++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1299 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	1300 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	1301 expression @code{@var{x} = @var{x} + 1}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1302
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1303 @item --@var{x}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1304 @opindex @code{--}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1305 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	1306 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	1307 expression @code{@var{x} = @var{x} - 1}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1308
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1309 @item @var{x}++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1310 @opindex ++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1311 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	1312 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	1313
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1314 @item @var{x}--
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1315 @opindex @code{--}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1316 This expression causes the variable @var{x} to be decremented. The
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1317 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	1318 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1319
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	1320 @node Operator Precedence
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1321 @section Operator Precedence
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1322 @cindex operator precedence
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1323
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1324 @dfn{Operator precedence} determines how operators are grouped, when
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1325 different operators appear close by in one expression. For example,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1326 @samp{*} has higher precedence than @samp{+}. Thus, the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1327 @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	1328 @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	1329
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1330 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	1331 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	1332 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	1333 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	1334 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	1335 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	1336 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	1337 any such mistake.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1338
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1339 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	1340 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	1341 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	1342 @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	1343 @code{a = (b = c)}.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1344
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1345 The precedence of prefix unary operators is important when another
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1346 operator follows the operand. For example, @code{-x^2} means
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1347 @code{-(x^2)}, because @samp{-} has lower precedence than @samp{^}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1348
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1349 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	1350 precedence. Unless noted, all operators group left to right.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1351
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1352 @table @code
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1353 @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	1354 @samp{()} @samp{@{@}} @samp{.}
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1355
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1356 @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	1357 @samp{++} @samp{--}
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1358
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1359 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	1360
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1361 @item transpose and exponentiation
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1362 @samp{'} @samp{.'} @samp{^} @samp{} @samp{.^} @samp{.}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1363
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1364 @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	1365 @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	1366
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1367 @item multiply and divide
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1368 @samp{} @samp{/} @samp{\} @samp{.\} @samp{.} @samp{./}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1369
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1370 @item add, subtract
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1371 @samp{+} @samp{-}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1372
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1373 @item colon
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1374 @samp{:}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1375
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1376 @item relational
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1377 @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	1378 @samp{~=}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1379
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1380 @item element-wise "and"
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1381 @samp{&}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1382
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1383 @item element-wise "or"
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1384 @samp{\|}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1385
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1386 @item logical "and"
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1387 @samp{&&}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1388
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1389 @item logical "or"
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1390 @samp{\|\|}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1391
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1392 @item assignment
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1393 @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	1394 @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	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 These operators group right to left.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1398 @end table

Mercurial > hg > octave-lyh

annotate doc/interpreter/expr.txi @ 17483:bddb9688e41c