Mercurial > octave

comparison doc/interpreter/var.txi @ 28504:d747d57989e2 stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: Better document how global variables and clear() interact (bug #57604). * var.txi: Rewrite section on global variables. * variables.cc (Fclear): Add a Programming Note about how clear removes only the local copy of a global variable.
author Rik <rik@octave.org>
date Fri, 26 Jun 2020 13:57:04 -0700
parents 00f796120a6d
children bb0ca2753bc2
comparison
equal deleted inserted replaced
28498:2de2b2ddd032 28504:d747d57989e2
83 @section Global Variables 83 @section Global Variables
84 @cindex global variables 84 @cindex global variables
85 @cindex @code{global} statement 85 @cindex @code{global} statement
86 @cindex variables, global 86 @cindex variables, global
87 87
88 A variable that has been declared @dfn{global} may be accessed from 88 A @dfn{global} variable is one that may be accessed anywhere within Octave.
89 within a function body without having to pass it as a formal parameter. 89 This is in contrast to a local variable which can only be accessed outside
90 90 of its current context if it is passed explicitly, such as by including it as a
91 A variable may be declared global using a @code{global} declaration 91 parameter when calling a function
92 statement. The following statements are all global declarations. 92 (@code{fcn (@var{local_var1}, @var{local_var2})}).
93
94 A variable is declared global by using a @code{global} declaration statement.
95 The following statements are all global declarations.
93 96
94 @example 97 @example
95 @group 98 @group
96 global a 99 global a
97 global a b 100 global a b
98 global c = 2 101 global c = 2
99 global d = 3 e f = 5 102 global d = 3 e f = 5
100 @end group 103 @end group
101 @end example 104 @end example
102 105
103 A global variable may only be initialized once in a @code{global} 106 Note that the @code{global} qualifier extends only to the next end-of-statement
104 statement. For example, after executing the following code 107 indicator which could be a comma (@samp{,}), semicolon (@samp{;}), or newline
108 (@samp{'\n'}). For example, the following code declares one global variable,
109 @var{a}, and one local variable @var{b} to which the value 1 is assigned.
110
111 @example
112 global a, b = 1
113 @end example
114
115 A global variable may only be initialized once in a @code{global} statement.
116 For example, after executing the following code
105 117
106 @example 118 @example
107 @group 119 @group
108 global gvar = 1 120 global gvar = 1
109 global gvar = 2 121 global gvar = 2
113 @noindent 125 @noindent
114 the value of the global variable @code{gvar} is 1, not 2. Issuing a 126 the value of the global variable @code{gvar} is 1, not 2. Issuing a
115 @samp{clear gvar} command does not change the above behavior, but 127 @samp{clear gvar} command does not change the above behavior, but
116 @samp{clear all} does. 128 @samp{clear all} does.
117 129
118 It is necessary declare a variable as global within a function body in 130 It is necessary declare a variable as global within a function body in order to
119 order to access it. For example, 131 access the one universal variable. For example,
120 132
121 @example 133 @example
122 @group 134 @group
123 global x 135 global x
124 function f () 136 function f ()
127 f () 139 f ()
128 @end group 140 @end group
129 @end example 141 @end example
130 142
131 @noindent 143 @noindent
132 does @emph{not} set the value of the global variable @code{x} to 1. In 144 does @emph{not} set the value of the global variable @code{x} to 1. Instead,
133 order to change the value of the global variable @code{x}, you must also 145 a local variable, with name @code{x}, is created and assigned the value of 1.
146 In order to change the value of the global variable @code{x}, you must also
134 declare it to be global within the function body, like this 147 declare it to be global within the function body, like this
135 148
136 @example 149 @example
137 @group 150 @group
138 function f () 151 function f ()
140 x = 1; 153 x = 1;
141 endfunction 154 endfunction
142 @end group 155 @end group
143 @end example 156 @end example
144 157
145 Passing a global variable in a function parameter list will 158 Passing a global variable in a function parameter list will make a local copy
146 make a local copy and not modify the global value. For example, given 159 and @emph{not} modify the global value. For example, given the function
147 the function
148 160
149 @example 161 @example
150 @group 162 @group
151 function f (x) 163 function f (x)
152 x = 0 164 x = 0
167 @example 179 @example
168 f (x) 180 f (x)
169 @end example 181 @end example
170 182
171 @noindent 183 @noindent
172 will display the value of @code{x} from inside the function as 0, 184 will display the value of @code{x} from inside the function as 0, but the value
173 but the value of @code{x} at the top level remains unchanged, because 185 of @code{x} at the top level remains unchanged, because the function works with
174 the function works with a @emph{copy} of its argument. 186 a @emph{copy} of its argument.
187
188 Programming Note: While global variables occasionally are the right solution to
189 a coding problem, modern best practice discourages their use. Code which
190 relies on global variables may behave unpredictably between different users
191 and can be difficult to debug. This is because global variables can introduce
192 systemic changes so that localizing a bug to a particular function, or to a
193 particular loop within a function, becomes difficult.
175 194
176 @DOCSTRING(isglobal) 195 @DOCSTRING(isglobal)
177 196
178 @node Persistent Variables 197 @node Persistent Variables
179 @section Persistent Variables 198 @section Persistent Variables