R 內部結構 ¶

1.1 SEXP ¶

R 使用者認為的變數或物件是繫結到值的符號。該值可以視為SEXP（指標）或其指向的結構SEXPREC（且有其他形式用於向量，即指向VECTOR_SEXPREC結構的VECSXP）。因此，R 物件的基本建構區塊通常稱為節點，意指SEXPREC或VECTOR_SEXPREC。

請注意，SEXPREC的內部結構並未公開給 R 擴充套件：SEXP反而是個不透明指標，且內部結構只能透過提供的函式存取。

兩種節點結構的前三個欄位都是 64 位元sxpinfo標頭，然後是三個指標（指向屬性、前一個節點和雙向連結清單中的下一個節點），然後是一些其他欄位。在 32 位元平台上，節點¹佔用 32 個位元組：在 64 位元平台上，通常為 56 個位元組（視對齊限制而定）。

sxpinfo 標頭的前 5 個位元指定多達 32 個 SEXPTYPE 之一。

• SEXPTYPE
• 標頭的其餘部分
• 「資料」
• 配置類別

#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 來源中記載，但顯然是指以前在 https://www.omegahat.net/RObjectTables/ 可用的 RObjectTable 套件。

基本環境很特別。有一個封裝為空環境 R_EmptyEnv 的 ENVSXP 環境，但該環境的框架並未被使用。反之，它的繫結是全域符號表的部份，是全域符號表中值不是 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–6 頁) 提供了一些指導方針。純量函數（逐一元件對向量執行的函數，其輸出與輸入類似）應保留屬性（可能除了類別，如果保留類別，則需要保留 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 中的函數有 3 種類型，封閉函數 (SEXPTYPE CLOSXP)、特殊函數 (SPECIALSXP) 和內建函數 (BUILTINSXP)。在本節中，我們考慮函數呼叫的實際參數何時 (以及是否) 進行評估。內部 (特殊/內建) 函數和 R 層級函數 (封閉函數) 的規則不同。

對於封閉的呼叫，實際和形式的引數會進行比對，並建構一個比對的呼叫（另一個 LANGSXP）。此程序首先將實際的引數清單替換為對所提供值的承諾清單。接著建構一個新的環境，其中包含比對到實際或預設值的正式參數名稱：所有比對的值都是承諾，預設值是承諾在剛建立的環境中進行評估。然後該環境用於評估函式的本體，並且在遇到承諾時會強制執行（因此評估實際或預設的引數）。（評估承諾會在其值上設定 NAMED = NAMEDMAX，因此如果引數是符號，則在評估封閉呼叫期間，其繫結會被視為具有多個參考。）[NAMED 機制已由參考計數取代。]

如果封閉是一個 S3 通用函式（也就是包含對 UseMethod 的呼叫），則評估程序會相同，直到遇到 UseMethod 呼叫。在那個時間點，用於進行分派的引數（通常是第一個）會在尚未評估的情況下進行評估。如果已找到一個是封閉的方法，則會為其建立一個新的評估環境，其中包含方法的比對引數，以及在評估通用函式本體期間迄今定義的任何新變數。（請注意，這表示在呼叫方法時，會捨棄對通用函式本體中正式引數值的變更，但已強制的實際引數承諾會保留在強制執行時找到的值。另一方面，遺失的引數具有承諾使用由方法而非通用函式提供的預設值的承諾。）如果找到的方法是基本方法，則會使用通用函式使用的比對的承諾引數清單（可能已強制執行）來呼叫該方法。

特殊函數和內建函數的本質區別⁵在於，特殊函數的參數在呼叫 C 程式碼之前不會被評估，而內建函數的參數會。請注意，特殊函數/內建函數與原始函數或 .Internal 是分開的：quote 是特殊原始函數，+ 是內建原始函數，cbind 是特殊 .Internal，而 grep 是內建 .Internal。

許多內部函數是內部泛函數，對特殊函數來說，表示它們在呼叫時不會評估其參數，但 C 程式碼會從呼叫 DispatchOrEval 開始。後者會評估第一個參數，並根據其類別尋找方法。（如果 S4 分派開啟，即使對於 S3 類別，也會先尋找 S4 方法。）如果找到方法，它會根據承諾評估剩餘參數的呼叫，將其分派到該方法。如果找不到方法，則在返回到內部泛函數之前評估剩餘參數。

內部函數可以成為泛函數的另一種方式是成為群組泛函數。大多數此類函數都是內建函數（因此會立即評估其所有參數），並且都包含呼叫 C 函數 DispatchGeneric。對於 "Math" 群組泛函數的參數數量有一些特殊情況，有些成員只允許一個參數，有些有兩個（第二個參數有預設值），而 trunc 允許一個或多個，但預設方法只接受一個。

