ref                   package:ref                   R Documentation

_c_r_e_a_t_i_n_g _r_e_f_e_r_e_n_c_e_s

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

     Package 'ref' implements references for S (R/S+). Function 'ref'
     creates references. For a memory efficient wrapper to matrixes and
     data.frames which allows nested subsetting see 'refdata'

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

     ref(name, loc = parent.frame())

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

    name: name of an (existing) object to be referenced 

     loc: location of the referenced object, i.e. an environment in R
          or a frame in S+ 

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

     In S (R/S+) paramters are passed by value and not by reference.
     When passing big objects, e.g. in recursive algorithms, this can
     quickly eat up memory. The functions of package 'ref' allow to
     pass references in function calls. The implementation is purely S
     and should work in R and S+. Existence of the referenced object is
     not checked by function 'ref'. Usually 'as.ref' is more convenient
     and secure to use. There is also a print method for references.

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

     a list with 

   name : name of the referenced object 

    loc : location of the referenced object, i.e. an environment in R
          or a frame in S+ 

     and class "ref"

_W_A_R_N_I_N_G:

     Usually functions in S have no side-effects except for the main
     effect of returning something. Working with references circumvents
     this programming style and can have considerable side-effects. You
     are using it at your own risk.

_R _1._8 _W_A_R_N_I_N_G:

     Changing parts of referenced objects has been slowed down by order
     of magnitudes since R version 1.8 (see performance test examples
     on the help page for {codederef

_S+ _W_A_R_N_I_N_G:

     Package ref should generally work under R and S+. However, when
     changing very small parts of referenced objects, using references
     under S+ might be inefficient (very slow with high temporary
     memory requirements).

_H_i_s_t_o_r_i_c_a_l _r_e_m_a_r_k_s:

     This package goes back to an idea submitted April 9th 1997 and
     code offered on August 17th 1997 on s-news. The idea of
     implementing references in S triggered an intense discussion on
     s-news. The status reached in 1997 can be summarized as follows:

   *_a_d_v_a_n_t_a_g_e* passing by reference can save memory compared to passing
        by value

   *_d_i_s_a_d_v_a_n_t_a_g_e* passing by reference is more dangerous than passing
        by value

   *_h_o_w_e_v_e_r* the implementation is purely in S, thus rather channels
        existing danger than adding new danger

   *_r_e_s_t_r_i_c_t_i_o_n* assigning to a subsetted part of a referenced object
        was inefficient in S+ (was S+ version 3)

     Due to the last restriction the code was never submitted as a
     mature library. Now in 2003 we have a stable version of R and
     astonishingly assigning to a subsetted part of a referenced object
     _can_ be implemented efficient. This shows what a great job the R
     core developers have done. In the current version the set of
     functions for references was dramatically simplified, the main
     differences to 1997 beeing the following:

   *_n_o _i_d_e_m_p_o_t_e_n_c_e* 'deref' and  'deref<-' now are a simple function
        and no longer are methods. This decision was made due top
        performance reasons. As a consequence, 'deref()' no longer is
        idempotent: one has to know whether an object is a reference.
        Function 'is.ref' provides a test. 

   *_n_o _w_r_i_t_e _p_r_o_t_e_c_t_i_o_n* The 1997 suggestion included a write
        protection attribute of references, allowing for read only
        references and allowing for references that could only be
        changed by functions that knwe the access code. Reasons for
        this: there is no need for readonly references (due to copy on
        modify) and oop provides better mechanisms for security. 

   *_n_o _s_t_a_t_i_c _v_a_r_i_a_b_l_e_s* The suggestion made in 1997 did include an
        implementation of static variables realized as special cases of
        references with a naming convention which reduced the risc of
        name collisions in the 1997 practice of assigning to frame 0.
        Now R has namespaces and the oop approach of Henrik Bengtsson
        using environments is to be prefered over relatively global
        static objects. 

_N_o_t_e:

     Using this type of references is fine for prototyping in a
     non-objectoriented programming style. For bigger projects and
     safer programming you should consider the approach suggested by
     Henrik Bengtsson at <URL:
     http://www.maths.lth.se/help/R/ImplementingReferences> (announced
     to be released as package "oo" or "classes")

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

     Jens Oehlschlgel

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

     'as.ref', 'deref', 'deref<-', 'exists.ref', 'is.ref', 'print.ref',
     'HanoiTower'

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

       v <- 1
       r <- ref("v")
       r
       deref(r)
       cat("For more examples see ?deref\n")

