annotate R/rdyncall/man/packing.Rd @ 15:1673ab696715

- erlang binding ToDo update in readme
author cslag
date Sat, 26 Mar 2016 16:09:41 +0100
parents 0cfcc391201f
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
1 \name{packing}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
2 \alias{.pack}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
3 \alias{packing}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
4 \alias{.unpack}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
5 \title{Handling of foreign C fundamental data types}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
6 \description{Functions to unpack/pack (read/write) foreign C data types from/to R atomic vectors and C data objects such as arrays and pointers to structures.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
7 \usage{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
8 .pack(x, offset, sigchar, value)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
9 .unpack(x, offset, sigchar)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
10 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
11 \arguments{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
12 \item{x}{atomic vector (logical, raw, integer or double) or external pointer.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
13 \item{offset}{integer specifying \emph{byte offset} starting at 0.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
14 \item{sigchar}{character string specifying the C data type by a \link{type signature}.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
15 \item{value}{R object value to be coerced and packed to a foreign C data type.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
16 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
17 \details{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
18 The function \code{.pack} converts an R \code{value} into a C data type specified by the \link{signature} \code{sigchar}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
19 and it writes the raw C foreign data value at byte position \code{offset} into the object \code{x}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
20 The function \code{.unpack} extracts a C data type according to the \link{signature} \code{sigchar}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
21 at byte position \code{offset} from the object \code{x} and converts the C value to an R value and returns it.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
22
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
23 Byte \code{offset} calculations start at 0 relative to the first byte in an atomic vectors data area.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
24
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
25 If \code{x} is an atomic vector, a bound check is carried out before read/write access.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
26 Otherwise, if \code{x} is an external pointer, there is only a C NULL pointer check.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
27 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
28 \value{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
29 \code{.unpack} returns a read C data type coerced to an R value.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
30 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
31 \seealso{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
32 \code{\link{.dyncall}} for details on type signatures.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
33 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
34 \examples{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
35 # transfer double to array of floats and back, compare precision:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
36 n <- 6
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
37 input <- rnorm(n)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
38 buf <- raw(n*4)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
39 for (i in 1:n) {
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
40 .pack(buf, 4*(i-1), "f", input[i])
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
41 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
42 output <- numeric(n)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
43 for (i in 1:n) {
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
44 output[i] <- .unpack(buf, 4*(i-1), "f")
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
45 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
46 # difference between double and float
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
47 difference <- output-input
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
48 print( cbind(input,output,difference) )
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
49 }