R 内部机制 ¶

1.1 SEXPs ¶

R 用户所认为的 变量 或 对象 是绑定到值的符号。该值可以被认为是 SEXP（一个指针），或者它指向的结构，一个 SEXPREC（对于向量，还有替代形式，即指向 VECTOR_SEXPREC 结构的 VECSXP）。因此，R 对象的基本构建块通常被称为 节点，指的是 SEXPREC 或 VECTOR_SEXPREC。

请注意，SEXPREC 的内部结构对 R 扩展不可用：相反，SEXP 是一个不透明的指针，只能通过提供的函数访问其内部结构。

两种类型的节点结构的前三个字段都是一个 64 位的 sxpinfo 头部，然后是三个指针（指向属性以及双向链表中的前一个和下一个节点），以及一些其他字段。在 32 位平台上，一个节点¹ 占用 32 字节：在 64 位平台上，通常占用 56 字节（取决于对齐约束）。

sxpinfo 头部的前五个位指定了最多 32 个 SEXPTYPE 之一。

• SEXPTYPEs
• 头部剩余部分
• “数据”
• 分配类别

#define NAMED_BITS 16
struct sxpinfo_struct {
    SEXPTYPE type      :  5;  /* discussed above */
    unsigned int scalar:  1;  /* is this a numeric vector of length 1?
    unsigned int obj   :  1;  /* is this an object with a class attribute? */
    unsigned int alt   :  1;  /* is this an ALTREP object? */
    unsigned int gp    : 16;  /* general purpose, see below */
    unsigned int mark  :  1;  /* mark object as ‘in use’ in GC */
    unsigned int debug :  1;
    unsigned int trace :  1;
    unsigned int spare :  1;  /* debug once and with reference counting */
    unsigned int gcgen :  1;  /* generation for GC */
    unsigned int gccls :  3;  /* class of node for GC */
    unsigned int named : NAMED_BITS; /* used to control copying */
    unsigned int extra : 32 - NAMED_BITS;
}; /*		    Tot: 64 */

b <- a

dim(a) <- c(7, 2)

a <- `dim<-`(a, c(7, 2))

union {
    struct primsxp_struct primsxp;
    struct symsxp_struct symsxp;
    struct listsxp_struct listsxp;
    struct envsxp_struct envsxp;
    struct closxp_struct closxp;
    struct promsxp_struct promsxp;
} u;

1.2 环境和变量查找 ¶

用户认为的“变量”是绑定到“环境”中的对象的符号。“环境”一词在 R 中被模棱两可地使用，表示 要么 ENVSXP 的框架（符号-值对的配对列表）要么 ENVSXP，一个框架加上一个封闭体。

还有其他地方可以查找“变量”，在代码中的注释中称为“用户数据库”。这些似乎在 R 源代码中没有记录，但显然指的是 RObjectTable 包，以前可在 https://www.omegahat.net/RObjectTables/ 获取。

基础环境是特殊的。存在一个名为 ENVSXP 的环境，它包含空环境 R_EmptyEnv，但该环境的帧未使用。相反，它的绑定是全局符号表的一部分，即全局符号表中值为非 R_UnboundValue 的那些符号。当 R 启动时，内部函数（通过 C 代码）被安装到符号表中，原始函数具有值，而 .Internal 函数具有在 INTERNAL 宏访问的字段中的值。然后计算 .Platform 和 .Machine，并将基础包加载到基础环境中，然后加载系统配置文件。

环境（和符号表）的帧通常被哈希以实现更快的访问（包括插入和删除）。

默认情况下，R 会维护一个（哈希的）全局缓存，用于存储已找到的“变量”（即符号及其绑定），这仅适用于已标记为参与的那些环境，包括全局环境（也称为用户工作区）、基础环境以及已 attach 的环境⁴。当环境被 attach 或 detach 时，其符号的名称将从缓存中清除。在从全局环境搜索变量（可能作为递归搜索的一部分）时，将使用缓存。

• 搜索路径
• 命名空间
• 哈希表

1.3 属性 ¶

正如我们所见，每个 SEXPREC 都包含一个指向节点属性的指针（默认值为 R_NilValue）。可以使用宏/函数 ATTRIB 和 SET_ATTRIB 访问/设置属性，但这种直接访问通常仅用于检查属性是否为 NULL 或重置它们。否则，访问将通过函数 getAttrib 和 setAttrib 进行，这些函数会对属性施加限制。需要注意的是，如果您将属性从一个对象复制到另一个对象，您可能会（取消）设置 "class" 属性，因此也需要复制对象和 S4 位。有一个宏/函数 DUPLICATE_ATTRIB 可以自动执行此操作。

请注意，CHARSXP 的“属性”用作 CHARSXP 缓存管理的一部分：当然，CHARSXP 对用户不可见，但 C 级代码可能会查看它们的属性。

代码假设节点的属性要么是 R_NilValue，要么是非零长度的配对列表（这由 SET_ATTRIB 检查）。属性通过配对列表上的标签进行命名。替换函数 attributes<- 确保在配对列表中 "dim" 位于 "dimnames" 之前。属性 "dim" 是几个特殊处理的属性之一：会检查其值，并删除任何 "names" 和 "dimnames" 属性。类似地，您不能在没有设置 "dim" 的情况下设置 "dimnames"，并且分配的值必须是长度正确且元素长度正确的列表（所有零长度元素都将被替换为 NULL）。

其他接受特殊处理的属性包括 "names"、"class"、"tsp"、"comment" 和 "row.names"。对于类似配对列表的对象，名称不会作为属性存储，而是作为标签（以符号形式）存储：但是，R 接口使它们看起来像传统的属性，并且对于一维数组，它们作为 "dimnames" 属性的第一个元素存储。C 代码确保 "tsp" 属性是 REALSXP，频率为正数，并且隐含长度与分配给对象的行的数量一致。类和注释限制为字符向量，分配零长度的注释或类将删除该属性。设置或删除 "class" 属性将相应地设置对象位。整数行名将转换为内部紧凑表示形式，反之亦然。

在向具有非标准复制语义类型的对象添加属性时，需要格外小心。只存在一个类型为 NILSXP 的对象，即 R_NilValue，它不应该具有属性（这在 installAttrib 中得到强制执行）。对于环境、外部指针和弱引用，属性应该与对象的全部用途相关：例如，为环境命名是合理的，并且为从包中的 R 代码填充的环境添加 "path" 属性也是合理的。

何时应在对象操作下保留属性？Becker、Chambers 和 Wilks（1988 年，第 144-146 页）提供了一些指导。标量函数（那些对向量逐元素操作且输出类似于输入的函数）应保留属性（可能除了类，如果它们保留类，则需要保留 OBJECT 和 S4 位）。二元运算通常调用 copyMostAttrib 从较长的参数复制大多数属性（如果它们具有相同的长度，则优先考虑第一个参数的值）。这里“大多数”是指除 names、dim 和 dimnames 之外的所有属性，这些属性由运算符代码适当地设置。

子集（除了空索引）通常会删除所有属性，除了 names、dim 和 dimnames，这些属性会根据需要重置。另一方面，子赋值通常会保留这些属性，即使长度发生了改变。强制转换会删除所有属性。例如

> x <- structure(1:8, names=letters[1:8], comm="a comment")
> x[]
a b c d e f g h
1 2 3 4 5 6 7 8
attr(,"comm")
[1] "a comment"
> x[1:3]
a b c
1 2 3
> x[3] <- 3
> x
a b c d e f g h
1 2 3 4 5 6 7 8
attr(,"comm")
[1] "a comment"
> x[9] <- 9
> x
a b c d e f g h
1 2 3 4 5 6 7 8 9
attr(,"comm")
[1] "a comment"

1.4 上下文 ¶

上下文是用于跟踪计算进行到何处（以及从何处开始）的内部机制，以便控制流结构可以工作，并且可以在错误条件下（例如 通过回溯）以及其他情况下生成合理的信息（sys.xxx 函数）。

执行上下文是 C structs 的堆栈

typedef struct RCNTXT {
    struct RCNTXT *nextcontext; /* The next context up the chain */
    int callflag;               /* The context ‘type’ */
    JMP_BUF cjmpbuf;            /* C stack and register information */
    int cstacktop;              /* Top of the pointer protection stack */
    int evaldepth;              /* Evaluation depth at inception */
    SEXP promargs;              /* Promises supplied to closure */
    SEXP callfun;               /* The closure called */
    SEXP sysparent;             /* Environment the closure was called from */
    SEXP call;                  /* The call that effected this context */
    SEXP cloenv;                /* The environment */
    SEXP conexit;               /* Interpreted on.exit code */
    void (*cend)(void *);       /* C on.exit thunk */
    void *cenddata;             /* Data for C on.exit thunk */
    char *vmax;                 /* Top of the R_alloc stack */
    int intsusp;                /* Interrupts are suspended */
    SEXP handlerstack;          /* Condition handler stack */
    SEXP restartstack;          /* Stack of available restarts */
    struct RPRSTACK *prstack;   /* Stack of pending promises */
} RCNTXT, *context;

