PageRenderTime 48ms CodeModel.GetById 20ms RepoModel.GetById 0ms app.codeStats 0ms

/trunk/Doc/Manual/R.html

#
HTML | 180 lines | 135 code | 43 blank | 2 comment | 0 complexity | 576bdabafab6ca1224e0268ed1e53705 MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0 
    

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
    2. 

  2. <html>
    3. 

  3. <head>
    4. 

  4. <title>SWIG and R</title>
    5. 

  5. <link rel="stylesheet" type="text/css" href="style.css">
    6. 

  6. </head>
    7. 

  7. 

  8. <body bgcolor="#ffffff">
    9. 

  9. <H1><a name="R"></a>35 SWIG and R</H1>
    10. 

  10. <!-- INDEX -->
    11. 

  11. <div class="sectiontoc">
    12. 

  12. <ul>
    13. 

  13. <li><a href="#R_nn2">Bugs</a>
    14. 

  14. <li><a href="#R_nn3">Using R and SWIG</a>
    15. 

  15. <li><a href="#R_nn4">Precompiling large R files</a>
    16. 

  16. <li><a href="#R_nn5">General policy</a>
    17. 

  17. <li><a href="#R_language_conventions">Language conventions</a>
    18. 

  18. <li><a href="#R_nn6">C++ classes</a>
    19. 

  19. <li><a href="#R_nn7">Enumerations</a>
    20. 

  20. </ul>
    21. 

  21. </div>
    22. 

  22. <!-- INDEX -->
    23. 

  23. 

  24. 

  25. 

  26. <p>
    27. 

  27. R is a GPL'ed open source statistical and plotting environment.
    28. 

  28. Information about R can be found at <a
    29. 

  29. href="http://www.r-project.org/">www.r-project.org</a>.
    30. 

  30. 

  31. The R bindings are under active development.  They have been used to
    32. 

  32. compile and run an R interface to QuantLib running on Mandriva Linux
    33. 

  33. with gcc. The R bindings also work on Microsoft Windows using Visual C++.
    34. 

  34. </p>
    35. 

  35. 

  36. <H2><a name="R_nn2"></a>35.1 Bugs</H2>
    37. 

  37. 

  38. 

  39. <p>
    40. 

  40. Currently the following features are not implemented or broken:
    41. 

  41. </p>
    42. 

  42. 

  43. <ul>
    44. 

  44. <li>Garbage collection of created objects
    45. 

  45. <li>C Array wrappings
    46. 

  46. </ul>
    47. 

  47. 

  48. <H2><a name="R_nn3"></a>35.2 Using R and SWIG</H2>
    49. 

  49. 

  50. 

  51. <p>
    52. 

  52. To use R and SWIG in C mode, execute the following commands where
    53. 

  53. example.c is the name of the file with the functions in them
    54. 

  54. </p>
    55. 

  55. 

  56. <div class="shell">
    57. 

  57. <pre>
    58. 

  58. swig -r example.i
    59. 

  59. R CMD SHLIB example_wrap.c example.c
    60. 

  60. </pre>
    61. 

  61. </div>
    62. 

  62. 

  63. <p>
    64. 

  64. The corresponding options for C++ mode are
    65. 

  65. </p>
    66. 

  66. 

  67. <div class="shell">
    68. 

  68. <pre>
    69. 

  69. swig -c++ -r -o example_wrap.cpp example.i
    70. 

  70. R CMD SHLIB example_wrap.cpp example.cpp
    71. 

  71. </pre>
    72. 

  72. </div>
    73. 

  73. 

  74. <p>
    75. 

  75. Note that R is sensitive to the names of the files.
    76. 

  76. The name of the wrapper file must be the
    77. 

  77. name of the library unless you use the -o option to R when building the library, for example:
    78. 

  78. </p>
    79. 

  79. 

  80. <div class="shell">
    81. 

  81. <pre>
    82. 

  82. swig -c++ -r -o example_wrap.cpp example.i
    83. 

  83. R CMD SHLIB -o example.so example_wrap.cpp example.cpp
    84. 

  84. </pre>
    85. 

  85. </div>
    86. 

  86. 

  87. <p>
    88. 

  88. R is also sensitive to the name of the file 
    89. 

  89. extension in C and C++ mode. In C++ mode, the file extension must be .cpp
    90. 

  90. rather than .cxx for the R compile command to recognize it. If your C++ code is 
    91. 

  91. in a file using something other than a .cpp extension, then it may still work using PKG_LIBS:
    92. 

  92. </p>
    93. 

  93. 

  94. <div class="shell">
    95. 

  95. <pre>
    96. 

  96. swig -c++ -r -o example_wrap.cpp example.i
    97. 

  97. PKG_LIBS="example.cxx" R CMD SHLIB -o example example_wrap.cpp
    98. 

  98. </pre>
    99. 

  99. </div>
    100. 

  100. 

  101. <p>
    102. 

  102. The commands produces two files.  A dynamic shared object file called
    103. 

  103. example.so, or example.dll, and an R wrapper file called example.R.  To load these
    104. 

  104. files, start up R and type in the following commands
    105. 

  105. </p>
    106. 

  106. 

  107. <div class="shell">
    108. 

  108. <pre>
    109. 

  109. dyn.load(paste("example", .Platform$dynlib.ext, sep=""))
    110. 

  110. source("example.R")
    111. 

  111. cacheMetaData(1)
    112. 

  112. </pre>
    113. 

  113. </div>
    114. 

  114. 

  115. The cacheMetaData(1) will cause R to refresh its object tables.
    116. 

  116. Without it, inheritance of wrapped objects may fail.
    117. 

  117. 

  118. <p>
    119. 

  119. These two files can be loaded in any order
    120. 

  120. </p>
    121. 

  121. 

  122. <H2><a name="R_nn4"></a>35.3 Precompiling large R files</H2>
    123. 

  123. 

  124. 

  125. In cases where the R file is large, one make save a lot of loading
    126. 

  126. time by precompiling the R wrapper.  This can be done by creating the
    127. 

  127. file makeRData.R which contains the following
    128. 

  128. 

  129. <pre>
    130. 

  130. source('BigFile.R')
    131. 

  131. save(list=ls(all=TRUE),file="BigFile.RData", compress=TRUE)
    132. 

  132. q(save="no")
    133. 

  133. </pre>
    134. 

  134. 

  135. This will generate a compiled R file called BigFile.RData that
    136. 

  136. will save a large amount of loading time.
    137. 

  137. 

  138. 

  139. 

  140. <H2><a name="R_nn5"></a>35.4 General policy</H2>
    141. 

  141. 

  142. 

  143. <p>
    144. 

  144. The general policy of the module is to treat the C/C++ as a basic
    145. 

  145. wrapping over the underlying functions and rely on the R type system
    146. 

  146. to provide R syntax.
    147. 

  147. </p>
    148. 

  148. 

  149. <H2><a name="R_language_conventions"></a>35.5 Language conventions</H2>
    150. 

  150. 

  151. 

  152. <p>
    153. 

  153. getitem and setitem use C++ conventions (i.e. zero based indices). [<-
    154. 

  154. and [ are overloaded to allow for R syntax (one based indices and
    155. 

  155. slices)
    156. 

  156. </p>
    157. 

  157. 

  158. <H2><a name="R_nn6"></a>35.6 C++ classes</H2>
    159. 

  159. 

  160. 

  161. <p>
    162. 

  162. C++ objects are implemented as external pointer objects with the class
    163. 

  163. being the mangled name of the class. The C++ classes are encapsulated
    164. 

  164. as an SEXP with an external pointer type. The class is the mangled
    165. 

  165. name of the class. The nice thing about R is that is allows you to
    166. 

  166. keep track of the pointer object which removes the necessity for a lot
    167. 

  167. of the proxy class baggage you see in other languages.
    168. 

  168. </p>
    169. 

  169. 

  170. <H2><a name="R_nn7"></a>35.7 Enumerations</H2>
    171. 

  171. 

  172. 

  173. <p>
    174. 

  174. enumerations are characters which are then converted back and forth to
    175. 

  175. ints before calling the C routines. All of the enumeration code is
    176. 

  176. done in R.
    177. 

  177. </p>
    178. 

  178. 

  179. </body>
    180. 

  180. </html>
    181. 

  181.