This unofficial, incomplete, perpetually lagging behind, and subtly
wrong document attempts to document the surface of the C API of the R
programming language in the style of Unix man pages or the
Rd help system.
© 2024 Ivan Krylov, Erez Shomron
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved an author.
In preparation of this work, the authors read the R source code (© R Core Team, GPL ≥ 2), R header files (LGPL ≥ 2.1), and manuals such as “Writing R Extensions” and “R Internals” (Latex2e-translated-notice).
Next: Constants, Previous: Introduction, Up: Introduction [Index]
#include <Rinternals.h> typedef struct SEXPREC * SEXP;
This is a pointer to an incomplete type that represents a single value
in R. It is almost never correct to give a null SEXP to R (some
clearly marked ALTREP methods are allowed to return a null SEXP).
With only two exceptions (see tryEval), R will never
return a null
SEXP1.
#include <Rinternals.h> typedef /*...*/ R_xlen_t; #define R_XLEN_T_MAX /*...*/ #define R_PRIdXLEN_T /*...*/
A signed integer type that represents lengths of R vectors. Will likely
be larger than a plain int on 64-bit platforms. (Note that
long is 32-bit on 64-bit Windows!)
In practice, all feasible values of this type can be safely represented
inside of a double value, and R_XLEN_T_MAX places an
appropriate upper limit.
Use R_PRIdXLEN_T as an appropriate printf specifier to
print values of type R_xlen_t on R ≥ 4.4:
Rprintf("%" R_PRIdXLEN_T "\n", XLENGTH(value));
Versions: Long vector support appeared in version 3.0.0.
#include <Rinternals.h> typedef int R_len_t; #define R_LEN_T_MAX INT_MAX
A signed integer type that represents lengths of “standard” (that is, non-long) R vectors. In most places, R_xlen_t should be used instead.
#include <R_ext/Boolean.h>
typedef /*...*/ Rboolean;
enum { FALSE=0, TRUE };
A C type with enumeration constants FALSE and TRUE defined.
Next: PROTECT_INDEX, Previous: Rboolean, Up: Types [Index]
#include <R_ext/Rdynload.h> typedef /*...*/ (*DL_FUNC)(/*...*/);
The type used to pass around function pointers. Casts to and from
DL_FUNC are required to avoid diagnostic messages from the
compiler; the true type of the function must be known separately.
#include <Rinternals.h> typedef /*...*/ PROTECT_INDEX;
A C integer type used to represent positions on the internal pointer protection stack. See PROTECT_WITH_INDEX.
Next: R_SIZE_T, Previous: PROTECT_INDEX, Up: Types [Index]
#include <Rinternals.h> typedef /*...*/ SEXPTYPE;
A C integer type that identifies the type of an R value. See Writing R Extensions, section 5.9.3 “Details of R types” for more information.
| Type | Name | Meaning |
|---|---|---|
NILSXP | NULL | The R NULL value. See R_NilValue for the pre-existing object. |
SYMSXP | symbol name | Symbols are used for names of R objects. They are persistent (never garbage-collected); each contains a string in the native encoding. See install for creation of new symbols. |
LISTSXP | pairlist | Lisp-style pairlists consist of “CONS cells”, each
containing two arbitrary R objects (CAR and CDR) and an
optional TAG, which must be a symbol. Typically, CAR
represents the current element in the list while CDR points at
the next cell in the list. See CONS and allocVector for
creation of new pairlists. |
CLOSXP | closure | A normal R function, consists of “formals” (its arguments), body (the code of the function) and environment (where the variables are looked up if not present in the calling frame). See R_mkClosure for creation of new closures. |
ENVSXP | environment | Environments contain variables and reference parent environments. See R_NewEnv for creation of new environments. |
PROMSXP | promise | Promises are an implementation detail of R’s lazy evaluation. |
LANGSXP | language | Like LISTSXP above, but used to express language constructs,
such as function calls. See LCONS and allocVector for creation
of new call objects. |
SPECIALSXP BUILTINSXP | special builtin | .Internal and .Primitive R functions, respectively. |
CHARSXP | char | Internal type used for individual elements of character vectors. See mkChar for creation of new strings. |
LGLSXP | logical | logical() vectors in R, individual elements represented by
ints. See allocVector or ScalarLogical. |
INTSXP | integer | integer() vectors in R, individual elements represented by
ints. See allocVector or ScalarInteger. |
REALSXP | double numeric | numeric() vectors in R, individual elements represented by
doubles. See allocVector or ScalarReal. |
CPLXSXP | complex | complex() vectors in R, individual elements of type
Rcomplex. See allocVector or
ScalarComplex. |
STRSXP | character | character() vectors in R, individual elements are
SEXPs of type CHARSXP (see above). See allocVector
or mkString or ScalarString. |
DOTSXP | ... | Internal object used to represent the function arguments contained
inside ... during a function call. |
VECSXP | list | “Generic vectors” (list()) in R. Individual elements are
arbitrary SEXPs. See allocVector. |
EXPRSXP | expression | expression() vectors in R, indended for storage of
LANGSXP objects. Very similar to VECSXP lists.
See allocVector. |
BCODESXP | bytecode | Function bytecode. |
EXTPTRSXP | externalptr | An R object wrapping an arbitrary data or function pointer, can have a finalizer attached. See R_MakeExternalPtr. |
WEAKREFSXP | weakref | A weak reference to another reference-semantics R object, can have a finalizer attached. See R_MakeWeakRef. |
RAWSXP | raw | raw() vectors in R, intended for storage of arbitrary bytes.
See allocVector or ScalarRaw. |
OBJSXP S4SXP | object S4 | Formal objects that don’t inherit from a different base type.
See allocS4Object, an experimental interface. The name S4SXP has been deprecated (but not removed) in version
4.4, introducing OBJSXP instead. |
ANYSXP | any | Used internally to denote a function accepting any R value as an argument. |
In general, behaviour is undefined if using a SEXPTYPE that is
not one of the constants mentioned above.
#include <R_ext/Utils.h> #define R_SIZE_T /*...*/
A C preprocessor definition that expands to either size_t in C or
std::size_t in C++. The header includes either stddef.h or
cstddef to provide the actual type definition.
#include <Rinternals.h>
typedef enum {
CE_NATIVE = /*...*/,
CE_UTF8 = /*...*/,
CE_LATIN1 = /*...*/,
CE_BYTES = /*...*/,
CE_SYMBOL = /*...*/,
CE_ANY = /*...*/,
} cetype_t;
A set of C enumeration constants defining character encoding codes for use in strings:
CE_NATIVE ¶The encoding defined by the current locale. Will correspond to UTF-8 on most modern systems, but may refer to the ANSI code page on older versions of Windows, or something completely different, such as ISO-8859-15 (Latin-9) or KOI8-R, on other Unix-like systems.
CE_UTF8 ¶The multi-byte Unicode encoding used by most systems at the time of writing.
CE_LATIN1 ¶Latin-1 is also known as ISO-8859-1, the ISO/IEC 8859 character encoding designed for use in Western Europe.
CE_BYTES ¶Used to mark a string as containing bytes in an unknown encoding so that it will not be translated. The zero byte still terminates a string, so having it in the middle of one is not allowed.
CE_SYMBOL ¶Used internally to indicate the Adobe Symbol encoding.
CE_ANY ¶Used internally to indicate that the string will not need re-encoding.
Next: Functions, Previous: Types, Up: Introduction [Index]
Next: R_NamesSymbol, Up: Constants [Index]
#include <Rinternals.h> LibExtern SEXP R_NilValue;
The NULL R value, of type NILSXP. No other values of this
type need to be created. This is the representation of an empty
pairlist.
Next: R_PosInf, Previous: R_NilValue, Up: Constants [Index]
#include <Rinternals.h> LibExtern SEXP R_DimNamesSymbol; LibExtern SEXP R_NamesSymbol;
The pre-installed symbols for attribute names (see setAttrib)
names and dimnames.
Next: M_PI, Previous: R_NamesSymbol, Up: Constants [Index]
#include <R_ext/Arith.h> /* alternatively: */ #include <Rmath.h> extern double R_PosInf; extern double R_NegInf; #define NA_REAL /*...*/
These variables contain the special floating-point values.
The positive infinity is larger than all values except itself and NaN, and the negative infinity is lower than all values except itself and NaN.
NA_REAL is a NaN value with a payload that identifies it as a
missing value (see ISNAN).
#include <R_ext/Constants.h> #ifndef M_PI #define M_PI /*...*/ #endif #include <Rmath.h> #ifndef M_PI #define M_PI /*...*/ #endif #ifndef M_E #define M_E /*...*/ #endif
These preprocessor constants define the π number and the Euler’s constant e.
#include <Rconfig.h> #define R_INLINE /*...*/
This preprocessor constant expands to the inline keyword suitable
for the C compiler, or to nothing if no such keyword was found during
the R configuration.
#include <Rversion.h> #define R_Version(v, p, s) /*...*/ #define R_VERSION /*...*/ #define R_MAJOR /*...*/ #define R_MINOR /*...*/ #define R_YEAR /*...*/ #define R_MONTH /*...*/ #define R_DAY /*...*/
The major version number, “4” in “4.5.0”.
The minor version number, “5” in “4.5.0”.
The “patch” version number, “0” in “4.5.0”.
R_VersionR_VERSIONA call to the R_Version(v, p, s) macro expands
to a numeric expression the value of which is comparable to the
pre-defined integer constant R_VERSION. It is intended for use
with integer constants in preprocessor tests:
#if R_VERSION >= R_Version(3, 3, 0) /* Can use features from R-3.3.0 */ #endif
R_MAJORExpands to a string literal containing the current major version of R.
R_MINORExpands to a string literal containing the current minor and patch
versions of R separated by a dot: "p.s".
R_YEARR_MONTHR_DAYThese macros expand to string literals containing the release date of the current version of R.
Next: Experimental functions, Previous: Constants, Up: Introduction [Index]
Next: PrintValue, Up: Functions [Index]
#include <Rinternals.h> R_xlen_t XLENGTH(SEXP x); R_xlen_t Rf_xlength(SEXP x); #ifndef R_NO_REMAP #define xlength Rf_xlength #endif int LENGTH(SEXP x); R_len_t Rf_length(SEXP x); #ifndef R_NO_REMAP #define length Rf_length #endif
An R value of a vector type: CHARSXP, LGLSXP,
INTSXP, REALSXP, CPLXSXP, STRSXP,
VECSXP, EXPRSXP, RAWSXP.
For Rf_xlength, also allowed are NILSXP, LISTSXP,
LANGSXP, DOTSXP, and ENVSXP, and all other types.
XLENGTHRf_xlengthReturns the number of elements in the vector. Rf_xlength will
also return 0 for a NILSXP; the number of elements in a pairlist
type (LISTSXP, LANGSXP, DOTSXP); the number of
elements in an environment (ENVSXP). For a CHARSXP, the
length of the string, not including the terminating zero byte. Behaviour
is unspecified for XLENGTH if x is not of a vector type.
Rf_xlength returns 1 for all other types.
Versions: This function appeared in version 3.0.0.
LENGTHRf_lengthSame as Rf_xlength, but raises an error if the length is not
representable as an R_len_t / int.
Next: R_registerRoutines, Previous: XLENGTH, Up: Functions [Index]
#include <Rinternals.h> void Rf_PrintValue(SEXP s); #ifndef R_NO_REMAP #define PrintValue Rf_PrintValue #endif
Not declared in a public header, for use in a debugger:
void R_PV(SEXP s);
An arbitrary R object to be printed. For R_PV, must have the
class attribute set.
Prints a representation of s on R’s standard output using the global printing options.
Next: R_RegisterCCallable, Previous: PrintValue, Up: Functions [Index]
#include <R_ext/Rdynload.h> int R_registerRoutines( DllInfo *info, const R_CMethodDef * const croutines, const R_CallMethodDef * const callRoutines, const R_FortranMethodDef * const fortranRoutines, const R_ExternalMethodDef * const externalRoutines ); Rboolean R_useDynamicSymbols( DllInfo *info, Rboolean use_symbols ); Rboolean R_forceSymbols( DllInfo *info, Rboolean force_symbols ); DL_FUNC R_FindSymbol( char const * name, char const * pkg, R_RegisteredNativeSymbol * symbol );
An opaque pointer passed by R to the initialization routine of the package.
An array of structs describing the native functions for use with
.C in the R code, containing the following fields:
const char *nameThe R-visible name of the function.
DL_FUNC funThe pointer to the function. The function is not required to conform to
the DL_FUNC prototype; R will cast the pointer back as
appropriate according to the value of numArgs.
int numArgsThe number of arguments accepted by the function.
R_NativePrimitiveArgType *typesOptional. If specified, must be an array of numArgs values
containing one of the SEXPTYPE constants, SINGLESXP (for
single-precision floats), or ANYSXP (meaning “any
otherwise supported argument”). Passing a NILSXP to .C
functions is not allowed; passing of LISTSXP lists is deprecated.
The array must be terminated by {NULL, NULL, 0, NULL}.
Versions: Prior to version 3.4.0, the
structcontained a nullable field,R_NativeArgStyle *styles, which was intended to specify whether an argument was for input, output, or something else.
An array of descriptions of native functions for use with .Call
in the R code. The structure fields are as follows:
const char *nameThe R-visible name of the function.
DL_FUNC funThe pointer to the function. R will cast the pointer as appropriate
according to the value of numArgs.
int numArgsThe number of arguments accepted by the function.
Must be terminated by {NULL, NULL, 0}.
An array of descriptions of native functions for use with
.Fortran in the R code. The structure fields are the same as in
croutines.
There are portability problems associated with passing STRSXPs to
.Fortran code: only the first element of the vector will be
passed. Passing VECSXP or LISTSXP lists, NILSXP,
functions, and environments is not allowed.
An array of descriptions of native functions for use with
.External in the R code. The structure fields are the same as in
callRoutines.
If FALSE, will disable the lookup of package functions by their
linker-level names and will only allow calling registered functions from
the package shared library, but R code will still be able to specify the
registered name as a string.
If TRUE, will only allow to call the native routines from this
shared library using special objects provided by
useDynLib(.registration = TRUE), not by their names.
The name of a native function registered by a package using
R_registerRoutines or exported by its shared object, a
0-terminated C string in the native encoding.
The name of the package to look up the function in, a 0-terminated C string in the native encoding. Can be an empty string to mean all shared objects loaded by R.
Pointer to an opaque structure used internally. Must be a null pointer.
R_registerRoutinesRegisters the native functions for use with R. May raise R-level errors.
R_useDynamicSymbolsR_forceSymbolsSets function resolution options, returning the previous value of the setting.
R_FindSymbolLooks up and returns the address of a symbol specified by name in
shared objects loaded by R and specified by pkg. For shared
objects where useDynamicLookup is set to FALSE, only the
registered symbols are searched and no dynamic lookup is performed. For
shared objects where forceSymbols is set to TRUE, the
lookup is not performed at all.
See Writing R Extensions, section 5.4 “Registering native routines” for more information.
Next: PROTECT, Previous: R_registerRoutines, Up: Functions [Index]
#include <R_ext/Rdynload.h> void R_RegisterCCallable( const char *package, const char *name, DL_FUNC fptr ); DL_FUNC R_GetCCallable( const char *package, const char *name );
The name of the package that owns the function.
The string identifying the function within the package.
The function pointer to be stored by R_RegisterCCallable and
returned by R_GetCCallable. The function doesn’t have to conform
to the DL_FUNC prototype; it is expected that the pointer will be
cast to some other function type.
R_RegisterCCallableAssociates fptr with the two strings package and name.
R_GetCCallableReturns the fptr from the previously established association or raises an error.
The package that calls R_GetCCallable must specify the
owner of the callable in both LinkingTo and either Imports
or Depends of its DESCRIPTION. Great care must be taken to
ensure that the interface of the callable matches the expectations of
the caller.
See Writing R Extensions, section 5.4.3 “Linking to native routines in other packages” for more information.
Versions: Both functions first introduced in version 2.4.0.
Next: PROTECT_WITH_INDEX, Previous: R_RegisterCCallable, Up: Functions [Index]
#include <Rinternals.h> SEXP Rf_protect(SEXP x); #ifndef R_NO_REMAP #define protect Rf_protect #endif #define PROTECT(x) Rf_protect(x) void Rf_unprotect(int n); #ifndef R_NO_REMAP #define unprotect Rf_unprotect #endif #define UNPROTECT(n) Rf_unprotect(n)
An arbitrary R value.
The number of R values to remove from the pointer protection stack.
Rf_protectPuts the x on the internal pointer protection stack so that it won’t be
deallocated by the garbage collector. Any values referenced by x
are also protected. Raises an error if the (limited-size) stack is full.
Returns the same x, making it possible to use the idiom SEXP
val = PROTECT(get_val());.
Unlike almost all of R API, PROTECT will not invoke the garbage
collector while running.
Rf_unprotectRemoves the last n elements from the pointer protection stack. The package code must leave the pointer protection stack in the same state as it was on function entry.
Almost all R functions can invoke the garbage collector, so any value that may be used later in a function must be protected before calling R API. It’s best to write functions that only protect a constant number of elements regardless of the size of the input.
Next: R_PreserveInMSet, Previous: PROTECT, Up: Functions [Index]
#include <Rinternals.h> void R_ProtectWithIndex( SEXP value, PROTECT_INDEX * index ); #define PROTECT_WITH_INDEX(value, index) R_ProtectWithIndex(value, index) void R_Reprotect( SEXP value, PROTECT_INDEX index ); #define REPROTECT(value, index) R_Reprotect(value, index)
An arbitrary R value.
The index identifying the position of value on the pointer protection stack.
R_ProtectWithIndexProtects (see PROTECT) the value and returns the protection index in the output variable index.
R_ReprotectPuts the given value at position index in the pointer protection stack, replacing the one previously referenced there.
Unlike almost all of R API, these two functions are guaranteed not to invoke the garbage collector while running.
Next: UNPROTECT_PTR, Previous: PROTECT_WITH_INDEX, Up: Functions [Index]
#include <Rinternals.h> SEXP R_NewPreciousMSet(int n); void R_PreserveInMSet( SEXP x, SEXP mset ); void R_ReleaseFromMSet( SEXP x, SEXP mset );
The initial size of the precious multi-set.
An arbitrary R value.
A precious multi-set previously returned by R_NewPreciousMSet.
The precious multi-set is introduced to make it possible to protect
values and then unprotect them by value (as opposed to unprotecting by
index in the protection stack), even if a single value has been
protected more than once. The need for this reportedly arises in
generated parser code (such as bison/yacc).
R_NewPreciousMSetReturns a newly allocated precious multi-set. Its SEXPTYPE is
unspecified; it should only be used with functions described here. Like
other R values, it must be protected and will protect values placed
inside it.
R_PreserveInMSetAdds the value into mset, resizing it as needed. The allocation may fail and raise an error.
R_ReleaseFromMSetDecrements the count of value in mset. This will unprotect
value if the count reaches 0 and it’s not referenced in a
different protected value.
Versions: These functions appeared in version 3.6.0.
Next: R_PreserveObject, Previous: R_PreserveInMSet, Up: Functions [Index]
#include <Rinternals.h> void Rf_unprotect_ptr(SEXP x); #ifndef R_NO_REMAP #define unprotect_ptr Rf_unprotect_ptr #endif #define UNPROTECT_PTR(x) Rf_unprotect_ptr(x)
An arbitrary R value.
Locates x on the protection stack and unprotects it.
This function is dangerous and may result in unexpected protection stack layout and hard-to-debug issues if x is protected multiple times. See also: https://blog.r-project.org/2018/12/10/unprotecting-by-value/index.html.
Next: allocVector, Previous: UNPROTECT_PTR, Up: Functions [Index]
#include <Rinternals.h> void R_PreserveObject(SEXP x); void R_ReleaseObject(SEXP x);
An arbitrary R value.
R_PreserveObjectPuts x into the persistent list of objects that should not be garbage-collected. This list persists for the duration of the R session.
R_ReleaseObjectRemoves x from the persistent list of protected objects.
Next: xlengthgets, Previous: R_PreserveObject, Up: Functions [Index]
#include <Rinternals.h> SEXP Rf_allocVector( SEXPTYPE type, R_xlen_t length ); #ifndef R_NO_REMAP #define allocVector Rf_allocVector #endif SEXP Rf_alloc3DArray( SEXPTYPE type, int dim1, int dim2, int dim3 ); #ifndef R_NO_REMAP #define alloc3DArray Rf_alloc3DArray #endif SEXP Rf_allocArray( SEXPTYPE type, SEXP dim ); #ifndef R_NO_REMAP #define allocArray Rf_allocArray #endif SEXP Rf_allocMatrix( SEXPTYPE type, int nrows, int ncols ); #ifndef R_NO_REMAP #define allocMatrix Rf_allocMatrix #endif
The type of the vector to allocate (see SEXPTYPE): must be any of
the vector types (CHARSXP, LGLSXP, INTSXP,
REALSXP, CPLXSXP, STRSXP, VECSXP,
EXPRSXP, RAWSXP), or the pairlist types (LISTSXP,
LANGSXP).
The length of the vector-to-be.
The desired dimensions of the array (as in c(dim1,
dim2, dim3)). Their product must not overflow R_xlen_t.
The desired dim attribute provided as an already existing R
vector dim of type INTSXP. prod(dim) must not
overflow R_xlen_t.
The desired dimensions of the matrix to allocate.
Rf_allocVectorAllocates and returns a vector of the specified type and length. Signals an R-level error if an allocation fails or if length exceeds an internal limit.
Here and below, the the contents of the freshly-allocated vector depends
on its type. Contents of atomic vectors (REALSXP, INTSXP,
LGLSXP, CPLXSXP, RAWSXP) will be undefined and must
be initialised before any other use. EXPRSXP and VECSXP
vectors will consist of R_NilValue elements. An STRSXP
vector will consist of blank strings. See allocList for pairlists.
Rf_alloc3DArrayVersions: Appeared in 2.6.0.
Rf_allocArrayAllocates and returns an array of the specified type with the
specified dimensions (either dim or c(dim1,
dim2, dim3)). The dim value becomes shared with the
returned value.
If prod(dim) or the product of dim1, dim2,
dim3 overflows R_xlen_t, behaviour is
undefined2.
Rf_allocMatrixA matrix of the specified type and dimensions
(c(nrows, ncols)).
Next: R_alloc, Previous: allocVector, Up: Functions [Index]
#include <Rinternals.h> SEXP Rf_lengthgets( SEXP x, R_len_t n ); #ifndef R_NO_REMAP #define lengthgets Rf_lengthgets #endif SEXP Rf_xlengthgets( SEXP x, R_xlen_t n ); #ifndef R_NO_REMAP #define xlengthgets Rf_xlengthgets #endif
An R value of a vector type: CHARSXP, LGLSXP,
INTSXP, REALSXP, CPLXSXP, STRSXP,
VECSXP, EXPRSXP, RAWSXP.
The desired length of the vector.
Returns the equivalent of length(x) <- n in R, which
may reuse the memory of the original x, or may be allocated anew.
The usual protection rules apply: after the call to xlengthgets,
the return value must be protected in place of x
(see PROTECT_WITH_INDEX).
Next: copyVector, Previous: xlengthgets, Up: Functions [Index]
#include <R_ext/Memory.h> char * R_alloc( R_SIZE_T n, int size ); long double * R_allocLD(size_t n); void* vmaxget(void); void vmaxset(const void * vmax); char * S_alloc(long n, int size); char * S_realloc( char * p, long n, long old, int size );
The number of elements to allocate the buffer for.
The size of individual element comprising the buffer to allocate.
The opaque context pointer previously returned by vmaxget.
A pointer previously returned by S_alloc.
R_allocAllocates a buffer for n contiguous elements, each of size
size, overflow-safe, with the typical malloc guarantees
about alignment, and returns a pointer to it. An error is raised on any
failures. The memory is managed by R and will be released automatically
on return from a call to .C(...) / .Call(...) /
.External(...).
R_allocLDAllocates an appropriately aligned buffer of long double[n]
in a similar manner and returns a pointer to it.
Versions: This function has been introduced in version 3.2.0.
vmaxgetReturns the context pointer indicating the currently protected
allocations previously made by R_alloc or R_allocLD or
other R functions that use these two internally.
vmaxsetRestores the context pointer, unprotecting all the allocations made
since the corresponding call to vmaxget.
S_allocLike R_alloc, but the returned buffer is zeroed out. Not
recommended for general use because the number of elements n is
only of type long, which may be much smaller than size_t.
S_reallocLike S_alloc, but the first old elements of the buffer are
copied from p. The allocation in p is otherwise untouched
and remains valid. If old * size overflows
size_t, behaviour is undefined.
Next: copyMostAttrib, Previous: R_alloc, Up: Functions [Index]
#include <Rinternals.h> void Rf_copyVector( SEXP destination, SEXP source ); #ifndef R_NO_REMAP #define copyVector Rf_copyVector #endif void Rf_copyMatrix( SEXP destination, SEXP source, Rboolean byrow ); #ifndef R_NO_REMAP #define copyMatrix Rf_copyMatrix #endif
R values of the same vector type, one of STRSXP, LGLSXP,
INTSXP, REALSXP, CPLXSXP, EXPRSXP,
VECSXP, RAWSXP, but not necessarily same length. For
copyMatrix, destination must be a matrix.
If TRUE, fill destination with elements row by row, like
matrix(byrow = TRUE) in R. Otherwise fill it column by column, as
in copyVector.
Rf_copyVectorCopies the contents of source into target, filling the
entire xlength(target), recycling the elements of
source if necessary.
Rf_copyMatrixLike copyVector, but makes it possible to fill a matrix row by
row from a vector.
Next: isReal, Previous: copyVector, Up: Functions [Index]
#include <Rinternals.h> void Rf_copyMostAttrib( SEXP source, SEXP destination ); #ifndef R_NO_REMAP #define copyMostAttrib Rf_copyMostAttrib #endif
An arbitrary R value to take the attributes from.
An arbitrary R value (except NULL, which doesn’t have attributes)
to set the attributes on.
destination takes on the values of every attribute of source
except names, dim, dimnames, sharing them with
source without duplication.
Sets the object bit on destination if it was set on source; sets the S4 object bit on destination to the value it had on source.
Next: isArray, Previous: copyMostAttrib, Up: Functions [Index]
#include <Rinternals.h> Rboolean Rf_isComplex(SEXP value); #ifndef R_NO_REMAP #define isComplex Rf_isComplex #endif Rboolean Rf_isEnvironment(SEXP value); #ifndef R_NO_REMAP #define isEnvironment Rf_isEnvironment #endif Rboolean Rf_isExpression(SEXP value); #ifndef R_NO_REMAP #define isExpression Rf_isExpression #endif Rboolean Rf_isFunction(SEXP value); #ifndef R_NO_REMAP #define isFunction Rf_isFunction #endif Rboolean Rf_isInteger(SEXP value); #ifndef R_NO_REMAP #define isInteger Rf_isInteger #endif Rboolean Rf_isLanguage(SEXP value); #ifndef R_NO_REMAP #define isLanguage Rf_isLanguage #endif Rboolean Rf_isList(SEXP value); #ifndef R_NO_REMAP #define isList Rf_isList #endif Rboolean Rf_isLogical(SEXP value); #ifndef R_NO_REMAP #define isLogical Rf_isLogical #endif Rboolean Rf_isNewList(SEXP value); #ifndef R_NO_REMAP #define isNewList Rf_isNewList #endif Rboolean Rf_isNull(SEXP value); #ifndef R_NO_REMAP #define isNull Rf_isNull #endif Rboolean Rf_isPairList(SEXP value); #ifndef R_NO_REMAP #define isPairList Rf_isPairList #endif Rboolean Rf_isPrimitive(SEXP value); #ifndef R_NO_REMAP #define isPrimitive Rf_isPrimitive #endif Rboolean Rf_isReal(SEXP value); #ifndef R_NO_REMAP #define isReal Rf_isReal #endif Rboolean Rf_isString(SEXP value); #ifndef R_NO_REMAP #define isString Rf_isString #endif Rboolean Rf_isSymbol(SEXP value); #ifndef R_NO_REMAP #define isSymbol Rf_isSymbol #endif Rboolean Rf_isVector(SEXP value); #ifndef R_NO_REMAP #define isVector Rf_isVector #endif Rboolean Rf_isVectorAtomic(SEXP value); #ifndef R_NO_REMAP #define isVectorAtomic Rf_isVectorAtomic #endif Rboolean Rf_isVectorList(SEXP value); #ifndef R_NO_REMAP #define isVectorList Rf_isVectorList #endif
An arbitrary R value.
Rf_isComplexRf_isEnvironmentRf_isExpressionRf_isIntegerRf_isLogicalRf_isNullRf_isRealRf_isSymbolReturns TRUE if TYPEOF(value) is equal to the
corresponding type code, otherwise FALSE.
Rf_isStringReturns TRUE if value is of type STRSXP (not
CHARSXP).
Rf_isFunctionReturns TRUE if value is a closure (CLOSXP) or one
of the callable primitives (BUILTINSXP / SPECIALSXP).
Rf_isLanguageReturns TRUE if value is a language pairlist, i.e.
LANGSXP or NILSXP.
Note that the test differs from R’s is.language(), which will
also return TRUE for SYMSXP or EXPRSXP.
Rf_isListReturns TRUE if value is a pairlist, i.e., LISTSXP
or NILSXP.
Rf_isNewListReturns TRUE if value is a NILSXP or a
VECSXP.
Rf_isPairListReturns TRUE if value is of a type implemented as
Lisp-style pairlists, i.e., one of NILSXP, LISTSXP,
LANGSXP, DOTSXP (new in 3.2.0).
Rf_isPrimitiveReturns TRUE if value is a primitive function:
BUILTINSXP or SPECIALSXP.
Rf_isVectorRf_isVectorAtomicRf_isVectorListisVectorAtomic returns TRUE if value has one of the
atomic vector types: LGLSXP, INTSXP, REALSXP,
CPLXSXP, STRSXP, RAWSXP.
isVectorList returns TRUE if value has one of the
recursive vector list types: VECSXP, EXPRSXP.
isVector returns TRUE if either isVectorAtomic or
isVectorList is TRUE.
Next: coerceVector, Previous: isReal, Up: Functions [Index]
#include <Rinternals.h> Rboolean Rf_isArray(SEXP value); #ifndef R_NO_REMAP #define isArray Rf_isArray #endif Rboolean Rf_isDataFrame(SEXP value); #ifndef R_NO_REMAP #define isDataFrame Rf_isDataFrame #endif Rboolean Rf_isFactor(SEXP value); #ifndef R_NO_REMAP #define isFactor Rf_isFactor #endif Rboolean Rf_isMatrix(SEXP value); #ifndef R_NO_REMAP #define isMatrix Rf_isMatrix #endif Rboolean Rf_isNumber(SEXP value); #ifndef R_NO_REMAP #define isNumber Rf_isNumber #endif Rboolean Rf_isNumeric(SEXP value); #ifndef R_NO_REMAP #define isNumeric Rf_isNumeric #endif Rboolean Rf_isObject(SEXP value); #ifndef R_NO_REMAP #define isObject Rf_isObject #endif Rboolean Rf_isOrdered(SEXP value); #ifndef R_NO_REMAP #define isOrdered Rf_isOrdered #endif Rboolean Rf_isS4(SEXP value); #ifndef R_NO_REMAP #define isS4 Rf_isS4 #endif Rboolean Rf_isTs(SEXP value); #ifndef R_NO_REMAP #define isTs Rf_isTs #endif Rboolean Rf_isUnordered(SEXP value); #ifndef R_NO_REMAP #define isUnordered Rf_isUnordered #endif
An arbitrary R value.
Rf_isArrayReturns TRUE if value has a valid dim attribite: of
integer type, with a nonzero length.
Rf_isDataFrameReturns TRUE if value inherits from data.frame.
Versions: This function appeared in version 4.5.0.
Rf_isFactorRf_isOrderedRf_isUnorderedisFactor returns TRUE if value is of integer
type and inherits from factor. isOrdered additionally
tests that value inherits from ordered. Converesly,
isUnordered tests that a factor value does not
inherit from ordered.
Rf_isMatrixReturns TRUE if value is of a vector type and has a
two-element integer attribute dim.
Rf_isNumberReturns TRUE if value can be interpreted as a number (as
opposed to a category code): LGLSXP, REALSXP,
CPLXSXP are accepted, and so are INTSXP that don’t inherit
from factor.
Rf_isNumericReturns TRUE if value can be interpreted as a number (as
opposed to a category code): LGLSXP and REALSXP are
accepted, and so are INTSXP that don’t inherit from
factor. Unlike isNumber, CPLXSXP are not
accepted.
Rf_isObjectReturns TRUE if the object bit is set in value, i.e. it’s a
formal object or has a non-empty class attribute.
Rf_isS4Returns TRUE if value is an S4 object. S4 objects will
either have the SEXPTYPE of their base class or OBJSXP if
they don’t inherit from a primitive base class, so there is a separate
bit marking an object as an S4 object.
Rf_isTsReturns TRUE if value can be considered a time series
object, i.e., if it has a non-empty tsp attribute.
#include <Rinternals.h> SEXP Rf_coerceVector( SEXP x, SEXPTYPE type ); #ifndef R_NO_REMAP #define coerceVector Rf_coerceVector #endif
An arbitrary R value.
The desired type to convert x to.
Allocates and returns a copy x converted to SEXPTYPE type, if possible. Not all conversions make sense. An impossible conversion will raise an R error.
Next: GetArrayDimnames, Previous: coerceVector, Up: Functions [Index]
#include <Rinternals.h> SEXP Rf_getAttrib( SEXP vec, SEXP name ); #ifndef R_NO_REMAP #define getAttrib Rf_getAttrib #endif SEXP Rf_setAttrib( SEXP vec, SEXP name, SEXP val ); #ifndef R_NO_REMAP #define setAttrib Rf_setAttrib #endif
An arbitrary R value that can have attributes. It is not allowed to get
attributes of a NILSXP or get/set attributes for a
CHARSXP.
The name of the attribute as a SYMSXP or a one-element
STRSXP.
The desired value of the attribute.
Rf_getAttribReturns the value of the attribute, or R_NilValue if the
attribute was not set. Raises an error if vec is of type
CHARSXP.
Rf_setAttribSets the value of the given attribute, modifying vec. Removes the
attribute if val == R_NilValue. Raises an error if
vec is of type CHARSXP or NILSXP.
Next: GetColNames, Previous: setAttrib, Up: Functions [Index]
#include <Rinternals.h> SEXP Rf_GetArrayDimnames(SEXP x); #ifndef R_NO_REMAP #define GetArrayDimnames Rf_GetArrayDimnames #endif
An arbitrary R value that can have dimensions.
Returns the value of the dimnames attribute, possibly
R_NilValue.
Next: GetMatrixDimnames, Previous: GetArrayDimnames, Up: Functions [Index]
#include <Rinternals.h> SEXP Rf_GetColNames(SEXP dn); #ifndef R_NO_REMAP #define GetColNames Rf_GetColNames #endif SEXP Rf_GetRowNames(SEXP dn); #ifndef R_NO_REMAP #define GetRowNames Rf_GetRowNames #endif
The value of the dimnames attribute of an R value
(see GetArrayDimnames).
Rf_GetColNamesReturns the column names of the original value.
Rf_GetRowNamesReturns the row names of the original value.
These functions were useful for portability during the times when R was
switching from pairlist-based dimnames to VECSXP-based
dimnames. Nowadays, dimnames are always adjusted to be a
vector.
Next: dimnamesgets, Previous: GetColNames, Up: Functions [Index]
#include <Rinternals.h> void Rf_GetMatrixDimnames( SEXP x, SEXP *rl, SEXP *cl, const char **rn, const char **cn ); #ifndef R_NO_REMAP #define GetMatrixDimnames Rf_GetMatrixDimnames #endif
An arbitrary R value that can have dimensions.
A pointer to a SEXP that will point to the row names of x.
A pointer to a SEXP that will point to the column names of
x.
A pointer to a const char * that will point to the name of the
row dimension of x.
A pointer to a const char * that will point to the name of the
column dimension of x.
If x has dimnames, populates the output arguments rl,
cl with rownames(x), colnames(x). Sets
them to R_NilValue if the dimension names are not set.
If dimnames(x) is named, the strings pointed to by
rn, cn may be allocated using R_alloc and thus
subject to vmaxset memory management. Otherwise, the pointers
rn, cn will be set to NULL.
Next: install, Previous: GetMatrixDimnames, Up: Functions [Index]
#include <Rinternals.h> SEXP Rf_dimnamesgets( SEXP vec, SEXP val ); #ifndef R_NO_REMAP #define dimnamesgets Rf_dimnamesgets #endif SEXP Rf_dimgets( SEXP vec, SEXP val ); #ifndef R_NO_REMAP #define dimgets Rf_dimgets #endif SEXP Rf_namesgets( SEXP vec, SEXP val ); #ifndef R_NO_REMAP #define namesgets Rf_namesgets #endif
An R vector.
For namesgets, can also be a pairlist.
The desired attribute value for vec.
For dimnamesgets: a (possibly named) VECSXP list, or
NILSXP.
Must be either of length zero (thus removing the dimnames) or of
the same length as dim(vec), with the length of each
element of val equal to the corresponding element of
dim(vec).
For dimgets: a vector of nonzero length, losslessly convertible
to INTSXP, such that prod(val) == length(vec).
For namesgets: a vector convertible to STRSXP. Will be
recycled if shorter than vec.
Modifies the attributes (dimnames(), dim(), or
names()) of vec in place and returns vec.
Currently, setting dim(vec) removes
dimnames(vec).
Next: mkNamed, Previous: dimnamesgets, Up: Functions [Index]
#include <Rinternals.h> SEXP Rf_install(const char * name); #ifndef R_NO_REMAP #define install Rf_install #endif SEXP Rf_installChar(SEXP x); SEXP Rf_installTrChar(SEXP x); SEXP PRINTNAME(SEXP s);
A native-encoding string giving the value of the symbol to create.
A CHARSXP containing the name of the desired symbol. Will be
translated into the native encoding if required.
A SYMSXP value.
Rf_installRf_installCharRf_installTrCharLocates and returns an existing symbol with the given name, or creates, installs and returns a new one. Symbols are currently not garbage-collected, so installing a symbol once should be sufficient, and the returned value is safe to retain.
Versions:
installCharandRf_installTrCharsolidified in their current form, including a remap frominstallChartoRf_installTrChar, in version 4.0.0. Prior to version 3.5.0, the functionRf_installCharperformedinstall(CHAR(x))directly, discarding the encoding information. The three namesinstallChar,Rf_installChar,Rf_installTrCharhave been declared as part of the API in version 4.5.0.
PRINTNAMEReturns the name of the symbol as a CHARSXP value.
#include <Rinternals.h> SEXP Rf_mkNamed( SEXPTYPE typ, const char ** names ); #ifndef R_NO_REMAP #define mkNamed Rf_mkNamed #endif
The desired type of the vector, must be compatible with allocVector.
An array of strings in the native encoding to take the names of the
vector elements from. Must be terminated by "", an empty string.
Allocates and returns an R vector of type typ with names taken from names. No additional vector element is created for the terminator in names.
#include <Rinternals.h> SEXP Rf_classgets( SEXP vec, SEXP klass ); #ifndef R_NO_REMAP #define classgets Rf_classgets #endif
An R value that can have attributes.
An R value of type NILSXP or STRSXP.
Sets the class attribute of vec to klass, altering
vec by reference. Sets or resets the object bit depending on
whether klass is non-empty.
Raises an error if arguments are of wrong type or when trying to set the
factor class on a non-INTSXP vec.
Next: STRING_ELT, Previous: classgets, Up: Functions [Index]
#include <Rinternals.h> SEXP Rf_allocList(int n); #ifndef R_NO_REMAP #define allocList Rf_allocList #endif SEXP Rf_allocLang(int n); #ifndef R_NO_REMAP #define allocLang Rf_allocLang #endif
The number of elements to allocate.
Rf_allocListReturns the head of the newly-allocated pairlist, a value of type
LISTSXP. The CAR of each pair references the
R_NilValue and the CDR references the next pair in the
list (R_NilValue for the last element).
Rf_allocLangSame as allocList, except the returned value is of type
LANGSXP. The following pairs in the list are still of type
LISTSXP.
#include <Rinternals.h> SEXP STRING_ELT( SEXP x, R_xlen_t i ); void SET_STRING_ELT( SEXP x, R_xlen_t i, SEXP v ); const SEXP * STRING_PTR_RO(SEXP x);
An R vector of type STRSXP.
An zero-based index into x.
An R value of type CHARSXP.
STRING_ELTReturns the CHARSXP element of the string vector x at index
i. Raises an error if x not of type STRSXP.
If i is out of range 0:(XLENGTH(x) - 1), behaviour is
undefined.
SET_STRING_ELTSets the CHARSXP element given in v at the index i
inside the STRSXP vector x. Raises an error if any of the
types don’t match or if i is out of range.
For a non-ALTREP x, such an assignment will not perform garbage
collection, so use of idioms such as SET_STRING_ELT(x,
i, mkChar("foo")) on a freshly allocated x is safe.
STRING_PTR_ROReturns a pointer to the beginning of a buffer of
SEXP[XLENGTH(x)], which correspond to the CHARSXP
objects comprising x. Modification of x through this pointer
is prohibited. If the length of x is zero, behaviour is undefined.
Versions: This function appeared in version 3.5.0.
Next: R_mkClosure, Previous: STRING_ELT, Up: Functions [Index]
#include <Rinternals.h> SEXP Rf_mkChar(const char * name); #ifndef R_NO_REMAP #define mkChar Rf_mkChar #endif SEXP Rf_mkCharLen( const char * name, int len ); #ifndef R_NO_REMAP #define mkCharLen Rf_mkCharLen #endif SEXP Rf_mkCharCE( const char * name, cetype_t enc ); #ifndef R_NO_REMAP #define mkCharCE Rf_mkCharCE #endif SEXP Rf_mkCharLenCE( const char * name, int len, cetype_t enc ); #ifndef R_NO_REMAP #define mkCharLenCE Rf_mkCharLenCE #endif #define CHAR(x) R_CHAR(x) const char * R_CHAR(SEXP x); cetype_t Rf_getCharCE(SEXP x); #ifndef R_NO_REMAP #define getCharCE Rf_getCharCE #endif
The contents of the string to be created.
The length of the string starting at name in bytes.
The encoding of the string (see cetype_t). Must be one of
CE_NATIVE, CE_UTF8, CE_LATIN1, CE_BYTES.
An R value of type CHARSXP.
Rf_mkCharRf_mkCharLenRf_mkCharCEVersions: Appeared in 2.7.0
Rf_mkCharLenCEReturns an R value of type CHARSXP referencing the specified
string with relevant encoding bits set. May return a new value, or one
that already exists in the string cache.
Like other values in R, CHARSXPs are subject to garbage
collection. They are usually protected indirectly by being assigned into
STRSXP values using SET_STRING_ELT.
R_CHARReturns the pointer to the 0-terminated C string represented by x. The data is stored in the declared encoding of the string, so this should only be used for strings known to be stored in ASCII.
Rf_getCharCEReturns the encoding of the string.
Versions: Appeared in 2.7.0
See translateChar for guaranteed access to the string data in a predictable encoding.
#include <Rinternals.h> SEXP R_mkClosure( SEXP formals, SEXP body, SEXP rho ); SEXP R_ClosureFormals(SEXP closure); SEXP R_ClosureBody(SEXP closure); SEXP R_ClosureEnv(SEXP closure); SEXP R_ClosureExpr(SEXP closure); SEXP R_BytecodeExpr(SEXP bytecode);
A named pairlist defining the formal arguments of the closure. The names
(TAGs) must be of type SYMSXP, and the values must be
unevaluated expressions (of any type suitable for evaluation, which
includes plain values) setting their default values, or
R_MissingArg if there is none. A TAG of
R_DotsSymbol (...) has the usual meaning of ellipsis in R.
The body of the function. Typically, a LANGSXP list expressing a
function call, which can be to the { operator for a series of expressions. Types CLOSXP,
BUILTINSXP, SPECIALSXP, DOTSXP, ANYSXP are
explicitly disallowed.
The evironment that will be the base of the call frame when the function
is called; must be of type ENVSXP.
A CLOSXP object.
A BCODESXP object of a previously exctacted body of a closure.
R_mkClosureConstructs and returns a closure, an R object of type CLOSXP.
Versions: This function appeared in version 4.5.0.
R_ClosureFormalsReturns the LISTSXP defining the formal arguments of a given
closure.
Versions: This function appeared in version 4.5.0.
R_ClosureBodyReturns the body of the given closure. For a compiled
closure, this will be a BCODESXP value.
Versions: This function appeared in version 4.5.0.
R_ClosureEnvReturns the ENVSXP of the environment of a given closure.
Versions: This function appeared in version 4.5.0.
R_ClosureExprReturns the body of the given closure. If it had been compiled,
the return value is the original, non-compiled expression, or a
NILSXP if the bytecode object does not reference any constants.
R_BytecodeExprReturns the original, non-compiled expression from a BCODESXP, or
a NILSXP if it does not reference any constants.
Versions: This function appeared in version 3.4.0.
Next: R_getVar, Previous: R_mkClosure, Up: Functions [Index]
#include <Rinternals.h> void Rf_defineVar( SEXP symbol, SEXP value, SEXP rho ); #ifndef R_NO_REMAP #define defineVar Rf_defineVar #endif void Rf_setVar( SEXP symbol, SEXP value, SEXP rho ); #ifndef R_NO_REMAP #define setVar Rf_setVar #endif
The name of the variable to bind, a SYMSXP.
An arbitrary R value to bind to the variable.
The environment in which to perform the assignment (defineVar) or
to start the search for a defined symbol to overwrite
(setVar). Must be an ENVSXP.
Rf_defineVarBinds the value to the given symbol in the environment rho without making a copy of it.
Rf_setVarSearches rho and its enclosing envrionments for an already defined
symbol and binds value to it without making a copy. If none
of the environments have symbol set, binds it in
R_GlobalEnv.
Versions: These functions appeared in version 4.5.0.
#include <Rinternals.h> SEXP R_getVar( SEXP sym, SEXP rho, Rboolean inherits ); SEXP R_getVarEx( SEXP sym, SEXP rho, Rboolean inherits, SEXP ifnotfound );
The name of the variable, must be a SYMSXP.
The environment to search the variable in, must be an ENVSXP.
Whether to keep looking for the variable in the enclosing environments.
What to return instead of the variable that has not been found.
R_getVarReturns the value of the requested variable, or raises an error if it was not found.
R_getVarExReturns the value of the requested variable, or ifnotfound if there was no such variable.
#include <Rinternals.h> SEXP R_NewEnv( SEXP enclos, int hash, int size );
The enclosing environment. Must be an ENVSXP.
If nonzero, the environment will use a hash table to look up the variables.
The initial size of the hash; ignored if hash == 0. Will
use a safe default if size <= 0.
Returns the new environment created with the specified settings, like
new.env() in R.
Versions: This function appeared in version 4.1.0.
Next: ScalarReal, Previous: R_NewEnv, Up: Functions [Index]
#include <Rinternals.h> int Rf_asInteger(SEXP x); #ifndef R_NO_REMAP #define asInteger Rf_asInteger #endif int Rf_asLogical(SEXP x); #ifndef R_NO_REMAP #define asLogical Rf_asLogical #endif double Rf_asReal(SEXP x); #ifndef R_NO_REMAP #define asReal Rf_asReal #endif Rcomplex Rf_asComplex(SEXP x); #ifndef R_NO_REMAP #define asComplex Rf_asComplex #endif SEXP Rf_asChar(SEXP x); #ifndef R_NO_REMAP #define asChar Rf_asChar #endif SEXP Rf_asCharacterFactor(SEXP x); #ifndef R_NO_REMAP #define asCharacterFactor Rf_asCharacterFactor #endif
An R value that could be converted to the desired type:
Rf_asIntegerRAWSXP, LGLSXP, INTSXP,
REALSXP (may warn), CPLXSXP (may warn),
STRSXP (may warn), CHARSXP (may warn)
Rf_asLogicalLGLSXP, INTSXP, REALSXP, CPLXSXP,
STRSXP, RAWSXP, CHARSXP
Rf_asRealLGLSXP, INTSXP, REALSXP, CPLXSXP (may warn),
STRSXP (may warn) CHARSXP (may warn)
Rf_asComplexLGLSXP, INTSXP, REALSXP, CPLXSXP,
STRSXP (may warn), CHARSXP (may warn)
Rf_asCharLGLSXP, INTSXP, REALSXP, CPLXSXP,
STRSXP, CHARSXP, SYMSXP
Rf_asCharacterFactorA valid factor.
Rf_asIntegerRf_asLogicalRf_asRealRf_asComplexReturns the result of the conversion as the corresponding primitive C
type. If x is a vector, the first element is used. Zero-length
vectors are converted into a corresponding NA value. If the
conversion is lossy, a warning is raised; if the type of x is
unsupported, an error is raised.
Rf_asCharReturns a string representation of x as a CHARSXP value. If
x is a vector, the first element is used. If the type is
unsupported or x is zero-length, returns NA_STRING.
Rf_asCharacterFactorReturns a STRSXP vector of the same length as x, same as
as.character(x) in R.
Support for RAWSXP in Rf_asInteger() appeared in 4.5.0.
Support for STRSXP and CHARSXP appeared in 2.6.0 for
Rf_asInteger(), Rf_asReal(), Rf_asComplex().
Support for CHARSXP in Rf_asChar() appeared in 2.6.0.
Rf_asCharacterFactor appeared in 2.9.0.
#include <Rinternals.h> SEXP Rf_ScalarReal(double x); #ifndef R_NO_REMAP #define ScalarReal Rf_ScalarReal #endif SEXP Rf_ScalarInteger(int x); #ifndef R_NO_REMAP #define ScalarInteger Rf_ScalarInteger #endif SEXP Rf_ScalarLogical(int x); #ifndef R_NO_REMAP #define ScalarLogical Rf_ScalarLogical #endif SEXP Rf_ScalarComplex(Rcomplex x); #ifndef R_NO_REMAP #define ScalarComplex Rf_ScalarComplex #endif SEXP Rf_ScalarRaw(Rbyte x); #ifndef R_NO_REMAP #define ScalarRaw Rf_ScalarRaw #endif SEXP Rf_ScalarString(SEXP x); #ifndef R_NO_REMAP #define ScalarString Rf_ScalarString #endif
A scalar value of the appropriate type (CHARSXP for
ScalarString).
Allocates and returns a one-element vector of the corresponding
SEXPTYPE (STRSXP for ScalarString).
Versions: From version 2.4.0
Rf_ScalarLogicalcoerces all non-zero, non-NA values toTRUE.
Next: CONS, Previous: ScalarReal, Up: Functions [Index]
#include <Rinternals.h> SEXP Rf_mkString(const char * s); #ifndef R_NO_REMAP #define mkString Rf_mkString #endif
A 0-terminated C string in the native encoding.
Allocates and returns a one-element STRSXP vector containing the
string s.
#include <Rinternals.h> SEXP Rf_cons(SEXP car, SEXP cdr); #ifndef R_NO_REMAP #define cons Rf_cons #endif #define CONS(car, cdr) Rf_cons(car, cdr) SEXP Rf_list1(SEXP s); #ifndef R_NO_REMAP #define list1 Rf_list1 #endif SEXP Rf_list2( SEXP s, SEXP t ); #ifndef R_NO_REMAP #define list2 Rf_list2 #endif SEXP Rf_list3( SEXP s, SEXP t, SEXP u ); #ifndef R_NO_REMAP #define list3 Rf_list3 #endif SEXP Rf_list4( SEXP s, SEXP t, SEXP u, SEXP v ); #ifndef R_NO_REMAP #define list4 Rf_list4 #endif SEXP Rf_list5( SEXP s, SEXP t, SEXP u, SEXP v, SEXP w ); #ifndef R_NO_REMAP #define list5 Rf_list5 #endif SEXP Rf_list6( SEXP s, SEXP t, SEXP u, SEXP v, SEXP w, SEXP x ); #ifndef R_NO_REMAP #define list6 Rf_list6 #endif
The two values to be referenced by the returned pair.
The elements to be included in the returned pairlist, in order.
Rf_consReturns a pair of type LISTSXP, the basis of Lisp-style
pairlists. The resulting value has CAR(value) ==
car, CDR(value) == cdr, and
TAG(value) == R_NilValue.
Rf_list1Rf_list2Rf_list3Rf_list4Rf_list5Rf_list6Construct a short Lisp-style pairlist and return its head pair. The
resulting value has CAR(value) == s, and
CDR(value) points to the next pair, or R_NilValue if
there are no more elements in the list.
Versions: The function
Rf_list6appeared in version 3.4.0.
Versions: Prior to version 4.4.0,
CONSdid not work withR_NO_REMAPset because it expanded toconsinstead ofRf_cons.
#include <Rinternals.h> SEXP Rf_lcons(SEXP car, SEXP cdr); #ifndef R_NO_REMAP #define lcons Rf_lcons #endif #define LCONS(car, cdr) Rf_lcons(car, cdr) SEXP Rf_lang1(SEXP s); #ifndef R_NO_REMAP #define lang1 Rf_lang1 #endif SEXP Rf_lang2( SEXP s, SEXP t ); #ifndef R_NO_REMAP #define lang2 Rf_lang2 #endif SEXP Rf_lang3( SEXP s, SEXP t, SEXP u ); #ifndef R_NO_REMAP #define lang3 Rf_lang3 #endif SEXP Rf_lang4( SEXP s, SEXP t, SEXP u, SEXP v ); #ifndef R_NO_REMAP #define lang4 Rf_lang4 #endif SEXP Rf_lang5( SEXP s, SEXP t, SEXP u, SEXP v, SEXP w ); #ifndef R_NO_REMAP #define lang5 Rf_lang5 #endif SEXP Rf_lang6( SEXP s, SEXP t, SEXP u, SEXP v, SEXP w, SEXP x ); #ifndef R_NO_REMAP #define lang6 Rf_lang6 #endif
The two values to be referenced by the returned LANGSXP pair.
The elements to be included in the returned language pairlist, in order.
Rf_lconsReturns a language pair object of type LANGSXP. The resulting
value has CAR(value) == car,
CDR(value) == cdr, and TAG(value) ==
R_NilValue.
Rf_lang1Rf_lang2Rf_lang3Rf_lang4Rf_lang5Rf_lang6Construct a short language pairlist and return its head pair. The
resulting value has CAR(value) == s, and
CDR(value) points to the next pair, or R_NilValue if
there are no more elements in the list. Only the head of the list is of
type LANGSXP; the rest of the list consists of pairs of type
LISTSXP.
Versions: Prior to version 4.4.0,
LCONSdid not work withR_NO_REMAPset because it expanded tolconsinstead ofRf_lcons. Version 2.12.0 introducedRf_lang5andRf_lang6.
#include <Rinternals.h> SEXP Rf_elt(SEXP list, int i); #ifndef R_NO_REMAP #define elt Rf_elt #endif
A pairlist object: LISTSXP, LANGSXP, or NILSXP.
A zero-based index into list.
Returns the ith element of the list, that is,
CAR(CDR(...(CDR(list)))), where the CDR(...) is
repeated i times.
If i is outside the range of valid indices, returns
R_NilValue.
#include <Rinternals.h> SEXP Rf_lastElt(SEXP list); #ifndef R_NO_REMAP #define lastElt Rf_lastElt #endif
A pairlist object: LISTSXP, LANGSXP, or NILSXP.
Returns the last element of the list, that is, CAR(tail)
for such tail = CDR(...(CDR(list))) that
CDR(tail) == R_NilValue.
If the list was empty (NILSXP) in the first place, returns
R_NilValue.
#include <Rinternals.h> SEXP Rf_nthcdr(SEXP s, int n); #ifndef R_NO_REMAP #define nthcdr Rf_nthcdr #endif
An R value for which CDR is applicable: LISTSXP,
LANGSXP, DOTSXP, NILSXP.
A zero-based index into s.
If s is long enough, returns CDR(...(CDR(s))) where
CDR(...) is repeated n times. Raises an error if the list
is too short, that is, an R_NilValue is encountered before an
intended CDR(...) call.
Next: R_ParentEnv, Previous: nthcdr, Up: Functions [Index]
#include <Rinternals.h> SEXPTYPE Rf_str2type(const char * name); #ifndef R_NO_REMAP #define str2type Rf_str2type #endif SEXP Rf_type2str(SEXPTYPE type); #ifndef R_NO_REMAP #define type2str Rf_type2str #endif SEXP Rf_type2str_nowarn(SEXPTYPE type); #ifndef R_NO_REMAP #define type2str_nowarn Rf_type2str_nowarn #endif const char * Rf_type2char(SEXPTYPE type); #ifndef R_NO_REMAP #define type2char Rf_type2char #endif
One of the type names as a 0-terminated C string. See SEXPTYPE.
A type code for an R value.
Rf_str2typeReturns the SEXPTYPE that corresponds to the given type name, or
(SEXPTYPE)-1 if the type name is invalid.
Versions: This function appeared in version 2.5.0.
Rf_type2str_nowarnReturns the type name of the given SEXPTYPE as a CHARSXP.
If type is not a valid type code, behaviour is undefined, but the
function intends to return R_NilValue.
Versions: This function appeared in version 3.2.0.
Rf_type2strReturns the type name of the given SEXPTYPE as a CHARSXP.
If type is not a valid type code, behaviour is undefined, but the
function intends to raise an R warning and return unknown type
#type as a CHARSXP.
Versions: This function appeared in version 2.5.0.
Rf_type2charLike type2str, including the undefined behaviour, but returns a C
string instead of a CHARSXP.
Versions: This function appeared in version 2.5.0.
#include <Rinternals.h> SEXP R_ParentEnv(SEXP env);
An R environment (of type ENVSXP).
Returns the enclosing environment of env, which will usually be of
type ENVSXP, except for the special environment R_EmptyEnv,
which terminates the environment chain; its enclosing environment is
R_NilValue.
Versions: This function appeared in version 4.5.0.
Next: topenv, Previous: R_ParentEnv, Up: Functions [Index]
#include <Rinternals.h> Rboolean Rf_inherits( SEXP s, const char * name ); #ifndef R_NO_REMAP #define inherits Rf_inherits #endif
An arbitrary R value.
An R class name as a zero-terminated C string in the native encoding.
Returns TRUE if s has the object bit set and its
class attribute vector contains a string equal to name;
otherwise returns FALSE.
Next: GetOption1, Previous: inherits, Up: Functions [Index]
#include <Rinternals.h> SEXP Rf_topenv( SEXP target, SEXP envir ); #ifndef R_NO_REMAP #define topenv Rf_topenv #endif
The environment to look for in the environment chain starting from envir.
The starting environment to look from.
Returns the “top level” environment of envir, that is, the first environment in the chain formed by the enclosing environments that satisfies any of the criteria:
R_GlobalEnv, the global environment
R_BaseEnv, the base environment
R_BaseNamespace
.packageName (and thus is a namespace environment)
If no environments in the chain satisfy the condition, returns
R_GlobalEnv.
Versions: This function was declared in Rinternals.h in version 3.5.0.
#include <Rinternals.h> SEXP Rf_GetOption1(SEXP tag); #ifndef R_NO_REMAP #define GetOption1 Rf_GetOption1 #endif int Rf_GetOptionWidth(void); #ifndef R_NO_REMAP #define GetOptionWidth Rf_GetOptionWidth #endif
The name of the option to look up, as a SYMSXP value.
Rf_GetOption1Returns the value of the option, or R_NilValue if it was not found.
Rf_GetOptionWidthReturns the value of the width option as a C integer. If it
somehow became invalid (not an integer, or outside the safe range),
returns 80, with a warning.
Next: ANY_ATTRIB, Previous: GetOption1, Up: Functions [Index]
#include <Rinternals.h> SEXP Rf_duplicate(SEXP s); #ifndef R_NO_REMAP #define duplicate Rf_duplicate #endif SEXP Rf_shallow_duplicate(SEXP s); #ifndef R_NO_REMAP #define shallow_duplicate Rf_shallow_duplicate #endif void DUPLICATE_ATTRIB(SEXP to, SEXP from); void SHALLOW_DUPLICATE_ATTRIB( SEXP to, SEXP from );
An arbitrary R value to duplicate.
The R value to set attibutes onto.
The R value to take attributes from.
Rf_duplicateReturns a by-value copy of s. For reference-semantics objects
(NILSXP, SYMSXP, ENVSXP, SPECIALSXP,
BUILTINSXP, EXTPTRSXP, BCODESXP,
WEAKREFSXP, CHARSXP, PROMSXP), where the reference
is the value, returns s itself. Duplicating a CLOSXP
results in a new object that references the same formals, body, and
enclosing environment. For the remaining value types (LISTSXP,
LANGSXP, DOTSXP, EXPRSXP, VECSXP,
LGLSXP, INTSXP, REALSXP, CPLXSXP,
RAWSXP, STRSXP), the result is a new object with the same
contents as s that can be changed without affecting s.
Rf_shallow_duplicateSame as duplicate, but list elements (such as CAR(...) for
pairlists and VECTOR_ELT(...) for generic vectors) do not get
duplicated and are instead shared.
Versions: This function appeared in version 3.1.0.
DUPLICATE_ATTRIBTakes all attributes from from, duplicates them using
duplicate(...) and sets them on to, modifying it by
reference.
Versions: Before version 3.3.0, this function behaved like
SHALLOW_DUPLICATE_ATTRIB.
SHALLOW_DUPLICATE_ATTRIBTakes all attributes from from, duplicates them using
shallow_duplicate(...) and sets them on to, modifying it by
reference.
Versions: This function appeared in version 3.3.0.
Next: MARK_NOT_MUTABLE, Previous: duplicate, Up: Functions [Index]
#include <Rinternals.h> int ANY_ATTRIB(SEXP x); void CLEAR_ATTRIB(SEXP x);
Any R value that can have attributes (see setAttrib).
ANY_ATTRIBReturns a non-zero value if x has any attributes; returns 0
if x has no attributes.
CLEAR_ATTRIBRemoves all attributes of x and clears its object bits, both regular and S4, altering it by reference.
Versions: These functions appeared in version 4.5.0.
Next: SETCADDDR, Previous: ANY_ATTRIB, Up: Functions [Index]
#include <Rinternals.h> int NO_REFERENCES(SEXP x); #define MAYBE_REFERENCED(x) (! NO_REFERENCES(x)) int MAYBE_SHARED(SEXP x); #define NOT_SHARED(x) (! MAYBE_SHARED(x)) void MARK_NOT_MUTABLE(SEXP x);
An arbitrary R value.
NO_REFERENCESMAYBE_REFERENCEDIf x has a reference count of 0, NO_REFERENCES(x) is
nonzero, and MAYBE_REFERENCED(x) is 0. It is safe to
modify x in this case.
Versions: These names appeared in version 3.1.0.
MAYBE_SHAREDNOT_SHAREDIf x has a reference count above 1, MAYBE_SHARED(x)
is nonzero, and NOT_SHARED(x) is 0. In this case,
x should not be modified in place and must be duplicated
(see duplicate) before performing any changes.
Versions:
MAYBE_SHAREDappeared in version 3.1.0.NOT_SHAREDappeared in version 3.2.0.
Note: Except in very special and well understood circumstances, an argument passed down to C code should not be modified if it has a positive reference count, even if that count is equal to one.
MARK_NOT_MUTABLESets the reference count of x to the maximum possible value, thus
ensuring that it will stay marked as shared. Any code wanting to modify
x will see it MAYBE_REFERENCED and have to duplicate it.
This is useful when keeping a pointer (see R_PreserveObject) to an object that is also accessible to other R code. Without an explicitly set reference count, mutators may modify the object in place.
Versions: This name appeared in version 3.1.0.
Versions: R switched from the previous mechanism of
NAMEDto reference counting in version 4.0.0. In previous versions of R, these names may be implemented as macros, directly accessingNAMED(x).
Next: TYPEOF, Previous: MARK_NOT_MUTABLE, Up: Functions [Index]
#include <Rinternals.h> SEXP CAR(SEXP e); SEXP CDR(SEXP e); SEXP TAG(SEXP e); SEXP SETCAR(SEXP e, SEXP y); SEXP SETCDR(SEXP e, SEXP y); void SET_TAG(SEXP e, SEXP t); SEXP CADR(SEXP e); SEXP CADDR(SEXP e); SEXP CADDDR(SEXP e); SEXP CAD4R(SEXP e); SEXP CAD5R(SEXP e); SEXP CAAR(SEXP e); SEXP CDAR(SEXP e); SEXP CDDR(SEXP e); SEXP CDDDR(SEXP e); SEXP SETCADR(SEXP e, SEXP y); SEXP SETCADDR(SEXP e, SEXP y); SEXP SETCADDDR(SEXP e, SEXP y); SEXP SETCAD4R(SEXP e, SEXP y);
A pairlist R value: LISTSXP or LANGSXP, or DOTSXP.
For read-only access (i.e. not SET), NILSXP is also
accepted.
An arbitrary R value.
The desired tag of the pairlist element, typically a SYMSXP or
NILSXP value.
CARSETCARReturns (CAR) or sets and returns the new value (SETCAR)
of the CAR field of the pair e. It is the same field that
corresponds to the first argument of constructors CONS and
LCONS.
CDRSETCDRReturns (CDR) or sets and returns the new value (SETCDR)
of the CDR field of the pair e. It is the same field that
corresponds to the second argument of constructors CONS and
LCONS.
TAGSET_TAGReturns (TAG) or sets (SET_TAG) the TAG field of
the pair e. The field is typically used to denote the name of the
list element; in calls (LANGSXP pairlists), it denotes the name
of the argument passed to the function.
CADRReturns CAR(CDR(e)).
CADDRReturns CAR(CDR(CDR(e))).
CADDDRReturns CAR(CDR(CDR(CDR(e)))).
CAD4RReturns CAR(CDR(CDR(CDR(CDR(e))))).
CAD5RReturns CAR(CDR(CDR(CDR(CDR(CDR(e)))))).
Versions: Appeared in 4.3.0.
CAARReturns CAR(CAR(e)).
CDARReturns CDR(CAR(e)).
CDDRReturns CDR(CDR(e)).
CDDDRReturns CDR(CDR(CDR(e))).
Versions: Appeared in 3.2.0.
SETCADRShortcut for SETCAR(CDR(e), y).
SETCADDRShortcut for SETCAR(CDR(CDR(e)), y).
SETCADDDRShortcut for SETCAR(CDR(CDR(CDR(e))), y).
SETCAD4RShortcut for SETCAR(CDR(CDR(CDR(CDR(e)))), y).
#include <Rinternals.h> int TYPEOF(SEXP x);
An arbitrary R value.
Returns the type code of x, see SEXPTYPE.
#include <R_ext/Arith.h> int R_isnancpp(double x); #define ISNAN(x) /*...*/ int R_IsNaN(double x); int R_IsNA(double x); #define ISNA(x) R_IsNA(x) int R_finite(double x); #define R_FINITE(x) /*...*/
A C value of type double.
ISNANR_isnancppReturns a nonzero value if x is one of the not-a-number floating
point values, which includes the NA value for doubles.
R_isnancpp has been implemented to work around some problems with
the standard C++ headers and isnan as a macro.
R_IsNaNReturns a nonzero value if x is a not-a-number floating point
value and not the special NA value.
R_IsNAISNAReturns a nonzero value if x is the double NA value.
R_finiteR_FINITEReturns a nonzero value if x represents a real number: is neither +/-infinity, nor a not-a-number value.
R uses a special NaN payload to mark values as missing. Some modern
processor architectures do not guarantee that the NaN payload will
propagate across arithmetic operations, so an operation on an NA
value that ought to result in a missing value may instead result in an
ordinary NaN.
#include <Rinternals.h> SEXP Rf_eval(SEXP e, SEXP, rho); #ifndef R_NO_REMAP #define eval Rf_eval #endif
An R value to evaluate. Value types (NILSXP, LISTSXP,
LGLSXP, INTSXP, REALSXP, STRSXP,
CPLXSXP, RAWSXP, OBJSXP, SPECIALSXP,
BUILTINSXP, ENVSXP, CLOSXP, VECSXP,
EXTPTRSXP, WEAKREFSXP, EXPRSXP) are accepted and
returned as is. Executable types (BCODESXP, SYMSXP,
PROMSXP; most typically LANGSXP) will be evaluated.
The environment in which to evaluate e. Must be an ENVSXP.
Evaluates e in the environment rho, which may cause arbitrary side effects, and returns its result (unless an error results in a long jump away from the call frame). May also raise an error if e is of an invalid type.
Next: R_ParseVector, Previous: eval, Up: Functions [Index]
#include <Rinternals.h> SEXP Rf_findFun( SEXP symbol, SEXP rho ); #ifndef R_NO_REMAP #define findFun Rf_findFun #endif
The name of the function to find, must be a SYMSXP.
The environment in which to look up the function, must be an
ENVSXP.
Looks up a function (of type CLOSXP, BUILTINSXP,
SPECIALSXP) in rho and its enclosing environments and
returns it. Raises an error if no such function could be found.
Next: R_GetCurrentSrcref, Previous: findFun, Up: Functions [Index]
#include <R_ext/Parse.h> SEXP R_ParseVector( SEXP text, int n, ParseStatus * status, SEXP srcfile ); #include <Rinternals.h> SEXP R_ParseString(const char * str); SEXP R_ParseEvalString( const char * str, SEXP env );
An STRSXP value containing the source code to parse.
The maximal number of expressions to parse. A negative number means no limit.
Pointer to a variable detailing the result of the operation.
Either a length-one STRSXP value to be used as the filename in
error messages, a value of class srcfile, or R_NilValue.
Versions: Added in 2.5.0.
A 0-terminated C string in the native encoding containing the R source code to parse. Must represent a single R expression.
The environment in which to evaluate the expression, must be an
ENVSXP.
R_ParseVectorParses text and returns an EXPRSXP vector of length no
longer than n (if n >= 0). The status may be
set to one of the following enumeration constants:
PARSE_OKParse succeeded.
PARSE_INCOMPLETEFound an incomplete expression.
PARSE_ERRORFound a syntax error.
If *status is not PARSE_OK, the parse failed and the
return value is R_NilValue.
R_ParseStringReturns the single expression represented by str in its parsed
form, which may be a plain R value, a SYMSXP variable name, or a
LANGSXP call object. Raises an error if the parse fails, or if
the number of R expressions in str is not 1.
R_ParseEvalStringReturns the result of evaluating the single expression from str in the environment env. May result in arbitrary side effects.
Next: R_MakeExternalPtr, Previous: R_ParseVector, Up: Functions [Index]
#include <Rinternals.h> SEXP R_GetCurrentSrcref(int skip); SEXP R_GetSrcFilename(SEXP srcref);
The number of source references to skip when walking the list of
contexts. If skip > 0, skips the source references from the
top of the context stack. If skip < 0, counts
abs(skip) source references from the bottom of the context
stack. For example, skip = -1 will give the deepest source
reference in the context stack.
An object of class srcref, or a NILSXP.
R_GetCurrentSrcrefReturns an object of class srcref corresponding to the given
position in the context stack, or R_NilValue if there were too
few source references.
R_GetSrcFilenameReturns a length-1 STRSXP containing the file name corresponding
to the source reference in srcref, or an "" if no such name
could be found.
Versions: These functions appeared in 2.15.1.
Next: R_RegisterFinalizer, Previous: R_GetCurrentSrcref, Up: Functions [Index]
#include <Rinternals.h> SEXP R_MakeExternalPtr( void * p, SEXP tag, SEXP prot ); SEXP R_MakeExternalPtrFn( DL_FUNC p, SEXP tag, SEXP prot ); void * R_ExternalPtrAddr(SEXP s); DL_FUNC R_ExternalPtrAddrFn(SEXP s); SEXP R_ExternalPtrTag(SEXP s); SEXP R_ExternalPtrProtected(SEXP s); void R_SetExternalPtrAddr( SEXP s, void * p ); void R_SetExternalPtrTag(SEXP s, SEXP tag); void R_SetExternalPtrProtected( SEXP s, SEXP prot ); void R_ClearExternalPtr(SEXP s);
An arbitrary C object pointer or a C function pointer cast to
DL_FUNC.
An arbitrary R object. By convention, can be used to identify the type
of the pointer: allocate a unique and persistent R value and then verify
R_ExternalPtrTag(s) == my_type_tag.
An arbitrary R object. By convention, can be used to keep an R object referenced if p is allocated through prot from the R heap.
An EXTPTRSXP object.
R_MakeExternalPtrR_MakeExternalPtrFnAllocate and return a new object of type EXTPTRSXP that contains
the pointer p and references the R values tag and
prot.
Versions:
R_MakeExternalPtrFnappeared in 3.4.0.
R_ExternalPtrAddrR_ExternalPtrAddrFnReturn the p value stored s. No type checking is performed; care must be taken to use the returned pointer with the correct corresponding object type.
Versions:
R_ExternalPtrAddrFnappeared in 3.4.0.
R_ExternalPtrTagReturn the tag value referenced by s.
R_ExternalPtrProtectedReturn the prot value referenced by s.
R_SetExternalPtrTagReplace the tag value referenced by s.
R_SetExternalPtrProtectedReplace the prot value referenced by s.
R_SetExternalPtrAddrReplace the stored pointer with the provided value p.
R_ClearExternalPtrSet the stored pointer to the null pointer.
In order to prevent resource leaks by ensuring that the destructors are
called, register a finalizer on the EXTPTRSXP value using
R_RegisterFinalizer.
Next: R_MakeWeakRef, Previous: R_MakeExternalPtr, Up: Functions [Index]
#include <Rinternals.h> void R_RegisterCFinalizer( SEXP s, R_CFinalizer_t cfun ); void R_RegisterCFinalizerEx( SEXP s, R_CFinalizer_t cfun, Rboolean onexit ); void R_RegisterFinalizer( SEXP s, SEXP fun ); void R_RegisterFinalizerEx( SEXP s, SEXP fun, Rboolean onexit );
A reference-semantics R value: ENVSXP or EXTPTRSXP.
A C function pointer of type void (*R_CFinalizer_t)(SEXP s)
which takes the original object s as an argument and performs the
necessary actions to release the associated external resources.
An R value of type CLOSXP, BUILTINSXP, or
SPECIALSXP. Must accept the original object s as the first
argument and perform the necessary actions.
Whether to call the finalizer during normal R shutdown. If FALSE,
the finalizer will only be called when collecting the object in the
middle of an R session. Not explicitly freeing memory on exit can speed
up the shutdown process, but at the cost of producing Valgrind and
LeakSanitizer warnings.
Finalizers for important resources that don’t go away on their own, such
as files, should be always registered with onexit = TRUE.
Next: VECTOR_ELT, Previous: R_RegisterFinalizer, Up: Functions [Index]
#include <Rinternals.h> SEXP R_MakeWeakRef( SEXP key, SEXP value, SEXP fin, Rboolean onexit ); SEXP R_MakeWeakRefC( SEXP key, SEXP value, R_CFinalizer_t cfin, Rboolean onexit ); SEXP R_WeakRefKey(SEXP w); SEXP R_WeakRefValue(SEXP w); void R_RunWeakRefFinalizer(SEXP w);
A reference-semantics R value: ENVSXP or EXTPTRSXP.
An arbitrary R value.
An R value of type CLOSXP, BUILTINSXP, or
SPECIALSXP. Must accept the key object as the first
argument. Can also be R_NilValue when no finalization is needed.
A C function pointer of type void (*R_CFinalizer_t)(SEXP
key) which takes the key object as an argument and performs
the necessary cleaning up.
Whether to call the finalizer during normal R shutdown. If FALSE,
the finalizer will only be called when collecting the object in the
middle of an R session.
A WEAKREFSXP object.
R_MakeWeakRefR_MakeWeakRefCAllocates and returns a new object of type WEAKREFSXP.
R_WeakRefKeyReturns the key of the weak reference, or R_NilValue if it
had been deemed no longer reachable.
R_WeakRefValueReturns the value of the weak reference, or R_NilValue if
the key had been deemed no longer reachable.
R_RunWeakRefFinalizerDestroys the weak reference by cleaning its key and value fields and running the finalizer (if set) with the previous value of the key.
The manner in which weak references propagate reachability is different from other R values:
This makes it possible to automatically manage global lists of reference-semantics objects with associated data.
See also: https://homepage.stat.uiowa.edu/~luke/R/weakfinex.html
Next: REAL, Previous: R_MakeWeakRef, Up: Functions [Index]
#include <Rinternals.h> SEXP VECTOR_ELT(SEXP x, R_xlen_t i); SEXP SET_VECTOR_ELT( SEXP x, R_xlen_t i, SEXP v ); const SEXP * VECTOR_PTR_RO(SEXP x);
An R value of type VECSXP or EXPRSXP.
A zero-based index into x.
An arbitrary R value.
VECTOR_ELTReturns the value at the zero-based position i of the vector
x. Raises an error if x is of the wrong type. If i is
out of range 0:(XLENGTH(x) - 1), behaviour is undefined.
SET_VECTOR_ELTSets the value v at the zero-based position i of the vector x. Raises an error if x of the wrong type or if i is outside the valid range. Returns v.
VECTOR_PTR_ROReturns a pointer to the beginning of a buffer of
SEXP[XLENGTH(x)], which corresponds to the objects
comprising x. Modification of x through this pointer is
prohibited. If the length of x is zero, behaviour is undefined.
Versions: Appeared in 4.5.0.
Next: translateChar, Previous: VECTOR_ELT, Up: Functions [Index]
#include <Rinternals.h> double * REAL(SEXP x); const double * REAL_RO(SEXP x); double REAL_ELT(SEXP x, R_xlen_t i); void SET_REAL_ELT( SEXP x, R_xlen_t i, double v ); int * INTEGER(SEXP x); const int * INTEGER_RO(SEXP x); int INTEGER_ELT(SEXP x, R_xlen_t i); void SET_INTEGER_ELT( SEXP x, R_xlen_t i, int v ); int * LOGICAL(SEXP x); const int * LOGICAL_RO(SEXP x); int LOGICAL_ELT(SEXP x, R_xlen_t i); void SET_LOGICAL_ELT( SEXP x, R_xlen_t i, int v ); Rbyte * RAW(SEXP x); const Rbyte * RAW_RO(SEXP x); Rbyte RAW_ELT(SEXP x, R_xlen_t i); void SET_RAW_ELT( SEXP x, R_xlen_t i, Rbyte v ); Rcomplex * COMPLEX(SEXP x); const Rcomplex * COMPLEX_RO(SEXP x); Rcomplex COMPLEX_ELT(SEXP x, R_xlen_t i); void SET_COMPLEX_ELT( SEXP x, R_xlen_t i, Rcomplex v ); const void * DATAPTR_RO(SEXP x);
An R value of the corresponding type (in order: REALSXP,
INTSXP, LGLSXP, RAWSXP, CPLXSXP).
For DATAPTR_RO, any vector type.
A zero-based index into x.
A C value of the corresponding type.
REALINTEGERLOGICALRAWCOMPLEXReturns a pointer to the start of the buffer that contains
XLENGTH(x) elements of the corresponding type. If x
is an ALTREP object, this will materialize it. Raises an error if
x is not of the corresponding type.
Modifications through the pointer affect x itself: care must be taken if it is shared (see MARK_NOT_MUTABLE). If the length of x is 0, behaviour is undefined.
REAL_ROINTEGER_ROLOGICAL_RORAW_ROCOMPLEX_ROSame as above, but modification of the contents of x is prohibited.
Versions: Appeared in 3.5.0.
REAL_ELTINTEGER_ELTLOGICAL_ELTRAW_ELTCOMPLEX_ELTReturns the element of x at the zero-based position i. May
avoid materialising an ALTREP object at the cost of one function call
per element. If i is out of range 0:(XLENGTH(x)-1),
behaviour is undefined.
Versions: Appeared in 3.5.0.
SET_REAL_ELTSET_INTEGER_ELTSET_LOGICAL_ELTSET_RAW_ELTSET_COMPLEX_ELTSets the element of x at the zero-based position i to
v (see MARK_NOT_MUTABLE for how to determine whether a
potentially shared x is safe to modify). May avoid materialising
an ALTREP object at the cost of one function call per replacement. If
i is out of range 0:(XLENGTH(x)-1), behaviour is
undefined.
Versions: Appeared in 3.5.0.
DATAPTR_ROReturns a pointer to the start of vector data of x.
Versions: Appeared in 3.5.0.
#include <Rinternals.h> const char * Rf_translateChar(SEXP x); #ifndef R_NO_REMAP #define translateChar Rf_translateChar #endif const char * Rf_translateCharUTF8( SEXP x ); #ifndef R_NO_REMAP #define translateCharUTF8 Rf_translateCharUTF8 #endif
A CHARSXP value.
Returns a pointer to the 0-terminated C string represented by x,
guaranteed to be in the native (translateChar) or UTF-8
(translateCharUTF8) encoding. Raises an R error if the encoding
of x is CE_BYTES.
The underlying buffer may be allocated using R_alloc and thus
subject to vmaxset memory management.
Next: nrows, Previous: translateChar, Up: Functions [Index]
#include <Rinternals.h> const char * Rf_reEnc( const char * x, cetype_t ce_in, cetype_t ce_out, int subst ); #ifndef R_NO_REMAP #define reEnc Rf_reEnc #endif
A 0-terminated C string to convert.
The encoding to convert x from, one of CE_NATIVE,
CE_UTF8, CE_LATIN1, CE_BYTES, or CE_SYMBOL.
The desired encoding of the return value, one of CE_NATIVE,
CE_UTF8, CE_LATIN1, CE_BYTES. (Not
CE_SYMBOL.)
How to substitute bytes that failed to translate (due to being invalid
in the ce_in encoding or unrepresentable in the ce_out
encoding): 1 will substitute the hexadecimal codes of the
characters in the form "<%02x>"; 2 will substitute ASCII
dots "."; any other value will omit output for these bytes.
Returns a 0-terminated C string in the encoding specified by ce_out. See R_alloc for how to manage the underlying memory of the buffer.
#include <Rinternals.h> int Rf_nrows(SEXP s); #ifndef R_NO_REMAP #define nrows Rf_nrows #endif int Rf_ncols(SEXP s); #ifndef R_NO_REMAP #define ncols Rf_ncols #endif
A vector or list value that can have the dim attribute.
nrowsLike NROW(s) in R, returns the first element of the
dim attribute if it exists, otherwise returns the length of
s.
ncolsLike NCOL(s) in R, returns the second element of the
dim attribute if it exists, otherwise returns 1.
#include <R_ext/RS.h> #define R_Calloc(n, t) /*...*/ #define R_Realloc(p, n, t) /*...*/ #define R_Free(p) /*...*/ #ifndef STRICT_R_HEADERS #define Calloc(n, t) /*...*/ #define Realloc(p, n, t) /*...*/ #define Free(p) /*...*/ #endif
The number of elements of type t to allocate a buffer for, as an
expression that can be cast to R_SIZE_T.
The type of each element, as a keyword that can be given to the
sizeof(t) operator.
An lvalue containing the pointer previously returned by R_Calloc
or R_Realloc.
R_CallocCallocAllocates a buffer of type t[n], safe from size
multiplication overflow, zero-initialises it, and returns a pointer to
it. If the allocation fails, raises an R error.
R_ReallocReallocIf p is a null pointer, allocates a new buffer of size
n*sizeof(t) with contents undefined and returns a
pointer to it. Otherwise returns a pointer to a buffer of size
n*sizeof(t) partially initialised from the previous
contents of the buffer pointed to by p. This may or may not resize
the buffer in place. After the function returns a new pointer, the
original argument p given to the function is no longer safe to use
and must be discarded.
If the size multiplication overflows, behaviour is undefined.
If any allocation fails, raises an R error, leaving the allocation pointed to by p unchanged.
R_FreeFreeDeallocates a buffer previously allocated by R_Callor or
R_Realloc and sets p to a null pointer.
Since these functions raise R errors on allocation failures, a way to
deallocate the managed resources in the current function must be
arranged separately. Typically, this involves static memory, a separate
destructor function that calls R_Free, and an R-level
on.exit.
Next: GetRNGstate, Previous: R_Calloc, Up: Functions [Index]
#include <R_ext/Error.h> NORET void Rf_error( const char * format, ... ); #ifndef R_NO_REMAP #define error Rf_error #endif void Rf_warning( const char * format, ... ); #ifndef R_NO_REMAP #define warning Rf_warning #endif #include <Rinternals.h> NORET void Rf_errorcall( SEXP call, const char * format, ... ); #ifndef R_NO_REMAP #define errorcall Rf_errorcall #endif void Rf_warningcall( SEXP call, const char * format, ... ); #ifndef R_NO_REMAP #define warningcall Rf_warningcall #endif void Rf_warningcall_immediate( SEXP call, const char * format, ... ); #ifndef R_NO_REMAP #define warningcall_immediate Rf_warningcall_immediate #endif ! Fortran wrappers subroutine rexit(message) subroutine rwarn(message)
A format string suitable for the C function vsnprintf.
Variable arguments to be interpreted by the format string.
An R value of type LANGSXP specifying the call to blame for the
error or the warning being raised, or R_NilValue to avoid
printing the location of the call.
A Fortran string with a length of 255 characters or less.
Rf_errorRf_errorcallFormats the message and raises an R error. This is a nonlocal transfer of control; the function does not return. Any resources without finalizers or error handlers set to release them will be leaked.
Rf_warningRf_warningcallFormats the message and raises an R warning. Depending on the value of
getOption('warn'), may ignore the warning (< 0), remember
the warning and present it after returning from the top-level context
(0); print it immediately (1); or convert it into an error
(>= 2).
Care must be taken to ensure that no resources will leak if a warning results in a nonlocal control transfer away from the current function.
Rf_warningcall_immediateLike warningcall above, but signals the warning immediately if
getOption('warn') <= 0.
rexitThe Fortran wrapper for error("%s", message). Will produce
an additional warning if message is longer than 255 characters.
rwarnThe Fortran wrapper for warning("%s", message). Will
produce an additional warning if message is longer than 255
characters.
Versions:
Rf_errorcallandRf_warningcallfirst declared inRinternals.hin version 2.3.0.
Next: R_sample_kind, Previous: error, Up: Functions [Index]
#include <R_ext/Random.h> void GetRNGstate(void); void PutRNGstate(void); double unif_rand(void); double norm_rand(void); double exp_rand(void); double R_unif_index(double dn);
The upped limit for the index, not inclusive.
GetRNGstateReads the state of the random number generator from the
.Random.seed variable in the global environment, initialising it
if needed. This function must be called once per call to a
package function before sampling numbers from the distributions using
the functions unif_rand, norm_rand, exp_rand,
R_unif_index.
PutRNGstateSaves the internal state of the random number generator into the
.Random.seed variable in the global environment. This function
must be called after sampling numbers from the distributions
before returning from package code back into R.
unif_randReturns a number sampled from the standard uniform distribution. The
value is in (0, 1), that is, not including either 0 or
1.
norm_randReturns a sample from the standard normal distribution, N(0, 1).
exp_randReturns a sample from the standard exponential distribution, with
density p(x) = exp(-x) for x >= 0.
R_unif_indexReturns an integer index uniformly sampled from 0:(dn-1).
If dn <= 0, returns 0.
Versions: Appeared in 3.4.0.
Next: Rprintf, Previous: GetRNGstate, Up: Functions [Index]
#include <R_ext/Random.h>
typedef enum {
ROUNDING,
REJECTION
} Sampletype;
Sampletype R_sample_kind(void);
Returns the current setting used by the R function sample and
other methods of discrete uniform generation. ROUNDING is
non-uniform on large populations, so should only be used to reproduce
previous results.
See also: https://bugs.r-project.org/show_bug.cgi?id=17494
Next: dblepr, Previous: R_sample_kind, Up: Functions [Index]
#include <R_ext/Print.h> void Rprintf(const char * format, ...); void REprintf(const char * format, ...); #if defined(R_USE_C99_IN_CXX) || !defined(__cplusplus) void Rvprintf( const char * format, R_VA_LIST arg ); void REvprintf( const char * format, R_VA_LIST arg ); #endif
A format string suitable for the C function vsnprintf.
The variadic arguments to be interpreted by the format string.
The macro R_VA_LIST expands to either va_list or
std::va_list, depending on whether the header is being included
by a C or a C++ compiler. The headers stdarg.h or cstdarg
are included as necessary. The va_list interface is only
available to the C++ compiler if the preprocessor symbol
R_USE_C99_IN_CXX is defined or the C++ version is 11 or above.
RprintfRvprintfFormats and prints the specified string on R’s standard output stream, which may be a GUI console window.
REprintfREvprintfFormats and prints the specified string on R’s standard error stream, which may be different from the standard output stream.
subroutine dblepr(label, nchar, ddata, ndata) subroutine realpr(label, nchar, rdata, ndata) subroutine intpr (label, nchar, idata, ndata) ! since R-4.0.0: subroutine labelpr(label, nchar) subroutine dblepr1(label, nchar, dvar) subroutine realpr1(label, nchar, rvar) subroutine intpr1 (label, nchar, ivar)
A character label to be used as the first line of output, up to 255 characters in length.
The number of characters from label to print. Can be -1 to
print all of them, or 0 to suppress the first line.
The number of elements to print from ddata, rdata, or idata.
The data to print after the first line. Arrays must be of length ndata or more.
These functions are provided for use from Fortran code.
If nchar != 0, prints the specified number of characters
from label on R’s standard output, followed by a newline. Printing
more than 255 characters will result in an R warning.
If calling dblepr, realpr, or intpr with
ndata > 0, or if calling dblepr1, realpr1, or
intpr1, prints the specified ddata/rdata/idata
or dvar/rvar/ivar on R’s standard output like R’s
default print method does for plain R values.
Versions: Functions
labelpr,dblepr1,realpr1,intpr1appeared in 4.0.0.
#include <Rmath.h> void Rf_rmultinom( int n, double * prob, int K, int * rN ); #ifndef R_NO_REMAP_RMATH #define rmultinom Rf_rmultinom #endif
The total number of objects in the multinomial experiment, must be at
least 0.
Input parameter: an array of length K specifing the probabilities
for the classes. Must sum to 1.
The number of elements in prob and rN, must be at least
1.
Output parameter: an array of length K to be filled with the numbers of objects distributed into the specified classes.
Raises warnings if K < 1 or n < 0. Raises an R
error if the elements of prob do not sum to 1.
Populates the array pointed to by rN with the numbers of objects
distributed into the respective classes during the multinomial
experiment.
Next: R_ShowMessage, Previous: rmultinom, Up: Functions [Index]
#include <Rmath.h> double Rf_dwilcox( double x, double m, double n, int give_log ); #ifndef R_NO_REMAP_RMATH #define dwilcox Rf_dwilcox #endif double Rf_pwilcox( double x, double m, double n, int lower_tail, int give_log ); #ifndef R_NO_REMAP_RMATH #define pwilcox Rf_pwilcox #endif double Rf_qwilcox( double p, double m, double n, int lower_tail, int log_p ); #ifndef R_NO_REMAP_RMATH #define qwilcox Rf_qwilcox #endif double Rf_rwilcox(double m, double n); #ifndef R_NO_REMAP_RMATH #define rwilcox Rf_rwilcox #endif void wilcox_free(void);
The values of the Wilcoxon rank sum statistic (which takes values in
0:(m*n)).
Numbers of observations in the first (m) and second (n) samples.
If nonzero, return natural logarithms of probabilities instead of probabilities themselves.
If nonzero, probabilities are of P[X <= x]. Otherwise,
P[X > x].
If log_p is zero, p is a probability value. For nonzero log_p, p is the natural logarithm of probability instead of just a probability.
Rf_dwilcoxReturns the value of the Wilcoxon rank sum statistic probability density function.
Rf_pwilcoxReturns the value of the distribution function.
Rf_qwilcoxReturns the value of the quantile function.
Rf_rwilcoxReturns one sample from the distribution with the given parameters. See GetRNGstate for the RNG state management requirements.
wilcox_freeReleases the internal cache allocated by the functions above. This function should be called after calling any of the functions above and before returning to R.
Versions: Prior to 4.2.0, this function was missing from the installed headers and needed to be declared manually (see R_Version).
Next: R_CheckUserInterrupt, Previous: dwilcox, Up: Functions [Index]
#include <R_ext/Error.h> void R_ShowMessage(const char * s);
The message, as a 0-terminated C string in the native encoding. May contain newlines.
Brings the message to the user’s attention immediately. Depending on the frontend in use, this may print s on the console or put up a modal GUI message box.
Next: R_CheckStack, Previous: R_ShowMessage, Up: Functions [Index]
#include <R_ext/Utils.h> void R_CheckUserInterrupt(void); subroutine rchkusr()
Checks the stack usage (see R_CheckStack). Checks for a pending
interrupt previously caused by typing Ctrl+C to send the
INT signal (Unix) or pressing the interrupt button
(Rgui.exe on Windows, R.app on macOS). If the interrupt
flag is set, signals the interrupt condition, which will perform a
nonlocal control transfer to the interrupt handler (if set) or to the
top level.
This function must be called from long-running loops in order to keep R
responsive. Note that with main-thread front-ends (such as
Rgui.exe), checking for interrupts involves first processing the
pending GUI events and finding out if the interrupt flag must be set,
which may take a noticeable amount of time if the function is called too
frequently.
Next: Riconv, Previous: R_CheckUserInterrupt, Up: Functions [Index]
#include <R_ext/Utils.h> void R_CheckStack(void); void R_CheckStack2(R_SIZE_T extra);
The desired amount of additional stack memory.
On systems and front-ends where stack checking is supported, checks
whether the current amount of used stack memory plus extra (if
using R_CheckStack2) exceeds the system-specific limit set during
R startup. If yes, signals an error condition and jumps to the top level
without running error handlers.
If not running on the same main thread as R, behaviour is undefined.
These functions must be called at the beginning of recursive functions
(R_CheckStack) or prior to allocating variable amounts of stack
memory using alloca or C99 variable-length arrays
(R_CheckStack2). Without an explicit check, overflowing the stack
will at best crash the process.
Versions:
R_CheckStack2appeared in 3.0.0.
Next: R_ToplevelExec, Previous: R_CheckStack, Up: Functions [Index]
#include <R_ext/Riconv.h> void * Riconv_open( const char * tocode, const char * fromcode ); size_t Riconv( void * cd, const char ** inbuf, size_t * inbytesleft, char ** outbuf, size_t * outbytesleft ); int Riconv_close(void * cd);
The name of the destination (tocode) and source (fromcode)
encodings as 0-terminated C strings. An empty string, "",
indicates the encoding of the current locale, like CE_NATIVE.
A valid iconv context pointer previously returned by
Riconv_open.
The input buffer (*inbuf)[*inbytesleft], containing
the bytes in the encoding specified by fromcode.
The output buffer (*outbuf)[*outbytesleft], intended
to contain the text from inbuf represented in the encoding
tocode.
Riconv_openAllocates and returns an encoding conversion context set up to convert
between the specified encodings. On a failure to allocate or initialise
the context (e.g. due to the conversion from fromcode to
tocode not being supported), returns (void*)-1 and sets
errno. Does not return a null pointer.
RiconvConverts as much data as possible, incrementing *inbuf and
*outbuf to point to the start of the remaining data and
adjusting *inbytesleft and *outbytesleft.
Returns the number of characters converted.
On error, returns (size_t)-1 and sets errno to one of the
constants: E2BIG (not enough space in outbuf),
EILSEQ (could not decode the byte at *inbuf in the
fromcode encoding), or EINVAL (the multi-byte sequence at
*inbuf is incomplete).
Riconv_closeDeallocates the resources previously allocated by Riconv_open.
This function must be called prior to discarding a context pointer in
order to avoid resource leaks.
Next: R_tryCatch, Previous: Riconv, Up: Functions [Index]
#include <Rinternals.h> Rboolean R_ToplevelExec( void (*fun)(void *), void * data ); SEXP R_tryEval( SEXP expr, SEXP env, int * ErrorOccurred ); SEXP R_tryEvalSilent( SEXP expr, SEXP env, int * ErrorOccurred );
The function and the data it needs, to execute
fun(data) in a separate top-level context.
The expression and the environment, to execute eval(expr,
env) in a separate top-level context. See eval.
An output variable indicating whether an R-level error has occurred during the call.
R_ToplevelExecTemporarily sets up a new top-level context and calls
fun(data). Existing condition handlers will not be
available for the duration of the call. Raising an R-level error or
interrupting R will not propagate past the current call.
Returns TRUE if the call completes normally, FALSE if a
jump to the top-level context has been performed.
R_tryEvalLike R_ToplevelExec, but calls eval(expr,
env). If the call completes normally, returns the result of
evaluation and sets *ErrorOccurred to zero. Otherwise
returns a null pointer and sets *ErrorOccurred to a
nonzero value.
Versions: Appeared in 1.4.0.
R_tryEvalSilentLike R_tryEval, but suppresses the printing of error messages for
the duration of the call.
Next: R_UnwindProtect, Previous: R_ToplevelExec, Up: Functions [Index]
#include <Rinternals.h> SEXP R_ExecWithCleanup( SEXP (*body)(void *), void * bdata, void (*cleanfun)(void *), void *cleandata ); SEXP R_tryCatch( SEXP (*body)(void *), void * bdata, SEXP conditions, SEXP (*handler)(SEXP condition, void * data), void * hdata, void (*cleanfun)(void *), void * cleandata ); SEXP R_tryCatchError( SEXP (*body)(void *), void * bdata, SEXP (*handler)(SEXP condition, void * data), void * hdata ); SEXP R_withCallingErrorHandler( SEXP (*body)(void *), void * bdata, SEXP (*handler)(SEXP condition, void * data), void * hdata );
The function and data to be called as body(bdata)
with error handling.
The cleanup function and necessary context to be called as
cleanfun(cleandata) unconditionally after a
successful call or handling the error. May be a null pointer for
R_tryCatch or R_tryCatchError.
A STRSXP vector of condition classes for which the condition
handler will be called.
The condition handler and necessary context to be called as
handler(condition, hdata).
R_ExecWithCleanupCalls and returns the value of body(bdata). If an
R-level error is raised, the function does not return. Sets up an
execution context so that whether the call completes successfully or
fails with an R-level error, cleanfun(cleandata) is
called.
Versions: Appeared in 3.1.0.
R_tryCatchCalls and returns the value of body(bdata). Sets up
error handlers using an R call to tryCatch(...). If a condition
of a class included in conditions is raised, tryCatch
unwinds the stack, executes handler(condition,
hdata) and returns its result.
Versions: Appeared in 3.4.0.
R_tryCatchErrorSame as R_tryCatch(body, bdata,
PROTECT(mkString("error")), handler, hdata, NULL, NULL).
Versions: Appeared in 3.4.0.
R_withCallingErrorHandlerCalls and returns the value of body(bdata). If an
R-level error is signalled, calls handler(condition,
hdata) before unwinding the stack. If handler returns,
normal error processing is resumed.
Versions: Appeared in 4.0.0.
Next: d1mach, Previous: R_tryCatch, Up: Functions [Index]
#include <Rinternals.h> SEXP R_MakeUnwindCont(void); SEXP R_UnwindProtect( SEXP (*fun)(void *), void * data, void (*cleanfun)(void *, Rboolean jump), void * cleandata, SEXP cont ); NORET void R_ContinueUnwind(SEXP cont);
The function to be called as fun(data).
The cleanup function to be called as
cleanfun(cleandata, jump).
The continuation token. Can be either a value previously returned by
R_MakeUnwindCont, or a null pointer.
R_MakeUnwindContAllocates and returns a continuation token. Its SEXPTYPE
is unspecified; the only valid uses are with functions described here.
Like most values in R, it must be protected for the duration of its use.
R_UnwindProtectR_ContinueUnwindCalls and returns the value of fun(data). If the call
succeeds, calls cleanfun(cleandata, FALSE) before
returning. If the call signals an R-level error, calls
cleanfun(cleandata, TRUE) before continuing the stack
unwinding.
If cont is not a null pointer, cleanfun is allowed to
perform nonlocal control transfers of its own, for example, to unwind
the C++ stack. The stack unwinding must stop before reaching the frames
owned by R (for example, by catching the exception), at which point the
code must resume the R-level error processing by calling
R_ContinueUnwind(cont).
Versions: Appeared in 3.5.0.
Next: R_ExpandFileName, Previous: R_UnwindProtect, Up: Functions [Index]
! For compatibility with legacy Fortran code, not declared in a header double precision function d1mach(i) integer function i1mach(i)
The number of the constant to return. Must be in 1:5 for
d1mach, 1:16 for i1mach.
d1machThe smallest positive value representable in a C variable of type
double. In Fortran, best replaced by the tiny() intrinsic.
In C, use the DBL_MIN constant from <limits.h>.
The largest finite value representable in a C variable of type
double. In Fortran, best replaced by the huge() intrinsic.
In C, use the DBL_MAX constant from <limits.h>.
For a base-B floating-point number with T digits,
d1mach(3) is B^(-T) and d1mach(4) is
B^(1-T), giving the bounds on relative spacing.
For IEEE 754 double precision floating-point numbers required by R,
these values are the machine epsilon times 1/2 and 1, respectively. In
Fortran, use the epsilon() intrinsic, and the
rrspacing(x) intrinsic for a more direct route to relative
spacing near a given x. In C, the values can be obtained using the
DBL_EPSILON constant from <limits.h>.
The base-10 logarithm of the base (radix) of the floating point types.
For IEEE 754 binary floating point numbers, this is log10(2). In
Fortran, use the radix() intrinsic. In C, use the
FLT_RADIX constant from <limits.h>.
i1machThe Fortran unit numbers for the standard input and output,
respecitvely. Direct I/O via the standard streams is not supported in R
packages. See dblepr for printing from Fortran code in R extensions,
Rprintf for the C interface. To read from the R console, construct
and evaluate a call to the R functions readline or scan.
In Fortran code running outside of R, best replaced by specifying an
asterisk * instead of the unit number in the read and
write statements, or use iso_fortran_env, only: input_unit,
output_unit.
The Fortran unit number for the card punch. Not guaranteed to work, even if a card punch is actually connected to the computer running R. Redirected to the standard error stream in practice, see below.
The Fortran unit number for the standard error stream. Direct output to the standard streams is not supported in R packages. See REprintf.
The number of bits in a C int value. In Fortran, use the
bit_size intrinsic. In C, use CHAR_BIT * sizeof(int) from
the <limits.h> header.
The number of characters per integer storage unit. In Fortran, either
use storage_size() together with bit_size(), combine
inquire(iolength=sizeof_int) integer_variable with
use iso_fortran_env, only: file_storage_size, or use
iso_c_binding, only: c_sizeof (which could all mean subtly different
things). In C, use sizeof(int).
The base (radix) of the C int type, i.e., 2.
The number of significant base-2 digits (bits) in a C int value.
In Fortran, use the digits() intrinsic. In C, use CHAR_BIT
* sizeof(int) - 1, assuming that one bit is effectively reserved for
the sign.
The largest int value. Best replaced by the huge()
intrinsic in Fortran, INT_MAX from <limits.h> in C.
The base (radix) of the C floating point type double, i.e., 2. In
Fortran, use the radix() intrinsic. In C, use the
FLT_RADIX constant from <limits.h>.
The number of base-2 digits in the significand of single-precision
floating point numbers (IEEE 754 float32). In Fortran, use the
digits() intrinsic. In C, use the FLT_MANT_DIG constant
from <limits.h>.
The minimum and maximum exponents for single-precision floating point
numbers, respectively. In other words, the smallest and the largest
numbers e such that 2^(e-1) is a normalised
float. In Fortran, use the minexponent() and
maxexponent() intrinsics. In C, use the FLT_MIN_EXP and
FLT_MAX_EXP constants from <limits.h>.
The number of base-2 digits in the significand of double-precision
floating point numbers (IEEE 754 float64). In Fortran, use the
digits() intrinsic. In C, use the DBL_MANT_DIG constant
from <limits.h>.
The minimum and maximum exponents for double-precision floating point
numbers, respectively. In other words, the smallest and the largest
numbers e such that 2^(e-1) is a normalised
double. In Fortran, use the minexponent() and
maxexponent() intrinsics. In C, use the DBL_MIN_EXP and
DBL_MAX_EXP constants from <limits.h>.
See also: http://web.archive.org/web/20230727205025/https://www.netlib.org/slatec/src/d1mach.f, http://web.archive.org/web/20230727212028/https://www.netlib.org/slatec/src/i1mach.f.
#include <R_ext/Utils.h> const char * R_ExpandFileName(const char * fn);
A path to a file.
If fn does not start with a tilde (~), returns fn. If
fn starts with ~name, returns a copy of fn with
the substring replaced by the path to the home directory of user
name. If name is an empty string, uses the home directory of
the current user. If a lookup of the home directory fails, returns
fn. The precise meaning of “home directory” is system-specific.
The return value points to a static buffer that may be overwritten by a
subsequent call to R_ExpandFileName. It must not be deallocated
by a call to free or otherwise.
Next: lbfgsb, Previous: R_ExpandFileName, Up: Functions [Index]
#include <R_ext/Utils.h> char * R_tmpnam2( const char * prefix, const char * tempdir, const char * fileext ); char * R_tmpnam( const char * prefix, const char * tempdir ); void R_free_tmpnam(char * name);
The non-random prefix of the desired name of the file. A null pointer is understood to mean an empty string.
The directory in which a name for the temp file must be created.
The non-random suffix of the desired name of the file. May start with a dot in order to make a file extension. A null pointer means an empty string.
A value previously returned by R_tmpnam or R_tmpnam2.
R_tmpnam2Allocates, constructs and returns a string consisting of tempdir,
followed by the system-specific directory separator, followed by
prefix, the random part of the file name, and the fileext.
The file pointed to by the returned path will not exist at the
time of the call to R_tmpnam2.
Versions: Appeared in 2.14.0.
In order to avoid race conditions, it is recommended to set the flags
that guarantee that the file will be created, or the system call will
fail, e.g. open(name, O_CREAT | O_EXCL, S_IRUSR | S_IWUSR)
or CreateFileA(name, GENERIC_READ | GENERIC_WRITE, 0, NULL,
CREATE_NEW, 0, NULL).
Raises an R error if the resulting string is too long for a file path, an allocation fails, or if, after a fixed number of tries, all paths tried lead to files that already exist. Does not affect the state of R’s random number generator.
R_tmpnamSame as R_tmpnam2(prefix, tempdir, "").
Versions: Appeared in 1.6.0.
R_free_tmpnamDeallocates the buffer holding name. Must be called prior to discarding the pointer to avoid resource leaks.
Versions: Appeared in 4.0.03.
#include <R_ext/Applic.h> typedef double (*optimfn)(int n, double * xin, void * ex); typedef void (*optimgr)(int n, double * xin, double * grad, void * ex); void vmmin( int n, double * x, double * Fmin, optimfn fn, optimgr gr, int maxit, int trace, int * mask, double abstol, double reltol, int nREPORT, void * ex, int * fncount, int * grcount, int * fail ); void nmmin( int n, double * xin, double * xout, double * Fmin, optimfn fn, int * fail, double abstol, double intol, void * ex, double alpha, double beta, double gamma, int trace, int * fncount, int maxit ); void cgmin( int n, double * xin, double * xout, double * Fmin, optimfn fn, optimgr gr, int * fail, double abstol, double intol, void * ex, int type, int trace, int * fncount, int * grcount, int maxit ); void lbfgsb( int n, int m, double * x, double * l, double * u, int * nbd, double * Fmin, optimfn fn, optimgr gr, int * fail, void * ex, double factr, double pgtol, int * fncount, int * grcount, int maxit, char * msg, int trace, int nREPORT ); void samin( int n, double * x, double * Fmin, optimfn fn, int maxit, int tmax, double ti, int trace, void * ex );
The number of parameters to optimise.
The the maximum number of variable metric corrections used to define the L-BFGS approximate Hessian.
The starting point of optimisation.
On entry, the starting point of optimisation. On exit, the optimal value found by the function.
The optimal value found by the function.
The arrays l[n] and u[n] set the
lower and the upper bounds on x, respectively. The array
nbd[n] must contain integers in 0:3: 0 if the
corresponding parameter is unbounded; 1 if it has a lower bound; 2 if it
has both a lower and an upper bound; 3 if it has an upper bound.
On exit, the value of the function at the optimal point.
The function to optimise. It must accept the parameters
xin[n], the opaque context pointer ex and
return the value at the given point.
The gradient of the function to optimise. Given the parameters
xin[n] and the opaque context pointer ex, must
populate grad[n] with the value of the gradient at
the given point.
The maximal number of iterations.
vmminnmmincgminWill print the progress information if set to a nonzero value.
vmmin will print the current value of the function every
nREPORT iterations.
lbfgsbNo progress printout.
Print the current value of the function every nREPORT iterations.
Print detailed information at the final iteration.
Same as 2, but also print the norm of the projected gradient every nREPORT iterations.
Print details of every iteration except “n-vectors”.
Same as 4, but also print the changes of active set and more information at the start and the end of iterations.
Same as 5, but also print the parameters and the gradient.
Printout is unspecified for other values of trace.
saminWill print the progress information every trace iterations if set to a positive value; no printout for zero. Must not be set to a negative value.
Report progress information every nREPORT iterations, if enabled with trace. Must be a positive number.
An array of int[n]. A nonzero mask[i]
indicates that x[i] is a fixed parameter.
Termination criterion: stop if fn(n, x,
ex) <= abstol.
Termination criterion: stop if |change in fn()| <=
reltol * (|min fn()| + reltol).
nmminTermination criterion is determined from the initial value of the
function: convtol = intol * (fabs(fn()) +
intol). During the iterations, the termination test is the range
of the values of the polytope being <= convtol.
cgminTermination criterion is determined from the number of function
parameters: tol = intol * n *
sqrt(intol). During the iterations, the termination test is the
conjugate step coefficient being <= tol.
Termination criterion: stop if (change in fn())/max(old
fn(), new fn(), 1) <= factr*epsmch, where
epsmch is the machine epsilon.
Termination criterion: stop if the infinity-norm of the projected
gradient is <= pgtol.
The number of evaluations to take at each temperature.
The starting simulated annealing temperature.
An opaque context pointer passed to fn and gr.
Output variable, will be populated with the number of calls to fn.
Output variable, will be populated with the number of calls to gr.
vmmincgminSet to 0 if the optimisation process converges, 1 otherwise.
nmminOptimisation converged.
Failed to evaluate the function at initial parameters, or exceeded the iteration number limit.
Polytope size measure not decreased after trying to shrink it.
lbfgsbOptimisation converged.
Exceeded the iteration number limit.
Warning: unable to satisfy the convergence conditions.
Error in the input arguments.
Scaling parameters: reflection factor, contraction factor, expansion factor, respectively. Reasonable defaults are 1.0, 0.5, and 2.0.
The type of the conjugate gradients minimiser: 1 for Fletcher-Reeves; 2 for Polak-Ribière; 3 for Beale-Sorenson.
vmminMinimises fn and gr using the variable-metric
Broyden-Fletcher-Goldfarb-Shanno algorithm. Memory use is
O(n^2). Raises an R-level error if nREPORT <=
0 or if the initial value of the function is not finite.
nmminMinimises fn using the Nelder-Mead method. Memory use is
O(n^2). Raises an R-level error if the initial value of the
function is not finite.
cgminMinimises fn and gr using the conjugate gradients method.
Memory use is O(n). Raises an R-level error if the initial
value of the function is not finite.
lbfgsbMinimises fn and gr using the limited-memory BFGS method
with box constraints. Memory use is O(n*m+m^2).
Raises an R-level error if nREPORT <= 0 or if any of the
function evaluations resulted in a value that is not finite.
saminMinimises fn using simulated annealing. Memory use is
O(n). Raises an R-level error if trace < 0.
#include <R_ext/Applic.h> typedef void (*integr_fn)(double *x, int n, void *ex); void Rdqags( integr_fn f, void * ex, double * a, double * b, double * epsabs, double * epsrel, double * result, double * abserr, int * neval, int * ier, int * limit, int * lenw, int * last, int * iwork, double * work ); void Rdqagi( integr_fn f, void * ex, double * bound, int * inf, double * epsabs, double * epsrel, double * result, double * abserr, int * neval, int * ier, int * limit, int * lenw, int * last, int * iwork, double * work );
The function to integrate and its opaque context pointer. Given an array
x[n] of function argument values, f must
overwrite each element x[i] with the value of the integrand
at x[i].
Input arguments, the bounds of the finite integration interval.
Input arguments. Depending on the value of inf, the bounds of the (semi-)infinite integration interval are:
(bound, +Inf)
(-Inf, bound)
(-Inf, +Inf); bound ignored
Input argument, requested absolute accuracy, i.e., the upper boundary on
the absolute difference between *value and the true value
of the integral. Must be positive.
Input argument, requested relative accuracy, i.e., the upper boundary on
the ratio between the absolute error and the modulus of the true value
of the integral. Must be >= max(50*DBL_EPSILON, 0.5e-28).
Output argument, the approximation of the integral.
Output argument, the upper bound of the modulus of the absolute integration error.
Output argument, number of evaluations of the integrand. This counts the
individual elements of the vectorised calls to f with
n > 1.
Output argument indicating the success or possible problems:
Normal and reliable termination of the routine. It is assumed that the requested accuracy has been achieved.
The maximum number of subdivisions allowed (see limit) has been achieved. Depending on the behaviour of the integrand, increasing limit or splitting the integration interval around singularities or discontinuities may help.
Accumulation of roudoff error has been detected. Requested tolerance not achieved. Error may be under-estimated.
Detected unacceptably bad behaviour of the integrand.
The algorithm does not converge. Requested tolerance cannot be achieved.
The integral is probably divergent, or slowly convergent.
Invalid input arguments: *epsabs <= 0, *epsrel <
max(50 * DBL_EPSILON, 0.5e-28), *limit < 1, or
*lenw < *limit * 4.
Output argument: the number of subintervals produced in the subdivision process.
The iwork[*limit] buffer will be used as necessary
storage, with limit determining the maximal number of subintervals
used.
If *last <= (*limit/2 + 2), let k =
*last; otherwise let k = *limit + 1 -
*last. On exit, the first k elements of iwork contain
1-based indices into work, so that
work[(*limit)*3 + iwork[0] - 1], …,
work[(*limit)*3 + iwork[k-1] - 1] form a
decreasing sequence of error estimates over the subintervals.
The work[*lenw] buffer will be used as necessary
storage, with lenw determining the maximal number of subintervals
used. *lenw must be at least *limit * 4.
On exit, work[0], …, work[*last - 1]
contain the left end points of the subintervals in the partition of the
integration range, and work[*limit], …,
work[*limit + *last - 1] contain the right end
points. work[*limit * 2], …,
work[*limit * 2 + *last - 1] contain the
integral approximations over the subintervals, and
work[*limit * 3], …,
work[*limit * 3 + *last - 1] contain the error
estimates.
RdqagsIntegrates f from a to b, populating the output arguments.
RdqagiIntegrates f over a (semi-)infinite interval, populating the output arguments.
See also: https://web.archive.org/web/20220308020443/https://nines.cs.kuleuven.be/software/QUADPACK/
#include <R_ext/GraphicsEngine.h> void Rf_onintr(void);
If the interrupts are currently suspended, sets the flag that an interrupt is pending and returns.
If the interrupts are not suspended, signals an interrupt
condition, allowing a calling handler to invoke an automatically-created
resume restart and return from onintr. If the condition is
not handled, jumps to the top level like from an unhandled R-level
error.
Next: R_orderVector, Previous: onintr, Up: Functions [Index]
#include <R_ext/Utils.h> double R_atof(const char * str); double R_strtod(const char * str, char ** endptr);
A 0-terminated C string containing a decimal or a hexadecimal number optionally preceded by whitespace. The number may optionally start with the sign, ‘-’ or ‘+’.
A decimal number consists of ASCII digits ‘0’...‘9’, possibly
containing the radix character, optionally followed by the decimal
exponent, which is ‘e’ (either case), followed by an optional sign,
followed by a whole decimal number indicationg a power of ten. For
example, +15.e-1 = (1 * 10^1 + 5 * 10^0) * 10^-1 = 1.5.
A hexadecimal number consists of ‘0x’ (case-insensitively),
followed by a hexadecimal number entered using ASCII characters
‘0’...‘9’, ‘a’...‘f’ (either case). If the number
contains the radix character, it must be followed by binary exponent,
which is ‘p’ (either case) followed by an optional sign, followed
by a whole decimal number indicating a power of two. This is unlike the
C standard behaviour, which makes both of them optional.
For example, +0x.18p+4 = (1 * 16^-1 + 8 * 16^-2) * 2^4 = 1.5.
The radix character (“decimal separator”) must be an ASCII dot, ‘.’.
Special strings ‘NaN’, ‘infinity’ and ‘Inf’ are also recognised as numbers, case-insensitively.
Optional argument. If not null, will be set to the location after the last processed character.
Returns the parsed number, optionally storing the pointer past the end
of the converted part of the string in endptr. Unlike the C
functions atof and strtod, if no conversion is performed,
returns NA_REAL, not 0.
Return value is unspecified for hexadecimal fractions with a radix character but no binary exponent4.
Versions: Appeared in 2.7.0.
#include <Rinternals.h> void R_orderVector ( int * indx, int n, SEXP arglist, Rboolean nalast, Rboolean decreasing ); void R_orderVector1( int * indx, int n, SEXP x, Rboolean nalast, Rboolean decreasing );
Output buffer indx[n], will be filled with 0-based
indices (in [0, n-1]) that permute the arguments to be sorted.
A pairlist (see isList, most likely LISTSXP) containing
vectors of potentially different types LGLSXP, INTSXP,
REALSXP, STRSXP, CPLXSXP, all of length n.
A vector of type LGLSXP, INTSXP, REALSXP,
STRSXP, CPLXSXP and length n.
Whether to sort missing values last (TRUE) or first
(FALSE).
Whether to sort in decreasing order, must be either TRUE or
FALSE.
Populates indx[n] with a permutation sorting the
input arguments. Complex vectors are sorted by using the imaginary parts
to resolve ties in the real parts of the elements. Behaviour is
undefined if any of the input vectors has length less than n.
Next: iPsort, Previous: R_orderVector, Up: Functions [Index]
#include <R_ext/Utils.h> void R_isort( int * x, int n); void R_rsort( double * x, int n); void R_csort(Rcomplex * x, int n); void rsort_with_index(double * x, int * indx, int n); void Rf_revsort( double * x, int * indx, int n); #ifndef R_NO_REMAP #define revsort Rf_revsort #endif
The buffer x[n] to be sorted.
The buffer indx[n] to which the same permutation will
be applied as to x[n].
R_isortR_rsortR_csortSorts the values in x[n] in the increasing order.
Complex vectors are sorted by using the imaginary parts to resolve ties
in the real parts of the elements. NAs are sorted last.
rsort_with_indexIn addition to sorting x[n] like R_rsort,
permutes the elements of indx[n] in the same manner.
Rf_revsortSorts x[n] in the decreasing order without handling
NAs and permutes the elements of indx[n] in
the same manner.
#include <R_ext/Utils.h> void Rf_iPsort( int * x, int n, int k); #ifndef R_NO_REMAP #define iPsort Rf_iPsort #endif void Rf_rPsort( double * x, int n, int k); #ifndef R_NO_REMAP #define rPsort Rf_rPsort #endif void Rf_cPsort(Rcomplex * x, int n, int k); #ifndef R_NO_REMAP #define cPsort Rf_cPsort #endif
The buffer x[n] to perform the partial sorting of.
The 0-based index into n specifying the basis of the partial sort.
Permutes the elements of x[n] so that the values
smaller than the value originally at x[k] are
positioned at smaller indices and the ones larger are positioned at
larger indices (likely moving x[k] as well).
NAs are sorted last. Behaviour is undefined if k is not in
range [0, n-1].
Next: UNIMPLEMENTED, Previous: iPsort, Up: Functions [Index]
#include <R_ext/Utils.h> void R_qsort_I(double * v, int * indx, int i, int j); void R_qsort_int_I(int * v, int * indx, int i, int j); void R_qsort(double * v, size_t i, size_t j); void R_qsort_int(int * v, size_t i, size_t j); ! Fortran interface: subroutine qsort3(x, ii, jj) subroutine qsort4(x, indx, ii, jj)
The buffer v[i:j] to sort, using 1-based
indices.
The buffer x(ii:jj) to sort, using 1-based
indices.
The buffer indx[i:j] to permute the same way as
v (or x).
Permutes the entries of v[i:j] or
x(ii:jj) (and indx at the same indices if
applicable) the same way, sorting the contents of v. Indices other
than i:j, 1-based, inclusive are not accessed in
either array.
#include <R_ext/Error.h> NORET void UNIMPLEMENTED(const char * s);
A 0-terminated C string naming the function.
Raises an R error with the translated error message “unimplemented feature in s”.
Next: R_malloc_gc, Previous: UNIMPLEMENTED, Up: Functions [Index]
#include <R_ext/Memory.h> void R_gc(void);
If the garbage collector is enabled, performs a full garbage collection. Otherwise, schedules a full garbage collection for the next time it can run.
#include <R_ext/Memory.h> void * R_malloc_gc(size_t n); void * R_calloc_gc(size_t n, size_t s); void * R_realloc_gc(void * p, size_t n);
For R_malloc_gc and R_realloc_gc, n is the size of
the buffer to allocate. For R_calloc_gc, n*s,
safe from multiplication overflow, is the size of the buffer to
allocate.
The pointer to reallocate.
These functions call the corresponding standard C library function
(malloc / calloc / realloc) and check the return
value. A non-null pointer is returned immediately. If the allocation
failed, they perform a garbage collection, retry once, and return the
resulting pointer.
Next: Indices, Previous: Functions, Up: Introduction [Index]
Next: R_Serialize, Up: Experimental functions [Index]
#include <R_ext/RS.h> void * R_chk_calloc(R_SIZE_T nelem, R_SIZE_T elsize); void * R_chk_realloc(void * ptr, R_SIZE_T size); void R_chk_free(void * ptr);
The number of elements of size elsize to allocate a buffer for.
The size of each element.
A pointer previously returned by R_chk_calloc or R_chk_realloc.
R_chk_callocThis is the function underlying the R_Calloc macro.
See R_Calloc.
R_reallocThis is the function underlying the R_Realloc macro.
See R_Realloc.
R_FreeThis is the function underlying the R_Free macro.
See R_Free.
Next: allocS4Object, Previous: R_chk_calloc, Up: Experimental functions [Index]
#include <Rinternals.h>
typedef void * R_pstream_data_t;
typedef enum {
R_pstream_any_format,
R_pstream_ascii_format,
R_pstream_binary_format,
R_pstream_xdr_format,
R_pstream_asciihex_format
} R_pstream_format_t;
typedef struct R_outpstream_st * R_outpstream_t;
typedef struct R_inpstream_st * R_inpstream_t;
void R_InitInPStream(
R_inpstream_t istream, R_pstream_data_t data,
R_pstream_format_t type,
int (*inchar)(R_inpstream_t stream),
void (*inbytes)(R_inpstream_t stream, void * buf, int length),
SEXP (*phook)(SEXP, SEXP), SEXP pdata
);
void R_InitOutPStream(
R_outpstream_t ostream, R_pstream_data_t data,
R_pstream_format_t type, int version,
void (*outchar)(R_outpstream_t stream, int chr),
void (*outbytes)(R_outpstream_t stream, void * buf, int length),
SEXP (*phook)(SEXP, SEXP), SEXP pdata
);
void R_InitFileInPStream(
R_inpstream_t istream, FILE * fp,
R_pstream_format_t type,
SEXP (*phook)(SEXP pref, SEXP pdata), SEXP pdata
);
void R_InitFileOutPStream(
R_outpstream_t ostream, FILE * fp,
R_pstream_format_t type, int version,
SEXP (*phook)(SEXP ref, SEXP pdata), SEXP pdata
);
void R_Serialize(SEXP s, R_outpstream_t stream);
SEXP R_Unserialize(R_inpstream_t stream);
A pointer to a caller-allocated struct R_inpstream_st. The header
file provides a definition of the structure, but its contents are an
implementation detail. For R_Unserialize, the structure must be
previously initialised.
A pointer to a caller-allocated struct R_outpstream_st. The header
file provides a definition of the structure, but its contents are an
implementation detail. For R_Serialize, the structure must be
previously initialised.
The context pointer for the user-provided functions inchar,
inbytes, outchar, outbytes. Inside the callbacks, can
be accessed as stream->data.
Set the output format for serialization or limit the input format for unserialization.
R_pstream_any_formatFor unserialization: accept any of the formats described below. Invalid for serialization.
R_pstream_ascii_formatR_pstream_asciihex_formatRepresents R data using 7-bit ASCII: strings are written using
backslash-escapes, raw bytes and integers are written in hexadecimal
representation. In R_pstream_ascii_format, floating-point numbers
are written out using the decimal %.16g format, which may not
round-trip exactly, especially between platforms. In
R_pstream_asciihex_format, floating-point numbers are written out
using the hexadecimal %a format, which more directly corresponds
to the binary representation of IEEE 754 float64 numbers. Not
very fast and doesn’t compress as well as binary formats.
R_pstream_binary_formatStores the in-memory representation of primitive R types. The fastest option; doesn’t have a guaranteed byte order.
R_pstream_xdr_formatStores the primitive R types in an XDR-like format where every
multi-byte value (such as 8-byte float64 numbers) is stored in
the big-endian order.
The version of the format to use, must be 2 or 3. Format version 3
requires at least R version 3.5.0 to unserialize. Format version 2 does
not specify the native encoding, so CE_NATIVE strings are not
guaranteed to unserialize in a valid manner. Additionally, serializing
in format version 2 will materialize ALTREP objects. The minimum R version
requirement is 2.3.0.
Like the C fgets function, must read a single byte from the
serialized stream and return it as an int, or return EOF.
Must fully populate the buffer buf[length] with the next
requested portion of the serialized stream, or signal an R-level error
if that’s impossible.
Called for individual bytes of the output serialization stream
represented as ints, like the C function fputc. May signal
an R-level error on failure.
Called with buf[length] populated with a portion of the output
serialization stream. May signal an R-level error on failure.
On serialization, the phook function will be called for objects of
type WEAKREFSXP, EXTPTRSXP, and some objects of type
ENVSXP (skipping the predefined and package/namespace
environments). The first argument is the object in question; the second
argument is the pdata context object. Must either return
R_NilValue in order to serialize the object as normal, or a
STRSXP vector of positive length, which will be serialized
instead of the reference object.
On unserialization, this function will be called for every
custom-serialized object, with the first argument being the previously
produced STRSXP vector and the second argument being the
pdata context object. The return value will be used instead of the
STRSXP representation.
phook can be a null pointer in order to disable this behaviour.
The C standard input/output file pointer to serialize the object into or
read the serialized data stream from. If used with a C++ compiler, the
type of this argument is std::FILE* instead.
R_InitInPStreamR_InitFileInPStreamPrepares the context object pointed to by istream for a subsequent
call to R_Unserialize using either user-provided callbacks or the
standard C input/output subsystem.
R_InitOutPStreamR_InitFileOutPStreamPrepares the context object pointed to by ostream for a subsequent
call to R_Serialize using either user-provided callbacks or the
standard C input/output subsystem.
R_SerializeGenerates a byte representation of s according to the settings in ostream and provides it to the callbacks specified by the initialization function. Invalid serialization settings provided at the initialization stage may result in an R-level error from this function.
R_UnserializeCalls the callbacks provided by the initialization function, decodes an R object represented by the returned byte stream and returns it. Invalid unserialization settings provided at the initialization stage may result in an R-level error from this function.
This function must not be used with untrusted sources of data. The problem is not limited to yet-undiscovered vulnerabilities in the serialization format parser, since valid R objects can contain code and therefore are capable of arbitrary behaviour, including reading and writing user data and sending it over the network.
Next: asS4, Previous: R_Serialize, Up: Experimental functions [Index]
#include <Rinternals.h> SEXP Rf_allocS4Object(void); #ifndef R_NO_REMAP #define allocS4Object Rf_allocS4Object #endif
Allocates and returns an R value of type OBJSXP with the S4 bit
set.
Next: R_check_class_etc, Previous: allocS4Object, Up: Experimental functions [Index]
#include <Rinternals.h> SEXP Rf_asS4( SEXP s, Rboolean flag, int complete ); #ifndef R_NO_REMAP #define asS4 Rf_asS4 #endif
The source object, any R value.
TRUE if s must be converted into an S4 object, FALSE
otherwise.
If s has the S4 bit set and flag is FALSE:
Return the same value as s but with the S4 bit unset
Only return the data slot of s if it’s neither a NILSXP nor
has the S4 bit set.
Like the complete = 1 case above, but if the condition is
not met, return s unchanged.
Converts between S4 and non-S4 objects. If the S4 bit of s matches
flag, returns s unchanged. Otherwise works on a shallow
duplicate (see shallow_duplicate) of s if it is
MAYBE_SHARED (see MAYBE_SHARED). When
converting a non-S4 object to an S4 object, sets the S4 bit and returns
the result. Otherwise acts depending on the complete argument.
Signals an R error if complete = 1 and the condition is not
met.
Next: R_getClassDef, Previous: asS4, Up: Experimental functions [Index]
#include <Rinternals.h> int R_check_class_etc( SEXP x, const char ** valid );
An S4 object.
An array of 0-terminated C strings naming S4 classes. Must be terminated
by an empty string, "".
Returns the 0-based index i of the class in valid that would
have satisfied the R expression is(x, valid[i]). If
no classes match, returns -1.
Versions: Prior to 4.5.0, behaviour for values without the object bit set was unspecified5.
Next: R_do_new_object, Previous: R_check_class_etc, Up: Experimental functions [Index]
#include <Rinternals.h> SEXP R_do_MAKE_CLASS(const char * what); SEXP R_getClassDef(const char *what);
The name of an S4 class as a 0-terminated C string.
R_do_MAKE_CLASSCalls methods::getClass and returns the S4 class definition
object for class what. If no class defition was found, signals an
R-level error.
R_getClassDefCalls methods::getClassDef and returns the S4 class definition
object for class what. If not class defition was found, returns
R_NilValue.
Next: R_do_slot, Previous: R_getClassDef, Up: Experimental functions [Index]
#include <Rinternals.h> SEXP R_do_new_object(SEXP class_def);
The S4 class definition object previously returned by
methods::getClassDef. See R_getClassDef.
Creates and returns a new S4 object of the given class.
Next: StringBlank, Previous: R_do_new_object, Up: Experimental functions [Index]
#include <Rinternals.h> int R_has_slot( SEXP obj, SEXP name ); SEXP R_do_slot( SEXP obj, SEXP name ); SEXP R_do_slot_assign( SEXP obj, SEXP name, SEXP value );
An S4 object.
The name of the slot. Must be either a SYMSXP or a 1-element
STRSXP vector.
The desired value of the slot name. Unlike the attributes, can be
a NILSXP.
R_has_slotReturns a nonzero value if obj has a slot named name, otherwise, a zero.
Versions: Appeared in 2.7.0.
R_do_slotReturns the equivalent of R expression obj@name. If
the slot named name does not exist, signals an R-level error.
R_do_slot_assignSets the attribute named name to value on the object obj and returns the new object which may or may not differ from obj.
In particular, when setting the .Data attribute, the value
will be allocated anew and must be protected and used in place of
the original.
Next: IS_LONG_VEC, Previous: R_do_slot, Up: Experimental functions [Index]
#include <Rinternals.h> Rboolean Rf_StringBlank(SEXP x); #ifndef R_NO_REMAP #define StringBlank Rf_StringBlank #endif #include <R_ext/Utils.h> Rboolean Rf_StringTrue(const char * name); #define StringTrue Rf_StringTrue Rboolean Rf_StringFalse(const char * name); #define StringFalse Rf_StringFalse Rboolean Rf_isBlankString(const char * name); #define isBlankString Rf_isBlankString
A value of type NILSXP or CHARSXP.
A 0-terminated C string in the encoding of the current locale.
Rf_StringBlankReturns TRUE if x is a NILSXP or a zero-length
CHARSXP; otherwise returns FALSE.
Rf_StringTrueReturns TRUE if name will be interpreted by R as a
“truthy” string, e.g., as.character(name) would return
TRUE. Otherwise returns FALSE.
Rf_StringFalseReturns TRUE if name will be interpreted by R as a
“falsy” string, e.g., as.character(name) would return
FALSE. Otherwise returns FALSE.
Rf_isBlankStringReturns TRUE if name is empty or only consists of “blank”
characters, such as spaces, newlines, horizontal or vertical tabs, or
form feeds. The precise definition of “blank” depends on the current
locale: it is either the C function iswspace (for multi-byte
locale encodings), or isspace. Returns FALSE if it finds a
non-blank character.
Next: IS_SCALAR, Previous: StringBlank, Up: Experimental functions [Index]
#include <Rinternals.h> int IS_LONG_VEC(SEXP x);
An R value of vector type (see XLENGTH).
Returns a nonzero value of x is longer than R_LEN_T_MAX,
i.e., LENGTH(x) would signal an error.
Versions: Appeared in 3.0.0.
Next: duplicated, Previous: IS_LONG_VEC, Up: Experimental functions [Index]
#include <Rinternals.h> int IS_SCALAR(SEXP x, int type);
An arbitrary R value.
A SEXPTYPE that corresponds to a vector type (see XLENGTH).
Returns TRUE if x is of type type and has a length of
1, otherwise FALSE. May raise an error if type is not a
vector type.
Versions: Appeared in 3.1.0.
Next: R_compute_identical, Previous: IS_SCALAR, Up: Experimental functions [Index]
#include <Rinternals.h> R_xlen_t Rf_any_duplicated( SEXP x, Rboolean from_last ); #ifndef R_NO_REMAP #define any_duplicated Rf_any_duplicated #endif R_xlen_t Rf_any_duplicated3( SEXP x, SEXP incomp, Rboolean from_last ); #ifndef R_NO_REMAP #define any_duplicated3 Rf_any_duplicated3 #endif SEXP Rf_duplicated( SEXP x, Rboolean from_last ); #ifndef R_NO_REMAP #define duplicated Rf_duplicated #endif
An R vector (see isVector).
A vector of values convertible to TYPEOF(x)
(see coerceVector) that are considered incomparable and therefore
will not be marked is duplicated.
Whether to search for duplicates from the last element of x instead of the first one.
Rf_any_duplicatedRf_any_duplicated3Both functions return the 1-based index of the first encountered element of x that has already been encountered, unless it is also a member of incomp. The return value is 0 if no such element could be found.
Rf_duplicatedReturns an LGLSXP vector of the same length as x. The first
appearance (corresponding to the traversal order in from_last) of
every item in x is marked with FALSE, and every following
occurrence is marked with TRUE.
Next: R_LockBinding, Previous: duplicated, Up: Experimental functions [Index]
#include <Rinternals.h> #define IDENT_NUM_AS_BITS /*...*/ #define IDENT_NA_AS_BITS /*...*/ #define IDENT_ATTR_BY_ORDER /*...*/ #define IDENT_USE_BYTECODE /*...*/ #define IDENT_USE_CLOENV /*...*/ #define IDENT_USE_SRCREF /*...*/ #define IDENT_EXTPTR_AS_REF /*...*/ Rboolean R_compute_identical( SEXP x, SEXP y, int flags );
The two R values to compare for being “identical”.
A bitwise combination of the following constants:
IDENT_NUM_AS_BITSIf set, will use bitwise comparison for non-NaN numbers; otherwise, compare them numerically. In particular, bitwise comparison will distinguish the floating point numbers +0 and -0.
IDENT_NA_AS_BITSIf set, will use bitwise comparison for NaN numbers. Otherwise,
NAs are identical to each other, but not equal to non-NA
NaN’s, which are also identical to each other.
IDENT_ATTR_BY_ORDERIf set, the order in which the attributes are set will be taken into account. Otherwise, the attributes of R values are considered to be sets and therefore orderless.
IDENT_USE_BYTECODEIf set, compare the bytecode bodies of closures. Otherwise, compare their body expressions (see R_ClosureExpr).
IDENT_USE_CLOENVIf set, compare the environment pointers when comparing closures. Otherwise, ignore the environments and only compare the bodies (see above) and the parilists of formals.
IDENT_USE_SRCREFIf set, compare the source references in addition to the bodies and pairlists of formals. Otherwise, ignore the source references.
IDENT_EXTPTR_AS_REFIf set, compare objects of type EXTPTRSXP directly, as in
x == y. Otherwise, compare their stored external
pointers, as in R_ExternalPtrAddr(x) ==
R_ExternalPtrAddr(y).
Tests the values x and y for being “identical”. Precise
definition of “identity” is an open question in programming and
philosophy, but in R, identical values must have the same type,
attributes, and contents, subject to the flags, recursively. For
reference-semantics types (ENVSXP, WEAKREFSXP,
SYMSXP, NILSXP, see above for EXTPTRSXP), identity
is equality of the pointers, not the contents.
The function will not raise any errors for valid x and y.
The defaults of the R function identical() correspond to the
flags being equal to IDENT_USE_CLOENV.
Next: R_LockEnvironment, Previous: R_compute_identical, Up: Experimental functions [Index]
#include <Rinternals.h> void R_LockBinding( SEXP sym, SEXP env ); Rboolean R_BindingIsLocked( SEXP sym, SEXP env ); void R_unLockBinding( SEXP sym, SEXP env );
The name of the binding, a SYMSXP value. Must name an existing
binding in env.
The environment owning the binding, an ENVSXP. An S4 object based
on an environment is also accepted.
Locking prevents the value of the binding named sym from changing in the environment env until it is unlocked. Unless env is also locked (see R_LockEnvironment), it is still possible to remove the locked binding and then create a new one.
R_LockBinding locks the binding; R_BindingIsLocked returns
whether the binding is locked; R_unLockBinding unlocks it again.
All three functions will signal an R-level error if sym does not
correspond to an existing binding in env. The base environment and
the base namespace are handled specially and will work as expected.
Next: R_MakeActiveBinding, Previous: R_LockBinding, Up: Experimental functions [Index]
#include <Rinternals.h> void R_LockEnvironment( SEXP env, Rboolean bindings ); Rboolean R_EnvironmentIsLocked(SEXP env);
An ENVSXP. An S4 object based on an environment is also accepted.
Whether to lock all the bindings (see R_LockBinding) before also locking the environment.
Locking an environment with R_LockEnvironment prevents future
additions and removals of bindings to the environment, but does not
prevent changes to the existing bindings, unless bindings is set
to TRUE. R_EnvironmentIsLocked returns whether env
is locked. There is no interface to unlock an environment again.
Next: DATAPTR_OR_NULL, Previous: R_LockEnvironment, Up: Experimental functions [Index]
#include <Rinternals.h> void R_MakeActiveBinding( SEXP sym, SEXP fun, SEXP env ); SEXP R_ActiveBindingFunction( SEXP sym, SEXP env ); Rboolean R_BindingIsActive( SEXP name, SEXP env );
A SYMSXP naming the binding. Must not name an already-existing
non-active binding, or a locked binding.
A SYMSXP naming the binding. Must correspond to an existing
binding in env.
A function: CLOSXP, BUILTINSXP, or SPECIALSXP
(see isFunction). Must accept one optional argument.
An ENVSXP. An S4 object based on an environment is also accepted.
R_MakeActiveBindingMakes it so that reading a variable named sym in the environment env will call fun with no arguments and use the return value as the value of the binding. Assigning to the variable named sym will instead call fun with the value being assigned as the only argument.
R_ActiveBindingFunctionIf sym corresponds to an active binding in env, returns its fun. Signals an R-level error otherwise.
R_BindingIsActiveReturns whether sym corresponds to an active binding in env. Signals an R-level error if sym cannot be found in env.
Next: REAL_GET_REGION, Previous: R_MakeActiveBinding, Up: Experimental functions [Index]
#include <Rinternals.h> const void * DATAPTR_OR_NULL(SEXP x); const int * LOGICAL_OR_NULL(SEXP x); const int * INTEGER_OR_NULL(SEXP x); const double * REAL_OR_NULL(SEXP x); const Rcomplex * COMPLEX_OR_NULL(SEXP x); const Rbyte * RAW_OR_NULL(SEXP x);
An R value of the corresponding type: any vector type for
DATAPTR_OR_NULL (see isVector); LGLSXP for
LOGICAL_OR_NULL; INTSXP for INTEGER_OR_NULL;
REALSXP for REAL_OR_NULL; CPLXSXP for
COMPLEX_OR_NULL; RAWSXP for RAW_OR_NULL.
These functions return a read-only data pointer if one is available
(see REAL_RO), but a null pointer if that would have involved
materialising an ALTREP object. An R-level error is signalled if x
is of the wrong SEXPTYPE.
Versions: Appeared in 3.5.0.
Next: REAL_NO_NA, Previous: DATAPTR_OR_NULL, Up: Experimental functions [Index]
#include <Rinternals.h> R_xlen_t INTEGER_GET_REGION( SEXP sx, R_xlen_t i, R_xlen_t n, int * buf ); R_xlen_t REAL_GET_REGION( SEXP sx, R_xlen_t i, R_xlen_t n, double * buf ); R_xlen_t LOGICAL_GET_REGION( SEXP sx, R_xlen_t i, R_xlen_t n, int * buf ); R_xlen_t COMPLEX_GET_REGION( SEXP sx, R_xlen_t i, R_xlen_t n, Rcomplex * buf ); R_xlen_t RAW_GET_REGION( SEXP sx, R_xlen_t i, R_xlen_t n, Rbyte * buf );
An R vector of the corresponding type: INTSXP for
INTEGER_GET_REGION, REALSXP for REAL_GET_REGION,
LGLSXP for LOGICAL_GET_REGION, CPLXSXP for
COMPLEX_GET_REGION, RAWSXP for RAW_GET_REGION.
The 0-based index into sx at which to start reading up to n elements.
The number of elements to read from sx.
The buffer buf[n] to populate with the contents of
sx.
These functions populate the buffer starting at buf with up to
n elements from the vector sx, returning the actual number
of elements written. If possible, this will avoid materialising the
ALTREP vector. An error is raised if sx is of the wrong type. If
i is outside the range 0:(XLENGTH(sx)-1), behaviour
is undefined.
Versions:
REAL_GET_REGIONandINTEGER_GET_REGIONppeared in 3.5.0;LOGICAL_GET_REGION,COMPLEX_GET_REGION, andRAW_GET_REGIONappeared in 3.6.0.
Next: REAL_IS_SORTED, Previous: REAL_GET_REGION, Up: Experimental functions [Index]
#include <Rinternals.h> int INTEGER_NO_NA(SEXP x); int REAL_NO_NA(SEXP x); int LOGICAL_NO_NA(SEXP x); int STRING_NO_NA(SEXP x);
An R vector of the corresponding type: INTSXP for
INTEGER_NO_NA, REALSXP for REAL_NO_NA,
STRSXP for STRING_NO_NA, LGLSXP for
LOGICAL_NO_NA.
These functions return a nonzero value if it is known that x
contains no missing (NA) values. Otherwise the vector may or may
not contain missing values. Behaviour is undefined if x is not of
the corresponding type.
Versions:
INTEGER_NO_NA,REAL_NO_NA,STRING_NO_NAappeared in 3.5.0.LOGICAL_NO_NAappeared in 3.6.0.
Next: ALTREP, Previous: REAL_NO_NA, Up: Experimental functions [Index]
#include <Rinternals.h>
enum {
SORTED_DECR = /*...*/,
UNKNOWN_SORTEDNESS = /*...*/,
SORTED_INCR = /*...*/,
};
int INTEGER_IS_SORTED(SEXP x);
int REAL_IS_SORTED(SEXP x);
int STRING_IS_SORTED(SEXP x);
An R vector of the corresponding type: INTSXP for
INTEGER_IS_SORTED, REALSXP for REAL_IS_SORTED,
CPLXSXP for COMPLEX_IS_SORTED, RAWSXP for
RAW_IS_SORTED.
These functions return SORTED_DECR if x is known to be
sorted in the decreasing order, SORTED_INCR if x is known
to be sorted in the increasing order, and UNKNOWN_SORTEDNESS if
x may or may not be sorted. Behaviour is undefined if x is
not of the corresponding type.
Versions: Appeared in 3.5.0.
Next: R_new_altrep, Previous: REAL_IS_SORTED, Up: Experimental functions [Index]
#include <Rinternals.h> int ALTREP(SEXP x); SEXP ALTREP_CLASS(SEXP ax); Rboolean R_altrep_inherits( SEXP x, R_altrep_class_t class );
An arbitrary R value.
An R value for which ALTREP(ax) is nonzero.
An ALTREP class pointer.
ALTREPReturns a nonzero value if x is a “compact representation” (ALTREP) value. Access to the data pointers of ALTREP values may be problematic and should be replaced with access to individual elements (see REAL_ELT) or vector subregions (see REAL_GET_REGION).
ALTREP_CLASSReturns the ALTREP class object containing the methods set up for use on
ax. The return value is of unspecified SEXPTYPE. Behaviour
is undefined if ax is not an ALTREP object.
R_altrep_inheritsReturns a nonzero value if x is an ALTREP value whose class pointer is class.
See also: https://svn.r-project.org/R/branches/ALTREP/ALTREP.html
Next: R_set_altrep_..._method, Previous: ALTREP, Up: Experimental functions [Index]
#include <R_ext/Altrep.h> SEXP R_new_altrep( R_altrep_class_t aclass, SEXP data1, SEXP data2 ); #include <Rinternals.h> SEXP R_altrep_data1(SEXP ax); SEXP R_altrep_data2(SEXP ax); void R_set_altrep_data1(SEXP ax, SEXP v); void R_set_altrep_data2(SEXP ax, SEXP v);
An initialized ALTREP class.
The two instance variables that will belong to the compact-representation value, arbitrary R values.
An R value for which ALTREP(ax) is nonzero.
An arbitrary R value.
R_new_altrepAllocates, constructs and returns a compact-representation value. It
will have the TYPEOF() of the corresponding class and will use
the methods in aclass and the instance variables to respond to
calls such as XLENGTH().
R_altrep_data1R_altrep_data2Returns one of the two ALTREP instance variables belonging to ax. Behaviour is undefined if ax is not an ALTREP object.
R_set_altrep_data1R_set_altrep_data2Sets the corresponding ALTREP instance variable of ax to v,
sharing it without duplication. Behaviour is undefined if ax is
not an ALTREP object.
Versions: Appeared in 3.5.0.
See also: https://svn.r-project.org/R/branches/ALTREP/ALTREP.html
Next: R_set_altvec_..._method, Previous: R_new_altrep, Up: Experimental functions [Index]
#include <R_ext/Altrep.h> typedef R_xlen_t (*R_altrep_Length_method_t)(SEXP x); void R_set_altrep_Length_method( R_altrep_class_t cls, R_altrep_Length_method_t fun ); typedef SEXP (*R_altrep_Duplicate_method_t)( SEXP x, Rboolean deep ); void R_set_altrep_Duplicate_method( R_altrep_class_t cls, R_altrep_Duplicate_method_t fun ); typedef SEXP (*R_altrep_DuplicateEX_method_t)( SEXP x, Rboolean deep ); void R_set_altrep_DuplicateEX_method( R_altrep_class_t cls, R_altrep_DuplicateEX_method_t fun ); typedef SEXP (*R_altrep_Serialized_state_method_t)(SEXP x); void R_set_altrep_Serialized_state_method( R_altrep_class_t cls, R_altrep_Serialized_state_method_t fun ); typedef SEXP (*R_altrep_Unserialize_method_t)( SEXP class, SEXP state ); void R_set_altrep_Unserialize_method( R_altrep_class_t cls, R_altrep_Unserialize_method_t fun ); typedef SEXP (*R_altrep_UnserializeEX_method_t)( SEXP class, SEXP state, SEXP attr, int objf, int levs ); void R_set_altrep_UnserializeEX_method( R_altrep_class_t cls, R_altrep_UnserializeEX_method_t fun ); typedef SEXP (*R_altrep_Coerce_method_t)(SEXP x, int type); void R_set_altrep_Coerce_method( R_altrep_class_t cls, R_altrep_Coerce_method_t fun ); typedef Rboolean (*R_altrep_Inspect_method_t)( SEXP x, int pre, int deep, int pvec, void (*inspect_subtree)(SEXP x, int pre, int deep, int pvec) ); void R_set_altrep_Inspect_method( R_altrep_class_t cls, R_altrep_Inspect_method_t fun );
A compact representation vector class object previously returned by
R_make_altstring_class, R_make_altinteger_class,
R_make_altreal_class, R_make_altlogical_class,
R_make_altraw_class, R_make_altcomplex_class, or
R_make_altlist_class.
The SEXP value corresponding to the ALTREP class definition.
A function pointer of the corresponding type.
An ALTREP value.
Set to TRUE if other values possibly contained in x must
also be duplicated in the return value instead of being shared by
reference.
An object previously returned by the Serialized_state method of
the class.
Internal fields (attributes, the object bit, the levels fields) of the ALTREP object being unserialized.
The desired SEXPTYPE of the return value.
The number of spaces in the Inspect output prefix.
A positive number defines the recursion depth of the Inspect
output; 0 for no recursion, -1 for effectively unlimited recursion.
The number of vector elements to print when Inspecting vector
values.
The function to call in order to inspect the child elements of x
if deep != 0. Will automatically adjust pre (by two)
and deep (by one) for the duration of the call.
R_set_altrep_Length_methodR_set_altrep_Duplicate_methodR_set_altrep_DuplicateEX_methodR_set_altrep_Serialized_state_methodR_set_altrep_Unserialize_methodR_set_altrep_UnserializeEX_methodR_set_altrep_Coerce_methodR_set_altrep_Inspect_methodSets the function pointer inside the ALTREP class object. Currently, these methods are common to all ALTREP classes. There is no facility for unregistering ALTREP classes, so once a function pointer is set from a package shared library, it must not be unloaded.
R_altrep_Length_method_tMust return the length of the compact-representation vector, or signal an error. The default method signals an error.
R_altrep_Duplicate_method_tMust return a copy (see duplicate) of x that can be altered independently of x, ignoring the attributes. R will duplicate and install the attributes by itself.
May return a null pointer, in which case R will produce a materialised copy of the object by itself. The default method returns a null pointer.
R_altrep_DuplicateEX_method_tLike the Duplicate method above, but must duplicate the
attributes in the same manner.
May return a null pointer, in which case R will produce a
materialised copy of the object by itself. The default method calls
the Duplicate method, duplicates the attributes of x and
installs them onto the return value.
R_altrep_Serialized_state_method_tMust prepare and return a representation of x that can be given to
the Unserialize methods below in order to recreate it.
May return a null pointer, making R materialise the object when saving it. The default method returns a null pointer.
R_altrep_Unserialize_method_tMust construct and return an ALTREP object of the given class given the
data previously prepared by the Serialized_state method above.
The default method signals an R-level error.
R_altrep_UnserializeEX_method_tLike the Unserialize method above, but must also take care of
setting the attributes, the levels field and the object bit on the
return value. This is likely impossible to implement within the confines
of the R API.
The default method calls the Unserialize method, sets the
attributes, the object bit, and the levels field, and returns the
result.
R_altrep_Coerce_method_tMust return an R value of SEXPTYPE type containing the
result of conversion of x into that type, ignoring the attributes.
May return a null pointer, making R perform the conversion as usual (see coerceVector). The default method returns a null pointer.
R_altrep_Inspect_method_tThis method will be called from .Internal(inspect(...)) after
printing the standard SEXP header contents; it can then print
(see Rprintf) additional information specific to this ALTREP class.
When starting a new line, this method must respect the output
indentation pre. Printing the vector elements, if done, should be
subject to the recommended vector printing length pvec. The method
should call inspect_subtree for child elements, subject to the
limits in deep.
If the return value is TRUE, R will consider the value inspected
and won’t access its contents; otherwise R will then inspect the
contents of x as if it was an ordinary value. Either way, R will
then take care of inspecting the attributes of x.
The default method returns FALSE.
Versions: Appeared in 3.5.0.
Next: R_make_altstring_class, Previous: R_set_altrep_..._method, Up: Experimental functions [Index]
#include <R_ext/Altrep.h> typedef void * (*R_altvec_Dataptr_method_t)( SEXP x, Rboolean writable ); void R_set_altvec_Dataptr_method( R_altrep_class_t cls, R_altvec_Dataptr_method_t fun ); typedef const void * (*R_altvec_Dataptr_or_null_method_t)(SEXP x); void R_set_altvec_Dataptr_or_null_method( R_altrep_class_t cls, R_altvec_Dataptr_or_null_method_t fun ); typedef SEXP (*R_altvec_Extract_subset_method_t)( SEXP x, SEXP indx, SEXP call ); void R_set_altvec_Extract_subset_method( R_altrep_class_t cls, R_altvec_Extract_subset_method_t fun );
A compact representation vector class object previously returned by
R_make_altstring_class, R_make_altinteger_class,
R_make_altreal_class, R_make_altlogical_class,
R_make_altraw_class, R_make_altcomplex_class, or
R_make_altlist_class.
A function pointer of the corresponding type.
An ALTREP value of the corresponding class.
TRUE if the return value may be used to modify x.
A vector of 1-based subscripts to extract from x, of type
REALSXP or INTSXP, not necessarily in range [1,
XLENGTH(x)].
A LANGSXP value for use in error reporting
(see errorcall).
R_set_altvec_Dataptr_methodR_set_altvec_Dataptr_or_null_methodR_set_altvec_Extract_subset_methodSets the function pointer inside the ALTREP class object. Currently, all ALTREP classes are vector classes. There is no facility for unregistering ALTREP classes, so once a function pointer is set from a package shared library, it must not be unloaded.
R_altvec_Dataptr_method_tMust return a pointer to the start of the buffer of type corresponding
to the SEXPTYPE of x and containing XLENGTH(x)
elements (see DATAPTR_RO) corresponding to the contents of
x. May signal an R error instead.
The default method always signals an error.
R_altvec_Dataptr_or_null_method_tLike the Dataptr method above, but the method may return a null
pointer to indicate a preference for *_Elt
(see REAL_ELT) and *_Get_region
(see REAL_GET_REGION) methods instead of full buffer access. The
return value will not be used to modify x.
The default method always returns a null pointer.
R_altvec_Extract_subset_method_tMust allocate and return a new vector containing the result of
subsetting, x[indx], following the usual semantics of
the [ operator for numeric subscripts. For values outside the
range of x, missing values must be returned (R_NilValue for
VECSXP lists, 0 for RAWSXP vectors). May also
return a null pointer (see above).
The default method always returns a null pointer.
Versions: Appeared in 3.5.0.
Next: R_make_altinteger_class, Previous: R_set_altvec_..._method, Up: Experimental functions [Index]
#include <R_ext/Altrep.h> R_altrep_class_t R_make_altstring_class( const char *cname, const char *pname, DllInfo *info ); typedef SEXP (*R_altstring_Elt_method_t)(SEXP x, R_xlen_t i); void R_set_altstring_Elt_method( R_altrep_class_t cls, R_altstring_Elt_method_t fun ); typedef void (*R_altstring_Set_elt_method_t)( SEXP x, R_xlen_t i, SEXP v ); void R_set_altstring_Set_elt_method( R_altrep_class_t cls, R_altstring_Set_elt_method_t fun ); typedef int (*R_altstring_Is_sorted_method_t)(SEXP x); void R_set_altstring_Is_sorted_method( R_altrep_class_t cls, R_altstring_Is_sorted_method_t fun ); typedef int (*R_altstring_No_NA_method_t)(SEXP x); void R_set_altstring_No_NA_method( R_altrep_class_t cls, R_altstring_No_NA_method_t fun );
The name of the ALTREP class and the package owning it, respectively. Together they identify an ALTREP class. It is possible to have multiple classes with the same cname but different pname (and vice versa).
An opaque pointer given to the initialization routine of the shared library (see R_registerRoutines).
A class object previously returned by R_make_altstring_class.
A function pointer of the corresponding type.
The ALTREP value of the given class.
The 0-based index into x in range [0, XLENGTH(x)-1].
The CHARSXP value to set into x.
R_make_altstring_classAllocates, registers and returns an ALTREP class with the given names.
In addition to the methods given here, compact representation string vectors must implement the common “altrep” methods (see R_set_altrep_..._method) and the common “altvec” methods (see R_set_altvec_..._method).
R_set_altstring_Elt_methodR_set_altstring_Set_elt_methodR_set_altstring_Is_sorted_methodR_set_altstring_No_NA_methodSets the function pointer inside the ALTREP class object. Behaviour is undefined if cls is not a compact string representation class. There is no facility for unregistering ALTREP classes, so once a function pointer is set from a package shared library, it must not be unloaded.
R_altstring_Elt_method_tMust return x[i] (for 0-based i) or signal an
error. The default method always raises an error.
R_altstring_Set_elt_method_tMust set x[i] <- v (for 0-based i), even
if it’s not compatible with the chosen compact representation, or signal
an error. The default method always raises an error.
R_altstring_Is_sorted_method_tMust return one of the sortedness constants: SORTED_DECR,
UNKNOWN_SORTEDNESS, SORTED_INCR.
See STRING_IS_SORTED. The default method always
returns UNKNOWN_SORTEDNESS.
R_altstring_No_NA_method_tMust return 1 if x is known not to store any missing values (see STRING_NO_NA), otherwise 0 (including if it’s unknown). The default method always returns 0.
Versions: Appeared in 3.5.0.
Next: R_make_altlogical_class, Previous: R_make_altstring_class, Up: Experimental functions [Index]
#include <R_ext/Altrep.h> R_altrep_class_t R_make_altinteger_class( const char *cname, const char *pname, DllInfo *info ); typedef int (*R_altinteger_Elt_method_t)( SEXP x, R_xlen_t i ); void R_set_altinteger_Elt_method( R_altrep_class_t cls, R_altinteger_Elt_method_t fun ); typedef R_xlen_t (*R_altinteger_Get_region_method_t)( SEXP x, R_xlen_t i, R_xlen_t n, int * buf ); void R_set_altinteger_Get_region_method( R_altrep_class_t cls, R_altinteger_Get_region_method_t fun ); typedef int (*R_altinteger_Is_sorted_method_t)(SEXP x); void R_set_altinteger_Is_sorted_method( R_altrep_class_t cls, R_altinteger_Is_sorted_method_t fun ); typedef int (*R_altinteger_No_NA_method_t)(SEXP x); void R_set_altinteger_No_NA_method( R_altrep_class_t cls, R_altinteger_No_NA_method_t fun ); typedef SEXP (*R_altinteger_Sum_method_t)( SEXP x, Rboolean narm ); void R_set_altinteger_Sum_method( R_altrep_class_t cls, R_altinteger_Sum_method_t fun ); typedef SEXP (*R_altinteger_Min_method_t)( SEXP x, Rboolean narm ); void R_set_altinteger_Min_method( R_altrep_class_t cls, R_altinteger_Min_method_t fun ); typedef SEXP (*R_altinteger_Max_method_t)( SEXP x, Rboolean narm ); void R_set_altinteger_Max_method( R_altrep_class_t cls, R_altinteger_Max_method_t fun );
The name of the ALTREP class and the package owning it, respectively. Together they identify an ALTREP class. It is possible to have multiple classes with the same cname but different pname (and vice versa).
An opaque pointer given to the initialization routine of the shared library (see R_registerRoutines).
A class object previously returned by R_make_altinteger_class.
The ALTREP value of the given class.
The 0-based index into x in range [0, XLENGTH(x)-1].
The buffer buf[n] to populate with the contents of
x.
If TRUE, ignore the missing values while computing the summary.
R_make_altinteger_classAllocates, registers and returns an ALTREP class with the given names.
In addition to the methods given here, compact representation integer vectors must implement the common “altrep” methods (see R_set_altrep_..._method) and the common “altvec” methods (see R_set_altvec_..._method).
R_set_altinteger_Elt_methodR_set_altinteger_Get_region_methodR_set_altinteger_Is_sorted_methodR_set_altinteger_No_NA_methodR_set_altinteger_Sum_methodR_set_altinteger_Min_methodR_set_altinteger_Max_methodSets the function pointer inside the ALTREP class object. Behaviour is undefined if cls is not a compact integer vector class. There is no facility for unregistering ALTREP classes, so once a function pointer is set from a package shared library, it must not be unloaded.
R_altinteger_Elt_method_tMust return x[i] for the 0-based index i. The
default method returns INTEGER(x)[i].
R_altinteger_Get_region_method_tMust copy up to n elements, starting at 0-based index i,
into buf[n], and return the number of elements
copied. The default method defers to INTEGER_ELT and hence the
Elt method above.
R_altinteger_Is_sorted_method_tMust return one of the sortedness constants: SORTED_DECR,
UNKNOWN_SORTEDNESS, SORTED_INCR.
See INTEGER_IS_SORTED. The default method always
returns UNKNOWN_SORTEDNESS.
R_altinteger_No_NA_method_tMust return 1 if x is known not to store any missing values (see INTEGER_NO_NA), otherwise 0 (including if it’s unknown). The default method always returns 0.
R_altinteger_Sum_method_tR_altinteger_Min_method_tR_altinteger_Max_method_tMust calculate and return the specified summary of the contents of
x, ignoring missing values if narm is TRUE. May
return a null pointer, in which case R will compute the summary by
accessing the elements of the vector.
Versions: Appeared in 3.5.0.
Next: R_make_altreal_class, Previous: R_make_altinteger_class, Up: Experimental functions [Index]
#include <R_ext/Altrep.h> R_altrep_class_t R_make_altlogical_class( const char *cname, const char *pname, DllInfo *info ); typedef int (*R_altlogical_Elt_method_t)( SEXP x, R_xlen_t i ); void R_set_altlogical_Elt_method( R_altrep_class_t cls, R_altlogical_Elt_method_t fun ); typedef R_xlen_t (*R_altlogical_Get_region_method_t)( SEXP x, R_xlen_t i, R_xlen_t n, int * buf ); void R_set_altlogical_Get_region_method( R_altrep_class_t cls, R_altlogical_Get_region_method_t fun ); typedef int (*R_altlogical_Is_sorted_method_t)(SEXP x); void R_set_altlogical_Is_sorted_method( R_altrep_class_t cls, R_altlogical_Is_sorted_method_t fun ); typedef int (*R_altlogical_No_NA_method_t)(SEXP x); void R_set_altlogical_No_NA_method( R_altrep_class_t cls, R_altlogical_No_NA_method_t fun ); typedef SEXP (*R_altlogical_Sum_method_t)( SEXP x, Rboolean narm ); void R_set_altlogical_Sum_method( R_altrep_class_t cls, R_altlogical_Sum_method_t fun );
The name of the ALTREP class and the package owning it, respectively. Together they identify an ALTREP class. It is possible to have multiple classes with the same cname but different pname (and vice versa).
An opaque pointer given to the initialization routine of the shared library (see R_registerRoutines).
A class object previously returned by R_make_altlogical_class.
The ALTREP value of the given class.
The 0-based index into x in range [0, XLENGTH(x)-1].
The buffer buf[n] to populate with the contents of
x.
If TRUE, ignore the missing values while computing the summary.
R_make_altlogical_classAllocates, registers and returns an ALTREP class with the given names.
In addition to the methods given here, compact representation integer vectors must implement the common “altrep” methods (see R_set_altrep_..._method) and the common “altvec” methods (see R_set_altvec_..._method).
R_set_altlogical_Elt_methodR_set_altlogical_Get_region_methodR_set_altlogical_Is_sorted_methodR_set_altlogical_No_NA_methodR_set_altlogical_Sum_methodSets the function pointer inside the ALTREP class object. Behaviour is undefined if cls is not a compact integer vector class. There is no facility for unregistering ALTREP classes, so once a function pointer is set from a package shared library, it must not be unloaded.
R_altlogical_Elt_method_tMust return x[i] for the 0-based index i. The
default method returns LOGICAL(x)[i].
R_altlogical_Get_region_method_tMust copy up to n elements, starting at 0-based index i,
into buf[n], and return the number of elements
copied. The default method defers to LOGICAL_ELT and hence the
Elt method above.
R_altlogical_Is_sorted_method_tMust return one of the sortedness constants: SORTED_DECR,
UNKNOWN_SORTEDNESS, SORTED_INCR.
See INTEGER_IS_SORTED. The default method always
returns UNKNOWN_SORTEDNESS.
R_altlogical_No_NA_method_tMust return 1 if x is known not to store any missing values (see LOGICAL_NO_NA), otherwise 0 (including if it’s unknown). The default method always returns 0.
R_altlogical_Sum_method_tMust calculate and return the specified summary of the contents of
x, ignoring missing values if narm is TRUE. May
return a null pointer, in which case R will compute the summary by
accessing the elements of the vector.
Versions: Appeared in 3.6.0.
Next: R_make_altcomplex_class, Previous: R_make_altlogical_class, Up: Experimental functions [Index]
#include <R_ext/Altrep.h> R_altrep_class_t R_make_altreal_class( const char *cname, const char *pname, DllInfo *info ); typedef double (*R_altreal_Elt_method_t)( SEXP x, R_xlen_t i ); void R_set_altreal_Elt_method( R_altrep_class_t cls, R_altreal_Elt_method_t fun ); typedef R_xlen_t (*R_altreal_Get_region_method_t)( SEXP x, R_xlen_t i, R_xlen_t n, double * buf ); void R_set_altreal_Get_region_method( R_altrep_class_t cls, R_altreal_Get_region_method_t fun ); typedef int (*R_altreal_Is_sorted_method_t)(SEXP x); void R_set_altreal_Is_sorted_method( R_altrep_class_t cls, R_altreal_Is_sorted_method_t fun ); typedef int (*R_altreal_No_NA_method_t)(SEXP x); void R_set_altreal_No_NA_method( R_altrep_class_t cls, R_altreal_No_NA_method_t fun ); typedef SEXP (*R_altreal_Sum_method_t)( SEXP x, Rboolean narm ); void R_set_altreal_Sum_method( R_altrep_class_t cls, R_altreal_Sum_method_t fun ); typedef SEXP (*R_altreal_Min_method_t)( SEXP x, Rboolean narm ); void R_set_altreal_Min_method( R_altrep_class_t cls, R_altreal_Min_method_t fun ); typedef SEXP (*R_altreal_Max_method_t)( SEXP x, Rboolean narm ); void R_set_altreal_Max_method( R_altrep_class_t cls, R_altreal_Max_method_t fun );
The name of the ALTREP class and the package owning it, respectively. Together they identify an ALTREP class. It is possible to have multiple classes with the same cname but different pname (and vice versa).
An opaque pointer given to the initialization routine of the shared library (see R_registerRoutines).
A class object previously returned by R_make_altreal_class.
The ALTREP value of the given class.
The 0-based index into x in range [0, XLENGTH(x)-1].
The buffer buf[n] to populate with the contents of
x.
If TRUE, ignore the missing values while computing the summary.
R_make_altreal_classAllocates, registers and returns an ALTREP class with the given names.
In addition to the methods given here, compact representation real vectors must implement the common “altrep” methods (see R_set_altrep_..._method) and the common “altvec” methods (see R_set_altvec_..._method).
R_set_altreal_Elt_methodR_set_altreal_Get_region_methodR_set_altreal_Is_sorted_methodR_set_altreal_No_NA_methodR_set_altreal_Sum_methodR_set_altreal_Min_methodR_set_altreal_Max_methodSets the function pointer inside the ALTREP class object. Behaviour is undefined if cls is not a compact real vector class. There is no facility for unregistering ALTREP classes, so once a function pointer is set from a package shared library, it must not be unloaded.
R_altreal_Elt_method_tMust return x[i] for the 0-based index i. The
default method returns REAL(x)[i].
R_altreal_Get_region_method_tMust copy up to n elements, starting at 0-based index i,
into buf[n], and return the number of elements
copied. The default method defers to REAL_ELT and hence the
Elt method above.
R_altreal_Is_sorted_method_tMust return one of the sortedness constants: SORTED_DECR,
UNKNOWN_SORTEDNESS, SORTED_INCR. See REAL_IS_SORTED.
The default method always returns UNKNOWN_SORTEDNESS.
R_altreal_No_NA_method_tMust return 1 if x is known not to store any missing values (see REAL_NO_NA), otherwise 0 (including if it’s unknown). The default method always returns 0.
R_altreal_Sum_method_tR_altreal_Min_method_tR_altreal_Max_method_tMust calculate and return the specified summary of the contents of
x, ignoring missing values if narm is TRUE. May
return a null pointer, in which case R will compute the summary by
accessing the elements of the vector.
Versions: Appeared in 3.5.0.
Next: R_make_altraw_class, Previous: R_make_altreal_class, Up: Experimental functions [Index]
#include <R_ext/Altrep.h> R_altrep_class_t R_make_altcomplex_class( const char *cname, const char *pname, DllInfo *info ); typedef Rcomplex (*R_altcomplex_Elt_method_t)( SEXP x, R_xlen_t i ); void R_set_altcomplex_Elt_method( R_altrep_class_t cls, R_altcomplex_Elt_method_t fun ); typedef R_xlen_t (*R_altcomplex_Get_region_method_t)( SEXP x, R_xlen_t i, R_xlen_t n, Rcomplex * buf ); void R_set_altcomplex_Get_region_method( R_altrep_class_t cls, R_altcomplex_Get_region_method_t fun );
The name of the ALTREP class and the package owning it, respectively. Together they identify an ALTREP class. It is possible to have multiple classes with the same cname but different pname (and vice versa).
An opaque pointer given to the initialization routine of the shared library (see R_registerRoutines).
A class object previously returned by R_make_altcomplex_class.
The ALTREP value of the given class.
The 0-based index into x in range [0, XLENGTH(x)-1].
The buffer buf[n] to populate with the contents of
x.
R_make_altcomplex_classAllocates, registers and returns an ALTREP class with the given names.
In addition to the methods given here, compact representation complex vectors must implement the common “altrep” methods (see R_set_altrep_..._method) and the common “altvec” methods (see R_set_altvec_..._method).
R_set_altcomplex_Elt_methodR_set_altcomplex_Get_region_methodSets the function pointer inside the ALTREP class object. Behaviour is undefined if cls is not a compact complex vector class. There is no facility for unregistering ALTREP classes, so once a function pointer is set from a package shared library, it must not be unloaded.
R_altcomplex_Elt_method_tMust return x[i] for the 0-based index i. The
default method returns COMPLEX(x)[i].
R_altcomplex_Get_region_method_tMust copy up to n elements, starting at 0-based index i,
into buf[n], and return the number of elements
copied. The default method defers to COMPLEX_ELT and hence the
Elt method above.
Versions: Appeared in 3.6.0.
Next: R_make_altlist_class, Previous: R_make_altcomplex_class, Up: Experimental functions [Index]
#include <R_ext/Altrep.h> R_altrep_class_t R_make_altraw_class( const char *cname, const char *pname, DllInfo *info ); typedef Rbyte (*R_altraw_Elt_method_t)( SEXP x, R_xlen_t i ); void R_set_altraw_Elt_method( R_altrep_class_t cls, R_altraw_Elt_method_t fun ); typedef R_xlen_t (*R_altraw_Get_region_method_t)( SEXP x, R_xlen_t i, R_xlen_t n, Rbyte * buf ); void R_set_altraw_Get_region_method( R_altrep_class_t cls, R_altraw_Get_region_method_t fun );
The name of the ALTREP class and the package owning it, respectively. Together they identify an ALTREP class. It is possible to have multiple classes with the same cname but different pname (and vice versa).
An opaque pointer given to the initialization routine of the shared library (see R_registerRoutines).
A class object previously returned by R_make_altraw_class.
The ALTREP value of the given class.
The 0-based index into x in range [0, XLENGTH(x)-1].
The buffer buf[n] to populate with the contents of
x.
R_make_altraw_classAllocates, registers and returns an ALTREP class with the given names.
In addition to the methods given here, compact representation complex vectors must implement the common “altrep” methods (see R_set_altrep_..._method) and the common “altvec” methods (see R_set_altvec_..._method).
R_set_altraw_Elt_methodR_set_altraw_Get_region_methodSets the function pointer inside the ALTREP class object. Behaviour is undefined if cls is not a compact complex vector class. There is no facility for unregistering ALTREP classes, so once a function pointer is set from a package shared library, it must not be unloaded.
R_altraw_Elt_method_tMust return x[i] for the 0-based index i. The
default method returns RAW(x)[i].
R_altraw_Get_region_method_tMust copy up to n elements, starting at 0-based index i,
into buf[n], and return the number of elements
copied. The default method defers to RAW_ELT and hence the
Elt method above.
Versions: Appeared in 3.6.0.
Next: R_GetX11Image, Previous: R_make_altraw_class, Up: Experimental functions [Index]
#include <R_ext/Altrep.h> R_altrep_class_t R_make_altlist_class( const char *cname, const char *pname, DllInfo *info ); typedef SEXP (*R_altlist_Elt_method_t)( SEXP x, R_xlen_t i ); void R_set_altlist_Elt_method( R_altrep_class_t cls, R_altlist_Elt_method_t fun ); typedef void (*R_altlist_Set_elt_method_t)( SEXP x, R_xlen_t i, SEXP v ); void R_set_altlist_Set_elt_method( R_altrep_class_t cls, R_altlist_Set_elt_method_t fun );
The name of the ALTREP class and the package owning it, respectively. Together they identify an ALTREP class. It is possible to have multiple classes with the same cname but different pname (and vice versa).
An opaque pointer given to the initialization routine of the shared library (see R_registerRoutines).
A class object previously returned by R_make_altlist_class.
The ALTREP value of the given class.
The 0-based index into x in range [0, XLENGTH(x)-1].
R_make_altlist_classAllocates, registers and returns an ALTREP class with the given names.
In addition to the methods given here, compact representation complex vectors must implement the common “altrep” methods (see R_set_altrep_..._method) and the common “altvec” methods (see R_set_altvec_..._method).
R_set_altlist_Elt_methodR_set_altlist_Get_region_methodSets the function pointer inside the ALTREP class object. Behaviour is undefined if cls is not a compact complex vector class. There is no facility for unregistering ALTREP classes, so once a function pointer is set from a package shared library, it must not be unloaded.
R_altlist_Elt_method_tMust return x[[i]] for the 0-based index i or
raise an error.
R_altlist_Set_elt_method_tMust set x[[i]] <- v for the 0-based index
i, altering x, or raise an error.
Versions: Appeared in 4.3.0.
Next: nlevels, Previous: R_make_altlist_class, Up: Experimental functions [Index]
/* Only available on Unix-like platforms; requires a working X11 device */ #include <R_ext/GetX11Image.h> Rboolean R_GetX11Image( int d, void * pximage, int * pwidth, int * pheight );
The number of the open graphical device.
Output variable, a pointer to a caller-owned pointer-to-XImage.
In other words,
#include <X11/Xlib.h> XImage * image; void * pximage = ℑ
Output variables, the width and the height of the graphics device, respectively.
If d is not the number of a currently open X11-backed graphics
device, returns FALSE. Otherwise calls XGetImage(),
populates the output variables with the returned XImage* and the
dimensions of the X11 window known to the device, and then returns
TRUE. If the returned XImage* is not null, the caller is
responsible for eventually deallocating it using XDestroyImage().
Versions: Appeared in 1.7.0.
See also: https://tronche.com/gui/x/xlib/utilities/manipulating-images.html.
Next: R_lsInternal3, Previous: R_GetX11Image, Up: Experimental functions [Index]
#include <Rinternals.h> int Rf_nlevels(SEXP f); #ifndef R_NO_REMAP #define nlevels Rf_nlevels #endif
An arbitrary R value.
If f is a factor (see isFactor), returns the length of
its levels attribute. Otherwise returns 0.
Next: copyListMatrix, Previous: nlevels, Up: Experimental functions [Index]
#include <Rinternals.h> SEXP R_lsInternal3( SEXP env, Rboolean all, Rboolean sorted );
An ENVEXP value.
Whether to include variable names starting with a dot.
Whether the return value must be sorted lexicographically.
Allocates and returns a STRSXP vector containing names of objects
in the environment env. The names may include those starting with
a dot and may be sorted, depending on the values of all and
sorted.
Versions: Appeared in 3.2.0.
Next: listAppend, Previous: R_lsInternal3, Up: Experimental functions [Index]
#include <Rinternals.h> void Rf_copyListMatrix( SEXP destination, SEXP source, Rboolean byrow ); #ifndef R_NO_REMAP #define copyListMatrix Rf_copyListMatrix #endif
Pairlists (of type LISTSXP or LANGSXP). destination
must have a valid two-element dim attribute.
If TRUE, fill destination with elements row by row, like
matrix(byrow = TRUE) in R. Otherwise fill it column by column,
like copyVector does for vector types.
Populates destination with duplicates (see duplicate) of
elements of source, overwriting the original contents. If
source contains less elements than destination, the rest of
the pairlist is filled with NILSXP values.
Behaviour is unspecified if byrow is TRUE and source
contains something other than CHARSXP
values6.
Next: isVectorizable, Previous: copyListMatrix, Up: Experimental functions [Index]
#include <Rinternals.h> SEXP Rf_listAppend( SEXP destination, SEXP source ); #ifndef R_NO_REMAP #define listAppend Rf_listAppend #endif
Pairlist objects (of type LISTSXP, LANGSXP, or
NILSXP).
Destructively concatenates source at the end of destination, overwriting the tail pair of the latter, and returns destination. The content of destination is shared with source without duplication.
If destination is a NILSXP, returns source.
Next: PairToVectorList, Previous: listAppend, Up: Experimental functions [Index]
#include <Rinternals.h> Rboolean Rf_isVectorizable(SEXP s); #ifndef R_NO_REMAP #define isVectorizable Rf_isVectorizable #endif
An arbitrary R value.
Returns TRUE if s is a VECSXP list or a pairlist
(see isPairList), every element of which is an atomic or
recursive vector (see isVector) of length no more than one.
Also returns TRUE for empty lists of such type. Otherwise
returns FALSE.
Next: R_existsVarInFrame, Previous: isVectorizable, Up: Experimental functions [Index]
#include <Rinternals.h> SEXP Rf_PairToVectorList(SEXP p); #ifndef R_NO_REMAP #define PairToVectorList Rf_PairToVectorList #endif SEXP Rf_VectorToPairList(SEXP v); #ifndef R_NO_REMAP #define VectorToPairList Rf_VectorToPairList #endif
A pairlist object (see isPairList).
A vector list object (see isVectorList).
Rf_PairToVectorListAllocates a VECSXP list, populates it with the elements of
p, and returns it. If any of the pairs are named, the names
attribute of the return value is populated with their TAG()
values (empty strings for those of them that are unset). “Most”
attributes are copied from p too (see copyMostAttrib).
Rf_VectorToPairListAllocates a LISTSXP list, populates it with the elements of
v, and returns it. TAG() values are set from the non-empty
elements of the names attribute of v. Unless the list is
empty (and therefore the return value is a NILSXP), “most”
attributes are copied from v (see copyMostAttrib).
Signals an R-level error if v is too long (see allocList).
Next: R_PackageEnvName, Previous: PairToVectorList, Up: Experimental functions [Index]
#include <Rinternals.h> Rboolean R_existsVarInFrame( SEXP env, SEXP name ); void R_removeVarFromFrame( SEXP name, SEXP env );
An ENVSXP value.
A SYMSXP value.
R_existsVarInFrameReturns TRUE if a binding for name exists in env,
otherwise FALSE.
Versions: Appeared in 4.2.0.
R_removeVarFromFrameIf a binding for name exists in env, removes it. Signals an R-level error if env is locked, is the base namespace, the base environment, or the empty environment.
Versions: Appeared in 4.1.0.
Next: R_FindNamespace, Previous: R_existsVarInFrame, Up: Experimental functions [Index]
#include <Rinternals.h> SEXP R_PackageEnvName(SEXP rho); Rboolean R_IsPackageEnv(SEXP rho);
An ENVSXP value.
R_IsPackageEnvReturns TRUE if rho is an environment and has a name
starting with ‘package:’. Such environments contain the exports
from a package, as opposed to package namespaces
(see R_FindNamespace).
R_PackageEnvNameIf R_IsPackageEnv(rho) is TRUE, returns the
STRSXP value containing the name of the environment. Otherwise
returns a NILSXP.
Next: psmatch, Previous: R_PackageEnvName, Up: Experimental functions [Index]
#include <Rinternals.h> SEXP R_FindNamespace(SEXP info); SEXP R_NamespaceEnvSpec(SEXP rho); Rboolean R_IsNamespaceEnv(SEXP rho);
A one-element STRSXP vector containing the name of the package.
An ENVSXP value.
R_FindNamespaceReturns the namespace environment of the package named info, or
signals an R-level error if the package could not be loaded. Behaviour
is unspecified if a function named getNamespace shadows the
base::getNamespace in the global
environment7.
R_NamespaceEnvSpecIf rho is a package namespace, returns its “spec”, which is a
character vector; its first element is the name of the namespace and its
second element is the version. Otherwise returns a NILSXP.
R_IsNamespaceEnvReturns TRUE if rho is a namespace environment. Such
environments contain all of the results of evaluation of the package
source code, not just the exported objects (see R_PackageEnvName).
Next: charIsUTF8, Previous: R_FindNamespace, Up: Experimental functions [Index]
#include <Rinternals.h> Rboolean Rf_psmatch( const char * formal, const char * tag, Rboolean exact ); #ifndef R_NO_REMAP #define psmatch Rf_psmatch #endif Rboolean Rf_pmatch( SEXP formal, SEXP tag, Rboolean exact ); #ifndef R_NO_REMAP #define pmatch Rf_pmatch #endif SEXP Rf_match( SEXP itable, SEXP ix, int nmatch ); #ifndef R_NO_REMAP #define match Rf_match #endif
The two strings to compare. For pmatch, can be SYMSXP,
CHARSXP, or 1-element STRSXP objects.
Whether the strings formal and tag must match exactly. If
FALSE, tag can be a prefix of formal.
A vector of values to find matches against.
A vector of values to find matches for.
The value to return for non-matching values.
psmatchpmatchReturns TRUE if tag matches formal, subject to the
exact argument; otherwise returns FALSE.
matchCoerces ix and itable to a common SEXPTYPE (see
help('<') for the order of type preference). For objects, calls
their mtfrm method first. Returns an INTSXP vector of the
same length as ix containing the 1-based indices of elements in
itable matching the corresponding element in ix. For
elements of ix that were not found in itable, nmatch
is returned.
Next: R_forceAndCall, Previous: psmatch, Up: Experimental functions [Index]
#include <Rinternals.h> Rboolean Rf_charIsASCII(SEXP x); #ifndef R_NO_REMAP #define charIsASCII Rf_charIsASCII #endif Rboolean Rf_charIsUTF8(SEXP x); #ifndef R_NO_REMAP #define charIsUTF8 Rf_charIsUTF8 #endif Rboolean Rf_charIsLatin1(SEXP x); #ifndef R_NO_REMAP #define charIsLatin1 Rf_charIsLatin1 #endif
A CHARSXP object.
These function return TRUE if x can be considered to be in
their respective encodings, FALSE otherwise. This is not as
simple as checking getCharCE(x)
(see getCharCE): a string can also be in UTF-8 if it’s
marked in the native encoding, but the locale encoding is also UTF-8.
See translateChar for access to string contents in a guaranteed
encoding.
Versions: Appeared in 4.5.0.
Next: isUnsorted, Previous: charIsUTF8, Up: Experimental functions [Index]
#include <Rinternals.h> SEXP R_forceAndCall( SEXP e, int n, SEXP rho );
A LANGSXP call.
The number of leading arguments to force.
The environment in which to evaluate e, an ENVSXP.
Evaluates CAR(e) and finds out its type. If the function to
call is a SPECIALSXP or a BUILTINSXP, evaluates the call
as usual. Otherwise the function must be a CLOSXP: the first
n arguments passed to it are evaluated right away (their promises
forced). Then the evaluation of the call proceeds normally.
Returns the result of the evaluated call. e is left unchanged.
Versions: Appeared in 3.2.0.
Next: Rf_ucstoutf8, Previous: R_forceAndCall, Up: Experimental functions [Index]
#include <Rinternals.h> Rboolean Rf_isUnsorted( SEXP x, Rboolean strictly ); #ifndef R_NO_REMAP #define isUnsorted Rf_isUnsorted #endif
An atomic vector (see isVectorAtomic).
Whether the comparison must be strict, i.e., not include equality.
Returns TRUE if x[i] >= x[i+1]
(strictly = TRUE) or x[i] > x[i+1]
(strictly = FALSE) for any applicable i. Avoids
materialising an ALTREP object. Vectors of length less than 2 are
considered unsorted.
Previous: isUnsorted, Up: Experimental functions [Index]
#include <R_ext/GraphicsEngine.h> void * Rf_AdobeSymbol2utf8( char * out, const char * in, size_t nwork, Rboolean usePUA ); #define AdobeSymbol2utf8 Rf_AdobeSymbol2utf8 int Rf_utf8toAdobeSymbol( char * out, const char * in ); #define utf8toAdobeSymbol Rf_utf82AdobeSymbol const char * Rf_utf8Toutf8NoPUA(const char * in); #define utf8Toutf8NoPUA Rf_utf8Toutf8NoPUA const char * Rf_utf8ToLatin1AdobeSymbol2utf8( const char * in, Rboolean usePUA ); #define utf8ToLatin1AdobeSymbol2utf8 Rf_utf8ToLatin1AdobeSymbol2utf8 size_t Rf_ucstoutf8(char *s, const unsigned int c);
The output buffer.
The input buffer.
The size of the output buffer. Must be at least 3*strlen(in)
+ 1.
Whether to use Private Use Area code points, expecting a specialised Symbol font, to represent the Adobe Symbol characters unavailable in regular Unicode.
Output variable, a buffer with enough space for one Unicode code point represented in UTF-8 followed by the terminating NUL byte.
The number of a Unicode code point.
Rf_AdobeSymbol2utf8Converts the Adobe Symbol-encoded text from in into UTF-8 and
writes it into out[nwork]. If there is not enough
space in the buffer for the first character plus the 0-terminator,
behaviour is undefined, but the function is intended to silently
truncate the output on a code point boundary.
Returns out.
Versions: Appeared in 4.1.0.
Rf_utf8toAdobeSymbolPerforms the inverse operation to Rf_AdobeSymbol2utf8(in,
out, in_length, TRUE): reads the UTF-8-encoded text in in
and writes its representation in the Adobe Symbol encoding into
out, assuming that it uses the PUA characters for Symbol fonts.
Returns the length of the string, excluding the final terminator,
written into out.
Signals an error if in contains invalid UTF-8 or cannot be represented in the Adobe Symbol encoding.
See vmaxset, for management of the temporary buffer.
Versions: Appeared in 4.1.0.
Rf_utf8Toutf8NoPUAReads the result of Rf_AdobeSymbol2utf8(in, out,
in_length, TRUE) from in and returns a new UTF-8-encoded string
containing the PUA code points replaced by best-fit non-PUA code points.
See vmaxset, for management of the returned buffer.
May signal an error if in contains valid UTF-8 that did not
originate from Rf_AdobeSymbol2utf8. If in contains invalid
UTF-8, behaviour is undefined.
Versions: Appeared in 4.1.0.
Rf_utf8ToLatin1AdobeSymbol2utf8Converts the contents of in from UTF-8 into Latin-1 using a
temporary buffer, substituting ‘.’ for non-representable
characters. Interprets the result of the conversion as Adobe Symbol by
calling Rf_AdobeSymbol2utf8 on an another temporary buffer and
returns the result.
See vmaxset, for management of the temporary buffers.
Versions: Appeared in 4.1.0.
Rf_ucstoutf8Converts the given Unicode code point into UTF-8 and writes the result into s, followed by a NUL byte. Returns the length of the string (not counting the terminator) written into s.
Will signal an error on conversion problems (see Riconv).
Versions: Appeared in 2.7.0.
Next: Self-test results, Previous: Experimental functions, Up: Introduction [Index]
| Jump to: | R |
|---|
| Jump to: | R |
|---|
Next: Experimental API, Previous: Headers, Up: Indices [Index]
Next: Variables and constants, Up: API [Index]
| Jump to: | A B C D E F G I L M N O P Q R S T U V W X |
|---|
| Jump to: | A B C D E F G I L M N O P Q R S T U V W X |
|---|
| Jump to: | A B C D E F I L M N O P R S T V W Y |
|---|
| Jump to: | A B C D E F I L M N O P R S T V W Y |
|---|
Next: Constants, Up: Experimental API [Index]
| Jump to: | A B C D E F G H I L M N P R S U V |
|---|
| Jump to: | A B C D E F G H I L M N P R S U V |
|---|
Previous: Functions, Up: Experimental API [Index]
| Jump to: | I R S U |
|---|
| Jump to: | I R S U |
|---|
Previous: Indices, Up: Introduction [Index]
Number of matching entries of class api: 334 Extraneous entries of class api: [1] "rwilcox" Undocumented entries of class api: [1] "bessel_i" "bessel_j" "bessel_k" "bessel_y" [5] "beta" "choose" "cospi" "digamma" [9] "dpsifn" "expm1" "findInterval" "findInterval2" [13] "fmax2" "fmin2" "fprec" "fround" [17] "fsign" "ftrunc" "gammafn" "imax2" [21] "imin2" "interv" "lbeta" "lchoose" [25] "lgamma1p" "lgammafn" "log1mexp" "log1p" [29] "log1pexp" "log1pmx" "logspace_add" "logspace_sub" [33] "logspace_sum" "pentagamma" "pow1p" "psigamma" [37] "qsort3" "qsort4" "R_max_col" "R_pow" [41] "R_pow_di" "Rtanpi" "sign" "signrank_free" [45] "sinpi" "tanpi" "tetragamma" "trigamma" Number of matching entries of class eapi: 137 Undocumented entries of class eapi: [1] "col2name" "CreateAtVector" [3] "curDevice" "desc2GEDesc" [5] "doesIdle" "doIdle" [7] "doKeybd" "doMouseEvent" [9] "GAxisPars" "GE_LENDget" [11] "GE_LENDpar" "GE_LJOINget" [13] "GE_LJOINpar" "GE_LTYget" [15] "GE_LTYpar" "GEaddDevice" [17] "GEaddDevice2" "GEaddDevice2f" [19] "GECap" "GEcheckState" [21] "GECircle" "GEcontourLines" [23] "GEcopyDisplayList" "GEcreateDevDesc" [25] "GEcreateSnapshot" "GEcurrentDevice" [27] "GEdestroyDevDesc" "GEdeviceDirty" [29] "GEdeviceNumber" "GEdirtyDevice" [31] "GEExpressionHeight" "GEExpressionMetric" [33] "GEExpressionWidth" "GEFill" [35] "GEFillStroke" "GEfromDeviceHeight" [37] "GEfromDeviceWidth" "GEfromDeviceX" [39] "GEfromDeviceY" "GEgetDevice" [41] "GEGlyph" "GEhandleEvent" [43] "GEinitDisplayList" "GEkillDevice" [45] "GELine" "GEMathText" [47] "GEMetricInfo" "GEMode" [49] "GENewPage" "GEnullDevice" [51] "GEonExit" "GEPath" [53] "GEplayDisplayList" "GEplaySnapshot" [55] "GEPolygon" "GEPolyline" [57] "GEPretty" "GERaster" [59] "GErecordGraphicOperation" "GErecording" [61] "GERect" "GEregisterSystem" [63] "GEregisterWithDevice" "GESetClip" [65] "GEStrHeight" "GEstring_to_pch" [67] "GEStrMetric" "GEStroke" [69] "GEStrWidth" "GESymbol" [71] "GEsystemState" "GEText" [73] "GEtoDeviceHeight" "GEtoDeviceWidth" [75] "GEtoDeviceX" "GEtoDeviceY" [77] "GEunregisterSystem" "GEXspline" [79] "killDevice" "ndevNumber" [81] "NewFrameConfirm" "nextDevice" [83] "NoDevices" "NumDevices" [85] "prevDevice" "R_CheckDeviceAvailable" [87] "R_CheckDeviceAvailableBool" "R_GE_checkVersionOrDie" [89] "R_GE_clipPathFillRule" "R_GE_getVersion" [91] "R_GE_glyphColour" "R_GE_glyphFont" [93] "R_GE_glyphFontFamily" "R_GE_glyphFontFile" [95] "R_GE_glyphFontIndex" "R_GE_glyphFontPSname" [97] "R_GE_glyphFontStyle" "R_GE_glyphFontWeight" [99] "R_GE_glyphID" "R_GE_glyphInfoFonts" [101] "R_GE_glyphInfoGlyphs" "R_GE_glyphRotation" [103] "R_GE_glyphSize" "R_GE_glyphX" [105] "R_GE_glyphY" "R_GE_hasGlyphRotation" [107] "R_GE_isPattern" "R_GE_linearGradientColour" [109] "R_GE_linearGradientExtend" "R_GE_linearGradientNumStops" [111] "R_GE_linearGradientStop" "R_GE_linearGradientX1" [113] "R_GE_linearGradientX2" "R_GE_linearGradientY1" [115] "R_GE_linearGradientY2" "R_GE_maskType" [117] "R_GE_patternType" "R_GE_radialGradientColour" [119] "R_GE_radialGradientCX1" "R_GE_radialGradientCX2" [121] "R_GE_radialGradientCY1" "R_GE_radialGradientCY2" [123] "R_GE_radialGradientExtend" "R_GE_radialGradientNumStops" [125] "R_GE_radialGradientR1" "R_GE_radialGradientR2" [127] "R_GE_radialGradientStop" "R_GE_rasterInterpolate" [129] "R_GE_rasterResizeForRotation" "R_GE_rasterRotate" [131] "R_GE_rasterRotatedOffset" "R_GE_rasterRotatedSize" [133] "R_GE_rasterScale" "R_GE_str2col" [135] "R_GE_tilingPatternExtend" "R_GE_tilingPatternFunction" [137] "R_GE_tilingPatternHeight" "R_GE_tilingPatternWidth" [139] "R_GE_tilingPatternX" "R_GE_tilingPatternY" [141] "R_GE_VStrHeight" "R_GE_VStrWidth" [143] "R_GE_VText" "RGBpar" [145] "RGBpar3" "selectDevice" R Under development (unstable) (2024-10-10 r87218)
https://stat.ethz.ch/pipermail/r-help/2024-July/479719.html
https://bugs.r-project.org/show_bug.cgi?id=18748
https://bugs.r-project.org/show_bug.cgi?id=17599
https://bugs.r-project.org/show_bug.cgi?id=18805
https://bugs.r-project.org/show_bug.cgi?id=18794
https://bugs.r-project.org/show_bug.cgi?id=18775