SCM

SCM Repository

[ihelp] Annotation of /src/manual/R-ints-ko.po
ViewVC logotype

Annotation of /src/manual/R-ints-ko.po

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1613 - (view) (download)

1 : gnustats 1339 # Korean translations for R-manual-translation-ko package
2 :     # Copyright (C) 2014 Chel Hee Lee
3 :     # This file is distributed under the same license as the R-manual-translation-ko package.
4 :     # Automatically generated, 2014.
5 :     #
6 :     msgid ""
7 :     msgstr ""
8 :     "Project-Id-Version: R-manual-translation-ko 0.3.0.1\n"
9 :     "Report-Msgid-Bugs-To: chl948@mail.usask.ca\n"
10 : gnustats 1340 "POT-Creation-Date: 2015-01-06 18:16-0600\n"
11 : gnustats 1613 "PO-Revision-Date: 2015-01-10 08:38-0600\n"
12 : gnustats 1339 "Last-Translator: Chel Hee Lee <chl948@mail.usask.ca>\n"
13 :     "Language-Team: Chel Hee Lee <chl948@mail.usask.ca>\n"
14 :     "Language: ko\n"
15 :     "MIME-Version: 1.0\n"
16 :     "Content-Type: text/plain; charset=UTF-8\n"
17 :     "Content-Transfer-Encoding: 8bit\n"
18 :     "Plural-Forms: nplurals=1; plural=0;\n"
19 :    
20 :     #. type: top
21 :     #: R-ints.texi:4
22 :     #: R-ints.texi:33
23 :     #: R-ints.texi:51
24 :     #, no-wrap
25 :     msgid "R Internals"
26 :     msgstr ""
27 :    
28 :     #. type: dircategory
29 :     #: R-ints.texi:12
30 :     #, no-wrap
31 :     msgid "Programming"
32 :     msgstr ""
33 :    
34 :     #. type: menuentry
35 :     #: R-ints.texi:15
36 :     msgid "R Internals: (R-ints)"
37 :     msgstr ""
38 :    
39 :     #. type: menuentry
40 :     #: R-ints.texi:15
41 :     msgid "R Internals."
42 :     msgstr ""
43 :    
44 :     #. type: include
45 :     #: R-ints.texi:19
46 :     #, no-wrap
47 :     msgid "R-defs.texi"
48 :     msgstr ""
49 :    
50 :     #. type: include
51 :     #: R-ints.texi:20
52 :     #, no-wrap
53 :     msgid "version.texi"
54 :     msgstr ""
55 :    
56 :     #. type: copying
57 :     #: R-ints.texi:24
58 :     msgid "This manual is for R, version @value{VERSION}."
59 :     msgstr ""
60 :    
61 :     #. type: copying
62 :     #: R-ints.texi:26
63 :     msgid "@Rcopyright{1999}"
64 :     msgstr ""
65 :    
66 :     #. type: quotation
67 :     #: R-ints.texi:29
68 :     msgid "@permission{}"
69 :     msgstr ""
70 :    
71 :     #. type: subtitle
72 :     #: R-ints.texi:34
73 :     #, no-wrap
74 :     msgid "Version @value{VERSION}"
75 :     msgstr ""
76 :    
77 :     #. type: author
78 :     #: R-ints.texi:35
79 :     #, no-wrap
80 :     msgid "R Core Team"
81 :     msgstr ""
82 :    
83 :     #. type: node
84 :     #: R-ints.texi:50
85 :     #: R-ints.texi:78
86 :     #: R-ints.texi:1947
87 :     #: R-ints.texi:2333
88 :     #: R-ints.texi:2461
89 :     #: R-ints.texi:2612
90 :     #: R-ints.texi:2698
91 :     #: R-ints.texi:3585
92 :     #: R-ints.texi:3747
93 :     #: R-ints.texi:4119
94 :     #: R-ints.texi:4252
95 :     #: R-ints.texi:4266
96 :     #: R-ints.texi:4310
97 :     #: R-ints.texi:4477
98 :     #: R-ints.texi:4482
99 :     #, no-wrap
100 :     msgid "Top"
101 :     msgstr ""
102 :    
103 :     #. type: node
104 :     #: R-ints.texi:50
105 :     #: R-ints.texi:75
106 :     #: R-ints.texi:78
107 :     #: R-ints.texi:79
108 :     #: R-ints.texi:110
109 :     #: R-ints.texi:528
110 :     #: R-ints.texi:667
111 :     #: R-ints.texi:772
112 :     #: R-ints.texi:865
113 :     #: R-ints.texi:1021
114 :     #: R-ints.texi:1076
115 :     #: R-ints.texi:1121
116 :     #: R-ints.texi:1229
117 :     #: R-ints.texi:1307
118 :     #: R-ints.texi:1326
119 :     #: R-ints.texi:1376
120 :     #: R-ints.texi:1547
121 :     #: R-ints.texi:1701
122 :     #: R-ints.texi:1758
123 :     #: R-ints.texi:1796
124 :     #: R-ints.texi:1883
125 :     #: R-ints.texi:1947
126 :     #, no-wrap
127 :     msgid "R Internal Structures"
128 :     msgstr ""
129 :    
130 :     #. type: node
131 :     #: R-ints.texi:50
132 :     #, no-wrap
133 :     msgid "(dir)"
134 :     msgstr ""
135 :    
136 :     #. type: ifnottex
137 :     #: R-ints.texi:55
138 : gnustats 1340 msgid ""
139 :     "This is a guide to the internal structures of @R{} and coding standards for "
140 :     "the core team working on @R{} itself."
141 : gnustats 1339 msgstr ""
142 :    
143 :     #. type: node
144 :     #: R-ints.texi:75
145 :     #: R-ints.texi:78
146 :     #: R-ints.texi:1947
147 :     #: R-ints.texi:2207
148 :     #: R-ints.texi:2233
149 :     #: R-ints.texi:2241
150 :     #: R-ints.texi:2300
151 :     #: R-ints.texi:2333
152 :     #, no-wrap
153 :     msgid ".Internal vs .Primitive"
154 :     msgstr ""
155 :    
156 :     #. type: node
157 :     #: R-ints.texi:75
158 :     #: R-ints.texi:1947
159 :     #: R-ints.texi:2333
160 :     #: R-ints.texi:2334
161 :     #: R-ints.texi:2356
162 :     #: R-ints.texi:2373
163 :     #: R-ints.texi:2419
164 :     #: R-ints.texi:2449
165 :     #: R-ints.texi:2456
166 :     #: R-ints.texi:2461
167 :     #, no-wrap
168 :     msgid "Internationalization in the R sources"
169 :     msgstr ""
170 :    
171 :     #. type: node
172 :     #: R-ints.texi:75
173 :     #: R-ints.texi:2333
174 :     #: R-ints.texi:2461
175 :     #: R-ints.texi:2515
176 :     #: R-ints.texi:2586
177 :     #: R-ints.texi:2612
178 :     #, no-wrap
179 :     msgid "Package Structure"
180 :     msgstr ""
181 :    
182 :     #. type: node
183 :     #: R-ints.texi:75
184 :     #: R-ints.texi:2461
185 :     #: R-ints.texi:2612
186 :     #: R-ints.texi:2613
187 :     #: R-ints.texi:2698
188 :     #, no-wrap
189 :     msgid "Files"
190 :     msgstr ""
191 :    
192 :     #. type: node
193 :     #: R-ints.texi:75
194 :     #: R-ints.texi:2612
195 :     #: R-ints.texi:2698
196 :     #: R-ints.texi:2824
197 :     #: R-ints.texi:2825
198 :     #: R-ints.texi:3399
199 :     #: R-ints.texi:3488
200 :     #: R-ints.texi:3580
201 :     #: R-ints.texi:3585
202 :     #, no-wrap
203 :     msgid "Graphics Devices"
204 :     msgstr ""
205 :    
206 :     #. type: node
207 :     #: R-ints.texi:75
208 :     #: R-ints.texi:2698
209 :     #: R-ints.texi:3585
210 :     #: R-ints.texi:3586
211 :     #: R-ints.texi:3611
212 :     #: R-ints.texi:3747
213 :     #, no-wrap
214 :     msgid "GUI consoles"
215 :     msgstr ""
216 :    
217 :     #. type: node
218 :     #: R-ints.texi:75
219 :     #: R-ints.texi:3585
220 :     #: R-ints.texi:3747
221 :     #: R-ints.texi:3748
222 :     #: R-ints.texi:4119
223 :     #, no-wrap
224 :     msgid "Tools"
225 :     msgstr ""
226 :    
227 :     #. type: node
228 :     #: R-ints.texi:75
229 :     #: R-ints.texi:3747
230 :     #: R-ints.texi:4119
231 :     #: R-ints.texi:4120
232 :     #: R-ints.texi:4252
233 :     #, no-wrap
234 :     msgid "R coding standards"
235 :     msgstr ""
236 :    
237 :     #. type: node
238 :     #: R-ints.texi:75
239 :     #: R-ints.texi:4119
240 :     #: R-ints.texi:4252
241 :     #: R-ints.texi:4253
242 :     #: R-ints.texi:4266
243 :     #, no-wrap
244 :     msgid "Testing R code"
245 :     msgstr ""
246 :    
247 :     #. type: node
248 :     #: R-ints.texi:75
249 :     #: R-ints.texi:4252
250 :     #: R-ints.texi:4266
251 :     #: R-ints.texi:4267
252 :     #: R-ints.texi:4310
253 :     #, no-wrap
254 :     msgid "Use of TeX dialects"
255 :     msgstr ""
256 :    
257 :     #. type: node
258 :     #: R-ints.texi:75
259 :     #: R-ints.texi:4266
260 :     #: R-ints.texi:4310
261 :     #: R-ints.texi:4311
262 :     #: R-ints.texi:4323
263 :     #: R-ints.texi:4396
264 :     #: R-ints.texi:4448
265 :     #: R-ints.texi:4477
266 :     #, no-wrap
267 :     msgid "Current and future directions"
268 :     msgstr ""
269 :    
270 :     #. type: node
271 :     #: R-ints.texi:75
272 :     #: R-ints.texi:4310
273 :     #: R-ints.texi:4477
274 :     #: R-ints.texi:4478
275 :     #: R-ints.texi:4482
276 :     #, no-wrap
277 :     msgid "Function and variable index"
278 :     msgstr ""
279 :    
280 :     #. type: unnumbered
281 :     #: R-ints.texi:75
282 :     #: R-ints.texi:4477
283 :     #: R-ints.texi:4482
284 :     #: R-ints.texi:4483
285 :     #, no-wrap
286 :     msgid "Concept index"
287 :     msgstr ""
288 :    
289 :     #. type: Plain text
290 :     #: R-ints.texi:84
291 : gnustats 1340 msgid ""
292 :     "This chapter is the beginnings of documentation about @R{} internal "
293 :     "structures. It is written for the core team and others studying the code in "
294 :     "the @file{src/main} directory."
295 : gnustats 1339 msgstr ""
296 :    
297 :     #. type: Plain text
298 :     #: R-ints.texi:89
299 : gnustats 1340 msgid ""
300 :     "It is a work-in-progress and should be checked against the current version "
301 :     "of the source code. Versions for @R{} 2.x.y contain historical comments "
302 :     "about when features were introduced: this version is for the 3.x.y series."
303 : gnustats 1339 msgstr ""
304 :    
305 :     #. type: node
306 :     #: R-ints.texi:108
307 :     #: R-ints.texi:110
308 :     #: R-ints.texi:111
309 :     #: R-ints.texi:146
310 :     #: R-ints.texi:225
311 :     #: R-ints.texi:372
312 :     #: R-ints.texi:511
313 :     #: R-ints.texi:528
314 :     #, no-wrap
315 :     msgid "SEXPs"
316 :     msgstr ""
317 :    
318 :     #. type: node
319 :     #: R-ints.texi:108
320 :     #: R-ints.texi:110
321 :     #: R-ints.texi:528
322 :     #: R-ints.texi:529
323 :     #: R-ints.texi:579
324 :     #: R-ints.texi:608
325 :     #: R-ints.texi:641
326 :     #: R-ints.texi:667
327 :     #, no-wrap
328 :     msgid "Environments and variable lookup"
329 :     msgstr ""
330 :    
331 :     #. type: node
332 :     #: R-ints.texi:108
333 :     #: R-ints.texi:528
334 :     #: R-ints.texi:667
335 :     #: R-ints.texi:668
336 :     #: R-ints.texi:772
337 :     #, no-wrap
338 :     msgid "Attributes"
339 :     msgstr ""
340 :    
341 :     #. type: node
342 :     #: R-ints.texi:108
343 :     #: R-ints.texi:667
344 :     #: R-ints.texi:772
345 :     #: R-ints.texi:773
346 :     #: R-ints.texi:865
347 :     #, no-wrap
348 :     msgid "Contexts"
349 :     msgstr ""
350 :    
351 :     #. type: node
352 :     #: R-ints.texi:108
353 :     #: R-ints.texi:772
354 :     #: R-ints.texi:865
355 :     #: R-ints.texi:866
356 :     #: R-ints.texi:948
357 :     #: R-ints.texi:993
358 :     #: R-ints.texi:1021
359 :     #, no-wrap
360 :     msgid "Argument evaluation"
361 :     msgstr ""
362 :    
363 :     #. type: node
364 :     #: R-ints.texi:108
365 :     #: R-ints.texi:865
366 :     #: R-ints.texi:1021
367 :     #: R-ints.texi:1022
368 :     #: R-ints.texi:1076
369 :     #, no-wrap
370 :     msgid "Autoprinting"
371 :     msgstr ""
372 :    
373 :     #. type: node
374 :     #: R-ints.texi:108
375 :     #: R-ints.texi:1021
376 :     #: R-ints.texi:1076
377 :     #: R-ints.texi:1121
378 :     #, no-wrap
379 :     msgid "The write barrier"
380 :     msgstr ""
381 :    
382 :     #. type: node
383 :     #: R-ints.texi:108
384 :     #: R-ints.texi:1076
385 :     #: R-ints.texi:1121
386 :     #: R-ints.texi:1122
387 :     #: R-ints.texi:1229
388 :     #, no-wrap
389 :     msgid "Serialization Formats"
390 :     msgstr ""
391 :    
392 :     #. type: node
393 :     #: R-ints.texi:108
394 :     #: R-ints.texi:1121
395 :     #: R-ints.texi:1229
396 :     #: R-ints.texi:1230
397 :     #: R-ints.texi:1307
398 :     #, no-wrap
399 :     msgid "Encodings for CHARSXPs"
400 :     msgstr ""
401 :    
402 :     #. type: node
403 :     #: R-ints.texi:108
404 :     #: R-ints.texi:1229
405 :     #: R-ints.texi:1307
406 :     #: R-ints.texi:1308
407 :     #: R-ints.texi:1326
408 :     #, no-wrap
409 :     msgid "The CHARSXP cache"
410 :     msgstr ""
411 :    
412 :     #. type: node
413 :     #: R-ints.texi:108
414 :     #: R-ints.texi:1307
415 :     #: R-ints.texi:1326
416 :     #: R-ints.texi:1327
417 :     #: R-ints.texi:1376
418 :     #, no-wrap
419 :     msgid "Warnings and errors"
420 :     msgstr ""
421 :    
422 :     #. type: node
423 :     #: R-ints.texi:108
424 :     #: R-ints.texi:1326
425 :     #: R-ints.texi:1376
426 :     #: R-ints.texi:1377
427 :     #: R-ints.texi:1390
428 :     #: R-ints.texi:1411
429 :     #: R-ints.texi:1428
430 :     #: R-ints.texi:1479
431 :     #: R-ints.texi:1547
432 :     #, no-wrap
433 :     msgid "S4 objects"
434 :     msgstr ""
435 :    
436 :     #. type: node
437 :     #: R-ints.texi:108
438 :     #: R-ints.texi:1376
439 :     #: R-ints.texi:1547
440 :     #: R-ints.texi:1548
441 :     #: R-ints.texi:1680
442 :     #: R-ints.texi:1701
443 :     #, no-wrap
444 :     msgid "Memory allocators"
445 :     msgstr ""
446 :    
447 :     #. type: node
448 :     #: R-ints.texi:108
449 :     #: R-ints.texi:1547
450 :     #: R-ints.texi:1701
451 :     #: R-ints.texi:1702
452 :     #: R-ints.texi:1712
453 :     #: R-ints.texi:1739
454 :     #: R-ints.texi:1758
455 :     #, no-wrap
456 :     msgid "Internal use of global and base environments"
457 :     msgstr ""
458 :    
459 :     #. type: node
460 :     #: R-ints.texi:108
461 :     #: R-ints.texi:1701
462 :     #: R-ints.texi:1758
463 :     #: R-ints.texi:1759
464 :     #: R-ints.texi:1796
465 :     #, no-wrap
466 :     msgid "Modules"
467 :     msgstr ""
468 :    
469 :     #. type: node
470 :     #: R-ints.texi:108
471 :     #: R-ints.texi:1758
472 :     #: R-ints.texi:1796
473 :     #: R-ints.texi:1797
474 :     #: R-ints.texi:1805
475 :     #: R-ints.texi:1856
476 :     #: R-ints.texi:1883
477 :     #, no-wrap
478 :     msgid "Visibility"
479 :     msgstr ""
480 :    
481 :     #. type: section
482 :     #: R-ints.texi:108
483 :     #: R-ints.texi:1796
484 :     #: R-ints.texi:1883
485 :     #: R-ints.texi:1884
486 :     #, no-wrap
487 :     msgid "Lazy loading"
488 :     msgstr ""
489 :    
490 :     #. type: cindex
491 :     #: R-ints.texi:113
492 :     #, no-wrap
493 :     msgid "SEXP"
494 :     msgstr ""
495 :    
496 :     #. type: cindex
497 :     #: R-ints.texi:114
498 :     #, no-wrap
499 :     msgid "SEXPRREC"
500 :     msgstr ""
501 :    
502 :     #. type: Plain text
503 :     #: R-ints.texi:122
504 : gnustats 1340 msgid ""
505 :     "What @R{} users think of as @emph{variables} or @emph{objects} are symbols "
506 :     "which are bound to a value. The value can be thought of as either a "
507 :     "@code{SEXP} (a pointer), or the structure it points to, a @code{SEXPREC} "
508 :     "(and there are alternative forms used for vectors, namely @code{VECSXP} "
509 :     "pointing to @code{VECTOR_SEXPREC} structures). So the basic building blocks "
510 :     "of @R{} objects are often called @emph{nodes}, meaning @code{SEXPREC}s or "
511 :     "@code{VECTOR_SEXPREC}s."
512 : gnustats 1339 msgstr ""
513 :    
514 :     #. type: Plain text
515 :     #: R-ints.texi:126
516 : gnustats 1340 msgid ""
517 :     "Note that the internal structure of the @code{SEXPREC} is not made available "
518 :     "to @R{} Extensions: rather @code{SEXP} is an opaque pointer, and the "
519 :     "internals can only be accessed by the functions provided."
520 : gnustats 1339 msgstr ""
521 :    
522 :     #. type: cindex
523 :     #: R-ints.texi:127
524 :     #, no-wrap
525 :     msgid "node"
526 :     msgstr ""
527 :    
528 :     #. type: Plain text
529 :     #: R-ints.texi:135
530 : gnustats 1340 msgid ""
531 :     "Both types of node structure have as their first three fields a 32-bit "
532 :     "@code{sxpinfo} header and then three pointers (to the attributes and the "
533 :     "previous and next node in a doubly-linked list), and then some further "
534 :     "fields. On a 32-bit platform a node@footnote{strictly, a @code{SEXPREC} "
535 :     "node; @code{VECTOR_SEXPREC} nodes are slightly smaller but followed by data "
536 :     "in the node.} occupies 28 bytes: on a 64-bit platform typically 56 bytes "
537 :     "(depending on alignment constraints)."
538 : gnustats 1339 msgstr ""
539 :    
540 :     #. type: Plain text
541 :     #: R-ints.texi:138
542 : gnustats 1340 msgid ""
543 :     "The first five bits of the @code{sxpinfo} header specify one of up to 32 "
544 :     "@code{SEXPTYPE}s."
545 : gnustats 1339 msgstr ""
546 :    
547 :     #. type: node
548 :     #: R-ints.texi:144
549 :     #: R-ints.texi:146
550 :     #: R-ints.texi:147
551 :     #: R-ints.texi:225
552 :     #, no-wrap
553 :     msgid "SEXPTYPEs"
554 :     msgstr ""
555 :    
556 :     #. type: node
557 :     #: R-ints.texi:144
558 :     #: R-ints.texi:146
559 :     #: R-ints.texi:225
560 :     #: R-ints.texi:226
561 :     #: R-ints.texi:372
562 :     #, no-wrap
563 :     msgid "Rest of header"
564 :     msgstr ""
565 :    
566 :     #. type: node
567 :     #: R-ints.texi:144
568 :     #: R-ints.texi:225
569 :     #: R-ints.texi:372
570 :     #: R-ints.texi:511
571 :     #, no-wrap
572 :     msgid "The 'data'"
573 :     msgstr ""
574 :    
575 :     #. type: subsection
576 :     #: R-ints.texi:144
577 :     #: R-ints.texi:372
578 :     #: R-ints.texi:511
579 :     #: R-ints.texi:512
580 :     #, no-wrap
581 :     msgid "Allocation classes"
582 :     msgstr ""
583 :    
584 :     #. type: multitable
585 :     #: R-ints.texi:149
586 :     #: R-ints.texi:160
587 :     #, no-wrap
588 :     msgid "SEXPTYPE"
589 :     msgstr ""
590 :    
591 :     #. type: Plain text
592 :     #: R-ints.texi:155
593 : gnustats 1340 msgid ""
594 :     "Currently @code{SEXPTYPE}s 0:10 and 13:25 are in use. Values 11 and 12 were "
595 :     "used for internal factors and ordered factors and have since been "
596 :     "withdrawn. Note that the @code{SEXPTYPE} numbers are stored in @code{save}d "
597 :     "objects and that the ordering of the types is used, so the gap cannot easily "
598 :     "be reused."
599 : gnustats 1339 msgstr ""
600 :    
601 :     #. type: cindex
602 :     #: R-ints.texi:156
603 :     #, no-wrap
604 :     msgid "SEXPTYPE table"
605 :     msgstr ""
606 :    
607 :     #. type: multitable
608 :     #: R-ints.texi:160
609 :     msgid "@headitem no"
610 :     msgstr ""
611 :    
612 :     #. type: multitable
613 :     #: R-ints.texi:160
614 :     msgid "Description"
615 :     msgstr ""
616 :    
617 :     #. type: item
618 :     #: R-ints.texi:160
619 :     #, no-wrap
620 :     msgid "@code{0} @tab @code{NILSXP} @tab @code{NULL}"
621 :     msgstr ""
622 :    
623 :     #. type: item
624 :     #: R-ints.texi:161
625 :     #, no-wrap
626 :     msgid "@code{1} @tab @code{SYMSXP} @tab symbols"
627 :     msgstr ""
628 :    
629 :     #. type: item
630 :     #: R-ints.texi:162
631 :     #, no-wrap
632 :     msgid "@code{2} @tab @code{LISTSXP} @tab pairlists"
633 :     msgstr ""
634 :    
635 :     #. type: item
636 :     #: R-ints.texi:163
637 :     #, no-wrap
638 :     msgid "@code{3} @tab @code{CLOSXP} @tab closures"
639 :     msgstr ""
640 :    
641 :     #. type: item
642 :     #: R-ints.texi:164
643 :     #, no-wrap
644 :     msgid "@code{4} @tab @code{ENVSXP} @tab environments"
645 :     msgstr ""
646 :    
647 :     #. type: item
648 :     #: R-ints.texi:165
649 :     #, no-wrap
650 :     msgid "@code{5} @tab @code{PROMSXP} @tab promises"
651 :     msgstr ""
652 :    
653 :     #. type: item
654 :     #: R-ints.texi:166
655 :     #, no-wrap
656 :     msgid "@code{6} @tab @code{LANGSXP} @tab language objects"
657 :     msgstr ""
658 :    
659 :     #. type: item
660 :     #: R-ints.texi:167
661 :     #, no-wrap
662 :     msgid "@code{7} @tab @code{SPECIALSXP} @tab special functions"
663 :     msgstr ""
664 :    
665 :     #. type: item
666 :     #: R-ints.texi:168
667 :     #, no-wrap
668 :     msgid "@code{8} @tab @code{BUILTINSXP} @tab builtin functions"
669 :     msgstr ""
670 :    
671 :     #. type: item
672 :     #: R-ints.texi:169
673 :     #, no-wrap
674 :     msgid "@code{9} @tab @code{CHARSXP} @tab internal character strings"
675 :     msgstr ""
676 :    
677 :     #. type: item
678 :     #: R-ints.texi:170
679 :     #, no-wrap
680 :     msgid "@code{10} @tab @code{LGLSXP} @tab logical vectors"
681 :     msgstr ""
682 :    
683 :     #. type: item
684 :     #: R-ints.texi:171
685 :     #, no-wrap
686 :     msgid "@code{13} @tab @code{INTSXP} @tab integer vectors"
687 :     msgstr ""
688 :    
689 :     #. type: item
690 :     #: R-ints.texi:172
691 :     #, no-wrap
692 :     msgid "@code{14} @tab @code{REALSXP} @tab numeric vectors"
693 :     msgstr ""
694 :    
695 :     #. type: item
696 :     #: R-ints.texi:173
697 :     #, no-wrap
698 :     msgid "@code{15} @tab @code{CPLXSXP} @tab complex vectors"
699 :     msgstr ""
700 :    
701 :     #. type: item
702 :     #: R-ints.texi:174
703 :     #, no-wrap
704 :     msgid "@code{16} @tab @code{STRSXP} @tab character vectors"
705 :     msgstr ""
706 :    
707 :     #. type: item
708 :     #: R-ints.texi:175
709 :     #, no-wrap
710 :     msgid "@code{17} @tab @code{DOTSXP} @tab dot-dot-dot object"
711 :     msgstr ""
712 :    
713 :     #. type: item
714 :     #: R-ints.texi:176
715 :     #, no-wrap
716 :     msgid "@code{18} @tab @code{ANYSXP} @tab make ``any'' args work"
717 :     msgstr ""
718 :    
719 :     #. type: item
720 :     #: R-ints.texi:177
721 :     #, no-wrap
722 :     msgid "@code{19} @tab @code{VECSXP} @tab list (generic vector)"
723 :     msgstr ""
724 :    
725 :     #. type: item
726 :     #: R-ints.texi:178
727 :     #, no-wrap
728 :     msgid "@code{20} @tab @code{EXPRSXP} @tab expression vector"
729 :     msgstr ""
730 :    
731 :     #. type: item
732 :     #: R-ints.texi:179
733 :     #, no-wrap
734 :     msgid "@code{21} @tab @code{BCODESXP} @tab byte code"
735 :     msgstr ""
736 :    
737 :     #. type: item
738 :     #: R-ints.texi:180
739 :     #, no-wrap
740 :     msgid "@code{22} @tab @code{EXTPTRSXP} @tab external pointer"
741 :     msgstr ""
742 :    
743 :     #. type: item
744 :     #: R-ints.texi:181
745 :     #, no-wrap
746 :     msgid "@code{23} @tab @code{WEAKREFSXP} @tab weak reference"
747 :     msgstr ""
748 :    
749 :     #. type: item
750 :     #: R-ints.texi:182
751 :     #, no-wrap
752 :     msgid "@code{24} @tab @code{RAWSXP} @tab raw vector"
753 :     msgstr ""
754 :    
755 :     #. type: item
756 :     #: R-ints.texi:183
757 :     #, no-wrap
758 :     msgid "@code{25} @tab @code{S4SXP} @tab S4 classes not of simple type"
759 :     msgstr ""
760 :    
761 :     #. type: cindex
762 :     #: R-ints.texi:187
763 :     #, no-wrap
764 :     msgid "atomic vector type"
765 :     msgstr ""
766 :    
767 :     #. type: Plain text
768 :     #: R-ints.texi:196
769 : gnustats 1340 msgid ""
770 :     "Many of these will be familiar from @R{} level: the atomic vector types are "
771 :     "@code{LGLSXP}, @code{INTSXP}, @code{REALSXP}, @code{CPLXSP}, @code{STRSXP} "
772 :     "and @code{RAWSXP}. Lists are @code{VECSXP} and names (also known as "
773 :     "symbols) are @code{SYMSXP}. Pairlists (@code{LISTSXP}, the name going back "
774 :     "to the origins of @R{} as a Scheme-like language) are rarely seen at @R{} "
775 :     "level, but are for example used for argument lists. Character vectors are "
776 :     "effectively lists all of whose elements are @code{CHARSXP}, a type that is "
777 :     "rarely visible at @R{} level."
778 : gnustats 1339 msgstr ""
779 :    
780 :     #. type: cindex
781 :     #: R-ints.texi:197
782 :     #, no-wrap
783 :     msgid "language object"
784 :     msgstr ""
785 :    
786 :     #. type: cindex
787 :     #: R-ints.texi:198
788 :     #, no-wrap
789 :     msgid "argument list"
790 :     msgstr ""
791 :    
792 :     #. type: Plain text
793 :     #: R-ints.texi:208
794 : gnustats 1340 msgid ""
795 :     "Language objects (@code{LANGSXP}) are calls (including formulae and so on). "
796 :     "Internally they are pairlists with first element a reference@footnote{a "
797 :     "pointer to a function or a symbol to look up the function by name, or a "
798 :     "language object to be evaluated to give a function.} to the function to be "
799 :     "called with remaining elements the actual arguments for the call (and with "
800 :     "the tags if present giving the specified argument names). Although this is "
801 :     "not enforced, many places in the code assume that the pairlist is of length "
802 :     "one or more, often without checking."
803 : gnustats 1339 msgstr ""
804 :    
805 :     #. type: cindex
806 :     #: R-ints.texi:209
807 :     #, no-wrap
808 :     msgid "expression"
809 :     msgstr ""
810 :    
811 :     #. type: Plain text
812 :     #: R-ints.texi:212
813 : gnustats 1340 msgid ""
814 :     "Expressions are of type @code{EXPRSXP}: they are a vector of (usually "
815 :     "language) objects most often seen as the result of @code{parse()}."
816 : gnustats 1339 msgstr ""
817 :    
818 :     #. type: cindex
819 :     #: R-ints.texi:213
820 :     #, no-wrap
821 :     msgid "function"
822 :     msgstr ""
823 :    
824 :     #. type: Plain text
825 :     #: R-ints.texi:219
826 : gnustats 1340 msgid ""
827 :     "The functions are of types @code{CLOSXP}, @code{SPECIALSXP} and "
828 :     "@code{BUILTINSXP}: where @code{SEXPTYPE}s are stored in an integer these are "
829 :     "sometimes lumped into a pseudo-type @code{FUNSXP} with code 99. Functions "
830 :     "defined via @code{function} are of type @code{CLOSXP} and have formals, body "
831 :     "and environment."
832 : gnustats 1339 msgstr ""
833 :    
834 :     #. type: cindex
835 :     #: R-ints.texi:220
836 :     #, no-wrap
837 :     msgid "S4 type"
838 :     msgstr ""
839 :    
840 :     #. type: Plain text
841 :     #: R-ints.texi:223
842 : gnustats 1340 msgid ""
843 :     "The @code{SEXPTYPE} @code{S4SXP} is for S4 objects which do not consist "
844 :     "solely of a simple type such as an atomic vector or function."
845 : gnustats 1339 msgstr ""
846 :    
847 :     #. type: Plain text
848 :     #: R-ints.texi:229
849 :     msgid "The @code{sxpinfo} header is defined as a 32-bit C structure by"
850 :     msgstr ""
851 :    
852 :     #. type: example
853 :     #: R-ints.texi:243
854 :     #, no-wrap
855 :     msgid ""
856 :     "struct sxpinfo_struct @{\n"
857 :     " SEXPTYPE type : 5; /* @r{discussed above} */\n"
858 :     " unsigned int obj : 1; /* @r{is this an object with a class attribute?} */\n"
859 :     " unsigned int named : 2; /* @r{used to control copying} */\n"
860 :     " unsigned int gp : 16; /* @r{general purpose, see below} */\n"
861 :     " unsigned int mark : 1; /* @r{mark object as `in use' in GC} */\n"
862 :     " unsigned int debug : 1;\n"
863 :     " unsigned int trace : 1;\n"
864 :     " unsigned int spare : 1; /* @r{debug once} */\n"
865 :     " unsigned int gcgen : 1; /* @r{generation for GC} */\n"
866 :     " unsigned int gccls : 3; /* @r{class of node for GC} */\n"
867 :     "@}; /* Tot: 32 */\n"
868 :     msgstr ""
869 :    
870 :     #. type: findex
871 :     #: R-ints.texi:245
872 :     #, no-wrap
873 :     msgid "debug bit"
874 :     msgstr ""
875 :    
876 :     #. type: Plain text
877 :     #: R-ints.texi:251
878 : gnustats 1340 msgid ""
879 :     "The @code{debug} bit is used for closures and environments. For closures it "
880 :     "is set by @code{debug()} and unset by @code{undebug()}, and indicates that "
881 :     "evaluations of the function should be run under the browser. For "
882 :     "environments it indicates whether the browsing is in single-step mode."
883 : gnustats 1339 msgstr ""
884 :    
885 :     #. type: findex
886 :     #: R-ints.texi:252
887 :     #, no-wrap
888 :     msgid "trace bit"
889 :     msgstr ""
890 :    
891 :     #. type: Plain text
892 :     #: R-ints.texi:255
893 : gnustats 1340 msgid ""
894 :     "The @code{trace} bit is used for functions for @code{trace()} and for other "
895 :     "objects when tracing duplications (see @code{tracemem})."
896 : gnustats 1339 msgstr ""
897 :    
898 :     #. type: findex
899 :     #: R-ints.texi:256
900 :     #, no-wrap
901 :     msgid "spare bit"
902 :     msgstr ""
903 :    
904 :     #. type: Plain text
905 :     #: R-ints.texi:259
906 : gnustats 1340 msgid ""
907 :     "The @code{spare} bit is used for closures to mark them for one time "
908 :     "debugging."
909 : gnustats 1339 msgstr ""
910 :    
911 :     #. type: findex
912 :     #: R-ints.texi:260
913 :     #, no-wrap
914 :     msgid "named bit"
915 :     msgstr ""
916 :    
917 :     #. type: findex
918 :     #: R-ints.texi:261
919 :     #: R-ints.texi:886
920 :     #: R-ints.texi:2129
921 :     #, no-wrap
922 :     msgid "NAMED"
923 :     msgstr ""
924 :    
925 :     #. type: findex
926 :     #: R-ints.texi:262
927 :     #, no-wrap
928 :     msgid "SET_NAMED"
929 :     msgstr ""
930 :    
931 :     #. type: cindex
932 :     #: R-ints.texi:263
933 :     #: R-ints.texi:716
934 :     #, no-wrap
935 :     msgid "copying semantics"
936 :     msgstr ""
937 :    
938 :     #. type: Plain text
939 :     #: R-ints.texi:267
940 : gnustats 1340 msgid ""
941 :     "The @code{named} field is set and accessed by the @code{SET_NAMED} and "
942 :     "@code{NAMED} macros, and take values @code{0}, @code{1} and @code{2}. @R{} "
943 :     "has a `call by value' illusion, so an assignment like"
944 : gnustats 1339 msgstr ""
945 :    
946 :     #. type: example
947 :     #: R-ints.texi:269
948 :     #, no-wrap
949 :     msgid "b <- a\n"
950 :     msgstr ""
951 :    
952 :     #. type: Plain text
953 :     #: R-ints.texi:284
954 : gnustats 1340 msgid ""
955 :     "appears to make a copy of @code{a} and refer to it as @code{b}. However, if "
956 :     "neither @code{a} nor @code{b} are subsequently altered there is no need to "
957 :     "copy. What really happens is that a new symbol @code{b} is bound to the "
958 :     "same value as @code{a} and the @code{named} field on the value object is set "
959 :     "(in this case to @code{2}). When an object is about to be altered, the "
960 :     "@code{named} field is consulted. A value of @code{2} means that the object "
961 :     "must be duplicated before being changed. (Note that this does not say that "
962 :     "it is necessary to duplicate, only that it should be duplicated whether "
963 :     "necessary or not.) A value of @code{0} means that it is known that no other "
964 :     "@code{SEXP} shares data with this object, and so it may safely be altered. "
965 :     "A value of @code{1} is used for situations like"
966 : gnustats 1339 msgstr ""
967 :    
968 :     #. type: example
969 :     #: R-ints.texi:287
970 :     #, no-wrap
971 :     msgid "dim(a) <- c(7, 2)\n"
972 :     msgstr ""
973 :    
974 :     #. type: Plain text
975 :     #: R-ints.texi:292
976 : gnustats 1340 msgid ""
977 :     "where in principle two copies of @code{a} exist for the duration of the "
978 :     "computation as (in principle)"
979 : gnustats 1339 msgstr ""
980 :    
981 :     #. type: example
982 :     #: R-ints.texi:295
983 :     #, no-wrap
984 :     msgid "a <- `dim<-`(a, c(7, 2))\n"
985 :     msgstr ""
986 :    
987 :     #. type: Plain text
988 :     #: R-ints.texi:300
989 : gnustats 1340 msgid ""
990 :     "but for no longer, and so some primitive functions can be optimized to avoid "
991 :     "a copy in this case."
992 : gnustats 1339 msgstr ""
993 :    
994 :     #. type: Plain text
995 :     #: R-ints.texi:304
996 : gnustats 1340 msgid ""
997 :     "The @code{gp} bits are by definition `general purpose'. We label these from "
998 :     "0 to 15. Bits 0--5 and bits 14--15 have been used as described below "
999 :     "(mainly from detective work on the sources)."
1000 : gnustats 1339 msgstr ""
1001 :    
1002 :     #. type: findex
1003 :     #: R-ints.texi:305
1004 :     #, no-wrap
1005 :     msgid "gp bits"
1006 :     msgstr ""
1007 :    
1008 :     #. type: findex
1009 :     #: R-ints.texi:306
1010 :     #, no-wrap
1011 :     msgid "LEVELS"
1012 :     msgstr ""
1013 :    
1014 :     #. type: findex
1015 :     #: R-ints.texi:307
1016 :     #, no-wrap
1017 :     msgid "SETLEVELS"
1018 :     msgstr ""
1019 :    
1020 :     #. type: Plain text
1021 :     #: R-ints.texi:314
1022 : gnustats 1340 msgid ""
1023 :     "The bits can be accessed and set by the @code{LEVELS} and @code{SETLEVELS} "
1024 :     "macros, which names appear to date back to the internal factor and ordered "
1025 :     "types and are now used in only a few places in the code. The @code{gp} "
1026 :     "field is serialized/unserialized for the @code{SEXPTYPE}s other than "
1027 :     "@code{NILSXP}, @code{SYMSXP} and @code{ENVSXP}."
1028 : gnustats 1339 msgstr ""
1029 :    
1030 :     #. type: Plain text
1031 :     #: R-ints.texi:320
1032 : gnustats 1340 msgid ""
1033 :     "Bits 14 and 15 of @code{gp} are used for `fancy bindings'. Bit 14 is used "
1034 :     "to lock a binding or an environment, and bit 15 is used to indicate an "
1035 :     "active binding. (For the definition of an `active binding' see the header "
1036 :     "comments in file @file{src/main/envir.c}.) Bit 15 is used for an "
1037 :     "environment to indicate if it participates in the global cache."
1038 : gnustats 1339 msgstr ""
1039 :    
1040 :     #. type: findex
1041 :     #: R-ints.texi:321
1042 :     #, no-wrap
1043 :     msgid "ARGSUSED"
1044 :     msgstr ""
1045 :    
1046 :     #. type: findex
1047 :     #: R-ints.texi:322
1048 :     #, no-wrap
1049 :     msgid "SET_ARGUSED"
1050 :     msgstr ""
1051 :    
1052 :     #. type: Plain text
1053 :     #: R-ints.texi:325
1054 : gnustats 1340 msgid ""
1055 :     "The macros @code{ARGUSED} and @code{SET_ARGUSED} are used when matching "
1056 :     "actual and formal function arguments, and take the values 0, 1 and 2."
1057 : gnustats 1339 msgstr ""
1058 :    
1059 :     #. type: findex
1060 :     #: R-ints.texi:326
1061 :     #: R-ints.texi:963
1062 :     #, no-wrap
1063 :     msgid "MISSING"
1064 :     msgstr ""
1065 :    
1066 :     #. type: findex
1067 :     #: R-ints.texi:327
1068 :     #, no-wrap
1069 :     msgid "SET_MISSING"
1070 :     msgstr ""
1071 :    
1072 :     #. type: Plain text
1073 :     #: R-ints.texi:334
1074 : gnustats 1340 msgid ""
1075 :     "The macros @code{MISSING} and @code{SET_MISSING} are used for pairlists of "
1076 :     "arguments. Four bits are reserved, but only two are used (and exactly what "
1077 :     "for is not explained). It seems that bit 0 is used by @code{matchArgs} to "
1078 :     "mark missingness on the returned argument list, and bit 1 is used to mark "
1079 :     "the use of a default value for an argument copied to the evaluation frame of "
1080 :     "a closure."
1081 : gnustats 1339 msgstr ""
1082 :    
1083 :     #. type: findex
1084 :     #: R-ints.texi:335
1085 :     #, no-wrap
1086 :     msgid "DDVAL"
1087 :     msgstr ""
1088 :    
1089 :     #. type: findex
1090 :     #: R-ints.texi:336
1091 :     #, no-wrap
1092 :     msgid "SET_DDVAL"
1093 :     msgstr ""
1094 :    
1095 :     #. type: cindex
1096 :     #: R-ints.texi:337
1097 :     #: R-ints.texi:996
1098 :     #, no-wrap
1099 :     msgid "... argument"
1100 :     msgstr ""
1101 :    
1102 :     #. type: Plain text
1103 :     #: R-ints.texi:342
1104 : gnustats 1340 msgid ""
1105 :     "Bit 0 is used by macros @code{DDVAL} and @code{SET_DDVAL}. This indicates "
1106 :     "that a @code{SYMSXP} is one of the symbols @code{..n} which are implicitly "
1107 :     "created when @code{...} is processed, and so indicates that it may need to "
1108 :     "be looked up in a @code{DOTSXP}."
1109 : gnustats 1339 msgstr ""
1110 :    
1111 :     #. type: findex
1112 :     #: R-ints.texi:343
1113 :     #, no-wrap
1114 :     msgid "PRSEEN"
1115 :     msgstr ""
1116 :    
1117 :     #. type: cindex
1118 :     #: R-ints.texi:344
1119 :     #, no-wrap
1120 :     msgid "promise"
1121 :     msgstr ""
1122 :    
1123 :     #. type: Plain text
1124 :     #: R-ints.texi:348
1125 : gnustats 1340 msgid ""
1126 :     "Bit 0 is used for @code{PRSEEN}, a flag to indicate if a promise has already "
1127 :     "been seen during the evaluation of the promise (and so to avoid recursive "
1128 :     "loops)."
1129 : gnustats 1339 msgstr ""
1130 :    
1131 :     #. type: Plain text
1132 :     #: R-ints.texi:352
1133 : gnustats 1340 msgid ""
1134 :     "Bit 0 is used for @code{HASHASH}, on the @code{PRINTNAME} of the @code{TAG} "
1135 :     "of the frame of an environment. (This bit is not serialized for "
1136 :     "@code{CHARSXP} objects.)"
1137 : gnustats 1339 msgstr ""
1138 :    
1139 :     #. type: Plain text
1140 :     #: R-ints.texi:355
1141 : gnustats 1340 msgid ""
1142 :     "Bits 0 and 1 are used for weak references (to indicate `ready to finalize', "
1143 :     "`finalize on exit')."
1144 : gnustats 1339 msgstr ""
1145 :    
1146 :     #. type: Plain text
1147 :     #: R-ints.texi:358
1148 : gnustats 1340 msgid ""
1149 :     "Bit 0 is used by the condition handling system (on a @code{VECSXP}) to "
1150 :     "indicate a calling handler."
1151 : gnustats 1339 msgstr ""
1152 :    
1153 :     #. type: Plain text
1154 :     #: R-ints.texi:360
1155 :     msgid "Bit 4 is turned on to mark S4 objects."
1156 :     msgstr ""
1157 :    
1158 :     #. type: Plain text
1159 :     #: R-ints.texi:366
1160 : gnustats 1340 msgid ""
1161 :     "Bits 1, 2, 3, 5 and 6 are used for a @code{CHARSXP} to denote its encoding. "
1162 :     "Bit 1 indicates that the @code{CHARSXP} should be treated as a set of bytes, "
1163 :     "not necessarily representing a character in any known encoding. Bits 2, 3 "
1164 :     "and 6 are used to indicate that it is known to be in Latin-1, UTF-8 or "
1165 :     "@acronym{ASCII} respectively."
1166 : gnustats 1339 msgstr ""
1167 :    
1168 :     #. type: Plain text
1169 :     #: R-ints.texi:371
1170 : gnustats 1340 msgid ""
1171 :     "Bit 5 for a @code{CHARSXP} indicates that it is hashed by its address, that "
1172 :     "is @code{NA_STRING} or is in the @code{CHARSXP} cache (this is not "
1173 :     "serialized). Only exceptionally is a @code{CHARSXP} not hashed, and this "
1174 :     "should never happen in end-user code."
1175 : gnustats 1339 msgstr ""
1176 :    
1177 :     #. type: subsection
1178 :     #: R-ints.texi:373
1179 :     #, no-wrap
1180 :     msgid "The `data'"
1181 :     msgstr ""
1182 :    
1183 :     #. type: Plain text
1184 :     #: R-ints.texi:378
1185 : gnustats 1340 msgid ""
1186 :     "A @code{SEXPREC} is a C structure containing the 32-bit header as described "
1187 :     "above, three pointers (to the attributes, previous and next node) and the "
1188 :     "node data, a union"
1189 : gnustats 1339 msgstr ""
1190 :    
1191 :     #. type: example
1192 :     #: R-ints.texi:388
1193 :     #, no-wrap
1194 :     msgid ""
1195 :     "union @{\n"
1196 :     " struct primsxp_struct primsxp;\n"
1197 :     " struct symsxp_struct symsxp;\n"
1198 :     " struct listsxp_struct listsxp;\n"
1199 :     " struct envsxp_struct envsxp;\n"
1200 :     " struct closxp_struct closxp;\n"
1201 :     " struct promsxp_struct promsxp;\n"
1202 :     "@} u;\n"
1203 :     msgstr ""
1204 :    
1205 :     #. type: Plain text
1206 :     #: R-ints.texi:393
1207 : gnustats 1340 msgid ""
1208 :     "All of these alternatives apart from the first (an @code{int}) are three "
1209 :     "pointers, so the union occupies three words."
1210 : gnustats 1339 msgstr ""
1211 :    
1212 :     #. type: cindex
1213 :     #: R-ints.texi:394
1214 :     #, no-wrap
1215 :     msgid "vector type"
1216 :     msgstr ""
1217 :    
1218 :     #. type: Plain text
1219 :     #: R-ints.texi:411
1220 : gnustats 1340 msgid ""
1221 :     "The vector types are @code{RAWSXP}, @code{CHARSXP}, @code{LGLSXP}, "
1222 :     "@code{INTSXP}, @code{REALSXP}, @code{CPLXSXP}, @code{STRSXP}, @code{VECSXP}, "
1223 :     "@code{EXPRSXP} and @code{WEAKREFSXP}. Remember that such types are a "
1224 :     "@code{VECTOR_SEXPREC}, which again consists of the header and the same three "
1225 :     "pointers, but followed by two integers giving the length and `true "
1226 :     "length'@footnote{This is almost unused. The only current use is for hash "
1227 :     "tables of environments (@code{VECSXP}s), where @code{length} is the size of "
1228 :     "the table and @code{truelength} is the number of primary slots in use, and "
1229 :     "for the reference hash tables in serialization (@code{VECSXP}s), where "
1230 :     "@code{truelength} is the number of slots in use.} of the vector, and then "
1231 :     "followed by the data (aligned as required: on most 32-bit systems with a 24-"
1232 :     "byte @code{VECTOR_SEXPREC} node the data can follow immediately after the "
1233 :     "node). The data are a block of memory of the appropriate length to store "
1234 :     "`true length' elements (rounded up to a multiple of 8 bytes, with the 8-byte "
1235 :     "blocks being the `Vcells' referred in the documentation for @code{gc()})."
1236 : gnustats 1339 msgstr ""
1237 :    
1238 :     #. type: Plain text
1239 :     #: R-ints.texi:414
1240 : gnustats 1340 msgid ""
1241 :     "The `data' for the various types are given in the table below. A lot of "
1242 :     "this is interpretation, i.e. the types are not checked."
1243 : gnustats 1339 msgstr ""
1244 :    
1245 :     #. type: item
1246 :     #: R-ints.texi:416
1247 :     #, no-wrap
1248 :     msgid "NILSXP"
1249 :     msgstr ""
1250 :    
1251 :     #. type: table
1252 :     #: R-ints.texi:419
1253 : gnustats 1340 msgid ""
1254 :     "There is only one object of type @code{NILSXP}, @code{R_NilValue}, with no "
1255 :     "data."
1256 : gnustats 1339 msgstr ""
1257 :    
1258 :     #. type: item
1259 :     #: R-ints.texi:420
1260 :     #, no-wrap
1261 :     msgid "SYMSXP"
1262 :     msgstr ""
1263 :    
1264 :     #. type: table
1265 :     #: R-ints.texi:426
1266 : gnustats 1340 msgid ""
1267 :     "Pointers to three nodes, the name, value and internal, accessed by "
1268 :     "@code{PRINTNAME} (a @code{CHARSXP}), @code{SYMVALUE} and @code{INTERNAL}. "
1269 :     "(If the symbol's value is a @code{.Internal} function, the last is a pointer "
1270 :     "to the appropriate @code{SEXPREC}.) Many symbols have @code{SYMVALUE} "
1271 :     "@code{R_UnboundValue}."
1272 : gnustats 1339 msgstr ""
1273 :    
1274 :     #. type: item
1275 :     #: R-ints.texi:427
1276 :     #, no-wrap
1277 :     msgid "LISTSXP"
1278 :     msgstr ""
1279 :    
1280 :     #. type: table
1281 :     #: R-ints.texi:430
1282 : gnustats 1340 msgid ""
1283 :     "Pointers to the CAR, CDR (usually a @code{LISTSXP} or @code{NULL}) and TAG "
1284 :     "(a @code{SYMSXP} or @code{NULL})."
1285 : gnustats 1339 msgstr ""
1286 :    
1287 :     #. type: item
1288 :     #: R-ints.texi:431
1289 :     #, no-wrap
1290 :     msgid "CLOSXP"
1291 :     msgstr ""
1292 :    
1293 :     #. type: table
1294 :     #: R-ints.texi:433
1295 :     msgid "Pointers to the formals (a pairlist), the body and the environment."
1296 :     msgstr ""
1297 :    
1298 :     #. type: item
1299 :     #: R-ints.texi:434
1300 :     #, no-wrap
1301 :     msgid "ENVSXP"
1302 :     msgstr ""
1303 :    
1304 :     #. type: table
1305 :     #: R-ints.texi:438
1306 : gnustats 1340 msgid ""
1307 :     "Pointers to the frame, enclosing environment and hash table (@code{NULL} or "
1308 :     "a @code{VECSXP}). A frame is a tagged pairlist with tag the symbol and CAR "
1309 :     "the bound value."
1310 : gnustats 1339 msgstr ""
1311 :    
1312 :     #. type: item
1313 :     #: R-ints.texi:439
1314 :     #, no-wrap
1315 :     msgid "PROMSXP"
1316 :     msgstr ""
1317 :    
1318 :     #. type: table
1319 :     #: R-ints.texi:443
1320 : gnustats 1340 msgid ""
1321 :     "Pointers to the value, expression and environment (in which to evaluate the "
1322 :     "expression). Once an promise has been evaluated, the environment is set to "
1323 :     "@code{NULL}."
1324 : gnustats 1339 msgstr ""
1325 :    
1326 :     #. type: item
1327 :     #: R-ints.texi:444
1328 :     #, no-wrap
1329 :     msgid "LANGSXP"
1330 :     msgstr ""
1331 :    
1332 :     #. type: table
1333 :     #: R-ints.texi:451
1334 : gnustats 1340 msgid ""
1335 :     "A special type of @code{LISTSXP} used for function calls. (The CAR "
1336 :     "references the function (perhaps via a symbol or language object), and the "
1337 :     "CDR the argument list with tags for named arguments.) @R{}-level "
1338 :     "documentation references to `expressions' / `language objects' are mainly "
1339 :     "@code{LANGSXP}s, but can be symbols (@code{SYMSXP}s) or expression vectors "
1340 :     "(@code{EXPRSXP}s)."
1341 : gnustats 1339 msgstr ""
1342 :    
1343 :     #. type: item
1344 :     #: R-ints.texi:452
1345 :     #, no-wrap
1346 :     msgid "SPECIALSXP"
1347 :     msgstr ""
1348 :    
1349 :     #. type: itemx
1350 :     #: R-ints.texi:453
1351 :     #, no-wrap
1352 :     msgid "BUILTINSXP"
1353 :     msgstr ""
1354 :    
1355 :     #. type: table
1356 :     #: R-ints.texi:456
1357 : gnustats 1340 msgid ""
1358 :     "An integer giving the offset into the table of primitives/@code{.Internal}s."
1359 : gnustats 1339 msgstr ""
1360 :    
1361 :     #. type: item
1362 :     #: R-ints.texi:457
1363 :     #, no-wrap
1364 :     msgid "CHARSXP"
1365 :     msgstr ""
1366 :    
1367 :     #. type: table
1368 :     #: R-ints.texi:460
1369 : gnustats 1340 msgid ""
1370 :     "@code{length}, @code{truelength} followed by a block of bytes (allowing for "
1371 :     "the @code{nul} terminator)."
1372 : gnustats 1339 msgstr ""
1373 :    
1374 :     #. type: item
1375 :     #: R-ints.texi:461
1376 :     #, no-wrap
1377 :     msgid "LGLSXP"
1378 :     msgstr ""
1379 :    
1380 :     #. type: itemx
1381 :     #: R-ints.texi:462
1382 :     #, no-wrap
1383 :     msgid "INTSXP"
1384 :     msgstr ""
1385 :    
1386 :     #. type: table
1387 :     #: R-ints.texi:465
1388 : gnustats 1340 msgid ""
1389 :     "@code{length}, @code{truelength} followed by a block of C @code{int}s (which "
1390 :     "are 32 bits on all @R{} platforms)."
1391 : gnustats 1339 msgstr ""
1392 :    
1393 :     #. type: item
1394 :     #: R-ints.texi:466
1395 :     #, no-wrap
1396 :     msgid "REALSXP"
1397 :     msgstr ""
1398 :    
1399 :     #. type: table
1400 :     #: R-ints.texi:468
1401 : gnustats 1340 msgid ""
1402 :     "@code{length}, @code{truelength} followed by a block of C @code{double}s."
1403 : gnustats 1339 msgstr ""
1404 :    
1405 :     #. type: item
1406 :     #: R-ints.texi:469
1407 :     #, no-wrap
1408 :     msgid "CPLXSXP"
1409 :     msgstr ""
1410 :    
1411 :     #. type: table
1412 :     #: R-ints.texi:472
1413 : gnustats 1340 msgid ""
1414 :     "@code{length}, @code{truelength} followed by a block of C99 @code{double "
1415 :     "complex}s."
1416 : gnustats 1339 msgstr ""
1417 :    
1418 :     #. type: item
1419 :     #: R-ints.texi:473
1420 :     #, no-wrap
1421 :     msgid "STRSXP"
1422 :     msgstr ""
1423 :    
1424 :     #. type: table
1425 :     #: R-ints.texi:476
1426 : gnustats 1340 msgid ""
1427 :     "@code{length}, @code{truelength} followed by a block of pointers (@code{SEXP}"
1428 :     "s pointing to @code{CHARSXP}s)."
1429 : gnustats 1339 msgstr ""
1430 :    
1431 :     #. type: item
1432 :     #: R-ints.texi:477
1433 :     #, no-wrap
1434 :     msgid "DOTSXP"
1435 :     msgstr ""
1436 :    
1437 :     #. type: table
1438 :     #: R-ints.texi:480
1439 : gnustats 1340 msgid ""
1440 :     "A special type of @code{LISTSXP} for the value bound to a @code{...} symbol: "
1441 :     "a pairlist of promises."
1442 : gnustats 1339 msgstr ""
1443 :    
1444 :     #. type: item
1445 :     #: R-ints.texi:481
1446 :     #, no-wrap
1447 :     msgid "ANYSXP"
1448 :     msgstr ""
1449 :    
1450 :     #. type: table
1451 :     #: R-ints.texi:484
1452 : gnustats 1340 msgid ""
1453 :     "This is used as a place holder for any type: there are no actual objects of "
1454 :     "this type."
1455 : gnustats 1339 msgstr ""
1456 :    
1457 :     #. type: item
1458 :     #: R-ints.texi:485
1459 :     #, no-wrap
1460 :     msgid "VECSXP"
1461 :     msgstr ""
1462 :    
1463 :     #. type: itemx
1464 :     #: R-ints.texi:486
1465 :     #, no-wrap
1466 :     msgid "EXPRSXP"
1467 :     msgstr ""
1468 :    
1469 :     #. type: table
1470 :     #: R-ints.texi:490
1471 : gnustats 1340 msgid ""
1472 :     "@code{length}, @code{truelength} followed by a block of pointers. These are "
1473 :     "internally identical (and identical to @code{STRSXP}) but differ in the "
1474 :     "interpretations placed on the elements."
1475 : gnustats 1339 msgstr ""
1476 :    
1477 :     #. type: item
1478 :     #: R-ints.texi:491
1479 :     #, no-wrap
1480 :     msgid "BCODESXP"
1481 :     msgstr ""
1482 :    
1483 :     #. type: table
1484 :     #: R-ints.texi:493
1485 :     msgid "For the `byte-code' objects generated by the compiler."
1486 :     msgstr ""
1487 :    
1488 :     #. type: item
1489 :     #: R-ints.texi:494
1490 :     #, no-wrap
1491 :     msgid "EXTPTRSXP"
1492 :     msgstr ""
1493 :    
1494 :     #. type: table
1495 :     #: R-ints.texi:497
1496 : gnustats 1340 msgid ""
1497 :     "Has three pointers, to the pointer, the protection value (an @R{} object "
1498 :     "which if alive protects this object) and a tag (a @code{SYMSXP}?)."
1499 : gnustats 1339 msgstr ""
1500 :    
1501 :     #. type: item
1502 :     #: R-ints.texi:498
1503 :     #, no-wrap
1504 :     msgid "WEAKREFSXP"
1505 :     msgstr ""
1506 :    
1507 :     #. type: table
1508 :     #: R-ints.texi:503
1509 : gnustats 1340 msgid ""
1510 :     "A @code{WEAKREFSXP} is a special @code{VECSXP} of length 4, with elements "
1511 :     "@samp{key}, @samp{value}, @samp{finalizer} and @samp{next}. The @samp{key} "
1512 :     "is @code{NULL}, an environment or an external pointer, and the "
1513 :     "@samp{finalizer} is a function or @code{NULL}."
1514 : gnustats 1339 msgstr ""
1515 :    
1516 :     #. type: item
1517 :     #: R-ints.texi:504
1518 :     #, no-wrap
1519 :     msgid "RAWSXP"
1520 :     msgstr ""
1521 :    
1522 :     #. type: table
1523 :     #: R-ints.texi:506
1524 :     msgid "@code{length}, @code{truelength} followed by a block of bytes."
1525 :     msgstr ""
1526 :    
1527 :     #. type: item
1528 :     #: R-ints.texi:507
1529 :     #, no-wrap
1530 :     msgid "S4SXP"
1531 :     msgstr ""
1532 :    
1533 :     #. type: table
1534 :     #: R-ints.texi:509
1535 :     msgid "two unused pointers and a tag."
1536 :     msgstr ""
1537 :    
1538 :     #. type: cindex
1539 :     #: R-ints.texi:514
1540 :     #, no-wrap
1541 :     msgid "allocation classes"
1542 :     msgstr ""
1543 :    
1544 :     #. type: Plain text
1545 :     #: R-ints.texi:526
1546 : gnustats 1340 msgid ""
1547 :     "As we have seen, the field @code{gccls} in the header is three bits to label "
1548 :     "up to 8 classes of nodes. Non-vector nodes are of class 0, and `small' "
1549 :     "vector nodes are of classes 1 to 5, with a class for custom allocator vector "
1550 :     "nodes 6 and `large' vector nodes being of class 7. The `small' vector nodes "
1551 :     "are able to store vector data of up to 8, 16, 32, 64 and 128 bytes: larger "
1552 :     "vectors are @code{malloc}-ed individually whereas the `small' nodes are "
1553 :     "allocated from pages of about 2000 bytes. Vector nodes allocated using "
1554 :     "custom allocators (via @code{allocVector3}) are not counted in the gc memory "
1555 :     "usage statistics since their memory semantics is not under R's control and "
1556 :     "may be non-standard (e.g., memory could be partially shared across nodes)."
1557 : gnustats 1339 msgstr ""
1558 :    
1559 :     #. type: cindex
1560 :     #: R-ints.texi:531
1561 :     #, no-wrap
1562 :     msgid "environment"
1563 :     msgstr ""
1564 :    
1565 :     #. type: cindex
1566 :     #: R-ints.texi:532
1567 :     #, no-wrap
1568 :     msgid "variable lookup"
1569 :     msgstr ""
1570 :    
1571 :     #. type: Plain text
1572 :     #: R-ints.texi:538
1573 : gnustats 1340 msgid ""
1574 :     "What users think of as `variables' are symbols which are bound to objects in "
1575 :     "`environments'. The word `environment' is used ambiguously in @R{} to mean "
1576 :     "@emph{either} the frame of an @code{ENVSXP} (a pairlist of symbol-value "
1577 :     "pairs) @emph{or} an @code{ENVSXP}, a frame plus an enclosure."
1578 : gnustats 1339 msgstr ""
1579 :    
1580 :     #. type: cindex
1581 :     #: R-ints.texi:539
1582 :     #, no-wrap
1583 :     msgid "user databases"
1584 :     msgstr ""
1585 :    
1586 :     #. type: Plain text
1587 :     #: R-ints.texi:544
1588 : gnustats 1340 msgid ""
1589 :     "There are additional places that `variables' can be looked up, called `user "
1590 :     "databases' in comments in the code. These seem undocumented in the @R{} "
1591 :     "sources, but apparently refer to the @pkg{RObjectTable} package at "
1592 :     "@uref{http://www.omegahat.org/RObjectTables/}."
1593 : gnustats 1339 msgstr ""
1594 :    
1595 :     #. type: cindex
1596 :     #: R-ints.texi:545
1597 :     #: R-ints.texi:1715
1598 :     #, no-wrap
1599 :     msgid "base environment"
1600 :     msgstr ""
1601 :    
1602 :     #. type: cindex
1603 :     #: R-ints.texi:546
1604 :     #: R-ints.texi:1716
1605 :     #, no-wrap
1606 :     msgid "environment, base"
1607 :     msgstr ""
1608 :    
1609 :     #. type: Plain text
1610 :     #: R-ints.texi:558
1611 : gnustats 1340 msgid ""
1612 :     "The base environment is special. There is an @code{ENVSXP} environment with "
1613 :     "enclosure the empty environment @code{R_EmptyEnv}, but the frame of that "
1614 :     "environment is not used. Rather its bindings are part of the global symbol "
1615 :     "table, being those symbols in the global symbol table whose values are not "
1616 :     "@code{R_UnboundValue}. When @R{} is started the internal functions are "
1617 :     "installed (by C code) in the symbol table, with primitive functions having "
1618 :     "values and @code{.Internal} functions having what would be their values in "
1619 :     "the field accessed by the @code{INTERNAL} macro. Then @code{.Platform} and "
1620 :     "@code{.Machine} are computed and the base package is loaded into the base "
1621 :     "environment followed by the system profile."
1622 : gnustats 1339 msgstr ""
1623 :    
1624 :     #. type: Plain text
1625 :     #: R-ints.texi:561
1626 : gnustats 1340 msgid ""
1627 :     "The frames of environments (and the symbol table) are normally hashed for "
1628 :     "faster access (including insertion and deletion)."
1629 : gnustats 1339 msgstr ""
1630 :    
1631 :     #. type: Plain text
1632 :     #: R-ints.texi:572
1633 : gnustats 1340 msgid ""
1634 :     "By default @R{} maintains a (hashed) global cache of `variables' (that is "
1635 :     "symbols and their bindings) which have been found, and this refers only to "
1636 :     "environments which have been marked to participate, which consists of the "
1637 :     "global environment (aka the user workspace), the base environment plus "
1638 :     "environments@footnote{Remember that attaching a list or a saved image "
1639 :     "actually creates and populates an environment and attaches that.} which have "
1640 :     "been @code{attach}ed. When an environment is either @code{attach}ed or "
1641 :     "@code{detach}ed, the names of its symbols are flushed from the cache. The "
1642 :     "cache is used whenever searching for variables from the global environment "
1643 :     "(possibly as part of a recursive search)."
1644 : gnustats 1339 msgstr ""
1645 :    
1646 :     #. type: node
1647 :     #: R-ints.texi:577
1648 :     #: R-ints.texi:579
1649 :     #: R-ints.texi:580
1650 :     #: R-ints.texi:608
1651 :     #, no-wrap
1652 :     msgid "Search paths"
1653 :     msgstr ""
1654 :    
1655 :     #. type: node
1656 :     #: R-ints.texi:577
1657 :     #: R-ints.texi:579
1658 :     #: R-ints.texi:608
1659 :     #: R-ints.texi:609
1660 :     #: R-ints.texi:641
1661 :     #, no-wrap
1662 :     msgid "Namespaces"
1663 :     msgstr ""
1664 :    
1665 :     #. type: subsection
1666 :     #: R-ints.texi:577
1667 :     #: R-ints.texi:608
1668 :     #: R-ints.texi:641
1669 :     #: R-ints.texi:642
1670 :     #, no-wrap
1671 :     msgid "Hash table"
1672 :     msgstr ""
1673 :    
1674 :     #. type: cindex
1675 :     #: R-ints.texi:582
1676 :     #, no-wrap
1677 :     msgid "search path"
1678 :     msgstr ""
1679 :    
1680 :     #. type: Plain text
1681 :     #: R-ints.texi:589
1682 : gnustats 1340 msgid ""
1683 :     "@Sl{} has the notion of a `search path': the lookup for a `variable' leads "
1684 :     "(possibly through a series of frames) to the `session frame' the `working "
1685 :     "directory' and then along the search path. The search path is a series of "
1686 :     "databases (as returned by @code{search()}) which contain the system "
1687 :     "functions (but not necessarily at the end of the path, as by default the "
1688 :     "equivalent of packages are added at the end)."
1689 : gnustats 1339 msgstr ""
1690 :    
1691 :     #. type: Plain text
1692 :     #: R-ints.texi:596
1693 : gnustats 1340 msgid ""
1694 :     "@R{} has a variant on the @Sl{} model. There is a search path (also "
1695 :     "returned by @code{search()}) which consists of the global environment (aka "
1696 :     "user workspace) followed by environments which have been attached and "
1697 :     "finally the base environment. Note that unlike @Sl{} it is not possible to "
1698 :     "attach environments before the workspace nor after the base environment."
1699 : gnustats 1339 msgstr ""
1700 :    
1701 :     #. type: Plain text
1702 :     #: R-ints.texi:607
1703 : gnustats 1340 msgid ""
1704 :     "However, the notion of variable lookup is more general in @R{}, hence the "
1705 :     "plural in the title of this subsection. Since environments have enclosures, "
1706 :     "from any environment there is a search path found by looking in the frame, "
1707 :     "then the frame of its enclosure and so on. Since loops are not allowed, "
1708 :     "this process will eventually terminate: it can terminate at either the base "
1709 :     "environment or the empty environment. (It can be conceptually simpler to "
1710 :     "think of the search always terminating at the empty environment, but with an "
1711 :     "optimization to stop at the base environment.) So the `search path' "
1712 :     "describes the chain of environments which is traversed once the search "
1713 :     "reaches the global environment."
1714 : gnustats 1339 msgstr ""
1715 :    
1716 :     #. type: cindex
1717 :     #: R-ints.texi:611
1718 :     #, no-wrap
1719 :     msgid "namespace"
1720 :     msgstr ""
1721 :    
1722 :     #. type: Plain text
1723 :     #: R-ints.texi:618
1724 : gnustats 1340 msgid ""
1725 :     "Namespaces are environments associated with packages (and once again the "
1726 :     "base package is special and will be considered separately). A package "
1727 :     "@code{@var{pkg}} with a namespace defines two environments @code{namespace:"
1728 :     "@var{pkg}} and @code{package:@var{pkg}}: it is @code{package:@var{pkg}} that "
1729 :     "can be @code{attach}ed and form part of the search path."
1730 : gnustats 1339 msgstr ""
1731 :    
1732 :     #. type: Plain text
1733 :     #: R-ints.texi:630
1734 : gnustats 1340 msgid ""
1735 :     "The objects defined by the @R{} code in the package are symbols with "
1736 :     "bindings in the @code{namespace:@var{pkg}} environment. The @code{package:"
1737 :     "@var{pkg}} environment is populated by selected symbols from the "
1738 :     "@code{namespace:@var{pkg}} environment (the exports). The enclosure of this "
1739 :     "environment is an environment populated with the explicit imports from other "
1740 :     "namespaces, and the enclosure of @emph{that} environment is the base "
1741 :     "namespace. (So the illusion of the imports being in the namespace "
1742 :     "environment is created via the environment tree.) The enclosure of the base "
1743 :     "namespace is the global environment, so the search from a package namespace "
1744 :     "goes via the (explicit and implicit) imports to the standard `search path'."
1745 : gnustats 1339 msgstr ""
1746 :    
1747 :     #. type: cindex
1748 :     #: R-ints.texi:631
1749 :     #, no-wrap
1750 :     msgid "base namespace"
1751 :     msgstr ""
1752 :    
1753 :     #. type: cindex
1754 :     #: R-ints.texi:632
1755 :     #, no-wrap
1756 :     msgid "namespace, base"
1757 :     msgstr ""
1758 :    
1759 :     #. type: findex
1760 :     #: R-ints.texi:633
1761 :     #, no-wrap
1762 :     msgid "R_BaseNamespace"
1763 :     msgstr ""
1764 :    
1765 :     #. type: Plain text
1766 :     #: R-ints.texi:640
1767 : gnustats 1340 msgid ""
1768 :     "The base namespace environment @code{R_BaseNamespace} is another "
1769 :     "@code{ENVSXP} that is special-cased. It is effectively the same thing as "
1770 :     "the base environment @code{R_BaseEnv} @emph{except} that its enclosure is "
1771 :     "the global environment rather than the empty environment: the internal code "
1772 :     "diverts lookups in its frame to the global symbol table."
1773 : gnustats 1339 msgstr ""
1774 :    
1775 :     #. type: Plain text
1776 :     #: R-ints.texi:651
1777 : gnustats 1340 msgid ""
1778 :     "Environments in @R{} usually have a hash table, and nowadays that is the "
1779 :     "default in @code{new.env()}. It is stored as a @code{VECSXP} where "
1780 :     "@code{length} is used for the allocated size of the table and "
1781 :     "@code{truelength} is the number of primary slots in use---the pointer to the "
1782 :     "@code{VECSXP} is part of the header of a @code{SEXP} of type @code{ENVSXP}, "
1783 :     "and this points to @code{R_NilValue} if the environment is not hashed."
1784 : gnustats 1339 msgstr ""
1785 :    
1786 :     #. type: Plain text
1787 :     #: R-ints.texi:653
1788 :     msgid "For the pros and cons of hashing, see a basic text on Computer Science."
1789 :     msgstr ""
1790 :    
1791 :     #. type: Plain text
1792 :     #: R-ints.texi:659
1793 : gnustats 1340 msgid ""
1794 :     "The code to implement hashed environments is in @file{src/main/envir.c}. "
1795 :     "Unless set otherwise (e.g.@: by the @code{size} argument of @code{new."
1796 :     "env()}) the initial table size is @code{29}. The table will be resized by a "
1797 :     "factor of 1.2 once the load factor (the proportion of primary slots in use) "
1798 :     "reaches 85%."
1799 : gnustats 1339 msgstr ""
1800 :    
1801 :     #. type: Plain text
1802 :     #: R-ints.texi:665
1803 : gnustats 1340 msgid ""
1804 :     "The hash chains are stored as pairlist elements of the @code{VECSXP}: items "
1805 :     "are inserted at the front of the pairlist. Hashing is principally designed "
1806 :     "for fast searching of environments, which are from time to time added to but "
1807 :     "rarely deleted from, so items are not actually deleted but have their value "
1808 :     "set to @code{R_UnboundValue}."
1809 : gnustats 1339 msgstr ""
1810 :    
1811 :     #. type: cindex
1812 :     #: R-ints.texi:670
1813 :     #, no-wrap
1814 :     msgid "attributes"
1815 :     msgstr ""
1816 :    
1817 :     #. type: findex
1818 :     #: R-ints.texi:671
1819 :     #, no-wrap
1820 :     msgid "ATTRIB"
1821 :     msgstr ""
1822 :    
1823 :     #. type: findex
1824 :     #: R-ints.texi:672
1825 :     #, no-wrap
1826 :     msgid "SET_ATTRIB"
1827 :     msgstr ""
1828 :    
1829 :     #. type: findex
1830 :     #: R-ints.texi:673
1831 :     #, no-wrap
1832 :     msgid "DUPLICATE_ATTRIB"
1833 :     msgstr ""
1834 :    
1835 :     #. type: Plain text
1836 :     #: R-ints.texi:685
1837 : gnustats 1340 msgid ""
1838 :     "As we have seen, every @code{SEXPREC} has a pointer to the attributes of the "
1839 :     "node (default @code{R_NilValue}). The attributes can be accessed/set by the "
1840 :     "macros/functions @code{ATTRIB} and @code{SET_ATTRIB}, but such direct access "
1841 :     "is normally only used to check if the attributes are @code{NULL} or to reset "
1842 :     "them. Otherwise access goes through the functions @code{getAttrib} and "
1843 :     "@code{setAttrib} which impose restrictions on the attributes. One thing to "
1844 :     "watch is that if you copy attributes from one object to another you may "
1845 :     "(un)set the @code{\"class\"} attribute and so need to copy the object and S4 "
1846 :     "bits as well. There is a macro/function @code{DUPLICATE_ATTRIB} to automate "
1847 :     "this."
1848 : gnustats 1339 msgstr ""
1849 :    
1850 :     #. type: Plain text
1851 :     #: R-ints.texi:689
1852 : gnustats 1340 msgid ""
1853 :     "Note that the `attributes' of a @code{CHARSXP} are used as part of the "
1854 :     "management of the @code{CHARSXP} cache: of course @code{CHARSXP}'s are not "
1855 :     "user-visible but C-level code might look at their attributes."
1856 : gnustats 1339 msgstr ""
1857 :    
1858 :     #. type: Plain text
1859 :     #: R-ints.texi:701
1860 : gnustats 1340 msgid ""
1861 :     "The code assumes that the attributes of a node are either @code{R_NilValue} "
1862 :     "or a pairlist of non-zero length (and this is checked by "
1863 :     "@code{SET_ATTRIB}). The attributes are named (via tags on the pairlist). "
1864 :     "The replacement function @code{attributes<-} ensures that @code{\"dim\"} "
1865 :     "precedes @code{\"dimnames\"} in the pairlist. Attribute @code{\"dim\"} is "
1866 :     "one of several that is treated specially: the values are checked, and any "
1867 :     "@code{\"names\"} and @code{\"dimnames\"} attributes are removed. Similarly, "
1868 :     "you cannot set @code{\"dimnames\"} without having set @code{\"dim\"}, and "
1869 :     "the value assigned must be a list of the correct length and with elements of "
1870 :     "the correct lengths (and all zero-length elements are replaced by "
1871 :     "@code{NULL})."
1872 : gnustats 1339 msgstr ""
1873 :    
1874 :     #. type: Plain text
1875 :     #: R-ints.texi:715
1876 : gnustats 1340 msgid ""
1877 :     "The other attributes which are given special treatment are @code{\"names\"}, "
1878 :     "@code{\"class\"}, @code{\"tsp\"}, @code{\"comment\"} and @code{\"row.names"
1879 :     "\"}. For pairlist-like objects the names are not stored as an attribute but "
1880 :     "(as symbols) as the tags: however the @R{} interface makes them look like "
1881 :     "conventional attributes, and for one-dimensional arrays they are stored as "
1882 :     "the first element of the @code{\"dimnames\"} attribute. The C code ensures "
1883 :     "that the @code{\"tsp\"} attribute is an @code{REALSXP}, the frequency is "
1884 :     "positive and the implied length agrees with the number of rows of the object "
1885 :     "being assigned to. Classes and comments are restricted to character "
1886 :     "vectors, and assigning a zero-length comment or class removes the "
1887 :     "attribute. Setting or removing a @code{\"class\"} attribute sets the object "
1888 :     "bit appropriately. Integer row names are converted to and from the internal "
1889 :     "compact representation."
1890 : gnustats 1339 msgstr ""
1891 :    
1892 :     #. type: Plain text
1893 :     #: R-ints.texi:725
1894 : gnustats 1340 msgid ""
1895 :     "Care needs to be taken when adding attributes to objects of the types with "
1896 :     "non-standard copying semantics. There is only one object of type "
1897 :     "@code{NILSXP}, @code{R_NilValue}, and that should never have attributes (and "
1898 :     "this is enforced in @code{installAttrib}). For environments, external "
1899 :     "pointers and weak references, the attributes should be relevant to all uses "
1900 :     "of the object: it is for example reasonable to have a name for an "
1901 :     "environment, and also a @code{\"path\"} attribute for those environments "
1902 :     "populated from @R{} code in a package."
1903 : gnustats 1339 msgstr ""
1904 :    
1905 :     #. type: cindex
1906 :     #: R-ints.texi:726
1907 :     #, no-wrap
1908 :     msgid "attributes, preserving"
1909 :     msgstr ""
1910 :    
1911 :     #. type: cindex
1912 :     #: R-ints.texi:727
1913 :     #, no-wrap
1914 :     msgid "preserving attributes"
1915 :     msgstr ""
1916 :    
1917 :     #. type: Plain text
1918 :     #: R-ints.texi:734
1919 : gnustats 1340 msgid ""
1920 :     "When should attributes be preserved under operations on an object? Becker, "
1921 :     "Chambers & Wilks (1988, pp. 144--6) give some guidance. Scalar functions "
1922 :     "(those which operate element-by-element on a vector and whose output is "
1923 :     "similar to the input) should preserve attributes (except perhaps class, and "
1924 :     "if they do preserve class they need to preserve the @code{OBJECT} and S4 "
1925 :     "bits). Binary operations normally call"
1926 : gnustats 1339 msgstr ""
1927 :    
1928 :     #. type: findex
1929 :     #: R-ints.texi:734
1930 :     #, no-wrap
1931 :     msgid "copyMostAttributes"
1932 :     msgstr ""
1933 :    
1934 :     #. type: Plain text
1935 :     #: R-ints.texi:740
1936 : gnustats 1340 msgid ""
1937 :     "@code{copyMostAttributes} to copy most attributes from the longer argument "
1938 :     "(and if they are of the same length from both, preferring the values on the "
1939 :     "first). Here `most' means all except the @code{names}, @code{dim} and "
1940 :     "@code{dimnames} which are set appropriately by the code for the operator."
1941 : gnustats 1339 msgstr ""
1942 :    
1943 :     #. type: Plain text
1944 :     #: R-ints.texi:746
1945 : gnustats 1340 msgid ""
1946 :     "Subsetting (other than by an empty index) generally drops all attributes "
1947 :     "except @code{names}, @code{dim} and @code{dimnames} which are reset as "
1948 :     "appropriate. On the other hand, subassignment generally preserves such "
1949 :     "attributes even if the length is changed. Coercion drops all attributes. "
1950 :     "For example:"
1951 : gnustats 1339 msgstr ""
1952 :    
1953 :     #. type: example
1954 :     #: R-ints.texi:769
1955 :     #, no-wrap
1956 :     msgid ""
1957 :     "> x <- structure(1:8, names=letters[1:8], comm=\"a comment\")\n"
1958 :     "> x[]\n"
1959 :     "a b c d e f g h\n"
1960 :     "1 2 3 4 5 6 7 8\n"
1961 :     "attr(,\"comm\")\n"
1962 :     "[1] \"a comment\"\n"
1963 :     "> x[1:3]\n"
1964 :     "a b c\n"
1965 :     "1 2 3\n"
1966 :     "> x[3] <- 3\n"
1967 :     "> x\n"
1968 :     "a b c d e f g h\n"
1969 :     "1 2 3 4 5 6 7 8\n"
1970 :     "attr(,\"comm\")\n"
1971 :     "[1] \"a comment\"\n"
1972 :     "> x[9] <- 9\n"
1973 :     "> x\n"
1974 :     "a b c d e f g h\n"
1975 :     "1 2 3 4 5 6 7 8 9\n"
1976 :     "attr(,\"comm\")\n"
1977 :     "[1] \"a comment\"\n"
1978 :     msgstr ""
1979 :    
1980 :     #. type: cindex
1981 :     #: R-ints.texi:775
1982 :     #, no-wrap
1983 :     msgid "context"
1984 :     msgstr ""
1985 :    
1986 :     #. type: Plain text
1987 :     #: R-ints.texi:781
1988 : gnustats 1340 msgid ""
1989 :     "@emph{Contexts} are the internal mechanism used to keep track of where a "
1990 :     "computation has got to (and from where), so that control-flow constructs can "
1991 :     "work and reasonable information can be produced on error conditions (such as "
1992 :     "@emph{via} traceback), and otherwise (the @code{sys.@var{xxx}} functions)."
1993 : gnustats 1339 msgstr ""
1994 :    
1995 :     #. type: Plain text
1996 :     #: R-ints.texi:783
1997 :     msgid "Execution contexts are a stack of C @code{structs}:"
1998 :     msgstr ""
1999 :    
2000 :     #. type: example
2001 :     #: R-ints.texi:805
2002 :     #, no-wrap
2003 :     msgid ""
2004 :     "typedef struct RCNTXT @{\n"
2005 :     " struct RCNTXT *nextcontext; /* @r{The next context up the chain} */\n"
2006 :     " int callflag; /* @r{The context `type'} */\n"
2007 :     " JMP_BUF cjmpbuf; /* @r{C stack and register information} */\n"
2008 :     " int cstacktop; /* @r{Top of the pointer protection stack} */\n"
2009 :     " int evaldepth; /* @r{Evaluation depth at inception} */\n"
2010 :     " SEXP promargs; /* @r{Promises supplied to closure} */\n"
2011 :     " SEXP callfun; /* @r{The closure called} */\n"
2012 :     " SEXP sysparent; /* @r{Environment the closure was called from} */\n"
2013 :     " SEXP call; /* @r{The call that effected this context} */\n"
2014 :     " SEXP cloenv; /* @r{The environment} */\n"
2015 :     " SEXP conexit; /* @r{Interpreted @code{on.exit} code} */\n"
2016 :     " void (*cend)(void *); /* @r{C @code{on.exit} thunk} */\n"
2017 :     " void *cenddata; /* @r{Data for C @code{on.exit} thunk} */\n"
2018 :     " char *vmax; /* @r{Top of the @code{R_alloc} stack} */\n"
2019 :     " int intsusp; /* @r{Interrupts are suspended} */\n"
2020 :     " SEXP handlerstack; /* @r{Condition handler stack} */\n"
2021 :     " SEXP restartstack; /* @r{Stack of available restarts} */\n"
2022 :     " struct RPRSTACK *prstack; /* @r{Stack of pending promises} */\n"
2023 :     "@} RCNTXT, *context;\n"
2024 :     msgstr ""
2025 :    
2026 :     #. type: Plain text
2027 :     #: R-ints.texi:810
2028 : gnustats 1340 msgid ""
2029 :     "plus additional fields for the byte-code compiler. The `types' are from"
2030 : gnustats 1339 msgstr ""
2031 :    
2032 :     #. type: example
2033 :     #: R-ints.texi:825
2034 :     #, no-wrap
2035 :     msgid ""
2036 :     "enum @{\n"
2037 :     " CTXT_TOPLEVEL = 0, /* @r{toplevel context} */\n"
2038 :     " CTXT_NEXT = 1, /* @r{target for @code{next}} */\n"
2039 :     " CTXT_BREAK = 2, /* @r{target for @code{break}} */\n"
2040 :     " CTXT_LOOP = 3, /* @r{@code{break} or @code{next} target} */\n"
2041 :     " CTXT_FUNCTION = 4, /* @r{function closure} */\n"
2042 :     " CTXT_CCODE = 8, /* @r{other functions that need error cleanup} */\n"
2043 :     " CTXT_RETURN = 12, /* @r{@code{return()} from a closure} */\n"
2044 :     " CTXT_BROWSER = 16, /* @r{return target on exit from browser} */\n"
2045 :     " CTXT_GENERIC = 20, /* @r{rather, running an S3 method} */\n"
2046 :     " CTXT_RESTART = 32, /* @r{a call to @code{restart} was made from a closure} */\n"
2047 :     " CTXT_BUILTIN = 64 /* @r{builtin internal function} */\n"
2048 :     "@};\n"
2049 :     msgstr ""
2050 :    
2051 :     #. type: Plain text
2052 :     #: R-ints.texi:830
2053 : gnustats 1340 msgid ""
2054 :     "where the @code{CTXT_FUNCTION} bit is on wherever function closures are "
2055 :     "involved."
2056 : gnustats 1339 msgstr ""
2057 :    
2058 :     #. type: Plain text
2059 :     #: R-ints.texi:837
2060 : gnustats 1340 msgid ""
2061 :     "Contexts are created by a call to @code{begincontext} and ended by a call to "
2062 :     "@code{endcontext}: code can search up the stack for a particular type of "
2063 :     "context via @code{findcontext} (and jump there) or jump to a specific "
2064 :     "context via @code{R_JumpToContext}. @code{R_ToplevelContext} is the `idle' "
2065 :     "state (normally the command prompt), and @code{R_GlobalContext} is the top "
2066 :     "of the stack."
2067 : gnustats 1339 msgstr ""
2068 :    
2069 :     #. type: Plain text
2070 :     #: R-ints.texi:840
2071 : gnustats 1340 msgid ""
2072 :     "Note that whilst calls to closures and builtins set a context, those to "
2073 :     "special internal functions never do."
2074 : gnustats 1339 msgstr ""
2075 :    
2076 :     #. type: findex
2077 :     #: R-ints.texi:841
2078 :     #, no-wrap
2079 :     msgid "UseMethod"
2080 :     msgstr ""
2081 :    
2082 :     #. type: cindex
2083 :     #: R-ints.texi:842
2084 :     #, no-wrap
2085 :     msgid "method dispatch"
2086 :     msgstr ""
2087 :    
2088 :     #. type: Plain text
2089 :     #: R-ints.texi:848
2090 : gnustats 1340 msgid ""
2091 :     "Dispatching from a S3 generic (via @code{UseMethod} or its internal "
2092 :     "equivalent) or calling @code{NextMethod} sets the context type to "
2093 :     "@code{CTXT_GENERIC}. This is used to set the @code{sysparent} of the method "
2094 :     "call to that of the @code{generic}, so the method appears to have been "
2095 :     "called in place of the generic rather than from the generic."
2096 : gnustats 1339 msgstr ""
2097 :    
2098 :     #. type: Plain text
2099 :     #: R-ints.texi:852
2100 : gnustats 1340 msgid ""
2101 :     "The @R{} @code{sys.frame} and @code{sys.call} functions work by counting "
2102 :     "calls to closures (type @code{CTXT_FUNCTION}) from either end of the context "
2103 :     "stack."
2104 : gnustats 1339 msgstr ""
2105 :    
2106 :     #. type: Plain text
2107 :     #: R-ints.texi:857
2108 : gnustats 1340 msgid ""
2109 :     "Note that the @code{sysparent} element of the structure is not the same "
2110 :     "thing as @code{sys.parent()}. Element @code{sysparent} is primarily used in "
2111 :     "managing changes of the function being evaluated, i.e. by @code{Recall} and "
2112 :     "method dispatch."
2113 : gnustats 1339 msgstr ""
2114 :    
2115 :     #. type: Plain text
2116 :     #: R-ints.texi:863
2117 : gnustats 1340 msgid ""
2118 :     "@code{CTXT_CCODE} contexts are currently used in @code{cat()}, "
2119 :     "@code{load()}, @code{scan()} and @code{write.table()} (to close the "
2120 :     "connection on error), by @code{PROTECT}, serialization (to recover from "
2121 :     "errors, e.g.@: free buffers) and within the error handling code (to raise "
2122 :     "the C stack limit and reset some variables)."
2123 : gnustats 1339 msgstr ""
2124 :    
2125 :     #. type: cindex
2126 :     #: R-ints.texi:868
2127 :     #, no-wrap
2128 :     msgid "argument evaluation"
2129 :     msgstr ""
2130 :    
2131 :     #. type: Plain text
2132 :     #: R-ints.texi:875
2133 : gnustats 1340 msgid ""
2134 :     "As we have seen, functions in @R{} come in three types, closures "
2135 :     "(@code{SEXPTYPE} @code{CLOSXP}), specials (@code{SPECIALSXP}) and builtins "
2136 :     "(@code{BUILTINSXP}). In this section we consider when (and if) the actual "
2137 :     "arguments of function calls are evaluated. The rules are different for the "
2138 :     "internal (special/builtin) and @R{}-level functions (closures)."
2139 : gnustats 1339 msgstr ""
2140 :    
2141 :     #. type: Plain text
2142 :     #: R-ints.texi:886
2143 : gnustats 1340 msgid ""
2144 :     "For a call to a closure, the actual and formal arguments are matched and a "
2145 :     "matched call (another @code{LANGSXP}) is constructed. This process first "
2146 :     "replaces the actual argument list by a list of promises to the values "
2147 :     "supplied. It then constructs a new environment which contains the names of "
2148 :     "the formal parameters matched to actual or default values: all the matched "
2149 :     "values are promises, the defaults as promises to be evaluated in the "
2150 :     "environment just created. That environment is then used for the evaluation "
2151 :     "of the body of the function, and promises will be forced (and hence actual "
2152 :     "or default arguments evaluated) when they are encountered."
2153 : gnustats 1339 msgstr ""
2154 :    
2155 :     #. type: Plain text
2156 :     #: R-ints.texi:890
2157 : gnustats 1340 msgid ""
2158 :     "(Evaluating a promise sets @code{NAMED = 2} on its value, so if the argument "
2159 :     "was a symbol its binding is regarded as having multiple references during "
2160 :     "the evaluation of the closure call.)"
2161 : gnustats 1339 msgstr ""
2162 :    
2163 :     #. type: Plain text
2164 :     #: R-ints.texi:906
2165 : gnustats 1340 msgid ""
2166 :     "If the closure is an S3 generic (that is, contains a call to "
2167 :     "@code{UseMethod}) the evaluation process is the same until the "
2168 :     "@code{UseMethod} call is encountered. At that point the argument on which "
2169 :     "to do dispatch (normally the first) will be evaluated if it has not been "
2170 :     "already. If a method has been found which is a closure, a new evaluation "
2171 :     "environment is created for it containing the matched arguments of the method "
2172 :     "plus any new variables defined so far during the evaluation of the body of "
2173 :     "the generic. (Note that this means changes to the values of the formal "
2174 :     "arguments in the body of the generic are discarded when calling the method, "
2175 :     "but @emph{actual} argument promises which have been forced retain the values "
2176 :     "found when they were forced. On the other hand, missing arguments have "
2177 :     "values which are promises to use the default supplied by the method and not "
2178 :     "by the generic.) If the method found is a primitive it is called with the "
2179 :     "matched argument list of promises (possibly already forced) used for the "
2180 :     "generic."
2181 : gnustats 1339 msgstr ""
2182 :    
2183 :     #. type: cindex
2184 :     #: R-ints.texi:907
2185 :     #, no-wrap
2186 :     msgid "builtin function"
2187 :     msgstr ""
2188 :    
2189 :     #. type: cindex
2190 :     #: R-ints.texi:908
2191 :     #, no-wrap
2192 :     msgid "special function"
2193 :     msgstr ""
2194 :    
2195 :     #. type: cindex
2196 :     #: R-ints.texi:909
2197 :     #, no-wrap
2198 :     msgid "primitive function"
2199 :     msgstr ""
2200 :    
2201 :     #. type: cindex
2202 :     #: R-ints.texi:910
2203 :     #, no-wrap
2204 :     msgid ".Internal function"
2205 :     msgstr ""
2206 :    
2207 :     #. type: Plain text
2208 :     #: R-ints.texi:919
2209 : gnustats 1340 msgid ""
2210 :     "The essential difference@footnote{There is currently one other difference: "
2211 :     "when profiling builtin functions are counted as function calls but specials "
2212 :     "are not.} between special and builtin functions is that the arguments of "
2213 :     "specials are not evaluated before the C code is called, and those of "
2214 :     "builtins are. Note that being a special/builtin is separate from being "
2215 :     "primitive or @code{.Internal}: @code{quote} is a special primitive, @code{+} "
2216 :     "is a builtin primitive, @code{cbind} is a special @code{.Internal} and "
2217 :     "@code{grep} is a builtin @code{.Internal}."
2218 : gnustats 1339 msgstr ""
2219 :    
2220 :     #. type: cindex
2221 :     #: R-ints.texi:920
2222 :     #, no-wrap
2223 :     msgid "generic, internal"
2224 :     msgstr ""
2225 :    
2226 :     #. type: findex
2227 :     #: R-ints.texi:921
2228 :     #, no-wrap
2229 :     msgid "DispatchOrEval"
2230 :     msgstr ""
2231 :    
2232 :     #. type: Plain text
2233 :     #: R-ints.texi:931
2234 : gnustats 1340 msgid ""
2235 :     "Many of the internal functions are internal generics, which for specials "
2236 :     "means that they do not evaluate their arguments on call, but the C code "
2237 :     "starts with a call to @code{DispatchOrEval}. The latter evaluates the first "
2238 :     "argument, and looks for a method based on its class. (If S4 dispatch is on, "
2239 :     "S4 methods are looked for first, even for S3 classes.) If it finds a "
2240 :     "method, it dispatches to that method with a call based on promises to "
2241 :     "evaluate the remaining arguments. If no method is found, the remaining "
2242 :     "arguments are evaluated before return to the internal generic."
2243 : gnustats 1339 msgstr ""
2244 :    
2245 :     #. type: cindex
2246 :     #: R-ints.texi:932
2247 :     #, no-wrap
2248 :     msgid "generic, generic"
2249 :     msgstr ""
2250 :    
2251 :     #. type: findex
2252 :     #: R-ints.texi:933
2253 :     #, no-wrap
2254 :     msgid "DispatchGeneric"
2255 :     msgstr ""
2256 :    
2257 :     #. type: Plain text
2258 :     #: R-ints.texi:942
2259 : gnustats 1340 msgid ""
2260 :     "The other way that internal functions can be generic is to be group "
2261 :     "generic. Most such functions are builtins (so immediately evaluate all "
2262 :     "their arguments), and all contain a call to the C function "
2263 :     "@code{DispatchGeneric}. There are some peculiarities over the number of "
2264 :     "arguments for the @code{\"Math\"} group generic, with some members allowing "
2265 :     "only one argument, some having two (with a default for the second) and "
2266 :     "@code{trunc} allows one or more but the default method only accepts one."
2267 : gnustats 1339 msgstr ""
2268 :    
2269 :     #. type: node
2270 :     #: R-ints.texi:946
2271 :     #: R-ints.texi:948
2272 :     #: R-ints.texi:949
2273 :     #: R-ints.texi:993
2274 :     #, no-wrap
2275 :     msgid "Missingness"
2276 :     msgstr ""
2277 :    
2278 :     #. type: subsection
2279 :     #: R-ints.texi:946
2280 :     #: R-ints.texi:948
2281 :     #: R-ints.texi:993
2282 :     #: R-ints.texi:994
2283 :     #, no-wrap
2284 :     msgid "Dot-dot-dot arguments"
2285 :     msgstr ""
2286 :    
2287 :     #. type: cindex
2288 :     #: R-ints.texi:951
2289 :     #, no-wrap
2290 :     msgid "missingness"
2291 :     msgstr ""
2292 :    
2293 :     #. type: Plain text
2294 :     #: R-ints.texi:958
2295 : gnustats 1340 msgid ""
2296 :     "Actual arguments to (non-internal) @R{} functions can be fewer than are "
2297 :     "required to match the formal arguments of the function. Having unmatched "
2298 :     "formal arguments will not matter if the argument is never used (by lazy "
2299 :     "evaluation), but when the argument is evaluated, either its default value is "
2300 :     "evaluated (within the evaluation environment of the function) or an error is "
2301 :     "thrown with a message along the lines of"
2302 : gnustats 1339 msgstr ""
2303 :    
2304 :     #. type: example
2305 :     #: R-ints.texi:961
2306 :     #, no-wrap
2307 :     msgid "argument \"foobar\" is missing, with no default\n"
2308 :     msgstr ""
2309 :    
2310 :     #. type: findex
2311 :     #: R-ints.texi:964
2312 :     #, no-wrap
2313 :     msgid "R_MissingArg"
2314 :     msgstr ""
2315 :    
2316 :     #. type: Plain text
2317 :     #: R-ints.texi:974
2318 : gnustats 1340 msgid ""
2319 :     "Internally missingness is handled by two mechanisms. The object "
2320 :     "@code{R_MissingArg} is used to indicate that a formal argument has no "
2321 :     "(default) value. When matching the actual arguments to the formal "
2322 :     "arguments, a new argument list is constructed from the formals all of whose "
2323 :     "values are @code{R_MissingArg} with the first @code{MISSING} bit set. Then "
2324 :     "whenever a formal argument is matched to an actual argument, the "
2325 :     "corresponding member of the new argument list has its value set to that of "
2326 :     "the matched actual argument, and if that is not @code{R_MissingArg} the "
2327 :     "missing bit is unset."
2328 : gnustats 1339 msgstr ""
2329 :    
2330 :     #. type: Plain text
2331 :     #: R-ints.texi:978
2332 : gnustats 1340 msgid ""
2333 :     "This new argument list is used to form the evaluation frame for the "
2334 :     "function, and if named arguments are subsequently given a new value (before "
2335 :     "they are evaluated) the missing bit is cleared."
2336 : gnustats 1339 msgstr ""
2337 :    
2338 :     #. type: Plain text
2339 :     #: R-ints.texi:987
2340 : gnustats 1340 msgid ""
2341 :     "Missingness of arguments can be interrogated via the @code{missing()} "
2342 :     "function. An argument is clearly missing if its missing bit is set or if "
2343 :     "the value is @code{R_MissingArg}. However, missingness can be passed on "
2344 :     "from function to function, for using a formal argument as an actual argument "
2345 :     "in a function call does not count as evaluation. So @code{missing()} has to "
2346 :     "examine the value (a promise) of a non-yet-evaluated formal argument to see "
2347 :     "if it might be missing, which might involve investigating a promise and so "
2348 :     "on @dots{}."
2349 : gnustats 1339 msgstr ""
2350 :    
2351 :     #. type: Plain text
2352 :     #: R-ints.texi:992
2353 : gnustats 1340 msgid ""
2354 :     "Special primitives also need to handle missing arguments, and in some case "
2355 :     "(e.g.@: @code{log}) that is why they are special and not builtin. This is "
2356 :     "usually done by testing if an argument's value is @code{R_MissingArg}."
2357 : gnustats 1339 msgstr ""
2358 :    
2359 :     #. type: Plain text
2360 :     #: R-ints.texi:999
2361 : gnustats 1340 msgid ""
2362 :     "Dot-dot-dot arguments are convenient when writing functions, but complicate "
2363 :     "the internal code for argument evaluation."
2364 : gnustats 1339 msgstr ""
2365 :    
2366 :     #. type: Plain text
2367 :     #: R-ints.texi:1006
2368 : gnustats 1340 msgid ""
2369 :     "The formals of a function with a @code{...} argument represent that as a "
2370 :     "single argument like any other argument, with tag the symbol "
2371 :     "@code{R_DotsSymbol}. When the actual arguments are matched to the formals, "
2372 :     "the value of the @code{...} argument is of @code{SEXPTYPE} @code{DOTSXP}, a "
2373 :     "pairlist of promises (as used for matched arguments) but distinguished by "
2374 :     "the @code{SEXPTYPE}."
2375 : gnustats 1339 msgstr ""
2376 :    
2377 :     #. type: Plain text
2378 :     #: R-ints.texi:1014
2379 : gnustats 1340 msgid ""
2380 :     "Recall that the evaluation frame for a function initially contains the "
2381 :     "@code{@var{name}=@var{value}} pairs from the matched call, and hence this "
2382 :     "will be true for @code{...} as well. The value of @code{...} is a (special) "
2383 :     "pairlist whose elements are referred to by the special symbols @code{..1}, "
2384 :     "@code{..2}, @dots{} which have the @code{DDVAL} bit set: when one of these "
2385 :     "is encountered it is looked up (via @code{ddfindVar}) in the value of the "
2386 :     "@code{...} symbol in the evaluation frame."
2387 : gnustats 1339 msgstr ""
2388 :    
2389 :     #. type: Plain text
2390 :     #: R-ints.texi:1016
2391 :     msgid "Values of arguments matched to a @code{...} argument can be missing."
2392 :     msgstr ""
2393 :    
2394 :     #. type: Plain text
2395 :     #: R-ints.texi:1020
2396 : gnustats 1340 msgid ""
2397 :     "Special primitives may need to handle @code{...} arguments: see for example "
2398 :     "the internal code of @code{switch} in file @file{src/main/builtin.c}."
2399 : gnustats 1339 msgstr ""
2400 :    
2401 :     #. type: cindex
2402 :     #: R-ints.texi:1024
2403 :     #, no-wrap
2404 :     msgid "autoprinting"
2405 :     msgstr ""
2406 :    
2407 :     #. type: findex
2408 :     #: R-ints.texi:1025
2409 :     #, no-wrap
2410 :     msgid "R_Visible"
2411 :     msgstr ""
2412 :    
2413 :     #. type: Plain text
2414 :     #: R-ints.texi:1033
2415 : gnustats 1340 msgid ""
2416 :     "Whether the returned value of a top-level @R{} expression is printed is "
2417 :     "controlled by the global boolean variable @code{R_Visible}. This is set (to "
2418 :     "true or false) on entry to all primitive and internal functions based on the "
2419 :     "@code{eval} column of the table in file @file{src/main/names.c}: the "
2420 :     "appropriate setting can be extracted by the macro @code{PRIMPRINT}."
2421 : gnustats 1339 msgstr ""
2422 :    
2423 :     #. type: findex
2424 :     #: R-ints.texi:1033
2425 :     #, no-wrap
2426 :     msgid "PRIMPRINT"
2427 :     msgstr ""
2428 :    
2429 :     #. type: findex
2430 :     #: R-ints.texi:1035
2431 :     #, no-wrap
2432 :     msgid "invisible"
2433 :     msgstr ""
2434 :    
2435 :     #. type: Plain text
2436 :     #: R-ints.texi:1039
2437 : gnustats 1340 msgid ""
2438 :     "The @R{} primitive function @code{invisible} makes use of this mechanism: it "
2439 :     "just sets @code{R_Visible = FALSE} before entry and returns its argument."
2440 : gnustats 1339 msgstr ""
2441 :    
2442 :     #. type: Plain text
2443 :     #: R-ints.texi:1051
2444 : gnustats 1340 msgid ""
2445 :     "For most functions the intention will be that the setting of "
2446 :     "@code{R_Visible} when they are entered is the setting used when they return, "
2447 :     "but there need to be exceptions. The @R{} functions @code{identify}, "
2448 :     "@code{options}, @code{system} and @code{writeBin} determine whether the "
2449 :     "result should be visible from the arguments or user action. Other functions "
2450 :     "themselves dispatch functions which may change the visibility flag: "
2451 :     "examples@footnote{the other current example is left brace, which is "
2452 :     "implemented as a primitive.} are @code{.Internal}, @code{do.call}, "
2453 :     "@code{eval}, @code{withVisible}, @code{if}, @code{NextMethod}, "
2454 :     "@code{Recall}, @code{recordGraphics}, @code{standardGeneric}, @code{switch} "
2455 :     "and @code{UseMethod}."
2456 : gnustats 1339 msgstr ""
2457 :    
2458 :     #. type: Plain text
2459 :     #: R-ints.texi:1056
2460 : gnustats 1340 msgid ""
2461 :     "`Special' primitive and internal functions evaluate their arguments "
2462 :     "internally @emph{after} @code{R_Visible} has been set, and evaluation of the "
2463 :     "arguments (e.g.@: an assignment as in PR#9263)) can change the value of the "
2464 :     "flag."
2465 : gnustats 1339 msgstr ""
2466 :    
2467 :     #. type: Plain text
2468 :     #: R-ints.texi:1066
2469 : gnustats 1340 msgid ""
2470 :     "The @code{R_Visible} flag can also get altered during the evaluation of a "
2471 :     "function, with comments in the code about @code{warning}, @code{writeChar} "
2472 :     "and graphics functions calling @code{GText} (PR#7397). (Since the C-level "
2473 :     "function @code{eval} sets @code{R_Visible}, this could apply to any function "
2474 :     "calling it. Since it is called when evaluating promises, even object lookup "
2475 :     "can change @code{R_Visible}.) Internal and primitive functions force the "
2476 :     "documented setting of @code{R_Visible} on return, unless the C code is "
2477 :     "allowed to change it (the exceptions above are indicated by @code{PRIMPRINT} "
2478 :     "having value 2)."
2479 : gnustats 1339 msgstr ""
2480 :    
2481 :     #. type: Plain text
2482 :     #: R-ints.texi:1074
2483 : gnustats 1340 msgid ""
2484 :     "The actual autoprinting is done by @code{PrintValueEnv} in file @file{print."
2485 :     "c}. If the object to be printed has the S4 bit set and S4 methods dispatch "
2486 :     "is on, @code{show} is called to print the object. Otherwise, if the object "
2487 :     "bit is set (so the object has a @code{\"class\"} attribute), @code{print} is "
2488 :     "called to dispatch methods: for objects without a class the internal code of "
2489 :     "@code{print.default} is called."
2490 : gnustats 1339 msgstr ""
2491 :    
2492 :     #. type: section
2493 :     #: R-ints.texi:1077
2494 :     #, no-wrap
2495 :     msgid "The write barrier and the garbage collector"
2496 :     msgstr ""
2497 :    
2498 :     #. type: cindex
2499 :     #: R-ints.texi:1079
2500 :     #, no-wrap
2501 :     msgid "write barrier"
2502 :     msgstr ""
2503 :    
2504 :     #. type: cindex
2505 :     #: R-ints.texi:1080
2506 :     #, no-wrap
2507 :     msgid "garbage collector"
2508 :     msgstr ""
2509 :    
2510 :     #. type: Plain text
2511 :     #: R-ints.texi:1085
2512 : gnustats 1340 msgid ""
2513 :     "@R{} has long had a generational garbage collector, and bit @code{gcgen} in "
2514 :     "the @code{sxpinfo} header is used in the implementation of this. This is "
2515 :     "used in conjunction with the @code{mark} bit to identify two previous "
2516 :     "generations."
2517 : gnustats 1339 msgstr ""
2518 :    
2519 :     #. type: Plain text
2520 :     #: R-ints.texi:1094
2521 : gnustats 1340 msgid ""
2522 :     "There are three levels of collections. Level 0 collects only the youngest "
2523 :     "generation, level 1 collects the two youngest generations and level 2 "
2524 :     "collects all generations. After 20 level-0 collections the next collection "
2525 :     "is at level 1, and after 5 level-1 collections at level 2. Further, if a "
2526 :     "level-@var{n} collection fails to provide 20% free space (for each of nodes "
2527 :     "and the vector heap), the next collection will be at level @var{n+1}. (The "
2528 :     "@R{}-level function @code{gc()} performs a level-2 collection.)"
2529 : gnustats 1339 msgstr ""
2530 :    
2531 :     #. type: Plain text
2532 :     #: R-ints.texi:1104
2533 : gnustats 1340 msgid ""
2534 :     "A generational collector needs to efficiently `age' the objects, especially "
2535 :     "list-like objects (including @code{STRSXP}s). This is done by ensuring that "
2536 :     "the elements of a list are regarded as at least as old as the list "
2537 :     "@emph{when they are assigned}. This is handled by the functions "
2538 :     "@code{SET_VECTOR_ELT} and @code{SET_STRING_ELT}, which is why they are "
2539 :     "functions and not macros. Ensuring the integrity of such operations is "
2540 :     "termed the @dfn{write barrier} and is done by making the @code{SEXP} opaque "
2541 :     "and only providing access via functions (which cannot be used as lvalues in "
2542 :     "assignments in C)."
2543 : gnustats 1339 msgstr ""
2544 :    
2545 :     #. type: Plain text
2546 :     #: R-ints.texi:1116
2547 : gnustats 1340 msgid ""
2548 :     "All code in @R{} extensions is by default behind the write barrier. The "
2549 :     "only way to obtain direct access to the internals of the @code{SEXPREC}s is "
2550 :     "to define @samp{USE_RINTERNALS} before including header file "
2551 :     "@file{Rinternals.h}, which is normally defined in @file{Defn.h}. To enable "
2552 :     "a check on the way that the access is used, @R{} can be compiled with flag "
2553 :     "@option{--enable-strict-barrier} which ensures that header @file{Defn.h} "
2554 :     "does not define @samp{USE_RINTERNALS} and hence that @code{SEXP} is opaque "
2555 :     "in most of @R{} itself. (There are some necessary exceptions: foremost in "
2556 :     "file @file{memory.c} where the accessor functions are defined and also in "
2557 :     "file @file{size.c} which needs access to the sizes of the internal "
2558 :     "structures.)"
2559 : gnustats 1339 msgstr ""
2560 :    
2561 :     #. type: Plain text
2562 :     #: R-ints.texi:1120
2563 : gnustats 1340 msgid ""
2564 :     "For background papers see @uref{http://www.stat.uiowa.edu/~luke/R/barrier."
2565 :     "html} and @uref{http://www.stat.uiowa.edu/~luke/R/gengcnotes.html}."
2566 : gnustats 1339 msgstr ""
2567 :    
2568 :     #. type: cindex
2569 :     #: R-ints.texi:1124
2570 :     #, no-wrap
2571 :     msgid "serialization"
2572 :     msgstr ""
2573 :    
2574 :     #. type: Plain text
2575 :     #: R-ints.texi:1134
2576 : gnustats 1340 msgid ""
2577 :     "Serialized versions of @R{} objects are used by @code{load}/@code{save} and "
2578 :     "also at a slightly lower level by @code{saveRDS}/@code{readRDS} (and their "
2579 :     "earlier `internal' dot-name versions) and @code{serialize}/"
2580 :     "@code{unserialize}. These differ in what they serialize to (a file, a "
2581 :     "connection, a raw vector) and whether they are intended to serialize a "
2582 :     "single object or a collection of objects (typically the workspace). "
2583 :     "@code{save} writes a header at the beginning of the file (a single LF-"
2584 :     "terminated line) which the lower-level versions do not."
2585 : gnustats 1339 msgstr ""
2586 :    
2587 :     #. type: Plain text
2588 :     #: R-ints.texi:1143
2589 : gnustats 1340 msgid ""
2590 :     "@code{save} and @code{saveRDS} allow various forms of compression, and "
2591 :     "@command{gzip} compression is the default (except for @acronym{ASCII} "
2592 :     "saves). Compression is applied to the whole file stream, including the "
2593 :     "headers, so serialized files can be uncompressed or re-compressed by "
2594 :     "external programs. Both @code{load} and @code{readRDS} can read "
2595 :     "@command{gzip}, @command{bzip2} and @command{xz} forms of compression when "
2596 :     "reading from a file, and @command{gzip} compression when reading from a "
2597 :     "connection."
2598 : gnustats 1339 msgstr ""
2599 :    
2600 :     #. type: Plain text
2601 :     #: R-ints.texi:1150
2602 : gnustats 1340 msgid ""
2603 :     "@R{} has used the same serialization format since @R{} 1.4.0 in December "
2604 :     "2001. Earlier formats are still supported via @code{load} and @code{save} "
2605 :     "but such formats are not described here. The current serialization format is "
2606 :     "called `version 2', and has been expanded in back-compatible ways since its "
2607 :     "inception, for example to support additional @code{SEXPTYPE}s."
2608 : gnustats 1339 msgstr ""
2609 :    
2610 :     #. type: Plain text
2611 :     #: R-ints.texi:1164
2612 : gnustats 1340 msgid ""
2613 :     "@code{save} works by writing a single-line header (typically @code{RDX2\\n} "
2614 :     "for a binary save: the only other current value is @code{RDA2\\n} for "
2615 :     "@code{save(files=TRUE)}), then creating a tagged pairlist of the objects to "
2616 :     "be saved and serializing that single object. @code{load} reads the header "
2617 :     "line, unserializes a single object (a pairlist or a vector list) and assigns "
2618 :     "the elements of the object in the specified environment. The header line "
2619 :     "serves two purposes in @R{}: it identifies the serialization format so "
2620 :     "@code{load} can switch to the appropriate reader code, and the linefeed "
2621 :     "allows the detection of files which have been subjected to a non-binary "
2622 :     "transfer which re-mapped line endings. It can also be thought of as a "
2623 :     "`magic number' in the sense used by the @command{file} program (although "
2624 :     "@R{} save files are not yet by default known to that program)."
2625 : gnustats 1339 msgstr ""
2626 :    
2627 :     #. type: Plain text
2628 :     #: R-ints.texi:1175
2629 : gnustats 1340 msgid ""
2630 :     "Serialization in @R{} needs to take into account that objects may contain "
2631 :     "references to environments, which then have enclosing environments and so "
2632 :     "on. (Environments recognized as package or name space environments are "
2633 :     "saved by name.) There are `reference objects' which are not duplicated on "
2634 :     "copy and should remain shared on unserialization. These are weak "
2635 :     "references, external pointers and environments other than those associated "
2636 :     "with packages, namespaces and the global environment. These are handled via "
2637 :     "a hash table, and references after the first are written out as a reference "
2638 :     "marker indexed by the table entry."
2639 : gnustats 1339 msgstr ""
2640 :    
2641 :     #. type: Plain text
2642 :     #: R-ints.texi:1185
2643 : gnustats 1340 msgid ""
2644 :     "Version-2 serialization first writes a header indicating the format "
2645 :     "(normally @samp{X\\n} for an XDR format binary save, but @samp{A\\n}, ASCII, "
2646 :     "and @samp{B\\n}, native word-order binary, can also occur) and then three "
2647 :     "integers giving the version of the format and two @R{} versions (packed by "
2648 :     "the @code{R_Version} macro from @file{Rversion.h}). (Unserialization "
2649 :     "interprets the two versions as the version of @R{} which wrote the file "
2650 :     "followed by the minimal version of @R{} needed to read the format.) "
2651 :     "Serialization then writes out the object recursively using function "
2652 :     "@code{WriteItem} in file @file{src/main/serialize.c}."
2653 : gnustats 1339 msgstr ""
2654 :    
2655 :     #. type: Plain text
2656 :     #: R-ints.texi:1190
2657 : gnustats 1340 msgid ""
2658 :     "Some objects are written as if they were @code{SEXPTYPE}s: such pseudo-"
2659 :     "@code{SEXPTYPE}s cover @code{R_NilValue}, @code{R_EmptyEnv}, "
2660 :     "@code{R_BaseEnv}, @code{R_GlobalEnv}, @code{R_UnboundValue}, "
2661 :     "@code{R_MissingArg} and @code{R_BaseNamespace}."
2662 : gnustats 1339 msgstr ""
2663 :    
2664 :     #. type: Plain text
2665 :     #: R-ints.texi:1209
2666 : gnustats 1340 msgid ""
2667 :     "For all @code{SEXPTYPE}s except @code{NILSXP}, @code{SYMSXP} and "
2668 :     "@code{ENVSXP} serialization starts with an integer with the @code{SEXPTYPE} "
2669 :     "in bits 0:7@footnote{only bits 0:4 are currently used for @code{SEXPTYPE}s "
2670 :     "but values 241:255 are used for pseudo-@code{SEXPTYPE}s.} followed by the "
2671 :     "object bit, two bits indicating if there are any attributes and if there is "
2672 :     "a tag (for the pairlist types), an unused bit and then the @code{gp} "
2673 :     "field@footnote{Currently the only relevant bits are 0:1, 4, 14:15.} in bits "
2674 :     "12:27. Pairlist-like objects write their attributes (if any), tag (if any), "
2675 :     "CAR and then CDR (using tail recursion): other objects write their "
2676 :     "attributes after themselves. Atomic vector objects write their length "
2677 :     "followed by the data: generic vector-list objects write their length "
2678 :     "followed by a call to @code{WriteItem} for each element. The code for "
2679 :     "@code{CHARSXP}s special-cases @code{NA_STRING} and writes it as length "
2680 :     "@code{-1} with no data. Lengths no more than @code{2^31 - 1} are written in "
2681 :     "that way and larger lengths (which only occur on 64-bit systems) as "
2682 :     "@code{-1} followed by the upper and lower 32-bits as integers (regarded as "
2683 :     "unsigned)."
2684 : gnustats 1339 msgstr ""
2685 :    
2686 :     #. type: Plain text
2687 :     #: R-ints.texi:1216
2688 : gnustats 1340 msgid ""
2689 :     "Environments are treated in several ways: as we have seen, some are written "
2690 :     "as specific pseudo-@code{SEXPTYPE}s. Package and namespace environments are "
2691 :     "written with pseudo-@code{SEXPTYPE}s followed by the name. `Normal' "
2692 :     "environments are written out as @code{ENVSXP}s with an integer indicating if "
2693 :     "the environment is locked followed by the enclosure, frame, `tag' (the hash "
2694 :     "table) and attributes."
2695 : gnustats 1339 msgstr ""
2696 :    
2697 :     #. type: Plain text
2698 :     #: R-ints.texi:1221
2699 : gnustats 1340 msgid ""
2700 :     "In the `XDR' format integers and doubles are written in bigendian order: "
2701 :     "however the format is not fully XDR (as defined in RFC 1832) as byte "
2702 :     "quantities (such as the contents of @code{CHARSXP} and @code{RAWSXP} types) "
2703 :     "are written as-is and not padded to a multiple of four bytes."
2704 : gnustats 1339 msgstr ""
2705 :    
2706 :     #. type: Plain text
2707 :     #: R-ints.texi:1228
2708 : gnustats 1340 msgid ""
2709 :     "The `ASCII' format writes 7-bit characters. Integers are formatted with "
2710 :     "@code{%d} (except that @code{NA_integer_} is written as @code{NA}), doubles "
2711 :     "formatted with @code{%.16g} (plus @code{NA}, @code{Inf} and @code{-Inf}) and "
2712 :     "bytes with @code{%02x}. Strings are written using standard escapes (e.g.@: "
2713 :     "@code{\\t} and @code{\\013}) for non-printing and non-@acronym{ASCII} bytes."
2714 : gnustats 1339 msgstr ""
2715 :    
2716 :     #. type: Plain text
2717 :     #: R-ints.texi:1233
2718 :     msgid "Character data in @R{} are stored in the sexptype @code{CHARSXP}."
2719 :     msgstr ""
2720 :    
2721 :     #. type: Plain text
2722 :     #: R-ints.texi:1245
2723 : gnustats 1340 msgid ""
2724 :     "There is support for encodings other than that of the current locale, in "
2725 :     "particular UTF-8 and the multi-byte encodings used on Windows for CJK "
2726 :     "languages. A limited means to indicate the encoding of a @code{CHARSXP} is "
2727 :     "@emph{via} two of the `general purpose' bits which are used to declare the "
2728 :     "encoding to be either Latin-1 or UTF-8. (Note that it is possible for a "
2729 :     "character vector to contain elements in different encodings.) Both printing "
2730 :     "and plotting notice the declaration and convert the string to the current "
2731 :     "locale (possibly using @code{<xx>} to display in hexadecimal bytes that are "
2732 :     "not valid in the current locale). Many (but not all) of the character "
2733 :     "manipulation functions will either preserve the declaration or re-encode the "
2734 :     "character string."
2735 : gnustats 1339 msgstr ""
2736 :    
2737 :     #. type: Plain text
2738 :     #: R-ints.texi:1248
2739 : gnustats 1340 msgid ""
2740 :     "Strings that refer to the OS such as file names need to be passed through a "
2741 :     "wide-character interface on some OSes (e.g. Windows)."
2742 : gnustats 1339 msgstr ""
2743 :    
2744 :     #. type: Plain text
2745 :     #: R-ints.texi:1255
2746 : gnustats 1340 msgid ""
2747 :     "When are character strings declared to be of known encoding? One way is to "
2748 :     "do so directly via @code{Encoding}. The parser declares the encoding if "
2749 :     "this is known, either via the @code{encoding} argument to @code{parse} or "
2750 :     "from the locale within which parsing is being done at the @R{} command "
2751 :     "line. (Other ways are recorded on the help page for @code{Encoding}.)"
2752 : gnustats 1339 msgstr ""
2753 :    
2754 :     #. type: Plain text
2755 :     #: R-ints.texi:1260
2756 : gnustats 1340 msgid ""
2757 :     "It is not necessary to declare the encoding of @acronym{ASCII} strings as "
2758 :     "they will work in any locale. @acronym{ASCII} strings should never have a "
2759 :     "marked encoding, as any encoding will be ignored when entering such strings "
2760 :     "into the @code{CHARSXP} cache."
2761 : gnustats 1339 msgstr ""
2762 :    
2763 :     #. type: Plain text
2764 :     #: R-ints.texi:1273
2765 : gnustats 1340 msgid ""
2766 :     "The rationale behind considering only UTF-8 and Latin-1 was that most "
2767 :     "systems are capable of producing UTF-8 strings and this is the nearest we "
2768 :     "have to a universal format. For those that do not (for example those "
2769 :     "lacking a powerful enough @code{iconv}), it is likely that they work in "
2770 :     "Latin-1, the old @R{} assumption. The the parser can return a UTF-8-encoded "
2771 :     "string if it encounters a @samp{\\uxxx} escape for a Unicode point that "
2772 :     "cannot be represented in the current charset. (This needs MBCS support, and "
2773 :     "was only enabled@footnote{See define @code{USE_UTF8_IF_POSSIBLE} in file "
2774 :     "@file{src/main/gram.c}.} on Windows.) This is enabled for all platforms, "
2775 :     "and a @samp{\\uxxx} or @samp{\\Uxxxxxxxx} escape ensures that the parsed "
2776 :     "string will be marked as UTF-8."
2777 : gnustats 1339 msgstr ""
2778 :    
2779 :     #. type: Plain text
2780 :     #: R-ints.texi:1278
2781 : gnustats 1340 msgid ""
2782 :     "Most of the character manipulation functions now preserve UTF-8 encodings: "
2783 :     "there are some notes as to which at the top of file @file{src/main/character."
2784 :     "c} and in file @file{src/library/base/man/Encoding.Rd}."
2785 : gnustats 1339 msgstr ""
2786 :    
2787 :     #. type: Plain text
2788 :     #: R-ints.texi:1289
2789 : gnustats 1340 msgid ""
2790 :     "Graphics devices are offered the possibility of handing UTF-8-encoded "
2791 :     "strings without re-encoding to the native character set, by setting "
2792 :     "@code{hasTextUTF8} to be @samp{TRUE} and supplying functions @code{textUTF8} "
2793 :     "and @code{strWidthUTF8} that expect UTF-8-encoded inputs. Normally the "
2794 :     "symbol font is encoded in Adobe Symbol encoding, but that can be re-encoded "
2795 :     "to UTF-8 by setting @code{wantSymbolUTF8} to @samp{TRUE}. The Windows' port "
2796 :     "of cairographics has a rather peculiar assumption: it wants the symbol font "
2797 :     "to be encoded in UTF-8 as if it were encoded in Latin-1 rather than Adobe "
2798 :     "Symbol: this is selected by @code{wantSymbolUTF8 = NA_LOGICAL}."
2799 : gnustats 1339 msgstr ""
2800 :    
2801 :     #. type: Plain text
2802 :     #: R-ints.texi:1301
2803 : gnustats 1340 msgid ""
2804 :     "Windows has no UTF-8 locales, but rather expects to work with "
2805 :     "UCS-2@footnote{or UTF-16 if support for surrogates is enabled in the OS, "
2806 :     "which it is not normally so at least for Western versions of Windows, "
2807 :     "despite some claims to the contrary on the Microsoft website.} strings. "
2808 :     "@R{} (being written in standard C) would not work internally with UCS-2 "
2809 :     "without extensive changes. The @file{Rgui} console@footnote{but not the "
2810 :     "GraphApp toolkit.} uses UCS-2 internally, but communicates with the @R{} "
2811 :     "engine in the native encoding. To allow UTF-8 strings to be printed in "
2812 :     "UTF-8 in @file{Rgui.exe}, an escape convention is used (see header file "
2813 :     "@file{rgui_UTF8.h}) which is used by @code{cat}, @code{print} and "
2814 :     "autoprinting."
2815 : gnustats 1339 msgstr ""
2816 :    
2817 :     #. type: Plain text
2818 :     #: R-ints.texi:1306
2819 : gnustats 1340 msgid ""
2820 :     "`Unicode' (UCS-2LE) files are common in the Windows world, and "
2821 :     "@code{readLines} and @code{scan} will read them into UTF-8 strings on "
2822 :     "Windows if the encoding is declared explicitly on an unopened connection "
2823 :     "passed to those functions."
2824 : gnustats 1339 msgstr ""
2825 :    
2826 :     #. type: findex
2827 :     #: R-ints.texi:1310
2828 :     #, no-wrap
2829 :     msgid "mkChar"
2830 :     msgstr ""
2831 :    
2832 :     #. type: Plain text
2833 :     #: R-ints.texi:1318
2834 : gnustats 1340 msgid ""
2835 :     "There is a global cache for @code{CHARSXP}s created by @code{mkChar} --- the "
2836 :     "cache ensures that most @code{CHARSXP}s with the same contents share storage "
2837 :     "(`contents' including any declared encoding). Not all @code{CHARSXP}s are "
2838 :     "part of the cache -- notably @samp{NA_STRING} is not. @code{CHARSXP}s "
2839 :     "reloaded from the @code{save} formats of @R{} prior to 0.99.0 are not cached "
2840 :     "(since the code used is frozen and very few examples still exist)."
2841 : gnustats 1339 msgstr ""
2842 :    
2843 :     #. type: findex
2844 :     #: R-ints.texi:1319
2845 :     #, no-wrap
2846 :     msgid "mkCharLenCE"
2847 :     msgstr ""
2848 :    
2849 :     #. type: Plain text
2850 :     #: R-ints.texi:1324
2851 : gnustats 1340 msgid ""
2852 :     "The cache records the encoding of the string as well as the bytes: all "
2853 :     "requests to create a @code{CHARSXP} should be @emph{via} a call to "
2854 :     "@code{mkCharLenCE}. Any encoding given in @code{mkCharLenCE} call will be "
2855 :     "ignored if the string's bytes are all @acronym{ASCII} characters."
2856 : gnustats 1339 msgstr ""
2857 :    
2858 :     #. type: findex
2859 :     #: R-ints.texi:1329
2860 :     #, no-wrap
2861 :     msgid "warning"
2862 :     msgstr ""
2863 :    
2864 :     #. type: findex
2865 :     #: R-ints.texi:1330
2866 :     #, no-wrap
2867 :     msgid "warningcall"
2868 :     msgstr ""
2869 :    
2870 :     #. type: findex
2871 :     #: R-ints.texi:1331
2872 :     #, no-wrap
2873 :     msgid "error"
2874 :     msgstr ""
2875 :    
2876 :     #. type: findex
2877 :     #: R-ints.texi:1332
2878 :     #, no-wrap
2879 :     msgid "errorcall"
2880 :     msgstr ""
2881 :    
2882 :     #. type: Plain text
2883 :     #: R-ints.texi:1342
2884 : gnustats 1340 msgid ""
2885 :     "Each of @code{warning} and @code{stop} have two C-level equivalents, "
2886 :     "@code{warning}, @code{warningcall}, @code{error} and @code{errorcall}. The "
2887 :     "relationship between the pairs is similar: @code{warning} tries to fathom "
2888 :     "out a suitable call, and then calls @code{warningcall} with that call as the "
2889 :     "first argument if it succeeds, and with @code{call = R_NilValue} if it does "
2890 :     "not. When @code{warningcall} is called, it includes the deparsed call in "
2891 :     "its printout unless @code{call = R_NilValue}."
2892 : gnustats 1339 msgstr ""
2893 :    
2894 :     #. type: Plain text
2895 :     #: R-ints.texi:1354
2896 : gnustats 1340 msgid ""
2897 :     "@code{warning} and @code{error} look at the context stack. If the topmost "
2898 :     "context is not of type @code{CTXT_BUILTIN}, it is used to provide the call, "
2899 :     "otherwise the next context provides the call. This means that when these "
2900 :     "functions are called from a primitive or @code{.Internal}, the imputed call "
2901 :     "will not be to primitive/@code{.Internal} but to the function calling the "
2902 :     "primitive/@code{.Internal} . This is exactly what one wants for a @code{."
2903 :     "Internal}, as this will give the call to the closure wrapper. (Further, for "
2904 :     "a @code{.Internal}, the call is the argument to @code{.Internal}, and so may "
2905 :     "not correspond to any @R{} function.) However, it is unlikely to be what is "
2906 :     "needed for a primitive."
2907 : gnustats 1339 msgstr ""
2908 :    
2909 :     #. type: Plain text
2910 :     #: R-ints.texi:1363
2911 : gnustats 1340 msgid ""
2912 :     "The upshot is that that @code{warningcall} and @code{errorcall} should "
2913 :     "normally be used for code called from a primitive, and @code{warning} and "
2914 :     "@code{error} should be used for code called from a @code{.Internal} (and "
2915 :     "necessarily from @code{.Call}, @code{.C} and so on, where the call is not "
2916 :     "passed down). However, there are two complications. One is that code might "
2917 :     "be called from either a primitive or a @code{.Internal}, in which case "
2918 :     "probably @code{warningcall} is more appropriate. The other involves "
2919 :     "replacement functions, where the call was once of the form"
2920 : gnustats 1339 msgstr ""
2921 :    
2922 :     #. type: example
2923 :     #: R-ints.texi:1366
2924 :     #, no-wrap
2925 :     msgid ""
2926 :     "> length(x) <- y ~ x\n"
2927 :     "Error in \"length<-\"(`*tmp*`, value = y ~ x) : invalid value\n"
2928 :     msgstr ""
2929 :    
2930 :     #. type: Plain text
2931 :     #: R-ints.texi:1373
2932 : gnustats 1340 msgid ""
2933 :     "which is unpalatable to the end user. For replacement functions there will "
2934 :     "be a suitable context at the top of the stack, so @code{warning} should be "
2935 :     "used. (The results for @code{.Internal} replacement functions such as "
2936 :     "@code{substr<-} are not ideal.)"
2937 : gnustats 1339 msgstr ""
2938 :    
2939 :     #. type: Plain text
2940 :     #: R-ints.texi:1382
2941 : gnustats 1340 msgid ""
2942 :     "[This section is currently a preliminary draft and should not be taken as "
2943 :     "definitive. The description assumes that @env{R_NO_METHODS_TABLES} has not "
2944 :     "been set.]"
2945 : gnustats 1339 msgstr ""
2946 :    
2947 :     #. type: node
2948 :     #: R-ints.texi:1388
2949 :     #: R-ints.texi:1390
2950 :     #: R-ints.texi:1391
2951 :     #: R-ints.texi:1411
2952 :     #, no-wrap
2953 :     msgid "Representation of S4 objects"
2954 :     msgstr ""
2955 :    
2956 :     #. type: node
2957 :     #: R-ints.texi:1388
2958 :     #: R-ints.texi:1390
2959 :     #: R-ints.texi:1411
2960 :     #: R-ints.texi:1412
2961 :     #: R-ints.texi:1428
2962 :     #, no-wrap
2963 :     msgid "S4 classes"
2964 :     msgstr ""
2965 :    
2966 :     #. type: node
2967 :     #: R-ints.texi:1388
2968 :     #: R-ints.texi:1411
2969 :     #: R-ints.texi:1428
2970 :     #: R-ints.texi:1429
2971 :     #: R-ints.texi:1479
2972 :     #, no-wrap
2973 :     msgid "S4 methods"
2974 :     msgstr ""
2975 :    
2976 :     #. type: subsection
2977 :     #: R-ints.texi:1388
2978 :     #: R-ints.texi:1428
2979 :     #: R-ints.texi:1479
2980 :     #: R-ints.texi:1480
2981 :     #, no-wrap
2982 :     msgid "Mechanics of S4 dispatch"
2983 :     msgstr ""
2984 :    
2985 :     #. type: Plain text
2986 :     #: R-ints.texi:1398
2987 : gnustats 1340 msgid ""
2988 :     "S4 objects can be of any @code{SEXPTYPE}. They are either an object of a "
2989 :     "simple type (such as an atomic vector or function) with S4 class information "
2990 :     "or of type @code{S4SXP}. In all cases, the `S4 bit' (bit 4 of the `general "
2991 :     "purpose' field) is set, and can be tested by the macro/function "
2992 :     "@code{IS_S4_OBJECT}."
2993 : gnustats 1339 msgstr ""
2994 :    
2995 :     #. type: Plain text
2996 :     #: R-ints.texi:1407
2997 : gnustats 1340 msgid ""
2998 :     "S4 objects are created via @code{new()}@footnote{This can also create non-S4 "
2999 :     "objects, as in @code{new(\"integer\")}.} and thence via the C function "
3000 :     "@code{R_do_new_object}. This duplicates the prototype of the class, adds a "
3001 :     "class attribute and sets the S4 bit. All S4 class attributes should be "
3002 :     "character vectors of length one with an attribute giving (as a character "
3003 :     "string) the name of the package (or @code{.GlobalEnv}) containing the class "
3004 :     "definition. Since S4 objects have a class attribute, the @code{OBJECT} bit "
3005 :     "is set."
3006 : gnustats 1339 msgstr ""
3007 :    
3008 :     #. type: Plain text
3009 :     #: R-ints.texi:1410
3010 : gnustats 1340 msgid ""
3011 :     "It is currently unclear what should happen if the class attribute is removed "
3012 :     "from an S4 object, or if this should be allowed."
3013 : gnustats 1339 msgstr ""
3014 :    
3015 :     #. type: Plain text
3016 :     #: R-ints.texi:1417
3017 : gnustats 1340 msgid ""
3018 :     "S4 classes are stored as @R{} objects in the environment in which they are "
3019 :     "created, with names @code{.__C__@var{classname}}: as such they are not "
3020 :     "listed by default by @code{ls}."
3021 : gnustats 1339 msgstr ""
3022 :    
3023 :     #. type: Plain text
3024 :     #: R-ints.texi:1420
3025 : gnustats 1340 msgid ""
3026 :     "The objects are S4 objects of class @code{\"classRepresentation\"} which is "
3027 :     "defined in the @pkg{methods} package."
3028 : gnustats 1339 msgstr ""
3029 :    
3030 :     #. type: Plain text
3031 :     #: R-ints.texi:1427
3032 : gnustats 1340 msgid ""
3033 :     "Since these are just objects, they are subject to the normal scoping rules "
3034 :     "and can be imported and exported from namespaces like other objects. The "
3035 :     "directives @code{importClassesFrom} and @code{exportClasses} are merely "
3036 :     "convenient ways to refer to class objects without needing to know their "
3037 :     "internal `metaname' (although @code{exportClasses} does a little sanity "
3038 :     "checking via @code{isClass})."
3039 : gnustats 1339 msgstr ""
3040 :    
3041 :     #. type: Plain text
3042 :     #: R-ints.texi:1436
3043 : gnustats 1340 msgid ""
3044 :     "Details of methods are stored in S4 objects of class @code{\"MethodsList"
3045 :     "\"}. They have a non-syntactic name of the form @code{.__M__@var{generic}:"
3046 :     "@var{package}} for all methods defined in the current environment for the "
3047 :     "named generic derived from a specific package (which might be @code{."
3048 :     "GlobalEnv})."
3049 : gnustats 1339 msgstr ""
3050 :    
3051 :     #. type: Plain text
3052 :     #: R-ints.texi:1441
3053 : gnustats 1340 msgid ""
3054 :     "There is also environment @code{.__T__@var{generic}:@var{package}} which has "
3055 :     "names the signatures of the methods defined, and values the corresponding "
3056 :     "method functions. This is often referred to as a `methods table'."
3057 : gnustats 1339 msgstr ""
3058 :    
3059 :     #. type: Plain text
3060 :     #: R-ints.texi:1445
3061 : gnustats 1340 msgid ""
3062 :     "When a package without a namespace is attached these objects become visible "
3063 :     "on the search path. @code{library} calls @code{methods:::cacheMetaData} to "
3064 :     "update the internal tables."
3065 : gnustats 1339 msgstr ""
3066 :    
3067 :     #. type: Plain text
3068 :     #: R-ints.texi:1452
3069 : gnustats 1340 msgid ""
3070 :     "During an @R{} session there is an environment associated with each non-"
3071 :     "primitive generic containing objects @code{.AllMTable}, @code{.Generic}, "
3072 :     "@code{.Methods}, @code{.MTable}, @code{.SigArgs} and @code{.SigLength}. "
3073 :     "@code{.MTable} and @code{AllMTable} are merged methods tables containing all "
3074 :     "the methods defined directly and via inheritance respectively. @code{."
3075 :     "Methods} is a merged methods list."
3076 : gnustats 1339 msgstr ""
3077 :    
3078 :     #. type: Plain text
3079 :     #: R-ints.texi:1461
3080 : gnustats 1340 msgid ""
3081 :     "Exporting methods from a namespace is more complicated than exporting a "
3082 :     "class. Note first that you do not export a method, but rather the directive "
3083 :     "@code{exportMethods} will export all the methods defined in the namespace "
3084 :     "for a specified generic: the code also adds to the list of generics any that "
3085 :     "are exported directly. For generics which are listed via "
3086 :     "@code{exportMethods} or exported themselves, the corresponding "
3087 :     "@code{\"MethodsList\"} and environment are exported and so will appear (as "
3088 :     "hidden objects) in the package environment."
3089 : gnustats 1339 msgstr ""
3090 :    
3091 :     #. type: Plain text
3092 :     #: R-ints.texi:1464
3093 : gnustats 1340 msgid ""
3094 :     "Methods for primitives which are internally S4 generic (see below) are "
3095 :     "always exported, whether mentioned in the @file{NAMESPACE} file or not."
3096 : gnustats 1339 msgstr ""
3097 :    
3098 :     #. type: Plain text
3099 :     #: R-ints.texi:1473
3100 : gnustats 1340 msgid ""
3101 :     "Methods can be imported either via the directive @code{importMethodsFrom} or "
3102 :     "via importing a namespace by @code{import}. Also, if a generic is imported "
3103 :     "via @code{importFrom}, its methods are also imported. In all cases the "
3104 :     "generic will be imported if it is in the namespace, so "
3105 :     "@code{importMethodsFrom} is most appropriate for methods defined on generics "
3106 :     "in other packages. Since methods for a generic could be imported from "
3107 :     "several different packages, the methods tables are merged."
3108 : gnustats 1339 msgstr ""
3109 :    
3110 :     #. type: Plain text
3111 :     #: R-ints.texi:1477
3112 : gnustats 1340 msgid ""
3113 :     "When a package with a namespace is attached @code{methods:::cacheMetaData} "
3114 :     "is called to update the internal tables: only the visible methods will be "
3115 :     "cached."
3116 : gnustats 1339 msgstr ""
3117 :    
3118 :     #. type: Plain text
3119 :     #: R-ints.texi:1484
3120 : gnustats 1340 msgid ""
3121 :     "This subsection does not discuss how S4 methods are chosen: see @uref{http://"
3122 :     "@/developer.@/r-project.org/howMethodsWork.pdf}."
3123 : gnustats 1339 msgstr ""
3124 :    
3125 :     #. type: Plain text
3126 :     #: R-ints.texi:1499
3127 : gnustats 1340 msgid ""
3128 :     "For all but primitive functions, setting a method on an existing function "
3129 :     "that is not itself S4 generic creates a new object in the current "
3130 :     "environment which is a call to @code{standardGeneric} with the old "
3131 :     "definition as the default method. Such S4 generics can also be created "
3132 :     "@emph{via} a call to @code{setGeneric}@footnote{although this is not "
3133 :     "recommended as it is less future-proof.} and are standard closures in the "
3134 :     "@R{} language, with environment the environment within which they are "
3135 :     "created. With the advent of namespaces this is somewhat problematic: if "
3136 :     "@code{myfn} was previously in a package with a name space there will be two "
3137 :     "functions called @code{myfn} on the search paths, and which will be called "
3138 :     "depends on which search path is in use. This is starkest for functions in "
3139 :     "the base namespace, where the original will be found ahead of the newly "
3140 :     "created function from any other package with a namespace."
3141 : gnustats 1339 msgstr ""
3142 :    
3143 :     #. type: Plain text
3144 :     #: R-ints.texi:1509
3145 : gnustats 1340 msgid ""
3146 :     "Primitive functions are treated quite differently, for efficiency reasons: "
3147 :     "this results in different semantics. @code{setGeneric} is disallowed for "
3148 :     "primitive functions. The @pkg{methods} namespace contains a list @code{."
3149 :     "BasicFunsList} named by primitive functions: the entries are either "
3150 :     "@code{FALSE} or a standard S4 generic showing the effective definition. "
3151 :     "When @code{setMethod} (or @code{setReplaceMethod}) is called, it either "
3152 :     "fails (if the list entry is @code{FALSE}) or a method is set on the "
3153 :     "effective generic given in the list."
3154 : gnustats 1339 msgstr ""
3155 :    
3156 :     #. type: Plain text
3157 :     #: R-ints.texi:1526
3158 : gnustats 1340 msgid ""
3159 :     "Actual dispatch of S4 methods for almost all primitives piggy-backs on the "
3160 :     "S3 dispatch mechanism, so S4 methods can only be dispatched for primitives "
3161 :     "which are internally S3 generic. When a primitive that is internally S3 "
3162 :     "generic is called with a first argument which is an S4 object and S4 "
3163 :     "dispatch is on (that is, the @pkg{methods} namespace is loaded), "
3164 :     "@code{DispatchOrEval} calls @code{R_possible_dispatch} (defined in file "
3165 :     "@file{src/main/objects.c}). (Members of the S3 group generics, which "
3166 :     "includes all the generic operators, are treated slightly differently: the "
3167 :     "first two arguments are checked and @code{DispatchGroup} is called.) "
3168 :     "@code{R_possible_dispatch} first checks an internal table to see if any S4 "
3169 :     "methods are set for that generic (and S4 dispatch is currently enabled for "
3170 :     "that generic), and if so proceeds to S4 dispatch using methods stored in "
3171 :     "another internal table. All primitives are in the base namespace, and this "
3172 :     "mechanism means that S4 methods can be set for (some) primitives and will "
3173 :     "always be used, in contrast to setting methods on non-primitives."
3174 : gnustats 1339 msgstr ""
3175 :    
3176 :     #. type: Plain text
3177 :     #: R-ints.texi:1529
3178 : gnustats 1340 msgid ""
3179 :     "The exception is @code{%*%}, which is S4 generic but not S3 generic as its C "
3180 :     "code contains a direct call to @code{R_possible_dispatch}."
3181 : gnustats 1339 msgstr ""
3182 :    
3183 :     #. type: Plain text
3184 :     #: R-ints.texi:1535
3185 : gnustats 1340 msgid ""
3186 :     "The primitive @code{as.double} is special, as @code{as.numeric} and @code{as."
3187 :     "real} are copies of it. The @pkg{methods} package code partly refers to "
3188 :     "generics by name and partly by function, and maps @code{as.double} and "
3189 :     "@code{as.real} to @code{as.numeric} (since that is the name used by packages "
3190 :     "exporting methods for it)."
3191 : gnustats 1339 msgstr ""
3192 :    
3193 :     #. type: Plain text
3194 :     #: R-ints.texi:1539
3195 : gnustats 1340 msgid ""
3196 :     "Some elements of the language are implemented as primitives, for example "
3197 :     "@code{@}}. This includes the subset and subassignment `functions' and they "
3198 :     "are S4 generic, again piggybacking on S3 dispatch."
3199 : gnustats 1339 msgstr ""
3200 :    
3201 :     #. type: Plain text
3202 :     #: R-ints.texi:1546
3203 : gnustats 1340 msgid ""
3204 :     "@code{.BasicFunsList} is generated when @pkg{methods} is installed, by "
3205 :     "computing all primitives, initially disallowing methods on all and then "
3206 :     "setting generics for members of @code{.GenericArgsEnv}, the S4 group "
3207 :     "generics and a short exceptions list in file @file{BasicFunsList.R}: this "
3208 :     "currently contains the subsetting and subassignment operators and an "
3209 :     "override for @code{c}."
3210 : gnustats 1339 msgstr ""
3211 :    
3212 :     #. type: Plain text
3213 :     #: R-ints.texi:1567
3214 : gnustats 1340 msgid ""
3215 :     "@R{}'s memory allocation is almost all done via routines in file @file{src/"
3216 :     "main/memory.c}. It is important to keep track of where memory is allocated, "
3217 :     "as the Windows port (by default) makes use of a memory allocator that "
3218 :     "differs from @code{malloc} etc as provided by MinGW. Specifically, there "
3219 :     "are entry points @code{Rm_malloc}, @code{Rm_free}, @code{Rm_calloc} and "
3220 :     "@code{Rm_free} provided by file @file{src/gnuwin32/malloc.c}. This was done "
3221 :     "for two reasons. The primary motivation was performance: the allocator "
3222 :     "provided by MSVCRT @emph{via} MinGW was far too slow at handling the many "
3223 :     "small allocations that the allocation system for @code{SEXPREC}s uses. As a "
3224 :     "side benefit, we can set a limit on the amount of allocated memory: this is "
3225 :     "useful as whereas Windows does provide virtual memory it is relatively far "
3226 :     "slower than many other @R{} platforms and so limiting @R{}'s use of swapping "
3227 :     "is highly advantageous. The high-performance allocator is only called from "
3228 :     "@file{src/main/memory.c}, @file{src/main/regex.c}, @file{src/extra/pcre} and "
3229 :     "@file{src/extra/xdr}: note that this means that it is not used in packages."
3230 : gnustats 1339 msgstr ""
3231 :    
3232 :     #. type: Plain text
3233 :     #: R-ints.texi:1571
3234 : gnustats 1340 msgid ""
3235 :     "The rest of @R{} should where possible make use of the allocators made "
3236 :     "available by file @file{src/main/memory.c}, which are also the methods "
3237 :     "recommended in"
3238 : gnustats 1339 msgstr ""
3239 :    
3240 :     #. type: ref{#1}
3241 :     #: R-ints.texi:1573
3242 :     msgid "Memory allocation, , Memory allocation, R-exts, Writing R Extensions"
3243 :     msgstr ""
3244 :    
3245 :     #. type: ifclear
3246 :     #: R-ints.texi:1576
3247 :     msgid "`Writing R Extensions'"
3248 :     msgstr ""
3249 :    
3250 :     #. type: findex
3251 :     #: R-ints.texi:1577
3252 :     #, no-wrap
3253 :     msgid "R_alloc"
3254 :     msgstr ""
3255 :    
3256 :     #. type: findex
3257 :     #: R-ints.texi:1578
3258 :     #, no-wrap
3259 :     msgid "Calloc"
3260 :     msgstr ""
3261 :    
3262 :     #. type: findex
3263 :     #: R-ints.texi:1579
3264 :     #, no-wrap
3265 :     msgid "Realloc"
3266 :     msgstr ""
3267 :    
3268 :     #. type: findex
3269 :     #: R-ints.texi:1580
3270 :     #, no-wrap
3271 :     msgid "Free"
3272 :     msgstr ""
3273 :    
3274 :     #. type: Plain text
3275 :     #: R-ints.texi:1585
3276 : gnustats 1340 msgid ""
3277 :     "for use in @R{} packages, namely the use of @code{R_alloc}, @code{Calloc}, "
3278 :     "@code{Realloc} and @code{Free}. Memory allocated by @code{R_alloc} is freed "
3279 :     "by the garbage collector once the `watermark' has been reset by calling"
3280 : gnustats 1339 msgstr ""
3281 :    
3282 :     #. type: findex
3283 :     #: R-ints.texi:1585
3284 :     #, no-wrap
3285 :     msgid "vmaxset"
3286 :     msgstr ""
3287 :    
3288 :     #. type: Plain text
3289 :     #: R-ints.texi:1589
3290 : gnustats 1340 msgid ""
3291 :     "@code{vmaxset}. This is done automatically by the wrapper code calling "
3292 :     "primitives and @code{.Internal} functions (and also by the wrapper code to "
3293 :     "@code{.Call} and @code{.External}), but"
3294 : gnustats 1339 msgstr ""
3295 :    
3296 :     #. type: findex
3297 :     #: R-ints.texi:1589
3298 :     #, no-wrap
3299 :     msgid "vmaxget"
3300 :     msgstr ""
3301 :    
3302 :     #. type: Plain text
3303 :     #: R-ints.texi:1593
3304 : gnustats 1340 msgid ""
3305 :     "@code{vmaxget} and @code{vmaxset} can be used to reset the watermark from "
3306 :     "within internal code if the memory is only required for a short time."
3307 : gnustats 1339 msgstr ""
3308 :    
3309 :     #. type: findex
3310 :     #: R-ints.texi:1594
3311 :     #, no-wrap
3312 :     msgid "alloca"
3313 :     msgstr ""
3314 :    
3315 :     #. type: Plain text
3316 :     #: R-ints.texi:1599
3317 : gnustats 1340 msgid ""
3318 :     "All of the methods of memory allocation mentioned so far are relatively "
3319 :     "expensive. All @R{} platforms support @code{alloca}, and in almost all "
3320 :     "cases@footnote{but apparently not on Windows.} this is managed by the "
3321 :     "compiler, allocates memory on the C stack and is very efficient."
3322 : gnustats 1339 msgstr ""
3323 :    
3324 :     #. type: Plain text
3325 :     #: R-ints.texi:1606
3326 : gnustats 1340 msgid ""
3327 :     "There are two disadvantages in using @code{alloca}. First, it is fragile "
3328 :     "and care is needed to avoid writing (or even reading) outside the bounds of "
3329 :     "the allocation block returned. Second, it increases the danger of "
3330 :     "overflowing the C stack. It is suggested that it is only used for smallish "
3331 :     "allocations (up to tens of thousands of bytes), and that"
3332 : gnustats 1339 msgstr ""
3333 :    
3334 :     #. type: findex
3335 :     #: R-ints.texi:1607
3336 :     #, no-wrap
3337 :     msgid "R_CheckStack"
3338 :     msgstr ""
3339 :    
3340 :     #. type: example
3341 :     #: R-ints.texi:1610
3342 :     #, no-wrap
3343 :     msgid " R_CheckStack();\n"
3344 :     msgstr ""
3345 :    
3346 :     #. type: Plain text
3347 :     #: R-ints.texi:1617
3348 : gnustats 1340 msgid ""
3349 :     "is called immediately after the allocation (as @R{}'s stack checking "
3350 :     "mechanism will warn far enough from the stack limit to allow for modest use "
3351 :     "of alloca). (@code{do_makeunique} in file @file{src/main/unique.c} provides "
3352 :     "an example of both points.)"
3353 : gnustats 1339 msgstr ""
3354 :    
3355 :     #. type: Plain text
3356 :     #: R-ints.texi:1619
3357 :     msgid "There is an alternative check,"
3358 :     msgstr ""
3359 :    
3360 :     #. type: findex
3361 :     #: R-ints.texi:1619
3362 :     #, no-wrap
3363 :     msgid "R_CheckStack2"
3364 :     msgstr ""
3365 :    
3366 :     #. type: example
3367 :     #: R-ints.texi:1622
3368 :     #, no-wrap
3369 :     msgid " R_CheckStack2(size_t extra);\n"
3370 :     msgstr ""
3371 :    
3372 :     #. type: Plain text
3373 :     #: R-ints.texi:1627
3374 : gnustats 1340 msgid ""
3375 :     "to be called immediately @emph{before} trying an allocation of @code{extra} "
3376 :     "bytes."
3377 : gnustats 1339 msgstr ""
3378 :    
3379 :     #. type: Plain text
3380 :     #: R-ints.texi:1633
3381 : gnustats 1340 msgid ""
3382 :     "An alternative strategy has been used for various functions which require "
3383 :     "intermediate blocks of storage of varying but usually small size, and this "
3384 :     "has been consolidated into the routines in the header file @file{src/main/"
3385 :     "RBufferUtils.h}. This uses a structure which contains a buffer, the current "
3386 :     "size and the default size. A call to"
3387 : gnustats 1339 msgstr ""
3388 :    
3389 :     #. type: findex
3390 :     #: R-ints.texi:1633
3391 :     #, no-wrap
3392 :     msgid "R_AllocStringBuffer"
3393 :     msgstr ""
3394 :    
3395 :     #. type: example
3396 :     #: R-ints.texi:1636
3397 :     #, no-wrap
3398 :     msgid " R_AllocStringBuffer(size_t blen, R_StringBuffer *buf);\n"
3399 :     msgstr ""
3400 :    
3401 :     #. type: Plain text
3402 :     #: R-ints.texi:1642
3403 : gnustats 1340 msgid ""
3404 :     "sets @code{buf->data} to a memory area of at least @code{blen+1} bytes. At "
3405 :     "least the default size is used, which means that for small allocations the "
3406 :     "same buffer can be reused. A call to"
3407 : gnustats 1339 msgstr ""
3408 :    
3409 :     #. type: findex
3410 :     #: R-ints.texi:1642
3411 :     #, no-wrap
3412 :     msgid "R_FreeStringBufferL"
3413 :     msgstr ""
3414 :    
3415 :     #. type: findex
3416 :     #: R-ints.texi:1643
3417 :     #, no-wrap
3418 :     msgid "R_FreeStringBuffer"
3419 :     msgstr ""
3420 :    
3421 :     #. type: Plain text
3422 :     #: R-ints.texi:1647
3423 : gnustats 1340 msgid ""
3424 :     "@code{R_FreeStringBufferL} releases memory if more than the default has been "
3425 :     "allocated whereas a call to @code{R_FreeStringBuffer} frees any memory "
3426 :     "allocated."
3427 : gnustats 1339 msgstr ""
3428 :    
3429 :     #. type: Plain text
3430 :     #: R-ints.texi:1649
3431 : gnustats 1340 msgid ""
3432 :     "The @code{R_StringBuffer} structure needs to be initialized, for example by"
3433 : gnustats 1339 msgstr ""
3434 :    
3435 :     #. type: example
3436 :     #: R-ints.texi:1652
3437 :     #, no-wrap
3438 :     msgid "static R_StringBuffer ex_buff = @{NULL, 0, MAXELTSIZE@};\n"
3439 :     msgstr ""
3440 :    
3441 :     #. type: Plain text
3442 :     #: R-ints.texi:1660
3443 : gnustats 1340 msgid ""
3444 :     "which uses a default size of @code{MAXELTSIZE = 8192} bytes. Most current "
3445 :     "uses have a static @code{R_StringBuffer} structure, which allows the "
3446 :     "(default-sized) buffer to be shared between calls to e.g.@: @code{grep} and "
3447 :     "even between functions: this will need to be changed if @R{} ever allows "
3448 :     "concurrent evaluation threads. So the idiom is"
3449 : gnustats 1339 msgstr ""
3450 :    
3451 :     #. type: example
3452 :     #: R-ints.texi:1673
3453 :     #, no-wrap
3454 :     msgid ""
3455 :     "static R_StringBuffer ex_buff = @{NULL, 0, MAXELTSIZE@};\n"
3456 :     "...\n"
3457 :     " char *buf;\n"
3458 :     " for(i = 0; i < n; i++) @{\n"
3459 :     " compute len\n"
3460 :     " buf = R_AllocStringBuffer(len, &ex_buff);\n"
3461 :     " use buf\n"
3462 :     " @}\n"
3463 :     " /* free allocation if larger than the default, but leave\n"
3464 :     " default allocated for future use */\n"
3465 :     " R_FreeStringBufferL(&ex_buff);\n"
3466 :     msgstr ""
3467 :    
3468 :     #. type: subsection
3469 :     #: R-ints.texi:1678
3470 :     #: R-ints.texi:1680
3471 :     #: R-ints.texi:1681
3472 :     #, no-wrap
3473 :     msgid "Internals of R_alloc"
3474 :     msgstr ""
3475 :    
3476 :     #. type: Plain text
3477 :     #: R-ints.texi:1689
3478 : gnustats 1340 msgid ""
3479 :     "The memory used by @code{R_alloc} is allocated as @R{} vectors, of type "
3480 :     "@code{RAWSXP}. Thus the allocation is in units of 8 bytes, and is rounded "
3481 :     "up. A request for zero bytes currently returns @code{NULL} (but this should "
3482 :     "not be relied on). For historical reasons, in all other cases 1 byte is "
3483 :     "added before rounding up so the allocation is always 1--8 bytes more than "
3484 :     "was asked for: again this should not be relied on."
3485 : gnustats 1339 msgstr ""
3486 :    
3487 :     #. type: Plain text
3488 :     #: R-ints.texi:1700
3489 : gnustats 1340 msgid ""
3490 :     "The vectors allocated are protected via the setting of @code{R_VStack}, as "
3491 :     "the garbage collector marks everything that can be reached from that "
3492 :     "location. When a vector is @code{R_alloc}ated, its @code{ATTRIB} pointer is "
3493 :     "set to the current @code{R_VStack}, and @code{R_VStack} is set to the latest "
3494 :     "allocation. Thus @code{R_VStack} is a single-linked chain of the vectors "
3495 :     "currently allocated via @code{R_alloc}. Function @code{vmaxset} resets the "
3496 :     "location @code{R_VStack}, and should be to a value that has previously be "
3497 :     "obtained @emph{via} @code{vmaxget}: allocations after the value was obtained "
3498 :     "will no longer be protected and hence available for garbage collection."
3499 : gnustats 1339 msgstr ""
3500 :    
3501 :     #. type: Plain text
3502 :     #: R-ints.texi:1706
3503 : gnustats 1340 msgid ""
3504 :     "This section notes known use by the system of these environments: the "
3505 :     "intention is to minimize or eliminate such uses."
3506 : gnustats 1339 msgstr ""
3507 :    
3508 :     #. type: node
3509 :     #: R-ints.texi:1710
3510 :     #: R-ints.texi:1712
3511 :     #: R-ints.texi:1713
3512 :     #: R-ints.texi:1739
3513 :     #, no-wrap
3514 :     msgid "Base environment"
3515 :     msgstr ""
3516 :    
3517 :     #. type: subsection
3518 :     #: R-ints.texi:1710
3519 :     #: R-ints.texi:1712
3520 :     #: R-ints.texi:1739
3521 :     #: R-ints.texi:1740
3522 :     #, no-wrap
3523 :     msgid "Global environment"
3524 :     msgstr ""
3525 :    
3526 :     #. type: findex
3527 :     #: R-ints.texi:1717
3528 :     #, no-wrap
3529 :     msgid ".Device"
3530 :     msgstr ""
3531 :    
3532 :     #. type: findex
3533 :     #: R-ints.texi:1718
3534 :     #, no-wrap
3535 :     msgid ".Devices"
3536 :     msgstr ""
3537 :    
3538 :     #. type: Plain text
3539 :     #: R-ints.texi:1724
3540 : gnustats 1340 msgid ""
3541 :     "The graphics devices system maintains two variables @code{.Device} and "
3542 :     "@code{.Devices} in the base environment: both are always set. The variable "
3543 :     "@code{.Devices} gives a list of character vectors of the names of open "
3544 :     "devices, and @code{.Device} is the element corresponding to the currently "
3545 :     "active device. The null device will always be open."
3546 : gnustats 1339 msgstr ""
3547 :    
3548 :     #. type: findex
3549 :     #: R-ints.texi:1725
3550 :     #, no-wrap
3551 :     msgid ".Options"
3552 :     msgstr ""
3553 :    
3554 :     #. type: Plain text
3555 :     #: R-ints.texi:1729
3556 : gnustats 1340 msgid ""
3557 :     "There appears to be a variable @code{.Options}, a pairlist giving the "
3558 :     "current options settings. But in fact this is just a symbol with a value "
3559 :     "assigned, and so shows up as a base variable."
3560 : gnustats 1339 msgstr ""
3561 :    
3562 :     #. type: findex
3563 :     #: R-ints.texi:1730
3564 :     #, no-wrap
3565 :     msgid ".Last.value"
3566 :     msgstr ""
3567 :    
3568 :     #. type: Plain text
3569 :     #: R-ints.texi:1733
3570 : gnustats 1340 msgid ""
3571 :     "Similarly, the evaluator creates a symbol @code{.Last.value} which appears "
3572 :     "as a variable in the base environment."
3573 : gnustats 1339 msgstr ""
3574 :    
3575 :     #. type: findex
3576 :     #: R-ints.texi:1734
3577 :     #, no-wrap
3578 :     msgid ".Traceback"
3579 :     msgstr ""
3580 :    
3581 :     #. type: findex
3582 :     #: R-ints.texi:1735
3583 :     #, no-wrap
3584 :     msgid "last.warning"
3585 :     msgstr ""
3586 :    
3587 :     #. type: Plain text
3588 :     #: R-ints.texi:1738
3589 : gnustats 1340 msgid ""
3590 :     "Errors can give rise to objects @code{.Traceback} and @code{last.warning} in "
3591 :     "the base environment."
3592 : gnustats 1339 msgstr ""
3593 :    
3594 :     #. type: cindex
3595 :     #: R-ints.texi:1742
3596 :     #, no-wrap
3597 :     msgid "global environment"
3598 :     msgstr ""
3599 :    
3600 :     #. type: cindex
3601 :     #: R-ints.texi:1743
3602 :     #, no-wrap
3603 :     msgid "environment, global"
3604 :     msgstr ""
3605 :    
3606 :     #. type: findex
3607 :     #: R-ints.texi:1744
3608 :     #, no-wrap
3609 :     msgid ".Random.seed"
3610 :     msgstr ""
3611 :    
3612 :     #. type: Plain text
3613 :     #: R-ints.texi:1747
3614 : gnustats 1340 msgid ""
3615 :     "The seed for the random number generator is stored in object @code{.Random."
3616 :     "seed} in the global environment."
3617 : gnustats 1339 msgstr ""
3618 :    
3619 :     #. type: findex
3620 :     #: R-ints.texi:1748
3621 :     #, no-wrap
3622 :     msgid "dump.frames"
3623 :     msgstr ""
3624 :    
3625 :     #. type: Plain text
3626 :     #: R-ints.texi:1751
3627 : gnustats 1340 msgid ""
3628 :     "Some error handlers may give rise to objects in the global environment: for "
3629 :     "example @code{dump.frames} by default produces @code{last.dump}."
3630 : gnustats 1339 msgstr ""
3631 :    
3632 :     #. type: findex
3633 :     #: R-ints.texi:1752
3634 :     #, no-wrap
3635 :     msgid ".SavedPlots"
3636 :     msgstr ""
3637 :    
3638 :     #. type: Plain text
3639 :     #: R-ints.texi:1756
3640 : gnustats 1340 msgid ""
3641 :     "The @code{windows()} device makes use of a variable @code{.SavedPlots} to "
3642 :     "store display lists of saved plots for later display. This is regarded as a "
3643 :     "variable created by the user."
3644 : gnustats 1339 msgstr ""
3645 :    
3646 :     #. type: cindex
3647 :     #: R-ints.texi:1761
3648 :     #, no-wrap
3649 :     msgid "modules"
3650 :     msgstr ""
3651 :    
3652 :     #. type: Plain text
3653 :     #: R-ints.texi:1766
3654 : gnustats 1340 msgid ""
3655 :     "@R{} makes use of a number of shared objects/DLLs stored in the "
3656 :     "@file{modules} directory. These are parts of the code which have been "
3657 :     "chosen to be loaded `on demand' rather than linked as dynamic libraries or "
3658 :     "incorporated into the main executable/dynamic library."
3659 : gnustats 1339 msgstr ""
3660 :    
3661 :     #. type: Plain text
3662 :     #: R-ints.texi:1770
3663 : gnustats 1340 msgid ""
3664 :     "For the remaining modules the motivation has been the amount of (often "
3665 :     "optional) code they will bring in via libraries to which they are linked."
3666 : gnustats 1339 msgstr ""
3667 :    
3668 :     #. type: code{#1}
3669 :     #: R-ints.texi:1773
3670 :     #, no-wrap
3671 :     msgid "internet"
3672 :     msgstr ""
3673 :    
3674 :     #. type: table
3675 :     #: R-ints.texi:1776
3676 : gnustats 1340 msgid ""
3677 :     "The internal HTTP and FTP clients and socket support, which link to system-"
3678 :     "specific support libraries."
3679 : gnustats 1339 msgstr ""
3680 :    
3681 :     #. type: code{#1}
3682 :     #: R-ints.texi:1777
3683 :     #, no-wrap
3684 :     msgid "lapack"
3685 :     msgstr ""
3686 :    
3687 :     #. type: table
3688 :     #: R-ints.texi:1780
3689 : gnustats 1340 msgid ""
3690 :     "The code which makes use of the LAPACK library, and is linked to "
3691 :     "@file{libRlapack} or an external LAPACK library."
3692 : gnustats 1339 msgstr ""
3693 :    
3694 :     #. type: code{#1}
3695 :     #: R-ints.texi:1781
3696 :     #, no-wrap
3697 :     msgid "vfonts"
3698 :     msgstr ""
3699 :    
3700 :     #. type: table
3701 :     #: R-ints.texi:1783
3702 :     msgid "The Hershey font databases and the code to draw with them."
3703 :     msgstr ""
3704 :    
3705 :     #. type: code{#1}
3706 :     #: R-ints.texi:1784
3707 :     #, no-wrap
3708 :     msgid "X11"
3709 :     msgstr ""
3710 :    
3711 :     #. type: table
3712 :     #: R-ints.texi:1789
3713 : gnustats 1340 msgid ""
3714 :     "(Unix-alikes only.) The @code{X11()}, @code{jpeg()}, @code{png()} and "
3715 :     "@code{tiff()} devices. These are optional, and links to some or all of the "
3716 :     "@code{X11}, @code{pango}, @code{cairo}, @code{jpeg}, @code{libpng} and "
3717 :     "@code{libtiff} libraries."
3718 : gnustats 1339 msgstr ""
3719 :    
3720 :     #. type: file{#1}
3721 :     #: R-ints.texi:1790
3722 :     #, no-wrap
3723 :     msgid "internet2.dll"
3724 :     msgstr ""
3725 :    
3726 :     #. type: table
3727 :     #: R-ints.texi:1794
3728 : gnustats 1340 msgid ""
3729 :     "(Windows only.) An alternative version of the internet access routines, "
3730 :     "compiled against Internet Explorer internals (and so loads @file{wininet."
3731 :     "dll} and @file{wsock32.dll})."
3732 : gnustats 1339 msgstr ""
3733 :    
3734 :     #. type: cindex
3735 :     #: R-ints.texi:1798
3736 :     #, no-wrap
3737 :     msgid "visibility"
3738 :     msgstr ""
3739 :    
3740 :     #. type: node
3741 :     #: R-ints.texi:1803
3742 :     #: R-ints.texi:1805
3743 :     #: R-ints.texi:1806
3744 :     #: R-ints.texi:1856
3745 :     #, no-wrap
3746 :     msgid "Hiding C entry points"
3747 :     msgstr ""
3748 :    
3749 :     #. type: subsection
3750 :     #: R-ints.texi:1803
3751 :     #: R-ints.texi:1805
3752 :     #: R-ints.texi:1856
3753 :     #: R-ints.texi:1857
3754 :     #, no-wrap
3755 :     msgid "Variables in Windows DLLs"
3756 :     msgstr ""
3757 :    
3758 :     #. type: Plain text
3759 :     #: R-ints.texi:1809
3760 :     msgid "We make use of the visibility mechanisms discussed in"
3761 :     msgstr ""
3762 :    
3763 :     #. type: ifset
3764 :     #: R-ints.texi:1811
3765 : gnustats 1340 msgid ""
3766 :     "@ref{Controlling visibility, , Controlling visibility, R-exts, Writing R "
3767 :     "Extensions},"
3768 : gnustats 1339 msgstr ""
3769 :    
3770 :     #. type: ifclear
3771 :     #: R-ints.texi:1814
3772 :     msgid "section `Controlling Visibility' in `Writing R Extensions',"
3773 :     msgstr ""
3774 :    
3775 :     #. type: Plain text
3776 :     #: R-ints.texi:1818
3777 : gnustats 1340 msgid ""
3778 :     "C entry points not needed outside the main @R{} executable/dynamic library "
3779 :     "(and in particular in no package nor module) should be prefixed by "
3780 :     "@code{attribute_hidden}."
3781 : gnustats 1339 msgstr ""
3782 :    
3783 :     #. type: findex
3784 :     #: R-ints.texi:1818
3785 :     #, no-wrap
3786 :     msgid "attribute_hidden"
3787 :     msgstr ""
3788 :    
3789 :     #. type: Plain text
3790 :     #: R-ints.texi:1826
3791 : gnustats 1340 msgid ""
3792 :     "Minimizing the visibility of symbols in the @R{} dynamic library will speed "
3793 :     "up linking to it (which packages will do) and reduce the possibility of "
3794 :     "linking to the wrong entry points of the same name. In addition, on some "
3795 :     "platforms reducing the number of entry points allows more efficient versions "
3796 :     "of PIC to be used: somewhat over half the entry points are hidden. A "
3797 :     "convenient way to hide variables (as distinct from functions) is to declare "
3798 :     "them @code{extern0} in header file @file{Defn.h}."
3799 : gnustats 1339 msgstr ""
3800 :    
3801 :     #. type: Plain text
3802 :     #: R-ints.texi:1832
3803 : gnustats 1340 msgid ""
3804 :     "The visibility mechanism used is only available with some compilers and "
3805 :     "platforms, and in particular not on Windows, where an alternative mechanism "
3806 :     "is used. Entry points will not be made available in @file{R.dll} if they "
3807 :     "are listed in the file @file{src/gnuwin32/Rdll.hide}."
3808 : gnustats 1339 msgstr ""
3809 :    
3810 :     #. type: findex
3811 :     #: R-ints.texi:1832
3812 :     #, no-wrap
3813 :     msgid "Rdll.hide"
3814 :     msgstr ""
3815 :    
3816 :     #. type: Plain text
3817 :     #: R-ints.texi:1841
3818 : gnustats 1340 msgid ""
3819 :     "Entries in that file start with a space and must be strictly in alphabetic "
3820 :     "order in the C locale (use @command{sort} on the file to ensure this if you "
3821 :     "change it). It is possible to hide Fortran as well as C entry points via "
3822 :     "this file: the former are lower-cased and have an underline as suffix, and "
3823 :     "the suffixed name should be included in the file. Some entry points exist "
3824 :     "only on Windows or need to be visible only on Windows, and some notes on "
3825 :     "these are provided in file @file{src/gnuwin32/Maintainters.notes}."
3826 : gnustats 1339 msgstr ""
3827 :    
3828 :     #. type: Plain text
3829 :     #: R-ints.texi:1851
3830 : gnustats 1340 msgid ""
3831 :     "Because of the advantages of reducing the number of visible entry points, "
3832 :     "they should be declared @code{attribute_hidden} where possible. Note that "
3833 :     "this only has an effect on a shared-R-library build, and so care is needed "
3834 :     "not to hide entry points that are legitimately used by packages. So it is "
3835 :     "best if the decision on visibility is made when a new entry point is "
3836 :     "created, including the decision if it should be included in header file "
3837 :     "@file{Rinternals.h}. A list of the visible entry points on shared-R-library "
3838 :     "build on a reasonably standard Unix-alike can be made by something like"
3839 : gnustats 1339 msgstr ""
3840 :    
3841 :     #. type: example
3842 :     #: R-ints.texi:1854
3843 :     #, no-wrap
3844 :     msgid "nm -g libR.so | grep ' [BCDT] ' | cut -b20-\n"
3845 :     msgstr ""
3846 :    
3847 :     #. type: Plain text
3848 :     #: R-ints.texi:1866
3849 : gnustats 1340 msgid ""
3850 :     "Windows is unique in that it conventionally treats importing variables "
3851 :     "differently from functions: variables that are imported from a DLL need to "
3852 :     "be specified by a prefix (often @samp{_imp_}) when being linked to "
3853 :     "(`imported') but not when being linked from (`exported'). The details "
3854 :     "depend on the compiler system, and have changed for MinGW during the "
3855 :     "lifetime of that port. They are in the main hidden behind some macros "
3856 :     "defined in header file @file{R_ext/libextern.h}."
3857 : gnustats 1339 msgstr ""
3858 :    
3859 :     #. type: Plain text
3860 :     #: R-ints.texi:1872
3861 : gnustats 1340 msgid ""
3862 :     "A (non-function) variable in the main @R{} sources that needs to be referred "
3863 :     "to outside @file{R.dll} (in a package, module or another DLL such as "
3864 :     "@file{Rgraphapp.dll}) should be declared with prefix @code{LibExtern}. The "
3865 :     "main use is in @file{Rinternals.h}, but it needs to be considered for any "
3866 :     "public header and also @file{Defn.h}."
3867 : gnustats 1339 msgstr ""
3868 :    
3869 :     #. type: Plain text
3870 :     #: R-ints.texi:1879
3871 : gnustats 1340 msgid ""
3872 :     "It would nowadays be possible to make use of the `auto-import' feature of "
3873 :     "the MinGW port of @command{ld} to fix up imports from DLLs (and if @R{} is "
3874 :     "built for the Cygwin platform this is what happens). However, this was not "
3875 :     "possible when the MinGW build of @R{} was first constructed in ca 1998, "
3876 :     "allows less control of visibility and would not work for other Windows "
3877 :     "compiler suites."
3878 : gnustats 1339 msgstr ""
3879 :    
3880 :     #. type: Plain text
3881 :     #: R-ints.texi:1882
3882 : gnustats 1340 msgid ""
3883 :     "It is only possible to check if this has been handled correctly by compiling "
3884 :     "the @R{} sources on Windows."
3885 : gnustats 1339 msgstr ""
3886 :    
3887 :     #. type: Plain text
3888 :     #: R-ints.texi:1891
3889 : gnustats 1340 msgid ""
3890 :     "Lazy loading is always used for code in packages but is optional (selected "
3891 :     "by the package maintainer) for datasets in packages. When a package/"
3892 :     "namespace which uses it is loaded, the package/namespace environment is "
3893 :     "populated with promises for all the named objects: when these promises are "
3894 :     "evaluated they load the actual code from a database."
3895 : gnustats 1339 msgstr ""
3896 :    
3897 :     #. type: Plain text
3898 :     #: R-ints.texi:1902
3899 : gnustats 1340 msgid ""
3900 :     "There are separate databases for code and data, stored in the @file{R} and "
3901 :     "@file{data} subdirectories. The database consists of two files, "
3902 :     "@file{@var{name}.rdb} and @file{@var{name}.rdx}. The @file{.rdb} file is a "
3903 :     "concatenation of serialized objects, and the @file{.rdx} file contains an "
3904 :     "index. The objects are stored in (usually) a @command{gzip}-compressed "
3905 :     "format with a 4-byte header giving the uncompressed serialized length (in "
3906 :     "XDR, that is big-endian, byte order) and read by a call to the primitive "
3907 :     "@code{lazyLoadDBfetch}. (Note that this makes lazy-loading unsuitable for "
3908 :     "really large objects: the unserialized length of an @R{} object can exceed "
3909 :     "4GB.)"
3910 : gnustats 1339 msgstr ""
3911 :    
3912 :     #. type: Plain text
3913 :     #: R-ints.texi:1917
3914 : gnustats 1340 msgid ""
3915 :     "The index or `map' file @file{@var{name}.rdx} is a compressed serialized "
3916 :     "@R{} object to be read by @code{readRDS}. It is a list with three elements "
3917 :     "@code{variables}, @code{references} and @code{compressed}. The first two "
3918 :     "are named lists of integer vectors of length 2 giving the offset and length "
3919 :     "of the serialized object in the @file{@var{name}.rdb} file. Element "
3920 :     "@code{variables} has an entry for each named object: @code{references} "
3921 :     "serializes a temporary environment used when named environments are added to "
3922 :     "the database. @code{compressed} is a logical indicating if the serialized "
3923 :     "objects were compressed: compression is always used nowadays. We later added "
3924 :     "the values @code{compressed = 2} and @code{3} for @command{bzip2} and "
3925 :     "@command{xz} compression (with the possibility of future expansion to other "
3926 :     "methods): these formats add a fifth byte to the header for the type of "
3927 :     "compression, and store serialized objects uncompressed if compression "
3928 :     "expands them."
3929 : gnustats 1339 msgstr ""
3930 :    
3931 :     #. type: Plain text
3932 :     #: R-ints.texi:1922
3933 : gnustats 1340 msgid ""
3934 :     "The loader for a lazy-load database of code or data is function "
3935 :     "@code{lazyLoad} in the @pkg{base} package, but note that there is a separate "
3936 :     "copy to load @pkg{base} itself in file @file{R_HOME/base/R/base}."
3937 : gnustats 1339 msgstr ""
3938 :    
3939 :     #. type: Plain text
3940 :     #: R-ints.texi:1928
3941 : gnustats 1340 msgid ""
3942 :     "Lazy-load databases are created by the code in @file{src/library/tools/R/"
3943 :     "makeLazyLoad.R}: the main tool is the unexported function "
3944 :     "@code{makeLazyLoadDB} and the insertion of database entries is done by calls "
3945 :     "to @code{.Call(\"R_lazyLoadDBinsertValue\", ...)}."
3946 : gnustats 1339 msgstr ""
3947 :    
3948 :     #. type: Plain text
3949 :     #: R-ints.texi:1932
3950 : gnustats 1340 msgid ""
3951 :     "Lazy-load databases of less than 10MB are cached in memory at first use: "
3952 :     "this was found necessary when using file systems with high latency "
3953 :     "(removable devices and network-mounted file systems on Windows)."
3954 : gnustats 1339 msgstr ""
3955 :    
3956 :     #. type: Plain text
3957 :     #: R-ints.texi:1942
3958 : gnustats 1340 msgid ""
3959 :     "Lazy-load databases are loaded into the exports for a package, but not into "
3960 :     "the namespace environment itself. Thus they are visible when the package is "
3961 :     "@emph{attached}, and also @emph{via} the @code{::} operator. This was a "
3962 :     "deliberate design decision, as packages mostly make datasets available for "
3963 :     "use by the end user (or other packages), and they should not be found "
3964 :     "preferentially from functions in the package, surprising users who expected "
3965 :     "the normal search path to be used. (There is an alternative mechanism, "
3966 :     "@file{sysdata.rda}, for `system datasets' that are intended primarily to be "
3967 :     "used within the package.)"
3968 : gnustats 1339 msgstr ""
3969 :    
3970 :     #. type: Plain text
3971 :     #: R-ints.texi:1946
3972 : gnustats 1340 msgid ""
3973 :     "The same database mechanism is used to store parsed @file{Rd} files. One or "
3974 :     "all of the parsed objects is fetched by a call to @code{tools:::fetchRdDB}."
3975 : gnustats 1339 msgstr ""
3976 :    
3977 :     #. type: chapter
3978 :     #: R-ints.texi:1948
3979 :     #, no-wrap
3980 :     msgid "@code{.Internal} vs @code{.Primitive}"
3981 :     msgstr ""
3982 :    
3983 :     #. type: findex
3984 :     #: R-ints.texi:1950
3985 :     #, no-wrap
3986 :     msgid ".Internal"
3987 :     msgstr ""
3988 :    
3989 :     #. type: findex
3990 :     #: R-ints.texi:1951
3991 :     #, no-wrap
3992 :     msgid ".Primitive"
3993 :     msgstr ""
3994 :    
3995 :     #. type: Plain text
3996 :     #: R-ints.texi:1964
3997 : gnustats 1340 msgid ""
3998 :     "C code compiled into @R{} at build time can be called directly in what are "
3999 :     "termed @emph{primitives} or via the @code{.Internal} interface, which is "
4000 :     "very similar to the @code{.External} interface except in syntax. More "
4001 :     "precisely, @R{} maintains a table of @R{} function names and corresponding C "
4002 :     "functions to call, which by convention all start with @samp{do_} and return "
4003 :     "a @code{SEXP}. This table (@code{R_FunTab} in file @file{src/main/names.c}) "
4004 :     "also specifies how many arguments to a function are required or allowed, "
4005 :     "whether or not the arguments are to be evaluated before calling, and whether "
4006 :     "the function is `internal' in the sense that it must be accessed via the "
4007 :     "@code{.Internal} interface, or directly accessible in which case it is "
4008 :     "printed in @R{} as @code{.Primitive}."
4009 : gnustats 1339 msgstr ""
4010 :    
4011 :     #. type: Plain text
4012 :     #: R-ints.texi:1968
4013 : gnustats 1340 msgid ""
4014 :     "Functions using @code{.Internal()} wrapped in a closure are in general "
4015 :     "preferred as this ensures standard handling of named and default arguments. "
4016 :     "For example, @code{grep} is defined as"
4017 : gnustats 1339 msgstr ""
4018 :    
4019 :     #. type: group
4020 :     #: R-ints.texi:1979
4021 :     #, no-wrap
4022 :     msgid ""
4023 :     "grep <-\n"
4024 :     "function (pattern, x, ignore.case = FALSE, perl = FALSE, value = FALSE,\n"
4025 :     " fixed = FALSE, useBytes = FALSE, invert = FALSE)\n"
4026 :     "@{\n"
4027 :     " if (!is.character(x)) x <- structure(as.character(x), names = names(x))\n"
4028 :     " .Internal(grep(as.character(pattern), x, ignore.case, value,\n"
4029 :     " perl, fixed, useBytes, invert))\n"
4030 :     "@}\n"
4031 :     "\n"
4032 :     msgstr ""
4033 :    
4034 :     #. type: Plain text
4035 :     #: R-ints.texi:1984
4036 : gnustats 1340 msgid ""
4037 :     "and the use of @code{as.character} allows methods to be dispatched (for "
4038 :     "example, for factors)."
4039 : gnustats 1339 msgstr ""
4040 :    
4041 :     #. type: Plain text
4042 :     #: R-ints.texi:1997
4043 : gnustats 1340 msgid ""
4044 :     "However, for reasons of convenience and also efficiency (as there is some "
4045 :     "overhead in using the @code{.Internal} interface wrapped in a function "
4046 :     "closure), the primitive functions are exceptions that can be accessed "
4047 :     "directly. And of course, primitive functions are needed for basic "
4048 :     "operations---for example @code{.Internal} is itself a primitive. Note that "
4049 :     "primitive functions make no use of @R{} code, and hence are very different "
4050 :     "from the usual interpreted functions. In particular, @code{formals} and "
4051 :     "@code{body} return @code{NULL} for such objects, and argument matching can "
4052 :     "be handled differently. For some primitives (including @code{call}, "
4053 :     "@code{switch}, @code{.C} and @code{.subset}) positional matching is "
4054 :     "important to avoid partial matching of the first argument."
4055 : gnustats 1339 msgstr ""
4056 :    
4057 :     #. type: Plain text
4058 :     #: R-ints.texi:2000
4059 : gnustats 1340 msgid ""
4060 :     "The list of primitive functions is subject to change; currently, it includes "
4061 :     "the following."
4062 : gnustats 1339 msgstr ""
4063 :    
4064 :     #. type: enumerate
4065 :     #: R-ints.texi:2006
4066 : gnustats 1340 msgid ""
4067 :     "``Special functions'' which really are @emph{language} elements, but "
4068 :     "implemented as primitive functions:"
4069 : gnustats 1339 msgstr ""
4070 :    
4071 :     #. type: group
4072 :     #: R-ints.texi:2011
4073 :     #, no-wrap
4074 :     msgid ""
4075 :     "@{ ( if for while repeat break next\n"
4076 :     "return function quote switch\n"
4077 :     msgstr ""
4078 :    
4079 :     #. type: enumerate
4080 :     #: R-ints.texi:2018
4081 : gnustats 1340 msgid ""
4082 :     "Language elements and basic @emph{operator}s (i.e., functions usually "
4083 :     "@emph{not} called as @code{foo(a, b, ...)}) for subsetting, assignment, "
4084 :     "arithmetic, comparison and logic:"
4085 : gnustats 1339 msgstr ""
4086 :    
4087 :     #. type: group
4088 :     #: R-ints.texi:2023
4089 :     #, no-wrap
4090 :     msgid ""
4091 :     " [ [[ $ @@\n"
4092 :     "<- <<- = [<- [[<- $<- @@<-\n"
4093 :     "\n"
4094 :     msgstr ""
4095 :    
4096 :     #. type: group
4097 :     #: R-ints.texi:2027
4098 :     #, no-wrap
4099 :     msgid ""
4100 :     "+ - * / ^ %% %*% %/%\n"
4101 :     "< <= == != >= >\n"
4102 :     "| || & && !\n"
4103 :     msgstr ""
4104 :    
4105 :     #. type: enumerate
4106 :     #: R-ints.texi:2033
4107 : gnustats 1340 msgid ""
4108 :     "When the arithmetic, comparison and logical operators are called as "
4109 :     "functions, any argument names are discarded so positional matching is used."
4110 : gnustats 1339 msgstr ""
4111 :    
4112 :     #. type: enumerate
4113 :     #: R-ints.texi:2037
4114 : gnustats 1340 msgid ""
4115 :     "``Low level'' 0-- and 1--argument functions which belong to one of the "
4116 :     "following groups of functions:"
4117 : gnustats 1339 msgstr ""
4118 :    
4119 :     #. type: enumerate
4120 :     #: R-ints.texi:2041
4121 :     msgid "Basic mathematical functions with a single argument, i.e.,"
4122 :     msgstr ""
4123 :    
4124 :     #. type: group
4125 :     #: R-ints.texi:2046
4126 :     #, no-wrap
4127 :     msgid ""
4128 :     "abs sign sqrt\n"
4129 :     "floor ceiling\n"
4130 :     msgstr ""
4131 :    
4132 :     #. type: group
4133 :     #: R-ints.texi:2056
4134 :     #, no-wrap
4135 :     msgid ""
4136 :     "exp expm1\n"
4137 :     "log2 log10 log1p\n"
4138 :     "cos sin tan\n"
4139 :     "acos asin atan\n"
4140 :     "cosh sinh tanh\n"
4141 :     "acosh asinh atanh\n"
4142 :     "cospi sinpi tanpi\n"
4143 :     msgstr ""
4144 :    
4145 :     #. type: group
4146 :     #: R-ints.texi:2060
4147 :     #, no-wrap
4148 :     msgid "gamma lgamma digamma trigamma\n"
4149 :     msgstr ""
4150 :    
4151 :     #. type: group
4152 :     #: R-ints.texi:2064
4153 :     #, no-wrap
4154 :     msgid "cumsum cumprod cummax cummin\n"
4155 :     msgstr ""
4156 :    
4157 :     #. type: group
4158 :     #: R-ints.texi:2068
4159 :     #, no-wrap
4160 :     msgid "Im Re Arg Conj Mod\n"
4161 :     msgstr ""
4162 :    
4163 :     #. type: enumerate
4164 :     #: R-ints.texi:2073
4165 : gnustats 1340 msgid ""
4166 :     "@code{log} is a primitive function of one or two arguments with named "
4167 :     "argument matching."
4168 : gnustats 1339 msgstr ""
4169 :    
4170 :     #. type: enumerate
4171 :     #: R-ints.texi:2077
4172 : gnustats 1340 msgid ""
4173 :     "@code{trunc} is a difficult case: it is a primitive that can have one or "
4174 :     "more arguments: the default method handled in the primitive has only one."
4175 : gnustats 1339 msgstr ""
4176 :    
4177 :     #. type: enumerate
4178 :     #: R-ints.texi:2081
4179 : gnustats 1340 msgid ""
4180 :     "Functions rarely used outside of ``programming'' (i.e., mostly used inside "
4181 :     "other functions), such as"
4182 : gnustats 1339 msgstr ""
4183 :    
4184 :     #. type: group
4185 :     #: R-ints.texi:2096
4186 :     #, no-wrap
4187 :     msgid ""
4188 :     "nargs missing on.exit interactive\n"
4189 :     "as.call as.character as.complex as.double\n"
4190 :     "as.environment as.integer as.logical as.raw\n"
4191 :     "is.array is.atomic is.call is.character\n"
4192 :     "is.complex is.double is.environment is.expression\n"
4193 :     "is.finite is.function is.infinite is.integer\n"
4194 :     "is.language is.list is.logical is.matrix\n"
4195 :     "is.na is.name is.nan is.null\n"
4196 :     "is.numeric is.object is.pairlist is.raw\n"
4197 :     "is.real is.recursive is.single is.symbol\n"
4198 :     "baseenv emptyenv globalenv pos.to.env\n"
4199 :     "unclass invisible seq_along seq_len\n"
4200 :     msgstr ""
4201 :    
4202 :     #. type: enumerate
4203 :     #: R-ints.texi:2101
4204 :     msgid "The programming and session management utilities"
4205 :     msgstr ""
4206 :    
4207 :     #. type: group
4208 :     #: R-ints.texi:2105
4209 :     #, no-wrap
4210 :     msgid "browser proc.time gc.time tracemem retracemem untracemem\n"
4211 :     msgstr ""
4212 :    
4213 :     #. type: enumerate
4214 :     #: R-ints.texi:2112
4215 :     msgid "The following basic replacement and extractor functions"
4216 :     msgstr ""
4217 :    
4218 :     #. type: group
4219 :     #: R-ints.texi:2126
4220 :     #, no-wrap
4221 :     msgid ""
4222 :     "length length<-\n"
4223 :     "class class<-\n"
4224 :     "oldClass oldCLass<-\n"
4225 :     "attr attr<-\n"
4226 :     "attributes attributes<-\n"
4227 :     "names names<-\n"
4228 :     "dim dim<-\n"
4229 :     "dimnames dimnames<-\n"
4230 :     " environment<-\n"
4231 :     " levels<-\n"
4232 :     " storage.mode<-\n"
4233 :     msgstr ""
4234 :    
4235 :     #. type: enumerate
4236 :     #: R-ints.texi:2136
4237 : gnustats 1340 msgid ""
4238 :     "Note that optimizing @code{NAMED = 1} is only effective within a primitive "
4239 :     "(as the closure wrapper of a @code{.Internal} will set @code{NAMED = 2} when "
4240 :     "the promise to the argument is evaluated) and hence replacement functions "
4241 :     "should where possible be primitive to avoid copying (at least in their "
4242 :     "default methods)."
4243 : gnustats 1339 msgstr ""
4244 :    
4245 :     #. type: enumerate
4246 :     #: R-ints.texi:2139
4247 :     msgid "The following functions are primitive for efficiency reasons:"
4248 :     msgstr ""
4249 :    
4250 :     #. type: group
4251 :     #: R-ints.texi:2147
4252 :     #, no-wrap
4253 :     msgid ""
4254 :     ": ~ c list\n"
4255 :     "call expression substitute\n"
4256 :     "UseMethod standardGeneric\n"
4257 :     ".C .Fortran .Call .External\n"
4258 :     "round signif rep seq.int\n"
4259 :     msgstr ""
4260 :    
4261 :     #. type: enumerate
4262 :     #: R-ints.texi:2152
4263 :     msgid "as well as the following internal-use-only functions"
4264 :     msgstr ""
4265 :    
4266 :     #. type: group
4267 :     #: R-ints.texi:2160
4268 :     #, no-wrap
4269 :     msgid ""
4270 :     ".Primitive .Internal\n"
4271 :     ".Call.graphics .External.graphics\n"
4272 :     ".subset .subset2\n"
4273 :     ".primTrace .primUntrace\n"
4274 :     "lazyLoadDBfetch\n"
4275 :     msgstr ""
4276 :    
4277 :     #. type: Plain text
4278 :     #: R-ints.texi:2167
4279 :     msgid "The multi-argument primitives"
4280 :     msgstr ""
4281 :    
4282 :     #. type: group
4283 :     #: R-ints.texi:2171
4284 :     #, no-wrap
4285 :     msgid ""
4286 :     "call switch\n"
4287 :     ".C .Fortran .Call .External\n"
4288 :     msgstr ""
4289 :    
4290 :     #. type: Plain text
4291 :     #: R-ints.texi:2179
4292 : gnustats 1340 msgid ""
4293 :     "intentionally use positional matching, and need to do so to avoid partial "
4294 :     "matching to their first argument. They do check that the first argument is "
4295 :     "unnamed or for the first two, partially matches the formal argument name. "
4296 :     "On the other hand,"
4297 : gnustats 1339 msgstr ""
4298 :    
4299 :     #. type: group
4300 :     #: R-ints.texi:2184
4301 :     #, no-wrap
4302 :     msgid ""
4303 :     "attr attr<- browser rememtrace substitute UseMethod\n"
4304 :     "log round signif rep seq.int\n"
4305 :     msgstr ""
4306 :    
4307 :     #. type: Plain text
4308 :     #: R-ints.texi:2189
4309 :     msgid "manage their own argument matching and do work in the standard way."
4310 :     msgstr ""
4311 :    
4312 :     #. type: Plain text
4313 :     #: R-ints.texi:2194
4314 : gnustats 1340 msgid ""
4315 :     "All the one-argument primitives check that if they are called with a named "
4316 :     "argument that this (partially) matches the name given in the documentation: "
4317 :     "this is also done for replacement functions with one argument plus "
4318 :     "@code{value}."
4319 : gnustats 1339 msgstr ""
4320 :    
4321 :     #. type: Plain text
4322 :     #: R-ints.texi:2199
4323 : gnustats 1340 msgid ""
4324 :     "The net effect is that argument matching for primitives intended for end-"
4325 :     "user use @emph{as functions} is done in the same way as for interpreted "
4326 :     "functions except for the six exceptions where positional matching is "
4327 :     "required."
4328 : gnustats 1339 msgstr ""
4329 :    
4330 :     #. type: node
4331 :     #: R-ints.texi:2205
4332 :     #: R-ints.texi:2207
4333 :     #: R-ints.texi:2208
4334 :     #: R-ints.texi:2233
4335 :     #, no-wrap
4336 :     msgid "Special primitives"
4337 :     msgstr ""
4338 :    
4339 :     #. type: node
4340 :     #: R-ints.texi:2205
4341 :     #: R-ints.texi:2207
4342 :     #: R-ints.texi:2233
4343 :     #: R-ints.texi:2234
4344 :     #: R-ints.texi:2241
4345 :     #, no-wrap
4346 :     msgid "Special internals"
4347 :     msgstr ""
4348 :    
4349 :     #. type: node
4350 :     #: R-ints.texi:2205
4351 :     #: R-ints.texi:2233
4352 :     #: R-ints.texi:2241
4353 :     #: R-ints.texi:2242
4354 :     #: R-ints.texi:2300
4355 :     #, no-wrap
4356 :     msgid "Prototypes for primitives"
4357 :     msgstr ""
4358 :    
4359 :     #. type: section
4360 :     #: R-ints.texi:2205
4361 :     #: R-ints.texi:2241
4362 :     #: R-ints.texi:2300
4363 :     #: R-ints.texi:2301
4364 :     #, no-wrap
4365 :     msgid "Adding a primitive"
4366 :     msgstr ""
4367 :    
4368 :     #. type: Plain text
4369 :     #: R-ints.texi:2218
4370 : gnustats 1340 msgid ""
4371 :     "A small number of primitives are @emph{specials} rather than "
4372 :     "@emph{builtins}, that is they are entered with unevaluated arguments. This "
4373 :     "is clearly necessary for the language constructs and the assignment "
4374 :     "operators, as well as for @code{&&} and @code{||} which conditionally "
4375 :     "evaluate their second argument, and @code{~}, @code{.Internal}, @code{call}, "
4376 :     "@code{expression}, @code{missing}, @code{on.exit}, @code{quote} and "
4377 :     "@code{substitute} which do not evaluate some of their arguments."
4378 : gnustats 1339 msgstr ""
4379 :    
4380 :     #. type: Plain text
4381 :     #: R-ints.texi:2221
4382 : gnustats 1340 msgid ""
4383 :     "@code{rep} and @code{seq.int} are special as they evaluate some of their "
4384 :     "arguments conditional on which are non-missing."
4385 : gnustats 1339 msgstr ""
4386 :    
4387 :     #. type: Plain text
4388 :     #: R-ints.texi:2224
4389 : gnustats 1340 msgid ""
4390 :     "@code{log}, @code{round} and @code{signif} are special to allow default "
4391 :     "values to be given to missing arguments."
4392 : gnustats 1339 msgstr ""
4393 :    
4394 :     #. type: Plain text
4395 :     #: R-ints.texi:2229
4396 : gnustats 1340 msgid ""
4397 :     "The subsetting, subassignment and @code{@@} operators are all special. (For "
4398 :     "both extraction and replacement forms, @code{$} and @code{@@} take a symbol "
4399 :     "argument, and @code{[} and @code{[[} allow missing arguments.)"
4400 : gnustats 1339 msgstr ""
4401 :    
4402 :     #. type: Plain text
4403 :     #: R-ints.texi:2232
4404 : gnustats 1340 msgid ""
4405 :     "@code{UseMethod} is special to avoid the additional contexts added to calls "
4406 :     "to builtins."
4407 : gnustats 1339 msgstr ""
4408 :    
4409 :     #. type: Plain text
4410 :     #: R-ints.texi:2240
4411 : gnustats 1340 msgid ""
4412 :     "There are also special @code{.Internal} functions: @code{NextMethod}, "
4413 :     "@code{Recall}, @code{withVisible}, @code{cbind}, @code{rbind} (to allow for "
4414 :     "the @code{deparse.level} argument), @code{eapply}, @code{lapply} and "
4415 :     "@code{vapply}."
4416 : gnustats 1339 msgstr ""
4417 :    
4418 :     #. type: Plain text
4419 :     #: R-ints.texi:2253
4420 : gnustats 1340 msgid ""
4421 :     "Prototypes are available for the primitive functions and operators, and "
4422 :     "these are used for printing, @code{args} and package checking (e.g.@: by "
4423 :     "@code{tools::checkS3methods} and by package @CRANpkg{codetools}). There are "
4424 :     "two environments in the @pkg{base} package (and namespace), @samp{."
4425 :     "GenericArgsEnv} for those primitives which are internal S3 generics, and "
4426 :     "@samp{.ArgsEnv} for the rest. Those environments contain closures with the "
4427 :     "same names as the primitives, formal arguments derived (manually) from the "
4428 :     "help pages, a body which is a suitable call to @code{UseMethod} or "
4429 :     "@code{NULL} and environment the base namespace."
4430 : gnustats 1339 msgstr ""
4431 :    
4432 :     #. type: Plain text
4433 :     #: R-ints.texi:2257
4434 : gnustats 1340 msgid ""
4435 :     "The C code for @code{print.default} and @code{args} uses the closures in "
4436 :     "these environments in preference to the definitions in base (as primitives)."
4437 : gnustats 1339 msgstr ""
4438 :    
4439 :     #. type: Plain text
4440 :     #: R-ints.texi:2262
4441 : gnustats 1340 msgid ""
4442 :     "The QC function @code{undoc} checks that all the functions prototyped in "
4443 :     "these environments are currently primitive, and that the primitives not "
4444 :     "included are better thought of as language elements (at the time of writing"
4445 : gnustats 1339 msgstr ""
4446 :    
4447 :     #. type: example
4448 :     #: R-ints.texi:2266
4449 :     #, no-wrap
4450 :     msgid ""
4451 :     "$ $<- && ( : @@ @@<- [ [[ [[<- [<- @{ || ~ <- <<- =\n"
4452 :     "break for function if next repeat return while\n"
4453 :     msgstr ""
4454 :    
4455 :     #. type: Plain text
4456 :     #: R-ints.texi:2272
4457 : gnustats 1340 msgid ""
4458 :     "). One could argue about @code{~}, but it is known to the parser and has "
4459 :     "semantics quite unlike a normal function. And @code{:} is documented with "
4460 :     "different argument names in its two meanings.)"
4461 : gnustats 1339 msgstr ""
4462 :    
4463 :     #. type: Plain text
4464 :     #: R-ints.texi:2291
4465 : gnustats 1340 msgid ""
4466 :     "The QC functions @code{codoc} and @code{checkS3methods} also make use of "
4467 :     "these environments (effectively placing them in front of base in the search "
4468 :     "path), and hence the formals of the functions they contain are checked "
4469 :     "against the help pages by @code{codoc}. However, there are two problems "
4470 :     "with the generic primitives. The first is that many of the operators are "
4471 :     "part of the S3 group generic @code{Ops} and that defines their arguments to "
4472 :     "be @code{e1} and @code{e2}: although it would be very unusual, an operator "
4473 :     "could be called as e.g.@: @code{\"+\"(e1=a, e2=b)} and if method dispatch "
4474 :     "occurred to a closure, there would be an argument name mismatch. So the "
4475 :     "definitions in environment @code{.GenericArgsEnv} have to use argument names "
4476 :     "@code{e1} and @code{e2} even though the traditional documentation is in "
4477 :     "terms of @code{x} and @code{y}: @code{codoc} makes the appropriate "
4478 :     "adjustment via @code{tools:::.make_S3_primitive_generic_env}. The second "
4479 :     "discrepancy is with the @code{Math} group generics, where the group generic "
4480 :     "is defined with argument list @code{(x, ...)}, but most of the members only "
4481 :     "allow one argument when used as the default method (and @code{round} and "
4482 :     "@code{signif} allow two as default methods): again fix-ups are used."
4483 : gnustats 1339 msgstr ""
4484 :    
4485 :     #. type: Plain text
4486 :     #: R-ints.texi:2299
4487 : gnustats 1340 msgid ""
4488 :     "Those primitives which are in @code{.GenericArgsEnv} are checked (via "
4489 :     "@file{tests/primitives.R}) to be generic @emph{via} defining methods for "
4490 :     "them, and a check is made that the remaining primitives are probably not "
4491 :     "generic, by setting a method and checking it is not dispatched to (but this "
4492 :     "can fail for other reasons). However, there is no certain way to know that "
4493 :     "if other @code{.Internal} or primitive functions are not internally generic "
4494 :     "except by reading the source code."
4495 : gnustats 1339 msgstr ""
4496 :    
4497 :     #. type: Plain text
4498 :     #: R-ints.texi:2306
4499 : gnustats 1340 msgid ""
4500 :     "[For R-core use: reverse this procedure to remove a primitive. Most "
4501 :     "commonly this is done by changing a @code{.Internal} to a primitive or "
4502 :     "@emph{vice versa}.]"
4503 : gnustats 1339 msgstr ""
4504 :    
4505 :     #. type: Plain text
4506 :     #: R-ints.texi:2310
4507 : gnustats 1340 msgid ""
4508 :     "Primitives are listed in the table @code{R_FunTab} in @file{src/main/names."
4509 :     "c}: primitives have @samp{Y = 0} in the @samp{eval} field."
4510 : gnustats 1339 msgstr ""
4511 :    
4512 :     #. type: Plain text
4513 :     #: R-ints.texi:2314
4514 : gnustats 1340 msgid ""
4515 :     "There needs to be an @samp{\\alias} entry in a help file in the @pkg{base} "
4516 :     "package, and the primitive needs to be added to one of the lists at the "
4517 :     "start of this section."
4518 : gnustats 1339 msgstr ""
4519 :    
4520 :     #. type: Plain text
4521 :     #: R-ints.texi:2320
4522 : gnustats 1340 msgid ""
4523 :     "Some primitives are regarded as language elements (the current ones are "
4524 :     "listed above). These need to be added to two lists of exceptions, "
4525 :     "@code{langElts} in @code{undoc()} (in file @file{src/library/tools/R/QC.R}) "
4526 :     "and @code{lang_elements} in @file{tests/primitives.R}."
4527 : gnustats 1339 msgstr ""
4528 :    
4529 :     #. type: Plain text
4530 :     #: R-ints.texi:2329
4531 : gnustats 1340 msgid ""
4532 :     "All other primitives are regarded as functions and should be listed in one "
4533 :     "of the environments defined in @file{src/library/base/R/zzz.R}, either "
4534 :     "@code{.ArgsEnv} or @code{.GenericArgsEnv}: internal generics also need to be "
4535 :     "listed in the character vector @code{.S3PrimitiveGenerics}. Note too the "
4536 :     "discussion about argument matching above: if you add a primitive function "
4537 :     "with more than one argument by converting a @code{.Internal} you need to add "
4538 :     "argument matching to the C code, and for those with a single argument, add "
4539 :     "argument-name checking."
4540 : gnustats 1339 msgstr ""
4541 :    
4542 :     #. type: Plain text
4543 :     #: R-ints.texi:2332
4544 : gnustats 1340 msgid ""
4545 :     "Do ensure that @command{make check-devel} has been run: that tests most of "
4546 :     "these requirements."
4547 : gnustats 1339 msgstr ""
4548 :    
4549 :