Mercurial > pub > dyncall > bindings

comparison R/rdyncall/man/struct.Rd @ 0:0cfcc391201f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial from svn dyncall-1745
author Daniel Adler
date Thu, 19 Mar 2015 22:26:28 +0100
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:0cfcc391201f
1 \name{struct}
2 \alias{struct}
3 \alias{new.struct}
4 \alias{as.struct}
5 \alias{parseStructInfos}
6 \alias{parseUnionInfos}
7 \alias{$.struct}
8 \alias{print.struct}
9 \alias{$<-.struct}
10 \title{Allocation and handling of foreign C aggregate data types}
11 \description{Functions for allocation, access and registration of foreign C \code{struct} and \code{union} data type.}
12 \usage{
13 new.struct(type)
14 as.struct(x, type)
15 parseStructInfos(sigs, envir=parent.frame())
16 parseUnionInfos(sigs, envir=parent.frame())
17 \S3method{$}{struct}(x, index)
18 \S3method{$}{struct}(x, index) <- value
19 \S3method{print}{struct}(x, indent=0, \ldots)
20 }
21 \arguments{
22 \item{x}{external pointer or atomic raw vector of S3 class 'struct'.}
23 \item{type}{S3 \link{TypeInfo} Object or character string that names the structure type.}
24 \item{sigs}{character string that specifies several C struct/union type \link{signature}s.}
25 \item{envir}{the environment to install S3 type information object(s).}
26 \item{index}{character string specifying the field name.}
27 \item{indent}{indentation level for pretty printing structures.}
28 \item{value}{value to be converted according to struct/union field type given by field index.}
29 \item{...}{additional arguments to be passed to \code{\link[base]{print}} method.}
30 }
31 \details{
32 References to foreign C data objects are represented by objects of class 'struct'.
33
34 Two reference types are supported:
35
36 \itemize{
37 \item \emph{External pointers} returned by \code{\link{.dyncall}} using a call signature with a \emph{typed pointer} return type signature
38 and pointers extracted as a result of \code{\link{.unpack}} and S3 \code{struct} \code{$}-operators.
39 \item \emph{Internal objects}, memory-managed by R, are allocated by \code{new.struct}:
40 An atomic \code{raw} storage object is returned, initialized with length equal to the byte size of the
41 foreign C data type.
42 }
43
44 In order to access and manipulate the data fields of foreign C aggregate data objects, the \dQuote{$} and \dQuote{$<-} S3 operator methods
45 can be used.
46
47 S3 objects of class \code{struct} have an attribute \code{struct} set to the name of a \code{\link{TypeInfo}} object, which provides the
48 run-time type information of a particular foreign C type.
49
50 The run-time type information for foreign C \code{struct} and \code{union} types need to be registered once via
51 \code{parseStructInfos} and \code{parseUnionInfos} functions.
52 The C data types are specified by \code{sigs}, a signature character string. The formats for both types are described next:
53
54 \strong{Structure type signatures} describe the layout of aggregate \code{struct} C data types.
55 Type Signatures are used within the \sQuote{field-types}. \sQuote{field-names} consists of space separated identifier names and
56 should match the number of fields.
57
58 \tabular{c}{
59 \emph{struct-name} '\code{\{}' \emph{field-types} '\code{\}}' \emph{field-names} '\code{;}' \cr
60 }
61
62 Here is an example of a C \code{struct} type:
63
64 \preformatted{
65 struct Rect \{
66 signed short x, y;
67 unsigned short w, h;
68 \};
69 }
70
71 The corresponding structure type signature is:
72
73 \preformatted{"Rect\{ssSS\}x y w h;"}
74
75 \strong{Union type signatures} describe the components of the \code{union} C data type.
76 Type signatures are used within the \sQuote{field-types}. \sQuote{field-names} consists of space separated identifier names and
77 should match the number of fields.
78
79 \tabular{c}{
80 \emph{union-name} '\code{|}' \emph{field-types} '\code{\}}' \emph{field-names} '\code{;}' \cr
81 }
82
83 Here is an example of a C \code{union} type,
84
85 \preformatted{
86 union Value \{
87 int anInt;
88 float aFloat;
89 struct LongValue aStruct
90 \};
91 }
92
93 The corresponding union type signature is:
94
95 \code{"Value|if<LongValue>}anInt aFloat aStruct;"}
96
97 \code{as.struct} can be used to \emph{cast} a foreign C data reference to a different type.
98 When using an external pointer reference, this can lead quickly to a \strong{fatal R process crash} - like in C.
99 }
100 \seealso{
101 \code{\link{.dyncall}} for type signatures and \code{\link{TypeInfo}} for details on run-time type information S3 objects.
102 }
103 \examples{
104 # Specify the following foreign type:
105 # struct Rect {
106 # short x, y;
107 # unsigned short w, h;
108 # }
109 parseStructInfos("Rect{ssSS}x y w h;")
110 r <- new.struct(Rect)
111 print(r)
112 r$x <- 40
113 r$y <- 60
114 r$w <- 10
115 r$h <- 15
116 print(r)
117 str(r)
118 }
119 \keyword{programming}
120 \keyword{interface}