加上字节码编译器的附加字段。这些“类型”来自

enum {
    CTXT_TOPLEVEL = 0,  /* toplevel context */
    CTXT_NEXT     = 1,  /* target for next */
    CTXT_BREAK    = 2,  /* target for break */
    CTXT_LOOP     = 3,  /* break or next target */
    CTXT_FUNCTION = 4,  /* function closure */
    CTXT_CCODE    = 8,  /* other functions that need error cleanup */
    CTXT_RETURN   = 12, /* return() from a closure */
    CTXT_BROWSER  = 16, /* return target on exit from browser */
    CTXT_GENERIC  = 20, /* rather, running an S3 method */
    CTXT_RESTART  = 32, /* a call to restart was made from a closure */
    CTXT_BUILTIN  = 64  /* builtin internal function */
};

其中 CTXT_FUNCTION 位在涉及函数闭包的任何地方都处于打开状态。

上下文由对 begincontext 的调用创建，并由对 endcontext 的调用结束：代码可以通过 findcontext 在堆栈中搜索特定类型的上下文（并跳转到该上下文）或通过 R_JumpToContext 跳转到特定上下文。 R_ToplevelContext 是“空闲”状态（通常是命令提示符），而 R_GlobalContext 是堆栈的顶部。

请注意，虽然对闭包的调用会设置上下文，但内部函数永远不会设置上下文，而原始内置函数仅在分析或它们是外部函数的接口时才会设置上下文。

字节码编译器在编译时生成一个指令到源引用和表达式的映射，这允许生成错误条件的信息。作为一种优化，字节码解释器在某些情况下不会设置上下文，例如在简单的循环中或内联简单的内置函数或内部函数的包装器时。

从 S3 通用函数（通过 UseMethod 或其内部等效项）进行调度或调用 NextMethod 会将上下文类型设置为 CTXT_GENERIC。这用于将方法调用的 sysparent 设置为 generic 的 sysparent，因此方法看起来是在通用函数的位置被调用，而不是从通用函数调用。

R 的 sys.frame 和 sys.call 函数通过从上下文堆栈的两端计算对闭包（类型 CTXT_FUNCTION）的调用来工作。

请注意，结构的 sysparent 元素与 sys.parent() 不同。元素 sysparent 主要用于管理正在评估的函数的更改，例如通过 Recall 和方法调度。

CTXT_CCODE 上下文目前用于 cat()、load()、scan() 和 write.table()（在错误时关闭连接）、PROTECT、序列化（从错误中恢复，例如释放缓冲区）以及错误处理代码中（提高 C 堆栈限制并重置一些变量）。

1.5 参数评估 ¶

正如我们所见，R 中的函数有三种类型：闭包（SEXPTYPE CLOSXP）、特殊函数（SPECIALSXP）和内置函数（BUILTINSXP）。在本节中，我们将考虑何时（以及是否）实际评估函数调用的参数。内部（特殊/内置）函数和 R 级函数（闭包）的规则不同。

对于闭包的调用，实际参数和形式参数会进行匹配，并构建一个匹配的调用（另一个 LANGSXP）。这个过程首先用对提供值的承诺列表替换实际参数列表。然后，它构建一个新的环境，其中包含与实际值或默认值匹配的形式参数的名称：所有匹配的值都是承诺，默认值是承诺，将在刚创建的环境中进行评估。然后，该环境用于评估函数体，并且承诺将在遇到时被强制（因此实际参数或默认参数被评估）。 （评估承诺会将其值的 NAMED 设置为 NAMEDMAX，因此如果参数是符号，则在评估闭包调用期间，其绑定被视为具有多个引用。）[NAMED 机制已被引用计数取代。]

如果闭包是 S3 通用函数（即包含对 UseMethod 的调用），则评估过程与遇到 UseMethod 调用之前相同。此时，将评估用于分派的论点（通常是第一个），如果它尚未被评估。如果找到一个方法，它是一个闭包，则会为它创建一个新的评估环境，其中包含该方法的匹配参数以及在评估通用函数体期间定义的任何新变量。（注意，这意味着对通用函数体中形式参数值的更改在调用方法时会被丢弃，但 实际 参数承诺在被强制时会保留找到的值。另一方面，缺少的参数的值是承诺使用该方法提供的默认值，而不是通用函数提供的默认值。）如果找到的方法是基本函数，则使用用于通用函数的匹配参数承诺列表（可能已被强制）调用它。

特殊函数和内置函数之间的本质区别⁵在于特殊函数的参数在调用 C 代码之前不会被评估，而内置函数的参数会被评估。请注意，是特殊函数/内置函数与是否是基本函数或 .Internal 是分开的：quote 是一个特殊基本函数，+ 是一个内置基本函数，cbind 是一个特殊 .Internal，而 grep 是一个内置 .Internal。

许多内部函数是内部通用函数，对于特殊函数来说，这意味着它们在调用时不会评估其参数，而是 C 代码从调用 DispatchOrEval 开始。后者评估第一个参数，并根据其类查找方法。（如果 S4 分派已开启，则会首先查找 S4 方法，即使对于 S3 类也是如此。）如果找到方法，它会使用基于承诺来评估剩余参数的调用分派到该方法。如果没有找到方法，则在返回到内部通用函数之前会评估剩余参数。

内部函数可以泛化的另一种方式是分组泛化。大多数此类函数是内置函数（因此立即评估所有参数），并且都包含对 C 函数 DispatchGeneric 的调用。对于 "Math" 分组泛化，参数数量有一些特殊情况，一些成员只允许一个参数，一些成员有两个参数（第二个参数有默认值），而 trunc 允许一个或多个参数，但默认方法只接受一个参数。

• 缺失值
• 省略号参数

argument "foobar" is missing, with no default

1.6 自动打印 ¶

顶层 R 表达式的返回值是否打印由全局布尔变量 R_Visible 控制。它在进入所有原语和内部函数时（设置为 true 或 false），基于文件 src/main/names.c 中表格的 eval 列：适当的设置可以通过宏 PRIMPRINT 提取。

R 原语函数 invisible 利用了这种机制：它只是在进入之前设置 R_Visible = FALSE 并返回其参数。

对于大多数函数，意图是当它们进入时 R_Visible 的设置是它们返回时使用的设置，但需要有例外。R 函数 identify、options、system 和 writeBin 确定结果是否应从参数或用户操作中可见。其他函数本身会调度可能更改可见性标志的函数：例如⁶ 是 .Internal、do.call、eval、withVisible、if、NextMethod、Recall、recordGraphics、standardGeneric、switch 和 UseMethod。

“特殊”基元函数和内部函数在R_Visible被设置之后内部评估其参数，并且参数的评估（例如 PR#9263 中的赋值）可能会改变标志的值。

在函数评估期间，R_Visible标志也可能被更改，代码中的注释提到了warning、writeChar和图形函数调用GText（PR#7397）。（由于 C 级函数eval设置了R_Visible，因此这可能适用于任何调用它的函数。由于它在评估承诺时被调用，因此即使对象查找也会更改R_Visible。）内部函数和基元函数强制在返回时将R_Visible设置为文档化的设置，除非 C 代码被允许更改它（上面的异常由PRIMPRINT的值为 2 指示）。

实际的自动打印由print.c文件中的PrintValueEnv完成。如果要打印的对象设置了 S4 位并且 S4 方法调度已开启，则调用show来打印对象。否则，如果设置了对象位（因此对象具有"class"属性），则调用print来调度方法：对于没有类的对象，将调用print.default的内部代码。

1.7 写屏障和垃圾收集器 ¶

R 长期以来一直使用分代垃圾收集器，sxpinfo头部的gcgen位用于实现它。它与mark位一起使用，用于识别两个之前的代。

有三个级别的收集。级别 0 只收集最年轻的代，级别 1 收集两个最年轻的代，级别 2 收集所有代。在 20 次级别 0 收集之后，下一次收集将处于级别 1，在 5 次级别 1 收集之后将处于级别 2。此外，如果级别-n收集未能提供 20% 的空闲空间（对于节点和向量堆中的每一个），则下一次收集将处于级别 n+1。（R 级函数gc()执行级别 2 收集。）

分代收集器需要有效地“老化”对象，尤其是列表状对象（包括STRSXP）。这是通过确保列表的元素被认为至少与列表一样旧来完成的当它们被分配时。这是由函数SET_VECTOR_ELT和SET_STRING_ELT处理的，这就是为什么它们是函数而不是宏的原因。确保此类操作的完整性被称为写屏障，它是通过使SEXP不透明并且只提供通过函数访问来完成的（在 C 中不能用作赋值中的左值）。

