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

annotate doc/interpreter/expr.txi @ 31145:7c5cb8f8a21e

pagetranspose.m, pagectranspose.m: New functions for transposing the page (3-D) of an N-D array. * pagectranspose.m, pagetranspose.m: New functions. * scripts/general/module.mk: Add new functions to build system. * etc/NEWS.8.md: Announce new functions. * expr.txi: Add functions to Octave manual.

author	Rik <rik@octave.org>
date	Mon, 11 Jul 2022 22:38:57 -0700
parents	796f54d4ddbf
children

rev	line source
30569 796f54d4ddbf update Octave Project Developers copyright for the new year John W. Eaton <jwe@octave.org> parents: 30453 diff changeset	1 @c Copyright (C) 1996-2022 The Octave Project Developers
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
24534 194eb4bd202b maint: Update punctuation for GPL v3 license text. Rik <rik@octave.org> parents: 24510 diff changeset	5 @c Octave is free software: you can redistribute it and/or modify it
22755 3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22620 diff changeset	6 @c under the terms of the GNU General Public License as published by
24534 194eb4bd202b maint: Update punctuation for GPL v3 license text. Rik <rik@octave.org> parents: 24510 diff changeset	7 @c the Free Software Foundation, either version 3 of the License, or
22755 3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22620 diff changeset	8 @c (at your option) any later version.
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	9 @c
22755 3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22620 diff changeset	10 @c Octave is distributed in the hope that it will be useful, but
3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22620 diff changeset	11 @c WITHOUT ANY WARRANTY; without even the implied warranty of
3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22620 diff changeset	12 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22620 diff changeset	13 @c GNU General Public License for more details.
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	14 @c
7018 fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	15 @c You should have received a copy of the GNU General Public License
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7001 diff changeset	16 @c along with Octave; see the file COPYING. If not, see
24534 194eb4bd202b maint: Update punctuation for GPL v3 license text. Rik <rik@octave.org> parents: 24510 diff changeset	17 @c <https://www.gnu.org/licenses/>.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	18
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	19 @node Expressions
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	20 @chapter Expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	21 @cindex expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	22
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	23 Expressions are the basic building block of statements in Octave. An
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	24 expression evaluates to a value, which you can print, test, store in a
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	25 variable, pass to a function, or assign a new value to a variable with
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	26 an assignment operator.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	27
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	28 An expression can serve as a statement on its own. Most other kinds of
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	29 statements contain one or more expressions which specify data to be
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	30 operated on. As in other languages, expressions in Octave include
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	31 variables, array references, constants, and function calls, as well as
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	32 combinations of these with various operators.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	33
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	34 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	35 * Index Expressions::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	36 * Calling Functions::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	37 * Arithmetic Ops::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	38 * Comparison Ops::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	39 * Boolean Expressions::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	40 * Assignment Ops::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	41 * Increment Ops::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	42 * Operator Precedence::
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	43 @end menu
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	44
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	45 @node Index Expressions
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	46 @section Index Expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	47
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	48 @opindex (
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	49 @opindex )
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	50 @opindex :
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	51
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	52 An @dfn{index expression} allows you to reference or extract selected
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	53 elements of a vector, a matrix (2-D), or a higher-dimensional array.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	54
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	55 Indices may be scalars, vectors, ranges, or the special operator @samp{:},
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	56 which selects entire rows, columns, or higher-dimensional slices.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	57
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	58 An index expression consists of a set of parentheses enclosing @math{M}
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	59 expressions separated by commas. Each individual index value, or component,
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	60 is used for the respective dimension of the object that it is applied to. In
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	61 other words, the first index component is used for the first dimension (rows)
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	62 of the object, the second index component is used for the second dimension
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	63 (columns) of the object, and so on. The number of index components @math{M}
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	64 defines the dimensionality of the index expression. An index with two
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	65 components would be referred to as a 2-D index because it has two dimensions.
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	66
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	67 In the simplest case, 1) all components are scalars, and 2) the dimensionality
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	68 of the index expression @math{M} is equal to the dimensionality of the object
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	69 it is applied to. For example:
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	70
5679 297b82335c7b [project @ 2006-03-16 16:44:12 by jwe] jwe parents: 5016 diff changeset	71 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9159 diff changeset	72 @group
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	73 A = reshape (1:8, 2, 2, 2) # Create 3-D array
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	74 A =
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	75
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	76 ans(:,:,1) =
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	77
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	78 1 3
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	79 2 4
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	80
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	81 ans(:,:,2) =
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	82
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	83 5 7
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	84 6 8
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	85
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	86 A(2, 1, 2) # second row, first column of second slice
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	87 # in third dimension: ans = 6
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	88 @end group
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	89 @end example
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	90
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	91 The size of the returned object in a specific dimension is equal to the number
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	92 of elements in the corresponding component of the index expression. When all
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	93 components are scalars, the result is a single output value. However, if any
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	94 component is a vector or range then the returned values are the Cartesian
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	95 product of the indices in the respective dimensions. For example:
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	96
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	97 @example
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	98 @group
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	99 A([1, 2], 1, 2) @equiv{} [A(1,1,2); A(2,1,2)]
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	100 @result{}
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	101 ans =
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	102 5
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	103 6
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9159 diff changeset	104 @end group
5679 297b82335c7b [project @ 2006-03-16 16:44:12 by jwe] jwe parents: 5016 diff changeset	105 @end example
297b82335c7b [project @ 2006-03-16 16:44:12 by jwe] jwe parents: 5016 diff changeset	106
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	107 The total number of returned values is the product of the number of elements
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	108 returned for each index component. In the example above, the total is 211 =
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	109 2 elements.
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	110
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	111 Notice that the size of the returned object in a given dimension is equal to
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	112 the number of elements in the index expression for that dimension. In the code
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	113 above, the first index component (@code{[1, 2]}) was specified as a row vector,
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	114 but its shape is unimportant. The important fact is that the component
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	115 specified two values, and hence the result must have a size of two in the first
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	116 dimension; and because the first dimension corresponds to rows, the overall
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	117 result is a column vector.
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	118
5679 297b82335c7b [project @ 2006-03-16 16:44:12 by jwe] jwe parents: 5016 diff changeset	119 @example
14038 b0cdd60db5e5 doc: Grammarcheck documentation ahead of 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14033 diff changeset	120 @group
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	121 A(1, [2, 1, 1], 1) # result is a row vector: ans = [3, 1, 1]
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	122 A(ones (2, 2), 1, 1) # result is a column vector: ans = [1; 1; 1; 1]
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	123 @end group
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	124 @end example
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	125
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	126 The first line demonstrates again that the size of the output in a given
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	127 dimension is equal to the number of elements in the respective indexing
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	128 component. In this case, the output has three elements in the second dimension
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	129 (which corresponds to columns), so the result is a row vector. The example
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	130 also shows how repeating entries in the index expression can be used to
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	131 replicate elements in the output. The last example further proves that the
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	132 shape of the indexing component is irrelevant, it is only the number of
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	133 elements (2x2 = 4) which is important.
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	134
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	135 The above rules apply whenever the dimensionality of the index expression
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	136 is greater than one (@math{M > 1}). However, for one-dimensional index
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	137 expressions special rules apply and the shape of the output @strong{is}
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	138 determined by the shape of the indexing component. For example:
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	139
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	140 @example
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	141 @group
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	142 A([1, 2]) # result is a row vector: ans = [1, 2]
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	143 A([1; 2]) # result is a column vector: ans = [1; 2]
14038 b0cdd60db5e5 doc: Grammarcheck documentation ahead of 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14033 diff changeset	144 @end group
5679 297b82335c7b [project @ 2006-03-16 16:44:12 by jwe] jwe parents: 5016 diff changeset	145 @end example
297b82335c7b [project @ 2006-03-16 16:44:12 by jwe] jwe parents: 5016 diff changeset	146
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	147 Note that it is permissible to use a 1-D index with a multi-dimensional
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	148 object (also called linear indexing). In this case, the elements of the
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	149 multi-dimensional array are taken in column-first order like Fortran. That is,
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	150 the columns of the array are imagined to be stacked on top of each other to
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	151 form a column vector and then the single linear index is applied to this
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	152 vector.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	153
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	154 @example
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	155 @group
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	156 A(5) # linear indexing into three-dimensional array: ans = 5
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	157 A(3:5) # result has shape of index component: ans = [3, 4, 5]
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	158 @end group
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	159 @end example
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	160
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	161 @opindex :, indexing expressions
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	162
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	163 A colon (@samp{:}) may be used as an index component to select all of the
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	164 elements in a specified dimension. Given the matrix,
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	165
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	166 @example
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	167 A = [1, 2; 3, 4]
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	168 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	169
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	170 @noindent
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	171 all of the following expressions are equivalent and select the first row of the
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	172 matrix.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	173
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	174 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	175 @group
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	176 A(1, [1, 2]) # row 1, columns 1 and 2
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	177 A(1, 1:2) # row 1, columns in range 1-2
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	178 A(1, :) # row 1, all columns
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	179 @end group
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	180 @end example
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	181
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	182 When a colon is used in the special case of 1-D indexing the result is always a
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	183 column vector. Creating column vectors with a colon index is a very frequently
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	184 encountered code idiom and is faster and generally clearer than calling
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	185 @code{reshape} for this case.
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	186
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	187 @example
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	188 @group
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	189 A(:) # result is column vector: ans = [1; 2; 3; 4]
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	190 A(:)' # result is row vector: ans = [1, 2, 3, 4]
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	191 @end group
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	192 @end example
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	193
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	194 @cindex @code{end}, indexing
24507 dc25a0dc7800 Correct a host of small formatting issues with Texinfo manual (bug #52774) Daniel J Sebald <daniel.sebald@ieee.org> parents: 24469 diff changeset	195 @cindex @sortas{end:} @code{end:} and @code{:end}
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	196
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	197 In index expressions the keyword @code{end} automatically refers to the last
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	198 entry for a particular dimension. This magic index can also be used in ranges
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	199 and typically eliminates the needs to call @code{size} or @code{length} to
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	200 gather array bounds before indexing. For example:
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	201
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	202 @example
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	203 @group
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	204 A(1:end/2) # first half of A => [1, 2]
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	205 A(end + 1) = 5; # append element
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	206 A(end) = []; # delete element
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	207 A(1:2:end) # odd elements of A => [1, 3]
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	208 A(2:2:end) # even elements of A => [2, 4]
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	209 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	210 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	211 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	212
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	213 @menu
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	214 * Advanced Indexing::
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	215 @end menu
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	216
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	217 @node Advanced Indexing
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	218 @subsection Advanced Indexing
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	219
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	220 When it is necessary to extract subsets of entries out of an array whose
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	221 indices cannot be written as a Cartesian product of components, linear
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	222 indexing together with the function @code{sub2ind} can be used. For example:
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	223
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	224 @example
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	225 @group
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	226 A = reshape (1:8, 2, 2, 2) # Create 3-D array
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	227 A =
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	228
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	229 ans(:,:,1) =
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	230
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	231 1 3
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	232 2 4
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	233
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	234 ans(:,:,2) =
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	235
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	236 5 7
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	237 6 8
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	238
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	239 A(sub2ind (size (A), [1, 2, 1], [1, 1, 2], [1, 2, 1]))
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	240 @result{} ans = [A(1, 1, 1), A(2, 1, 2), A(1, 2, 1)]
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	241 @end group
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	242 @end example
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	243
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	244 An array with @samp{nd} dimensions can be indexed by an index expression which
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	245 has from 1 to @samp{nd} components. For the ordinary and most common case, the
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	246 number of components @samp{M} matches the number of dimensions @samp{nd}. In
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	247 this case the ordinary indexing rules apply and each component corresponds to
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	248 the respective dimension of the array.
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	249
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	250 However, if the number of indexing components exceeds the number of dimensions
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	251 (@w{@code{M > nd}}) then the excess components must all be singletons
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	252 (@code{1}). Moreover, if @w{@code{M < nd}}, the behavior is equivalent to
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	253 reshaping the input object so as to merge the trailing @w{@code{nd - M}}
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	254 dimensions into the last index dimension @code{M}. Thus, the result will have
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	255 the dimensionality of the index expression, and not the original object. This
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	256 is the case whenever dimensionality of the index is greater than one
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	257 (@w{@code{M > 1}}), so that the special rules for linear indexing are not
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	258 applied. This is easiest to understand with an example:
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	259
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	260 @example
24468 abe0b0e08897 doc: Rewrite documentation for Advanced Indexing (bug #52723). Rik <rik@octave.org> parents: 24454 diff changeset	261 A = reshape (1:8, 2, 2, 2) # Create 3-D array
abe0b0e08897 doc: Rewrite documentation for Advanced Indexing (bug #52723). Rik <rik@octave.org> parents: 24454 diff changeset	262 A =
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	263
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	264 ans(:,:,1) =
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	265
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	266 1 3
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	267 2 4
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	268
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	269 ans(:,:,2) =
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	270
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	271 5 7
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	272 6 8
9159 c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	273
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	274 ## 2-D indexing causes third dimension to be merged into second dimension.
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	275 ## Equivalent array for indexing, Atmp, is now 2x4.
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	276 Atmp = reshape (A, 2, 4)
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	277 Atmp =
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	278
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	279 1 3 5 7
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	280 2 4 6 8
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	281
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	282
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	283 A(2,1) # Reshape to 2x4 matrix, second entry of first column: ans = 2
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	284 A(2,4) # Reshape to 2x4 matrix, second entry of fourth column: ans = 8
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	285 A(:,:) # Reshape to 2x4 matrix, select all rows & columns, ans = Atmp
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	286 @end example
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	287
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	288 @noindent
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	289 Note here the elegant use of the double colon to replace the call to the
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	290 @code{reshape} function.
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	291
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	292 Another advanced use of linear indexing is to create arrays filled with a
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	293 single value. This can be done by using an index of ones on a scalar value.
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	294 The result is an object with the dimensions of the index expression and every
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	295 element equal to the original scalar. For example, the following statements
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	296
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	297 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	298 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	299 a = 13;
12546 39ca02387a32 Improve docstrings for a number of functions. Rik <octave@nomad.inbox5.com> parents: 12544 diff changeset	300 a(ones (1, 4))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	301 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	302 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	303
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	304 @noindent
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	305 produce a row vector whose four elements are all equal to 13.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	306
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	307 Similarly, by indexing a scalar with two vectors of ones it is possible to
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	308 create a matrix. The following statements
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	309
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	310 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	311 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	312 a = 13;
12546 39ca02387a32 Improve docstrings for a number of functions. Rik <octave@nomad.inbox5.com> parents: 12544 diff changeset	313 a(ones (1, 2), ones (1, 3))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	314 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	315 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	316
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	317 @noindent
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	318 create a 2x3 matrix with all elements equal to 13. This could also have been
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	319 written as
9159 c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	320
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	321 @example
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	322 13(ones (2, 3))
9159 c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	323 @end example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	324
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	325 It is more efficient to use indexing rather than the code construction
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	326 @code{scalar * ones (M, N, @dots{})} because it avoids the unnecessary
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	327 multiplication operation. Moreover, multiplication may not be defined for the
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	328 object to be replicated whereas indexing an array is always defined. The
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	329 following code shows how to create a 2x3 cell array from a base unit which is
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	330 not itself a scalar.
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	331
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	332 @example
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	333 @group
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	334 @{"Hello"@}(ones (2, 3))
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	335 @end group
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	336 @end example
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	337
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	338 It should be noted that @code{ones (1, n)} (a row vector of ones) results in a
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	339 range object (with zero increment). A range is stored internally as a starting
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	340 value, increment, end value, and total number of values; hence, it is more
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	341 efficient for storage than a vector or matrix of ones whenever the number of
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	342 elements is greater than 4. In particular, when @samp{r} is a row vector, the
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	343 expressions
9159 c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	344
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	345 @example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	346 r(ones (1, n), :)
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	347 @end example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	348
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	349 @example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	350 r(ones (n, 1), :)
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	351 @end example
c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	352
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	353 @noindent
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	354 will produce identical results, but the first one will be significantly faster,
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	355 at least for @samp{r} and @samp{n} large enough. In the first case the index
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	356 is held in compressed form as a range which allows Octave to choose a more
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	357 efficient algorithm to handle the expression.
9159 c07cbffb82e3 update indexing docs Jaroslav Hajek <highegg@gmail.com> parents: 9153 diff changeset	358
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	359 A general recommendation for users unfamiliar with these techniques is to use
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	360 the function @code{repmat} for replicating smaller arrays into bigger ones,
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	361 which uses such tricks.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	362
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	363 A second use of indexing is to speed up code. Indexing is a fast operation and
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	364 judicious use of it can reduce the requirement for looping over individual
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	365 array elements, which is a slow operation.
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	366
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	367 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	368 @math{a} containing the values
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	369 @tex
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	370 $a_i = \sqrt{i}$.
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	371 @end tex
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	372 @ifnottex
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14171 diff changeset	373 a(i) = sqrt (i).
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	374 @end ifnottex
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	375
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	376 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9159 diff changeset	377 @group
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	378 for i = 1:10
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	379 a(i) = sqrt (i);
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	380 endfor
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9159 diff changeset	381 @end group
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	382 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	383
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	384 @noindent
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	385 It is quite inefficient to create a vector using a loop like this. In this
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	386 case, it would have been much more efficient to use the expression
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	387
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	388 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	389 a = sqrt (1:10);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	390 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	391
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	392 @noindent
14033 dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	393 which avoids the loop entirely.
dfbf6a49847c doc: Update documentation on indexing expressions Rik <octave@nomad.inbox5.com> parents: 13780 diff changeset	394
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	395 In cases where a loop cannot be avoided, or a number of values must be combined
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	396 to form a larger matrix, it is generally faster to set the size of the matrix
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	397 first (pre-allocate storage), and then insert elements using indexing commands.
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	398 For example, given a matrix @code{a},
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	399
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	400 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	401 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	402 [nr, nc] = size (a);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	403 x = zeros (nr, n * nc);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	404 for i = 1:n
3602 83889344cbef [project @ 2000-02-25 08:52:20 by jwe] jwe parents: 3428 diff changeset	405 x(:,(i-1)nc+1:inc) = a;
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	406 endfor
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	407 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	408 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	409
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	410 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	411 is considerably faster than
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	412
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	413 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	414 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	415 x = a;
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	416 for i = 1:n-1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	417 x = [x, a];
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	418 endfor
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	419 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	420 @end example
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 @noindent
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	423 because Octave does not have to repeatedly resize the intermediate result.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	424
6549 5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 6501 diff changeset	425 @DOCSTRING(sub2ind)
5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 6501 diff changeset	426
5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 6501 diff changeset	427 @DOCSTRING(ind2sub)
5a5a09d7deb8 [project @ 2007-04-20 06:55:29 by jwe] jwe parents: 6501 diff changeset	428
11431 0d9640d755b1 Improve docstrings for all isXXX functions. Rik <octave@nomad.inbox5.com> parents: 11403 diff changeset	429 @DOCSTRING(isindex)
0d9640d755b1 Improve docstrings for all isXXX functions. Rik <octave@nomad.inbox5.com> parents: 11403 diff changeset	430
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	431 @node Calling Functions
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	432 @section Calling Functions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	433
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	434 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	435 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	436 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	437
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	438 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	439 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	440 these. In addition, you can define your own functions.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	441 @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	442
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	443 @cindex arguments in function call
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	444 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	445 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	446 @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	447 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	448 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	449 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	450 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	451 intended. Here are some examples:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	452
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	453 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	454 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	455 sqrt (x^2 + y^2) # @r{One argument}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	456 ones (n, m) # @r{Two arguments}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	457 rand () # @r{No arguments}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	458 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	459 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	460
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	461 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	462 @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	463 to take the square root of:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	464
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	465 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	466 sqrt (@var{argument})
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	467 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	468
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	469 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	470 depending on the particular usage, and their behavior is different
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	471 depending on the number of arguments supplied.
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 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	474 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	475 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	476 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	477 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	478
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	479 Unlike most languages, functions in Octave may return multiple values.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	480 For example, the following statement
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	481
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	482 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	483 [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	484 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	485
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	486 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	487 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	488 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	489
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	490 The left side of a multiple assignment expression is itself a list of
25352 3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	491 expressions, that is, a list of variable names potentially qualified by
3d5f953e2ef6 doc: Rewrite section on indexing for clarity (bug #53675). Rik <rik@octave.org> parents: 25054 diff changeset	492 index expressions. See also @ref{Index Expressions}, and @ref{Assignment Ops}.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	493
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	494 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	495 * Call by Value::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	496 * Recursion::
24510 a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	497 * Access via Handle::
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	498 @end menu
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	499
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	500 @node Call by Value
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	501 @subsection Call by Value
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	502
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	503 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	504 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	505 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	506 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	507 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	508 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	509 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	510 body. For example, the function
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	511
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	512 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	513 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	514 function f (x, n)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	515 while (n-- > 0)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	516 disp (x);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	517 endwhile
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	518 endfunction
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	519 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	520 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	521
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	522 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	523 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	524 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	525 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	526 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	527 pass constants for any function parameter without first having to
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	528 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	529
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	530 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	531 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	532 argument had. For example, given a function called as
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 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	535 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	536 foo = "bar";
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	537 fcn (foo)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	538 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	539 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	540
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	541 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	542 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	543 @code{foo}.'' Instead, think of the argument as the string value,
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17170 diff changeset	544 @qcode{"bar"}.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	545
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	546 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	547 values are not copied unnecessarily. For example,
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 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	550 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	551 x = rand (1000);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	552 f (x);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	553 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	554 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	555
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	556 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	557 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	558 @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	559 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	560 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	561 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	562 temporary result.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	563
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	564 @node Recursion
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	565 @subsection Recursion
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	566 @cindex factorial function
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	567
6939 46d1ad37d943 [project @ 2007-10-01 16:12:20 by jwe] jwe parents: 6778 diff changeset	568 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	569 implemented in terms of functions that cannot be called recursively.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	570 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	571 Fortran subroutine that cannot be called recursively, so @code{lsode}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	572 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	573 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	574 in an error.}, recursive function calls are allowed. A
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	575 @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	576 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	577 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	578 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	579 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	580
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	581 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	582 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	583 function retval = fact (n)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	584 if (n > 0)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	585 retval = n * fact (n-1);
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	586 else
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	587 retval = 1;
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	588 endif
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	589 endfunction
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	590 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	591 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	592
24510 a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	593 @noindent
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	594 This function is recursive because it calls itself directly. It
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	595 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	596 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	597 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	598 the recursion ends.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	599
28657 bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 27980 diff changeset	600 The function @code{max_recursion_depth} may be used to specify a limit
bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 27980 diff changeset	601 to the recursion depth and prevents Octave from recursing infinitely.
bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 27980 diff changeset	602 Similarly, the function @code{max_stack_depth} may be used to specify
bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 27980 diff changeset	603 limit to the depth of function calls, whether recursive or not. These
bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 27980 diff changeset	604 limits help prevent stack overflow on the computer Octave is running on,
bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 27980 diff changeset	605 so that instead of exiting with a signal, the interpreter will throw an
bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 27980 diff changeset	606 error and return to the command prompt.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	607
3371 86873384cd10 [project @ 1999-11-21 17:31:07 by jwe] jwe parents: 3294 diff changeset	608 @DOCSTRING(max_recursion_depth)
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	609
24855 41f80b9af274 prevent stack overflow crash on deeply nested function calls (bug #47620) John W. Eaton <jwe@octave.org> parents: 24691 diff changeset	610 @DOCSTRING(max_stack_depth)
41f80b9af274 prevent stack overflow crash on deeply nested function calls (bug #47620) John W. Eaton <jwe@octave.org> parents: 24691 diff changeset	611
24510 a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	612 @node Access via Handle
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	613 @subsection Access via Handle
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	614 @cindex function handle
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	615 @cindex indirect function call
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	616
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	617 @opindex @@ function handle
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	618 A function may be abstracted and referenced via a function handle acquired
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	619 using the special operator @samp{@@}. For example,
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	620
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	621 @example
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	622 @group
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	623 f = @@plus;
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	624 f (2, 2)
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	625 @result{} 4
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	626 @end group
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	627 @end example
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	628
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	629 @noindent
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	630 is equivalent to calling @code{plus (2, 2)} directly. Beyond abstraction for
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	631 general programming, function handles find use in callback methods for figures
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	632 and graphics by adding listeners to properties or assigning pre-existing
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	633 actions, such as in the following example:
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	634
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	635 @cindex figure deletefcn
24987 a895967fd5a7 doc: grammarcheck manual (.txi) ahead of 4.4 release. Rik <rik@octave.org>* parents: 24855 diff changeset	636
24510 a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	637 @example
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	638 @group
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	639 function mydeletefcn (h, ~, msg)
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	640 printf (msg);
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	641 endfunction
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	642 sombrero;
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	643 set (gcf, "deletefcn", @{@@mydeletefcn, "Bye!\n"@});
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	644 close;
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	645 @end group
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	646 @end example
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	647
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	648 @noindent
24987 a895967fd5a7 doc: grammarcheck manual (.txi) ahead of 4.4 release. Rik <rik@octave.org>* parents: 24855 diff changeset	649 The above will print @qcode{"Bye!"} to the terminal upon the closing
a895967fd5a7 doc: grammarcheck manual (.txi) ahead of 4.4 release. Rik <rik@octave.org>* parents: 24855 diff changeset	650 (deleting) of the figure. There are many graphics property actions for which
a895967fd5a7 doc: grammarcheck manual (.txi) ahead of 4.4 release. Rik <rik@octave.org>* parents: 24855 diff changeset	651 a callback function may be assigned, including, @code{buttondownfcn},
a895967fd5a7 doc: grammarcheck manual (.txi) ahead of 4.4 release. Rik <rik@octave.org>* parents: 24855 diff changeset	652 @code{windowscrollwheelfcn}, @code{createfcn}, @code{deletefcn},
a895967fd5a7 doc: grammarcheck manual (.txi) ahead of 4.4 release. Rik <rik@octave.org>* parents: 24855 diff changeset	653 @code{keypressfcn}, etc.
24510 a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	654
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	655 Note that the @samp{@@} character also plays a role in defining class
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	656 functions, i.e., methods, but not as a syntactical element. Rather it begins a
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	657 directory name containing methods for a class that shares the directory name
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	658 sans the @samp{@@} character. See @ref{Object Oriented Programming}.
a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24507 diff changeset	659
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	660 @node Arithmetic Ops
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	661 @section Arithmetic Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	662 @cindex arithmetic operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	663 @cindex operators, arithmetic
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	664 @cindex addition
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	665 @cindex subtraction
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	666 @cindex multiplication
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	667 @cindex matrix multiplication
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	668 @cindex division
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	669 @cindex quotient
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	670 @cindex negation
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	671 @cindex unary minus
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	672 @cindex exponentiation
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	673 @cindex transpose
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	674 @cindex Hermitian operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	675 @cindex transpose, complex-conjugate
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	676 @cindex complex-conjugate transpose
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	677
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	678 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	679 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	680 (@pxref{Broadcasting}).
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	681
13780 990762e784fe Fix confusing interaction between @code macro and transpose operator (') in documentation (Bug #34661). Rik <octave@nomad.inbox5.com> parents: 12627 diff changeset	682 @table @asis
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	683 @item @var{x} + @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	684 @opindex +
30332 256fad4ac653 eiminate .+ and .- from documentation John W. Eaton <jwe@octave.org> parents: 30326 diff changeset	685 Addition (always works element by element). If both operands are
256fad4ac653 eiminate .+ and .- from documentation John W. Eaton <jwe@octave.org> parents: 30326 diff changeset	686 matrices, the number of rows and columns must both agree, or they must
256fad4ac653 eiminate .+ and .- from documentation John W. Eaton <jwe@octave.org> parents: 30326 diff changeset	687 be broadcastable to the same shape.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	688
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	689 @item @var{x} - @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	690 @opindex -
30332 256fad4ac653 eiminate .+ and .- from documentation John W. Eaton <jwe@octave.org> parents: 30326 diff changeset	691 Subtraction (always works element by element). If both operands are
256fad4ac653 eiminate .+ and .- from documentation John W. Eaton <jwe@octave.org> parents: 30326 diff changeset	692 matrices, the number of rows and columns of both must agree, or they
256fad4ac653 eiminate .+ and .- from documentation John W. Eaton <jwe@octave.org> parents: 30326 diff changeset	693 must be broadcastable to the same shape.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	694
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	695 @item @var{x} * @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	696 @opindex *
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	697 Matrix multiplication. The number of columns of @var{x} must agree with
24454 b9d482dd90f3 doc: Fix mistaken use of space between function and '(' in documentation (bug #52723). Rik <rik@octave.org> parents: 23219 diff changeset	698 the number of rows of @var{y}.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	699
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	700 @item @var{x} .* @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	701 @opindex .*
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	702 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	703 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	704 broadcastable to the same shape.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	705
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	706 @item @var{x} / @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	707 @opindex /
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	708 Right division. This is conceptually equivalent to the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	709
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	710 @example
27257 7f5008aec7a1 doc: Add function index entry for alias "inverse" bug #56629). Rik <rik@octave.org> parents: 26379 diff changeset	711 (inv (y') * x')'
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	712 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	713
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	714 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	715 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	716
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	717 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	718 a minimum norm solution is computed.
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 @item @var{x} ./ @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	721 @opindex ./
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	722 Element-by-element right division.
3294 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 @item @var{x} \ @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	725 @opindex \
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	726 Left division. This is conceptually equivalent to the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	727
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	728 @example
27257 7f5008aec7a1 doc: Add function index entry for alias "inverse" bug #56629). Rik <rik@octave.org> parents: 26379 diff changeset	729 inv (x) * y
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	730 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	731
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	732 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	733 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	734
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	735 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	736 a minimum norm solution is computed.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	737
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	738 @item @var{x} .\ @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	739 @opindex .\
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	740 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	741 by each corresponding element of @var{x}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	742
17170 d6499c14021c doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 17152 diff changeset	743 @item @var{x} ^ @var{y}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	744 @opindex ^
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	745 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	746 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	747 @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	748 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	749 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	750 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	751 @var{x} and @var{y} are matrices.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	752
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	753 The implementation of this operator needs to be improved.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	754
17170 d6499c14021c doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 17152 diff changeset	755 @item @var{x} .^ @var{y}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	756 @opindex .^
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	757 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	758 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	759 broadcastable to the same shape. If several complex results are
2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	760 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	761 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	762 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	763 real result is preferred.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	764
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	765 @item -@var{x}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	766 @opindex -
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	767 Negation.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	768
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	769 @item +@var{x}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	770 @opindex +
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	771 Unary plus. This operator has no effect on the operand.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	772
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	773 @item @var{x}'
24550 966c3283a164 doc: Fix appearance of '.' and "'" in Operator Index (bug #52813). Rik <rik@octave.org> parents: 24534 diff changeset	774 @opindex @code{'}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	775 Complex conjugate transpose. For real arguments, this operator is the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	776 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	777 equivalent to the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	778
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	779 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	780 conj (x.')
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	781 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	782
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	783 @item @var{x}.'
24550 966c3283a164 doc: Fix appearance of '.' and "'" in Operator Index (bug #52813). Rik <rik@octave.org> parents: 24534 diff changeset	784 @opindex @code{.'}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	785 Transpose.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	786 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	787
14171 2ced2f59f523 doc: miscellaneous documentation improvements Rik <octave@nomad.inbox5.com> parents: 14169 diff changeset	788 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	789 @samp{.}, there is a possible ambiguity for statements like
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	790
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	791 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	792 1./m
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	793 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	794
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	795 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	796 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	797 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	798 expression as if you had typed
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	799
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	800 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	801 (1) ./ m
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	802 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	803
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	804 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	805 and not
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	806
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	807 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	808 (1.) / m
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	809 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	810
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	811 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	812 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	813 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	814 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	815 useful in this case.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	816
24550 966c3283a164 doc: Fix appearance of '.' and "'" in Operator Index (bug #52813). Rik <rik@octave.org> parents: 24534 diff changeset	817 @opindex @code{'}
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	818 @DOCSTRING(ctranspose)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	819
31145 7c5cb8f8a21e pagetranspose.m, pagectranspose.m: New functions for transposing the page (3-D) of an N-D array. Rik <rik@octave.org> parents: 30569 diff changeset	820 @DOCSTRING(pagectranspose)
7c5cb8f8a21e pagetranspose.m, pagectranspose.m: New functions for transposing the page (3-D) of an N-D array. Rik <rik@octave.org> parents: 30569 diff changeset	821
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	822 @opindex .\
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	823 @DOCSTRING(ldivide)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	824
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	825 @opindex -
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	826 @DOCSTRING(minus)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	827
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	828 @opindex \
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	829 @DOCSTRING(mldivide)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	830
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	831 @opindex ^
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	832 @DOCSTRING(mpower)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	833
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	834 @opindex /
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	835 @DOCSTRING(mrdivide)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	836
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	837 @opindex *
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	838 @DOCSTRING(mtimes)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	839
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	840 @opindex +
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	841 @DOCSTRING(plus)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	842
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	843 @opindex .^
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	844 @DOCSTRING(power)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	845
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	846 @opindex ./
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	847 @DOCSTRING(rdivide)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	848
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	849 @opindex .*
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	850 @DOCSTRING(times)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	851
24550 966c3283a164 doc: Fix appearance of '.' and "'" in Operator Index (bug #52813). Rik <rik@octave.org> parents: 24534 diff changeset	852 @opindex @code{.'}
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	853 @DOCSTRING(transpose)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	854
31145 7c5cb8f8a21e pagetranspose.m, pagectranspose.m: New functions for transposing the page (3-D) of an N-D array. Rik <rik@octave.org> parents: 30569 diff changeset	855 @DOCSTRING(pagetranspose)
7c5cb8f8a21e pagetranspose.m, pagectranspose.m: New functions for transposing the page (3-D) of an N-D array. Rik <rik@octave.org> parents: 30569 diff changeset	856
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	857 @opindex -
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	858 @DOCSTRING(uminus)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	859
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	860 @opindex +
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	861 @DOCSTRING(uplus)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	862
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	863 @node Comparison Ops
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	864 @section Comparison Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	865 @cindex comparison expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	866 @cindex expressions, comparison
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	867 @cindex relational operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	868 @cindex operators, relational
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	869 @cindex less than operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	870 @cindex greater than operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	871 @cindex equality operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	872 @cindex tests for equality
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	873 @cindex equality, tests for
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	874
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	875 @dfn{Comparison operators} compare numeric values for relationships
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	876 such as equality. They are written using
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	877 @emph{relational operators}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	878
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	879 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	880 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	881 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	882 @xref{Broadcasting}. For example:
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	883
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	884 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	885 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	886 [1, 2; 3, 4] == [1, 3; 2, 4]
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	887 @result{} 1 0
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	888 0 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	889 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	890 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	891
14116 951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 14038 diff changeset	892 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	893 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	894 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	895
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	896 @table @code
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	897 @item @var{x} < @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	898 @opindex <
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	899 True if @var{x} is less than @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	900
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	901 @item @var{x} <= @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	902 @opindex <=
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	903 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	904
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	905 @item @var{x} == @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	906 @opindex ==
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	907 True if @var{x} is equal to @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	908
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	909 @item @var{x} >= @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	910 @opindex >=
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	911 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	912
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	913 @item @var{x} > @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	914 @opindex >
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	915 True if @var{x} is greater than @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	916
17170 d6499c14021c doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 17152 diff changeset	917 @item @var{x} != @var{y}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	918 @itemx @var{x} ~= @var{y}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	919 @opindex !=
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	920 @opindex ~=
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	921 True if @var{x} is not equal to @var{y}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	922 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	923
9578 7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	924 For complex numbers, the following ordering is defined:
7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	925 @var{z1} < @var{z2}
16826 a4969508008e doc: Periodic spellcheck of the documentation. Rik <rik@octave.org> parents: 14856 diff changeset	926 if and only if
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	927
9578 7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	928 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9578 diff changeset	929 @group
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	930 abs (@var{z1}) < abs (@var{z2})
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14171 diff changeset	931 \|\| (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	932 @end group
9578 7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	933 @end example
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	934
322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10711 diff changeset	935 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	936 @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	937 parts.
9578 7dafdb8b062f refactor comparison ops implementations Jaroslav Hajek <highegg@gmail.com> parents: 9245 diff changeset	938
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	939 String comparisons may also be performed with the @code{strcmp}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	940 function, not with the comparison operators listed above.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	941 @xref{Strings}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	942
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	943 @opindex ==
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	944 @DOCSTRING(eq)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	945
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	946 @opindex >=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	947 @DOCSTRING(ge)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	948
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	949 @opindex >
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	950 @DOCSTRING(gt)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	951
6550 1b7a6061a05d [project @ 2007-04-20 07:40:26 by jwe] jwe parents: 6549 diff changeset	952 @DOCSTRING(isequal)
1b7a6061a05d [project @ 2007-04-20 07:40:26 by jwe] jwe parents: 6549 diff changeset	953
16935 a7b2fc7fe1a9 binocdf.m: Reverse calling convention to betaincinv to preserve accuracy when p =~ 1. Rik <rik@octave.org> parents: 16826 diff changeset	954 @DOCSTRING(isequaln)
6550 1b7a6061a05d [project @ 2007-04-20 07:40:26 by jwe] jwe parents: 6549 diff changeset	955
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	956 @opindex <=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	957 @DOCSTRING(le)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	958
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	959 @opindex <
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	960 @DOCSTRING(lt)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	961
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	962 @opindex !=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	963 @opindex ~=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	964 @DOCSTRING(ne)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	965
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	966 @node Boolean Expressions
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	967 @section Boolean Expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	968 @cindex expressions, boolean
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	969 @cindex boolean expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	970 @cindex expressions, logical
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	971 @cindex logical expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	972 @cindex operators, boolean
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	973 @cindex boolean operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	974 @cindex logical operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	975 @cindex operators, logical
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	976 @cindex and operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	977 @cindex or operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	978 @cindex not operator
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 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	981 * Element-by-element Boolean Operators::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 16935 diff changeset	982 * Short-circuit Boolean Operators::
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	983 @end menu
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	984
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	985 @node Element-by-element Boolean Operators
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	986 @subsection Element-by-element Boolean Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	987 @cindex element-by-element evaluation
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	988
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	989 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	990 comparison expressions using the boolean
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	991 operators ``or'' (@samp{\|}), ``and'' (@samp{&}), and ``not'' (@samp{!}),
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	992 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	993 expression is computed by combining the truth values of the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	994 corresponding elements of the component expressions. A value is
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	995 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	996
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	997 Element-by-element boolean expressions can be used wherever comparison
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	998 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	999 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	1000 @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	1001 elements are nonzero.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1002
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1003 Like comparison operations, each element of an element-by-element
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1004 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	1005 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	1006 variable, or used in arithmetic.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1007
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1008 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	1009
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1010 @table @code
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1011 @item @var{boolean1} & @var{boolean2}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1012 @opindex &
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1013 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	1014 @var{boolean1} and @var{boolean2} are true.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1015
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1016 @item @var{boolean1} \| @var{boolean2}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1017 @opindex \|
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1018 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	1019 of @var{boolean1} or @var{boolean2} is true.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1020
17170 d6499c14021c doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 17152 diff changeset	1021 @item ! @var{boolean}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1022 @itemx ~ @var{boolean}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1023 @opindex ~
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1024 @opindex !
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1025 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	1026 @var{boolean} is false.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1027 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1028
14119 94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14116 diff changeset	1029 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	1030 expression
3294 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 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1033 [1, 0; 0, 1] & [1, 0; 2, 3]
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1034 @end example
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 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1037 returns a two by two identity matrix.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1038
14119 94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 14116 diff changeset	1039 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	1040 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	1041 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	1042 matrix.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1043
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1044 For the binary element-by-element boolean operators, both subexpressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1045 @var{boolean1} and @var{boolean2} are evaluated before computing the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1046 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	1047 effects. For example, in the expression
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 a & b++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1051 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1052
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1053 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1054 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	1055 @var{a} is zero.
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 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	1058 described for matrix-valued operands.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1059
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	1060 @opindex &
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	1061 @DOCSTRING(and)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	1062
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	1063 @opindex ~
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	1064 @opindex !
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	1065 @DOCSTRING(not)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	1066
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	1067 @opindex \|
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	1068 @DOCSTRING(or)
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 10846 diff changeset	1069
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	1070 @node Short-circuit Boolean Operators
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1071 @subsection Short-circuit Boolean Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1072 @cindex short-circuit evaluation
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1073
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1074 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	1075 @code{while} conditions, Octave's element-by-element boolean operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1076 are often sufficient for performing most logical operations. However,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1077 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	1078 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	1079 @dfn{short-circuit} boolean operators work this way.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1080
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1081 @table @code
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1082 @item @var{boolean1} && @var{boolean2}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1083 @opindex &&
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1084 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	1085 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	1086 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	1087 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	1088 scalar using the equivalent of the operation @code{all
20659 4a82f565a669 doc: Fix typo in short-circuit operators documentation (bug #46280). Rik <rik@octave.org> parents: 19697 diff changeset	1089 (@var{boolean2}(:))}. If it is true, the result of the overall expression
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1090 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	1091
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1092 @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	1093 @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	1094 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	1095 so @code{[] && true} evaluates to @code{false} even though
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1096 @code{all ([])} is @code{true}.
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1097
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1098 @item @var{boolean1} \|\| @var{boolean2}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1099 @opindex \|\|
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1100 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	1101 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	1102 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	1103 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	1104 scalar using the equivalent of the operation @code{all
20659 4a82f565a669 doc: Fix typo in short-circuit operators documentation (bug #46280). Rik <rik@octave.org> parents: 19697 diff changeset	1105 (@var{boolean2}(:))}. If it is true, the result of the overall expression
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1106 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	1107
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1108 @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	1109 see the previous list item for details.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1110 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1111
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1112 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	1113 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	1114 the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1115
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1116 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1117 a && b++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1118 @end example
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 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1121 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	1122 @var{a} is nonzero.
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 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	1125 is possible write
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 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1128 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1129 function f (a, b, c)
7768 a2d9f325b65a Use isschar instead of deprecated isstr Rafael Laboissiere <rafael@debian.org> parents: 7594 diff changeset	1130 if (nargin > 2 && ischar (c))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1131 @dots{}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1132 @end group
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 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	1137 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	1138 short-circuit feature, it would be necessary to write
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 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1141 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1142 function f (a, b, c)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1143 if (nargin > 2)
7768 a2d9f325b65a Use isschar instead of deprecated isstr Rafael Laboissiere <rafael@debian.org> parents: 7594 diff changeset	1144 if (ischar (c))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1145 @dots{}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1146 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1147 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1148
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1149 @noindent
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1150 Writing
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1151
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1152 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1153 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1154 function f (a, b, c)
7768 a2d9f325b65a Use isschar instead of deprecated isstr Rafael Laboissiere <rafael@debian.org> parents: 7594 diff changeset	1155 if (nargin > 2 & ischar (c))
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1156 @dots{}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1157 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1158 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1159
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1160 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1161 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	1162 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	1163 operands for the operator @samp{&}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1164
12543 f60f755ebfe4 Add do_braindead_shortcircuit_evaluation to documentation. Rik <octave@nomad.inbox5.com> parents: 11552 diff changeset	1165 @sc{matlab} has special behavior that allows the operators @samp{&} and
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	1166 @samp{\|} to short-circuit when used in the truth expression for @code{if} and
22620 74fb14727a30 doc: Remove DOCSTRING references to non-existent functions (bug #49329). Rik <rik@octave.org> parents: 22323 diff changeset	1167 @code{while} statements. Octave behaves the same way for compatibility,
74fb14727a30 doc: Remove DOCSTRING references to non-existent functions (bug #49329). Rik <rik@octave.org> parents: 22323 diff changeset	1168 however, the use of the @samp{&} and @samp{\|} operators in this way is
74fb14727a30 doc: Remove DOCSTRING references to non-existent functions (bug #49329). Rik <rik@octave.org> parents: 22323 diff changeset	1169 strongly discouraged and a warning will be issued. Instead, you should use
74fb14727a30 doc: Remove DOCSTRING references to non-existent functions (bug #49329). Rik <rik@octave.org> parents: 22323 diff changeset	1170 the @samp{&&} and @samp{\|\|} operators that always have short-circuit behavior.
20745 c4f79fc9281a doc: Resolve two undocumented functions in manual. Rik <rik@octave.org> parents: 20659 diff changeset	1171
12543 f60f755ebfe4 Add do_braindead_shortcircuit_evaluation to documentation. Rik <octave@nomad.inbox5.com> parents: 11552 diff changeset	1172 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	1173 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	1174 function.
10308 0d928dd9eeb8 extend parseparams Jaroslav Hajek <highegg@gmail.com> parents: 10228 diff changeset	1175
11552 6b6e9051ecb8 Add merge/ifelse function to documentation. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	1176 @DOCSTRING(merge)
10308 0d928dd9eeb8 extend parseparams Jaroslav Hajek <highegg@gmail.com> parents: 10228 diff changeset	1177
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	1178 @node Assignment Ops
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1179 @section Assignment Expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1180 @cindex assignment expressions
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1181 @cindex assignment operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1182 @cindex operators, assignment
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1183 @cindex expressions, assignment
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1184
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1185 @opindex =
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1186
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1187 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	1188 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	1189 the variable @code{z}:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1190
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1191 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1192 z = 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1193 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1194
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1195 @noindent
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1196 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	1197 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	1198 The @samp{=} sign is called an @dfn{assignment operator}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1199
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1200 Assignments can store string values also. For example, the following
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17170 diff changeset	1201 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	1202 variable @code{message}:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1203
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1204 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1205 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1206 thing = "food"
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1207 predicate = "good"
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1208 message = [ "this " , thing , " is " , predicate ]
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1209 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1210 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1211
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1212 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1213 (This also illustrates concatenation of strings.)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1214
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1215 @cindex side effect
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1216 Most operators (addition, concatenation, and so on) have no effect
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1217 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	1218 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	1219 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	1220 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	1221 a @dfn{side effect}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1222
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1223 @cindex lvalue
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1224 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	1225 (@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	1226 (@pxref{Index Expressions}) or a list of return values
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1227 (@pxref{Calling Functions}). These are all called @dfn{lvalues}, which
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1228 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	1229 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	1230 which the assignment stores in the specified variable, matrix element,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1231 or list of return values.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1232
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1233 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	1234 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	1235 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	1236 @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	1237
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1238 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1239 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1240 octave:13> foo = 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1241 foo = 1
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1242 octave:13> foo = "bar"
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1243 foo = bar
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1244 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1245 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1246
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1247 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1248 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	1249 it previously had a numeric value is forgotten.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1250
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1251 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	1252 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	1253 @code{a} is a matrix with at least two columns,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1254
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1255 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1256 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1257 a(:, 2) = 5
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1258 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1259 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1260
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1261 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1262 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	1263
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1264 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	1265 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	1266 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	1267
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1268 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1269 A (3, :) = []
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1270 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1271
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1272 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1273 deletes the third row of @var{A}, and the assignment
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 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1276 A (:, 1:2:5) = []
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1277 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1278
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1279 @noindent
6672 2f0abcba669c [project @ 2007-05-30 06:42:22 by jwe] jwe parents: 6642 diff changeset	1280 deletes the first, third, and fifth columns.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1281
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1282 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	1283 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	1284 can write multiple assignments together:
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1285
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1286 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1287 x = y = z = 0
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1288 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1289
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1290 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1291 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	1292 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	1293 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	1294
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1295 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	1296 a valid expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1297
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1298 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1299 [a, b, c] = [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1300 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1301
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1302 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1303 that is exactly equivalent to
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1304
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1305 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1306 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1307 [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1308 a = u
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1309 b = s
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1310 c = v
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1311 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1312 @end example
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 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	1315 expression need not match. For example, the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1316
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1317 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1318 [a, b] = [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1319 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1320
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1321 @noindent
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18842 diff changeset	1322 is equivalent to
3294 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 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1325 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1326 [u, s, v] = svd (a)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1327 a = u
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1328 b = s
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1329 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1330 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1331
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1332 @noindent
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1333 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	1334 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	1335 following will produce an error.
fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1336
9153 5247e89688e1 Eliminate most overfull errors when running texi2pdf for generating pdf documentation Rik <rdrider0-list@yahoo.com> parents: 9037 diff changeset	1337 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9159 diff changeset	1338 @group
8015 30629059b72d Update the manual to reflect the changes in error output sh@sh-laptop parents: 7768 diff changeset	1339 [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	1340 @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	1341 @end group
9153 5247e89688e1 Eliminate most overfull errors when running texi2pdf for generating pdf documentation Rik <rdrider0-list@yahoo.com> parents: 9037 diff changeset	1342 @end example
6632 fc235391e58f [project @ 2007-05-16 18:21:26 by jwe] jwe parents: 6550 diff changeset	1343
10209 ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1344 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	1345 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	1346 anywhere:
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1347
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1348 @example
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1349 @group
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1350 [~, s, v] = svd (a);
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1351 @end group
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1352 @end example
ea0d83b4470b document use of ~ placeholders in the manual Jaroslav Hajek <highegg@gmail.com> parents: 9758 diff changeset	1353
10228 fa0c28aff439 update documentation Jaroslav Hajek <highegg@gmail.com> parents: 10209 diff changeset	1354 This is cleaner and more memory efficient than using a dummy variable.
fa0c28aff439 update documentation Jaroslav Hajek <highegg@gmail.com> parents: 10209 diff changeset	1355 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	1356 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	1357 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	1358
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1359 @opindex +=
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1360 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	1361 with a given value, like this
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1362
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1363 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1364 a = a + 2;
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1365 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1366
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1367 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1368 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	1369 @code{+=} operator
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1370
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1371 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1372 a += 2;
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1373 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1374
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1375 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1376 @opindex -=
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1377 @opindex *=
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1378 @opindex /=
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1379 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	1380 multiplication (@code{*=}), and division (@code{/=}). An expression
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1381 of the form
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1382
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1383 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1384 @var{expr1} @var{op}= @var{expr2}
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1385 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1386
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1387 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1388 is evaluated as
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1389
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1390 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1391 @var{expr1} = (@var{expr1}) @var{op} (@var{expr2})
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1392 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1393
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1394 @noindent
18842 e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1395 where @var{op} can be either @code{+}, @code{-}, @code{*}, or @code{/},
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1396 as long as @var{expr2} is a simple expression with no side effects. If
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1397 @var{expr2} also contains an assignment operator, then this expression
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1398 is evaluated as
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1399
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1400 @example
19152 0f9c5a15c8fa doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 19131 diff changeset	1401 @group
18842 e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1402 @var{temp} = @var{expr2}
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1403 @var{expr1} = (@var{expr1}) @var{op} @var{temp}
19152 0f9c5a15c8fa doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 19131 diff changeset	1404 @end group
18842 e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1405 @end example
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1406
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1407 @noindent
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1408 where @var{temp} is a placeholder temporary value storing the computed
e6a4fa91a2f1 doc: Clarify order of evaluation of compound assignment expressions Mike Miller <mtmiller@ieee.org> parents: 17744 diff changeset	1409 result of evaluating @var{expr2}. So, the expression
6642 ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1410
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1411 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1412 a *= b+1
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1413 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1414
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1415 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1416 is evaluated as
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1417
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1418 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1419 a = a * (b+1)
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1420 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1421
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1422 @noindent
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1423 and @emph{not}
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1424
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1425 @example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1426 a = a * b + 1
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1427 @end example
ffee6a1a10f3 [project @ 2007-05-21 19:58:43 by jwe] jwe parents: 6632 diff changeset	1428
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1429 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	1430 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	1431 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	1432 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	1433 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	1434
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1435 @cindex increment operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1436 @cindex decrement operator
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1437 @cindex operators, increment
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1438 @cindex operators, decrement
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1439
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	1440 @node Increment Ops
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1441 @section Increment Operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1442
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1443 @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	1444 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	1445 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	1446 value.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1447
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1448 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	1449 @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	1450 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	1451 same as the expression @code{@var{x} = @var{x} + 1}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1452
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1453 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	1454 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	1455 @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	1456 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	1457 value of @var{x} is 3.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1458
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1459 For matrix and vector arguments, the increment and decrement operators
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1460 work on each element of the operand.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1461
30453 7ecd07721cca doc: Increment and decrement operators must "hug" the variable they affect (bug #60882). Markus Mützel <markus.muetzel@gmx.de> parents: 30332 diff changeset	1462 The increment and decrement operators must "hug" their corresponding
7ecd07721cca doc: Increment and decrement operators must "hug" the variable they affect (bug #60882). Markus Mützel <markus.muetzel@gmx.de> parents: 30332 diff changeset	1463 variable. That means, no white spaces are allowed between these
7ecd07721cca doc: Increment and decrement operators must "hug" the variable they affect (bug #60882). Markus Mützel <markus.muetzel@gmx.de> parents: 30332 diff changeset	1464 operators and the variable they affect.
7ecd07721cca doc: Increment and decrement operators must "hug" the variable they affect (bug #60882). Markus Mützel <markus.muetzel@gmx.de> parents: 30332 diff changeset	1465
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1466 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	1467
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1468 @table @code
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1469 @item ++@var{x}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1470 @opindex ++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1471 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	1472 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	1473 expression @code{@var{x} = @var{x} + 1}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1474
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1475 @item --@var{x}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1476 @opindex @code{--}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1477 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	1478 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	1479 expression @code{@var{x} = @var{x} - 1}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1480
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1481 @item @var{x}++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1482 @opindex ++
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1483 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	1484 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	1485
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1486 @item @var{x}--
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1487 @opindex @code{--}
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1488 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	1489 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	1490 @end table
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1491
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 3602 diff changeset	1492 @node Operator Precedence
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1493 @section Operator Precedence
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1494 @cindex operator precedence
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1495
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1496 @dfn{Operator precedence} determines how operators are grouped, when
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1497 different operators appear close by in one expression. For example,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1498 @samp{*} has higher precedence than @samp{+}. Thus, the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1499 @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	1500 @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	1501
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1502 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	1503 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	1504 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	1505 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	1506 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	1507 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	1508 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	1509 any such mistake.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1510
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1511 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	1512 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	1513 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	1514 @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	1515 @code{a = (b = c)}.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1516
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1517 The precedence of prefix unary operators is important when another
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1518 operator follows the operand. For example, @code{-x^2} means
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1519 @code{-(x^2)}, because @samp{-} has lower precedence than @samp{^}.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1520
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1521 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	1522 precedence. Unless noted, all operators group left to right.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1523
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1524 @table @code
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1525 @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	1526 @samp{()} @samp{@{@}} @samp{.}
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1527
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1528 @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	1529 @samp{++} @samp{--}
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1530
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1531 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	1532
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1533 @item transpose and exponentiation
30326 2ba4758654ca deprecate and . operators (bug #60882) John W. Eaton <jwe@octave.org> parents: 28657 diff changeset	1534 @samp{'} @samp{.'} @samp{^} @samp{.^}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1535
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1536 @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	1537 @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	1538
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1539 @item multiply and divide
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1540 @samp{} @samp{/} @samp{\} @samp{.\} @samp{.} @samp{./}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1541
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1542 @item add, subtract
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1543 @samp{+} @samp{-}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1544
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1545 @item colon
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1546 @samp{:}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1547
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1548 @item relational
27980 6931d95d1967 Use "!=" in preference to "~=" everywhere in code. Rik <rik@octave.org> parents: 27257 diff changeset	1549 @samp{<} @samp{<=} @samp{==} @samp{>=} @samp{>} @samp{!=} @samp{~=}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1550
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1551 @item element-wise "and"
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1552 @samp{&}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1553
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1554 @item element-wise "or"
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1555 @samp{\|}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1556
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1557 @item logical "and"
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1558 @samp{&&}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1559
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1560 @item logical "or"
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1561 @samp{\|\|}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1562
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1563 @item assignment
002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1564 @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	1565 @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	1566 @samp{&=}
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1567
12627 002948ae5bc0 fix precedence level of transpose operators (bug #32533) John W. Eaton <jwe@octave.org> parents: 12601 diff changeset	1568 These operators group right to left.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	1569 @end table

Mercurial > jwe > octave

annotate doc/interpreter/expr.txi @ 31145:7c5cb8f8a21e