get_rm.Rd 1.97 KB
 Radford Neal committed Jun 01, 2013 1 2 % File src/library/base/man/pnamedcnt.Rd % Part of pqR.  Radford Neal committed Sep 12, 2018 3 % Copyright (C) 2013, 2018 Radford M. Neal  Radford Neal committed Jun 01, 2013 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 % Distributed under GPL 2 or later \name{get_rm} \alias{get_rm} \title{Get value of variable and then remove it} \description{ This function removes a variable from the current environment, and returns its value just before it was removed. It is useful primarily when the value returned may have been stored only in the variable removed, in which case the value will be known to not be used elsewhere, and will not have to be copied if it is later modified. } \usage{ get_rm(x) } \arguments{ \item{x}{A variable in the current environment.} } \details{ For each object, R maintains a count of how many variables/names reference the object, called "named". If this count is greater than one, modifications to part of the variable will cause it to first be copied, so that the other references will see the original value. When the value in a variable has a count of one, this can be reduced to zero when that variable is removed, but on its own, this is not useful, since the value can no longer be accessed. However, with \code{get_rm}, the count can be reduced to zero and the value still be used, for example as a function return value, or an operand of an arithmetic operator, whose space may be reused for the result. See the examples below. An error is signaled if the variable does not exist in the current environment. } \value{ The value of \code{x}, just before it was removed. } \seealso{ \code{\link{get}}, \code{\link{rm}} } \examples{ f <- function () { v <- 1:1000; v <- v + v^2; get_rm(v) } u <- f() u[500] <- 0L # the change to u[500] can be done without copying g <- function (v) { v[1:(length(v)/2)] <- 1; get_rm(v) } u <- g(numeric(1000))  Radford Neal committed Jun 01, 2013 51 u[500] <- 9 # just one allocation of a vector of length 1000 will be done  Radford Neal committed Jun 01, 2013 52 53 54  A <- numeric(1000)+2 B <- numeric(1000)+3  Radford Neal committed Sep 12, 2018 55 A <- (get_rm(A)+1)*B # doesn't allocate space for a 3rd 1000-element vector  Radford Neal committed Jun 01, 2013 56 57 } \keyword{programming}