R 扩展中的所有代码都在写入屏障之后。R 扩展不能直接访问 SEXPREC 的内部结构。如果定义了 ‘USE_RINTERNALS’，则基本代码可以访问内部结构。这通常在编译 R 时在 Defn.h 中定义。为了启用对访问方式使用的检查，R 可以使用标志 --enable-strict-barrier 编译，这将确保头文件 Defn.h 不定义 ‘USE_RINTERNALS’，因此 SEXP 在大多数 R 本身中都是不透明的。（有一些必要的例外：最重要的是在文件 memory.c 中定义访问器函数，以及在文件 size.c 中，它需要访问内部结构的大小。）

有关背景资料，请参阅 https://homepage.stat.uiowa.edu/~luke/R/barrier.html 和 https://homepage.stat.uiowa.edu/~luke/R/gengcnotes.html。

1.8 序列化格式 ¶

R 对象的序列化版本由 load/save 使用，并且在稍低级别由 saveRDS/readRDS（以及它们早期的“内部”点名版本）和 serialize/unserialize 使用。它们在序列化到的内容（文件、连接、原始向量）以及它们是用于序列化单个对象还是对象集合（通常是工作空间）方面有所不同。 save 在文件开头写入一个头文件（一行以 LF 结尾），而低级别版本则没有。

save 和 saveRDS 允许各种形式的压缩，并且 gzip 压缩是默认的（除了 ASCII 保存）。压缩应用于整个文件流，包括头文件，因此序列化文件可以通过外部程序解压缩或重新压缩。 load 和 readRDS 都可以在从文件读取时读取 gzip、bzip2 和 xz 形式的压缩，以及在从连接读取时读取 gzip 压缩。

从 2001 年 12 月的 R 1.4.0 到 2019 年 3 月的 R 3.5.3，R 一直使用相同的序列化格式，称为“版本 2”。它自创建以来以向后兼容的方式扩展，例如，支持额外的 SEXPTYPE。早期格式仍然通过 load 和 save 支持，但此处没有描述这些格式。当前默认的序列化格式称为“版本 3”，它是在 R 3.5.0 中引入的。

save 的工作原理是写入一个单行标题（通常对于二进制保存来说是 RDX2\n，当前唯一另一个值是 RDA2\n，用于 save(files=TRUE)），然后创建一个要保存对象的标记对列表，并序列化该单个对象。 load 读取标题行，反序列化单个对象（一个对列表或一个向量列表），并在指定的环境中分配对象的元素。标题行在 R 中有两个作用：它识别序列化格式，以便 load 可以切换到相应的读取器代码，而换行符 \n 允许检测经过非二进制传输且重新映射了行尾的文件。它也可以被认为是 file 程序中使用的“魔数”（尽管 R 保存文件目前默认情况下不被该程序识别）。

R 中的序列化需要考虑到对象可能包含对环境的引用，而这些环境又具有封闭环境，依此类推。（被识别为包或命名空间环境的环境按名称保存。）存在“引用对象”，它们在复制时不会被复制，并且应该在反序列化时保持共享。这些是弱引用、外部指针以及除与包、命名空间和全局环境相关的环境之外的其他环境。这些通过哈希表进行处理，第一个引用之后的引用以表项索引的引用标记形式写入。

版本 2 序列化首先写入一个指示格式的标题（通常对于 XDR 格式二进制保存来说是 ‘X\n’，但 ‘A\n’（ASCII）和 ‘B\n’（本机字序二进制）也可能出现），然后写入三个整数，分别表示格式的版本和两个 R 版本（由 Rversion.h 中的 R_Version 宏打包）。（反序列化将两个版本解释为写入文件的 R 版本，以及读取格式所需的最小 R 版本。）序列化然后使用 src/main/serialize.c 文件中的 WriteItem 函数递归地写入对象。

某些对象被写入，就好像它们是 SEXPTYPE 一样：此类伪 SEXPTYPE 包括 R_NilValue、R_EmptyEnv、R_BaseEnv、R_GlobalEnv、R_UnboundValue、R_MissingArg 和 R_BaseNamespace。

对于所有 SEXPTYPE，除了 NILSXP、SYMSXP 和 ENVSXP，序列化从一个整数开始，该整数在位 0:7 中包含 SEXPTYPE⁷，后面跟着对象位，两个位指示是否有任何属性以及是否有标签（对于配对列表类型），一个未使用的位，然后是 gp 字段⁸ 在位 12:27 中。配对列表类对象写入它们的属性（如果有），标签（如果有），CAR 然后是 CDR（使用尾递归）：其他对象在自身之后写入它们的属性。原子向量对象写入它们的长度，然后是数据：通用向量列表对象写入它们的长度，然后对每个元素调用 WriteItem。CHARSXP 的代码对 NA_STRING 进行特殊处理，并将其写入为长度 -1，没有数据。长度不超过 2^31 - 1 以这种方式写入，而更大的长度（仅在 64 位系统上出现）则以 -1 以及高 32 位和低 32 位作为整数（视为无符号）写入。

环境以多种方式处理：正如我们所见，一些环境被写入为特定的伪 SEXPTYPE。包和命名空间环境被写入为伪 SEXPTYPE，后面跟着名称。‘普通’环境被写入为 ENVSXP，其中包含一个整数，指示环境是否被锁定，后面跟着封闭环境、帧、‘标签’（哈希表）和属性。

在 ‘XDR’ 格式中，整数和双精度数以大端序写入：但是，该格式并非完全 XDR（如 RFC 1832 中所定义），因为字节数量（如 CHARSXP 和 RAWSXP 类型的內容）按原样写入，不会填充到 4 字节的倍数。

‘ASCII’ 格式写入 7 位字符。整数使用 %d 格式化（除了 NA_integer_ 被写入为 NA），双精度数使用 %.16g 格式化（加上 NA、Inf 和 -Inf），字节使用 %02x 格式化。字符串使用标准转义符（例如 \t 和 \013）来写入非打印字符和非 ASCII 字节。

版本 3 序列化通过支持 ALTREP 框架对象的自定义序列化来扩展版本 2。它还在序列化时存储当前的本机编码，以便在不同本机编码下运行的 R 中反序列化时，可以转换未标记的字符串。

1.9 CHARSXPs 的编码 ¶

R 中的字符数据存储在 sexptype CHARSXP 中。

除了当前区域设置的编码之外，还支持其他编码，特别是 UTF-8 和 Windows 用于 CJK 语言的多字节编码。指示 CHARSXP 编码的有限方法是通过两个“通用”位，这两个位用于声明编码为 Latin-1 或 UTF-8。（请注意，字符向量可能包含不同编码的元素。）打印和绘图都会注意到声明并将字符串转换为当前区域设置（可能使用 <xx> 以十六进制字节显示在当前区域设置中无效的字节）。许多（但并非全部）字符操作函数将保留声明或重新编码字符字符串。

引用操作系统的字符串（如文件名）需要在某些操作系统（例如 Windows）上通过宽字符接口传递。

何时声明字符字符串具有已知编码？一种方法是通过 Encoding 直接声明。如果已知，解析器将声明编码，无论是通过 parse 的 encoding 参数，还是从 R 命令行中进行解析的区域设置。（其他方法记录在 Encoding 的帮助页面上。）

没有必要声明 ASCII 字符串的编码，因为它们将在任何区域设置中工作。ASCII 字符串永远不应该有标记的编码，因为任何编码在将此类字符串输入 CHARSXP 缓存时都会被忽略。

仅考虑 UTF-8 和 Latin-1 的基本原理是，大多数系统能够生成 UTF-8 字符串，这是我们最接近通用格式的。对于那些没有（例如那些没有足够强大的 iconv 的系统），它们很可能在 Latin-1 中工作，这是旧的 R 假设。然后，解析器可以返回一个 UTF-8 编码的字符串，如果它遇到一个“\uxxxx”转义符，用于表示当前字符集中无法表示的 Unicode 点。（这需要 MBCS 支持，并且在过去仅在 Windows 上启用⁹。）现在，这已在所有平台上启用，并且“\uxxxx”或“\Uxxxxxxxx”转义符确保解析后的字符串将被标记为 UTF-8。

大多数字符操作函数现在保留 UTF-8 编码：在文件 src/main/character.c 的顶部和文件 src/library/base/man/Encoding.Rd 中有一些关于哪些函数保留 UTF-8 编码的说明。

图形设备可以通过将 hasTextUTF8 设置为 ‘TRUE’ 并提供期望 UTF-8 编码输入的函数 textUTF8 和 strWidthUTF8，来处理 UTF-8 编码的字符串，而无需重新编码为本地字符集。通常情况下，符号字体使用 Adobe Symbol 编码，但可以通过将 wantSymbolUTF8 设置为 ‘TRUE’ 将其重新编码为 UTF-8。cairographics 的 Windows 端口有一个相当奇怪的假设：它希望符号字体以 UTF-8 编码，就好像它以 Latin-1 而不是 Adobe Symbol 编码一样：这可以通过 wantSymbolUTF8 = NA_LOGICAL 来选择。

