SWIG: Doc/Manual/R.html

"Fossies" - the Fresh Open Source Software Archive

Member "swig-4.1.1/Doc/Manual/R.html" (30 Nov 2022, 9806 Bytes) of package /linux/misc/swig-4.1.1.tar.gz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2 <html> 3 <head> 4 <title>SWIG and R</title> 5 <link rel="stylesheet" type="text/css" href="style.css"> 6 <meta http-equiv="content-type" content="text/html; charset=UTF-8"> 7 </head> 8 9 <body bgcolor="#ffffff"> 10 <H1><a name="R">34 SWIG and R</a></H1> 11  12 <div class="sectiontoc"> 13 <ul> 14 <li><a href="#R_nn2">Bugs</a> 15 <li><a href="#R_nn3">Using R and SWIG</a> 16 <li><a href="#R_nn4">Precompiling large R files</a> 17 <li><a href="#R_nn5">General policy</a> 18 <li><a href="#R_language_conventions">Language conventions</a> 19 <li><a href="#R_nn6">C++ classes</a> 20 <ul> 21 <li><a href="#R_class_examples">Examples</a> 22 </ul> 23 <li><a href="#R_nn7">Enumerations</a> 24 </ul> 25 </div> 26  27 28 29 30 <p> 31 R is a GPL'ed open source statistical and plotting environment. 32 Information about R can be found at <a 33 href="https://www.r-project.org/">www.r-project.org</a>. 34 </p> 35 36 <p> 37 The R bindings are under active development. They have been used to 38 compile and run an R interface to QuantLib running on Mandriva Linux 39 with gcc. They are also used to create the SimpleITK R package, which 40 runs on Linux and MacOS. SWIG is used to create all wrapper 41 interfaces 42 to <a href="https://www.simpleitk.org/">SimpleITK</a>. The R 43 bindings also work on Microsoft Windows using Visual C++. 44 </p> 45 46 <H2><a name="R_nn2">34.1 Bugs</a></H2> 47 48 49 <p> 50 Currently the following features are not implemented or broken: 51 </p> 52 53 <ul> 54 <li>Garbage collection of some created objects. Finalizers are 55 available for wrapped C++ classes and are called by the 56 garbage collection system. 57 <li>C Array wrappings 58 </ul> 59 60 <H2><a name="R_nn3">34.2 Using R and SWIG</a></H2> 61 62 63 <p> 64 To use R and SWIG in C mode, execute the following commands where 65 example.c is the name of the file with the functions in them 66 </p> 67 68 <div class="shell"> 69 <pre> 70 swig -r example.i 71 R CMD SHLIB example_wrap.c example.c 72 </pre> 73 </div> 74 75 <p> 76 The corresponding options for C++ mode are 77 </p> 78 79 <div class="shell"> 80 <pre> 81 swig -c++ -r -o example_wrap.cpp example.i 82 R CMD SHLIB example_wrap.cpp example.cpp 83 </pre> 84 </div> 85 86 <p> 87 Note that R is sensitive to the names of the files. 88 The name of the wrapper file must be the 89 name of the library unless you use the -o option to R when building the library, for example: 90 </p> 91 92 <div class="shell"> 93 <pre> 94 swig -c++ -r -o example_wrap.cpp example.i 95 R CMD SHLIB -o example.so example_wrap.cpp example.cpp 96 </pre> 97 </div> 98 99 <p> 100 R is also sensitive to the name of the file 101 extension in C and C++ mode. In C++ mode, the file extension must be .cpp 102 rather than .cxx for the R compile command to recognize it. If your C++ code is 103 in a file using something other than a .cpp extension, then it may still work using PKG_LIBS: 104 </p> 105 106 <div class="shell"> 107 <pre> 108 swig -c++ -r -o example_wrap.cpp example.i 109 PKG_LIBS="example.cxx" R CMD SHLIB -o example example_wrap.cpp 110 </pre> 111 </div> 112 113 <p> 114 The commands produces two files. A dynamic shared object file called 115 example.so, or example.dll, and an R wrapper file called example.R. To load these 116 files, start up R and type in the following commands 117 </p> 118 119 <div class="shell"> 120 <pre> 121 dyn.load(paste("example", .Platform$dynlib.ext, sep="")) 122 source("example.R") 123 cacheMetaData(1) 124 </pre> 125 </div> 126 127 <p> 128 The cacheMetaData(1) will cause R to refresh its object tables. 129 Without it, inheritance of wrapped objects may fail. 130 These two files can be loaded in any order. 131 </p> 132 133 <p> 134 If you are compiling code yourself (not using R itself), there are a few things to watch out for: 135 </p> 136 137 <ul> 138 <li>The output shared library name (to the left of the file extension) MUST match the module name, or alternatively, you can also set the -package NAME command line argument. See swig -r -help for more information 139 <li>If you do not set the output file name appropriately, you might see errors like 140 <div class="shell"> 141 <pre> 142 > fact(4) 143 Error in .Call("R_swig_fact", s_arg1, as.logical(.copy), PACKAGE = "example") : 144 "R_swig_fact" not available for .Call() for package "example" 145 </pre> 146 </div> 147 <li>Make sure the architecture of the shared library(x64 for instance), matches the architecture of the R program you want to load your shared library into 148 </ul> 149 150 <H2><a name="R_nn4">34.3 Precompiling large R files</a></H2> 151 152 153 <p> 154 In cases where the R file is large, one make save a lot of loading 155 time by precompiling the R wrapper. This can be done by creating the 156 file makeRData.R which contains the following 157 </p> 158 159 <div class="code"><pre> 160 source('BigFile.R') 161 save(list=ls(all=TRUE), file="BigFile.RData", compress=TRUE) 162 q(save="no") 163 </pre></div> 164 165 <p> 166 This will generate a compiled R file called BigFile.RData that 167 will save a large amount of loading time. 168 </p> 169 170 <p> 171 There is no need to precompile large R files if the SWIG-generated code is being included 172 in an R package. The package infrastructure provides this service during package installation. 173 </p> 174 175 <H2><a name="R_nn5">34.4 General policy</a></H2> 176 177 178 <p> 179 The general policy of the module is to treat the C/C++ as a basic 180 wrapping over the underlying functions and rely on the R type system 181 to provide R syntax. 182 </p> 183 184 <H2><a name="R_language_conventions">34.5 Language conventions</a></H2> 185 186 187 <p> 188 getitem and setitem use C++ conventions (i.e. zero based indices). [<- 189 and [ are overloaded to allow for R syntax (one based indices and 190 slices) 191 </p> 192 193 <H2><a name="R_nn6">34.6 C++ classes</a></H2> 194 195 196 <p> 197 Wrapping of C++ classes for R works quite well. R has a special 198 type, known as an external reference, that can be used as a pointer 199 to arbitrary things, including C++ classes. The proxy layers generated 200 for other classes are not required. 201 </p> 202 203 <p> 204 SWIG currently creates a custom hierarchy of R classes derived from the 205 external reference type and implements 206 type checking and function overloading in the R code it generates. In 207 the future we hope to utilise the built in R6 class structures. 208 </p> 209 210 <p> 211 The R interface has the following capabilities: 212 </p> 213 <ul> 214 <li> Destructor methods are registered and called automatically by the R garbage collector. 215 <li> A range of std::vector types are converted automatically to R equivalents via the std_vector.i library. 216 <li> The $ operator is used for method access. 217 <li> Variable accessors are automatically generated and called via the $, [, [[, $<-, [<-, [[<- operators. 218 </ul> 219 220 <H3><a name="R_class_examples">34.6.1 Examples</a></H3> 221 222 223 <p> 224 Consider the following simple example: 225 </p> 226 227 <div class="code"> 228 <pre> 229 class Vehicle { 230 private: 231 int m_axles; 232 233 public: 234 int Axles() { 235 return(m_axles); 236 } 237 238 bool Available; 239 240 Vehicle() { 241 Available=false; 242 m_axles=2; 243 } 244 245 Vehicle(int ax) { 246 Available=false; 247 m_axles=ax; 248 } 249 }; 250 </pre> 251 </div> 252 253 <p> 254 The following options are available in R: 255 </p> 256 257 <div class="code"> 258 <pre> 259 v1 <- Vehicle() 260 v2 <- Vehicle(4) 261 # access members 262 v1$Axles() 263 [1] 2 264 v2$Axles 265 [1] 4 266 v1$Available 267 [1] FALSE 268 # Set availability 269 v1$Available <- TRUE 270 v1$Available 271 [1] TRUE 272 </pre> 273 </div> 274 275 <p> 276 A useful trick to determine the methods that are available is to 277 query the R method definition as follows: 278 </p> 279 280 <div class="code"> 281 <pre> 282 # display the methods for the class 283 getMethod("$", class(v1)) 284 285 Method Definition: 286 287 function (x, name) 288 { 289 accessorFuns = list(Axles = Vehicle_Axles, Available = Vehicle_Available_get) 290 vaccessors = c("Available") 291 idx = pmatch(name, names(accessorFuns)) 292 if (is.na(idx)) 293 return(callNextMethod(x, name)) 294 f = accessorFuns[[idx]] 295 if (is.na(match(name, vaccessors))) 296 function(...) { 297 f(x, ...) 298 } 299 else f(x) 300 } 301 302 Signatures: 303 x 304 target "_p_Vehicle" 305 defined "_p_Vehicle" 306 307 </pre> 308 </div> 309 <p> 310 The names in the <tt>accessorFuns</tt> list correspond to class methods while names in the <tt>vaccessors</tt> section 311 correspond to variables that may be modified. 312 </p> 313 <H2><a name="R_nn7">34.7 Enumerations</a></H2> 314 315 316 <p> 317 R doesn't have a native enumeration type. Enumerations are represented 318 as character strings in R, with calls to R functions that convert back 319 and forth between integers. 320 </p> 321 322 <p> 323 The details of enumeration names and contents are stored in hidden R 324 environments, which are named according to the enumeration name - for 325 example, an enumeration colour: 326 </p> 327 328 <div class="code"><pre> 329 enum colour { red=-1, blue, green = 10 }; 330 </pre></div> 331 332 <p> 333 will be initialized by the following call in R: 334 </p> 335 336 <div class="code"><pre> 337 defineEnumeration("_colour", 338 .values=c("red" = .Call('R_swig_colour_red_get',FALSE, PACKAGE='enum_thorough'), 339 "blue" = .Call('R_swig_colour_blue_get',FALSE, PACKAGE='enum_thorough'), 340 "green" = .Call('R_swig_colour_green_get',FALSE, PACKAGE='enum_thorough'))) 341 </pre></div> 342 343 <p> 344 which will create an environment named <tt>.__E___colour</tt>. The enumeration 345 values are initialised via calls to C/C++ code, allowing complex 346 values for enumerations to be used. Calls to the C/C++ code require 347 the compiled library to be loaded, so a <tt>delayedAssign</tt> is employed 348 within <tt>defineEnumeration</tt> in order to allow the code to be easily used in R 349 packages. 350 </p> 351 352 <p> 353 The user typically does not need to access the enumeration lookup 354 functions or know the name of the enumeration type used by 355 R. Attributes containing the type information are attached by swig to 356 functions requiring enumeration arguments or returning enumeration 357 values, and those attributes are used to identify and access the 358 appropriate environments and thus translate between characters 359 and integers. 360 </p> 361 362 <p> 363 The relevant functions, for debugging purposes, are <tt>enumToInteger</tt> and 364 <tt>enumFromInteger</tt>. 365 </p> 366 367 <p> 368 Anonymous enumerations are ignored by the binding generation process, 369 leaving no way of accessing the value of anonymous enumerations from R 370 code. 371 </p> 372 373 </body> 374 </html>