deref                  package:ref                  R Documentation

_d_e_r_e_f_e_r_e_n_c_i_n_g _r_e_f_e_r_e_n_c_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     This functions allow to access a referenced object. 'deref(ref)'
     returns the object, and 'deref(ref) <- value' assigns to the
     referenced object.

_U_s_a_g_e:

     deref(ref)
     deref<-(ref, value)
     #the following does not pass R CMD CHECK
     #deref(ref) <- value
     #deref(ref)[1] <- value  # subsetted assignment appears to be inefficent in S+.

_A_r_g_u_m_e_n_t_s:

     ref: a reference as returned by 'ref' or 'as.ref' 

_D_e_t_a_i_l_s:

     'deref' and 'deref<-' provide convenient access to objects in
     other environments/frames. In fact they are wrappers to 'get' and
     'assign'. However, convenient does not neccessarily means
     efficient. If performance is an issue, the direct use of
     'new.env', 'substitute' and 'eval' may give better results. See
     the examples below.

_V_a_l_u_e:

     'deref' returns the referenced object. 
      '"deref<-"' returns a reference to the modified object, see
     'ref'.

_N_o_t_e:

     Subsetted assignment appears to be inefficent in S+. Note the use
     of 'substitute' in the examples.

_A_u_t_h_o_r(_s):

     Jens Oehlschlgel

_R_e_f_e_r_e_n_c_e_s:

     Writing R Extensions

_S_e_e _A_l_s_o:

     'ref', 'as.ref',  'get',  'assign',  'substitute',  'eval'

_E_x_a_m_p_l_e_s:

       # Simple usage example
       x <- cbind(1:5, 1:5)          # take some object
       rx <- as.ref(x)               # wrap it into a reference
       deref(rx)                     # read it through the reference
       deref(rx) <- rbind(1:5, 1:5)  # replace the object in the reference by another one
       deref(rx)[1, ]                # read part of the object
       deref(rx)[1, ] <- 5:1         # replace part of the object
       deref(rx)                     # see the change
       cat("For examples how to pass by references see the Performance test examples at the help pages\n")

      ## Not run: 
       ## Performance test examples showing actually passing by reference
       # define test size
       nmatrix <- 1000   # matrix size of nmatrix by nmatrix
       nloop   <- 10     # you might want to use less loops in S+, you might want more in R versions before 1.8

       # Performance test using ref
       t1 <- function(){ # outer function
         m <- matrix(nrow=nmatrix, ncol=nmatrix)
         a <- as.ref(m)
           t2(a)
         m[1,1]
       }
       # subsetting deref is slower (by factor 75 slower since R 1.8 compared to previous versions, and much, much slower in S+) ...
       t2 <- function(ref){ # inner function
         cat("timing", timing.wrapper(
           for(i in 1:nloop)
             deref(ref)[1,1] <- i
         ), "\n")
       }
       if (is.R())gc()
       t1()
       # ... than using substitute
       t2 <- function(ref){
         obj <- as.name(ref$name)
         loc <- ref$loc
         cat("timing", timing.wrapper(
           for(i in 1:nloop)
             eval(substitute(x[1,1] <- i, list(x=obj, i=i)), loc)
         ), "\n")
       }
       if (is.R())gc()
       t1()

       # Performance test using Object (R only)
       # see Henrik Bengtsson package(oo)
       Object <- function(){
         this <- list(env.=new.env());
         class(this) <- "Object";
         this;
       }
       "$.Object" <- function(this, name){
         get(name, envir=unclass(this)$env.);
       }
       "$<-.Object" <- function(this, name, value){
         assign(name, value, envir=unclass(this)$env.);
         this;
       }
       # outer function
       t1 <- function(){
         o <- Object()
         o$m <- matrix(nrow=nmatrix, ncol=nmatrix)
           t2(o)
         o$m[1,1]
       }
       # subsetting o$m is slower ...
       t2 <- function(o){
         cat("timing", timing.wrapper(
           for(i in 1:nloop)
             o$m[1,1] <- i
         ), "\n")
       }
       if (is.R())gc()
       t1()
       # ... than using substitute
       t2 <- function(o){
         env <- unclass(o)$env.
         cat("timing", timing.wrapper(
           for(i in 1:nloop)
             eval(substitute(m[1,1] <- i, list(i=i)), env)
         ), "\n")
       }
       if (is.R())gc()
       t1()

       ## End(Not run)