使用 MSVCRT 作为 C 运行时的 Windows 没有 UTF-8 本地化，而是期望使用 UCS-2¹⁰ 字符串。R（用标准 C 编写）在没有大量更改的情况下，不会在内部使用 UCS-2。 Rgui 控制台¹¹ 在内部使用 UCS-2，但以本地编码与 R 引擎通信。为了允许 UTF-8 字符串在 Rgui.exe 中以 UTF-8 格式打印，cat、print 和自动打印使用了一种转义约定（参见头文件 rgui_UTF8.h）。

‘Unicode’ (UCS-2LE) 文件在 Windows 世界中很常见，如果在传递给这些函数的未打开连接上显式声明编码，则 readLines 和 scan 会将它们读入 Windows 上的 UTF-8 字符串。

Windows 对当前区域设置编码有多种概念，一种是在 C 运行时（C 库）中，另一种是活动代码页（系统区域设置）。活动代码页在调用 Windows API 函数的非 UTF-16 变体（以前称为 ANSI 调用）时使用，无论是直接调用还是通过 MinGW-w64 中的 POSIX 包装器间接调用，从 R、R 包和它们链接到的库调用。虽然 R 通过直接调用 Windows API 的 UTF-16 变体处理了许多情况，但它有时仍然可能使用非 UTF-16 变体，并且主要为 POSIX 系统开发的外部库通常也这样做。因此，为了让 R 在 Windows 上可靠地处理（非 ASCII）字符串，Windows 上的 C 区域设置编码和活动代码页必须相同，默认情况下它们是相同的。

Windows UCRT C 运行时支持 UTF-8 本地化。从历史上看，活动代码页是一个系统范围的设置，更改它需要重新启动，并且不支持 UTF-8。后来，添加了一个“BETA：使用 Unicode UTF-8 进行全球语言支持”功能，将活动代码页设置为 UTF-8，但这仍然需要重新启动，并且会影响所有应用程序，其中许多应用程序无法正确使用此意外设置，因此它无法在实践中使用。

从 Windows 10（版本 1903）、Windows Server 2022（LTSC）和 Windows Server 1903（半年频道）开始，Windows 允许在应用程序清单中将活动代码页设置为 UTF-8。这仅更改给定应用程序的活动代码页，并且与将 UCRT C 区域设置更改为 UTF-8 一起进行。适用于 Windows 的 R 4.2 使用此功能在 Windows 上将 UTF-8 作为本地编码。为了实现这一点，R 必须切换到 UCRT，这反过来又需要创建 Rtools42。

旧版本的 Windows 仍然依赖于之前的编码支持，其中原生编码不能是 UTF-8。R 4.2 需要 UCRT 才能工作，但 UCRT 可以安装在 Windows Vista SP2 和 Windows Server 2008 SP2 及更高版本上。它从 Windows 10 和 Windows Server 2016 开始随 Windows 一起提供。

1.10 CHARSXP 缓存 ¶

有一个用于 CHARSXP 的全局缓存，该缓存由 mkChar 创建——缓存确保大多数具有相同内容的 CHARSXP 共享存储（“内容”包括任何声明的编码）。并非所有 CHARSXP 都是缓存的一部分——特别是“NA_STRING”不是。从 R 0.99.0 之前的 save 格式重新加载的 CHARSXP 不会被缓存（因为使用的代码是固定的，并且很少有示例仍然存在）。

缓存记录字符串的编码以及字节：所有创建 CHARSXP 的请求都应该通过调用 mkCharLenCE 来进行。如果字符串的字节都是 ASCII 字符，则在 mkCharLenCE 调用中给出的任何编码都将被忽略。

1.11 警告和错误 ¶

warning 和 stop 都有两个 C 级别的等效项，分别是 warning、warningcall、error 和 errorcall。这两对之间的关系类似：warning 尝试找出合适的调用，然后在成功时将该调用作为第一个参数调用 warningcall，如果失败则调用 call = R_NilValue。当调用 warningcall 时，它会在其打印输出中包含解语法后的调用，除非 call = R_NilValue。

warning 和 error 会查看上下文堆栈。如果最顶层的上下文不是 CTXT_BUILTIN 类型，则使用它来提供调用，否则下一个上下文提供调用。这意味着当从基本函数或 .Internal 调用这些函数时，推断的调用将不是对基本函数/.Internal 的调用，而是对调用基本函数/.Internal 的函数的调用。这正是人们对 .Internal 所期望的，因为它将提供对闭包包装器的调用。（此外，对于 .Internal，调用是 .Internal 的参数，因此可能不对应于任何 R 函数。）但是，对于基本函数来说，这不太可能是需要的。

简而言之，warningcall 和 errorcall 通常用于从基本函数调用的代码，而 warning 和 error 则用于从 .Internal（以及必然地从 .Call、.C 等，其中调用不会向下传递）调用的代码。但是，有两个复杂情况。一是代码可能从基本函数或 .Internal 中调用，在这种情况下，warningcall 可能更合适。另一个涉及替换函数，其中调用曾经是

> length(x) <- y ~ x
Error in "length<-"(`*tmp*`, value = y ~ x) : invalid value

这对于最终用户来说是不可接受的。对于替换函数，堆栈顶部将有一个合适的上下文，因此应使用 warning。（对于 .Internal 替换函数（如 substr<-）的结果并不理想。）

1.12 S4 对象 ¶

[本节目前为初步草案，不应视为最终版本。描述假设 R_NO_METHODS_TABLES 未设置。]