• 遺失值
• 點點點參數

argument "foobar" is missing, with no default

1.6 自動列印 ¶

頂層 R 表達式的傳回值是否列印是由全域布林變數 R_Visible 控制。根據檔案 src/main/names.c 中表格的 eval 欄，在進入所有基本和內部函數時設定（為 true 或 false）：適當的設定可以透過巨集 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。）除非允許 C 程式碼變更（上述例外情況由值為 2 的 PRIMPRINT 指示），否則內部和基元函數會強制執行回傳時 R_Visible 的文件設定。

實際的自動列印是由 PrintValueEnv 在檔案 print.c 中完成的。如果要列印的物件設定了 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 中。若要啟用對存取方式的檢查，可以使用旗標 --enable-strict-barrier 編譯 R，這可確保標頭 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 壓縮。

R 從 2001 年 12 月的 R 1.4.0 到 2019 年 3 月的 R 3.5.3 使用相同的序列化格式，稱為「版本 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 除外），序列化從一個整數開始，其中 SEXPTYPE 位於位元 0:7⁷，後面接著物件位元、兩個位元表示是否有任何屬性，以及是否有標籤（對於 pairlist 類型），一個未使用的位元，然後是位元 12:27 中的 gp 欄位⁸。 類似 pairlist 的物件會寫入其屬性（如果有）、標籤（如果有）、CAR，然後是 CDR（使用尾端遞迴）：其他物件會在自身之後寫入其屬性。原子向量物件會寫入其長度，後面接著資料：一般向量清單物件會寫入其長度，後面接著對每個元素呼叫 WriteItem。 CHARSXP 的程式碼會針對 NA_STRING 進行特殊處理，並將其寫入為長度 -1，沒有資料。長度不超過 2^31 - 1 會以這種方式寫入，而較長的長度（僅出現在 64 位元系統中）會寫入為 -1，後面接著上、下 32 位元作為整數（視為未簽署）。

環境以多種方式處理：正如我們所見，有些寫成特定的偽 SEXPTYPE。套件和名稱空間環境寫成偽 SEXPTYPE，後接名稱。「正常」環境寫成 ENVSXP，其中整數表示環境是否已鎖定，後接封裝、框架、「標籤」（雜湊表）和屬性。

在「XDR」格式中，整數和雙精度數寫成大端序：但格式並非完全 XDR（如 RFC 1832 所定義），因為位元組數量（例如 CHARSXP 和 RAWSXP 類型的內容）寫成原樣，未填充至四個位元組的倍數。

「ASCII」格式寫入 7 位元字元。整數格式化為 %d（但 NA_integer_ 寫成 NA），雙精度數格式化為 %.16g（加上 NA、Inf 和 -Inf），位元組格式化為 %02x。字串使用標準跳脫字元（例如 \t 和 \013）寫入非列印和非 ASCII 位元組。

版本 3 序列化擴充版本 2，支援 ALTREP 框架物件的客製化序列化。它也會在序列化時儲存目前的原生編碼，這樣未標記的字串可以在不同原生編碼下執行的 R 中反序列化時轉換。

1.9 CHARSXPs 的編碼 ¶

R 中的字元資料儲存在 sexptype CHARSXP 中。

支援除了目前區域設定以外的編碼，特別是 UTF-8 和 Windows 上用於中日韓語言的多位元組編碼。表示 CHARSXP 編碼的有限方法是透過兩個用於宣告編碼為 Latin-1 或 UTF-8 的「一般用途」位元。 (請注意，字元向量有可能包含不同編碼的元素。) 列印和繪圖都會注意到宣告並將字串轉換為目前區域設定 (可能使用 <xx> 以十六進位位元組顯示目前區域設定中無效的位元組)。許多 (但不是全部) 字元處理函數將保留宣告或重新編碼字串。

參照作業系統的字串 (例如檔案名稱) 需要在某些作業系統 (例如 Windows) 上透過寬字元介面傳遞。

字元字串何時宣告為已知編碼？一種方法是透過 Encoding 直接執行。如果已知，剖析器會宣告編碼，透過 parse 的 encoding 參數或 R 命令列中執行剖析的區域設定。 (其他方法會記錄在 Encoding 的說明頁面中。)

不需要宣告 ASCII 字串的編碼，因為它們可以在任何區域設定中運作。 ASCII 字串不應該有標記的編碼，因為輸入此類字串至 CHARSXP 快取時，任何編碼都會被忽略。

