R Foreign 對外函數接口

說明

調用已加載的編譯代碼的函數R.

用法

       .C(.NAME, ..., NAOK = FALSE, DUP = TRUE, PACKAGE, ENCODING)
 .Fortran(.NAME, ..., NAOK = FALSE, DUP = TRUE, PACKAGE, ENCODING)

參數

.NAME	給出 C 函數或 Fortran 子例程名稱的字符串，或引用此類名稱的 "NativeSymbolInfo" 、 "RegisteredNativeSymbol" 或 "NativeSymbol" 類的對象。
...	要傳遞給外部函數的參數。最多 65 個。
NAOK	如果 TRUE 則參數中的任何 NA 或 NaN 或 Inf 值都將傳遞給外部函數。如果 FALSE ，則 NA 或 NaN 或 Inf 值的存在被視為錯誤。
PACKAGE	如果提供，則限製對字符串的搜索.NAME到此參數給出的 DLL(加上常規擴展，‘。所以', '.dll’，……)。 這是為了增加包的安全性，通過使用這個參數可以確保沒有其他包可以覆蓋它們的外部符號，並且還可以加快搜索速度(請參閱“注意”)。
DUP, ENCODING	為了向後兼容，接受但忽略。

細節

這些函數可用於調用已編譯的 C 和 Fortran 代碼。後來的接口是.Call和.External，更加靈活並且性能更好。

這些函數是 primitive ，並且 .NAME 始終與提供的第一個參數(不應命名)匹配。其他命名參數遵循...，因此不能縮寫。為了清楚起見，應避免在傳遞給 ... 的參數中使用與 .NAME 匹配或部分匹配的名稱。

值

與傳入參數的 ... 列表類似的列表(包括為參數指定的任何名稱)，但反映了 C 或 Fortran 代碼所做的任何更改。

參數類型

類型的映射RC 或 Fortran 參數的參數是

R	C	Fortran
integer	int *	integer
numeric	雙倍的 *	雙精度
- 或者 -	float *	real
complex	R複合體 *	雙複合體
logical	int *	integer
character	字符 **	[見下文]
raw	無符號字符 *	不允許
list	性經驗*	不允許
other	SEXP	不允許

注意：integer 和 logical 對應的 C 類型是 int ，而不是 S 中的 long 。這種差異在大多數 64 位平台上很重要，其中 int 是 32 位，long 是64 位(但不適用於 64 位 Windows)。

注意：logical 對應的 Fortran 類型是 integer ，而不是 logical ：這種差異對某些 Fortran 編譯器很重要。

中的數值向量R將作為類型傳遞double *到 C(並且作為double precisionFortran)除非參數有屬性Csingle調成TRUE(使用as.single或者single)。該機製僅用於促進現有 C 和 Fortran 代碼的接口。

C型Rcomplex定義於‘Complex.h' 作為一個typedef struct {double r; double i;}。它可能等同於也可能不等同於 C99double complex類型，具體取決於所使用的編譯器。

邏輯值以 0 ( FALSE )、1 ( TRUE ) 或 INT_MIN = -2147483648 ( NA ，但僅當 NAOK = TRUE ) 的形式發送，並且編譯後的代碼應返回這三個值之一：但是 INT_MIN 以外的非零值被映射到 TRUE 。

缺失的 ( NA ) 字符串值將作為字符串 "NA" 傳遞給 .C。由於 C char 類型可以表示所有可能的位模式，因此似乎無法區分丟失的字符串和字符串 "NA" 。如果這種區別很重要，請使用 .Call 。

不推薦使用帶有 .Fortran 的字符串，並且會發出警告。它將字符向量的第一個(唯一)字符串作為 C 字符數組傳遞給 Fortran：如果單獨傳遞其真實長度，則可以將其用作 character*255。最多僅傳回字符串的 255 個字符。 (它的工作效果如何，甚至是否有效，都取決於 C 和 Fortran 編譯器以及平台。)

列表、函數或其他R對象可以(由於曆史原因)傳遞給.C，但是.Call接口是更優選的。除了原子向量之外的所有輸入都應被視為隻讀，並且除了向量(包括列表)之外的所有輸入、函數和環境現在均已棄用。

Fortran 符號名稱

所有已知可用於編譯的 Fortran 編譯器R將符號名稱映射為小寫，也是如此.Fortran.

包含下劃線的符號名稱在 Fortran 77 中無效(盡管它們在 Fortran 9x 中有效)。許多 Fortran 77 編譯器將允許它們，但可能會以不同的方式將它們轉換為不包含下劃線的名稱。此類名稱通常會與.Fortran(因為它們的翻譯方式是在R被構建並使用的信息.Fortran)，但可移植代碼不應使用包含下劃線的 Fortran 名稱。

采用.Fortran小心編譯的 Fortran 9x 代碼：如果使用的 Fortran 9x 編譯器與配置時使用的 Fortran 編譯器不同，則可能無法工作R，特別是當子例程名稱不是小寫或包含下劃線時。調用 Fortran 9x 代碼的最便攜方式R是使用.C和 Fortran 2003 模塊iso_c_binding為 Fortran 代碼提供 C 接口。

複製參數

在調用編譯代碼並收集結果之前複製字符向量。對於其他原子向量，如果在調用代碼中以其他方式使用參數，則在調用編譯代碼之前複製參數。

非原子向量對象對於 C 代碼來說是隻讀的，並且永遠不會被複製。

可以通過設置 options(CBoundsCheck = TRUE) 來更改此行為。在這種情況下，原始、邏輯、整數、雙精度和複數向量參數在調用編譯代碼之前和之後都會被複製。製作的第一個副本在每一端都通過保護字節進行擴展，並且在返回時檢查這些字節是否未被更改。對於 .C ，字符向量的每個元素都使用保護字節。

注意

如果要頻繁使用這些函數之一，請指定 PACKAGE(將搜索限製為單個 DLL)或將 .NAME 作為本機符號對象之一傳遞。搜索符號可能需要很長時間，尤其是在加載許多命名空間時。

你可能會看到PACKAGE = "base"對於鏈接到的符號R。不要在您自己的代碼中使用此符號：此類符號不是 API 的一部分，可能會在沒有警告的情況下進行更改。

參考

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.

也可以看看

dyn.load、.Call。

“編寫 R 擴展”手冊。