• S4 对象的表示
• S4 类
• S4 方法
• S4 调度的机制

 length(nM <- asNamespace("Matrix") )                    # 941 for Matrix 1.2-6
 length(meth <- grep("^[.]__T__", names(nM), value=TRUE))# 107 generics with methods
 length(meth.Ops <- nM$`.__T__Ops:base‘) # 71 methods for the ’Ops' (group)generic
 head(sort(names(meth.Ops))) ## "abIndex#abIndex" ... "ANY#ddiMatrix" "ANY#ldiMatrix" "ANY#Matrix"

1.13 内存分配器 ¶

R 的内存分配几乎全部通过文件 src/main/memory.c 中的例程完成。

R 的其余部分应尽可能使用文件 src/main/memory.c 提供的分配器，这也是 Writing R Extensions 中 内存分配 部分推荐在 R 包中使用的方法，即使用 R_alloc、R_Calloc、R_Realloc 和 R_Free。由 R_alloc 分配的内存将在调用 vmaxset 后重置“水位线”时由垃圾收集器释放。这由调用基本函数和 .Internal 函数的包装代码（以及 .Call 和 .External 的包装代码）自动完成，但 vmaxget 和 vmaxset 可用于在内部代码中重置水位线，如果内存仅在短时间内需要。

到目前为止提到的所有内存分配方法都比较昂贵。所有 R 平台都支持 alloca，并且在几乎所有情况下¹⁴，这是由编译器管理的，在 C 栈上分配内存，效率很高。

使用 alloca 有两个缺点。首先，它很脆弱，需要小心避免写入（甚至读取）返回的分配块的边界之外。其次，它增加了 C 栈溢出的风险。建议仅将其用于较小的分配（最多数万字节），并且

    R_CheckStack();

在分配后立即调用（因为 R 的栈检查机制会在距离栈限制足够远的地方发出警告，以允许适度使用 alloca）。（文件 src/main/unique.c 中的 do_makeunique 提供了这两个方面的示例。）

有一个替代检查，

    R_CheckStack2(size_t extra);

在尝试分配 extra 字节之前立即调用。

另一种策略已用于各种需要不同大小（但通常很小）的中间存储块的函数，并且已合并到头文件 src/main/RBufferUtils.h 中的例程中。这使用了一个包含缓冲区、当前大小和默认大小的结构。调用

    R_AllocStringBuffer(size_t blen, R_StringBuffer *buf);

将 buf->data 设置为至少 blen+1 字节的内存区域。至少使用默认大小，这意味着对于小的分配，可以使用相同的缓冲区。调用 R_FreeStringBufferL 会释放内存（如果分配的内存超过默认大小），而调用 R_FreeStringBuffer 会释放任何分配的内存。

需要初始化 R_StringBuffer 结构，例如：

static R_StringBuffer ex_buff = {NULL, 0, MAXELTSIZE};

它使用 MAXELTSIZE = 8192 字节的默认大小。大多数当前使用情况都具有静态的 R_StringBuffer 结构，这允许在调用例如 grep 以及函数之间共享（默认大小的）缓冲区：如果 R 允许并发评估线程，则需要更改此行为。因此，惯用法是

static R_StringBuffer ex_buff = {NULL, 0, MAXELTSIZE};
...
    char *buf;
    for(i = 0; i < n; i++) {
        compute len
        buf = R_AllocStringBuffer(len, &ex_buff);
        use buf
    }
    /*  free allocation if larger than the default, but leave
        default allocated for future use */
   R_FreeStringBufferL(&ex_buff);

• R_alloc 的内部机制

1.14 全局和基本环境的内部使用 ¶

本节记录系统对这些环境的已知使用情况：目的是尽量减少或消除此类使用。

• 基本环境
• 全局环境

1.15 模块 ¶

R 使用存储在 modules 目录中的多个共享对象/DLL。这些是代码的一部分，已选择按需加载，而不是作为动态库链接或合并到主可执行文件/动态库中。

对于其余模块，其动机是它们将通过链接到的库引入的（通常是可选的）代码量。via

internet

内部 HTTP 和 FTP 客户端以及套接字支持，它们链接到特定于系统的支持库。这可能会加载 libcurl，并且在 Windows 上将加载 wininet.dll 和 ws2_32.dll。

lapack

使用 LAPACK 库的代码，并链接到 libRlapack 或外部 LAPACK 库。

X11

（仅限类 Unix 系统。）X11()、jpeg()、png() 和 tiff() 设备。这些是可选的，并链接到一些或所有 X11、pango、cairo、jpeg、libpng 和 libtiff 库。

1.16 可见性 ¶

• 隐藏 C 入口点
• Windows DLL 中的变量

nm -g libR.so | grep ‘ [BCDT] ’ | cut -b20-

1.17 延迟加载 ¶

延迟加载始终用于包中的代码，但对于包中的数据集是可选的（由包维护者选择）。当使用延迟加载的包/命名空间被加载时，包/命名空间环境将填充所有命名对象的承诺：当这些承诺被评估时，它们将从数据库中加载实际的代码。

代码和数据有单独的数据库，存储在 R 和 data 子目录中。数据库由两个文件组成，name.rdb 和 name.rdx。 .rdb 文件是序列化对象的串联，而 .rdx 文件包含索引。对象存储在（通常）gzip 压缩格式中，带有 4 字节的头部，给出未压缩的序列化长度（以 XDR 格式，即大端字节序），并通过调用原始 lazyLoadDBfetch 函数读取。（请注意，这使得延迟加载不适合非常大的对象：R 对象的未序列化长度可能超过 4GB。）

索引或“映射”文件 name.rdx 是一个压缩的序列化 R 对象，由 readRDS 读取。它是一个包含三个元素的列表：variables、references 和 compressed。前两个是长度为 2 的整数向量的命名列表，给出序列化对象在 name.rdb 文件中的偏移量和长度。元素 variables 为每个命名对象提供一个条目：references 序列化一个临时环境，该环境在将命名环境添加到数据库时使用。 compressed 是一个逻辑值，指示序列化对象是否被压缩：如今总是使用压缩。我们后来添加了值 compressed = 2 和 3 用于 bzip2 和 xz 压缩（将来可能扩展到其他方法）：这些格式在标头中添加第五个字节以表示压缩类型，并在压缩扩展序列化对象时以未压缩形式存储它们。

出于性能原因，源引用被特殊处理：来自 srcfile 环境的绑定 lines 和 parseData 是延迟加载的。这使用了一种机制，允许从环境中延迟加载选定的绑定。此类环境的键是一个包含两个元素的列表：eagerKey 给出用于急切加载的绑定的长度为 2 的整数键，而 lazyKeys 给出一个长度为 2 的整数键向量，每个延迟加载的绑定一个。

用于代码或数据的延迟加载数据库的加载器是 base 包中的函数 lazyLoad，但请注意，在文件 R_HOME/base/R/base 中有一个单独的副本用于加载 base 本身。

延迟加载数据库由 src/library/tools/R/makeLazyLoad.R 中的代码创建：主要工具是未导出的函数 makeLazyLoadDB，数据库条目的插入通过调用 .Call("R_lazyLoadDBinsertValue", ...) 完成。

小于 10MB 的延迟加载数据库在第一次使用时会缓存在内存中：在使用具有高延迟的文件系统（可移动设备和 Windows 上的网络挂载文件系统）时发现这很有必要。

延迟加载数据库被加载到包的导出中，但不会加载到命名空间环境本身。因此，当包被 附加 时，它们是可见的，并且也 通过 :: 运算符可见。这是一个有意设计的决定，因为包主要使数据集可供最终用户（或其他包）使用，并且它们不应该优先从包中的函数中找到，这会让期望使用正常搜索路径的用户感到惊讶。（存在一种替代机制，sysdata.rda，用于主要用于包内的“系统数据集”。）

相同的数据库机制用于存储解析后的 Rd 文件。通过调用 tools:::fetchRdDB 获取一个或所有解析后的对象。

2.1 特殊基本类型 ¶

少数基本类型是特殊的，而不是内置的，也就是说它们以未求值的参数输入。对于语言结构和赋值运算符，以及对于&&和||（它们有条件地求值其第二个参数），以及~，.Internal，call，expression，missing，on.exit，quote和substitute（它们不求值其某些参数），这显然是必要的。

rep和seq.int是特殊的，因为它们根据哪些参数不缺失来求值其某些参数。

log，round和signif是特殊的，以允许为缺失参数提供默认值。

子集、子赋值和@运算符都是特殊的。（对于提取和替换形式，$和@接受符号参数，而[和[[允许缺失参数。）

UseMethod是特殊的，以避免对内置函数调用添加额外的上下文。

2.2 特殊内部函数 ¶

还有一些特殊的.Internal函数：NextMethod，Recall，withVisible，cbind，rbind（以允许使用deparse.level参数），eapply，lapply和vapply。

2.3 基本类型的原型 ¶

基本函数和运算符的原型可用，这些原型用于打印、args和包检查（例如，由tools::checkS3methods和包codetools）。在base包（和命名空间）中，有两个环境：‘.GenericArgsEnv’用于那些作为内部 S3 泛型的基本类型，以及‘.ArgsEnv’用于其余的基本类型。这些环境包含与基本类型同名的闭包，从帮助页面（手动）派生的形式参数，一个作为对UseMethod或NULL的适当调用的主体，以及基本命名空间的环境。

用于 print.default 和 args 的 C 代码优先使用这些环境中的闭包，而不是 base 中的定义（作为基本类型）。

QC 函数 undoc 检查这些环境中原型化的所有函数当前是否都是基本类型，以及未包含的基本类型是否更适合被视为语言元素（在撰写本文时）。

$  $<-  &&  (  :  @  @<-  [  [[  [[<-  [<-  {  ||  ~  <-  <<-  =
break  for function  if  next  repeat  return  while

人们可能会争论 ~，但它为解析器所知，其语义与普通函数完全不同。而 : 在其两种含义中使用不同的参数名称进行记录。

QC 函数 codoc 和 checkS3methods 也使用这些环境（实际上将它们放在 base 的搜索路径之前），因此它们包含的函数的形式参数由 codoc 根据帮助页面进行检查。但是，通用基本类型存在两个问题。第一个问题是，许多运算符是 S3 组通用 Ops 的一部分，并且定义了它们的参数为 e1 和 e2：虽然这很不寻常，但运算符可以像 "+"(e1=a, e2=b) 那样调用，如果方法调度发生在闭包上，则会发生参数名称不匹配。因此，环境 .GenericArgsEnv 中的定义必须使用参数名称 e1 和 e2，即使传统文档使用的是 x 和 y：codoc 通过 tools:::.make_S3_primitive_generic_env 进行适当的调整。第二个差异在于 Math 组通用类型，其中组通用类型定义的参数列表为 (x, ...)，但大多数成员在用作默认方法时只允许一个参数（而 round 和 signif 允许两个作为默认方法）：同样使用修复程序。

那些位于 .GenericArgsEnv 中的基本类型通过定义它们的方法进行检查（通过 tests/primitives.R）以确定它们是否为通用类型，并且通过设置方法并检查它是否未被调度到（但这可能因其他原因而失败）来检查剩余的基本类型可能不是通用类型。但是，除了阅读源代码之外，没有确定的方法可以知道其他 .Internal 或基本函数是否在内部是通用类型。

2.4 添加一个基本类型 ¶

[供 R 核心使用：反转此过程以移除一个基本类型。最常见的情况是将一个 .Internal 更改为基本类型或反之。]

基本类型列在 src/main/names.c 中的表 R_FunTab 中：基本类型在 ‘eval’ 字段中具有 ‘Y = 0’。

在 base 包中的帮助文件中需要有一个 ‘\alias’ 条目，并且需要将基本类型添加到本节开头列出的列表之一中。

一些基本类型被视为语言元素（当前列出的元素）。这些需要添加到两个异常列表中，langElts 在 undoc() 中（在文件 src/library/tools/R/QC.R 中）和 lang_elements 在 tests/primitives.R 中。

所有其他基本类型都被视为函数，应列在 src/library/base/R/zzz.R 中定义的环境之一中，即 .ArgsEnv 或 .GenericArgsEnv：内部泛型也需要列在字符向量 .S3PrimitiveGenerics 中。还要注意上面关于参数匹配的讨论：如果您通过转换 .Internal 添加了一个具有多个参数的基本类型函数，则需要在 C 代码中添加参数匹配，对于那些只有一个参数的函数，则需要添加参数名称检查。

请确保已运行 make check-devel：它测试了这些要求中的大多数。

3.1 R 代码 ¶

R 代码的国际化与扩展包的国际化方式完全相同。由于所有包含 R 代码的标准包也都有命名空间，因此无需指定 domain，但为了效率，当消息通过 gettextf、gettext 或 ngettext 构建时，对 message、warning 和 stop 的调用应包含 domain = NA。

对于每个包，提取的消息和翻译源存储在源包的包目录 po 下，编译后的翻译存储在 inst/po 下，以便安装到已安装包的包目录 po 下。这也适用于包中的 C 代码。

3.2 主 C 代码 ¶

主 C 代码（例如，在文件 src/*/*.c 和模块中的代码）是 R 最接近于为其编写 ‘gettext’ 的应用程序类型的地方。主 C 代码中的消息位于域 R 中，并存储在顶级目录 po 下，编译后的翻译存储在 share/locale 下。

R 域涵盖的文件列表在文件 po/POTFILES.in 中指定。

标记要翻译的消息的正常方法是使用 _("msg")，就像包一样。但是，有时需要标记要翻译的段落，而不想在此时进行翻译，例如，在声明字符串常量时。这就是 N_ 宏的用途，例如

{ ERROR_ARGTYPE,           N_("invalid argument type")},

来自文件 src/main/errors.c。

宏 P_

#ifdef ENABLE_NLS
#define P_(StringS, StringP, N) ngettext (StringS, StringP, N)
#else
#define P_(StringS, StringP, N) (N > 1 ? StringP: StringS)
#endif

可用作 ngettext 的包装器：但是，在某些情况下，首选方法是使用 ngettext 对代码进行条件化（在 ENABLE_NLS 上）。

宏 _("msg") 可以安全地用于目录 src/appl 中；独立 ‘nmath’ 的头文件跳过了可能的翻译。（这并不适用于 N_ 或 P_）。

3.3 Windows-GUI 特定代码 ¶

Windows GUI 的消息位于单独的域“RGui”中。这样做有两个原因：

• Windows 版本的 R 的翻译人员可能与其他 R 版本的翻译人员不同（熟悉 GUI 有助于），以及
• Windows 的消息最自然地以语言的本机字符集处理，对于 CJK 语言，字符集是 Windows 特定的。（事实证明，由于我们移植的 iconv 在 Windows 下运行良好，因此这不像预期的那样重要。）

“RGui”域的消息由 G_("msg") 标记，这是一个在头文件 src/gnuwin32/win-nls.h 中定义的宏。要考虑的文件列表在文件 src/library/tools/R/translations.R 中的函数 update_RGui_po 中硬编码，该函数通过文件 po/Makefile.win 中的 update-RGui 目标调用：请注意，这包括 devWindows.c，因为 windows 设备上的菜单被认为是 GUI 的一部分。（还有 GN_("msg")，它是 N_("msg") 的类似物。）

“RGui”域的模板和消息目录位于包 base 的顶层 po 目录中。

3.4 macOS GUI ¶

这是单独处理的：请参阅 https://developer.r-project.org/Translations30.html。

3.5 更新 ¶

有关如何更新消息模板和目录，请参阅文件 po/README。

4.1 元数据 ¶

目录 Meta 包含几个 .rds 格式的文件，即由 saveRDS 写入的序列化 R 对象。所有包都有文件 Rd.rds, hsearch.rds, links.rds, features.rds 和 package.rds。具有命名空间的包有一个文件 nsInfo.rds，而具有数据、演示或小插图的包则有 data.rds, demo.rds 或 vignette.rds 文件。

这些文件的结构（以及它们的存在和名称）对 R 来说是私有的，因此这里的描述是针对那些试图跟踪 R 源代码的人：在非基础包中不应该引用这些文件。

文件 package.rds 是从 DESCRIPTION 文件中提取的信息的转储。它是一个包含多个组件的列表。第一个是“DESCRIPTION”，是一个字符向量，表示 read.dcf 读取的 DESCRIPTION 文件。后面的元素“Depends”、“Suggests”、“Imports”、“Rdepends” 和 “Rdepends2” 记录了“Depends”、“Suggests” 和 “Imports” 字段。这些都是列表，可以为空。前三个列表中每个包都有一个条目，每个条目都是一个长度为 1 或 3 的列表，其中包含元素“name”（包名）以及可选元素“op”（一个字符字符串）和“version”（一个类为“"package_version"”的对象）。元素“Rdepends” 用于第一个 R 版本依赖项，而“Rdepends2” 是一个包含零个或多个 R 版本依赖项的列表，每个依赖项都是一个三元素列表，其形式与包的描述相同。元素“Rdepends” 已经不再使用，但它仍然可能需要，以便 R < 2.7.0 可以检测到该包没有为其安装。

文件 nsInfo.rds 记录了一个列表，它是 NAMESPACE 文件的解析版本。

文件 Rd.rds 记录了一个数据框，其中每行对应一个帮助文件。列包括“File”（带扩展名的文件名）、“Name”（“\name” 部分）、“Type”（来自可选的“\docType” 部分）、“Title”、“Encoding”、“Aliases”、“Concepts” 和 “Keywords”。除了“Aliases” 是一个字符向量列表之外，所有列都是字符向量。

文件 hsearch.rds 记录了由 ‘help.search’ 使用的信息。这是一个包含四个未命名元素的列表，它们是帮助文件、别名、关键字和概念的字符矩阵。所有矩阵都有 ‘ID’ 和 ‘Package’ 列，用于将别名、关键字和概念（后三个元素的剩余列）与特定的帮助文件关联。第一个元素还有 ‘LibPath’（存储为 "" 并填充文件加载的位置）、‘name’、‘title’、‘topic’（第一个别名，用于在将结果呈现为 ‘pkgname::topic’ 时使用）和 ‘Encoding’ 列。

文件 links.rds 记录了一个命名的字符向量，名称是别名，值是形式为

"../../pkgname/html/filename.html"

文件 data.rds 记录了一个包含两列的字符矩阵，列分别是数据集名称和对应帮助文件中的标题。文件 demo.rds 对包演示具有相同的结构。

文件 vignette.rds 记录了一个数据框，每个 ‘vignette’ (.[RS]nw 文件在 inst/doc 中) 对应一行，并包含 ‘File’（源代码中的完整文件路径）、‘Title’、‘PDF’（已安装的 PDF 版本的无路径文件名，如果存在）、‘Depends’、‘Keywords’ 和 ‘R’（已安装的 R 代码的无路径文件名，如果存在）列。

4.2 帮助 ¶

所有已安装的包，无论它们是否有任何 .Rd 文件，都具有 help 和 html 目录。后者通常只包含单个文件 00Index.html，即包索引，其中包含指向帮助主题（如果有）的超链接。

目录 help 包含文件 AnIndex、paths.rds 和 pkgname.rd[bx]。后两个文件是解析后的 .Rd 文件的延迟加载数据库，由 tools:::fetchRdDB 访问。文件 paths.rds 是保存的 .Rd 文件的原始路径名称的字符向量，用于更新数据库时使用。

文件 AnIndex 是一个两列制表符分隔的文件：第一列包含帮助文件中定义的别名，第二列包含包含该别名的文件的基名（不带 .Rd 或 .rd 扩展名）。它由 utils:::index.search 读取以搜索与主题（别名）匹配的文件，并由 scan 在 utils:::matchAvailableTopics 中读取，它是完成系统的一部分。

文件 aliases.rds 与 AnIndex 中的信息相同，但以命名字符向量形式表示（名称为主题，值为文件名基名），以便更快地访问。

6.1 图形设备 ¶

R 附带了几个图形设备，并且支持第三方包提供额外的设备——现在已经有几个包提供了。本节从图形设备编写者的角度描述了设备内部结构。

• 设备结构
• 设备功能
• 处理文本
• 约定
• ‘模式’
• 图形事件
• 特定设备

typedef struct _GEDevDesc GEDevDesc;
struct _GEDevDesc {
    pDevDesc dev;
    Rboolean displayListOn;
    SEXP displayList;
    SEXP DLlastElt;
    SEXP savedSnapshot;
    Rboolean dirty;
    Rboolean recordGraphics;
    GESystemDesc *gesd[MAX_GRAPHICS_SYSTEMS];
    Rboolean ask;
}

    pGEDevDesc gdd;

    R_GE_checkVersionOrDie(R_GE_version);
    R_CheckDeviceAvailable();
    BEGIN_SUSPEND_INTERRUPTS {
        pDevDesc dev;
        /* Allocate and initialize the device driver data */
        if (!(dev = (pDevDesc) calloc(1, sizeof(DevDesc))))
            return 0; /* or error() */
        /* set up device driver or free ‘dev’ and error() */
        gdd = GEcreateDevDesc(dev);
        GEaddDevice2(gdd, "dev_name");
    } END_SUSPEND_INTERRUPTS;

int R_GE_getVersion(void);
void R_GE_checkVersionOrDie(int version);

void text(double x, double y, const char *str, double rot, double hadj,
          pGgcontext gc, pDevDesc dd);

double strWidth(const char *str, pGEcontext gc, pDevDesc dd);

void metricInfo(int c, pGEcontext gc,
               double* ascent, double* descent, double* width,
               pDevDesc dd);

    Rboolean Unicode = mbcslocale && (gc->fontface != 5);
    if (c < 0) { Unicode = TRUE; c = -c; }
    if(Unicode) UniCharMetric(c, ...); else CharMetric(c, ...);

double xCharOffset;
double yCharOffset;
double yLineBias;
double cra[2];

dd->cra[0] = 0.9 * fnsize;
dd->cra[1] = 1.2 * fnsize;

    /* Character Addressing Offsets */
    /* These offsets should center a single */
    /* plotting character over the plotting point. */
    /* Pure guesswork and eyeballing ... */

    dd->xCharOffset =  0.4900;
    dd->yCharOffset =  0.3333;
    dd->yLineBias = 0.2;

    void glyph(int n, int *glyphs, double *x, double *y, 
               SEXP font, double size,
               int colour, double rot, pDevDesc dd);

     * device_Mode is called whenever the graphics engine
     * starts drawing (mode=1) or stops drawing (mode=0)
     * GMode (in graphics.c) also says that
     * mode = 2 (graphical input on) exists.
     * The device is not required to do anything

6.2 颜色 ¶

设备接收颜色作为 typedef rcolor（一个 unsigned int），定义在头文件 R_ext/GraphicsEngine.h 中）。4 个字节分别是 R ,G, B 和 alpha，从最低有效位到最高有效位。因此，RGB 的每个值都有 256 个亮度级别，从 0 到 255。alpha 字节表示不透明度，因此值 255 表示完全不透明，0 表示完全透明：许多但并非所有设备都处理半透明颜色。

可以在 C 中使用宏 R_RGBA 创建颜色，并且在 R_ext/GraphicsDevice.h 中定义了一组宏来提取各种组件。

基本图形系统中的颜色最初是从 S（以及之前的贝尔实验室的 GRZ 库）中采用的，其概念是使用数字“1...N”加上“0”（当前设备的背景颜色）来引用（可变大小的）颜色调色板。R 引入了通过字符字符串引用颜色的想法，形式可以是“#RRGGBB”或“#RRGGBBAA”（以十六进制表示字节），如函数 rgb() 所示，或者通过名称：657 个已知名称在字符向量 colors 中给出，并在包 grDevices 的文件 colors.c 中的表格中给出。请注意，半透明颜色不是“预乘的”，因此 50% 透明的白色是“#ffffff80”。

整数或字符 NA 颜色在内部映射到透明白色，字符字符串 "NA" 也是如此。

负颜色数字是错误。大于“N”的颜色会循环，例如，对于大小为 8 的默认调色板，颜色“10”是调色板中的颜色“2”。

整数颜色比基本图形子系统使用得更广泛，因为它们受包 grid 支持，因此也受 lattice 和 ggplot2 支持。（它们也受包 rgl 支持。）grid 重新定义了颜色“0”为透明白色，但 rgl 使用了 col2rgb，因此使用了基本图形的背景颜色。

请注意，正整数颜色引用当前调色板，颜色“0”引用当前设备（如果需要，会打开一个设备）。这些在使用时映射到类型 rcolor：这在重新播放显示列表时很重要，例如，当设备大小调整或使用 dev.copy 时。调色板应被视为每个会话的：它存储在包 grDevices 中。

惯例是设备使用“sRGB”色彩空间。这是一个行业标准：它被所有除高端数码相机以外的网页浏览器和 JPEG 使用。解释是图形设备和操作颜色的代码的事情，而不是图形引擎或子系统的事情。

R 使用类似于 PostScript 和 PDF 的绘画模型。这意味着，当形状（圆形、矩形和多边形）既可以填充又可以有描边边界时，应该先填充，然后描边（否则只有半边边界可见）。当填充和边界都是半透明时，对意图的解释有一定的空间。大多数设备首先绘制填充，然后绘制边界，在每一步都进行 alpha 混合。但是，PDF 会对对象进行一些自动分组，并且当填充和边界具有相同的 alpha 时，它们会被绘制到同一层上，然后在一步中进行 alpha 混合。（参见 PDF 参考第六版第 569 页，版本 1.7。不幸的是，虽然这是 PDF 标准规定应该发生的事情，但它没有被一些查看器正确实现。）

从颜色编号到类型 rcolor 的映射主要由函数 RGBpar3 完成：它从 R 二进制文件导出，但链接到包 grDevices 中的代码。第一个参数是指向字符、整数或双精度向量 SEXP，第二个参数是颜色 0（或 "0"）的 rcolor 值。C 入口点 RGBpar 是一个包装器，它将 0 视为透明白色：它通常用于为设备设置颜色默认值。R 级别的包装器是 col2rgb。

还有 R_GE_str2col，它接受一个 C 字符串并将其转换为类型 rcolor："0' 被转换为透明白色。

有一个 R 级别的颜色转换为“##RRGGBBAA”的转换，由 image.default(useRaster = TRUE) 完成。

API 中另一个颜色转换入口点是 name2col，它接受一个颜色名称（C 字符串）并返回一个 rcolor 类型的值。它处理 "NA"、"transparent" 和 R 函数 colors() 中已知的 657 种颜色。

6.3 基础图形 ¶

基础图形系统在 R 3.0.0 中迁移到包 graphics：它之前是在 src/main 中的文件中实现的。

出于历史原因，它主要在两层实现。文件 plot.c、plot3d.c 和 par.c 包含实现基本图形操作的约 30 个 .External 调用的代码。然后，此代码调用以 G 开头的名称的函数，这些函数在文件 graphics.c 中的标题 Rgraphics.h 中声明，进而调用图形引擎（其函数几乎都以 GE 开头）。

基础图形子系统的很大一部分基础设施是图形参数（由 par() 设置/读取）。这些参数存储在私有标题 Graphics.h 中声明的 GPar 结构中。此结构有两个变量（state 和 valid）跟踪设备上基础子系统的状态，以及许多记录图形参数及其函数的变量。

基础系统状态包含在私有标题 GraphicsBase.h 中定义的 baseSystemState 结构中。它包含三个 GPar 结构和一个布尔变量，用于记录 plot.new()（或 persp）是否已在设备上成功使用。

三个 GPar 结构的副本用于存储当前参数（通过 gpptr 访问）、“设备副本”（通过 dpptr 访问）以及保存的“设备副本”参数的副本的空间。当前参数显然是当前正在使用的参数，并在每次调用 plot.new() 时从“设备副本”中复制（无论是否前进到下一“页”）。保存的副本保留设备上次完全清除时的状态（例如，当 plot.new() 以 par(new=TRUE) 调用时），并用于重播显示列表。

分离并不完全干净：如果通过 plot.window() 设置了带有对数刻度的绘图，则“设备副本”会发生改变。

在 graphics.c 中的 static 变量中还有另一个大多数图形参数的副本，这些副本用于在处理高级图形调用中的内联参数（由 ProcessInlinePars 处理）时保留当前参数。

基本子系统的快照记录了 GPar 结构的“保存的设备副本”。

• 参数和参数

6.4 网格图形 ¶

[至少提供指向文档的指针。]

7.1 R.app ¶

R.app 是一个提供控制台的 macOS 应用程序。它的源代码是一个独立的项目²¹，它的二进制文件链接到一个 R 安装，它作为动态库 libR.dylib 运行。macOS 的标准 CRAN 分发版捆绑了 GUI 和 R 本身，但安装 GUI 是可选的，这两个组件都可以单独更新。

R.app 依赖于 libR.dylib 位于特定位置，因此依赖于 R 作为 Mac macOS 的“框架”构建和安装。具体来说，它使用 /Library/Frameworks/R.framework/R。这是一个符号链接，因为框架可以包含多个版本的 R。它最终解析为 /Library/Frameworks/R.framework/Versions/Current/Resources/lib/libR.dylib，它（在 CRAN 发行版中）是一个包含多个子体系结构的“胖”二进制文件。

macOS 应用程序是目录树：每个 R.app 包含一个用 Objective-C 编写的针对一个子体系结构的前端：在标准发行版中，有针对 32 位和 64 位 Intel 体系结构的独立应用程序。

最初，R 源代码包含大量仅由 macOS GUI 使用的代码，但这些代码已迁移到 R.app 源代码中。

R.app 将 R 作为嵌入式应用程序启动，其命令行包含 --gui=aqua（见下文）。它使用在头文件 Rinterface.h 中定义的大多数接口指针，以及文件 src/main/sysutils.c 中的私有接口指针。它在搜索路径的第二个位置添加了一个名为 tools:RGUI 的环境。这包含许多用于支持菜单项的实用函数，例如 package.manager()，以及函数 q() 和 quit()，它们屏蔽了包 base 中的那些函数——自定义版本以特定于 R.app 的方式保存历史记录。

R 有一个 configure 选项 --with-aqua 用于自定义 R 的构建方式：这与 --enable-R-framework 选项不同，后者会导致 make install 将 R 安装为使用 R.app 所需的框架。（选项 --with-aqua 是 macOS 上的默认选项。）它在 config.h 中设置宏 HAVE_AQUA，并在 make 变量 BUILD_AQUA_TRUE 中设置。这些有几个后果

• 设备 quartz() 在包 grDevices 中构建（除了作为存根）：这需要一个 Objective-C 编译器。然后，只要终端 R 可以访问 macOS 屏幕，就可以使用 quartz()。
• 文件 src/unix/aqua.c 已编译。这现在只包含设备 quartz() 的接口指针。
• capabilities("aqua") 设置为 TRUE。
• 个人库目录的默认路径设置为 ~/Library/R/arch/x.y/library。
• 在等待 system() 返回时，支持设置“繁忙”指示器。
• 在来自 parallel 包的派生子进程中，R_ProcessEvents 被抑制。R.app 中的关联回调执行了不应该在子进程中执行的操作，并且派生会派生整个进程，包括控制台。
• 支持使用选项 --gui=aqua 启动嵌入式 R：当执行此操作时，全局 C 变量 useaqua 被设置为真值。这会产生一些后果
  • 通过 R_Interactive 断言 R 会话是交互式的。
  • .Platform$GUI 被设置为 "AQUA"。这会产生一些后果
    • 如果环境变量 DISPLAY 未设置，则将其设置为 ‘:0’。
    • /usr/local/bin 被追加到 PATH，因为 gfortran 安装在该目录下。
    • 默认的 HTML 浏览器被切换到 R.app 中的浏览器。
    • 各种小部件被切换到 R.app 中提供的版本：这些包括图形菜单、数据编辑器（但不包括 View() 使用的数据查看器）以及由 browseEnv() 调用的工作区浏览器。
    • grDevices 包在加载时知道它正在 R.app 下运行，因此会通知任何 quartz 设备，Quartz 事件循环已经在运行。
  • 操作系统 system 函数的使用（包括 system() 和 system2()，以及启动编辑器和分页器）被 R.app 中的版本替换（默认情况下，它只是调用操作系统的 system，并重置各种信号处理程序）。
• 如果 R 是通过 --gui=aqua 启动的，或者 R 在非 ‘dumb’ 类型终端中运行，则发送到文件 stdout 和 stderr 的标准输出将通过 C 函数 Rstd_WriteConsoleEx 传输。这使用 ANSI 终端转义序列将发送到 stderr 的行在 stdout 上以粗体显示。
• 出于历史原因，启动选项 -psn 被允许但会被忽略。（似乎在 2003 年，‘r27492’，这是由 Finder 添加的。）

12.1 长向量 ¶

R 2.x.y 中的向量长度限制为 2^31 - 1 个元素（约 20 亿），因为长度存储在 SEXPREC 中，作为 C int，并且该类型被广泛用于记录长度和元素编号，包括在包中。

请注意，在 32 位平台下，更长的向量实际上是不可能的，因为它们有地址限制，因此本节仅适用于 64 位平台。在 32 位版本的 R 中，内部结构保持不变。

如果单个对象具有 2^31 个或更多元素，则如果为整数或逻辑类型，则至少占用 8GB 内存，如果为数值或字符类型，则占用 16GB 内存，因此常规使用此类对象还需要一段时间。

现在对长向量有一些支持。这适用于原始、逻辑、整数、数值和字符向量，以及列表和表达式向量。（字符向量 (CHARSXP) 的元素仍然限制为 2^31 - 1 字节。）一些注意事项

• 这是通过将长度（和真实长度）记录为 -1 并将实际长度记录为标题开头的 64 位字段来实现的。由于 R 中相当多的代码使用带符号类型来表示长度，因此“长长度”使用带符号的 C99 类型 ptrdiff_t 记录，该类型被 typedef 为 R_xlen_t。
• 理论上，这些可以具有 63 位长度，但请注意，当前的 64 位操作系统甚至在理论上也不提供 64 位地址空间，并且目前存在 52 位限制（这超过了当前操作系统的理论限制，并确保此类长度可以精确地存储在双精度浮点数中）。
• 序列化格式已更改以适应更长的长度，但长度高达 2^31-1 的向量以与以前相同的方式存储。更长的向量将其长度字段设置为 -1，后面跟着两个 32 位字段，分别给出实际长度的较高 32 位和较低 32 位。目前有一个健全性检查，在反序列化时将长度限制为 2^48。
• 类型 R_xlen_t 在 C 头文件 Rinternals.h 中提供给包：这在 C 代码中应该没问题，因为需要 C99。人们确实尝试在 C++ 中使用 R 内部函数，但 C++98 编译器不需要支持这些类型。
• 索引可以通过使用双精度浮点数来完成。内部索引代码以前使用正整数索引（负数、逻辑和矩阵索引都转换为正整数）：它现在可以使用 INTSXP 或 REALSXP 索引。
• 如果长度超过 2^31-1，R 函数 length 将返回一个双精度浮点值。在传递给 .C/.Fortran 之前调用 as.integer(length(x)) 的代码应该检查 NA 结果。

12.2 64 位类型 ¶

也有一些愿望能够在 R 中存储更大的整数，尽管将这些整数存储为 double 的可能性经常被忽视（例如，由 seek 返回的文件指针已经存储为 double）。

已经提出了不同的路线

• 向 R 添加一种新类型，并将其用于长度和索引 - 最有可能的是一个 64 位有符号类型，例如 longint。R 的通常隐式强制规则将确保为索引或 length<- 提供一个 integer 向量可以正常工作。
• 一个更激进的方案是将现有的 integer 类型在 64 位平台上改为 64 位（S-PLUS 对 DEC/Compaq Alpha 系统采用的就是这种方法）。或者在所有平台上都这样做。
• 允许长度和索引使用 integer 或 double 值，并在必要时返回 double。

第三种方案的优点是，对现有代码的干扰最小，并且不会增加内存需求。在第一种和第三种方案中，R 的代码和用户代码都需要适应非 integer 类型的长度，而在第三种方案中，长向量的代码分支很少被测试。

大多数 .C 和 .Fortran 接口的用户使用 as.integer 来表示长度和元素编号，但少数用户会省略这些，因为他们知道这些是 integer 类型的。可以合理地假设这些永远不会用于长向量。

其余的接口需要处理更改后的 VECTOR_SEXPREC 类型。似乎在大多数情况下，长度是通过 length 和 LENGTH 函数²⁶ 访问的。当前的方法是保持这些函数返回 32 位长度，并引入“长”版本 xlength 和 XLENGTH，它们返回 R_xlen_t 值。

另请参见 https://homepage.cs.uiowa.edu/~luke/talks/useR10.pdf.

12.3 大型矩阵 ¶

矩阵存储为向量，因此也限制为 2^31-1 个元素。现在，在 64 位平台上允许更长的向量，支持具有更多元素的矩阵，只要每个维度不超过 2^31-1。但是，并非所有应用程序都支持。

主要问题是使用 32 位 INTEGER 编译的 Fortran 代码执行的线性代数。虽然没有保证，但似乎目前在 64 位平台上与 R 一起使用的所有编译器都允许每个维度小于 2^31 但具有 2^31 个或更多元素的矩阵，并正确地对其进行索引，并且大部分支持软件（例如 BLAS 和 LAPACK）也能正常工作。

存在例外情况：例如，一些复杂的 LAPACK 辅助例程确实使用单个 INTEGER 索引，因此会静默溢出并导致段错误或给出错误的结果。一个已知的例子是在复数矩阵上使用 svd() 函数。

由于这是实现相关的，因此优化的 BLAS 和 LAPACK 可能存在进一步的限制：在使用 ATLAS 在 ‘x86_64’ Linux 上运行 svd() 函数时，已报告出现段错误。

对于大型矩阵的矩阵代数运算，几乎肯定需要一台具有大量内存（数百 GB）、多个核心和多线程 BLAS 的机器。