octave: doc/interpreter/var.txi annotate

annotate doc/interpreter/var.txi @ 33661:4c378dd47cf2 default tip @

command-widget: Use new signal-slot syntax for better compiler diagnostics. * libgui/src/command-widget.cc (console::console): Use new signal-slot syntax for better compiler diagnostics.

author	Markus Mützel <markus.muetzel@gmx.de>
date	Wed, 12 Jun 2024 17:24:20 +0200
parents	f1bf2e22a94f
children

rev	line source
32632 2e484f9f1f18 maint: update Octave Project Developers copyright for the new year John W. Eaton <jwe@octave.org> parents: 31706 diff changeset	1 @c Copyright (C) 1996-2024 The Octave Project Developers
7018 fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6899 diff changeset	2 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6899 diff changeset	3 @c This file is part of Octave.
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6899 diff changeset	4 @c
24534 194eb4bd202b maint: Update punctuation for GPL v3 license text. Rik <rik@octave.org> parents: 24441 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: 22323 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: 24441 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: 22323 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: 17744 diff changeset	9 @c
22755 3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22323 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: 22323 diff changeset	11 @c WITHOUT ANY WARRANTY; without even the implied warranty of
3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22323 diff changeset	12 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22323 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: 17744 diff changeset	14 @c
7018 fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 6899 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: 6899 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: 24441 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: 4029 diff changeset	19 @node Variables
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	20 @chapter Variables
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	21 @cindex variables, user-defined
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	22 @cindex user-defined variables
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	23
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	24 Variables let you give names to values and refer to them later. You have
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	25 already seen variables in many of the examples. The name of a variable
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	26 must be a sequence of letters, digits and underscores, but it may not begin
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	27 with a digit. Octave does not enforce a limit on the length of variable
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	28 names, but it is seldom useful to have variables with names longer than
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	29 about 30 characters. The following are all valid variable names
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	30
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	31 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	32 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	33 x
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	34 x15
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	35 __foo_bar_baz__
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	36 fucnrdthsucngtagdjb
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	37 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	38 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	39
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	40 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	41 However, names like @code{__foo_bar_baz__} that begin and end with two
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	42 underscores are understood to be reserved for internal use by Octave.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	43 You should not use them in code you write, except to access Octave's
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	44 documented internal variables and built-in symbolic constants.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	45
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	46 Case is significant in variable names. The symbols @code{a} and
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	47 @code{A} are distinct variables.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	48
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	49 A variable name is a valid expression by itself. It represents the
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	50 variable's current value. Variables are given new values with
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	51 @dfn{assignment operators} and @dfn{increment operators}.
17097 e7a059a9a644 doc: Use XREF as anchor prefix in documentation for clearer results in Info viewer. Rik <rik@octave.org> parents: 16772 diff changeset	52 @xref{Assignment Ops,,Assignment Expressions}.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	53
28652 bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 28504 diff changeset	54 There is one automatically created variable with a special meaning. The
bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 28504 diff changeset	55 @code{ans} variable always contains the result of the last computation,
bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 28504 diff changeset	56 where the output wasn't assigned to any variable. The code @code{a =
bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 28504 diff changeset	57 cos (pi)} will assign the value -1 to the variable @code{a}, but will
bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 28504 diff changeset	58 not change the value of @code{ans}. However, the code @code{cos (pi)}
bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 28504 diff changeset	59 will set the value of @code{ans} to -1.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	60
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	61 Variables in Octave do not have fixed types, so it is possible to first
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	62 store a numeric value in a variable and then to later use the same name
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	63 to hold a string value in the same program. Variables may not be used
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	64 before they have been given a value. Doing so results in an error.
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	65
8567 674d00f5e072 remove variable index Soren Hauberg <soren@hauberg.org> parents: 8566 diff changeset	66 @cindex @code{ans}
8566 da95767511f5 Remove descriptions of built-in variables from manual sh@sh-laptop parents: 8519 diff changeset	67 @DOCSTRING(ans)
da95767511f5 Remove descriptions of built-in variables from manual sh@sh-laptop parents: 8519 diff changeset	68
6550 1b7a6061a05d [project @ 2007-04-20 07:40:26 by jwe] jwe parents: 6501 diff changeset	69 @DOCSTRING(isvarname)
1b7a6061a05d [project @ 2007-04-20 07:40:26 by jwe] jwe parents: 6501 diff changeset	70
26202 368dc1142072 makeValidName.m, makeUniqueStrings.m: Clean up functions to use Octave conventions. Rik <rik@octave.org> parents: 26170 diff changeset	71 @DOCSTRING(matlab.lang.makeValidName)
368dc1142072 makeValidName.m, makeUniqueStrings.m: Clean up functions to use Octave conventions. Rik <rik@octave.org> parents: 26170 diff changeset	72
368dc1142072 makeValidName.m, makeUniqueStrings.m: Clean up functions to use Octave conventions. Rik <rik@octave.org> parents: 26170 diff changeset	73 @DOCSTRING(matlab.lang.makeUniqueStrings)
7984 bbaa5d7d0143 Some documentation updates David Bateman <dbateman@free.fr> parents: 7336 diff changeset	74
bbaa5d7d0143 Some documentation updates David Bateman <dbateman@free.fr> parents: 7336 diff changeset	75 @DOCSTRING(namelengthmax)
bbaa5d7d0143 Some documentation updates David Bateman <dbateman@free.fr> parents: 7336 diff changeset	76
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	77 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	78 * Global Variables::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	79 * Persistent Variables::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	80 * Status of Variables::
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	81 @end menu
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	82
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 4029 diff changeset	83 @node Global Variables
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	84 @section Global Variables
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	85 @cindex global variables
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	86 @cindex @code{global} statement
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	87 @cindex variables, global
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	88
32972 f1bf2e22a94f doc: Expand keyword list to include categorized docstrings. (bug #59737) Nicholas R. Jankowski <jankowski.nicholas@gmail.com> parents: 32632 diff changeset	89 See keyword: @ref{XREFglobal, , global}
f1bf2e22a94f doc: Expand keyword list to include categorized docstrings. (bug #59737) Nicholas R. Jankowski <jankowski.nicholas@gmail.com> parents: 32632 diff changeset	90
28504 d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	91 A @dfn{global} variable is one that may be accessed anywhere within Octave.
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	92 This is in contrast to a local variable which can only be accessed outside
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	93 of its current context if it is passed explicitly, such as by including it as a
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	94 parameter when calling a function
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	95 (@code{fcn (@var{local_var1}, @var{local_var2})}).
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	96
28504 d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	97 A variable is declared global by using a @code{global} declaration statement.
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	98 The following statements are all global declarations.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	99
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	100 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	101 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	102 global a
4504 f6a61399bc5c [project @ 2003-09-09 17:48:00 by jwe] jwe parents: 4476 diff changeset	103 global a b
f6a61399bc5c [project @ 2003-09-09 17:48:00 by jwe] jwe parents: 4476 diff changeset	104 global c = 2
f6a61399bc5c [project @ 2003-09-09 17:48:00 by jwe] jwe parents: 4476 diff changeset	105 global d = 3 e f = 5
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	106 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	107 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	108
28504 d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	109 Note that the @code{global} qualifier extends only to the next end-of-statement
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	110 indicator which could be a comma (@samp{,}), semicolon (@samp{;}), or newline
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	111 (@samp{'\n'}). For example, the following code declares one global variable,
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	112 @var{a}, and one local variable @var{b} to which the value 1 is assigned.
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	113
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	114 @example
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	115 global a, b = 1
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	116 @end example
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	117
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	118 A global variable may only be initialized once in a @code{global} statement.
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	119 For example, after executing the following code
4504 f6a61399bc5c [project @ 2003-09-09 17:48:00 by jwe] jwe parents: 4476 diff changeset	120
f6a61399bc5c [project @ 2003-09-09 17:48:00 by jwe] jwe parents: 4476 diff changeset	121 @example
f6a61399bc5c [project @ 2003-09-09 17:48:00 by jwe] jwe parents: 4476 diff changeset	122 @group
f6a61399bc5c [project @ 2003-09-09 17:48:00 by jwe] jwe parents: 4476 diff changeset	123 global gvar = 1
f6a61399bc5c [project @ 2003-09-09 17:48:00 by jwe] jwe parents: 4476 diff changeset	124 global gvar = 2
f6a61399bc5c [project @ 2003-09-09 17:48:00 by jwe] jwe parents: 4476 diff changeset	125 @end group
f6a61399bc5c [project @ 2003-09-09 17:48:00 by jwe] jwe parents: 4476 diff changeset	126 @end example
f6a61399bc5c [project @ 2003-09-09 17:48:00 by jwe] jwe parents: 4476 diff changeset	127
f6a61399bc5c [project @ 2003-09-09 17:48:00 by jwe] jwe parents: 4476 diff changeset	128 @noindent
6077 95f153281c97 [project @ 2006-10-24 16:24:30 by jwe] jwe parents: 5942 diff changeset	129 the value of the global variable @code{gvar} is 1, not 2. Issuing a
6623 545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	130 @samp{clear gvar} command does not change the above behavior, but
6077 95f153281c97 [project @ 2006-10-24 16:24:30 by jwe] jwe parents: 5942 diff changeset	131 @samp{clear all} does.
4504 f6a61399bc5c [project @ 2003-09-09 17:48:00 by jwe] jwe parents: 4476 diff changeset	132
28504 d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	133 It is necessary declare a variable as global within a function body in order to
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	134 access the one universal variable. For example,
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	135
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	136 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	137 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	138 global x
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	139 function f ()
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	140 x = 1;
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	141 endfunction
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	142 f ()
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	143 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	144 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	145
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	146 @noindent
28504 d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	147 does @emph{not} set the value of the global variable @code{x} to 1. Instead,
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	148 a local variable, with name @code{x}, is created and assigned the value of 1.
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	149 In order to change the value of the global variable @code{x}, you must also
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	150 declare it to be global within the function body, like this
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	151
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	152 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	153 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	154 function f ()
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	155 global x;
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	156 x = 1;
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	157 endfunction
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	158 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	159 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	160
28504 d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	161 Passing a global variable in a function parameter list will make a local copy
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	162 and @emph{not} modify the global value. For example, given the function
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	163
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	164 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	165 @group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	166 function f (x)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	167 x = 0
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	168 endfunction
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	169 @end group
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	170 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	171
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	172 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	173 and the definition of @code{x} as a global variable at the top level,
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	174
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	175 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	176 global x = 13
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	177 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	178
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	179 @noindent
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	180 the expression
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	181
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	182 @example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	183 f (x)
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	184 @end example
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	185
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	186 @noindent
28504 d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	187 will display the value of @code{x} from inside the function as 0, but the value
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	188 of @code{x} at the top level remains unchanged, because the function works with
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	189 a @emph{copy} of its argument.
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	190
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	191 Programming Note: While global variables occasionally are the right solution to
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	192 a coding problem, modern best practice discourages their use. Code which
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	193 relies on global variables may behave unpredictably between different users
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	194 and can be difficult to debug. This is because global variables can introduce
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	195 systemic changes so that localizing a bug to a particular function, or to a
d747d57989e2 doc: Better document how global variables and clear() interact (bug #57604). Rik <rik@octave.org> parents: 26376 diff changeset	196 particular loop within a function, becomes difficult.
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	197
4029 2cc57b6169cf [project @ 2002-08-09 07:36:15 by jwe] jwe parents: 3439 diff changeset	198 @DOCSTRING(isglobal)
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	199
4686 c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	200 @node Persistent Variables
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	201 @section Persistent Variables
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	202 @cindex persistent variables
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	203 @cindex @code{persistent} statement
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	204 @cindex variables, persistent
32972 f1bf2e22a94f doc: Expand keyword list to include categorized docstrings. (bug #59737) Nicholas R. Jankowski <jankowski.nicholas@gmail.com> parents: 32632 diff changeset	205
f1bf2e22a94f doc: Expand keyword list to include categorized docstrings. (bug #59737) Nicholas R. Jankowski <jankowski.nicholas@gmail.com> parents: 32632 diff changeset	206 See keyword: @ref{XREFpersistent, , persistent}
4686 c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	207
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	208 A variable that has been declared @dfn{persistent} within a function
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	209 will retain its contents in memory between subsequent calls to the
9037 4cb9f994dcec Documentation cleanup of var.texi, expr.texi, eval.texi Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	210 same function. The difference between persistent variables and global
4686 c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	211 variables is that persistent variables are local in scope to a
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	212 particular function and are not visible elsewhere.
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	213
6899 110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	214 The following example uses a persistent variable to create a function
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	215 that prints the number of times it has been called.
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	216
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	217 @example
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	218 @group
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	219 function count_calls ()
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	220 persistent calls = 0;
21634 96518f623c91 Backed out changeset dcf8922b724b Mike Miller <mtmiller@octave.org> parents: 21633 diff changeset	221 printf ("'count_calls' has been called %d times\n",
96518f623c91 Backed out changeset dcf8922b724b Mike Miller <mtmiller@octave.org> parents: 21633 diff changeset	222 ++calls);
6899 110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	223 endfunction
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	224
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	225 for i = 1:3
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	226 count_calls ();
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	227 endfor
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	228
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	229 @print{} 'count_calls' has been called 1 times
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	230 @print{} 'count_calls' has been called 2 times
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	231 @print{} 'count_calls' has been called 3 times
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	232 @end group
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	233 @end example
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	234
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	235 As the example shows, a variable may be declared persistent using a
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	236 @code{persistent} declaration statement. The following statements are
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	237 all persistent declarations.
4686 c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	238
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	239 @example
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	240 @group
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	241 persistent a
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	242 persistent a b
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	243 persistent c = 2
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	244 persistent d = 3 e f = 5
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	245 @end group
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	246 @end example
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	247
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	248 The behavior of persistent variables is equivalent to the behavior of
18110 2217bc116aa9 maint: Dummy merge with gui-release, ignoring all recent backout merges Jordi Gutiérrez Hermoso <jordigh@octave.org> parents: 18106 diff changeset	249 static variables in C@.
6899 110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	250
24953 11b13a7cc57e doc: Document forbidden persistent function input/output arguments (bug #53331). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 24534 diff changeset	251 One restriction for persistent variables is, that neither input nor
11b13a7cc57e doc: Document forbidden persistent function input/output arguments (bug #53331). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 24534 diff changeset	252 output arguments of a function can be persistent:
11b13a7cc57e doc: Document forbidden persistent function input/output arguments (bug #53331). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 24534 diff changeset	253
11b13a7cc57e doc: Document forbidden persistent function input/output arguments (bug #53331). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 24534 diff changeset	254 @example
11b13a7cc57e doc: Document forbidden persistent function input/output arguments (bug #53331). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 24534 diff changeset	255 @group
11b13a7cc57e doc: Document forbidden persistent function input/output arguments (bug #53331). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 24534 diff changeset	256 function y = foo ()
11b13a7cc57e doc: Document forbidden persistent function input/output arguments (bug #53331). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 24534 diff changeset	257 persistent y = 0; # Not allowed!
11b13a7cc57e doc: Document forbidden persistent function input/output arguments (bug #53331). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 24534 diff changeset	258 endfunction
11b13a7cc57e doc: Document forbidden persistent function input/output arguments (bug #53331). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 24534 diff changeset	259
11b13a7cc57e doc: Document forbidden persistent function input/output arguments (bug #53331). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 24534 diff changeset	260 foo ()
11b13a7cc57e doc: Document forbidden persistent function input/output arguments (bug #53331). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 24534 diff changeset	261 @print{} error: can't make function parameter y persistent
11b13a7cc57e doc: Document forbidden persistent function input/output arguments (bug #53331). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 24534 diff changeset	262 @end group
11b13a7cc57e doc: Document forbidden persistent function input/output arguments (bug #53331). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 24534 diff changeset	263 @end example
11b13a7cc57e doc: Document forbidden persistent function input/output arguments (bug #53331). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 24534 diff changeset	264
6899 110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	265 Like global variables, a persistent variable may only be initialized once.
6896 5c9c49c51302 [project @ 2007-09-13 18:49:15 by jwe] jwe parents: 6778 diff changeset	266 For example, after executing the following code
4686 c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	267
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	268 @example
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	269 @group
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	270 persistent pvar = 1
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	271 persistent pvar = 2
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	272 @end group
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	273 @end example
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	274
c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	275 @noindent
6896 5c9c49c51302 [project @ 2007-09-13 18:49:15 by jwe] jwe parents: 6778 diff changeset	276 the value of the persistent variable @code{pvar} is 1, not 2.
4686 c7ae43dfdea4 [project @ 2004-01-06 19:29:23 by jwe] jwe parents: 4504 diff changeset	277
6899 110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	278 If a persistent variable is declared but not initialized to a specific
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	279 value, it will contain an empty matrix. So, it is also possible to
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	280 initialize a persistent variable by checking whether it is empty, as the
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	281 following example illustrates.
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	282
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	283 @example
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	284 @group
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	285 function count_calls ()
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	286 persistent calls;
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	287 if (isempty (calls))
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	288 calls = 0;
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	289 endif
21634 96518f623c91 Backed out changeset dcf8922b724b Mike Miller <mtmiller@octave.org> parents: 21633 diff changeset	290 printf ("'count_calls' has been called %d times\n",
96518f623c91 Backed out changeset dcf8922b724b Mike Miller <mtmiller@octave.org> parents: 21633 diff changeset	291 ++calls);
6899 110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	292 endfunction
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	293 @end group
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	294 @end example
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	295
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	296 @noindent
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	297 This implementation behaves in exactly the same way as the previous
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	298 implementation of @code{count_calls}.
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	299
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	300 The value of a persistent variable is kept in memory until it is
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	301 explicitly cleared. Assuming that the implementation of @code{count_calls}
9307 c2923c27c877 Various documentation improvements Rik <rdrider0-list@yahoo.com> parents: 9209 diff changeset	302 is saved on disk, we get the following behavior.
6899 110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	303
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	304 @example
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	305 for i = 1:2
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	306 count_calls ();
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	307 endfor
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	308 @print{} 'count_calls' has been called 1 times
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	309 @print{} 'count_calls' has been called 2 times
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	310
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	311 clear
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	312 for i = 1:2
14846 460a3c6d8bf1 maint: Use Octave coding convention for cuddled parenthis in function calls with empty argument lists. Rik <octave@nomad.inbox5.com> parents: 14138 diff changeset	313 count_calls ();
6899 110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	314 endfor
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	315 @print{} 'count_calls' has been called 3 times
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	316 @print{} 'count_calls' has been called 4 times
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	317
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	318 clear all
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	319 for i = 1:2
14846 460a3c6d8bf1 maint: Use Octave coding convention for cuddled parenthis in function calls with empty argument lists. Rik <octave@nomad.inbox5.com> parents: 14138 diff changeset	320 count_calls ();
6899 110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	321 endfor
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	322 @print{} 'count_calls' has been called 1 times
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	323 @print{} 'count_calls' has been called 2 times
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	324
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	325 clear count_calls
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	326 for i = 1:2
14846 460a3c6d8bf1 maint: Use Octave coding convention for cuddled parenthis in function calls with empty argument lists. Rik <octave@nomad.inbox5.com> parents: 14138 diff changeset	327 count_calls ();
6899 110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	328 endfor
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	329 @print{} 'count_calls' has been called 1 times
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	330 @print{} 'count_calls' has been called 2 times
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	331 @end example
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	332
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	333 @noindent
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	334 That is, the persistent variable is only removed from memory when the
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	335 function containing the variable is removed. Note that if the function
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	336 definition is typed directly into the Octave prompt, the persistent
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	337 variable will be cleared by a simple @code{clear} command as the entire
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	338 function definition will be removed from memory. If you do not want
110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	339 a persistent variable to be removed from memory even if the function is
17097 e7a059a9a644 doc: Use XREF as anchor prefix in documentation for clearer results in Info viewer. Rik <rik@octave.org> parents: 16772 diff changeset	340 cleared, you should use the @code{mlock} function
e7a059a9a644 doc: Use XREF as anchor prefix in documentation for clearer results in Info viewer. Rik <rik@octave.org> parents: 16772 diff changeset	341 (@pxref{Function Locking}).
6899 110c5782fe3b [project @ 2007-09-14 15:17:53 by jwe] jwe parents: 6896 diff changeset	342
4167 aae05d51353c [project @ 2002-11-12 02:52:50 by jwe] jwe parents: 4029 diff changeset	343 @node Status of Variables
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	344 @section Status of Variables
bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	345
6623 545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	346 When creating simple one-shot programs it can be very convenient to
9037 4cb9f994dcec Documentation cleanup of var.texi, expr.texi, eval.texi Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	347 see which variables are available at the prompt. The function @code{who}
6623 545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	348 and its siblings @code{whos} and @code{whos_line_format} will show
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	349 different information about what is in memory, as the following shows.
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	350
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	351 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9037 diff changeset	352 @group
6623 545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	353 str = "A random string";
24440 f8bbaacefc33 doc: Fix various inconsistencies in manual (bug #52712). Rik <rik@octave.org> parents: 23219 diff changeset	354 who
f8bbaacefc33 doc: Fix various inconsistencies in manual (bug #52712). Rik <rik@octave.org> parents: 23219 diff changeset	355 @print{} Variables in the current scope:
f8bbaacefc33 doc: Fix various inconsistencies in manual (bug #52712). Rik <rik@octave.org> parents: 23219 diff changeset	356 @print{}
f8bbaacefc33 doc: Fix various inconsistencies in manual (bug #52712). Rik <rik@octave.org> parents: 23219 diff changeset	357 @print{} ans str
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9037 diff changeset	358 @end group
6623 545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	359 @end example
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	360
3361 4f40efa995c1 [project @ 1999-11-19 21:19:37 by jwe] jwe parents: 3294 diff changeset	361 @DOCSTRING(who)
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	362
4913 c8368716bab3 [project @ 2004-07-23 16:00:48 by jwe] jwe parents: 4686 diff changeset	363 @DOCSTRING(whos)
c8368716bab3 [project @ 2004-07-23 16:00:48 by jwe] jwe parents: 4686 diff changeset	364
c8368716bab3 [project @ 2004-07-23 16:00:48 by jwe] jwe parents: 4686 diff changeset	365 @DOCSTRING(whos_line_format)
c8368716bab3 [project @ 2004-07-23 16:00:48 by jwe] jwe parents: 4686 diff changeset	366
6623 545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	367 Instead of displaying which variables are in memory, it is possible
9037 4cb9f994dcec Documentation cleanup of var.texi, expr.texi, eval.texi Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	368 to determine if a given variable is available. That way it is possible
4cb9f994dcec Documentation cleanup of var.texi, expr.texi, eval.texi Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	369 to alter the behavior of a program depending on the existence of a
4cb9f994dcec Documentation cleanup of var.texi, expr.texi, eval.texi Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	370 variable. The following example illustrates this.
6623 545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	371
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	372 @example
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9037 diff changeset	373 @group
6623 545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	374 if (! exist ("meaning", "var"))
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	375 disp ("The program has no 'meaning'");
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	376 endif
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9037 diff changeset	377 @end group
6623 545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	378 @end example
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	379
3361 4f40efa995c1 [project @ 1999-11-19 21:19:37 by jwe] jwe parents: 3294 diff changeset	380 @DOCSTRING(exist)
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	381
6623 545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	382 Usually Octave will manage the memory, but sometimes it can be practical
9037 4cb9f994dcec Documentation cleanup of var.texi, expr.texi, eval.texi Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	383 to remove variables from memory manually. This is usually needed when
6623 545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	384 working with large variables that fill a substantial part of the memory.
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	385 On a computer that uses the IEEE floating point format, the following
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	386 program allocates a matrix that requires around 128 MB memory.
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	387
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	388 @example
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	389 large_matrix = zeros (4000, 4000);
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	390 @end example
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	391
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	392 @noindent
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	393 Since having this variable in memory might slow down other computations,
9037 4cb9f994dcec Documentation cleanup of var.texi, expr.texi, eval.texi Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	394 it can be necessary to remove it manually from memory. The @code{clear}
26170 96bc9ee8e77f clearvars.m: Implement new function. Rik <rik@octave.org> parents: 25054 diff changeset	395 or @code{clearvars} functions do this.
6623 545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	396
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	397 @DOCSTRING(clear)
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	398
26170 96bc9ee8e77f clearvars.m: Implement new function. Rik <rik@octave.org> parents: 25054 diff changeset	399 @DOCSTRING(clearvars)
96bc9ee8e77f clearvars.m: Implement new function. Rik <rik@octave.org> parents: 25054 diff changeset	400
12580 2c4e52c83b64 Move pack() function to proper place in documentation. Rik <octave@nomad.inbox5.com> parents: 12578 diff changeset	401 @DOCSTRING(pack)
2c4e52c83b64 Move pack() function to proper place in documentation. Rik <octave@nomad.inbox5.com> parents: 12578 diff changeset	402
8347 fa78cb8d8a5c corrections for typos Brian Gough<bjg@network-theory.co.uk> parents: 8286 diff changeset	403 Information about a function or variable such as its location in the
9037 4cb9f994dcec Documentation cleanup of var.texi, expr.texi, eval.texi Rik <rdrider0-list@yahoo.com> parents: 8920 diff changeset	404 file system can also be acquired from within Octave. This is usually
6623 545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	405 only useful during development of programs, and not within a program.
545847da3b88 [project @ 2007-05-15 02:23:08 by jwe] jwe parents: 6550 diff changeset	406
3361 4f40efa995c1 [project @ 1999-11-19 21:19:37 by jwe] jwe parents: 3294 diff changeset	407 @DOCSTRING(type)
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	408
3361 4f40efa995c1 [project @ 1999-11-19 21:19:37 by jwe] jwe parents: 3294 diff changeset	409 @DOCSTRING(which)
3294 bfe1573bd2ae [project @ 1999-10-19 10:06:07 by jwe] jwe parents: diff changeset	410
8817 03b7f618ab3d include docstrings for new functions in the manual John W. Eaton <jwe@octave.org> parents: 8571 diff changeset	411 @DOCSTRING(what)

Mercurial > octave

annotate doc/interpreter/var.txi @ 33661:4c378dd47cf2 default tip @