SCM

SCM Repository

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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1339, Wed Jan 7 00:16:09 2015 UTC revision 1340, Wed Jan 7 00:16:41 2015 UTC
# Line 7  Line 7 
7  msgstr ""  msgstr ""
8  "Project-Id-Version: R-manual-translation-ko 0.3.0.1\n"  "Project-Id-Version: R-manual-translation-ko 0.3.0.1\n"
9  "Report-Msgid-Bugs-To: chl948@mail.usask.ca\n"  "Report-Msgid-Bugs-To: chl948@mail.usask.ca\n"
10  "POT-Creation-Date: 2014-12-23 00:16-0600\n"  "POT-Creation-Date: 2015-01-06 18:16-0600\n"
11  "PO-Revision-Date: 2014-12-23 00:16-0600\n"  "PO-Revision-Date: 2015-01-06 18:16-0600\n"
12  "Last-Translator: Chel Hee Lee  <chl948@mail.usask.ca>\n"  "Last-Translator: Chel Hee Lee  <chl948@mail.usask.ca>\n"
13  "Language-Team: Chel Hee Lee  <chl948@mail.usask.ca>\n"  "Language-Team: Chel Hee Lee  <chl948@mail.usask.ca>\n"
14  "Language: ko\n"  "Language: ko\n"
# Line 135  Line 135 
135    
136  #. type: ifnottex  #. type: ifnottex
137  #: R-ints.texi:55  #: R-ints.texi:55
138  msgid "This is a guide to the internal structures of @R{} and coding standards for the core team working on @R{} itself."  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  msgstr ""  msgstr ""
142    
143  #. type: node  #. type: node
# Line 286  Line 288 
288    
289  #. type: Plain text  #. type: Plain text
290  #: R-ints.texi:84  #: R-ints.texi:84
291  msgid "This chapter is the beginnings of documentation about @R{} internal structures.  It is written for the core team and others studying the code in the @file{src/main} directory."  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  msgstr ""  msgstr ""
296    
297  #. type: Plain text  #. type: Plain text
298  #: R-ints.texi:89  #: R-ints.texi:89
299  msgid "It is a work-in-progress and should be checked against the current version of the source code.  Versions for @R{} 2.x.y contain historical comments about when features were introduced: this version is for the 3.x.y series."  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  msgstr ""  msgstr ""
304    
305  #. type: node  #. type: node
# Line 493  Line 501 
501    
502  #. type: Plain text  #. type: Plain text
503  #: R-ints.texi:122  #: R-ints.texi:122
504  msgid "What @R{} users think of as @emph{variables} or @emph{objects} are symbols which are bound to a value.  The value can be thought of as either a @code{SEXP} (a pointer), or the structure it points to, a @code{SEXPREC} (and there are alternative forms used for vectors, namely @code{VECSXP} pointing to @code{VECTOR_SEXPREC} structures).  So the basic building blocks of @R{} objects are often called @emph{nodes}, meaning @code{SEXPREC}s or @code{VECTOR_SEXPREC}s."  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  msgstr ""  msgstr ""
513    
514  #. type: Plain text  #. type: Plain text
515  #: R-ints.texi:126  #: R-ints.texi:126
516  msgid "Note that the internal structure of the @code{SEXPREC} is not made available to @R{} Extensions: rather @code{SEXP} is an opaque pointer, and the internals can only be accessed by the functions provided."  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  msgstr ""  msgstr ""
521    
522  #. type: cindex  #. type: cindex
# Line 509  Line 527 
527    
528  #. type: Plain text  #. type: Plain text
529  #: R-ints.texi:135  #: R-ints.texi:135
530  msgid "Both types of node structure have as their first three fields a 32-bit @code{sxpinfo} header and then three pointers (to the attributes and the previous and next node in a doubly-linked list), and then some further fields.  On a 32-bit platform a node@footnote{strictly, a @code{SEXPREC} node; @code{VECTOR_SEXPREC} nodes are slightly smaller but followed by data in the node.} occupies 28 bytes: on a 64-bit platform typically 56 bytes (depending on alignment constraints)."  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  msgstr ""  msgstr ""
539    
540  #. type: Plain text  #. type: Plain text
541  #: R-ints.texi:138  #: R-ints.texi:138
542  msgid "The first five bits of the @code{sxpinfo} header specify one of up to 32 @code{SEXPTYPE}s."  msgid ""
543    "The first five bits of the @code{sxpinfo} header specify one of up to 32 "
544    "@code{SEXPTYPE}s."
545  msgstr ""  msgstr ""
546    
547  #. type: node  #. type: node
# Line 563  Line 590 
590    
591  #. type: Plain text  #. type: Plain text
592  #: R-ints.texi:155  #: R-ints.texi:155
593  msgid "Currently @code{SEXPTYPE}s 0:10 and 13:25 are in use.  Values 11 and 12 were used for internal factors and ordered factors and have since been withdrawn.  Note that the @code{SEXPTYPE} numbers are stored in @code{save}d objects and that the ordering of the types is used, so the gap cannot easily be reused."  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  msgstr ""  msgstr ""
600    
601  #. type: cindex  #. type: cindex
# Line 734  Line 766 
766    
767  #. type: Plain text  #. type: Plain text
768  #: R-ints.texi:196  #: R-ints.texi:196
769  msgid "Many of these will be familiar from @R{} level: the atomic vector types are @code{LGLSXP}, @code{INTSXP}, @code{REALSXP}, @code{CPLXSP}, @code{STRSXP} and @code{RAWSXP}.  Lists are @code{VECSXP} and names (also known as symbols) are @code{SYMSXP}.  Pairlists (@code{LISTSXP}, the name going back to the origins of @R{} as a Scheme-like language)  are rarely seen at @R{} level, but are for example used for argument lists.  Character vectors are effectively lists all of whose elements are @code{CHARSXP}, a type that is rarely visible at @R{} level."  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  msgstr ""  msgstr ""
779    
780  #. type: cindex  #. type: cindex
# Line 751  Line 791 
791    
792  #. type: Plain text  #. type: Plain text
793  #: R-ints.texi:208  #: R-ints.texi:208
794  msgid "Language objects (@code{LANGSXP}) are calls (including formulae and so on).  Internally they are pairlists with first element a reference@footnote{a pointer to a function or a symbol to look up the function by name, or a language object to be evaluated to give a function.} to the function to be called with remaining elements the actual arguments for the call (and with the tags if present giving the specified argument names).  Although this is not enforced, many places in the code assume that the pairlist is of length one or more, often without checking."  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  msgstr ""  msgstr ""
804    
805  #. type: cindex  #. type: cindex
# Line 762  Line 810 
810    
811  #. type: Plain text  #. type: Plain text
812  #: R-ints.texi:212  #: R-ints.texi:212
813  msgid "Expressions are of type @code{EXPRSXP}: they are a vector of (usually language) objects most often seen as the result of @code{parse()}."  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  msgstr ""  msgstr ""
817    
818  #. type: cindex  #. type: cindex
# Line 773  Line 823 
823    
824  #. type: Plain text  #. type: Plain text
825  #: R-ints.texi:219  #: R-ints.texi:219
826  msgid "The functions are of types @code{CLOSXP}, @code{SPECIALSXP} and @code{BUILTINSXP}: where @code{SEXPTYPE}s are stored in an integer these are sometimes lumped into a pseudo-type @code{FUNSXP} with code 99.  Functions defined via @code{function} are of type @code{CLOSXP} and have formals, body and environment."  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  msgstr ""  msgstr ""
833    
834  #. type: cindex  #. type: cindex
# Line 784  Line 839 
839    
840  #. type: Plain text  #. type: Plain text
841  #: R-ints.texi:223  #: R-ints.texi:223
842  msgid "The @code{SEXPTYPE} @code{S4SXP} is for S4 objects which do not consist solely of a simple type such as an atomic vector or function."  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  msgstr ""  msgstr ""
846    
847  #. type: Plain text  #. type: Plain text
# Line 818  Line 875 
875    
876  #. type: Plain text  #. type: Plain text
877  #: R-ints.texi:251  #: R-ints.texi:251
878  msgid "The @code{debug} bit is used for closures and environments.  For closures it is set by @code{debug()} and unset by @code{undebug()}, and indicates that evaluations of the function should be run under the browser.  For environments it indicates whether the browsing is in single-step mode."  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  msgstr ""  msgstr ""
884    
885  #. type: findex  #. type: findex
# Line 829  Line 890 
890    
891  #. type: Plain text  #. type: Plain text
892  #: R-ints.texi:255  #: R-ints.texi:255
893  msgid "The @code{trace} bit is used for functions for @code{trace()} and for other objects when tracing duplications (see @code{tracemem})."  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  msgstr ""  msgstr ""
897    
898  #. type: findex  #. type: findex
# Line 840  Line 903 
903    
904  #. type: Plain text  #. type: Plain text
905  #: R-ints.texi:259  #: R-ints.texi:259
906  msgid "The @code{spare} bit is used for closures to mark them for one time debugging."  msgid ""
907    "The @code{spare} bit is used for closures to mark them for one time "
908    "debugging."
909  msgstr ""  msgstr ""
910    
911  #. type: findex  #. type: findex
# Line 872  Line 937 
937    
938  #. type: Plain text  #. type: Plain text
939  #: R-ints.texi:267  #: R-ints.texi:267
940  msgid "The @code{named} field is set and accessed by the @code{SET_NAMED} and @code{NAMED} macros, and take values @code{0}, @code{1} and @code{2}.  @R{} has a `call by value' illusion, so an assignment like"  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  msgstr ""  msgstr ""
945    
946  #. type: example  #. type: example
# Line 883  Line 951 
951    
952  #. type: Plain text  #. type: Plain text
953  #: R-ints.texi:284  #: R-ints.texi:284
954  msgid "appears to make a copy of @code{a} and refer to it as @code{b}.  However, if neither @code{a} nor @code{b} are subsequently altered there is no need to copy.  What really happens is that a new symbol @code{b} is bound to the same value as @code{a} and the @code{named} field on the value object is set (in this case to @code{2}).  When an object is about to be altered, the @code{named} field is consulted.  A value of @code{2} means that the object must be duplicated before being changed.  (Note that this does not say that it is necessary to duplicate, only that it should be duplicated whether necessary or not.)  A value of @code{0} means that it is known that no other @code{SEXP} shares data with this object, and so it may safely be altered.  A value of @code{1} is used for situations like"  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  msgstr ""  msgstr ""
967    
968  #. type: example  #. type: example
# Line 894  Line 973 
973    
974  #. type: Plain text  #. type: Plain text
975  #: R-ints.texi:292  #: R-ints.texi:292
976  msgid "where in principle two copies of @code{a} exist for the duration of the computation as (in principle)"  msgid ""
977    "where in principle two copies of @code{a} exist for the duration of the "
978    "computation as (in principle)"
979  msgstr ""  msgstr ""
980    
981  #. type: example  #. type: example
# Line 905  Line 986 
986    
987  #. type: Plain text  #. type: Plain text
988  #: R-ints.texi:300  #: R-ints.texi:300
989  msgid "but for no longer, and so some primitive functions can be optimized to avoid a copy in this case."  msgid ""
990    "but for no longer, and so some primitive functions can be optimized to avoid "
991    "a copy in this case."
992  msgstr ""  msgstr ""
993    
994  #. type: Plain text  #. type: Plain text
995  #: R-ints.texi:304  #: R-ints.texi:304
996  msgid "The @code{gp} bits are by definition `general purpose'.  We label these from 0 to 15.  Bits 0--5 and bits 14--15 have been used as described below (mainly from detective work on the sources)."  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  msgstr ""  msgstr ""
1001    
1002  #. type: findex  #. type: findex
# Line 933  Line 1019 
1019    
1020  #. type: Plain text  #. type: Plain text
1021  #: R-ints.texi:314  #: R-ints.texi:314
1022  msgid "The bits can be accessed and set by the @code{LEVELS} and @code{SETLEVELS} macros, which names appear to date back to the internal factor and ordered types and are now used in only a few places in the code.  The @code{gp} field is serialized/unserialized for the @code{SEXPTYPE}s other than @code{NILSXP}, @code{SYMSXP} and @code{ENVSXP}."  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  msgstr ""  msgstr ""
1029    
1030  #. type: Plain text  #. type: Plain text
1031  #: R-ints.texi:320  #: R-ints.texi:320
1032  msgid "Bits 14 and 15 of @code{gp} are used for `fancy bindings'.  Bit 14 is used to lock a binding or an environment, and bit 15 is used to indicate an active binding.  (For the definition of an `active binding' see the header comments in file @file{src/main/envir.c}.)  Bit 15 is used for an environment to indicate if it participates in the global cache."  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  msgstr ""  msgstr ""
1039    
1040  #. type: findex  #. type: findex
# Line 955  Line 1051 
1051    
1052  #. type: Plain text  #. type: Plain text
1053  #: R-ints.texi:325  #: R-ints.texi:325
1054  msgid "The macros @code{ARGUSED} and @code{SET_ARGUSED} are used when matching actual and formal function arguments, and take the values 0, 1 and 2."  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  msgstr ""  msgstr ""
1058    
1059  #. type: findex  #. type: findex
# Line 973  Line 1071 
1071    
1072  #. type: Plain text  #. type: Plain text
1073  #: R-ints.texi:334  #: R-ints.texi:334
1074  msgid "The macros @code{MISSING} and @code{SET_MISSING} are used for pairlists of arguments.  Four bits are reserved, but only two are used (and exactly what for is not explained).  It seems that bit 0 is used by @code{matchArgs} to mark missingness on the returned argument list, and bit 1 is used to mark the use of a default value for an argument copied to the evaluation frame of a closure."  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  msgstr ""  msgstr ""
1082    
1083  #. type: findex  #. type: findex
# Line 997  Line 1101 
1101    
1102  #. type: Plain text  #. type: Plain text
1103  #: R-ints.texi:342  #: R-ints.texi:342
1104  msgid "Bit 0 is used by macros @code{DDVAL} and @code{SET_DDVAL}.  This indicates that a @code{SYMSXP} is one of the symbols @code{..n} which are implicitly created when @code{...} is processed, and so indicates that it may need to be looked up in a @code{DOTSXP}."  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  msgstr ""  msgstr ""
1110    
1111  #. type: findex  #. type: findex
# Line 1014  Line 1122 
1122    
1123  #. type: Plain text  #. type: Plain text
1124  #: R-ints.texi:348  #: R-ints.texi:348
1125  msgid "Bit 0 is used for @code{PRSEEN}, a flag to indicate if a promise has already been seen during the evaluation of the promise (and so to avoid recursive loops)."  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  msgstr ""  msgstr ""
1130    
1131  #. type: Plain text  #. type: Plain text
1132  #: R-ints.texi:352  #: R-ints.texi:352
1133  msgid "Bit 0 is used for @code{HASHASH}, on the @code{PRINTNAME} of the @code{TAG} of the frame of an environment. (This bit is not serialized for @code{CHARSXP} objects.)"  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  msgstr ""  msgstr ""
1138    
1139  #. type: Plain text  #. type: Plain text
1140  #: R-ints.texi:355  #: R-ints.texi:355
1141  msgid "Bits 0 and 1 are used for weak references (to indicate `ready to finalize', `finalize on exit')."  msgid ""
1142    "Bits 0 and 1 are used for weak references (to indicate `ready to finalize', "
1143    "`finalize on exit')."
1144  msgstr ""  msgstr ""
1145    
1146  #. type: Plain text  #. type: Plain text
1147  #: R-ints.texi:358  #: R-ints.texi:358
1148  msgid "Bit 0 is used by the condition handling system (on a @code{VECSXP}) to indicate a calling handler."  msgid ""
1149    "Bit 0 is used by the condition handling system (on a @code{VECSXP}) to "
1150    "indicate a calling handler."
1151  msgstr ""  msgstr ""
1152    
1153  #. type: Plain text  #. type: Plain text
# Line 1039  Line 1157 
1157    
1158  #. type: Plain text  #. type: Plain text
1159  #: R-ints.texi:366  #: R-ints.texi:366
1160  msgid "Bits 1, 2, 3, 5 and 6 are used for a @code{CHARSXP} to denote its encoding.  Bit 1 indicates that the @code{CHARSXP} should be treated as a set of bytes, not necessarily representing a character in any known encoding.  Bits 2, 3 and 6 are used to indicate that it is known to be in Latin-1, UTF-8 or @acronym{ASCII} respectively."  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  msgstr ""  msgstr ""
1167    
1168  #. type: Plain text  #. type: Plain text
1169  #: R-ints.texi:371  #: R-ints.texi:371
1170  msgid "Bit 5 for a @code{CHARSXP} indicates that it is hashed by its address, that is @code{NA_STRING} or is in the @code{CHARSXP} cache (this is not serialized).  Only exceptionally is a @code{CHARSXP} not hashed, and this should never happen in end-user code."  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  msgstr ""  msgstr ""
1176    
1177  #. type: subsection  #. type: subsection
# Line 1055  Line 1182 
1182    
1183  #. type: Plain text  #. type: Plain text
1184  #: R-ints.texi:378  #: R-ints.texi:378
1185  msgid "A @code{SEXPREC} is a C structure containing the 32-bit header as described above, three pointers (to the attributes, previous and next node) and the node data, a union"  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  msgstr ""  msgstr ""
1190    
1191  #. type: example  #. type: example
# Line 1074  Line 1204 
1204    
1205  #. type: Plain text  #. type: Plain text
1206  #: R-ints.texi:393  #: R-ints.texi:393
1207  msgid "All of these alternatives apart from the first (an @code{int}) are three pointers, so the union occupies three words."  msgid ""
1208    "All of these alternatives apart from the first (an @code{int}) are three "
1209    "pointers, so the union occupies three words."
1210  msgstr ""  msgstr ""
1211    
1212  #. type: cindex  #. type: cindex
# Line 1085  Line 1217 
1217    
1218  #. type: Plain text  #. type: Plain text
1219  #: R-ints.texi:411  #: R-ints.texi:411
1220  msgid "The vector types are @code{RAWSXP}, @code{CHARSXP}, @code{LGLSXP}, @code{INTSXP}, @code{REALSXP}, @code{CPLXSXP}, @code{STRSXP}, @code{VECSXP}, @code{EXPRSXP} and @code{WEAKREFSXP}.  Remember that such types are a @code{VECTOR_SEXPREC}, which again consists of the header and the same three pointers, but followed by two integers giving the length and `true length'@footnote{This is almost unused.  The only current use is for hash tables of environments (@code{VECSXP}s), where @code{length} is the size of the table and @code{truelength} is the number of primary slots in use, and for the reference hash tables in serialization (@code{VECSXP}s), where @code{truelength} is the number of slots in use.} of the vector, and then followed by the data (aligned as required: on most 32-bit systems with a 24-byte @code{VECTOR_SEXPREC} node the data can follow immediately after the node).  The data are a block of memory of the appropriate length to store `true length' elements (rounded up to a multiple of 8 bytes, with the 8-byte blocks being the `Vcells' referred in the documentation for @code{gc()})."  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  msgstr ""  msgstr ""
1237    
1238  #. type: Plain text  #. type: Plain text
1239  #: R-ints.texi:414  #: R-ints.texi:414
1240  msgid "The `data' for the various types are given in the table below.  A lot of this is interpretation, i.e. the types are not checked."  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  msgstr ""  msgstr ""
1244    
1245  #. type: item  #. type: item
# Line 1101  Line 1250 
1250    
1251  #. type: table  #. type: table
1252  #: R-ints.texi:419  #: R-ints.texi:419
1253  msgid "There is only one object of type @code{NILSXP}, @code{R_NilValue}, with no data."  msgid ""
1254    "There is only one object of type @code{NILSXP}, @code{R_NilValue}, with no "
1255    "data."
1256  msgstr ""  msgstr ""
1257    
1258  #. type: item  #. type: item
# Line 1112  Line 1263 
1263    
1264  #. type: table  #. type: table
1265  #: R-ints.texi:426  #: R-ints.texi:426
1266  msgid "Pointers to three nodes, the name, value and internal, accessed by @code{PRINTNAME} (a @code{CHARSXP}), @code{SYMVALUE} and @code{INTERNAL}.  (If the symbol's value is a @code{.Internal} function, the last is a pointer to the appropriate @code{SEXPREC}.)  Many symbols have @code{SYMVALUE} @code{R_UnboundValue}."  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  msgstr ""  msgstr ""
1273    
1274  #. type: item  #. type: item
# Line 1123  Line 1279 
1279    
1280  #. type: table  #. type: table
1281  #: R-ints.texi:430  #: R-ints.texi:430
1282  msgid "Pointers to the CAR, CDR (usually a @code{LISTSXP} or @code{NULL}) and TAG (a @code{SYMSXP} or @code{NULL})."  msgid ""
1283    "Pointers to the CAR, CDR (usually a @code{LISTSXP} or @code{NULL}) and TAG "
1284    "(a @code{SYMSXP} or @code{NULL})."
1285  msgstr ""  msgstr ""
1286    
1287  #. type: item  #. type: item
# Line 1145  Line 1303 
1303    
1304  #. type: table  #. type: table
1305  #: R-ints.texi:438  #: R-ints.texi:438
1306  msgid "Pointers to the frame, enclosing environment and hash table (@code{NULL} or a @code{VECSXP}).  A frame is a tagged pairlist with tag the symbol and CAR the bound value."  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  msgstr ""  msgstr ""
1311    
1312  #. type: item  #. type: item
# Line 1156  Line 1317 
1317    
1318  #. type: table  #. type: table
1319  #: R-ints.texi:443  #: R-ints.texi:443
1320  msgid "Pointers to the value, expression and environment (in which to evaluate the expression).  Once an promise has been evaluated, the environment is set to @code{NULL}."  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  msgstr ""  msgstr ""
1325    
1326  #. type: item  #. type: item
# Line 1167  Line 1331 
1331    
1332  #. type: table  #. type: table
1333  #: R-ints.texi:451  #: R-ints.texi:451
1334  msgid "A special type of @code{LISTSXP} used for function calls.  (The CAR references the function (perhaps via a symbol or language object), and the CDR the argument list with tags for named arguments.)  @R{}-level documentation references to `expressions' / `language objects' are mainly @code{LANGSXP}s, but can be symbols (@code{SYMSXP}s) or expression vectors (@code{EXPRSXP}s)."  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  msgstr ""  msgstr ""
1342    
1343  #. type: item  #. type: item
# Line 1184  Line 1354 
1354    
1355  #. type: table  #. type: table
1356  #: R-ints.texi:456  #: R-ints.texi:456
1357  msgid "An integer giving the offset into the table of primitives/@code{.Internal}s."  msgid ""
1358    "An integer giving the offset into the table of primitives/@code{.Internal}s."
1359  msgstr ""  msgstr ""
1360    
1361  #. type: item  #. type: item
# Line 1195  Line 1366 
1366    
1367  #. type: table  #. type: table
1368  #: R-ints.texi:460  #: R-ints.texi:460
1369  msgid "@code{length}, @code{truelength} followed by a block of bytes (allowing for the @code{nul} terminator)."  msgid ""
1370    "@code{length}, @code{truelength} followed by a block of bytes (allowing for "
1371    "the @code{nul} terminator)."
1372  msgstr ""  msgstr ""
1373    
1374  #. type: item  #. type: item
# Line 1212  Line 1385 
1385    
1386  #. type: table  #. type: table
1387  #: R-ints.texi:465  #: R-ints.texi:465
1388  msgid "@code{length}, @code{truelength} followed by a block of C @code{int}s (which are 32 bits on all @R{} platforms)."  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  msgstr ""  msgstr ""
1392    
1393  #. type: item  #. type: item
# Line 1223  Line 1398 
1398    
1399  #. type: table  #. type: table
1400  #: R-ints.texi:468  #: R-ints.texi:468
1401  msgid "@code{length}, @code{truelength} followed by a block of C @code{double}s."  msgid ""
1402    "@code{length}, @code{truelength} followed by a block of C @code{double}s."
1403  msgstr ""  msgstr ""
1404    
1405  #. type: item  #. type: item
# Line 1234  Line 1410 
1410    
1411  #. type: table  #. type: table
1412  #: R-ints.texi:472  #: R-ints.texi:472
1413  msgid "@code{length}, @code{truelength} followed by a block of C99 @code{double complex}s."  msgid ""
1414    "@code{length}, @code{truelength} followed by a block of C99 @code{double "
1415    "complex}s."
1416  msgstr ""  msgstr ""
1417    
1418  #. type: item  #. type: item
# Line 1245  Line 1423 
1423    
1424  #. type: table  #. type: table
1425  #: R-ints.texi:476  #: R-ints.texi:476
1426  msgid "@code{length}, @code{truelength} followed by a block of pointers (@code{SEXP}s pointing to @code{CHARSXP}s)."  msgid ""
1427    "@code{length}, @code{truelength} followed by a block of pointers (@code{SEXP}"
1428    "s pointing to @code{CHARSXP}s)."
1429  msgstr ""  msgstr ""
1430    
1431  #. type: item  #. type: item
# Line 1256  Line 1436 
1436    
1437  #. type: table  #. type: table
1438  #: R-ints.texi:480  #: R-ints.texi:480
1439  msgid "A special type of @code{LISTSXP} for the value bound to a @code{...} symbol: a pairlist of promises."  msgid ""
1440    "A special type of @code{LISTSXP} for the value bound to a @code{...} symbol: "
1441    "a pairlist of promises."
1442  msgstr ""  msgstr ""
1443    
1444  #. type: item  #. type: item
# Line 1267  Line 1449 
1449    
1450  #. type: table  #. type: table
1451  #: R-ints.texi:484  #: R-ints.texi:484
1452  msgid "This is used as a place holder for any type: there are no actual objects of this type."  msgid ""
1453    "This is used as a place holder for any type: there are no actual objects of "
1454    "this type."
1455  msgstr ""  msgstr ""
1456    
1457  #. type: item  #. type: item
# Line 1284  Line 1468 
1468    
1469  #. type: table  #. type: table
1470  #: R-ints.texi:490  #: R-ints.texi:490
1471  msgid "@code{length}, @code{truelength} followed by a block of pointers.  These are internally identical (and identical to @code{STRSXP}) but differ in the interpretations placed on the elements."  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  msgstr ""  msgstr ""
1476    
1477  #. type: item  #. type: item
# Line 1306  Line 1493 
1493    
1494  #. type: table  #. type: table
1495  #: R-ints.texi:497  #: R-ints.texi:497
1496  msgid "Has three pointers, to the pointer, the protection value (an @R{} object which if alive protects this object) and a tag (a @code{SYMSXP}?)."  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  msgstr ""  msgstr ""
1500    
1501  #. type: item  #. type: item
# Line 1317  Line 1506 
1506    
1507  #. type: table  #. type: table
1508  #: R-ints.texi:503  #: R-ints.texi:503
1509  msgid "A @code{WEAKREFSXP} is a special @code{VECSXP} of length 4, with elements @samp{key}, @samp{value}, @samp{finalizer} and @samp{next}.  The @samp{key} is @code{NULL}, an environment or an external pointer, and the @samp{finalizer} is a function or @code{NULL}."  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  msgstr ""  msgstr ""
1515    
1516  #. type: item  #. type: item
# Line 1350  Line 1543 
1543    
1544  #. type: Plain text  #. type: Plain text
1545  #: R-ints.texi:526  #: R-ints.texi:526
1546  msgid "As we have seen, the field @code{gccls} in the header is three bits to label up to 8 classes of nodes.  Non-vector nodes are of class 0, and `small' vector nodes are of classes 1 to 5, with a class for custom allocator vector nodes 6 and `large' vector nodes being of class 7.  The `small' vector nodes are able to store vector data of up to 8, 16, 32, 64 and 128 bytes: larger vectors are @code{malloc}-ed individually whereas the `small' nodes are allocated from pages of about 2000 bytes. Vector nodes allocated using custom allocators (via @code{allocVector3}) are not counted in the gc memory usage statistics since their memory semantics is not under R's control and may be non-standard (e.g., memory could be partially shared across nodes)."  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  msgstr ""  msgstr ""
1558    
1559  #. type: cindex  #. type: cindex
# Line 1367  Line 1570 
1570    
1571  #. type: Plain text  #. type: Plain text
1572  #: R-ints.texi:538  #: R-ints.texi:538
1573  msgid "What users think of as `variables' are symbols which are bound to objects in `environments'.  The word `environment' is used ambiguously in @R{} to mean @emph{either} the frame of an @code{ENVSXP} (a pairlist of symbol-value pairs) @emph{or} an @code{ENVSXP}, a frame plus an enclosure."  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  msgstr ""  msgstr ""
1579    
1580  #. type: cindex  #. type: cindex
# Line 1378  Line 1585 
1585    
1586  #. type: Plain text  #. type: Plain text
1587  #: R-ints.texi:544  #: R-ints.texi:544
1588  msgid "There are additional places that `variables' can be looked up, called `user databases' in comments in the code.  These seem undocumented in the @R{} sources, but apparently refer to the @pkg{RObjectTable} package at @uref{http://www.omegahat.org/RObjectTables/}."  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  msgstr ""  msgstr ""
1594    
1595  #. type: cindex  #. type: cindex
# Line 1397  Line 1608 
1608    
1609  #. type: Plain text  #. type: Plain text
1610  #: R-ints.texi:558  #: R-ints.texi:558
1611  msgid "The base environment is special.  There is an @code{ENVSXP} environment with enclosure the empty environment @code{R_EmptyEnv}, but the frame of that environment is not used.  Rather its bindings are part of the global symbol table, being those symbols in the global symbol table whose values are not @code{R_UnboundValue}.  When @R{} is started the internal functions are installed (by C code) in the symbol table, with primitive functions having values and @code{.Internal} functions having what would be their values in the field accessed by the @code{INTERNAL} macro.  Then @code{.Platform} and @code{.Machine} are computed and the base package is loaded into the base environment followed by the system profile."  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  msgstr ""  msgstr ""
1623    
1624  #. type: Plain text  #. type: Plain text
1625  #: R-ints.texi:561  #: R-ints.texi:561
1626  msgid "The frames of environments (and the symbol table) are normally hashed for faster access (including insertion and deletion)."  msgid ""
1627    "The frames of environments (and the symbol table) are normally hashed for "
1628    "faster access (including insertion and deletion)."
1629  msgstr ""  msgstr ""
1630    
1631  #. type: Plain text  #. type: Plain text
1632  #: R-ints.texi:572  #: R-ints.texi:572
1633  msgid "By default @R{} maintains a (hashed) global cache of `variables' (that is symbols and their bindings) which have been found, and this refers only to environments which have been marked to participate, which consists of the global environment (aka the user workspace), the base environment plus environments@footnote{Remember that attaching a list or a saved image actually creates and populates an environment and attaches that.} which have been @code{attach}ed.  When an environment is either @code{attach}ed or @code{detach}ed, the names of its symbols are flushed from the cache.  The cache is used whenever searching for variables from the global environment (possibly as part of a recursive search)."  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  msgstr ""  msgstr ""
1645    
1646  #. type: node  #. type: node
# Line 1446  Line 1679 
1679    
1680  #. type: Plain text  #. type: Plain text
1681  #: R-ints.texi:589  #: R-ints.texi:589
1682  msgid "@Sl{} has the notion of a `search path': the lookup for a `variable' leads (possibly through a series of frames) to the `session frame' the `working directory' and then along the search path.  The search path is a series of databases (as returned by @code{search()}) which contain the system functions (but not necessarily at the end of the path, as by default the equivalent of packages are added at the end)."  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  msgstr ""  msgstr ""
1690    
1691  #. type: Plain text  #. type: Plain text
1692  #: R-ints.texi:596  #: R-ints.texi:596
1693  msgid "@R{} has a variant on the @Sl{} model.  There is a search path (also returned by @code{search()}) which consists of the global environment (aka user workspace) followed by environments which have been attached and finally the base environment.  Note that unlike @Sl{} it is not possible to attach environments before the workspace nor after the base environment."  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  msgstr ""  msgstr ""
1700    
1701  #. type: Plain text  #. type: Plain text
1702  #: R-ints.texi:607  #: R-ints.texi:607
1703  msgid "However, the notion of variable lookup is more general in @R{}, hence the plural in the title of this subsection.  Since environments have enclosures, from any environment there is a search path found by looking in the frame, then the frame of its enclosure and so on.  Since loops are not allowed, this process will eventually terminate: it can terminate at either the base environment or the empty environment.  (It can be conceptually simpler to think of the search always terminating at the empty environment, but with an optimization to stop at the base environment.)  So the `search path' describes the chain of environments which is traversed once the search reaches the global environment."  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  msgstr ""  msgstr ""
1715    
1716  #. type: cindex  #. type: cindex
# Line 1467  Line 1721 
1721    
1722  #. type: Plain text  #. type: Plain text
1723  #: R-ints.texi:618  #: R-ints.texi:618
1724  msgid "Namespaces are environments associated with packages (and once again the base package is special and will be considered separately).  A package @code{@var{pkg}} with a namespace defines two environments @code{namespace:@var{pkg}} and @code{package:@var{pkg}}: it is @code{package:@var{pkg}} that can be @code{attach}ed and form part of the search path."  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  msgstr ""  msgstr ""
1731    
1732  #. type: Plain text  #. type: Plain text
1733  #: R-ints.texi:630  #: R-ints.texi:630
1734  msgid "The objects defined by the @R{} code in the package are symbols with bindings in the @code{namespace:@var{pkg}} environment.  The @code{package:@var{pkg}} environment is populated by selected symbols from the @code{namespace:@var{pkg}} environment (the exports).  The enclosure of this environment is an environment populated with the explicit imports from other namespaces, and the enclosure of @emph{that} environment is the base namespace.  (So the illusion of the imports being in the namespace environment is created via the environment tree.)  The enclosure of the base namespace is the global environment, so the search from a package namespace goes via the (explicit and implicit) imports to the standard `search path'."  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  msgstr ""  msgstr ""
1746    
1747  #. type: cindex  #. type: cindex
# Line 1495  Line 1764 
1764    
1765  #. type: Plain text  #. type: Plain text
1766  #: R-ints.texi:640  #: R-ints.texi:640
1767  msgid "The base namespace environment @code{R_BaseNamespace} is another @code{ENVSXP} that is special-cased.  It is effectively the same thing as the base environment @code{R_BaseEnv} @emph{except} that its enclosure is the global environment rather than the empty environment: the internal code diverts lookups in its frame to the global symbol table."  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  msgstr ""  msgstr ""
1774    
1775  #. type: Plain text  #. type: Plain text
1776  #: R-ints.texi:651  #: R-ints.texi:651
1777  msgid "Environments in @R{} usually have a hash table, and nowadays that is the default in @code{new.env()}.  It is stored as a @code{VECSXP} where @code{length} is used for the allocated size of the table and @code{truelength} is the number of primary slots in use---the pointer to the @code{VECSXP} is part of the header of a @code{SEXP} of type @code{ENVSXP}, and this points to @code{R_NilValue} if the environment is not hashed."  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  msgstr ""  msgstr ""
1785    
1786  #. type: Plain text  #. type: Plain text
# Line 1510  Line 1790 
1790    
1791  #. type: Plain text  #. type: Plain text
1792  #: R-ints.texi:659  #: R-ints.texi:659
1793  msgid "The code to implement hashed environments is in @file{src/main/envir.c}.  Unless set otherwise (e.g.@: by the @code{size} argument of @code{new.env()}) the initial table size is @code{29}.  The table will be resized by a factor of 1.2 once the load factor (the proportion of primary slots in use) reaches 85%."  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  msgstr ""  msgstr ""
1800    
1801  #. type: Plain text  #. type: Plain text
1802  #: R-ints.texi:665  #: R-ints.texi:665
1803  msgid "The hash chains are stored as pairlist elements of the @code{VECSXP}: items are inserted at the front of the pairlist.  Hashing is principally designed for fast searching of environments, which are from time to time added to but rarely deleted from, so items are not actually deleted but have their value set to @code{R_UnboundValue}."  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  msgstr ""  msgstr ""
1810    
1811  #. type: cindex  #. type: cindex
# Line 1544  Line 1834 
1834    
1835  #. type: Plain text  #. type: Plain text
1836  #: R-ints.texi:685  #: R-ints.texi:685
1837  msgid "As we have seen, every @code{SEXPREC} has a pointer to the attributes of the node (default @code{R_NilValue}).  The attributes can be accessed/set by the macros/functions @code{ATTRIB} and @code{SET_ATTRIB}, but such direct access is normally only used to check if the attributes are @code{NULL} or to reset them.  Otherwise access goes through the functions @code{getAttrib} and @code{setAttrib} which impose restrictions on the attributes.  One thing to watch is that if you copy attributes from one object to another you may (un)set the @code{\"class\"} attribute and so need to copy the object and S4 bits as well.  There is a macro/function @code{DUPLICATE_ATTRIB} to automate this."  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  msgstr ""  msgstr ""
1849    
1850  #. type: Plain text  #. type: Plain text
1851  #: R-ints.texi:689  #: R-ints.texi:689
1852  msgid "Note that the `attributes' of a @code{CHARSXP} are used as part of the management of the @code{CHARSXP} cache: of course @code{CHARSXP}'s are not user-visible but C-level code might look at their attributes."  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  msgstr ""  msgstr ""
1857    
1858  #. type: Plain text  #. type: Plain text
1859  #: R-ints.texi:701  #: R-ints.texi:701
1860  msgid "The code assumes that the attributes of a node are either @code{R_NilValue} or a pairlist of non-zero length (and this is checked by @code{SET_ATTRIB}).  The attributes are named (via tags on the pairlist).  The replacement function @code{attributes<-} ensures that @code{\"dim\"} precedes @code{\"dimnames\"} in the pairlist.  Attribute @code{\"dim\"} is one of several that is treated specially: the values are checked, and any @code{\"names\"} and @code{\"dimnames\"} attributes are removed.  Similarly, you cannot set @code{\"dimnames\"} without having set @code{\"dim\"}, and the value assigned must be a list of the correct length and with elements of the correct lengths (and all zero-length elements are replaced by @code{NULL})."  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  msgstr ""  msgstr ""
1873    
1874  #. type: Plain text  #. type: Plain text
1875  #: R-ints.texi:715  #: R-ints.texi:715
1876  msgid "The other attributes which are given special treatment are @code{\"names\"}, @code{\"class\"}, @code{\"tsp\"}, @code{\"comment\"} and @code{\"row.names\"}.  For pairlist-like objects the names are not stored as an attribute but (as symbols) as the tags: however the @R{} interface makes them look like conventional attributes, and for one-dimensional arrays they are stored as the first element of the @code{\"dimnames\"} attribute.  The C code ensures that the @code{\"tsp\"} attribute is an @code{REALSXP}, the frequency is positive and the implied length agrees with the number of rows of the object being assigned to.  Classes and comments are restricted to character vectors, and assigning a zero-length comment or class removes the attribute.  Setting or removing a @code{\"class\"} attribute sets the object bit appropriately.  Integer row names are converted to and from the internal compact representation."  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  msgstr ""  msgstr ""
1891    
1892  #. type: Plain text  #. type: Plain text
1893  #: R-ints.texi:725  #: R-ints.texi:725
1894  msgid "Care needs to be taken when adding attributes to objects of the types with non-standard copying semantics.  There is only one object of type @code{NILSXP}, @code{R_NilValue}, and that should never have attributes (and this is enforced in @code{installAttrib}).  For environments, external pointers and weak references, the attributes should be relevant to all uses of the object: it is for example reasonable to have a name for an environment, and also a @code{\"path\"} attribute for those environments populated from @R{} code in a package."  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  msgstr ""  msgstr ""
1904    
1905  #. type: cindex  #. type: cindex
# Line 1581  Line 1916 
1916    
1917  #. type: Plain text  #. type: Plain text
1918  #: R-ints.texi:734  #: R-ints.texi:734
1919  msgid "When should attributes be preserved under operations on an object? Becker, Chambers & Wilks (1988, pp. 144--6) give some guidance.  Scalar functions (those which operate element-by-element on a vector and whose output is similar to the input) should preserve attributes (except perhaps class, and if they do preserve class they need to preserve the @code{OBJECT} and S4 bits).  Binary operations normally call"  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  msgstr ""  msgstr ""
1927    
1928  #. type: findex  #. type: findex
# Line 1592  Line 1933 
1933    
1934  #. type: Plain text  #. type: Plain text
1935  #: R-ints.texi:740  #: R-ints.texi:740
1936  msgid "@code{copyMostAttributes} to copy most attributes from the longer argument (and if they are of the same length from both, preferring the values on the first).  Here `most' means all except the @code{names}, @code{dim} and @code{dimnames} which are set appropriately by the code for the operator."  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  msgstr ""  msgstr ""
1942    
1943  #. type: Plain text  #. type: Plain text
1944  #: R-ints.texi:746  #: R-ints.texi:746
1945  msgid "Subsetting (other than by an empty index) generally drops all attributes except @code{names}, @code{dim} and @code{dimnames} which are reset as appropriate.  On the other hand, subassignment generally preserves such attributes even if the length is changed.  Coercion drops all attributes. For example:"  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  msgstr ""  msgstr ""
1952    
1953  #. type: example  #. type: example
# Line 1635  Line 1985 
1985    
1986  #. type: Plain text  #. type: Plain text
1987  #: R-ints.texi:781  #: R-ints.texi:781
1988  msgid "@emph{Contexts} are the internal mechanism used to keep track of where a computation has got to (and from where), so that control-flow constructs can work and reasonable information can be produced on error conditions (such as @emph{via} traceback), and otherwise (the @code{sys.@var{xxx}} functions)."  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  msgstr ""  msgstr ""
1994    
1995  #. type: Plain text  #. type: Plain text
# Line 1671  Line 2025 
2025    
2026  #. type: Plain text  #. type: Plain text
2027  #: R-ints.texi:810  #: R-ints.texi:810
2028  msgid "plus additional fields for the byte-code compiler.  The `types' are from"  msgid ""
2029    "plus additional fields for the byte-code compiler.  The `types' are from"
2030  msgstr ""  msgstr ""
2031    
2032  #. type: example  #. type: example
# Line 1695  Line 2050 
2050    
2051  #. type: Plain text  #. type: Plain text
2052  #: R-ints.texi:830  #: R-ints.texi:830
2053  msgid "where the @code{CTXT_FUNCTION} bit is on wherever function closures are involved."  msgid ""
2054    "where the @code{CTXT_FUNCTION} bit is on wherever function closures are "
2055    "involved."
2056  msgstr ""  msgstr ""
2057    
2058  #. type: Plain text  #. type: Plain text
2059  #: R-ints.texi:837  #: R-ints.texi:837
2060  msgid "Contexts are created by a call to @code{begincontext} and ended by a call to @code{endcontext}: code can search up the stack for a particular type of context via @code{findcontext} (and jump there) or jump to a specific context via @code{R_JumpToContext}.  @code{R_ToplevelContext} is the `idle' state (normally the command prompt), and @code{R_GlobalContext} is the top of the stack."  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  msgstr ""  msgstr ""
2068    
2069  #. type: Plain text  #. type: Plain text
2070  #: R-ints.texi:840  #: R-ints.texi:840
2071  msgid "Note that whilst calls to closures and builtins set a context, those to special internal functions never do."  msgid ""
2072    "Note that whilst calls to closures and builtins set a context, those to "
2073    "special internal functions never do."
2074  msgstr ""  msgstr ""
2075    
2076  #. type: findex  #. type: findex
# Line 1722  Line 2087 
2087    
2088  #. type: Plain text  #. type: Plain text
2089  #: R-ints.texi:848  #: R-ints.texi:848
2090  msgid "Dispatching from a S3 generic (via @code{UseMethod} or its internal equivalent) or calling @code{NextMethod} sets the context type to @code{CTXT_GENERIC}.  This is used to set the @code{sysparent} of the method call to that of the @code{generic}, so the method appears to have been called in place of the generic rather than from the generic."  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  msgstr ""  msgstr ""
2097    
2098  #. type: Plain text  #. type: Plain text
2099  #: R-ints.texi:852  #: R-ints.texi:852
2100  msgid "The @R{} @code{sys.frame} and @code{sys.call} functions work by counting calls to closures (type @code{CTXT_FUNCTION}) from either end of the context stack."  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  msgstr ""  msgstr ""
2105    
2106  #. type: Plain text  #. type: Plain text
2107  #: R-ints.texi:857  #: R-ints.texi:857
2108  msgid "Note that the @code{sysparent} element of the structure is not the same thing as @code{sys.parent()}.  Element @code{sysparent} is primarily used in managing changes of the function being evaluated, i.e. by @code{Recall} and method dispatch."  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  msgstr ""  msgstr ""
2114    
2115  #. type: Plain text  #. type: Plain text
2116  #: R-ints.texi:863  #: R-ints.texi:863
2117  msgid "@code{CTXT_CCODE} contexts are currently used in @code{cat()}, @code{load()}, @code{scan()} and @code{write.table()} (to close the connection on error), by @code{PROTECT}, serialization (to recover from errors, e.g.@: free buffers) and within the error handling code (to raise the C stack limit and reset some variables)."  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  msgstr ""  msgstr ""
2124    
2125  #. type: cindex  #. type: cindex
# Line 1748  Line 2130 
2130    
2131  #. type: Plain text  #. type: Plain text
2132  #: R-ints.texi:875  #: R-ints.texi:875
2133  msgid "As we have seen, functions in @R{} come in three types, closures (@code{SEXPTYPE} @code{CLOSXP}), specials (@code{SPECIALSXP}) and builtins (@code{BUILTINSXP}).  In this section we consider when (and if)  the actual arguments of function calls are evaluated.  The rules are different for the internal (special/builtin) and @R{}-level functions (closures)."  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  msgstr ""  msgstr ""
2140    
2141  #. type: Plain text  #. type: Plain text
2142  #: R-ints.texi:886  #: R-ints.texi:886
2143  msgid "For a call to a closure, the actual and formal arguments are matched and a matched call (another @code{LANGSXP}) is constructed.  This process first replaces the actual argument list by a list of promises to the values supplied.  It then constructs a new environment which contains the names of the formal parameters matched to actual or default values: all the matched values are promises, the defaults as promises to be evaluated in the environment just created.  That environment is then used for the evaluation of the body of the function, and promises will be forced (and hence actual or default arguments evaluated) when they are encountered."  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  msgstr ""  msgstr ""
2154    
2155  #. type: Plain text  #. type: Plain text
2156  #: R-ints.texi:890  #: R-ints.texi:890
2157  msgid "(Evaluating a promise sets @code{NAMED = 2} on its value, so if the argument was a symbol its binding is regarded as having multiple references during the evaluation of the closure call.)"  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  msgstr ""  msgstr ""
2162    
2163  #. type: Plain text  #. type: Plain text
2164  #: R-ints.texi:906  #: R-ints.texi:906
2165  msgid "If the closure is an S3 generic (that is, contains a call to @code{UseMethod}) the evaluation process is the same until the @code{UseMethod} call is encountered.  At that point the argument on which to do dispatch (normally the first) will be evaluated if it has not been already.  If a method has been found which is a closure, a new evaluation environment is created for it containing the matched arguments of the method plus any new variables defined so far during the evaluation of the body of the generic.  (Note that this means changes to the values of the formal arguments in the body of the generic are discarded when calling the method, but @emph{actual} argument promises which have been forced retain the values found when they were forced.  On the other hand, missing arguments have values which are promises to use the default supplied by the method and not by the generic.)  If the method found is a primitive it is called with the matched argument list of promises (possibly already forced) used for the generic."  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  msgstr ""  msgstr ""
2182    
2183  #. type: cindex  #. type: cindex
# Line 1792  Line 2206 
2206    
2207  #. type: Plain text  #. type: Plain text
2208  #: R-ints.texi:919  #: R-ints.texi:919
2209  msgid "The essential difference@footnote{There is currently one other difference: when profiling builtin functions are counted as function calls but specials are not.} between special and builtin functions is that the arguments of specials are not evaluated before the C code is called, and those of builtins are.  Note that being a special/builtin is separate from being primitive or @code{.Internal}: @code{quote} is a special primitive, @code{+} is a builtin primitive, @code{cbind} is a special @code{.Internal} and @code{grep} is a builtin @code{.Internal}."  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  msgstr ""  msgstr ""
2219    
2220  #. type: cindex  #. type: cindex
# Line 1809  Line 2231 
2231    
2232  #. type: Plain text  #. type: Plain text
2233  #: R-ints.texi:931  #: R-ints.texi:931
2234  msgid "Many of the internal functions are internal generics, which for specials means that they do not evaluate their arguments on call, but the C code starts with a call to @code{DispatchOrEval}.  The latter evaluates the first argument, and looks for a method based on its class.  (If S4 dispatch is on, S4 methods are looked for first, even for S3 classes.)  If it finds a method, it dispatches to that method with a call based on promises to evaluate the remaining arguments.  If no method is found, the remaining arguments are evaluated before return to the internal generic."  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  msgstr ""  msgstr ""
2244    
2245  #. type: cindex  #. type: cindex
# Line 1826  Line 2256 
2256    
2257  #. type: Plain text  #. type: Plain text
2258  #: R-ints.texi:942  #: R-ints.texi:942
2259  msgid "The other way that internal functions can be generic is to be group generic.  Most such functions are builtins (so immediately evaluate all their arguments), and all contain a call to the C function @code{DispatchGeneric}.  There are some peculiarities over the number of arguments for the @code{\"Math\"} group generic, with some members allowing only one argument, some having two (with a default for the second) and @code{trunc} allows one or more but the default method only accepts one."  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  msgstr ""  msgstr ""
2268    
2269  #. type: node  #. type: node
# Line 1855  Line 2292 
2292    
2293  #. type: Plain text  #. type: Plain text
2294  #: R-ints.texi:958  #: R-ints.texi:958
2295  msgid "Actual arguments to (non-internal) @R{} functions can be fewer than are required to match the formal arguments of the function.  Having unmatched formal arguments will not matter if the argument is never used (by lazy evaluation), but when the argument is evaluated, either its default value is evaluated (within the evaluation environment of the function) or an error is thrown with a message along the lines of"  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  msgstr ""  msgstr ""
2303    
2304  #. type: example  #. type: example
# Line 1872  Line 2315 
2315    
2316  #. type: Plain text  #. type: Plain text
2317  #: R-ints.texi:974  #: R-ints.texi:974
2318  msgid "Internally missingness is handled by two mechanisms. The object @code{R_MissingArg} is used to indicate that a formal argument has no (default) value.  When matching the actual arguments to the formal arguments, a new argument list is constructed from the formals all of whose values are @code{R_MissingArg} with the first @code{MISSING} bit set.  Then whenever a formal argument is matched to an actual argument, the corresponding member of the new argument list has its value set to that of the matched actual argument, and if that is not @code{R_MissingArg} the missing bit is unset."  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  msgstr ""  msgstr ""
2329    
2330  #. type: Plain text  #. type: Plain text
2331  #: R-ints.texi:978  #: R-ints.texi:978
2332  msgid "This new argument list is used to form the evaluation frame for the function, and if named arguments are subsequently given a new value (before they are evaluated) the missing bit is cleared."  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  msgstr ""  msgstr ""
2337    
2338  #. type: Plain text  #. type: Plain text
2339  #: R-ints.texi:987  #: R-ints.texi:987
2340  msgid "Missingness of arguments can be interrogated via the @code{missing()} function.  An argument is clearly missing if its missing bit is set or if the value is @code{R_MissingArg}.  However, missingness can be passed on from function to function, for using a formal argument as an actual argument in a function call does not count as evaluation.  So @code{missing()} has to examine the value (a promise) of a non-yet-evaluated formal argument to see if it might be missing, which might involve investigating a promise and so on @dots{}."  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  msgstr ""  msgstr ""
2350    
2351  #. type: Plain text  #. type: Plain text
2352  #: R-ints.texi:992  #: R-ints.texi:992
2353  msgid "Special primitives also need to handle missing arguments, and in some case (e.g.@: @code{log}) that is why they are special and not builtin.  This is usually done by testing if an argument's value is @code{R_MissingArg}."  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  msgstr ""  msgstr ""
2358    
2359  #. type: Plain text  #. type: Plain text
2360  #: R-ints.texi:999  #: R-ints.texi:999
2361  msgid "Dot-dot-dot arguments are convenient when writing functions, but complicate the internal code for argument evaluation."  msgid ""
2362    "Dot-dot-dot arguments are convenient when writing functions, but complicate "
2363    "the internal code for argument evaluation."
2364  msgstr ""  msgstr ""
2365    
2366  #. type: Plain text  #. type: Plain text
2367  #: R-ints.texi:1006  #: R-ints.texi:1006
2368  msgid "The formals of a function with a @code{...} argument represent that as a single argument like any other argument, with tag the symbol @code{R_DotsSymbol}.  When the actual arguments are matched to the formals, the value of the @code{...} argument is of @code{SEXPTYPE} @code{DOTSXP}, a pairlist of promises (as used for matched arguments)  but distinguished by the @code{SEXPTYPE}."  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  msgstr ""  msgstr ""
2376    
2377  #. type: Plain text  #. type: Plain text
2378  #: R-ints.texi:1014  #: R-ints.texi:1014
2379  msgid "Recall that the evaluation frame for a function initially contains the @code{@var{name}=@var{value}} pairs from the matched call, and hence this will be true for @code{...} as well.  The value of @code{...} is a (special) pairlist whose elements are referred to by the special symbols @code{..1}, @code{..2}, @dots{} which have the @code{DDVAL} bit set: when one of these is encountered it is looked up (via @code{ddfindVar})  in the value of the @code{...} symbol in the evaluation frame."  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  msgstr ""  msgstr ""
2388    
2389  #. type: Plain text  #. type: Plain text
# Line 1912  Line 2393 
2393    
2394  #. type: Plain text  #. type: Plain text
2395  #: R-ints.texi:1020  #: R-ints.texi:1020
2396  msgid "Special primitives may need to handle @code{...} arguments: see for example the internal code of @code{switch} in file @file{src/main/builtin.c}."  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  msgstr ""  msgstr ""
2400    
2401  #. type: cindex  #. type: cindex
# Line 1929  Line 2412 
2412    
2413  #. type: Plain text  #. type: Plain text
2414  #: R-ints.texi:1033  #: R-ints.texi:1033
2415  msgid "Whether the returned value of a top-level @R{} expression is printed is controlled by the global boolean variable @code{R_Visible}.  This is set (to true or false) on entry to all primitive and internal functions based on the @code{eval} column of the table in file @file{src/main/names.c}: the appropriate setting can be extracted by the macro @code{PRIMPRINT}."  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  msgstr ""  msgstr ""
2422    
2423  #. type: findex  #. type: findex
# Line 1946  Line 2434 
2434    
2435  #. type: Plain text  #. type: Plain text
2436  #: R-ints.texi:1039  #: R-ints.texi:1039
2437  msgid "The @R{} primitive function @code{invisible} makes use of this mechanism: it just sets @code{R_Visible = FALSE} before entry and returns its argument."  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  msgstr ""  msgstr ""
2441    
2442  #. type: Plain text  #. type: Plain text
2443  #: R-ints.texi:1051  #: R-ints.texi:1051
2444  msgid "For most functions the intention will be that the setting of @code{R_Visible} when they are entered is the setting used when they return, but there need to be exceptions.  The @R{} functions @code{identify}, @code{options}, @code{system} and @code{writeBin} determine whether the result should be visible from the arguments or user action.  Other functions themselves dispatch functions which may change the visibility flag: examples@footnote{the other current example is left brace, which is implemented as a primitive.} are @code{.Internal}, @code{do.call}, @code{eval}, @code{withVisible}, @code{if}, @code{NextMethod}, @code{Recall}, @code{recordGraphics}, @code{standardGeneric}, @code{switch} and @code{UseMethod}."  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  msgstr ""  msgstr ""
2457    
2458  #. type: Plain text  #. type: Plain text
2459  #: R-ints.texi:1056  #: R-ints.texi:1056
2460  msgid "`Special' primitive and internal functions evaluate their arguments internally @emph{after} @code{R_Visible} has been set, and evaluation of the arguments (e.g.@: an assignment as in PR#9263)) can change the value of the flag."  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  msgstr ""  msgstr ""
2466    
2467  #. type: Plain text  #. type: Plain text
2468  #: R-ints.texi:1066  #: R-ints.texi:1066
2469  msgid "The @code{R_Visible} flag can also get altered during the evaluation of a function, with comments in the code about @code{warning}, @code{writeChar} and graphics functions calling @code{GText} (PR#7397).  (Since the C-level function @code{eval} sets @code{R_Visible}, this could apply to any function calling it.  Since it is called when evaluating promises, even object lookup can change @code{R_Visible}.)  Internal and primitive functions force the documented setting of @code{R_Visible} on return, unless the C code is allowed to change it (the exceptions above are indicated by @code{PRIMPRINT} having value 2)."  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  msgstr ""  msgstr ""
2480    
2481  #. type: Plain text  #. type: Plain text
2482  #: R-ints.texi:1074  #: R-ints.texi:1074
2483  msgid "The actual autoprinting is done by @code{PrintValueEnv} in file @file{print.c}.  If the object to be printed has the S4 bit set and S4 methods dispatch is on, @code{show} is called to print the object.  Otherwise, if the object bit is set (so the object has a @code{\"class\"} attribute), @code{print} is called to dispatch methods: for objects without a class the internal code of @code{print.default} is called."  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  msgstr ""  msgstr ""
2491    
2492  #. type: section  #. type: section
# Line 1989  Line 2509 
2509    
2510  #. type: Plain text  #. type: Plain text
2511  #: R-ints.texi:1085  #: R-ints.texi:1085
2512  msgid "@R{} has long had a generational garbage collector, and bit @code{gcgen} in the @code{sxpinfo} header is used in the implementation of this.  This is used in conjunction with the @code{mark} bit to identify two previous generations."  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  msgstr ""  msgstr ""
2518    
2519  #. type: Plain text  #. type: Plain text
2520  #: R-ints.texi:1094  #: R-ints.texi:1094
2521  msgid "There are three levels of collections.  Level 0 collects only the youngest generation, level 1 collects the two youngest generations and level 2 collects all generations.  After 20 level-0 collections the next collection is at level 1, and after 5 level-1 collections at level 2.  Further, if a level-@var{n} collection fails to provide 20% free space (for each of nodes and the vector heap), the next collection will be at level @var{n+1}.  (The @R{}-level function @code{gc()} performs a level-2 collection.)"  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  msgstr ""  msgstr ""
2530    
2531  #. type: Plain text  #. type: Plain text
2532  #: R-ints.texi:1104  #: R-ints.texi:1104
2533  msgid "A generational collector needs to efficiently `age' the objects, especially list-like objects (including @code{STRSXP}s).  This is done by ensuring that the elements of a list are regarded as at least as old as the list @emph{when they are assigned}.  This is handled by the functions @code{SET_VECTOR_ELT} and @code{SET_STRING_ELT}, which is why they are functions and not macros.  Ensuring the integrity of such operations is termed the @dfn{write barrier} and is done by making the @code{SEXP} opaque and only providing access via functions (which cannot be used as lvalues in assignments in C)."  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  msgstr ""  msgstr ""
2544    
2545  #. type: Plain text  #. type: Plain text
2546  #: R-ints.texi:1116  #: R-ints.texi:1116
2547  msgid "All code in @R{} extensions is by default behind the write barrier.  The only way to obtain direct access to the internals of the @code{SEXPREC}s is to define @samp{USE_RINTERNALS} before including header file @file{Rinternals.h}, which is normally defined in @file{Defn.h}.  To enable a check on the way that the access is used, @R{} can be compiled with flag @option{--enable-strict-barrier} which ensures that header @file{Defn.h} does not define @samp{USE_RINTERNALS} and hence that @code{SEXP} is opaque in most of @R{} itself.  (There are some necessary exceptions: foremost in file @file{memory.c} where the accessor functions are defined and also in file @file{size.c} which needs access to the sizes of the internal structures.)"  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  msgstr ""  msgstr ""
2560    
2561  #. type: Plain text  #. type: Plain text
2562  #: R-ints.texi:1120  #: R-ints.texi:1120
2563  msgid "For background papers see @uref{http://www.stat.uiowa.edu/~luke/R/barrier.html} and @uref{http://www.stat.uiowa.edu/~luke/R/gengcnotes.html}."  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  msgstr ""  msgstr ""
2567    
2568  #. type: cindex  #. type: cindex
# Line 2020  Line 2573 
2573    
2574  #. type: Plain text  #. type: Plain text
2575  #: R-ints.texi:1134  #: R-ints.texi:1134
2576  msgid "Serialized versions of @R{} objects are used by @code{load}/@code{save} and also at a slightly lower level by @code{saveRDS}/@code{readRDS} (and their earlier `internal' dot-name versions) and @code{serialize}/@code{unserialize}.  These differ in what they serialize to (a file, a connection, a raw vector) and whether they are intended to serialize a single object or a collection of objects (typically the workspace).  @code{save} writes a header at the beginning of the file (a single LF-terminated line) which the lower-level versions do not."  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  msgstr ""  msgstr ""
2586    
2587  #. type: Plain text  #. type: Plain text
2588  #: R-ints.texi:1143  #: R-ints.texi:1143
2589  msgid "@code{save} and @code{saveRDS} allow various forms of compression, and @command{gzip} compression is the default (except for @acronym{ASCII} saves).  Compression is applied to the whole file stream, including the headers, so serialized files can be uncompressed or re-compressed by external programs.  Both @code{load} and @code{readRDS} can read @command{gzip}, @command{bzip2} and @command{xz} forms of compression when reading from a file, and @command{gzip} compression when reading from a connection."  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  msgstr ""  msgstr ""
2599    
2600  #. type: Plain text  #. type: Plain text
2601  #: R-ints.texi:1150  #: R-ints.texi:1150
2602  msgid "@R{} has used the same serialization format since @R{} 1.4.0 in December 2001.  Earlier formats are still supported via @code{load} and @code{save} but such formats are not described here. The current serialization format is called `version 2', and has been expanded in back-compatible ways since its inception, for example to support additional @code{SEXPTYPE}s."  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  msgstr ""  msgstr ""
2609    
2610  #. type: Plain text  #. type: Plain text
2611  #: R-ints.texi:1164  #: R-ints.texi:1164
2612  msgid "@code{save} works by writing a single-line header (typically @code{RDX2\\n} for a binary save: the only other current value is @code{RDA2\\n} for @code{save(files=TRUE)}), then creating a tagged pairlist of the objects to be saved and serializing that single object.  @code{load} reads the header line, unserializes a single object (a pairlist or a vector list) and assigns the elements of the object in the specified environment.  The header line serves two purposes in @R{}: it identifies the serialization format so @code{load} can switch to the appropriate reader code, and the linefeed allows the detection of files which have been subjected to a non-binary transfer which re-mapped line endings.  It can also be thought of as a `magic number' in the sense used by the @command{file} program (although @R{} save files are not yet by default known to that program)."  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  msgstr ""  msgstr ""
2626    
2627  #. type: Plain text  #. type: Plain text
2628  #: R-ints.texi:1175  #: R-ints.texi:1175
2629  msgid "Serialization in @R{} needs to take into account that objects may contain references to environments, which then have enclosing environments and so on.  (Environments recognized as package or name space environments are saved by name.)  There are `reference objects' which are not duplicated on copy and should remain shared on unserialization.  These are weak references, external pointers and environments other than those associated with packages, namespaces and the global environment.  These are handled via a hash table, and references after the first are written out as a reference marker indexed by the table entry."  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  msgstr ""  msgstr ""
2640    
2641  #. type: Plain text  #. type: Plain text
2642  #: R-ints.texi:1185  #: R-ints.texi:1185
2643  msgid "Version-2 serialization first writes a header indicating the format (normally @samp{X\\n} for an XDR format binary save, but @samp{A\\n}, ASCII, and @samp{B\\n}, native word-order binary, can also occur) and then three integers giving the version of the format and two @R{} versions (packed by the @code{R_Version} macro from @file{Rversion.h}).  (Unserialization interprets the two versions as the version of @R{} which wrote the file followed by the minimal version of @R{} needed to read the format.)  Serialization then writes out the object recursively using function @code{WriteItem} in file @file{src/main/serialize.c}."  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  msgstr ""  msgstr ""
2654    
2655  #. type: Plain text  #. type: Plain text
2656  #: R-ints.texi:1190  #: R-ints.texi:1190
2657  msgid "Some objects are written as if they were @code{SEXPTYPE}s: such pseudo-@code{SEXPTYPE}s cover @code{R_NilValue}, @code{R_EmptyEnv}, @code{R_BaseEnv}, @code{R_GlobalEnv}, @code{R_UnboundValue}, @code{R_MissingArg} and @code{R_BaseNamespace}."  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  msgstr ""  msgstr ""
2663    
2664  #. type: Plain text  #. type: Plain text
2665  #: R-ints.texi:1209  #: R-ints.texi:1209
2666  msgid "For all @code{SEXPTYPE}s except @code{NILSXP}, @code{SYMSXP} and @code{ENVSXP} serialization starts with an integer with the @code{SEXPTYPE} in bits 0:7@footnote{only bits 0:4 are currently used for @code{SEXPTYPE}s but values 241:255 are used for pseudo-@code{SEXPTYPE}s.} followed by the object bit, two bits indicating if there are any attributes and if there is a tag (for the pairlist types), an unused bit and then the @code{gp} field@footnote{Currently the only relevant bits are 0:1, 4, 14:15.} in bits 12:27.  Pairlist-like objects write their attributes (if any), tag (if any), CAR and then CDR (using tail recursion): other objects write their attributes after themselves.  Atomic vector objects write their length followed by the data: generic vector-list objects write their length followed by a call to @code{WriteItem} for each element.  The code for @code{CHARSXP}s special-cases @code{NA_STRING} and writes it as length @code{-1} with no data.  Lengths no more than @code{2^31 - 1} are written in that way and larger lengths (which only occur on 64-bit systems) as @code{-1} followed by the upper and lower 32-bits as integers (regarded as unsigned)."  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  msgstr ""  msgstr ""
2685    
2686  #. type: Plain text  #. type: Plain text
2687  #: R-ints.texi:1216  #: R-ints.texi:1216
2688  msgid "Environments are treated in several ways: as we have seen, some are written as specific pseudo-@code{SEXPTYPE}s.  Package and namespace environments are written with pseudo-@code{SEXPTYPE}s followed by the name.  `Normal' environments are written out as @code{ENVSXP}s with an integer indicating if the environment is locked followed by the enclosure, frame, `tag' (the hash table) and attributes."  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  msgstr ""  msgstr ""
2696    
2697  #. type: Plain text  #. type: Plain text
2698  #: R-ints.texi:1221  #: R-ints.texi:1221
2699  msgid "In the `XDR' format integers and doubles are written in bigendian order: however the format is not fully XDR (as defined in RFC 1832) as byte quantities (such as the contents of @code{CHARSXP} and @code{RAWSXP} types) are written as-is and not padded to a multiple of four bytes."  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  msgstr ""  msgstr ""
2705    
2706  #. type: Plain text  #. type: Plain text
2707  #: R-ints.texi:1228  #: R-ints.texi:1228
2708  msgid "The `ASCII' format writes 7-bit characters.  Integers are formatted with @code{%d} (except that @code{NA_integer_} is written as @code{NA}), doubles formatted with @code{%.16g} (plus @code{NA}, @code{Inf} and @code{-Inf}) and bytes with @code{%02x}.  Strings are written using standard escapes (e.g.@: @code{\\t} and @code{\\013}) for non-printing and non-@acronym{ASCII} bytes."  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  msgstr ""  msgstr ""
2715    
2716  #. type: Plain text  #. type: Plain text
# Line 2080  Line 2720 
2720    
2721  #. type: Plain text  #. type: Plain text
2722  #: R-ints.texi:1245  #: R-ints.texi:1245
2723  msgid "There is support for encodings other than that of the current locale, in particular UTF-8 and the multi-byte encodings used on Windows for CJK languages. A limited means to indicate the encoding of a @code{CHARSXP} is @emph{via} two of the `general purpose' bits which are used to declare the encoding to be either Latin-1 or UTF-8.  (Note that it is possible for a character vector to contain elements in different encodings.)  Both printing and plotting notice the declaration and convert the string to the current locale (possibly using @code{<xx>} to display in hexadecimal bytes that are not valid in the current locale).  Many (but not all) of the character manipulation functions will either preserve the declaration or re-encode the character string."  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  msgstr ""  msgstr ""
2736    
2737  #. type: Plain text  #. type: Plain text
2738  #: R-ints.texi:1248  #: R-ints.texi:1248
2739  msgid "Strings that refer to the OS such as file names need to be passed through a wide-character interface on some OSes (e.g. Windows)."  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  msgstr ""  msgstr ""
2743    
2744  #. type: Plain text  #. type: Plain text
2745  #: R-ints.texi:1255  #: R-ints.texi:1255
2746  msgid "When are character strings declared to be of known encoding? One way is to do so directly via @code{Encoding}.  The parser declares the encoding if this is known, either via the @code{encoding} argument to @code{parse} or from the locale within which parsing is being done at the @R{} command line.  (Other ways are recorded on the help page for @code{Encoding}.)"  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  msgstr ""  msgstr ""
2753    
2754  #. type: Plain text  #. type: Plain text
2755  #: R-ints.texi:1260  #: R-ints.texi:1260
2756  msgid "It is not necessary to declare the encoding of @acronym{ASCII} strings as they will work in any locale.  @acronym{ASCII} strings should never have a marked encoding, as any encoding will be ignored when entering such strings into the @code{CHARSXP} cache."  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  msgstr ""  msgstr ""
2762    
2763  #. type: Plain text  #. type: Plain text
2764  #: R-ints.texi:1273  #: R-ints.texi:1273
2765  msgid "The rationale behind considering only UTF-8 and Latin-1 was that most systems are capable of producing UTF-8 strings and this is the nearest we have to a universal format.  For those that do not (for example those lacking a powerful enough @code{iconv}), it is likely that they work in Latin-1, the old @R{} assumption. The the parser can return a UTF-8-encoded string if it encounters a @samp{\\uxxx} escape for a Unicode point that cannot be represented in the current charset.  (This needs MBCS support, and was only enabled@footnote{See define @code{USE_UTF8_IF_POSSIBLE} in file @file{src/main/gram.c}.} on Windows.)  This is enabled for all platforms, and a @samp{\\uxxx} or @samp{\\Uxxxxxxxx} escape ensures that the parsed string will be marked as UTF-8."  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  msgstr ""  msgstr ""
2778    
2779  #. type: Plain text  #. type: Plain text
2780  #: R-ints.texi:1278  #: R-ints.texi:1278
2781  msgid "Most of the character manipulation functions now preserve UTF-8 encodings: there are some notes as to which at the top of file @file{src/main/character.c} and in file @file{src/library/base/man/Encoding.Rd}."  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  msgstr ""  msgstr ""
2786    
2787  #. type: Plain text  #. type: Plain text
2788  #: R-ints.texi:1289  #: R-ints.texi:1289
2789  msgid "Graphics devices are offered the possibility of handing UTF-8-encoded strings without re-encoding to the native character set, by setting @code{hasTextUTF8} to be @samp{TRUE} and supplying functions @code{textUTF8} and @code{strWidthUTF8} that expect UTF-8-encoded inputs.  Normally the symbol font is encoded in Adobe Symbol encoding, but that can be re-encoded to UTF-8 by setting @code{wantSymbolUTF8} to @samp{TRUE}.  The Windows' port of cairographics has a rather peculiar assumption: it wants the symbol font to be encoded in UTF-8 as if it were encoded in Latin-1 rather than Adobe Symbol: this is selected by @code{wantSymbolUTF8 = NA_LOGICAL}."  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  msgstr ""  msgstr ""
2800    
2801  #. type: Plain text  #. type: Plain text
2802  #: R-ints.texi:1301  #: R-ints.texi:1301
2803  msgid "Windows has no UTF-8 locales, but rather expects to work with UCS-2@footnote{or UTF-16 if support for surrogates is enabled in the OS, which it is not normally so at least for Western versions of Windows, despite some claims to the contrary on the Microsoft website.} strings.  @R{} (being written in standard C) would not work internally with UCS-2 without extensive changes.  The @file{Rgui} console@footnote{but not the GraphApp toolkit.} uses UCS-2 internally, but communicates with the @R{} engine in the native encoding.  To allow UTF-8 strings to be printed in UTF-8 in @file{Rgui.exe}, an escape convention is used (see header file @file{rgui_UTF8.h}) which is used by @code{cat}, @code{print} and autoprinting."  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  msgstr ""  msgstr ""
2816    
2817  #. type: Plain text  #. type: Plain text
2818  #: R-ints.texi:1306  #: R-ints.texi:1306
2819  msgid "`Unicode' (UCS-2LE) files are common in the Windows world, and @code{readLines} and @code{scan} will read them into UTF-8 strings on Windows if the encoding is declared explicitly on an unopened connection passed to those functions."  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  msgstr ""  msgstr ""
2825    
2826  #. type: findex  #. type: findex
# Line 2131  Line 2831 
2831    
2832  #. type: Plain text  #. type: Plain text
2833  #: R-ints.texi:1318  #: R-ints.texi:1318
2834  msgid "There is a global cache for @code{CHARSXP}s created by @code{mkChar} --- the cache ensures that most @code{CHARSXP}s with the same contents share storage (`contents' including any declared encoding).  Not all @code{CHARSXP}s are part of the cache -- notably @samp{NA_STRING} is not. @code{CHARSXP}s reloaded from the @code{save} formats of @R{} prior to 0.99.0 are not cached (since the code used is frozen and very few examples still exist)."  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  msgstr ""  msgstr ""
2842    
2843  #. type: findex  #. type: findex
# Line 2142  Line 2848 
2848    
2849  #. type: Plain text  #. type: Plain text
2850  #: R-ints.texi:1324  #: R-ints.texi:1324
2851  msgid "The cache records the encoding of the string as well as the bytes: all requests to create a @code{CHARSXP} should be @emph{via} a call to @code{mkCharLenCE}.  Any encoding given in @code{mkCharLenCE} call will be ignored if the string's bytes are all @acronym{ASCII} characters."  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  msgstr ""  msgstr ""
2857    
2858  #. type: findex  #. type: findex
# Line 2171  Line 2881 
2881    
2882  #. type: Plain text  #. type: Plain text
2883  #: R-ints.texi:1342  #: R-ints.texi:1342
2884  msgid "Each of @code{warning} and @code{stop} have two C-level equivalents, @code{warning}, @code{warningcall}, @code{error} and @code{errorcall}.  The relationship between the pairs is similar: @code{warning} tries to fathom out a suitable call, and then calls @code{warningcall} with that call as the first argument if it succeeds, and with @code{call = R_NilValue} if it does not.  When @code{warningcall} is called, it includes the deparsed call in its printout unless @code{call = R_NilValue}."  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  msgstr ""  msgstr ""
2893    
2894  #. type: Plain text  #. type: Plain text
2895  #: R-ints.texi:1354  #: R-ints.texi:1354
2896  msgid "@code{warning} and @code{error} look at the context stack.  If the topmost context is not of type @code{CTXT_BUILTIN}, it is used to provide the call, otherwise the next context provides the call.  This means that when these functions are called from a primitive or @code{.Internal}, the imputed call will not be to primitive/@code{.Internal} but to the function calling the primitive/@code{.Internal} .  This is exactly what one wants for a @code{.Internal}, as this will give the call to the closure wrapper.  (Further, for a @code{.Internal}, the call is the argument to @code{.Internal}, and so may not correspond to any @R{} function.)  However, it is unlikely to be what is needed for a primitive."  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  msgstr ""  msgstr ""
2908    
2909  #. type: Plain text  #. type: Plain text
2910  #: R-ints.texi:1363  #: R-ints.texi:1363
2911  msgid "The upshot is that that @code{warningcall} and @code{errorcall} should normally be used for code called from a primitive, and @code{warning} and @code{error} should be used for code called from a @code{.Internal} (and necessarily from @code{.Call}, @code{.C} and so on, where the call is not passed down).  However, there are two complications.  One is that code might be called from either a primitive or a @code{.Internal}, in which case probably @code{warningcall} is more appropriate.  The other involves replacement functions, where the call was once of the form"  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  msgstr ""  msgstr ""
2921    
2922  #. type: example  #. type: example
# Line 2194  Line 2929 
2929    
2930  #. type: Plain text  #. type: Plain text
2931  #: R-ints.texi:1373  #: R-ints.texi:1373
2932  msgid "which is unpalatable to the end user.  For replacement functions there will be a suitable context at the top of the stack, so @code{warning} should be used.  (The results for @code{.Internal} replacement functions such as @code{substr<-} are not ideal.)"  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  msgstr ""  msgstr ""
2938    
2939  #. type: Plain text  #. type: Plain text
2940  #: R-ints.texi:1382  #: R-ints.texi:1382
2941  msgid "[This section is currently a preliminary draft and should not be taken as definitive.  The description assumes that @env{R_NO_METHODS_TABLES} has not been set.]"  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  msgstr ""  msgstr ""
2946    
2947  #. type: node  #. type: node
# Line 2242  Line 2984 
2984    
2985  #. type: Plain text  #. type: Plain text
2986  #: R-ints.texi:1398  #: R-ints.texi:1398
2987  msgid "S4 objects can be of any @code{SEXPTYPE}.  They are either an object of a simple type (such as an atomic vector or function) with S4 class information or of type @code{S4SXP}.  In all cases, the `S4 bit' (bit 4 of the `general purpose' field) is set, and can be tested by the macro/function @code{IS_S4_OBJECT}."  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  msgstr ""  msgstr ""
2994    
2995  #. type: Plain text  #. type: Plain text
2996  #: R-ints.texi:1407  #: R-ints.texi:1407
2997  msgid "S4 objects are created via @code{new()}@footnote{This can also create non-S4 objects, as in @code{new(\"integer\")}.} and thence via the C function @code{R_do_new_object}.  This duplicates the prototype of the class, adds a class attribute and sets the S4 bit.  All S4 class attributes should be character vectors of length one with an attribute giving (as a character string) the name of the package (or @code{.GlobalEnv}) containing the class definition.  Since S4 objects have a class attribute, the @code{OBJECT} bit is set."  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  msgstr ""  msgstr ""
3007    
3008  #. type: Plain text  #. type: Plain text
3009  #: R-ints.texi:1410  #: R-ints.texi:1410
3010  msgid "It is currently unclear what should happen if the class attribute is removed from an S4 object, or if this should be allowed."  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  msgstr ""  msgstr ""
3014    
3015  #. type: Plain text  #. type: Plain text
3016  #: R-ints.texi:1417  #: R-ints.texi:1417
3017  msgid "S4 classes are stored as @R{} objects in the environment in which they are created, with names @code{.__C__@var{classname}}: as such they are not listed by default by @code{ls}."  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  msgstr ""  msgstr ""
3022    
3023  #. type: Plain text  #. type: Plain text
3024  #: R-ints.texi:1420  #: R-ints.texi:1420
3025  msgid "The objects are S4 objects of class @code{\"classRepresentation\"} which is defined in the @pkg{methods} package."  msgid ""
3026    "The objects are S4 objects of class @code{\"classRepresentation\"} which is "
3027    "defined in the @pkg{methods} package."
3028  msgstr ""  msgstr ""
3029    
3030  #. type: Plain text  #. type: Plain text
3031  #: R-ints.texi:1427  #: R-ints.texi:1427
3032  msgid "Since these are just objects, they are subject to the normal scoping rules and can be imported and exported from namespaces like other objects.  The directives @code{importClassesFrom} and @code{exportClasses} are merely convenient ways to refer to class objects without needing to know their internal `metaname' (although @code{exportClasses} does a little sanity checking via @code{isClass})."  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  msgstr ""  msgstr ""
3040    
3041  #. type: Plain text  #. type: Plain text
3042  #: R-ints.texi:1436  #: R-ints.texi:1436
3043  msgid "Details of methods are stored in S4 objects of class @code{\"MethodsList\"}.  They have a non-syntactic name of the form @code{.__M__@var{generic}:@var{package}} for all methods defined in the current environment for the named generic derived from a specific package (which might be @code{.GlobalEnv})."  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  msgstr ""  msgstr ""
3050    
3051  #. type: Plain text  #. type: Plain text
3052  #: R-ints.texi:1441  #: R-ints.texi:1441
3053  msgid "There is also environment @code{.__T__@var{generic}:@var{package}} which has names the signatures of the methods defined, and values the corresponding method functions.  This is often referred to as a `methods table'."  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  msgstr ""  msgstr ""
3058    
3059  #. type: Plain text  #. type: Plain text
3060  #: R-ints.texi:1445  #: R-ints.texi:1445
3061  msgid "When a package without a namespace is attached these objects become visible on the search path.  @code{library} calls @code{methods:::cacheMetaData} to update the internal tables."  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  msgstr ""  msgstr ""
3066    
3067  #. type: Plain text  #. type: Plain text
3068  #: R-ints.texi:1452  #: R-ints.texi:1452
3069  msgid "During an @R{} session there is an environment associated with each non-primitive generic containing objects @code{.AllMTable}, @code{.Generic}, @code{.Methods}, @code{.MTable}, @code{.SigArgs} and @code{.SigLength}.  @code{.MTable} and @code{AllMTable} are merged methods tables containing all the methods defined directly and via inheritance respectively.  @code{.Methods} is a merged methods list."  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  msgstr ""  msgstr ""
3077    
3078  #. type: Plain text  #. type: Plain text
3079  #: R-ints.texi:1461  #: R-ints.texi:1461
3080  msgid "Exporting methods from a namespace is more complicated than exporting a class.  Note first that you do not export a method, but rather the directive @code{exportMethods} will export all the methods defined in the namespace for a specified generic: the code also adds to the list of generics any that are exported directly.  For generics which are listed via @code{exportMethods} or exported themselves, the corresponding @code{\"MethodsList\"} and environment are exported and so will appear (as hidden objects) in the package environment."  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  msgstr ""  msgstr ""
3090    
3091  #. type: Plain text  #. type: Plain text
3092  #: R-ints.texi:1464  #: R-ints.texi:1464
3093  msgid "Methods for primitives which are internally S4 generic (see below) are always exported, whether mentioned in the @file{NAMESPACE} file or not."  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  msgstr ""  msgstr ""
3097    
3098  #. type: Plain text  #. type: Plain text
3099  #: R-ints.texi:1473  #: R-ints.texi:1473
3100  msgid "Methods can be imported either via the directive @code{importMethodsFrom} or via importing a namespace by @code{import}.  Also, if a generic is imported via @code{importFrom}, its methods are also imported.  In all cases the generic will be imported if it is in the namespace, so @code{importMethodsFrom} is most appropriate for methods defined on generics in other packages.  Since methods for a generic could be imported from several different packages, the methods tables are merged."  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  msgstr ""  msgstr ""
3109    
3110  #. type: Plain text  #. type: Plain text
3111  #: R-ints.texi:1477  #: R-ints.texi:1477
3112  msgid "When a package with a namespace is attached @code{methods:::cacheMetaData} is called to update the internal tables: only the visible methods will be cached."  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  msgstr ""  msgstr ""
3117    
3118  #. type: Plain text  #. type: Plain text
3119  #: R-ints.texi:1484  #: R-ints.texi:1484
3120  msgid "This subsection does not discuss how S4 methods are chosen: see @uref{http://@/developer.@/r-project.org/howMethodsWork.pdf}."  msgid ""
3121    "This subsection does not discuss how S4 methods are chosen: see @uref{http://"
3122    "@/developer.@/r-project.org/howMethodsWork.pdf}."
3123  msgstr ""  msgstr ""
3124    
3125  #. type: Plain text  #. type: Plain text
3126  #: R-ints.texi:1499  #: R-ints.texi:1499
3127  msgid "For all but primitive functions, setting a method on an existing function that is not itself S4 generic creates a new object in the current environment which is a call to @code{standardGeneric} with the old definition as the default method.  Such S4 generics can also be created @emph{via} a call to @code{setGeneric}@footnote{although this is not recommended as it is less future-proof.} and are standard closures in the @R{} language, with environment the environment within which they are created.  With the advent of namespaces this is somewhat problematic: if @code{myfn} was previously in a package with a name space there will be two functions called @code{myfn} on the search paths, and which will be called depends on which search path is in use.  This is starkest for functions in the base namespace, where the original will be found ahead of the newly created function from any other package with a namespace."  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  msgstr ""  msgstr ""
3142    
3143  #. type: Plain text  #. type: Plain text
3144  #: R-ints.texi:1509  #: R-ints.texi:1509
3145  msgid "Primitive functions are treated quite differently, for efficiency reasons: this results in different semantics.  @code{setGeneric} is disallowed for primitive functions.  The @pkg{methods} namespace contains a list @code{.BasicFunsList} named by primitive functions: the entries are either @code{FALSE} or a standard S4 generic showing the effective definition.  When @code{setMethod} (or @code{setReplaceMethod}) is called, it either fails (if the list entry is @code{FALSE}) or a method is set on the effective generic given in the list."  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  msgstr ""  msgstr ""
3155    
3156  #. type: Plain text  #. type: Plain text
3157  #: R-ints.texi:1526  #: R-ints.texi:1526
3158  msgid "Actual dispatch of S4 methods for almost all primitives piggy-backs on the S3 dispatch mechanism, so S4 methods can only be dispatched for primitives which are internally S3 generic.  When a primitive that is internally S3 generic is called with a first argument which is an S4 object and S4 dispatch is on (that is, the @pkg{methods} namespace is loaded), @code{DispatchOrEval} calls @code{R_possible_dispatch} (defined in file @file{src/main/objects.c}).  (Members of the S3 group generics, which includes all the generic operators, are treated slightly differently: the first two arguments are checked and @code{DispatchGroup} is called.)  @code{R_possible_dispatch} first checks an internal table to see if any S4 methods are set for that generic (and S4 dispatch is currently enabled for that generic), and if so proceeds to S4 dispatch using methods stored in another internal table.  All primitives are in the base namespace, and this mechanism means that S4 methods can be set for (some) primitives and will always be used, in contrast to setting methods on non-primitives."  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  msgstr ""  msgstr ""
3175    
3176  #. type: Plain text  #. type: Plain text
3177  #: R-ints.texi:1529  #: R-ints.texi:1529
3178  msgid "The exception is @code{%*%}, which is S4 generic but not S3 generic as its C code contains a direct call to @code{R_possible_dispatch}."  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  msgstr ""  msgstr ""
3182    
3183  #. type: Plain text  #. type: Plain text
3184  #: R-ints.texi:1535  #: R-ints.texi:1535
3185  msgid "The primitive @code{as.double} is special, as @code{as.numeric} and @code{as.real} are copies of it.  The @pkg{methods} package code partly refers to generics by name and partly by function, and maps @code{as.double} and @code{as.real} to @code{as.numeric} (since that is the name used by packages exporting methods for it)."  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  msgstr ""  msgstr ""
3192    
3193  #. type: Plain text  #. type: Plain text
3194  #: R-ints.texi:1539  #: R-ints.texi:1539
3195  msgid "Some elements of the language are implemented as primitives, for example @code{@}}.  This includes the subset and subassignment `functions' and they are S4 generic, again piggybacking on S3 dispatch."  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  msgstr ""  msgstr ""
3200    
3201  #. type: Plain text  #. type: Plain text
3202  #: R-ints.texi:1546  #: R-ints.texi:1546
3203  msgid "@code{.BasicFunsList} is generated when @pkg{methods} is installed, by computing all primitives, initially disallowing methods on all and then setting generics for members of @code{.GenericArgsEnv}, the S4 group generics and a short exceptions list in file @file{BasicFunsList.R}: this currently contains the subsetting and subassignment operators and an override for @code{c}."  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  msgstr ""  msgstr ""
3211    
3212  #. type: Plain text  #. type: Plain text
3213  #: R-ints.texi:1567  #: R-ints.texi:1567
3214  msgid "@R{}'s memory allocation is almost all done via routines in file @file{src/main/memory.c}.  It is important to keep track of where memory is allocated, as the Windows port (by default) makes use of a memory allocator that differs from @code{malloc} etc as provided by MinGW.  Specifically, there are entry points @code{Rm_malloc}, @code{Rm_free}, @code{Rm_calloc} and @code{Rm_free} provided by file @file{src/gnuwin32/malloc.c}.  This was done for two reasons.  The primary motivation was performance: the allocator provided by MSVCRT @emph{via} MinGW was far too slow at handling the many small allocations that the allocation system for @code{SEXPREC}s uses.  As a side benefit, we can set a limit on the amount of allocated memory: this is useful as whereas Windows does provide virtual memory it is relatively far slower than many other @R{} platforms and so limiting @R{}'s use of swapping is highly advantageous.  The high-performance allocator is only called from @file{src/main/memory.c}, @file{src/main/regex.c}, @file{src/extra/pcre} and @file{src/extra/xdr}: note that this means that it is not used in packages."  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  msgstr ""  msgstr ""
3231    
3232  #. type: Plain text  #. type: Plain text
3233  #: R-ints.texi:1571  #: R-ints.texi:1571
3234  msgid "The rest of @R{} should where possible make use of the allocators made available by file @file{src/main/memory.c}, which are also the methods recommended in"  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  msgstr ""  msgstr ""
3239    
3240  #. type: ref{#1}  #. type: ref{#1}
# Line 2396  Line 3273 
3273    
3274  #. type: Plain text  #. type: Plain text
3275  #: R-ints.texi:1585  #: R-ints.texi:1585
3276  msgid "for use in @R{} packages, namely the use of @code{R_alloc}, @code{Calloc}, @code{Realloc} and @code{Free}.  Memory allocated by @code{R_alloc} is freed by the garbage collector once the `watermark' has been reset by calling"  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  msgstr ""  msgstr ""
3281    
3282  #. type: findex  #. type: findex
# Line 2407  Line 3287 
3287    
3288  #. type: Plain text  #. type: Plain text
3289  #: R-ints.texi:1589  #: R-ints.texi:1589
3290  msgid "@code{vmaxset}.  This is done automatically by the wrapper code calling primitives and @code{.Internal} functions (and also by the wrapper code to @code{.Call} and @code{.External}), but"  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  msgstr ""  msgstr ""
3295    
3296  #. type: findex  #. type: findex
# Line 2418  Line 3301 
3301    
3302  #. type: Plain text  #. type: Plain text
3303  #: R-ints.texi:1593  #: R-ints.texi:1593
3304  msgid "@code{vmaxget} and @code{vmaxset} can be used to reset the watermark from within internal code if the memory is only required for a short time."  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  msgstr ""  msgstr ""
3308    
3309  #. type: findex  #. type: findex
# Line 2429  Line 3314 
3314    
3315  #. type: Plain text  #. type: Plain text
3316  #: R-ints.texi:1599  #: R-ints.texi:1599
3317  msgid "All of the methods of memory allocation mentioned so far are relatively expensive.  All @R{} platforms support @code{alloca}, and in almost all cases@footnote{but apparently not on Windows.} this is managed by the compiler, allocates memory on the C stack and is very efficient."  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  msgstr ""  msgstr ""
3323    
3324  #. type: Plain text  #. type: Plain text
3325  #: R-ints.texi:1606  #: R-ints.texi:1606
3326  msgid "There are two disadvantages in using @code{alloca}.  First, it is fragile and care is needed to avoid writing (or even reading) outside the bounds of the allocation block returned.  Second, it increases the danger of overflowing the C stack.  It is suggested that it is only used for smallish allocations (up to tens of thousands of bytes), and that"  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  msgstr ""  msgstr ""
3333    
3334  #. type: findex  #. type: findex
# Line 2451  Line 3345 
3345    
3346  #. type: Plain text  #. type: Plain text
3347  #: R-ints.texi:1617  #: R-ints.texi:1617
3348  msgid "is called immediately after the allocation (as @R{}'s stack checking mechanism will warn far enough from the stack limit to allow for modest use of alloca).  (@code{do_makeunique} in file @file{src/main/unique.c} provides an example of both points.)"  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  msgstr ""  msgstr ""
3354    
3355  #. type: Plain text  #. type: Plain text
# Line 2473  Line 3371 
3371    
3372  #. type: Plain text  #. type: Plain text
3373  #: R-ints.texi:1627  #: R-ints.texi:1627
3374  msgid "to be called immediately @emph{before} trying an allocation of @code{extra} bytes."  msgid ""
3375    "to be called immediately @emph{before} trying an allocation of @code{extra} "
3376    "bytes."
3377  msgstr ""  msgstr ""
3378    
3379  #. type: Plain text  #. type: Plain text
3380  #: R-ints.texi:1633  #: R-ints.texi:1633
3381  msgid "An alternative strategy has been used for various functions which require intermediate blocks of storage of varying but usually small size, and this has been consolidated into the routines in the header file @file{src/main/RBufferUtils.h}.  This uses a structure which contains a buffer, the current size and the default size. A call to"  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  msgstr ""  msgstr ""
3388    
3389  #. type: findex  #. type: findex
# Line 2495  Line 3400 
3400    
3401  #. type: Plain text  #. type: Plain text
3402  #: R-ints.texi:1642  #: R-ints.texi:1642
3403  msgid "sets @code{buf->data} to a memory area of at least @code{blen+1} bytes.  At least the default size is used, which means that for small allocations the same buffer can be reused.  A call to"  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  msgstr ""  msgstr ""
3408    
3409  #. type: findex  #. type: findex
# Line 2512  Line 3420 
3420    
3421  #. type: Plain text  #. type: Plain text
3422  #: R-ints.texi:1647  #: R-ints.texi:1647
3423  msgid "@code{R_FreeStringBufferL} releases memory if more than the default has been allocated whereas a call to @code{R_FreeStringBuffer} frees any memory allocated."  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  msgstr ""  msgstr ""
3428    
3429  #. type: Plain text  #. type: Plain text
3430  #: R-ints.texi:1649  #: R-ints.texi:1649
3431  msgid "The @code{R_StringBuffer} structure needs to be initialized, for example by"  msgid ""
3432    "The @code{R_StringBuffer} structure needs to be initialized, for example by"
3433  msgstr ""  msgstr ""
3434    
3435  #. type: example  #. type: example
# Line 2528  Line 3440 
3440    
3441  #. type: Plain text  #. type: Plain text
3442  #: R-ints.texi:1660  #: R-ints.texi:1660
3443  msgid "which uses a default size of @code{MAXELTSIZE = 8192} bytes.  Most current uses have a static @code{R_StringBuffer} structure, which allows the (default-sized) buffer to be shared between calls to e.g.@: @code{grep} and even between functions: this will need to be changed if @R{} ever allows concurrent evaluation threads.  So the idiom is"  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  msgstr ""  msgstr ""
3450    
3451  #. type: example  #. type: example
# Line 2558  Line 3475 
3475    
3476  #. type: Plain text  #. type: Plain text
3477  #: R-ints.texi:1689  #: R-ints.texi:1689
3478  msgid "The memory used by @code{R_alloc} is allocated as @R{} vectors, of type @code{RAWSXP}.  Thus the allocation is in units of 8 bytes, and is rounded up.  A request for zero bytes currently returns @code{NULL} (but this should not be relied on).  For historical reasons, in all other cases 1 byte is added before rounding up so the allocation is always 1--8 bytes more than was asked for: again this should not be relied on."  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  msgstr ""  msgstr ""
3486    
3487  #. type: Plain text  #. type: Plain text
3488  #: R-ints.texi:1700  #: R-ints.texi:1700
3489  msgid "The vectors allocated are protected via the setting of @code{R_VStack}, as the garbage collector marks everything that can be reached from that location.  When a vector is @code{R_alloc}ated, its @code{ATTRIB} pointer is set to the current @code{R_VStack}, and @code{R_VStack} is set to the latest allocation.  Thus @code{R_VStack} is a single-linked chain of the vectors currently allocated via @code{R_alloc}.  Function @code{vmaxset} resets the location @code{R_VStack}, and should be to a value that has previously be obtained @emph{via} @code{vmaxget}: allocations after the value was obtained will no longer be protected and hence available for garbage collection."  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  msgstr ""  msgstr ""
3500    
3501  #. type: Plain text  #. type: Plain text
3502  #: R-ints.texi:1706  #: R-ints.texi:1706
3503  msgid "This section notes known use by the system of these environments: the intention is to minimize or eliminate such uses."  msgid ""
3504    "This section notes known use by the system of these environments: the "
3505    "intention is to minimize or eliminate such uses."
3506  msgstr ""  msgstr ""
3507    
3508  #. type: node  #. type: node
# Line 2603  Line 3537 
3537    
3538  #. type: Plain text  #. type: Plain text
3539  #: R-ints.texi:1724  #: R-ints.texi:1724
3540  msgid "The graphics devices system maintains two variables @code{.Device} and @code{.Devices} in the base environment: both are always set.  The variable @code{.Devices} gives a list of character vectors of the names of open devices, and @code{.Device} is the element corresponding to the currently active device.  The null device will always be open."  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  msgstr ""  msgstr ""
3547    
3548  #. type: findex  #. type: findex
# Line 2614  Line 3553 
3553    
3554  #. type: Plain text  #. type: Plain text
3555  #: R-ints.texi:1729  #: R-ints.texi:1729
3556  msgid "There appears to be a variable @code{.Options}, a pairlist giving the current options settings.  But in fact this is just a symbol with a value assigned, and so shows up as a base variable."  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  msgstr ""  msgstr ""
3561    
3562  #. type: findex  #. type: findex
# Line 2625  Line 3567 
3567    
3568  #. type: Plain text  #. type: Plain text
3569  #: R-ints.texi:1733  #: R-ints.texi:1733
3570  msgid "Similarly, the evaluator creates a symbol @code{.Last.value} which appears as a variable in the base environment."  msgid ""
3571    "Similarly, the evaluator creates a symbol @code{.Last.value} which appears "
3572    "as a variable in the base environment."
3573  msgstr ""  msgstr ""
3574    
3575  #. type: findex  #. type: findex
# Line 2642  Line 3586 
3586    
3587  #. type: Plain text  #. type: Plain text
3588  #: R-ints.texi:1738  #: R-ints.texi:1738
3589  msgid "Errors can give rise to objects @code{.Traceback} and @code{last.warning} in the base environment."  msgid ""
3590    "Errors can give rise to objects @code{.Traceback} and @code{last.warning} in "
3591    "the base environment."
3592  msgstr ""  msgstr ""
3593    
3594  #. type: cindex  #. type: cindex
# Line 2665  Line 3611 
3611    
3612  #. type: Plain text  #. type: Plain text
3613  #: R-ints.texi:1747  #: R-ints.texi:1747
3614  msgid "The seed for the random number generator is stored in object @code{.Random.seed} in the global environment."  msgid ""
3615    "The seed for the random number generator is stored in object @code{.Random."
3616    "seed} in the global environment."
3617  msgstr ""  msgstr ""
3618    
3619  #. type: findex  #. type: findex
# Line 2676  Line 3624 
3624    
3625  #. type: Plain text  #. type: Plain text
3626  #: R-ints.texi:1751  #: R-ints.texi:1751
3627  msgid "Some error handlers may give rise to objects in the global environment: for example @code{dump.frames} by default produces @code{last.dump}."  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  msgstr ""  msgstr ""
3631    
3632  #. type: findex  #. type: findex
# Line 2687  Line 3637 
3637    
3638  #. type: Plain text  #. type: Plain text
3639  #: R-ints.texi:1756  #: R-ints.texi:1756
3640  msgid "The @code{windows()} device makes use of a variable @code{.SavedPlots} to store display lists of saved plots for later display.  This is regarded as a variable created by the user."  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  msgstr ""  msgstr ""
3645    
3646  #. type: cindex  #. type: cindex
# Line 2698  Line 3651 
3651    
3652  #. type: Plain text  #. type: Plain text
3653  #: R-ints.texi:1766  #: R-ints.texi:1766
3654  msgid "@R{} makes use of a number of shared objects/DLLs stored in the @file{modules} directory.  These are parts of the code which have been chosen to be loaded `on demand' rather than linked as dynamic libraries or incorporated into the main executable/dynamic library."  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  msgstr ""  msgstr ""
3660    
3661  #. type: Plain text  #. type: Plain text
3662  #: R-ints.texi:1770  #: R-ints.texi:1770
3663  msgid "For the remaining modules the motivation has been the amount of (often optional) code they will bring in via libraries to which they are linked."  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  msgstr ""  msgstr ""
3667    
3668  #. type: code{#1}  #. type: code{#1}
# Line 2714  Line 3673 
3673    
3674  #. type: table  #. type: table
3675  #: R-ints.texi:1776  #: R-ints.texi:1776
3676  msgid "The internal HTTP and FTP clients and socket support, which link to system-specific support libraries."  msgid ""
3677    "The internal HTTP and FTP clients and socket support, which link to system-"
3678    "specific support libraries."
3679  msgstr ""  msgstr ""
3680    
3681  #. type: code{#1}  #. type: code{#1}
# Line 2725  Line 3686 
3686    
3687  #. type: table  #. type: table
3688  #: R-ints.texi:1780  #: R-ints.texi:1780
3689  msgid "The code which makes use of the LAPACK library, and is linked to @file{libRlapack} or an external LAPACK library."  msgid ""
3690    "The code which makes use of the LAPACK library, and is linked to "
3691    "@file{libRlapack} or an external LAPACK library."
3692  msgstr ""  msgstr ""
3693    
3694  #. type: code{#1}  #. type: code{#1}
# Line 2747  Line 3710 
3710    
3711  #. type: table  #. type: table
3712  #: R-ints.texi:1789  #: R-ints.texi:1789
3713  msgid "(Unix-alikes only.)  The @code{X11()}, @code{jpeg()}, @code{png()} and @code{tiff()} devices. These are optional, and links to some or all of the @code{X11}, @code{pango}, @code{cairo}, @code{jpeg}, @code{libpng} and @code{libtiff} libraries."  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  msgstr ""  msgstr ""
3719    
3720  #. type: file{#1}  #. type: file{#1}
# Line 2758  Line 3725 
3725    
3726  #. type: table  #. type: table
3727  #: R-ints.texi:1794  #: R-ints.texi:1794
3728  msgid "(Windows only.)  An alternative version of the internet access routines, compiled against Internet Explorer internals (and so loads @file{wininet.dll} and @file{wsock32.dll})."  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  msgstr ""  msgstr ""
3733    
3734  #. type: cindex  #. type: cindex
# Line 2792  Line 3762 
3762    
3763  #. type: ifset  #. type: ifset
3764  #: R-ints.texi:1811  #: R-ints.texi:1811
3765  msgid "@ref{Controlling visibility, , Controlling visibility, R-exts, Writing R Extensions},"  msgid ""
3766    "@ref{Controlling visibility, , Controlling visibility, R-exts, Writing R "
3767    "Extensions},"
3768  msgstr ""  msgstr ""
3769    
3770  #. type: ifclear  #. type: ifclear
# Line 2802  Line 3774 
3774    
3775  #. type: Plain text  #. type: Plain text
3776  #: R-ints.texi:1818  #: R-ints.texi:1818
3777  msgid "C entry points not needed outside the main @R{} executable/dynamic library (and in particular in no package nor module) should be prefixed by @code{attribute_hidden}."  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  msgstr ""  msgstr ""
3782    
3783  #. type: findex  #. type: findex
# Line 2813  Line 3788 
3788    
3789  #. type: Plain text  #. type: Plain text
3790  #: R-ints.texi:1826  #: R-ints.texi:1826
3791  msgid "Minimizing the visibility of symbols in the @R{} dynamic library will speed up linking to it (which packages will do) and reduce the possibility of linking to the wrong entry points of the same name.  In addition, on some platforms reducing the number of entry points allows more efficient versions of PIC to be used: somewhat over half the entry points are hidden.  A convenient way to hide variables (as distinct from functions) is to declare them @code{extern0} in header file @file{Defn.h}."  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  msgstr ""  msgstr ""
3800    
3801  #. type: Plain text  #. type: Plain text
3802  #: R-ints.texi:1832  #: R-ints.texi:1832
3803  msgid "The visibility mechanism used is only available with some compilers and platforms, and in particular not on Windows, where an alternative mechanism is used.  Entry points will not be made available in @file{R.dll} if they are listed in the file @file{src/gnuwin32/Rdll.hide}."  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  msgstr ""  msgstr ""
3809    
3810  #. type: findex  #. type: findex
# Line 2829  Line 3815 
3815    
3816  #. type: Plain text  #. type: Plain text
3817  #: R-ints.texi:1841  #: R-ints.texi:1841
3818  msgid "Entries in that file start with a space and must be strictly in alphabetic order in the C locale (use @command{sort} on the file to ensure this if you change it).  It is possible to hide Fortran as well as C entry points via this file: the former are lower-cased and have an underline as suffix, and the suffixed name should be included in the file.  Some entry points exist only on Windows or need to be visible only on Windows, and some notes on these are provided in file @file{src/gnuwin32/Maintainters.notes}."  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  msgstr ""  msgstr ""
3827    
3828  #. type: Plain text  #. type: Plain text
3829  #: R-ints.texi:1851  #: R-ints.texi:1851
3830  msgid "Because of the advantages of reducing the number of visible entry points, they should be declared @code{attribute_hidden} where possible.  Note that this only has an effect on a shared-R-library build, and so care is needed not to hide entry points that are legitimately used by packages.  So it is best if the decision on visibility is made when a new entry point is created, including the decision if it should be included in header file @file{Rinternals.h}.  A list of the visible entry points on shared-R-library build on a reasonably standard Unix-alike can be made by something like"  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  msgstr ""  msgstr ""
3840    
3841  #. type: example  #. type: example
# Line 2845  Line 3846 
3846    
3847  #. type: Plain text  #. type: Plain text
3848  #: R-ints.texi:1866  #: R-ints.texi:1866
3849  msgid "Windows is unique in that it conventionally treats importing variables differently from functions: variables that are imported from a DLL need to be specified by a prefix (often @samp{_imp_}) when being linked to (`imported') but not when being linked from (`exported').  The details depend on the compiler system, and have changed for MinGW during the lifetime of that port.  They are in the main hidden behind some macros defined in header file @file{R_ext/libextern.h}."  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  msgstr ""  msgstr ""
3858    
3859  #. type: Plain text  #. type: Plain text
3860  #: R-ints.texi:1872  #: R-ints.texi:1872
3861  msgid "A (non-function) variable in the main @R{} sources that needs to be referred to outside @file{R.dll} (in a package, module or another DLL such as @file{Rgraphapp.dll}) should be declared with prefix @code{LibExtern}.  The main use is in @file{Rinternals.h}, but it needs to be considered for any public header and also @file{Defn.h}."  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  msgstr ""  msgstr ""
3868    
3869  #. type: Plain text  #. type: Plain text
3870  #: R-ints.texi:1879  #: R-ints.texi:1879
3871  msgid "It would nowadays be possible to make use of the `auto-import' feature of the MinGW port of @command{ld} to fix up imports from DLLs (and if @R{} is built for the Cygwin platform this is what happens).  However, this was not possible when the MinGW build of @R{} was first constructed in ca 1998, allows less control of visibility and would not work for other Windows compiler suites."  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  msgstr ""  msgstr ""
3879    
3880  #. type: Plain text  #. type: Plain text
3881  #: R-ints.texi:1882  #: R-ints.texi:1882
3882  msgid "It is only possible to check if this has been handled correctly by compiling the @R{} sources on Windows."  msgid ""
3883    "It is only possible to check if this has been handled correctly by compiling "
3884    "the @R{} sources on Windows."
3885  msgstr ""  msgstr ""
3886    
3887  #. type: Plain text  #. type: Plain text
3888  #: R-ints.texi:1891  #: R-ints.texi:1891
3889  msgid "Lazy loading is always used for code in packages but is optional (selected by the package maintainer) for datasets in packages.  When a package/namespace which uses it is loaded, the package/namespace environment is populated with promises for all the named objects: when these promises are evaluated they load the actual code from a database."  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  msgstr ""  msgstr ""
3896    
3897  #. type: Plain text  #. type: Plain text
3898  #: R-ints.texi:1902  #: R-ints.texi:1902
3899  msgid "There are separate databases for code and data, stored in the @file{R} and @file{data} subdirectories.  The database consists of two files, @file{@var{name}.rdb} and @file{@var{name}.rdx}.  The @file{.rdb} file is a concatenation of serialized objects, and the @file{.rdx} file contains an index.  The objects are stored in (usually) a @command{gzip}-compressed format with a 4-byte header giving the uncompressed serialized length (in XDR, that is big-endian, byte order)  and read by a call to the primitive @code{lazyLoadDBfetch}.  (Note that this makes lazy-loading unsuitable for really large objects: the unserialized length of an @R{} object can exceed 4GB.)"  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  msgstr ""  msgstr ""
3911    
3912  #. type: Plain text  #. type: Plain text
3913  #: R-ints.texi:1917  #: R-ints.texi:1917
3914  msgid "The index or `map' file @file{@var{name}.rdx} is a compressed serialized @R{} object to be read by @code{readRDS}.  It is a list with three elements @code{variables}, @code{references} and @code{compressed}.  The first two are named lists of integer vectors of length 2 giving the offset and length of the serialized object in the @file{@var{name}.rdb} file.  Element @code{variables} has an entry for each named object: @code{references} serializes a temporary environment used when named environments are added to the database.  @code{compressed} is a logical indicating if the serialized objects were compressed: compression is always used nowadays. We later added the values @code{compressed = 2} and @code{3} for @command{bzip2} and @command{xz} compression (with the possibility of future expansion to other methods): these formats add a fifth byte to the header for the type of compression, and store serialized objects uncompressed if compression expands them."  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  msgstr ""  msgstr ""
3930    
3931  #. type: Plain text  #. type: Plain text
3932  #: R-ints.texi:1922  #: R-ints.texi:1922
3933  msgid "The loader for a lazy-load database of code or data is function @code{lazyLoad} in the @pkg{base} package, but note that there is a separate copy to load @pkg{base} itself in file @file{R_HOME/base/R/base}."  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  msgstr ""  msgstr ""
3938    
3939  #. type: Plain text  #. type: Plain text
3940  #: R-ints.texi:1928  #: R-ints.texi:1928
3941  msgid "Lazy-load databases are created by the code in @file{src/library/tools/R/makeLazyLoad.R}: the main tool is the unexported function @code{makeLazyLoadDB} and the insertion of database entries is done by calls to @code{.Call(\"R_lazyLoadDBinsertValue\", ...)}."  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  msgstr ""  msgstr ""
3947    
3948  #. type: Plain text  #. type: Plain text
3949  #: R-ints.texi:1932  #: R-ints.texi:1932
3950  msgid "Lazy-load databases of less than 10MB are cached in memory at first use: this was found necessary when using file systems with high latency (removable devices and network-mounted file systems on Windows)."  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  msgstr ""  msgstr ""
3955    
3956  #. type: Plain text  #. type: Plain text
3957  #: R-ints.texi:1942  #: R-ints.texi:1942
3958  msgid "Lazy-load databases are loaded into the exports for a package, but not into the namespace environment itself.  Thus they are visible when the package is @emph{attached}, and also @emph{via} the @code{::} operator.  This was a deliberate design decision, as packages mostly make datasets available for use by the end user (or other packages), and they should not be found preferentially from functions in the package, surprising users who expected the normal search path to be used.  (There is an alternative mechanism, @file{sysdata.rda}, for `system datasets' that are intended primarily to be used within the package.)"  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  msgstr ""  msgstr ""
3969    
3970  #. type: Plain text  #. type: Plain text
3971  #: R-ints.texi:1946  #: R-ints.texi:1946
3972  msgid "The same database mechanism is used to store parsed @file{Rd} files.  One or all of the parsed objects is fetched by a call to @code{tools:::fetchRdDB}."  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  msgstr ""  msgstr ""
3976    
3977  #. type: chapter  #. type: chapter
# Line 2923  Line 3994 
3994    
3995  #. type: Plain text  #. type: Plain text
3996  #: R-ints.texi:1964  #: R-ints.texi:1964
3997  msgid "C code compiled into @R{} at build time can be called directly in what are termed @emph{primitives} or via the @code{.Internal} interface, which is very similar to the @code{.External} interface except in syntax.  More precisely, @R{} maintains a table of @R{} function names and corresponding C functions to call, which by convention all start with @samp{do_} and return a @code{SEXP}.  This table (@code{R_FunTab} in file @file{src/main/names.c}) also specifies how many arguments to a function are required or allowed, whether or not the arguments are to be evaluated before calling, and whether the function is `internal' in the sense that it must be accessed via the @code{.Internal} interface, or directly accessible in which case it is printed in @R{} as @code{.Primitive}."  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  msgstr ""  msgstr ""
4010    
4011  #. type: Plain text  #. type: Plain text
4012  #: R-ints.texi:1968  #: R-ints.texi:1968
4013  msgid "Functions using @code{.Internal()} wrapped in a closure are in general preferred as this ensures standard handling of named and default arguments.  For example, @code{grep} is defined as"  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  msgstr ""  msgstr ""
4018    
4019  #. type: group  #. type: group
# Line 2948  Line 4033 
4033    
4034  #. type: Plain text  #. type: Plain text
4035  #: R-ints.texi:1984  #: R-ints.texi:1984
4036  msgid "and the use of @code{as.character} allows methods to be dispatched (for example, for factors)."  msgid ""
4037    "and the use of @code{as.character} allows methods to be dispatched (for "
4038    "example, for factors)."
4039  msgstr ""  msgstr ""
4040    
4041  #. type: Plain text  #. type: Plain text
4042  #: R-ints.texi:1997  #: R-ints.texi:1997
4043  msgid "However, for reasons of convenience and also efficiency (as there is some overhead in using the @code{.Internal} interface wrapped in a function closure), the primitive functions are exceptions that can be accessed directly.  And of course, primitive functions are needed for basic operations---for example @code{.Internal} is itself a primitive.  Note that primitive functions make no use of @R{} code, and hence are very different from the usual interpreted functions.  In particular, @code{formals} and @code{body} return @code{NULL} for such objects, and argument matching can be handled differently.  For some primitives (including @code{call}, @code{switch}, @code{.C} and @code{.subset})  positional matching is important to avoid partial matching of the first argument."  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  msgstr ""  msgstr ""
4056    
4057  #. type: Plain text  #. type: Plain text
4058  #: R-ints.texi:2000  #: R-ints.texi:2000
4059  msgid "The list of primitive functions is subject to change; currently, it includes the following."  msgid ""
4060    "The list of primitive functions is subject to change; currently, it includes "
4061    "the following."
4062  msgstr ""  msgstr ""
4063    
4064  #. type: enumerate  #. type: enumerate
4065  #: R-ints.texi:2006  #: R-ints.texi:2006
4066  msgid "``Special functions'' which really are @emph{language} elements, but implemented as primitive functions:"  msgid ""
4067    "``Special functions'' which really are @emph{language} elements, but "
4068    "implemented as primitive functions:"
4069  msgstr ""  msgstr ""
4070    
4071  #. type: group  #. type: group
# Line 2976  Line 4078 
4078    
4079  #. type: enumerate  #. type: enumerate
4080  #: R-ints.texi:2018  #: R-ints.texi:2018
4081  msgid "Language elements and basic @emph{operator}s (i.e., functions usually @emph{not} called as @code{foo(a, b, ...)}) for subsetting, assignment, arithmetic, comparison and logic:"  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  msgstr ""  msgstr ""
4086    
4087  #. type: group  #. type: group
# Line 2999  Line 4104 
4104    
4105  #. type: enumerate  #. type: enumerate
4106  #: R-ints.texi:2033  #: R-ints.texi:2033
4107  msgid "When the arithmetic, comparison and logical operators are called as functions, any argument names are discarded so positional matching is used."  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  msgstr ""  msgstr ""
4111    
4112  #. type: enumerate  #. type: enumerate
4113  #: R-ints.texi:2037  #: R-ints.texi:2037
4114  msgid "``Low level'' 0-- and 1--argument functions which belong to one of the following groups of functions:"  msgid ""
4115    "``Low level'' 0-- and 1--argument functions which belong to one of the "
4116    "following groups of functions:"
4117  msgstr ""  msgstr ""
4118    
4119  #. type: enumerate  #. type: enumerate
# Line 3053  Line 4162 
4162    
4163  #. type: enumerate  #. type: enumerate
4164  #: R-ints.texi:2073  #: R-ints.texi:2073
4165  msgid "@code{log} is a primitive function of one or two arguments with named argument matching."  msgid ""
4166    "@code{log} is a primitive function of one or two arguments with named "
4167    "argument matching."
4168  msgstr ""  msgstr ""
4169    
4170  #. type: enumerate  #. type: enumerate
4171  #: R-ints.texi:2077  #: R-ints.texi:2077
4172  msgid "@code{trunc} is a difficult case: it is a primitive that can have one or more arguments: the default method handled in the primitive has only one."  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  msgstr ""  msgstr ""
4176    
4177  #. type: enumerate  #. type: enumerate
4178  #: R-ints.texi:2081  #: R-ints.texi:2081
4179  msgid "Functions rarely used outside of ``programming'' (i.e., mostly used inside other functions), such as"  msgid ""
4180    "Functions rarely used outside of ``programming'' (i.e., mostly used inside "
4181    "other functions), such as"
4182  msgstr ""  msgstr ""
4183    
4184  #. type: group  #. type: group
# Line 3119  Line 4234 
4234    
4235  #. type: enumerate  #. type: enumerate
4236  #: R-ints.texi:2136  #: R-ints.texi:2136
4237  msgid "Note that optimizing @code{NAMED = 1} is only effective within a primitive (as the closure wrapper of a @code{.Internal} will set @code{NAMED = 2} when the promise to the argument is evaluated) and hence replacement functions should where possible be primitive to avoid copying (at least in their default methods)."  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  msgstr ""  msgstr ""
4244    
4245  #. type: enumerate  #. type: enumerate
# Line 3169  Line 4289 
4289    
4290  #. type: Plain text  #. type: Plain text
4291  #: R-ints.texi:2179  #: R-ints.texi:2179
4292  msgid "intentionally use positional matching, and need to do so to avoid partial matching to their first argument.  They do check that the first argument is unnamed or for the first two, partially matches the formal argument name.  On the other hand,"  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  msgstr ""  msgstr ""
4298    
4299  #. type: group  #. type: group
# Line 3187  Line 4311 
4311    
4312  #. type: Plain text  #. type: Plain text
4313  #: R-ints.texi:2194  #: R-ints.texi:2194
4314  msgid "All the one-argument primitives check that if they are called with a named argument that this (partially) matches the name given in the documentation: this is also done for replacement functions with one argument plus @code{value}."  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  msgstr ""  msgstr ""
4320    
4321  #. type: Plain text  #. type: Plain text
4322  #: R-ints.texi:2199  #: R-ints.texi:2199
4323  msgid "The net effect is that argument matching for primitives intended for end-user use @emph{as functions} is done in the same way as for interpreted functions except for the six exceptions where positional matching is required."  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  msgstr ""  msgstr ""
4329    
4330  #. type: node  #. type: node
# Line 3235  Line 4367 
4367    
4368  #. type: Plain text  #. type: Plain text
4369  #: R-ints.texi:2218  #: R-ints.texi:2218
4370  msgid "A small number of primitives are @emph{specials} rather than @emph{builtins}, that is they are entered with unevaluated arguments.  This is clearly necessary for the language constructs and the assignment operators, as well as for @code{&&} and @code{||} which conditionally evaluate their second argument, and @code{~}, @code{.Internal}, @code{call}, @code{expression}, @code{missing}, @code{on.exit}, @code{quote} and @code{substitute} which do not evaluate some of their arguments."  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  msgstr ""  msgstr ""
4379    
4380  #. type: Plain text  #. type: Plain text
4381  #: R-ints.texi:2221  #: R-ints.texi:2221
4382  msgid "@code{rep} and @code{seq.int} are special as they evaluate some of their arguments conditional on which are non-missing."  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  msgstr ""  msgstr ""
4386    
4387  #. type: Plain text  #. type: Plain text
4388  #: R-ints.texi:2224  #: R-ints.texi:2224
4389  msgid "@code{log}, @code{round} and @code{signif} are special to allow default values to be given to missing arguments."  msgid ""
4390    "@code{log}, @code{round} and @code{signif} are special to allow default "
4391    "values to be given to missing arguments."
4392  msgstr ""  msgstr ""
4393    
4394  #. type: Plain text  #. type: Plain text
4395  #: R-ints.texi:2229  #: R-ints.texi:2229
4396  msgid "The subsetting, subassignment and @code{@@} operators are all special.  (For both extraction and replacement forms, @code{$} and @code{@@} take a symbol argument, and @code{[} and @code{[[} allow missing arguments.)"  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  msgstr ""  msgstr ""
4401    
4402  #. type: Plain text  #. type: Plain text
4403  #: R-ints.texi:2232  #: R-ints.texi:2232
4404  msgid "@code{UseMethod} is special to avoid the additional contexts added to calls to builtins."  msgid ""
4405    "@code{UseMethod} is special to avoid the additional contexts added to calls "
4406    "to builtins."
4407  msgstr ""  msgstr ""
4408    
4409  #. type: Plain text  #. type: Plain text
4410  #: R-ints.texi:2240  #: R-ints.texi:2240
4411  msgid "There are also special @code{.Internal} functions: @code{NextMethod}, @code{Recall}, @code{withVisible}, @code{cbind}, @code{rbind} (to allow for the @code{deparse.level} argument), @code{eapply}, @code{lapply} and @code{vapply}."  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  msgstr ""  msgstr ""
4417    
4418  #. type: Plain text  #. type: Plain text
4419  #: R-ints.texi:2253  #: R-ints.texi:2253
4420  msgid "Prototypes are available for the primitive functions and operators, and these are used for printing, @code{args} and package checking (e.g.@: by @code{tools::checkS3methods} and by package @CRANpkg{codetools}).  There are two environments in the @pkg{base} package (and namespace), @samp{.GenericArgsEnv} for those primitives which are internal S3 generics, and @samp{.ArgsEnv} for the rest.  Those environments contain closures with the same names as the primitives, formal arguments derived (manually) from the help pages, a body which is a suitable call to @code{UseMethod} or @code{NULL} and environment the base namespace."  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  msgstr ""  msgstr ""
4431    
4432  #. type: Plain text  #. type: Plain text
4433  #: R-ints.texi:2257  #: R-ints.texi:2257
4434  msgid "The C code for @code{print.default} and @code{args} uses the closures in these environments in preference to the definitions in base (as primitives)."  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  msgstr ""  msgstr ""
4438    
4439  #. type: Plain text  #. type: Plain text
4440  #: R-ints.texi:2262  #: R-ints.texi:2262
4441  msgid "The QC function @code{undoc} checks that all the functions prototyped in these environments are currently primitive, and that the primitives not included are better thought of as language elements (at the time of writing"  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  msgstr ""  msgstr ""
4446    
4447  #. type: example  #. type: example
# Line 3288  Line 4454 
4454    
4455  #. type: Plain text  #. type: Plain text
4456  #: R-ints.texi:2272  #: R-ints.texi:2272
4457  msgid ").  One could argue about @code{~}, but it is known to the parser and has semantics quite unlike a normal function.  And @code{:} is documented with different argument names in its two meanings.)"  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  msgstr ""  msgstr ""
4462    
4463  #. type: Plain text  #. type: Plain text
4464  #: R-ints.texi:2291  #: R-ints.texi:2291
4465  msgid "The QC functions @code{codoc} and @code{checkS3methods} also make use of these environments (effectively placing them in front of base in the search path), and hence the formals of the functions they contain are checked against the help pages by @code{codoc}.  However, there are two problems with the generic primitives.  The first is that many of the operators are part of the S3 group generic @code{Ops} and that defines their arguments to be @code{e1} and @code{e2}: although it would be very unusual, an operator could be called as e.g.@: @code{\"+\"(e1=a, e2=b)} and if method dispatch occurred to a closure, there would be an argument name mismatch.  So the definitions in environment @code{.GenericArgsEnv} have to use argument names @code{e1} and @code{e2} even though the traditional documentation is in terms of @code{x} and @code{y}: @code{codoc} makes the appropriate adjustment via @code{tools:::.make_S3_primitive_generic_env}.  The second discrepancy is with the @code{Math} group generics, where the group generic is defined with argument list @code{(x, ...)}, but most of the members only allow one argument when used as the default method (and @code{round} and @code{signif} allow two as default methods): again fix-ups are used."  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  msgstr ""  msgstr ""
4484    
4485  #. type: Plain text  #. type: Plain text
4486  #: R-ints.texi:2299  #: R-ints.texi:2299
4487  msgid "Those primitives which are in @code{.GenericArgsEnv} are checked (via @file{tests/primitives.R}) to be generic @emph{via} defining methods for them, and a check is made that the remaining primitives are probably not generic, by setting a method and checking it is not dispatched to (but this can fail for other reasons).  However, there is no certain way to know that if other @code{.Internal} or primitive functions are not internally generic except by reading the source code."  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  msgstr ""  msgstr ""
4496    
4497  #. type: Plain text  #. type: Plain text
4498  #: R-ints.texi:2306  #: R-ints.texi:2306
4499  msgid "[For R-core use: reverse this procedure to remove a primitive.  Most commonly this is done by changing a @code{.Internal} to a primitive or @emph{vice versa}.]"  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  msgstr ""  msgstr ""
4504    
4505  #. type: Plain text  #. type: Plain text
4506  #: R-ints.texi:2310  #: R-ints.texi:2310
4507  msgid "Primitives are listed in the table @code{R_FunTab} in @file{src/main/names.c}: primitives have @samp{Y = 0} in the @samp{eval} field."  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  msgstr ""  msgstr ""
4511    
4512  #. type: Plain text  #. type: Plain text
4513  #: R-ints.texi:2314  #: R-ints.texi:2314
4514  msgid "There needs to be an @samp{\\alias} entry in a help file in the @pkg{base} package, and the primitive needs to be added to one of the lists at the start of this section."  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  msgstr ""  msgstr ""
4519    
4520  #. type: Plain text  #. type: Plain text
4521  #: R-ints.texi:2320  #: R-ints.texi:2320
4522  msgid "Some primitives are regarded as language elements (the current ones are listed above).  These need to be added to two lists of exceptions, @code{langElts} in @code{undoc()} (in file @file{src/library/tools/R/QC.R}) and @code{lang_elements} in @file{tests/primitives.R}."  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  msgstr ""  msgstr ""
4528    
4529  #. type: Plain text  #. type: Plain text
4530  #: R-ints.texi:2329  #: R-ints.texi:2329
4531  msgid "All other primitives are regarded as functions and should be listed in one of the environments defined in @file{src/library/base/R/zzz.R}, either @code{.ArgsEnv} or @code{.GenericArgsEnv}: internal generics also need to be listed in the character vector @code{.S3PrimitiveGenerics}.  Note too the discussion about argument matching above: if you add a primitive function with more than one argument by converting a @code{.Internal} you need to add argument matching to the C code, and for those with a single argument, add argument-name checking."  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  msgstr ""  msgstr ""
4541    
4542  #. type: Plain text  #. type: Plain text
4543  #: R-ints.texi:2332  #: R-ints.texi:2332
4544  msgid "Do ensure that @command{make check-devel} has been run: that tests most of these requirements."  msgid ""
4545    "Do ensure that @command{make check-devel} has been run: that tests most of "
4546    "these requirements."
4547  msgstr ""  msgstr ""
4548    
4549  #. type: Plain text  #. type: Plain text
4550  #: R-ints.texi:2338  #: R-ints.texi:2338
4551  msgid "The process of marking messages (errors, warnings etc) for translation in an @R{} package is described in"  msgid ""
4552    "The process of marking messages (errors, warnings etc) for translation in an "
4553    "@R{} package is described in"
4554  msgstr ""  msgstr ""
4555    
4556  #. type: ifset  #. type: ifset
4557  #: R-ints.texi:2340  #: R-ints.texi:2340
4558  msgid "@ref{Internationalization, , Internationalization, R-exts, Writing R Extensions},"  msgid ""
4559    "@ref{Internationalization, , Internationalization, R-exts, Writing R "
4560    "Extensions},"
4561  msgstr ""  msgstr ""
4562    
4563  #. type: ifclear  #. type: ifclear
# Line 3348  Line 4567 
4567    
4568  #. type: Plain text  #. type: Plain text
4569  #: R-ints.texi:2347  #: R-ints.texi:2347
4570  msgid "and the standard packages included with @R{} have (with an exception in @pkg{grDevices} for the menus of the @code{windows()} device) been internationalized in the same way as other packages."  msgid ""
4571    "and the standard packages included with @R{} have (with an exception in "
4572    "@pkg{grDevices} for the menus of the @code{windows()} device) been "
4573    "internationalized in the same way as other packages."
4574  msgstr ""  msgstr ""
4575    
4576  #. type: node  #. type: node
# Line 3401  Line 4623 
4623    
4624  #. type: Plain text  #. type: Plain text
4625  #: R-ints.texi:2366  #: R-ints.texi:2366
4626  msgid "Internationalization for @R{} code is done in exactly the same way as for extension packages.  As all standard packages which have @R{} code also have a namespace, it is never necessary to specify @code{domain}, but for efficiency calls to @code{message}, @code{warning} and @code{stop} should include @code{domain = NA} when the message is constructed @emph{via} @code{gettextf}, @code{gettext} or @code{ngettext}."  msgid ""
4627    "Internationalization for @R{} code is done in exactly the same way as for "
4628    "extension packages.  As all standard packages which have @R{} code also have "
4629    "a namespace, it is never necessary to specify @code{domain}, but for "
4630    "efficiency calls to @code{message}, @code{warning} and @code{stop} should "
4631    "include @code{domain = NA} when the message is constructed @emph{via} "
4632    "@code{gettextf}, @code{gettext} or @code{ngettext}."
4633  msgstr ""  msgstr ""
4634    
4635  #. type: Plain text  #. type: Plain text
4636  #: R-ints.texi:2372  #: R-ints.texi:2372
4637  msgid "For each package, the extracted messages and translation sources are stored under package directory @file{po} in the source package, and compiled translations under @file{inst/po} for installation to package directory @file{po} in the installed package.  This also applies to C code in packages."  msgid ""
4638    "For each package, the extracted messages and translation sources are stored "
4639    "under package directory @file{po} in the source package, and compiled "
4640    "translations under @file{inst/po} for installation to package directory "
4641    "@file{po} in the installed package.  This also applies to C code in packages."
4642  msgstr ""  msgstr ""
4643    
4644  #. type: Plain text  #. type: Plain text
4645  #: R-ints.texi:2381  #: R-ints.texi:2381
4646  msgid "The main C code (e.g.@: that in files @file{src/*/*.c} and in the modules) is where @R{} is closest to the sort of application for which @samp{gettext} was written.  Messages in the main C code are in domain @code{R} and stored in the top-level directory @file{po} with compiled translations under @file{share/locale}."  msgid ""
4647    "The main C code (e.g.@: that in files @file{src/*/*.c} and in the modules) "
4648    "is where @R{} is closest to the sort of application for which @samp{gettext} "
4649    "was written.  Messages in the main C code are in domain @code{R} and stored "
4650    "in the top-level directory @file{po} with compiled translations under "
4651    "@file{share/locale}."
4652  msgstr ""  msgstr ""
4653    
4654  #. type: Plain text  #. type: Plain text
4655  #: R-ints.texi:2384  #: R-ints.texi:2384
4656  msgid "The list of files covered by the @R{} domain is specified in file @file{po/POTFILES.in}."  msgid ""
4657    "The list of files covered by the @R{} domain is specified in file @file{po/"
4658    "POTFILES.in}."
4659  msgstr ""  msgstr ""
4660    
4661  #. type: Plain text  #. type: Plain text
4662  #: R-ints.texi:2390  #: R-ints.texi:2390
4663  msgid "The normal way to mark messages for translation is via @code{_(\"msg\")} just as for packages.  However, sometimes one needs to mark passages for translation without wanting them translated at the time, for example when declaring string constants.  This is the purpose of the @code{N_} macro, for example"  msgid ""
4664    "The normal way to mark messages for translation is via @code{_(\"msg\")} "
4665    "just as for packages.  However, sometimes one needs to mark passages for "
4666    "translation without wanting them translated at the time, for example when "
4667    "declaring string constants.  This is the purpose of the @code{N_} macro, for "
4668    "example"
4669  msgstr ""  msgstr ""
4670    
4671  #. type: example  #. type: example
# Line 3453  Line 4697 
4697    
4698  #. type: Plain text  #. type: Plain text
4699  #: R-ints.texi:2413  #: R-ints.texi:2413
4700  msgid "may be used as a wrapper for @code{ngettext}: however in some cases the preferred approach has been to conditionalize (on @code{ENABLE_NLS}) code using @code{ngettext}."  msgid ""
4701    "may be used as a wrapper for @code{ngettext}: however in some cases the "
4702    "preferred approach has been to conditionalize (on @code{ENABLE_NLS}) code "
4703    "using @code{ngettext}."
4704  msgstr ""  msgstr ""
4705    
4706  #. type: Plain text  #. type: Plain text
4707  #: R-ints.texi:2417  #: R-ints.texi:2417
4708  msgid "The macro @code{_(\"msg\")} can safely be used in directory @file{src/appl}; the header for standalone @samp{nmath} skips possible translation.  (This does not apply to @code{N_} or @code{P_})."  msgid ""
4709    "The macro @code{_(\"msg\")} can safely be used in directory @file{src/appl}; "
4710    "the header for standalone @samp{nmath} skips possible translation.  (This "
4711    "does not apply to @code{N_} or @code{P_})."
4712  msgstr ""  msgstr ""
4713    
4714  #. type: Plain text  #. type: Plain text
4715  #: R-ints.texi:2424  #: R-ints.texi:2424
4716  msgid "Messages for the Windows GUI are in a separate domain @samp{RGui}.  This was done for two reasons:"  msgid ""
4717    "Messages for the Windows GUI are in a separate domain @samp{RGui}.  This was "
4718    "done for two reasons:"
4719  msgstr ""  msgstr ""
4720    
4721  #. type: itemize  #. type: itemize
4722  #: R-ints.texi:2429  #: R-ints.texi:2429
4723  msgid "The translators for the Windows version of @R{} might be separate from those for the rest of @R{} (familiarity with the GUI helps), and"  msgid ""
4724    "The translators for the Windows version of @R{} might be separate from those "
4725    "for the rest of @R{} (familiarity with the GUI helps), and"
4726  msgstr ""  msgstr ""
4727    
4728  #. type: itemize  #. type: itemize
4729  #: R-ints.texi:2435  #: R-ints.texi:2435
4730  msgid "Messages for Windows are most naturally handled in the native charset for the language, and in the case of CJK languages the charset is Windows-specific.  (It transpires that as the @code{iconv} we ported works well under Windows, this is less important than anticipated.)"  msgid ""
4731    "Messages for Windows are most naturally handled in the native charset for "
4732    "the language, and in the case of CJK languages the charset is Windows-"
4733    "specific.  (It transpires that as the @code{iconv} we ported works well "
4734    "under Windows, this is less important than anticipated.)"
4735  msgstr ""  msgstr ""
4736    
4737  #. type: Plain text  #. type: Plain text
4738  #: R-ints.texi:2444  #: R-ints.texi:2444
4739  msgid "Messages for the @samp{RGui} domain are marked by @code{G_(\"msg\")}, a macro that is defined in header file @file{src/gnuwin32/win-nls.h}.  The list of files that are considered is hardcoded in the @code{RGui.pot-update} target of file @file{po/Makefile.in.in}: note that this includes @file{devWindows.c} as the menus on the @code{windows} device are considered to be part of the GUI.  (There is also @code{GN_(\"msg\")}, the analogue of @code{N_(\"msg\")}.)"  msgid ""
4740    "Messages for the @samp{RGui} domain are marked by @code{G_(\"msg\")}, a "
4741    "macro that is defined in header file @file{src/gnuwin32/win-nls.h}.  The "
4742    "list of files that are considered is hardcoded in the @code{RGui.pot-update} "
4743    "target of file @file{po/Makefile.in.in}: note that this includes "
4744    "@file{devWindows.c} as the menus on the @code{windows} device are considered "
4745    "to be part of the GUI.  (There is also @code{GN_(\"msg\")}, the analogue of "
4746    "@code{N_(\"msg\")}.)"
4747  msgstr ""  msgstr ""
4748    
4749  #. type: Plain text  #. type: Plain text
4750  #: R-ints.texi:2447  #: R-ints.texi:2447
4751  msgid "The template and message catalogs for the @samp{RGui} domain are in the top-level @file{po} directory."  msgid ""
4752    "The template and message catalogs for the @samp{RGui} domain are in the top-"
4753    "level @file{po} directory."
4754  msgstr ""  msgstr ""
4755    
4756  #. type: Plain text  #. type: Plain text
4757  #: R-ints.texi:2454  #: R-ints.texi:2454
4758  msgid "This is handled separately: see @uref{http://developer.r-project.org/Translations.html}."  msgid ""
4759    "This is handled separately: see @uref{http://developer.r-project.org/"
4760    "Translations.html}."
4761  msgstr ""  msgstr ""
4762    
4763  #. type: Plain text  #. type: Plain text
4764  #: R-ints.texi:2460  #: R-ints.texi:2460
4765  msgid "See file @file{po/README} for how to update the message templates and catalogs."  msgid ""
4766    "See file @file{po/README} for how to update the message templates and "
4767    "catalogs."
4768  msgstr ""  msgstr ""
4769    
4770  #. type: chapter  #. type: chapter
# Line 3522  Line 4793 
4793    
4794  #. type: Plain text  #. type: Plain text
4795  #: R-ints.texi:2472  #: R-ints.texi:2472
4796  msgid "The structure of a @emph{source} packages is described in @ref{Creating R packages, , Creating R packages, R-exts, Writing R Extensions}: this chapter is concerned with the structure of @emph{installed} packages."  msgid ""
4797    "The structure of a @emph{source} packages is described in @ref{Creating R "
4798    "packages, , Creating R packages, R-exts, Writing R Extensions}: this chapter "
4799    "is concerned with the structure of @emph{installed} packages."
4800  msgstr ""  msgstr ""
4801    
4802  #. type: Plain text  #. type: Plain text
4803  #: R-ints.texi:2484  #: R-ints.texi:2484
4804  msgid "An installed package has a top-level file @file{DESCRIPTION}, a copy of the file of that name in the package sources with a @samp{Built} field appended, and file @file{INDEX}, usually describing the objects on which help is available, a file @file{NAMESPACE} if the package has a name space, optional files such as @file{CITATION}, @file{LICENCE} and @file{NEWS}, and any other files copied in from @file{inst}.  It will have directories @file{Meta}, @file{help} and @file{html} (even if the package has no help pages), almost always has a directory @file{R} and often has a directory @file{libs} to contain compiled code.  Other directories with known meaning to @R{} are @file{data}, @file{demo}, @file{doc} and @file{po}."  msgid ""
4805    "An installed package has a top-level file @file{DESCRIPTION}, a copy of the "
4806    "file of that name in the package sources with a @samp{Built} field appended, "
4807    "and file @file{INDEX}, usually describing the objects on which help is "
4808    "available, a file @file{NAMESPACE} if the package has a name space, optional "
4809    "files such as @file{CITATION}, @file{LICENCE} and @file{NEWS}, and any other "
4810    "files copied in from @file{inst}.  It will have directories @file{Meta}, "
4811    "@file{help} and @file{html} (even if the package has no help pages), almost "
4812    "always has a directory @file{R} and often has a directory @file{libs} to "
4813    "contain compiled code.  Other directories with known meaning to @R{} are "
4814    "@file{data}, @file{demo}, @file{doc} and @file{po}."
4815  msgstr ""  msgstr ""
4816    
4817  #. type: Plain text  #. type: Plain text
4818  #: R-ints.texi:2493  #: R-ints.texi:2493
4819  msgid "Function @code{library} looks for a namespace and if one is found passes control to @code{loadNamespace}.  Then @code{library} or @code{loadNamespace} looks for file @file{R/@var{pkgname}}, warns if it is not found and otherwise sources the code (using @code{sys.source})  into the package's environment, then lazy-loads a database @file{R/sysdata} if present.  So how @R{} code gets loaded depends on the contents of @file{R/@var{pkgname}}: a standard template to load lazy-load databases are provided in @file{share/R/nspackloader.R}."  msgid ""
4820    "Function @code{library} looks for a namespace and if one is found passes "
4821    "control to @code{loadNamespace}.  Then @code{library} or "
4822    "@code{loadNamespace} looks for file @file{R/@var{pkgname}}, warns if it is "
4823    "not found and otherwise sources the code (using @code{sys.source})  into the "
4824    "package's environment, then lazy-loads a database @file{R/sysdata} if "
4825    "present.  So how @R{} code gets loaded depends on the contents of @file{R/"
4826    "@var{pkgname}}: a standard template to load lazy-load databases are provided "
4827    "in @file{share/R/nspackloader.R}."
4828  msgstr ""  msgstr ""
4829    
4830  #. type: Plain text  #. type: Plain text
4831  #: R-ints.texi:2500  #: R-ints.texi:2500
4832  msgid "Compiled code is usually loaded when the package's namespace is loaded by a @code{useDynlib} directive in a @file{NAMESPACE} file or by the package's @code{.onLoad} function.  Conventionally compiled code is loaded by a call to @code{library.dynam} and this looks in directory @file{libs} (and in an appropriate sub-directory if sub-architectures are in use) for a shared object (Unix-alike) or DLL (Windows)."  msgid ""
4833    "Compiled code is usually loaded when the package's namespace is loaded by a "
4834    "@code{useDynlib} directive in a @file{NAMESPACE} file or by the package's "
4835    "@code{.onLoad} function.  Conventionally compiled code is loaded by a call "
4836    "to @code{library.dynam} and this looks in directory @file{libs} (and in an "
4837    "appropriate sub-directory if sub-architectures are in use) for a shared "
4838    "object (Unix-alike) or DLL (Windows)."
4839  msgstr ""  msgstr ""
4840    
4841  #. type: Plain text  #. type: Plain text
4842  #: R-ints.texi:2508  #: R-ints.texi:2508
4843  msgid "Subdirectory @file{data} serves two purposes. In a package using lazy-loading of data, it contains a lazy-load database @file{Rdata}, plus a file @file{Rdata.rds} which contain a named character vector used by @code{data()} in the (unusual) event that it is used for such a package.  Otherwise it is a copy of the @file{data} directory in the sources, with saved images re-compressed if @command{R CMD INSTALL --resave-data} was used."  msgid ""
4844    "Subdirectory @file{data} serves two purposes. In a package using lazy-"
4845    "loading of data, it contains a lazy-load database @file{Rdata}, plus a file "
4846    "@file{Rdata.rds} which contain a named character vector used by "
4847    "@code{data()} in the (unusual) event that it is used for such a package.  "
4848    "Otherwise it is a copy of the @file{data} directory in the sources, with "
4849    "saved images re-compressed if @command{R CMD INSTALL --resave-data} was used."
4850  msgstr ""  msgstr ""
4851    
4852  #. type: Plain text  #. type: Plain text
4853  #: R-ints.texi:2511  #: R-ints.texi:2511
4854  msgid "Subdirectory @file{demo} supports the @code{demo} function, and is copied from the sources."  msgid ""
4855    "Subdirectory @file{demo} supports the @code{demo} function, and is copied "
4856    "from the sources."
4857  msgstr ""  msgstr ""
4858    
4859  #. type: Plain text  #. type: Plain text
4860  #: R-ints.texi:2514  #: R-ints.texi:2514
4861  msgid "Subdirectory @file{po} contains (in subdirectories) compiled message catalogs."  msgid ""
4862    "Subdirectory @file{po} contains (in subdirectories) compiled message "
4863    "catalogs."
4864  msgstr ""  msgstr ""
4865    
4866  #. type: Plain text  #. type: Plain text
4867  #: R-ints.texi:2524  #: R-ints.texi:2524
4868  msgid "Directory @file{Meta} contains several files in @code{.rds} format, that is serialized @R{} objects written by @code{saveRDS}.  All packages have files @file{Rd.rds}, @file{hsearch.rds}, @file{links.rds} and @file{package.rds}.  Packages with namespaces have a file @file{nsInfo.rds}, and those with data, demos or vignettes have @file{data.rds}, @file{demo.rds} or @file{vignette.rds} files."  msgid ""
4869    "Directory @file{Meta} contains several files in @code{.rds} format, that is "
4870    "serialized @R{} objects written by @code{saveRDS}.  All packages have files "
4871    "@file{Rd.rds}, @file{hsearch.rds}, @file{links.rds} and @file{package.rds}.  "
4872    "Packages with namespaces have a file @file{nsInfo.rds}, and those with data, "
4873    "demos or vignettes have @file{data.rds}, @file{demo.rds} or @file{vignette."
4874    "rds} files."
4875  msgstr ""  msgstr ""
4876    
4877  #. type: Plain text  #. type: Plain text
4878  #: R-ints.texi:2529  #: R-ints.texi:2529
4879  msgid "The structure of these files (and their existence and names) is private to @R{}, so the description here is for those trying to follow the @R{} sources: there should be no reference to these files in non-base packages."  msgid ""
4880    "The structure of these files (and their existence and names) is private to "
4881    "@R{}, so the description here is for those trying to follow the @R{} "
4882    "sources: there should be no reference to these files in non-base packages."
4883  msgstr ""  msgstr ""
4884    
4885  #. type: Plain text  #. type: Plain text
4886  #: R-ints.texi:2546  #: R-ints.texi:2546
4887  msgid "File @file{package.rds} is a dump of information extracted from the @file{DESCRIPTION} file.  It is a list of several components.  The first, @samp{DESCRIPTION}, is a character vector, the @file{DESCRIPTION} file as read by @code{read.dcf}.  Further elements @samp{Depends}, @samp{Suggests}, @samp{Imports}, @samp{Rdepends} and @samp{Rdepends2} record the @samp{Depends}, @samp{Suggests} and @samp{Imports} fields.  These are all lists, and can be empty.  The first three have an entry for each package named, each entry being a list of length 1 or 3, which element @samp{name} (the package name) and optional elements @samp{op} (a character string) and @samp{version} (an object of class @samp{\"package_version\"}).  Element @samp{Rdepends} is used for the first version dependency on @R{}, and @samp{Rdepends2} is a list of zero or more @R{} version dependencies---each is a three-element list of the form described for packages.  Element @samp{Rdepends} is no longer used, but it is still potentially needed so @R{} < 2.7.0 can detect that the package was not installed for it."  msgid ""
4888    "File @file{package.rds} is a dump of information extracted from the "
4889    "@file{DESCRIPTION} file.  It is a list of several components.  The first, "
4890    "@samp{DESCRIPTION}, is a character vector, the @file{DESCRIPTION} file as "
4891    "read by @code{read.dcf}.  Further elements @samp{Depends}, @samp{Suggests}, "
4892    "@samp{Imports}, @samp{Rdepends} and @samp{Rdepends2} record the "
4893    "@samp{Depends}, @samp{Suggests} and @samp{Imports} fields.  These are all "
4894    "lists, and can be empty.  The first three have an entry for each package "
4895    "named, each entry being a list of length 1 or 3, which element @samp{name} "
4896    "(the package name) and optional elements @samp{op} (a character string) and "
4897    "@samp{version} (an object of class @samp{\"package_version\"}).  Element "
4898    "@samp{Rdepends} is used for the first version dependency on @R{}, and "
4899    "@samp{Rdepends2} is a list of zero or more @R{} version dependencies---each "
4900    "is a three-element list of the form described for packages.  Element "
4901    "@samp{Rdepends} is no longer used, but it is still potentially needed so "
4902    "@R{} < 2.7.0 can detect that the package was not installed for it."
4903  msgstr ""  msgstr ""
4904    
4905  #. type: Plain text  #. type: Plain text
4906  #: R-ints.texi:2549  #: R-ints.texi:2549
4907  msgid "File @file{nsInfo.rds} records a list, a parsed version of the @file{NAMESPACE} file."  msgid ""
4908    "File @file{nsInfo.rds} records a list, a parsed version of the "
4909    "@file{NAMESPACE} file."
4910  msgstr ""  msgstr ""
4911    
4912  #. type: Plain text  #. type: Plain text
4913  #: R-ints.texi:2556  #: R-ints.texi:2556
4914  msgid "File @file{Rd.rds} records a data frame with one row for each help file.  The columns are @samp{File} (the file name with extension), @samp{Name} (the @samp{\\name} section), @samp{Type} (from the optional @samp{\\docType} section), @samp{Title}, @samp{Encoding}, @samp{Aliases}, @samp{Concepts} and @samp{Keywords}.  All columns are character vectors apart from @samp{Aliases}, which is a list of character vectors."  msgid ""
4915    "File @file{Rd.rds} records a data frame with one row for each help file.  "
4916    "The columns are @samp{File} (the file name with extension), @samp{Name} (the "
4917    "@samp{\\name} section), @samp{Type} (from the optional @samp{\\docType} "
4918    "section), @samp{Title}, @samp{Encoding}, @samp{Aliases}, @samp{Concepts} and "
4919    "@samp{Keywords}.  All columns are character vectors apart from "
4920    "@samp{Aliases}, which is a list of character vectors."
4921  msgstr ""  msgstr ""
4922    
4923  #. type: Plain text  #. type: Plain text
4924  #: R-ints.texi:2567  #: R-ints.texi:2567
4925  msgid "File @file{hsearch.rds} records the information to be used by @samp{help.search}.  This is a list of four unnamed elements which are character matrices for help files, aliases, keywords and concepts.  All the matrices have columns @samp{ID} and @samp{Package} which are used to tie the aliases, keywords and concepts (the remaining column of the last three elements) to a particular help file.  The first element has further columns @samp{LibPath} (stored as @code{\"\"} and filled in what the file is loaded), @samp{name}, @samp{title}, @samp{topic} (the first alias, used when presenting the results as @samp{@var{pkgname}::@var{topic}}) and @samp{Encoding}."  msgid ""
4926    "File @file{hsearch.rds} records the information to be used by @samp{help."
4927    "search}.  This is a list of four unnamed elements which are character "
4928    "matrices for help files, aliases, keywords and concepts.  All the matrices "
4929    "have columns @samp{ID} and @samp{Package} which are used to tie the aliases, "
4930    "keywords and concepts (the remaining column of the last three elements) to a "
4931    "particular help file.  The first element has further columns @samp{LibPath} "
4932    "(stored as @code{\"\"} and filled in what the file is loaded), @samp{name}, "
4933    "@samp{title}, @samp{topic} (the first alias, used when presenting the "
4934    "results as @samp{@var{pkgname}::@var{topic}}) and @samp{Encoding}."
4935  msgstr ""  msgstr ""
4936    
4937  #. type: Plain text  #. type: Plain text
4938  #: R-ints.texi:2570  #: R-ints.texi:2570
4939  msgid "File @file{links.rds} records a named character vector, the names being aliases and the values character strings of the form"  msgid ""
4940    "File @file{links.rds} records a named character vector, the names being "
4941    "aliases and the values character strings of the form"
4942  msgstr ""  msgstr ""
4943    
4944  #. type: example  #. type: example
# Line 3598  Line 4949 
4949    
4950  #. type: Plain text  #. type: Plain text
4951  #: R-ints.texi:2577  #: R-ints.texi:2577
4952  msgid "File @file{data.rds} records a two-column character matrix with columns of dataset names and titles from the corresponding help file.  File @file{demo.rds} has the same structure for package demos."  msgid ""
4953    "File @file{data.rds} records a two-column character matrix with columns of "
4954    "dataset names and titles from the corresponding help file.  File @file{demo."
4955    "rds} has the same structure for package demos."
4956  msgstr ""  msgstr ""
4957    
4958  #. type: Plain text  #. type: Plain text
4959  #: R-ints.texi:2584  #: R-ints.texi:2584
4960  msgid "File @file{vignette.rds} records a dataframe with one row for each `vignette' (@file{.[RS]nw} file in @file{inst/doc}) and with columns @samp{File} (the full file path in the sources), @samp{Title}, @samp{PDF} (the pathless file name of the installed PDF version, if present), @samp{Depends}, @samp{Keywords} and @samp{R} (the pathless file name of the installed @R{} code, if present)."  msgid ""
4961    "File @file{vignette.rds} records a dataframe with one row for each "
4962    "`vignette' (@file{.[RS]nw} file in @file{inst/doc}) and with columns "
4963    "@samp{File} (the full file path in the sources), @samp{Title}, @samp{PDF} "
4964    "(the pathless file name of the installed PDF version, if present), "
4965    "@samp{Depends}, @samp{Keywords} and @samp{R} (the pathless file name of the "
4966    "installed @R{} code, if present)."
4967  msgstr ""  msgstr ""
4968    
4969  #. type: Plain text  #. type: Plain text
4970  #: R-ints.texi:2593  #: R-ints.texi:2593
4971  msgid "All installed packages, whether they had any @file{.Rd} files or not, have @file{help} and @file{html} directories. The latter normally only contains the single file @file{00Index.html}, the package index which has hyperlinks to the help topics (if any)."  msgid ""
4972    "All installed packages, whether they had any @file{.Rd} files or not, have "
4973    "@file{help} and @file{html} directories. The latter normally only contains "
4974    "the single file @file{00Index.html}, the package index which has hyperlinks "
4975    "to the help topics (if any)."
4976  msgstr ""  msgstr ""
4977    
4978  #. type: Plain text  #. type: Plain text
4979  #: R-ints.texi:2600  #: R-ints.texi:2600
4980  msgid "Directory @file{help} contains files @file{AnIndex}, @file{paths.rds} and @file{@var{pkgname}.rd[bx]}.  The latter two files are a lazy-load database of parsed @file{.Rd} files, accessed by @code{tools:::fetchRdDB}.  File @file{paths.rds} is a saved character vector of the original path names of the @file{.Rd} files, used when updating the database."  msgid ""
4981    "Directory @file{help} contains files @file{AnIndex}, @file{paths.rds} and "
4982    "@file{@var{pkgname}.rd[bx]}.  The latter two files are a lazy-load database "
4983    "of parsed @file{.Rd} files, accessed by @code{tools:::fetchRdDB}.  File "
4984    "@file{paths.rds} is a saved character vector of the original path names of "
4985    "the @file{.Rd} files, used when updating the database."
4986  msgstr ""  msgstr ""
4987    
4988  #. type: Plain text  #. type: Plain text
4989  #: R-ints.texi:2607  #: R-ints.texi:2607
4990  msgid "File @file{AnIndex} is a two-column tab-delimited file: the first column contains the aliases defined in the help files and the second the basename (without the @file{.Rd} or @file{.rd} extension) of the file containing that alias.  It is read by @code{utils:::index.search} to search for files matching a topic (alias), and read by @code{scan} in @code{utils:::matchAvailableTopics}, part of the completion system."  msgid ""
4991    "File @file{AnIndex} is a two-column tab-delimited file: the first column "
4992    "contains the aliases defined in the help files and the second the basename "
4993    "(without the @file{.Rd} or @file{.rd} extension) of the file containing that "
4994    "alias.  It is read by @code{utils:::index.search} to search for files "
4995    "matching a topic (alias), and read by @code{scan} in @code{utils:::"
4996    "matchAvailableTopics}, part of the completion system."
4997  msgstr ""  msgstr ""
4998    
4999  #. type: Plain text  #. type: Plain text
5000  #: R-ints.texi:2611  #: R-ints.texi:2611
5001  msgid "File @file{aliases.rds} is the same information as @file{AnIndex} as a named character vector (names the topics, values the file basename), for faster access."  msgid ""
5002    "File @file{aliases.rds} is the same information as @file{AnIndex} as a named "
5003    "character vector (names the topics, values the file basename), for faster "
5004    "access."
5005  msgstr ""  msgstr ""
5006    
5007  #. type: Plain text  #. type: Plain text
5008  #: R-ints.texi:2619  #: R-ints.texi:2619
5009  msgid "@R{} provides many functions to work with files and directories: many of these have been added relatively recently to facilitate scripting in @R{} and in particular the replacement of Perl scripts by @R{} scripts in the management of @R{} itself."  msgid ""
5010    "@R{} provides many functions to work with files and directories: many of "
5011    "these have been added relatively recently to facilitate scripting in @R{} "
5012    "and in particular the replacement of Perl scripts by @R{} scripts in the "
5013    "management of @R{} itself."
5014  msgstr ""  msgstr ""
5015    
5016  #. type: Plain text  #. type: Plain text
5017  #: R-ints.texi:2626  #: R-ints.texi:2626
5018  msgid "These functions are implemented by standard C/POSIX library calls, except on Windows.  That means that filenames must be encoded in the current locale as the OS provides no other means to access the file system: increasingly filenames are stored in UTF-8 and the OS will translate filenames to UTF-8 in other locales.  So using a UTF-8 locale gives transparent access to the whole file system."  msgid ""
5019    "These functions are implemented by standard C/POSIX library calls, except on "
5020    "Windows.  That means that filenames must be encoded in the current locale as "
5021    "the OS provides no other means to access the file system: increasingly "
5022    "filenames are stored in UTF-8 and the OS will translate filenames to UTF-8 "
5023    "in other locales.  So using a UTF-8 locale gives transparent access to the "
5024    "whole file system."
5025  msgstr ""  msgstr ""
5026    
5027  #. type: Plain text  #. type: Plain text
5028  #: R-ints.texi:2639  #: R-ints.texi:2639
5029  msgid "Windows is another story.  There the internal view of filenames is in UTF-16LE (so-called `Unicode'), and standard C library calls can only access files whose names can be expressed in the current codepage.  To circumvent that restriction, there is a parallel set of Windows-specific calls which take wide-character arguments for filepaths.  Much of the file-handling in @R{} has been moved over to using these functions, so filenames can be manipulated in @R{} as UTF-8 encoded character strings, converted to wide characters (which on Windows are UTF-16LE) and passed to the OS.  The utilities @code{RC_fopen} and @code{filenameToWchar} help this process.  Currently @code{file.copy} to a directory, @code{list.files}, @code{list.dirs} and @code{path.expand} work only with filepaths encoded in the current codepage."  msgid ""
5030    "Windows is another story.  There the internal view of filenames is in "
5031    "UTF-16LE (so-called `Unicode'), and standard C library calls can only access "
5032    "files whose names can be expressed in the current codepage.  To circumvent "
5033    "that restriction, there is a parallel set of Windows-specific calls which "
5034    "take wide-character arguments for filepaths.  Much of the file-handling in "
5035    "@R{} has been moved over to using these functions, so filenames can be "
5036    "manipulated in @R{} as UTF-8 encoded character strings, converted to wide "
5037    "characters (which on Windows are UTF-16LE) and passed to the OS.  The "
5038    "utilities @code{RC_fopen} and @code{filenameToWchar} help this process.  "
5039    "Currently @code{file.copy} to a directory, @code{list.files}, @code{list."