Mercurial > octave
view doc/interpreter/var.txi @ 30564:796f54d4ddbf stable
update Octave Project Developers copyright for the new year
In files that have the "Octave Project Developers" copyright notice,
update for 2021.
In all .txi and .texi files except gpl.txi and gpl.texi in the
doc/liboctave and doc/interpreter directories, change the copyright
to "Octave Project Developers", the same as used for other source
files. Update copyright notices for 2022 (not done since 2019). For
gpl.txi and gpl.texi, change the copyright notice to be "Free Software
Foundation, Inc." and leave the date at 2007 only because this file
only contains the text of the GPL, not anything created by the Octave
Project Developers.
Add Paul Thomas to contributors.in.
author | John W. Eaton <jwe@octave.org> |
---|---|
date | Tue, 28 Dec 2021 18:22:40 -0500 |
parents | bb0ca2753bc2 |
children | 597f3ee61a48 |
line wrap: on
line source
@c Copyright (C) 1996-2022 The Octave Project Developers @c @c This file is part of Octave. @c @c Octave is free software: you can redistribute it and/or modify it @c under the terms of the GNU General Public License as published by @c the Free Software Foundation, either version 3 of the License, or @c (at your option) any later version. @c @c Octave is distributed in the hope that it will be useful, but @c WITHOUT ANY WARRANTY; without even the implied warranty of @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @c GNU General Public License for more details. @c @c You should have received a copy of the GNU General Public License @c along with Octave; see the file COPYING. If not, see @c <https://www.gnu.org/licenses/>. @node Variables @chapter Variables @cindex variables, user-defined @cindex user-defined variables Variables let you give names to values and refer to them later. You have already seen variables in many of the examples. The name of a variable must be a sequence of letters, digits and underscores, but it may not begin with a digit. Octave does not enforce a limit on the length of variable names, but it is seldom useful to have variables with names longer than about 30 characters. The following are all valid variable names @example @group x x15 __foo_bar_baz__ fucnrdthsucngtagdjb @end group @end example @noindent However, names like @code{__foo_bar_baz__} that begin and end with two underscores are understood to be reserved for internal use by Octave. You should not use them in code you write, except to access Octave's documented internal variables and built-in symbolic constants. Case is significant in variable names. The symbols @code{a} and @code{A} are distinct variables. A variable name is a valid expression by itself. It represents the variable's current value. Variables are given new values with @dfn{assignment operators} and @dfn{increment operators}. @xref{Assignment Ops,,Assignment Expressions}. There is one automatically created variable with a special meaning. The @code{ans} variable always contains the result of the last computation, where the output wasn't assigned to any variable. The code @code{a = cos (pi)} will assign the value -1 to the variable @code{a}, but will not change the value of @code{ans}. However, the code @code{cos (pi)} will set the value of @code{ans} to -1. Variables in Octave do not have fixed types, so it is possible to first store a numeric value in a variable and then to later use the same name to hold a string value in the same program. Variables may not be used before they have been given a value. Doing so results in an error. @cindex @code{ans} @DOCSTRING(ans) @DOCSTRING(isvarname) @DOCSTRING(matlab.lang.makeValidName) @DOCSTRING(matlab.lang.makeUniqueStrings) @DOCSTRING(namelengthmax) @menu * Global Variables:: * Persistent Variables:: * Status of Variables:: @end menu @node Global Variables @section Global Variables @cindex global variables @cindex @code{global} statement @cindex variables, global A @dfn{global} variable is one that may be accessed anywhere within Octave. This is in contrast to a local variable which can only be accessed outside of its current context if it is passed explicitly, such as by including it as a parameter when calling a function (@code{fcn (@var{local_var1}, @var{local_var2})}). A variable is declared global by using a @code{global} declaration statement. The following statements are all global declarations. @example @group global a global a b global c = 2 global d = 3 e f = 5 @end group @end example Note that the @code{global} qualifier extends only to the next end-of-statement indicator which could be a comma (@samp{,}), semicolon (@samp{;}), or newline (@samp{'\n'}). For example, the following code declares one global variable, @var{a}, and one local variable @var{b} to which the value 1 is assigned. @example global a, b = 1 @end example A global variable may only be initialized once in a @code{global} statement. For example, after executing the following code @example @group global gvar = 1 global gvar = 2 @end group @end example @noindent the value of the global variable @code{gvar} is 1, not 2. Issuing a @samp{clear gvar} command does not change the above behavior, but @samp{clear all} does. It is necessary declare a variable as global within a function body in order to access the one universal variable. For example, @example @group global x function f () x = 1; endfunction f () @end group @end example @noindent does @emph{not} set the value of the global variable @code{x} to 1. Instead, a local variable, with name @code{x}, is created and assigned the value of 1. In order to change the value of the global variable @code{x}, you must also declare it to be global within the function body, like this @example @group function f () global x; x = 1; endfunction @end group @end example Passing a global variable in a function parameter list will make a local copy and @emph{not} modify the global value. For example, given the function @example @group function f (x) x = 0 endfunction @end group @end example @noindent and the definition of @code{x} as a global variable at the top level, @example global x = 13 @end example @noindent the expression @example f (x) @end example @noindent will display the value of @code{x} from inside the function as 0, but the value of @code{x} at the top level remains unchanged, because the function works with a @emph{copy} of its argument. Programming Note: While global variables occasionally are the right solution to a coding problem, modern best practice discourages their use. Code which relies on global variables may behave unpredictably between different users and can be difficult to debug. This is because global variables can introduce systemic changes so that localizing a bug to a particular function, or to a particular loop within a function, becomes difficult. @DOCSTRING(isglobal) @node Persistent Variables @section Persistent Variables @cindex persistent variables @cindex @code{persistent} statement @cindex variables, persistent @anchor{XREFpersistent} A variable that has been declared @dfn{persistent} within a function will retain its contents in memory between subsequent calls to the same function. The difference between persistent variables and global variables is that persistent variables are local in scope to a particular function and are not visible elsewhere. The following example uses a persistent variable to create a function that prints the number of times it has been called. @example @group function count_calls () persistent calls = 0; printf ("'count_calls' has been called %d times\n", ++calls); endfunction for i = 1:3 count_calls (); endfor @print{} 'count_calls' has been called 1 times @print{} 'count_calls' has been called 2 times @print{} 'count_calls' has been called 3 times @end group @end example As the example shows, a variable may be declared persistent using a @code{persistent} declaration statement. The following statements are all persistent declarations. @example @group persistent a persistent a b persistent c = 2 persistent d = 3 e f = 5 @end group @end example The behavior of persistent variables is equivalent to the behavior of static variables in C@. One restriction for persistent variables is, that neither input nor output arguments of a function can be persistent: @example @group function y = foo () persistent y = 0; # Not allowed! endfunction foo () @print{} error: can't make function parameter y persistent @end group @end example Like global variables, a persistent variable may only be initialized once. For example, after executing the following code @example @group persistent pvar = 1 persistent pvar = 2 @end group @end example @noindent the value of the persistent variable @code{pvar} is 1, not 2. If a persistent variable is declared but not initialized to a specific value, it will contain an empty matrix. So, it is also possible to initialize a persistent variable by checking whether it is empty, as the following example illustrates. @example @group function count_calls () persistent calls; if (isempty (calls)) calls = 0; endif printf ("'count_calls' has been called %d times\n", ++calls); endfunction @end group @end example @noindent This implementation behaves in exactly the same way as the previous implementation of @code{count_calls}. The value of a persistent variable is kept in memory until it is explicitly cleared. Assuming that the implementation of @code{count_calls} is saved on disk, we get the following behavior. @example for i = 1:2 count_calls (); endfor @print{} 'count_calls' has been called 1 times @print{} 'count_calls' has been called 2 times clear for i = 1:2 count_calls (); endfor @print{} 'count_calls' has been called 3 times @print{} 'count_calls' has been called 4 times clear all for i = 1:2 count_calls (); endfor @print{} 'count_calls' has been called 1 times @print{} 'count_calls' has been called 2 times clear count_calls for i = 1:2 count_calls (); endfor @print{} 'count_calls' has been called 1 times @print{} 'count_calls' has been called 2 times @end example @noindent That is, the persistent variable is only removed from memory when the function containing the variable is removed. Note that if the function definition is typed directly into the Octave prompt, the persistent variable will be cleared by a simple @code{clear} command as the entire function definition will be removed from memory. If you do not want a persistent variable to be removed from memory even if the function is cleared, you should use the @code{mlock} function (@pxref{Function Locking}). @node Status of Variables @section Status of Variables When creating simple one-shot programs it can be very convenient to see which variables are available at the prompt. The function @code{who} and its siblings @code{whos} and @code{whos_line_format} will show different information about what is in memory, as the following shows. @example @group str = "A random string"; who @print{} Variables in the current scope: @print{} @print{} ans str @end group @end example @DOCSTRING(who) @DOCSTRING(whos) @DOCSTRING(whos_line_format) Instead of displaying which variables are in memory, it is possible to determine if a given variable is available. That way it is possible to alter the behavior of a program depending on the existence of a variable. The following example illustrates this. @example @group if (! exist ("meaning", "var")) disp ("The program has no 'meaning'"); endif @end group @end example @DOCSTRING(exist) Usually Octave will manage the memory, but sometimes it can be practical to remove variables from memory manually. This is usually needed when working with large variables that fill a substantial part of the memory. On a computer that uses the IEEE floating point format, the following program allocates a matrix that requires around 128 MB memory. @example large_matrix = zeros (4000, 4000); @end example @noindent Since having this variable in memory might slow down other computations, it can be necessary to remove it manually from memory. The @code{clear} or @code{clearvars} functions do this. @DOCSTRING(clear) @DOCSTRING(clearvars) @DOCSTRING(pack) Information about a function or variable such as its location in the file system can also be acquired from within Octave. This is usually only useful during development of programs, and not within a program. @DOCSTRING(type) @DOCSTRING(which) @DOCSTRING(what)