僅考慮 UTF-8 和 Latin-1 的基本原理在於，大多數系統都能產生 UTF-8 字串，而且這是我們最接近通用格式的字串。對於無法產生 UTF-8 字串的系統（例如缺少功能強大的 iconv 的系統），它們很可能使用 Latin-1，這是 R 的舊假設。然後，如果解析器遇到無法在當前字元集表示的 Unicode 點的「\uxxxx」跳脫字元，它可以傳回 UTF-8 編碼的字串。（這需要 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。通常，符號字型會編碼在 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。後來已新增「測試版：使用 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 使用此功能取得 UTF-8 作為 Windows 上的原生編碼。為了實現此目的，R 必須切換至 UCRT，而這反過來又需要建立 Rtools42。

較舊版本的 Windows 仍然依賴先前的編碼支援，其中原生編碼無法為 UTF-8。R 4.2 需要 UCRT 才能運作，但 UCRT 可以安裝在 Vista SP2 和 Windows Server 2008 SP2 以後的 Windows 上。它自 Windows 10 和 Windows Server 2016 起隨 Windows 附帶。

1.10 CHARSXP 快取 ¶

由 mkChar 建立的 CHARSXP 有一個全域快取，這個快取可確保具有相同內容的大部分 CHARSXP 共用儲存空間（「內容」包括任何已宣告的編碼）。並非所有 CHARSXP 都是快取的一部分，特別是「NA_STRING」並非快取的一部分。從 0.99.0 之前的 R 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 提供的配置器，這些配置器也是 撰寫 R 擴充套件 中 記憶體配置 推薦使用的方法 ，供 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。這些是選擇「依需求」載入的程式碼部分，而不是連結為動態函式庫或併入主執行檔/動態函式庫。

對於其餘模組，其動機是它們會透過連結的函式庫載入大量的（通常是選用的）程式碼。

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 的合適呼叫的主體，以及 base 命名空間的環境。

print.default 和 args 的 C 程式碼優先使用這些環境中的封閉函數，而不是 base 中的定義（作為基本函數）。

QC 函數 undoc 檢查這些環境中建構原型的所有函數目前都是基本函數，而且未包含的基本函數最好視為語言元素（在撰寫時

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

）。有人可能會爭論 ~，但它為剖析器所知，而且語意與一般函數非常不同。而 : 在兩個意義中有不同的參數名稱的文件。

QC 函數 codoc 和 checkS3methods 也使用這些環境（有效地將它們置於搜尋路徑中的基礎之前），因此 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）是否為泛型 via，並透過設定方法並檢查它未被調用，對其餘的基本原語進行檢查，以確定它們可能不是泛型（但這可能會因為其他原因而失敗）。但是，除了閱讀原始碼之外，沒有確定的方法可以知道其他 .Internal 或基本函數是否在內部是泛型的。

2.4 新增基本型別 ¶

[供 R 核心使用：反向執行此程序以移除基本型別。最常見的方式是將 .Internal 變更為基本型別或 反之亦然。]

基本型別列於 src/main/names.c 中的 R_FunTab 表格：基本型別在「eval」欄位中為「Y = 0」。

需要在 base 套件的說明檔案中新增「\alias」項目，且需要將基本型別新增至本節開頭的其中一個清單。

有些基本型別被視為語言元素（目前的基本型別已列於上方）。這些需要新增至 src/library/tools/R/QC.R 檔案中的 undoc() 中的 langElts 清單，以及 tests/primitives.R 中的 lang_elements 清單。

所有其他基本型別都被視為函式，且應列於 src/library/base/R/zzz.R 中定義的其中一個環境中，可能是 .ArgsEnv 或 .GenericArgsEnv：內部泛型也需要列於字元向量 .S3PrimitiveGenerics 中。另請注意上方關於引數配對的討論：如果您透過轉換 .Internal 新增具有多個引數的基本型別函式，您需要將引數配對新增至 C 程式碼，而對於具有單一引數的基本型別函式，則需要新增引數名稱檢查。

請務必執行 make check-devel：這會測試大部分這些需求。

3.1 R 程式碼 ¶

R 程式碼的國際化方式與擴充套件套件完全相同。由於所有具有 R 程式碼的標準套件也都有名稱空間，因此從不需要指定 domain，但為了效率，當訊息是 via 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」是一個字元向量，DESCRIPTION 檔案由 read.dcf 讀取。其他元素「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 記錄一個資料框，每一列代表一個說明檔案。欄位有「檔案」（含副檔名的檔案名稱）、「名稱」（「\name」區段）、「類型」（來自選用的「\docType」區段）、「標題」、「編碼」、「別名」、「概念」和「關鍵字」。除了「別名」是字元向量的清單外，其他欄位都是字元向量。

