annotate R/rdyncall/man/utils.Rd @ 3:f5d4d5c2f750

- gemspec fix
author cslag
date Thu, 31 Dec 2015 20:24:53 +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{utils}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
2 \alias{is.nullptr}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
3 \alias{as.extptr}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
4 \alias{is.externalptr}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
5 \alias{floatraw}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
6 \alias{as.floatraw}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
7 \alias{floatraw2numeric}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
8 \alias{ptr2str}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
9 \alias{strarrayptr}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
10 \alias{strptr}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
11 \alias{offsetPtr}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
12 \title{Utility functions for working with foreign C data types}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
13 \description{Functions for low-level operations on C pointers as well as
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
14 helper functions and objects to handle C \code{float} arrays and strings.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
15 \usage{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
16 is.nullptr(x)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
17 as.extptr(x)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
18 is.externalptr(x)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
19 floatraw(n)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
20 as.floatraw(x)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
21 floatraw2numeric(x)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
22 ptr2str(x)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
23 strarrayptr(x)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
24 strptr(x)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
25 offsetPtr(x, offset)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
26 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
27 \arguments{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
28 \item{x}{an R object.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
29 \item{n}{number of elements to allocate.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
30 \item{offset}{a offset given in bytes.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
31 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
32 \details{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
33
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
34 \code{is.nullptr} tests if the external pointer given by \code{x} represents a C \code{NULL} pointer.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
35
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
36 \code{as.extptr} returns an external pointer to the data area of atomic
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
37 vector given by \code{x}. The external pointer holds an additional reference
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
38 to the \code{x} R object to prevent it from garbage collection.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
39
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
40 \code{is.externalptr} tests if the object given by \code{x} is an external pointer.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
41
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
42 \code{floatraw} creates an array with a capacity to store \code{n} single-precision C \code{float} values.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
43 The array is implemented via a \code{\link[base]{raw}} vector.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
44
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
45 \code{as.floatraw} coerces a numeric vector into a single-precision C \code{float} vector.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
46 Values given by \code{x} are converted to C \code{float} values and stored in the R raw vector via \code{.pack}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
47 This function is useful when calling foreign functions that expeect a C \code{float} pointer via \code{\link{.dyncall}}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
48
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
49 \code{floatraw2numeric} coerces a C \code{float} (raw) vector to a numeric vector.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
50
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
51 \code{ptr2str}, \code{strarrayptr}, \code{strptr} are currently experimental.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
52
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
53 \code{offsetPtr} creates a new external pointer pointing to \code{x} plus the byte \code{offset}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
54 If \code{x} is given as an external pointer, the address is increased by the \code{offset},
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
55 or, if \code{x} is given as a atomic vector, the address of the data (pointing to offset zero) is taken as basis
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
56 and increased by the \code{offset}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
57 The returned external pointer is protected (as offered by the C function \code{R_MakeExternalPtr}) by the external pointer \code{x}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
58 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
59 \value{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
60 A logical value is returned by \code{is.nullptr} and \code{is.externalptr}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
61 \code{as.extptr} returns an external pointer value.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
62 \code{floatraw} and \code{as.floatraw} return an atomic vector of type \code{raw}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
63 tagged with class \code{'floatraw'}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
64 \code{floatraw2numeric} returns a \code{numeric} atomic vector.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
65 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
66 \keyword{programming}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
67 \keyword{interface}