Doc/Manual/R.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <title>SWIG and R</title>
   5 <link rel="stylesheet" type="text/css" href="style.css">
   6 </head>
   7
   8 <body bgcolor="#ffffff">
   9 <H1><a name="R"></a>34 SWIG and R</H1>
  10 <!-- INDEX -->
  11 <div class="sectiontoc">
  12 <ul>
  13 <li><a href="#R_nn2">Bugs</a>
  14 <li><a href="#R_nn3">Using R and SWIG</a>
  15 <li><a href="#R_nn4">Precompiling large R files</a>
  16 <li><a href="#R_nn5">General policy</a>
  17 <li><a href="#R_language_conventions">Language conventions</a>
  18 <li><a href="#R_nn6">C++ classes</a>
  19 <li><a href="#R_nn7">Enumerations</a>
  20 </ul>
  21 </div>
  22 <!-- INDEX -->
  23
  24
  25
  26 <p>
  27 R is a GPL'ed open source statistical and plotting environment.
  28 Information about R can be found at <a
  29 href="http://www.r-project.org/">www.r-project.org</a>.
  30
  31 The R bindings are under active development.  They have been used to
  32 compile and run an R interface to QuantLib running on Mandriva Linux
  33 with gcc. The R bindings also work on Microsoft Windows using Visual C++.
  34 </p>
  35
  36 <H2><a name="R_nn2"></a>34.1 Bugs</H2>
  37
  38
  39 <p>
  40 Currently the following features are not implemented or broken:
  41 </p>
  42
  43 <ul>
  44 <li>Garbage collection of created objects
  45 <li>C Array wrappings
  46 </ul>
  47
  48 <H2><a name="R_nn3"></a>34.2 Using R and SWIG</H2>
  49
  50
  51 <p>
  52 To use R and SWIG in C mode, execute the following commands where
  53 example.c is the name of the file with the functions in them
  54 </p>
  55
  56 <div class="shell">
  57 <pre>
  58 swig -r example.i
  59 PKG_LIBS="example.c" R CMD SHLIB example_wrap.c
  60 </pre>
  61 </div>
  62
  63 <p>
  64 The corresponding comments for C++ mode are
  65 </p>
  66
  67 <div class="shell">
  68 <pre>
  69 swig -c++ -r -o example_wrap.cpp example.i
  70 PKG_LIBS="example.cxx" R CMD SHLIB example_wrap.cpp
  71 </pre>
  72 </div>
  73
  74 <p>
  75 Note that R is sensitive to the name of the file and to the file
  76 extension in C and C++ mode.  The name of the wrapper file must be the
  77 name of the library.  Also in C++ mode, the file extension must be .cpp
  78 rather than .cxx for the R compile command to recognize it.
  79 </p>
  80
  81 <p>
  82 The commands produces two files.  A dynamic shared object file called
  83 example.so, or example.dll, and an R wrapper file called example.R.  To load these
  84 files, start up R and type in the following commands
  85 </p>
  86
  87 <div class="shell">
  88 <pre>
  89 dyn.load(paste("example", .Platform$dynlib.ext, sep=""))
  90 source("example.R")
  91 cacheMetaData(1)
  92 </pre>
  93 </div>
  94
  95 The cacheMetaData(1) will cause R to refresh its object tables.
  96 Without it, inheritance of wrapped objects may fail.
  97
  98 <p>
  99 These two files can be loaded in any order
 100 </p>
 101
 102 <H2><a name="R_nn4"></a>34.3 Precompiling large R files</H2>
 103
 104
 105 In cases where the R file is large, one make save a lot of loading
 106 time by precompiling the R wrapper.  This can be done by creating the
 107 file makeRData.R which contains the following
 108
 109 <pre>
 110 source('BigFile.R')
 111 save(list=ls(all=TRUE),file="BigFile.RData", compress=TRUE)
 112 q(save="no")
 113 </pre>
 114
 115 This will generate a compiled R file called BigFile.RData that
 116 will save a large amount of loading time.
 117
 118
 119
 120 <H2><a name="R_nn5"></a>34.4 General policy</H2>
 121
 122
 123 <p>
 124 The general policy of the module is to treat the C/C++ as a basic
 125 wrapping over the underlying functions and rely on the R type system
 126 to provide R syntax.
 127 </p>
 128
 129 <H2><a name="R_language_conventions"></a>34.5 Language conventions</H2>
 130
 131
 132 <p>
 133 getitem and setitem use C++ conventions (i.e. zero based indices). [<-
 134 and [ are overloaded to allow for R syntax (one based indices and
 135 slices)
 136 </p>
 137
 138 <H2><a name="R_nn6"></a>34.6 C++ classes</H2>
 139
 140
 141 <p>
 142 C++ objects are implemented as external pointer objects with the class
 143 being the mangled name of the class. The C++ classes are encapsulated
 144 as an SEXP with an external pointer type. The class is the mangled
 145 name of the class. The nice thing about R is that is allows you to
 146 keep track of the pointer object which removes the necessity for a lot
 147 of the proxy class baggage you see in other languages.
 148 </p>
 149
 150 <H2><a name="R_nn7"></a>34.7 Enumerations</H2>
 151
 152
 153 <p>
 154 enumerations are characters which are then converted back and forth to
 155 ints before calling the C routines. All of the enumeration code is
 156 done in R.
 157 </p>
 158
 159 </body>
 160 </html>