Contents

rename()

Usage:

rename(var, newName), where newName is an undefined variable

Keywords: general, variables

rename(Var, Name) where Name is an undefined variable (no value has been
assigned to it) changes the name of Var to Name. Var may be an existing
variable, a constant such as 3.5, "hello", or T, or an expression such
as 'sqrt(20)' or '3*cos(x) + 4*sin(x)'.  When Var a constant or
expression, rename(Var, Name) is equivalent to Name <- Var.  Unless Name
is a CHARACTER scalar (see below), it must not be a function or an
existing variable or macro.  It is an error if variable Name exists,
unless it is the same variable as Var as in rename(x,x).

rename(Var, nameVar) where nameVar is a quoted string or scalar
CHARACTER variable is equivalent to rename(Var, <<nameVar>>), that is
the new name is the value of nameVar.  For example, rename(x, y) and
rename(x, "y") are equivalent.  The value of nameVar must not be the
name of any existing variable, macro or function and must be a legal
name (see 'syntax').  "NULL", "T", and "F" are not legal names.

It is an error if Var is a locked variable; see lockvars(),
unlockvars(), islock() and variables:"locked_variables".

Var must not be a function or a "special" variable such as CLIPBOARD,
SELECTION or GRAPHWINDOWS.  See topics 'CLIPBOARD', 'GRAPHWINDOWS' and
'graph_assign'.

You can achieve the same effect as rename(Var,Name) by
  Cmd> Name <- Var; delete(Var)

However, if Var is not a constant or expression, doing it this way
entails the temporary existence in memory of two copies of Var.  If Var
is large, there may not be enough room in your workspace.  The use of
rename() avoids this problem.  For this reason, in a macro that uses
another macro to compute a value, it may sometimes be helpful to use
rename() instead of assignment.

Examples:
  Cmd> rename(PI, pi) # or rename(PI,"pi"), change name of PI to pi

  Cmd> e <- 10; rename(E, e) # is an error since e exists

  Cmd> rename(sqrt(2),sqrt2) # same as sqrt2 <- sqrt(2)

The last example would be an error if sqrt2 is already a variable.

See also nameof(), compnames(), varnames()