├── .Rbuildignore ├── .github ├── .gitignore └── workflows │ └── pkgdown.yaml ├── .gitignore ├── DESCRIPTION ├── NAMESPACE ├── R ├── ISNA.R ├── R_CheckUserInterrupt.R ├── R_xlen_t.R ├── SEXP.R ├── SEXPTYPE.R ├── allocVector.R ├── coerceVector.R ├── isNumeric.R └── setAttrib.R ├── README.md ├── inst └── WORDLIST └── man ├── ISNA.Rd ├── R_CheckUserInterrupt.Rd ├── R_xlen_t.Rd ├── SEXP.Rd ├── SEXPTYPE.Rd ├── allocVector.Rd ├── coerceVector.Rd ├── figures └── getAttrib.png ├── getAttrib.Rd └── isNumeric.Rd /.Rbuildignore: -------------------------------------------------------------------------------- 1 | ^README[.]md$ 2 | ^[.](git|svn) 3 | ^([.]travis|appveyor)[.]yml$ 4 | ^.*[.]png$ 5 | ^.local 6 | ^_pkgdown\.yml$ 7 | ^docs$ 8 | ^pkgdown$ 9 | ^\.github$ 10 | -------------------------------------------------------------------------------- /.github/.gitignore: -------------------------------------------------------------------------------- 1 | *.html 2 | -------------------------------------------------------------------------------- /.github/workflows/pkgdown.yaml: -------------------------------------------------------------------------------- 1 | # Workflow derived from https://github.com/r-lib/actions/tree/v2/examples 2 | # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help 3 | on: 4 | push: 5 | branches: [main, master] 6 | pull_request: 7 | branches: [main, master] 8 | release: 9 | types: [published] 10 | workflow_dispatch: 11 | 12 | name: pkgdown 13 | 14 | jobs: 15 | pkgdown: 16 | runs-on: ubuntu-latest 17 | # Only restrict concurrency for non-PR jobs 18 | concurrency: 19 | group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} 20 | env: 21 | GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} 22 | steps: 23 | - uses: actions/checkout@v3 24 | 25 | - uses: r-lib/actions/setup-pandoc@v2 26 | 27 | - uses: r-lib/actions/setup-r@v2 28 | with: 29 | use-public-rspm: true 30 | 31 | - uses: r-lib/actions/setup-r-dependencies@v2 32 | with: 33 | extra-packages: any::pkgdown, local::. 34 | needs: website 35 | 36 | - name: Build site 37 | run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE) 38 | shell: Rscript {0} 39 | 40 | - name: Deploy to GitHub pages 🚀 41 | if: github.event_name != 'pull_request' 42 | uses: JamesIves/github-pages-deploy-action@v4.4.1 43 | with: 44 | clean: false 45 | branch: gh-pages 46 | folder: docs 47 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .Rhistory 2 | *~ 3 | **/*~ 4 | .local 5 | docs 6 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: RNativeAPI 2 | Version: 0.0.0-9000 3 | Title: R Native API - Documentation and Examples 4 | Description: A proof-of-concept package documenting the R Native API via the built-in R help system. The help pages are written in Roxygen2 that are compiled to Rd format and then rendered by R as regular help pages. Disclaimer: This is just a proof of concept; I'm not claiming this is the best approach. 5 | Authors@R: c( 6 | person("Henrik", "Bengtsson", role=c("aut", "cre", "cph"), 7 | email = "henrikb@braju.com")) 8 | License: GPL (>= 3) 9 | RoxygenNote: 7.2.3 10 | Roxygen: list(markdown = TRUE) 11 | URL: https://henrikbengtsson.github.io/RNativeAPI/ 12 | -------------------------------------------------------------------------------- /NAMESPACE: -------------------------------------------------------------------------------- 1 | # Generated by roxygen2: do not edit by hand 2 | 3 | export(ISNA) 4 | export(R_CheckUserInterrupt) 5 | export(R_len_t) 6 | export(R_xlen_t) 7 | export(SEXP) 8 | export(SEXPTYPE) 9 | export(allocVector) 10 | export(coerceVector) 11 | export(getAttrib) 12 | export(isNumeric) 13 | export(setAttrib) 14 | -------------------------------------------------------------------------------- /R/ISNA.R: -------------------------------------------------------------------------------- 1 | #' Checks if a Value is NA, NaN, or Finite 2 | #' 3 | #' @param x (double) An scalar double. 4 | #' 5 | #' @return (integer) 0 ("false") or 1 ("true"). 6 | #' 7 | #' @section Overview: 8 | #' 9 | #' | | `NaN` | `NA` | 10 | #' |-------------|--------|-------| 11 | #' | C API: | | | 12 | #' | `ISNAN()` | true | true | 13 | #' | `ISNA()` | false | true | 14 | #' | `R_IsNaN()` | true | false | 15 | #' | `R_IsNA()` | false | true | 16 | #' | | | | 17 | #' | R API: | | | 18 | #' | `is.na()` | TRUE | TRUE | 19 | #' | `is.nan()` | TRUE | FALSE | 20 | #' 21 | # Source: Kevin Ushey, StackOverflow, October 2014, 22 | # https://stackoverflow.com/a/26262984/1072091 23 | #' 24 | #' @section C API: 25 | #' 26 | #' ```c 27 | #' #include 28 | #' 29 | #' int R_IsNA(double); 30 | #' int R_IsNaN(double); 31 | #' int R_finite(double); 32 | #' 33 | #' #define ISNA(x) R_IsNA(x) 34 | #' 35 | #' #ifdef __cplusplus 36 | #' int R_isnancpp(double); /* in arithmetic.c */ 37 | #' # define ISNAN(x) R_isnancpp(x) 38 | #' #else 39 | #' # define ISNAN(x) (isnan(x)!=0) 40 | #' #endif 41 | #' 42 | #' #ifdef HAVE_WORKING_ISFINITE 43 | #' /* isfinite is defined in according to C99 */ 44 | #' # define R_FINITE(x) isfinite(x) 45 | #' #else 46 | #' # define R_FINITE(x) R_finite(x) 47 | #' #endif 48 | #' ``` 49 | # Comment: Need to indent above C code to avoid the #ifdef 50 | # parts from being dropped 51 | #' 52 | #' @section R API: 53 | #' ```r 54 | #' library(base) 55 | #' 56 | #' x <- c(NA_real_, NaN, 3.14, -Inf, +Inf) 57 | #' is.na(x) # c( TRUE, TRUE, FALSE, FALSE, FALSE) 58 | #' is.nan(x) # c(FALSE, TRUE, FALSE, FALSE, FALSE) 59 | #' is.finite(x) # c( TRUE, TRUE, TRUE, FALSE, FALSE) 60 | #' is.infinite(x) # c(FALSE, FALSE, FALSE, TRUE, TRUE) 61 | #' ``` 62 | #' 63 | #' @source Declaration: [src/include/R_ext/Arith.h](https://github.com/wch/r-source/blob/trunk/src/include/R_ext/Arith.h) via [src/include/R.h](https://github.com/wch/r-source/blob/trunk/src/include/R.h) 64 | #' @source Implementation: Functions `R_IsNA(double x)`, `R_IsNaN(double x)`, and `R_finite(double x)` are implemented in [src/main/arithmetic.c](https://github.com/wch/r-source/blob/trunk/src/main/arithmetic.c) 65 | #' 66 | #' @aliases ISNA ISNAN R_FINITE 67 | #' @aliases R_IsNA R_IsNaN R_finite 68 | #' @export 69 | ISNA <- ISNAN <- R_FINITE <- R_IsNA <- R_IsNaN <- R_finite <- function(x) { 70 | x = "double" 71 | return(logical(1L)) 72 | } 73 | 74 | -------------------------------------------------------------------------------- /R/R_CheckUserInterrupt.R: -------------------------------------------------------------------------------- 1 | #' Checks for User Interrupt 2 | #' 3 | #' Check if the user has requested an interrupt, and if so branch to 4 | #' \R's error signaling functions. 5 | #' 6 | #' @param void (void) Nothing. 7 | #' 8 | #' @return Nothing. 9 | #' 10 | #' @section C API: 11 | #' 12 | #' ```c 13 | #' #include 14 | #' 15 | #' void R_CheckUserInterrupt(void) 16 | #' ``` 17 | # 18 | #' @section R API: 19 | #' 20 | #' All evaluation at the top level of R checks for interrupts. 21 | #' 22 | #' Related functions that affect `R_CheckUserInterrupt()`: 23 | #' * [base::suspendInterrupts()] - suspends interrupts during evaluation 24 | #' * [base::allowInterrupts()] - allows interrupts during evaluation 25 | #' 26 | #' @source Declaration: [src/include/R_ext/Utils.h](https://github.com/wch/r-source/blob/trunk/src/include/R_ext/Utils.h) 27 | #' @source Implementation: [src/main/errors.c](https://github.com/wch/r-source/blob/trunk/src/main/errors.c) 28 | #' 29 | #' @export 30 | R_CheckUserInterrupt <- function(void) { 31 | void = void 32 | 33 | return(void) 34 | } 35 | -------------------------------------------------------------------------------- /R/R_xlen_t.R: -------------------------------------------------------------------------------- 1 | #' Type Definition: 'R_xlen_t' and 'R_len_t' 2 | #' 3 | #' @usage 4 | #' #include 5 | #' R_xlen_t 6 | #' R_len_t 7 | #' 8 | #' @section C API: 9 | #' Long vectors: 10 | #' 11 | #' ```c 12 | #' typedef ptrdiff_t R_xlen_t; 13 | #' define R_XLEN_T_MAX 4503599627370496 14 | #' ``` 15 | #' 16 | #' Short vectors: 17 | #' ```c 18 | #' typedef int R_len_t; 19 | #' #define R_LEN_T_MAX INT_MAX 20 | #' ``` 21 | #' 22 | #' If long vectors are _not_ supported on the current platform, then: 23 | #' 24 | #' ```c 25 | #' LONG_VECTOR_SUPPORT 26 | #' ``` 27 | #' 28 | #' is _not_ defined and we have: 29 | #' 30 | #' ``` 31 | #' typedef int R_xlen_t; 32 | #' define R_XLEN_T_MAX R_LEN_T_MAX 33 | #' ``` 34 | #' 35 | #' @section R API: 36 | #' ```r 37 | #' library(base) 38 | #' 39 | #' # Maximum length of a "short" vector ... 40 | #' x <- seq_len(.Machine$integer.max) 41 | #' xlen <- length(x) # integer; internally R_len_t 42 | #' 43 | #' # ... before becoming a "long" vector 44 | #' x <- seq_len(.Machine$integer.max + 1) 45 | #' xlen <- length(x) # numeric; internally R_xlen_t 46 | #' ``` 47 | #' 48 | #' @source Declaration: [src/include/Rinternals.h](https://github.com/wch/r-source/blob/trunk/src/include/Rinternals.h) 49 | #' 50 | #' @aliases R_len_t R_xlen_t 51 | #' @aliases R_LEN_T_MAX R_XLEN_T_MAX 52 | #' @export 53 | R_xlen_t <- structure(double(1L), class = "typedef", min = 0L, max = 2^52) 54 | 55 | #' @export 56 | R_len_t <- structure(integer(1L), class = "typedef", min = 0L, max = .Machine[["integer.max"]]) 57 | -------------------------------------------------------------------------------- /R/SEXP.R: -------------------------------------------------------------------------------- 1 | #' The `SEXP` Structure 2 | #' 3 | #' @format A C struct. 4 | #' 5 | #' @section C API: 6 | #' 7 | #' ```c 8 | #' #include 9 | #' ``` 10 | #' 11 | #' @seealso 12 | #' The `SEXP` structure is documented in 'R Language Definition'. 13 | #' 14 | #' @docType class 15 | #' 16 | #' @export 17 | SEXP <- NULL 18 | 19 | -------------------------------------------------------------------------------- /R/SEXPTYPE.R: -------------------------------------------------------------------------------- 1 | #' The `SEXPTYPE` Structure 2 | #' 3 | #' @format A C struct. 4 | #' 5 | #' @section C API: 6 | #' 7 | #' ```c 8 | #' #include 9 | #' ``` 10 | #' 11 | #' @section Availalble SEXTYPE types: 12 | #' 13 | #' * `NILSXP` [NULL] 14 | #' * `SYMSXP` name/[symbol] 15 | #' * `LISTSXP` [pairlist] 16 | #' * `CLOSXP` [function] or function closure 17 | #' * `ENVSXP` [environment] 18 | #' * `PROMSXP` promises 19 | #' * `LANGSXP` [language] objects 20 | #' * `SPECIALSXP` special functions 21 | #' * `BUILTINSXP` builtin functions 22 | #' * `CHARSXP` internal character strings 23 | #' * `LGLSXP` [logical] vectors 24 | #' * `INTSXP` [integer] vectors 25 | #' * `REALSXP` [numeric] vectors (with storage mode [double]) 26 | #' * `CPLXSXP` [complex] vectors 27 | #' * `STRSXP` [character] vectors 28 | #' * `DOTSXP` dot-dot-dot ([...]) object 29 | #' * `ANYSXP` make "any" args work 30 | #' * `VECSXP` [list] (generic vector) 31 | #' * `EXPRSXP` [expression] vector 32 | #' * `BCODESXP` byte code 33 | #' * `EXTPTRSXP` external pointer 34 | #' * `WEAKREFSXP` weak reference 35 | #' * `RAWSXP` [raw] vector 36 | #' * `S4SXP` S4 classes not of simple type 37 | #' 38 | #' @seealso 39 | #' The `SEXPTYPE` is documented in Section 'Details of R types' in 'R Language Definition' 40 | #' and Section 'SEXPTYPEs' in 'R Internals'. 41 | #' 42 | #' @docType class 43 | #' 44 | #' @aliases NILSXP SYMSXP LISTSXP CLOSXP ENVSXP PROMSXP LANGSXP SPECIALSXP BUILTINSXP CHARSXP LGLSXP INTSXP REALSXP CPLXSXP STRSXP DOTSXP ANYSXP VECSXP EXPRSXP BCODESXP EXTPTRSXP WEAKREFSXP RAWSXP S4SXP 45 | #' @export 46 | SEXPTYPE <- NULL 47 | -------------------------------------------------------------------------------- /R/allocVector.R: -------------------------------------------------------------------------------- 1 | #' Allocates a Vector 2 | #' 3 | #' @param type ([SEXPTYPE]) An macro constant of length one. 4 | #' 5 | #' @param length ([R_xlen_t]) An non-negative integer. 6 | #' 7 | #' @return `allocVector()` returns an [SEXP] object of type [SEXPTYPE] `type`. 8 | #' 9 | #' @section C API: 10 | #' 11 | #' ```c 12 | #' #include 13 | #' SEXP Rf_allocVector(SEXPTYPE, R_xlen_t) 14 | #' #define allocVector Rf_allocVector 15 | #' ``` 16 | #' 17 | #' Related macros: 18 | #' 19 | #' ```c 20 | #' #include 21 | #' #define NEW_LOGICAL(n) Rf_allocVector(LGLSXP,n) 22 | #' #define NEW_INTEGER(n) Rf_allocVector(INTSXP,n) 23 | #' #define NEW_NUMERIC(n) Rf_allocVector(REALSXP,n) 24 | #' #define NEW_CHARACTER(n) Rf_allocVector(STRSXP,n) 25 | #' #define NEW_COMPLEX(n) Rf_allocVector(CPLXSXP,n) 26 | #' #define NEW_LIST(n) Rf_allocVector(VECSXP,n) 27 | #' #define NEW_STRING(n) NEW_CHARACTER(n) 28 | #' #define NEW_RAW(n) Rf_allocVector(RAWSXP,n) 29 | #' ``` 30 | #' 31 | #' @section R API: 32 | #' ```r 33 | #' library(base) 34 | #' 35 | #' x_logical <- logical(length = n) 36 | #' x_integer <- integer(length = n) 37 | #' x_numeric <- numeric(length = n) 38 | #' x_character <- character(length = n) 39 | #' x_complex <- complex(length.out = n) 40 | #' x_list <- vector(mode = "list", length = n) 41 | #' x_raw <- raw(length = n) 42 | #' ``` 43 | #' 44 | #' @source Declaration: [src/include/Rinternals.h](https://github.com/wch/r-source/blob/trunk/src/include/Rinternals.h) and [src/include/Rdefines.h](https://github.com/wch/r-source/blob/trunk/src/include/Rdefines.h) 45 | #' @source Implementation: `allocVector(SEXPTYPE type, R_xlen_t length)` is a simple inline wrapper functions that calls `allocVector3(type, length, NULL)`, cf. [src/include/Rinlinedfuns.h](https://github.com/wch/r-source/blob/trunk/src/include/Rinlinedfuns.h) 46 | #' 47 | #' @aliases Rf_allocVector 48 | #' @aliases NEW_LOGICAL NEW_INTEGER NEW_NUMERIC NEW_CHARACTER NEW_COMPLEX NEW_LIST NEW_STRING NEW_RAW 49 | #' @export 50 | allocVector <- function(type, length) { 51 | type = SEXPTYPE 52 | type = R_xlen_t 53 | 54 | return(SEXP) 55 | } 56 | -------------------------------------------------------------------------------- /R/coerceVector.R: -------------------------------------------------------------------------------- 1 | #' Coerces a Vector 2 | #' 3 | #' @param v ([SEXP]) An \R object. 4 | #' 5 | #' @param type ([SEXPTYPE]) An macro constant of length one. 6 | #' 7 | #' @return `coerceVector()` returns an [SEXP] object of type [SEXPTYPE] `type`. 8 | #' 9 | #' @section C API: 10 | #' 11 | #' ```c 12 | #' #include 13 | #' SEXP Rf_coerceVector(SEXP, SEXPTYPE) 14 | #' #define coerceVector Rf_coerceVector 15 | #' ``` 16 | #' 17 | #' Related macros: 18 | #' 19 | #' ```c 20 | #' #include 21 | #' #define AS_LOGICAL(x) Rf_coerceVector(x,LGLSXP) 22 | #' #define AS_INTEGER(x) Rf_coerceVector(x,INTSXP) 23 | #' #define AS_NUMERIC(x) Rf_coerceVector(x,REALSXP) 24 | #' #define AS_CHARACTER(x) Rf_coerceVector(x,STRSXP) 25 | #' #define AS_COMPLEX(x) Rf_coerceVector(x,CPLXSXP) 26 | #' #define AS_VECTOR(x) Rf_coerceVector(x,VECSXP) 27 | #' #define AS_LIST(x) Rf_coerceVector(x,VECSXP) 28 | #' #define AS_RAW(x) Rf_coerceVector(x,RAWSXP) 29 | #' ``` 30 | #' 31 | #' @section R API: 32 | #' ```r 33 | #' library(base) 34 | #' 35 | #' x <- 1:5 36 | #' y_integer <- as.integer(x) 37 | #' y_logical <- as.logical(x) 38 | #' y_numeric <- as.numeric(x) 39 | #' y_character <- as.character(x) 40 | #' ``` 41 | #' 42 | #' @source Declaration: [src/include/Rinternals.h](https://github.com/wch/r-source/blob/trunk/src/include/Rinternals.h) and [src/include/Rdefines.h](https://github.com/wch/r-source/blob/trunk/src/include/Rdefines.h) 43 | #' @source Implementation: [src/main/coerce.c](https://github.com/wch/r-source/blob/trunk/src/main/coerce.c) 44 | #' 45 | #' @aliases Rf_coerceVector 46 | #' @aliases AS_LOGICAL AS_INTEGER AS_NUMERIC AS_CHARACTER AS_COMPLEX AS_VECTOR AS_LIST AS_RAW 47 | #' @export 48 | coerceVector <- function(v, type) { 49 | v = SEXP 50 | type = integer 51 | 52 | return(SEXP) 53 | } 54 | -------------------------------------------------------------------------------- /R/isNumeric.R: -------------------------------------------------------------------------------- 1 | #' Checks if an SEXP is of Certain Type 2 | #' 3 | #' @param s ([SEXP]) An \R object. 4 | #' 5 | #' @return (`Rboolean`) `true` (=1) or `false` (=0). 6 | #' 7 | #' @section C API: 8 | #' 9 | #' ```c 10 | #' #include 11 | #' Rboolean Rf_isNumeric(SEXP); 12 | #' #define isNumeric Rf_isNumeric 13 | #' ``` 14 | #' 15 | #' @section R API: 16 | #' ```r 17 | #' library(base) 18 | #' 19 | #' is.numeric(integer(length = 2L)) ## TRUE 20 | #' is.numeric(numeric(length = 2L)) ## TRUE 21 | #' is.numeric(factor(c("a", "b"))) ## FALSE 22 | #' is.numeric(logical(length = 2L)) ## FALSE but isNumeric() = true! 23 | #' ``` 24 | #' 25 | #' @source Declaration: [src/include/Rinternals.h](https://github.com/wch/r-source/blob/trunk/src/include/Rinternals.h) and [src/include/Rdefines.h](https://github.com/wch/r-source/blob/trunk/src/include/Rdefines.h) 26 | #' @source Implementation: Inline function `isNumeric(SEXP s)`, cf. [src/include/Rinlinedfuns.h](https://github.com/wch/r-source/blob/trunk/src/include/Rinlinedfuns.h) 27 | #' 28 | #' @aliases isNumeric Rf_isNumeric 29 | #' @export 30 | isNumeric <- function(s) { 31 | x = SEXP 32 | return(logical(1L)) 33 | } 34 | -------------------------------------------------------------------------------- /R/setAttrib.R: -------------------------------------------------------------------------------- 1 | #' Gets and Sets an Attribute of an R Object 2 | #' 3 | #' @param vec ([SEXP]) An \R object. 4 | #' 5 | #' @param name ([SEXP]) A [character] of length one. 6 | #' 7 | #' @return `getAttrib()` returns ([SEXP]) the value of attribute `name`. 8 | #' 9 | #' @section C API: 10 | #' 11 | #' ```c 12 | #' #include 13 | #' 14 | #' SEXP getAttrib(SEXP vec, SEXP name) 15 | #' SEXP setAttrib(SEXP vec, SEXP name, SEXP val) 16 | #' ``` 17 | # 18 | #' @section R API: 19 | #' ```r 20 | #' library(base) 21 | #' 22 | #' value <- attr(vec, name, exact = TRUE) 23 | #' attr(vec, name) <- val 24 | #' ``` 25 | #' 26 | #' @source Declaration: [src/include/Rinternals.h](https://github.com/wch/r-source/blob/trunk/src/include/Rinternals.h) 27 | #' @source Implementation: [src/main/attrib.c](https://github.com/wch/r-source/blob/trunk/src/main/attrib.c) 28 | #' 29 | #' @export 30 | getAttrib <- function(vec, name) { 31 | vec = SEXP 32 | name = SEXP 33 | 34 | return(SEXP) 35 | } 36 | 37 | 38 | #' @param val ([SEXP]) An \R object. 39 | #' 40 | #' @return `setAttrib()` returns ([SEXP]) a copy of \R object `vec` with attribute `name` set. 41 | #' @return ([SEXP]) 42 | #' 43 | #' @rdname getAttrib 44 | #' @export 45 | setAttrib <- function(vec, name, val) { 46 | vec = SEXP 47 | name = SEXP 48 | val = SEXP 49 | 50 | return(SEXP) 51 | } 52 | 53 | 54 | #' [character]: [base::character] 55 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # R package: RNativeAPI - Documentation and Examples of the R Native API 2 | 3 | A proof-of-concept package documenting the R Native API via the built-in R help system. The help pages are written in Roxygen2 that are compiled to Rd format and then rendered by R as regular help pages. 4 | 5 | _Disclaimer: This is just a proof of concept; I'm not claiming this is the best approach._ 6 | 7 | 8 | ## Examples 9 | 10 | 11 | ### Help pages 12 | 13 | #### HTML version 14 | 15 | Screenshot of help(getAttrib) 16 | 17 | 18 | #### Text version 19 | 20 | ```r 21 | > options(help_type = "text") 22 | > ?RNativeAPI::getAttrib 23 | 24 | getAttrib package:RNativeAPI R Documentation 25 | 26 | Gets and Sets an Attribute of an R Object 27 | 28 | Description: 29 | 30 | Gets and Sets an Attribute of an R Object 31 | 32 | Usage: 33 | 34 | getAttrib(vec, name) 35 | 36 | setAttrib(vec, name, val) 37 | 38 | Arguments: 39 | 40 | vec: (SEXP) An R object. 41 | 42 | name: (SEXP) A character of length one. 43 | 44 | val: (SEXP) An R object. 45 | 46 | Value: 47 | 48 | getAttrib() returns (SEXP) the value of attribute ‘name’. 49 | 50 | setAttrib() returns (SEXP) a copy of R object ‘vec’ with attribute ‘name’ set. 51 | 52 | C API: 53 | 54 | SEXP getAttrib(SEXP vec, SEXP name) 55 | SEXP setAttrib(SEXP vec, SEXP name, SEXP val) 56 | 57 | R API: 58 | 59 | value <- attr(vec, name) 60 | attr(vec, name) <- val 61 | 62 | Source: 63 | 64 | Declaration: src/include/Rinternals.h 65 | 66 | Implementation: src/main/attrib.c 67 | ``` 68 | 69 | 70 | ## Displaying functions 71 | 72 | ```r 73 | > RNativeAPI::getAttrib 74 | function (vec, name) 75 | { 76 | vec = SEXP 77 | name = SEXP 78 | return(SEXP) 79 | } 80 | 81 | 82 | ``` 83 | 84 | _Comment:_ By a customized class and `print()` method, the above can probably be presented much nice. With some efforts, it could even display the actual source code (there are already R packages providing functionalities for this). 85 | 86 | 87 | -------------------------------------------------------------------------------- /inst/WORDLIST: -------------------------------------------------------------------------------- 1 | attrib 2 | Rinternals 3 | Roxygen 4 | SEXP 5 | src 6 | struct 7 | -------------------------------------------------------------------------------- /man/ISNA.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/ISNA.R 3 | \name{ISNA} 4 | \alias{ISNA} 5 | \alias{ISNAN} 6 | \alias{R_FINITE} 7 | \alias{R_IsNA} 8 | \alias{R_IsNaN} 9 | \alias{R_finite} 10 | \title{Checks if a Value is NA, NaN, or Finite} 11 | \source{ 12 | Declaration: \href{https://github.com/wch/r-source/blob/trunk/src/include/R_ext/Arith.h}{src/include/R_ext/Arith.h} via \href{https://github.com/wch/r-source/blob/trunk/src/include/R.h}{src/include/R.h} 13 | 14 | Implementation: Functions \verb{R_IsNA(double x)}, \verb{R_IsNaN(double x)}, and \verb{R_finite(double x)} are implemented in \href{https://github.com/wch/r-source/blob/trunk/src/main/arithmetic.c}{src/main/arithmetic.c} 15 | } 16 | \usage{ 17 | ISNA(x) 18 | } 19 | \arguments{ 20 | \item{x}{(double) An scalar double.} 21 | } 22 | \value{ 23 | (integer) 0 ("false") or 1 ("true"). 24 | } 25 | \description{ 26 | Checks if a Value is NA, NaN, or Finite 27 | } 28 | \section{Overview}{ 29 | \tabular{lll}{ 30 | \tab \code{NaN} \tab \code{NA} \cr 31 | C API: \tab \tab \cr 32 | \code{ISNAN()} \tab true \tab true \cr 33 | \code{ISNA()} \tab false \tab true \cr 34 | \code{R_IsNaN()} \tab true \tab false \cr 35 | \code{R_IsNA()} \tab false \tab true \cr 36 | \tab \tab \cr 37 | R API: \tab \tab \cr 38 | \code{is.na()} \tab TRUE \tab TRUE \cr 39 | \code{is.nan()} \tab TRUE \tab FALSE \cr 40 | } 41 | } 42 | 43 | \section{C API}{ 44 | 45 | 46 | \if{html}{\out{
}}\preformatted{ #include 47 | 48 | int R_IsNA(double); 49 | int R_IsNaN(double); 50 | int R_finite(double); 51 | 52 | #define ISNA(x) R_IsNA(x) 53 | 54 | #ifdef __cplusplus 55 | int R_isnancpp(double); /* in arithmetic.c */ 56 | # define ISNAN(x) R_isnancpp(x) 57 | #else 58 | # define ISNAN(x) (isnan(x)!=0) 59 | #endif 60 | 61 | #ifdef HAVE_WORKING_ISFINITE 62 | /* isfinite is defined in according to C99 */ 63 | # define R_FINITE(x) isfinite(x) 64 | #else 65 | # define R_FINITE(x) R_finite(x) 66 | #endif 67 | }\if{html}{\out{
}} 68 | } 69 | 70 | \section{R API}{ 71 | 72 | 73 | \if{html}{\out{
}}\preformatted{library(base) 74 | 75 | x <- c(NA_real_, NaN, 3.14, -Inf, +Inf) 76 | is.na(x) # c( TRUE, TRUE, FALSE, FALSE, FALSE) 77 | is.nan(x) # c(FALSE, TRUE, FALSE, FALSE, FALSE) 78 | is.finite(x) # c( TRUE, TRUE, TRUE, FALSE, FALSE) 79 | is.infinite(x) # c(FALSE, FALSE, FALSE, TRUE, TRUE) 80 | }\if{html}{\out{
}} 81 | } 82 | 83 | -------------------------------------------------------------------------------- /man/R_CheckUserInterrupt.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/R_CheckUserInterrupt.R 3 | \name{R_CheckUserInterrupt} 4 | \alias{R_CheckUserInterrupt} 5 | \title{Checks for User Interrupt} 6 | \source{ 7 | Declaration: \href{https://github.com/wch/r-source/blob/trunk/src/include/R_ext/Utils.h}{src/include/R_ext/Utils.h} 8 | 9 | Implementation: \href{https://github.com/wch/r-source/blob/trunk/src/main/errors.c}{src/main/errors.c} 10 | } 11 | \usage{ 12 | R_CheckUserInterrupt(void) 13 | } 14 | \arguments{ 15 | \item{void}{(void) Nothing.} 16 | } 17 | \value{ 18 | Nothing. 19 | } 20 | \description{ 21 | Check if the user has requested an interrupt, and if so branch to 22 | \R's error signaling functions. 23 | } 24 | \section{C API}{ 25 | 26 | 27 | \if{html}{\out{
}}\preformatted{#include 28 | 29 | void R_CheckUserInterrupt(void) 30 | }\if{html}{\out{
}} 31 | } 32 | 33 | \section{R API}{ 34 | 35 | 36 | All evaluation at the top level of R checks for interrupts. 37 | 38 | Related functions that affect \code{R_CheckUserInterrupt()}: 39 | \itemize{ 40 | \item \code{\link[base:conditions]{base::suspendInterrupts()}} - suspends interrupts during evaluation 41 | \item \code{\link[base:conditions]{base::allowInterrupts()}} - allows interrupts during evaluation 42 | } 43 | } 44 | 45 | -------------------------------------------------------------------------------- /man/R_xlen_t.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/R_xlen_t.R 3 | \docType{data} 4 | \name{R_xlen_t} 5 | \alias{R_xlen_t} 6 | \alias{R_len_t} 7 | \alias{R_LEN_T_MAX} 8 | \alias{R_XLEN_T_MAX} 9 | \title{Type Definition: 'R_xlen_t' and 'R_len_t'} 10 | \format{ 11 | An object of class \code{typedef} of length 1. 12 | } 13 | \source{ 14 | Declaration: \href{https://github.com/wch/r-source/blob/trunk/src/include/Rinternals.h}{src/include/Rinternals.h} 15 | } 16 | \usage{ 17 | #include 18 | R_xlen_t 19 | R_len_t 20 | } 21 | \description{ 22 | Type Definition: 'R_xlen_t' and 'R_len_t' 23 | } 24 | \section{C API}{ 25 | 26 | Long vectors: 27 | 28 | \if{html}{\out{
}}\preformatted{typedef ptrdiff_t R_xlen_t; 29 | define R_XLEN_T_MAX 4503599627370496 30 | }\if{html}{\out{
}} 31 | 32 | Short vectors: 33 | 34 | \if{html}{\out{
}}\preformatted{typedef int R_len_t; 35 | #define R_LEN_T_MAX INT_MAX 36 | }\if{html}{\out{
}} 37 | 38 | If long vectors are \emph{not} supported on the current platform, then: 39 | 40 | \if{html}{\out{
}}\preformatted{LONG_VECTOR_SUPPORT 41 | }\if{html}{\out{
}} 42 | 43 | is \emph{not} defined and we have: 44 | 45 | \if{html}{\out{
}}\preformatted{typedef int R_xlen_t; 46 | define R_XLEN_T_MAX R_LEN_T_MAX 47 | }\if{html}{\out{
}} 48 | } 49 | 50 | \section{R API}{ 51 | 52 | 53 | \if{html}{\out{
}}\preformatted{library(base) 54 | 55 | # Maximum length of a "short" vector ... 56 | x <- seq_len(.Machine$integer.max) 57 | xlen <- length(x) # integer; internally R_len_t 58 | 59 | # ... before becoming a "long" vector 60 | x <- seq_len(.Machine$integer.max + 1) 61 | xlen <- length(x) # numeric; internally R_xlen_t 62 | }\if{html}{\out{
}} 63 | } 64 | 65 | \keyword{datasets} 66 | -------------------------------------------------------------------------------- /man/SEXP.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/SEXP.R 3 | \docType{class} 4 | \name{SEXP} 5 | \alias{SEXP} 6 | \title{The \code{SEXP} Structure} 7 | \format{ 8 | A C struct. 9 | } 10 | \usage{ 11 | SEXP 12 | } 13 | \description{ 14 | The \code{SEXP} Structure 15 | } 16 | \section{C API}{ 17 | 18 | 19 | \if{html}{\out{
}}\preformatted{#include 20 | }\if{html}{\out{
}} 21 | } 22 | 23 | \seealso{ 24 | The \code{SEXP} structure is documented in 'R Language Definition'. 25 | } 26 | \keyword{datasets} 27 | -------------------------------------------------------------------------------- /man/SEXPTYPE.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/SEXPTYPE.R 3 | \docType{class} 4 | \name{SEXPTYPE} 5 | \alias{SEXPTYPE} 6 | \alias{NILSXP} 7 | \alias{SYMSXP} 8 | \alias{LISTSXP} 9 | \alias{CLOSXP} 10 | \alias{ENVSXP} 11 | \alias{PROMSXP} 12 | \alias{LANGSXP} 13 | \alias{SPECIALSXP} 14 | \alias{BUILTINSXP} 15 | \alias{CHARSXP} 16 | \alias{LGLSXP} 17 | \alias{INTSXP} 18 | \alias{REALSXP} 19 | \alias{CPLXSXP} 20 | \alias{STRSXP} 21 | \alias{DOTSXP} 22 | \alias{ANYSXP} 23 | \alias{VECSXP} 24 | \alias{EXPRSXP} 25 | \alias{BCODESXP} 26 | \alias{EXTPTRSXP} 27 | \alias{WEAKREFSXP} 28 | \alias{RAWSXP} 29 | \alias{S4SXP} 30 | \title{The \code{SEXPTYPE} Structure} 31 | \format{ 32 | A C struct. 33 | } 34 | \usage{ 35 | SEXPTYPE 36 | } 37 | \description{ 38 | The \code{SEXPTYPE} Structure 39 | } 40 | \section{C API}{ 41 | 42 | 43 | \if{html}{\out{
}}\preformatted{#include 44 | }\if{html}{\out{
}} 45 | } 46 | 47 | \section{Availalble SEXTYPE types}{ 48 | 49 | \itemize{ 50 | \item \code{NILSXP} \link{NULL} 51 | \item \code{SYMSXP} name/\link{symbol} 52 | \item \code{LISTSXP} \link{pairlist} 53 | \item \code{CLOSXP} \link{function} or function closure 54 | \item \code{ENVSXP} \link{environment} 55 | \item \code{PROMSXP} promises 56 | \item \code{LANGSXP} \link{language} objects 57 | \item \code{SPECIALSXP} special functions 58 | \item \code{BUILTINSXP} builtin functions 59 | \item \code{CHARSXP} internal character strings 60 | \item \code{LGLSXP} \link{logical} vectors 61 | \item \code{INTSXP} \link{integer} vectors 62 | \item \code{REALSXP} \link{numeric} vectors (with storage mode \link{double}) 63 | \item \code{CPLXSXP} \link{complex} vectors 64 | \item \code{STRSXP} \link{character} vectors 65 | \item \code{DOTSXP} dot-dot-dot (\link{...}) object 66 | \item \code{ANYSXP} make "any" args work 67 | \item \code{VECSXP} \link{list} (generic vector) 68 | \item \code{EXPRSXP} \link{expression} vector 69 | \item \code{BCODESXP} byte code 70 | \item \code{EXTPTRSXP} external pointer 71 | \item \code{WEAKREFSXP} weak reference 72 | \item \code{RAWSXP} \link{raw} vector 73 | \item \code{S4SXP} S4 classes not of simple type 74 | } 75 | } 76 | 77 | \seealso{ 78 | The \code{SEXPTYPE} is documented in Section 'Details of R types' in 'R Language Definition' 79 | and Section 'SEXPTYPEs' in 'R Internals'. 80 | } 81 | \keyword{datasets} 82 | -------------------------------------------------------------------------------- /man/allocVector.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/allocVector.R 3 | \name{allocVector} 4 | \alias{allocVector} 5 | \alias{Rf_allocVector} 6 | \alias{NEW_LOGICAL} 7 | \alias{NEW_INTEGER} 8 | \alias{NEW_NUMERIC} 9 | \alias{NEW_CHARACTER} 10 | \alias{NEW_COMPLEX} 11 | \alias{NEW_LIST} 12 | \alias{NEW_STRING} 13 | \alias{NEW_RAW} 14 | \title{Allocates a Vector} 15 | \source{ 16 | Declaration: \href{https://github.com/wch/r-source/blob/trunk/src/include/Rinternals.h}{src/include/Rinternals.h} and \href{https://github.com/wch/r-source/blob/trunk/src/include/Rdefines.h}{src/include/Rdefines.h} 17 | 18 | Implementation: \verb{allocVector(SEXPTYPE type, R_xlen_t length)} is a simple inline wrapper functions that calls \code{allocVector3(type, length, NULL)}, cf. \href{https://github.com/wch/r-source/blob/trunk/src/include/Rinlinedfuns.h}{src/include/Rinlinedfuns.h} 19 | } 20 | \usage{ 21 | allocVector(type, length) 22 | } 23 | \arguments{ 24 | \item{type}{(\link{SEXPTYPE}) An macro constant of length one.} 25 | 26 | \item{length}{(\link{R_xlen_t}) An non-negative integer.} 27 | } 28 | \value{ 29 | \code{allocVector()} returns an \link{SEXP} object of type \link{SEXPTYPE} \code{type}. 30 | } 31 | \description{ 32 | Allocates a Vector 33 | } 34 | \section{C API}{ 35 | 36 | 37 | \if{html}{\out{
}}\preformatted{#include 38 | SEXP Rf_allocVector(SEXPTYPE, R_xlen_t) 39 | #define allocVector Rf_allocVector 40 | }\if{html}{\out{
}} 41 | 42 | Related macros: 43 | 44 | \if{html}{\out{
}}\preformatted{#include 45 | #define NEW_LOGICAL(n) Rf_allocVector(LGLSXP,n) 46 | #define NEW_INTEGER(n) Rf_allocVector(INTSXP,n) 47 | #define NEW_NUMERIC(n) Rf_allocVector(REALSXP,n) 48 | #define NEW_CHARACTER(n) Rf_allocVector(STRSXP,n) 49 | #define NEW_COMPLEX(n) Rf_allocVector(CPLXSXP,n) 50 | #define NEW_LIST(n) Rf_allocVector(VECSXP,n) 51 | #define NEW_STRING(n) NEW_CHARACTER(n) 52 | #define NEW_RAW(n) Rf_allocVector(RAWSXP,n) 53 | }\if{html}{\out{
}} 54 | } 55 | 56 | \section{R API}{ 57 | 58 | 59 | \if{html}{\out{
}}\preformatted{library(base) 60 | 61 | x_logical <- logical(length = n) 62 | x_integer <- integer(length = n) 63 | x_numeric <- numeric(length = n) 64 | x_character <- character(length = n) 65 | x_complex <- complex(length.out = n) 66 | x_list <- vector(mode = "list", length = n) 67 | x_raw <- raw(length = n) 68 | }\if{html}{\out{
}} 69 | } 70 | 71 | -------------------------------------------------------------------------------- /man/coerceVector.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/coerceVector.R 3 | \name{coerceVector} 4 | \alias{coerceVector} 5 | \alias{Rf_coerceVector} 6 | \alias{AS_LOGICAL} 7 | \alias{AS_INTEGER} 8 | \alias{AS_NUMERIC} 9 | \alias{AS_CHARACTER} 10 | \alias{AS_COMPLEX} 11 | \alias{AS_VECTOR} 12 | \alias{AS_LIST} 13 | \alias{AS_RAW} 14 | \title{Coerces a Vector} 15 | \source{ 16 | Declaration: \href{https://github.com/wch/r-source/blob/trunk/src/include/Rinternals.h}{src/include/Rinternals.h} and \href{https://github.com/wch/r-source/blob/trunk/src/include/Rdefines.h}{src/include/Rdefines.h} 17 | 18 | Implementation: \href{https://github.com/wch/r-source/blob/trunk/src/main/coerce.c}{src/main/coerce.c} 19 | } 20 | \usage{ 21 | coerceVector(v, type) 22 | } 23 | \arguments{ 24 | \item{v}{(\link{SEXP}) An \R object.} 25 | 26 | \item{type}{(\link{SEXPTYPE}) An macro constant of length one.} 27 | } 28 | \value{ 29 | \code{coerceVector()} returns an \link{SEXP} object of type \link{SEXPTYPE} \code{type}. 30 | } 31 | \description{ 32 | Coerces a Vector 33 | } 34 | \section{C API}{ 35 | 36 | 37 | \if{html}{\out{
}}\preformatted{#include 38 | SEXP Rf_coerceVector(SEXP, SEXPTYPE) 39 | #define coerceVector Rf_coerceVector 40 | }\if{html}{\out{
}} 41 | 42 | Related macros: 43 | 44 | \if{html}{\out{
}}\preformatted{#include 45 | #define AS_LOGICAL(x) Rf_coerceVector(x,LGLSXP) 46 | #define AS_INTEGER(x) Rf_coerceVector(x,INTSXP) 47 | #define AS_NUMERIC(x) Rf_coerceVector(x,REALSXP) 48 | #define AS_CHARACTER(x) Rf_coerceVector(x,STRSXP) 49 | #define AS_COMPLEX(x) Rf_coerceVector(x,CPLXSXP) 50 | #define AS_VECTOR(x) Rf_coerceVector(x,VECSXP) 51 | #define AS_LIST(x) Rf_coerceVector(x,VECSXP) 52 | #define AS_RAW(x) Rf_coerceVector(x,RAWSXP) 53 | }\if{html}{\out{
}} 54 | } 55 | 56 | \section{R API}{ 57 | 58 | 59 | \if{html}{\out{
}}\preformatted{library(base) 60 | 61 | x <- 1:5 62 | y_integer <- as.integer(x) 63 | y_logical <- as.logical(x) 64 | y_numeric <- as.numeric(x) 65 | y_character <- as.character(x) 66 | }\if{html}{\out{
}} 67 | } 68 | 69 | -------------------------------------------------------------------------------- /man/figures/getAttrib.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/HenrikBengtsson/RNativeAPI/96b1213710d26549141bc3e94124e1b762076023/man/figures/getAttrib.png -------------------------------------------------------------------------------- /man/getAttrib.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/setAttrib.R 3 | \name{getAttrib} 4 | \alias{getAttrib} 5 | \alias{setAttrib} 6 | \title{Gets and Sets an Attribute of an R Object} 7 | \source{ 8 | Declaration: \href{https://github.com/wch/r-source/blob/trunk/src/include/Rinternals.h}{src/include/Rinternals.h} 9 | 10 | Implementation: \href{https://github.com/wch/r-source/blob/trunk/src/main/attrib.c}{src/main/attrib.c} 11 | } 12 | \usage{ 13 | getAttrib(vec, name) 14 | 15 | setAttrib(vec, name, val) 16 | } 17 | \arguments{ 18 | \item{vec}{(\link{SEXP}) An \R object.} 19 | 20 | \item{name}{(\link{SEXP}) A \link{character} of length one.} 21 | 22 | \item{val}{(\link{SEXP}) An \R object.} 23 | } 24 | \value{ 25 | \code{getAttrib()} returns (\link{SEXP}) the value of attribute \code{name}. 26 | 27 | \code{setAttrib()} returns (\link{SEXP}) a copy of \R object \code{vec} with attribute \code{name} set. 28 | 29 | (\link{SEXP}) 30 | } 31 | \description{ 32 | Gets and Sets an Attribute of an R Object 33 | } 34 | \section{C API}{ 35 | 36 | 37 | \if{html}{\out{
}}\preformatted{#include 38 | 39 | SEXP getAttrib(SEXP vec, SEXP name) 40 | SEXP setAttrib(SEXP vec, SEXP name, SEXP val) 41 | }\if{html}{\out{
}} 42 | } 43 | 44 | \section{R API}{ 45 | 46 | 47 | \if{html}{\out{
}}\preformatted{library(base) 48 | 49 | value <- attr(vec, name, exact = TRUE) 50 | attr(vec, name) <- val 51 | }\if{html}{\out{
}} 52 | } 53 | 54 | -------------------------------------------------------------------------------- /man/isNumeric.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/isNumeric.R 3 | \name{isNumeric} 4 | \alias{isNumeric} 5 | \alias{Rf_isNumeric} 6 | \title{Checks if an SEXP is of Certain Type} 7 | \source{ 8 | Declaration: \href{https://github.com/wch/r-source/blob/trunk/src/include/Rinternals.h}{src/include/Rinternals.h} and \href{https://github.com/wch/r-source/blob/trunk/src/include/Rdefines.h}{src/include/Rdefines.h} 9 | 10 | Implementation: Inline function \verb{isNumeric(SEXP s)}, cf. \href{https://github.com/wch/r-source/blob/trunk/src/include/Rinlinedfuns.h}{src/include/Rinlinedfuns.h} 11 | } 12 | \usage{ 13 | isNumeric(s) 14 | } 15 | \arguments{ 16 | \item{s}{(\link{SEXP}) An \R object.} 17 | } 18 | \value{ 19 | (\code{Rboolean}) \code{true} (=1) or \code{false} (=0). 20 | } 21 | \description{ 22 | Checks if an SEXP is of Certain Type 23 | } 24 | \section{C API}{ 25 | 26 | 27 | \if{html}{\out{
}}\preformatted{#include 28 | Rboolean Rf_isNumeric(SEXP); 29 | #define isNumeric Rf_isNumeric 30 | }\if{html}{\out{
}} 31 | } 32 | 33 | \section{R API}{ 34 | 35 | 36 | \if{html}{\out{
}}\preformatted{library(base) 37 | 38 | is.numeric(integer(length = 2L)) ## TRUE 39 | is.numeric(numeric(length = 2L)) ## TRUE 40 | is.numeric(factor(c("a", "b"))) ## FALSE 41 | is.numeric(logical(length = 2L)) ## FALSE but isNumeric() = true! 42 | }\if{html}{\out{
}} 43 | } 44 | 45 | --------------------------------------------------------------------------------