檔案 hsearch.rds 記錄「help.search」要使用的資訊。這是一個清單，有四個未命名元素，它們是說明檔案、別名、關鍵字和概念的字元矩陣。所有矩陣都有「ID」和「套件」欄位，用來將別名、關鍵字和概念（最後三個元素的剩餘欄位）連結到特定的說明檔案。第一個元素有更多欄位，包括「LibPath」（儲存為 ""，在檔案載入時填入）、「name」、「title」、「topic」（第一個別名，用於將結果呈現為「pkgname::topic」）和「編碼」。

檔案 links.rds 記錄一個命名字元向量，名稱是別名，值是下列形式的字元字串

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

檔案 data.rds 記錄一個兩欄字元矩陣，欄位包含資料集名稱和對應說明檔案的標題。檔案 demo.rds 對套件示範有相同的結構。

檔案 vignette.rds 記錄一個資料框，每一列代表一個「範例」（.[RS]nw 檔案在 inst/doc），欄位有「檔案」（來源中的完整檔案路徑）、「標題」、「PDF」（已安裝 PDF 版本的無路徑檔案名稱，如果存在）、「依賴」、「關鍵字」和「R」（已安裝 R 程式碼的無路徑檔案名稱，如果存在）。

4.2 說明 ¶

所有已安裝的套件，無論是否具有任何 .Rd 檔案，都具有 help 和 html 目錄。後者通常只包含單一檔案 00Index.html，套件索引具有指向說明主題（如果有）的超連結。

目錄 help 包含檔案 AnIndex、paths.rds 和 pkgname.rd[bx]。後兩個檔案是已剖析 .Rd 檔案的延遲載入資料庫，由 tools:::fetchRdDB 存取。檔案 paths.rds 是 .Rd 檔案原始路徑名稱的已儲存字元向量，用於更新資料庫時。

檔案 AnIndex 是兩個欄的 tab 分隔檔案：第一個欄包含說明檔案中定義的別名，第二個欄包含包含該別名的檔案的基底名稱（不含 .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（在標頭 R_ext/GraphicsEngine.h 中定義的 unsigned int）。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」。這是一個產業標準：它被 Web 瀏覽器和所有數位相機（除了高階相機）的 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 執行 R 安裝。macOS 的標準 CRAN R 發行版會將 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()，以及遮罩套件 base 中函數 q() 和 quit() 的函數，自訂版本會以特定於 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() 建立（除了作為 stub）於套件 grDevices 中：這需要一個 Objective-C 編譯器。然後 quartz() 可用於終端機 R，只要後者可存取 macOS 畫面。
• 檔案 src/unix/aqua.c 已編譯。這現在只包含 quartz() 裝置的介面指標。
• capabilities("aqua") 已設定為 TRUE。
• 個人函式庫目錄的預設路徑設定為 ~/Library/R/arch/x.y/library。
• 支援在等待 system() 回傳時設定「忙碌」指示器。
• R_ProcessEvents 在套件 parallel 的分岔子行程中受到抑制。在 R.app 中的關聯回呼執行不應在子行程中執行的動作，而分岔會分岔整個程序，包括主控台。
• 支援使用選項 --gui=aqua 啟動嵌入式 R：執行此動作時，全域 C 變數 useaqua 會設定為 true 值。這會產生後果
  • R 會期透過 R_Interactive 宣告為互動式。
  • .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 中提供給套件：由於需要 C99，因此這在 C 程式碼中應該沒問題。人們確實會嘗試在 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 的一般隱式強制轉換規則會確保提供 integer 向量用於索引或 length<- 會運作。
• 更徹底的替代方案是將現有的 integer 類型變更為 64 位元平台上的 64 位元（這是 S-PLUS 對 DEC/Compaq Alpha 系統採取的方法）。甚至可以在所有平台上使用。
• 允許 integer 或 double 值用於長度和索引，並僅在必要時傳回 double。

第三個方法的優點是對現有程式碼的干擾最小，且不會增加記憶體需求。在第一個和第三個場景中，R 自身的程式碼和使用者程式碼都必須調整為非 integer 類型的長度，而在第三個程式碼分支中，會很少測試長向量。

大多數 .C 和 .Fortran 介面的使用者會使用 as.integer 作為長度和元素編號，但少數人會省略這些，因為他們知道這些是 integer 類型。假設這些永遠不會用於長向量可能是合理的。

其餘的介面需要應付已變更的 VECTOR_SEXPREC 類型。在多數情況下，長度似乎是由 length 和 LENGTH 函數存取的²⁶ 目前的做法是讓這些函數傳回 32 位元長度，並引入傳回 R_xlen_t 值的「長」版本 xlength 和 XLENGTH。

另請參閱 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() 時發生區段錯誤。

對於大型矩陣的矩陣代數，幾乎可以肯定需要一台具有大量 RAM（數百 GB）、多個核心和多執行緒 BLAS 的機器。