Internal API

AnySxp <: Sxp

Representation of R "any" object (comparable to Ref{Any}).

This corresponds to type tag 18.

Fields

• head::SxpHead

" BcodeSxp <: Sxp

Representation of R byte code.

This corresponds to type tag 21.

Fields

• head::SxpHead

BuiltinSxp <: FunctionSxp

Representation of R built-in function.

This corresponds to type tag 8.

Fields

• head::SxpHead

CharSxp <: VectorAtomicSxp

Representation of R character string.

This corresponds to type tag 9.

Fields

• head::SxpHead
• length::Cint
• truelength::Cint

ClosSxp <: FunctionSxp

Representation of R function closure.

This corresponds to R type tag 3.

Fields

• head::SxpHead
• formals::Ptr{ListSxp}
• body::Ptr{UnknownSxp}
• env::Ptr{UnknownSxp}

CplxSxp <: VectorNumericSxp

Representation of R complex vector.

This corresponds to type tag 15.

Fields

• head::SxpHead
• length::Cint
• truelength::Cint

DotSxp <: Sxp

Representation of R dot-dot-dot object.

This corresponds to type tag 17.

Fields

• head::SxpHead

EnvSxp <: Sxp

Representation of R environment.

This corresponds to type tag 4.

Fields

• head::SxpHead
• frame::Ptr{UnknownSxp}
• enclos::Ptr{UnknownSxp}
• hashtab::Ptr{UnknownSxp}

ExprSxp <: VectorListSxp

Representation of R expression vector.

This corresponds to type tag 20.

Fields

• head::SxpHead
• length::Cint
• truelength::Cint

ExtPtrSxp <: Sxp

Representation of R external pointer.

This corresponds to type tag 22.

Fields

• head::SxpHead
• ptr::Ptr{Cvoid}
• prot::Ptr{Cvoid}
• tag::Ptr{UnknownSxp}

" IntSxp <: VectorNumericSxp

Representation of R integer vector.

This corresponds to type tag 13.

Fields

• head::SxpHead
• length::Cint
• truelength::Cint

LangSxp <: PairListSxp

Representation of R function call.

This corresponds to type tag 6.

Fields

• head::SxpHead
• car::Ptr{UnknownSxp}
• cdr::Ptr{UnknownSxp}
• tag::Ptr{UnknownSxp}

LglSxp <: VectorNumericSxp

Representation of R logical vector.

This corresponds to type tag 10.

Fields

• head::SxpHead
• length::Cint
• truelength::Cint

ListSxp <: PairListSxp

Representation of R pairs (cons) list cell.

This corresponds to R type tag 2.

Fields

• head::SxpHead
• car::Ptr{UnknownSxp}
• cdr::Ptr{UnknownSxp}
• tag::Ptr{UnknownSxp}

NilSxpR <: PairListSxp

Representation of R NULL value.

This corresponds to R type tag 0.

Fields

• head::SxpHead

PromSxp <: Sxp

Representation of R promise.

This corresponds to type tag 5.

Fields

• head::SxpHead
• value::Ptr{UnknownSxp}
• expr::Ptr{UnknownSxp}
• env::Ptr{UnknownSxp}

RClass{Symbol}

Representation of R Class.

Examples:

• RCall{:logical}
• RCall{:integer}
• RCall{:numeric}
• RCall{:character}

RObject{S<:Sxp}

An RObject is a Julia wrapper for an R object (known as an "S-expression", i.e. SEXP). It is stored as a pointer which is protected from the R garbage collector, until the RObject itself is finalized by Julia. The parameter is the type of the S-expression.

When called with a Julia object as an argument, a corresponding R object is constructed.

Examples

julia> RObject(1)
RObject{IntSxp}
[1] 1

julia> RObject(1:3)
RObject{IntSxp}
[1] 1 2 3

julia> RObject(1.0:3.0)
RObject{RealSxp}
[1] 1 2 3

Fields

• p::Ptr{S} Pointer to the relevant R object.

RawSxp <: VectorAtomicSxp

Representation of R byte vector.

This corresponds to type tag 24.

Fields

• head::SxpHead
• length::Cint
• truelength::Cint

RealSxp <: VectorNumericSxp

Representation of R real (numeric) vector.

This correponds to type tag 14.

Fields

• head::SxpHead
• length::Cint
• truelength::Cint

S4Sxp <: Sxp

Representation of R S4 object.

This corresponds to type tag 24.

Fields

• head::SxpHead

SpecialSxp <: FunctionSxp

Representation of R special function.

This corresponds to type tag 7.

Fields

• head::SxpHead

StrSxp <: VectorListSxp

Representation of R vector of character strings.

This correponds to type tag 16.

Fields

• head::SxpHead
• length::Cint
• truelength::Cint

Sxp

Representation of R symbolic expression record SEXPREC in R API.

These are represented by a pointer Ptr{S<:Sxp} (which is called SEXP in R API).

See also R internals documentation

SxpHead <: Sxp

R Sxp header (SEXPREC_HEADER).

A pointer to this is used for unknown types.

Fields

• info::SxpPtrInfo
• attrib::Ptr{Cvoid}
• gc_next::Ptr{Cvoid}
• gc_prev::Ptr{Cvoid}

SxpPtrInfo

Representation of sxpinfo_struct.

SymSxp <: Sxp

Representation of R symbol.

This corresponds to type tag 1.

Fields

• head::SxpHead
• name::Ptr{CharSxp}
• value::Ptr{UnknownSxp}
• internal::Ptr{UnknownSxp}

SxpHead <: Sxp

R Sxp header (SEXPREC_HEADER).

A pointer to this is used for unknown types.

Fields

• info::SxpPtrInfo
• attrib::Ptr{Cvoid}
• gc_next::Ptr{Cvoid}
• gc_prev::Ptr{Cvoid}

VecSxp <: VectorListSxp

Representation of R list (i.e. Array{Any,1}).

This corresponds to type tag 19.

Fields

• head::SxpHead
• length::Cint
• truelength::Cint

WeakRefSxp <: Sxp

Representation of R weak reference.

This corresponds to type tag 23.

Fields

• head::SxpHead
• length::Cint
• truelength::Cint

extract the value of symbol s in the environment e

extract an element from a S4Sxp by label

extract an element from a PairListSxp by label

Set element of a VectorSxp by a label.

extract the i-th element of a PairListSxp

Determines the encoding of the CharSxp. This is determined by the 'gp' part of the sxpinfo (this is the middle 16 bits).

• 0x00000200 (bit 1): set of bytes (no known encoding)
• 0x00000400 (bit 2): Latin-1
• 0x00000800 (bit 3): UTF-8
• 0x00004000 (bit 6): ASCII

We only support ASCII and UTF-8.

Sxp methods for length return the R length.

Rf_xlength handles Sxps that are not vector-like and R's "long vectors", which have a negative value for the length member.

Returns the names of an R vector, the result is converted to a Julia symbol array.

assign value v to symbol s in the environment e

extract an element from a S4Sxp by label

Set element of a PairListSxp by a label.

Set element of a VectorSxp by a label.

assign value v to the i-th element of a PairListSxp

Returns the size of an R object.

Check if there are any NA values in the vector.

The R NAMED property, represented by 2 bits in the info field. This can take values 0,1 or 2, corresponding to whether it is bound to 0,1 or 2 or more symbols. See http://cran.r-project.org/doc/manuals/r-patched/R-exts.html#Named-objects-and-copying

decref_extptr(p::Ptr{ExtPtrSxp})

Called by the R finalizer to remove p from JULIA_TYPES_EXT_PTRS

endEmbeddedR()

Close embedded R session.

find namespace by name of the namespace, it is not error tolerant.

get namespace by name of the namespace. It is safer to be used than findNamespace as it checks bound.

Get the R parser error msg for the previous parsing result.

Return a particular attribute of an RObject

Returns the class of an R object.

Returns the names of an R vector.

ijulia_cleanup()

Clean up R display device and temporary files after error.

ijulia_displayfile(m::MIME, f)

Display a graphics file in IJulia.

This function generally should not be called by the user, but instead by the appropriate display hook.

See also ijulia_setdevice.

ijulia_displayplots()

Closes graphics device and displays files in notebook.

This is a postexecution hook called by IJulia after cell evaluation and should generally not be called by the user.

ijulia_init()

Initialize RCall's IJulia support.

ijulia_setdevice(m::MIME; kwargs...)
ijulia_setdevice(m::MIME"image/png"; width=6*72, height=5*72)
ijulia_setdevice(m::MIME"image/svg+xml"; width=6, height=5)

Set options for R plotting with IJulia.

The first argument should be a MIME object: currently supported are

• MIME("image/png") [default]
• MIME("image/svg+xml")

The keyword arguments are forwarded to the appropriate R graphics device: see the relevant R help for details.

initEmbeddedR()

This initializes an embedded R session. It should only be called when R is not already running (e.g. if Julia is running inside an R session)

Check if a value corresponds to R's sentinel NA values. These function should not be exported.

Check if the ith member of s correspond to R's NA values.

Check if the members of a vector are NA values. Always return a BitArray.

Check if values correspond to R's NULL object.

julia_extptr_callback(p::Ptr{ListSxp})

The function called by R .External for Julia callbacks.

The argument should be a Ptr{ListSxp} containing

• a pointer to the function itself (Ptr{ExtPtrSxp})
• a pointer to the Julia function (Ptr{ExtPtrSxp})
• any arguments (as Ptr{S<:Sxp})

Returns Ptr{UnknownSxp} to the result.

makeExternalPtr(ptr::Ptr{Cvoid},
                tag=Const.NilValue,
                prot=Const.NilValue)

Create an Ptr{ExtPtrSxp} object.

makeNativeSymbolRef(fptr::Ptr{Cvoid})

Register a function pointer as an R NativeSymbol.

NA element for each R base class

newEnvironment([env])

Create a new environment which extends environment env (globalEnv by default).

A pure julia wrapper of R_ParseVector

polled_events()::Cvoid

Event Callback: allows R to process Julia events when R is busy. For example, writing output to stdout while running an expensive R command.

See Writing R Extensions: Calling R.dll directly and Writing R Extensions: Meshing Event Loops

Prepare code for evaluating the julia expressions. When the code is evaluated, the results are stored in the R environment #JL.

preserve(p::Ptr{<:Sxp})

Prevent garbage collection of an R object.

Object can be released via release.

This is slower than protect, as it requires searching an internal list, but more flexible.

protect(p::Ptr{<:Sxp})

Stack-based protection of garbage collection of R objects.

Objects are released via unprotect. Returns the same pointer, allowing inline use.

This is faster than preserve, but more restrictive. Really only useful inside functions, where you can control the unprotect step.

Evaluate a function in the global environment. The first argument corresponds to the function to be called. It can be either a FunctionSxp type, a SymSxp or a Symbol.

Evaluate a function in the global environment. The first argument corresponds to the function to be called. It can be either a FunctionSxp type, a SymSxp or a Symbol.

rcopy(r) copies the contents of an R object into a corresponding canonical Julia type.

rdevicename(::MIME"image/png")
rdevicename(::MIME"image/svg+xml")

Return the name of the associated R device as a symbol.

See also ijulia_setdevice.

read_console

R_ReadConsole API callback to read input.

See Writing R extensions: Setting R callbacks

registerCFinalizerEx(s::Ptr{ExtPtrSxp})

Register finalizer to be called by the R GC.

release(p::Ptr{<:Sxp})
release(p::RObject{<:Sxp})

Release object that has been GC protected by preserve.

Render an inline R script, substituting invalid dollar signs ($) for Julia symbols

Evaluate an R symbol or language object (i.e. a function call) in an R try/catch block, returning an RObject.

Evaluate an R expression array iteratively. If throw_error is false, the error message and warning will be thrown to stderr.

Evaluate an R symbol or language object (i.e. a function call) in an R try/catch block, returning a Sxp pointer.

Import an R package as a julia module. Sanitizes the imported symbols by default, because otherwise certain symbols cannot be used.

E.g.: PerformanceAnalytics::charts.Bar in R becomes PerformanceAnalytics.charts_Bar in Julia

gg = rimport("ggplot2")

normalization is passed directly to replace via splatting.

Create a function call from a function pointer and a list of arguments and return it as an RObject, which can then be evaluated

Create a function call from a list of arguments

robject(x) converts a Julia object x to a corresponding RObject implicitly. Explicit conversions could be called with robject(<R Class>, x).

Parse a string as an R expression, returning an RObject.

Parse a string as an R expression, returning a Sxp pointer.

Print the value of an Sxp using R's printing mechanism

RParseVector wrapped by RtryCatchError. It catches possible R's stop calls which may cause longjmp in C.

See Writing R Extensions: Condition handling and cleanup code

set_last_value(s::Ptr{<:Sxp})

Set the variable .Last.value to a given value

Set a particular attribute of an RObject

Set the class of an R object.

Set the names of an R vector.

setup_callbacks()

Initialize JULIA_CALLBACK

sexp(x) converts a Julia object x to a pointer to a corresponding Sxp Object.

sexp(p::Ptr{UnknownSxp})

Return a restrictively parameterized Ptr{<:Sxp} pointing to the same object as p.

sexp(::Type{RClass{:externalptr}}, j::Any)

Wrap a Julia object in a R Ptr{ExtPtrSxp}.

We store the pointer and the object in JULIA_TYPES_EXT_PTRS to protect it from Julia's GC.

sexp(::Type{RClass{:function}}, f)

Wrap a callable Julia object f in a R ClosSxpPtr.

Constructs the following R code

function(...) .External(JULIA_CALLBACK, fExPtr, ...)

sexp(::Type{<:Sxp}, s::RObject{<:Sxp})

Return the associated Sxp pointer.

sexp_arglist_dots(args...; kwargs...)

Create an argument list for an R function call, with a varargs "dots" at the end.

sexpnum(s::Sxp)
sexpnum(p::Ptr{<:Sxp})

Return the SEXPTYPE number, i.e. type tag, of a Sxp.

Determined from the trailing 5 bits of the first 32-bit word. Is a 0-based index into the info field of a SxpHead.

A pure julia wrapper of R_tryEval.

unprotect(n)

Release last n objects GC-protected by protect.

unsafe_array(r::RObject{S})
unsafe_array(s::Ptr{S})

The same as unsafe_vec, except returns an appropriately sized array.

unsafe_vec(r::RObject{<:VectorSxp})
unsafe_vec(s::Ptr{S})

Represent the contents of a VectorSxp type as a Vector.

This does not copy the contents. If the argument is not named (in R) or otherwise protected from R's garbage collection (e.g. by keeping the containing RObject in scope) the contents of this vector can be modified or could cause a memory error when accessed.

In the special case that the R vector is empty, then an empty vector is allocated on the Julia end. This is necessary as of R 4.5 to avoid issues with pointer alignment and an optimization for empty vectors on the R end.

The contents are as stored in R. Missing values (NA's) are represented in R by sentinels. Missing data values in RealSxp and CplxSxp show up as NaN and NaN + NaNim, respectively. Missing data in IntSxp show up as -2147483648, the minimum 32-bit integer value. Internally a LglSxp is represented as Vector{Int32}. The convention is that 0 is false, -2147483648 is NA and all other values represent true.

validate_libR(libR)

Checks that the R library libR can be loaded and is satisfies version requirements.

write_console_ex(buf::Ptr{UInt8},buflen::Cint,otype::Cint)::Cvoid

R_WriteConsoleEx API callback to write console output.

otype specifies the output type (regular output or warning/error).

See Writing R extensions: Setting R callbacks

R"..."

An inline R expression, the result of which is evaluated and returned as an RObject.

It supports substitution of Julia variables and expressions via prefix with $ whenever not valid R syntax (i.e. when not immediately following another completed R expression):

R"glm(Sepal.Length ~ Sepal.Width, data=$iris)"

It is also possible to pass Julia expressions:

R"plot(#54)"

All such Julia expressions are evaluated once, before the R expression is evaluated.

The expression does not support assigning to Julia variables, so the only way to retrieve values from R is via the return value.

@rget(args...)

Copy variable(s) from R to Julia using the same name.

Import an R Package as a Julia module. For example,

@rimport ggplot2

is equivalent to ggplot2 = rimport("ggplot2") with error checking.

You can also use classic Python syntax to make an alias: @rimport *package-name* as *shorthand*

@rimport ggplot2 as gg

which is equivalent to gg = rimport("ggplot2").

@rlibrary(package)

Load an R package as if it were a Julia package, bringing all exported bindings into scope.

More or less equivalent to:

__temp__ = rimport("ggplot2")
using .__temp__

@rput(args...)

Copy variable(s) from Julia to R using the same name.

JULIA_CALLBACK

RObject containing an ExtPtrSxp to the Julia callback.

JULIA_TYPES_EXT_PTRS

Julia types (typically functions) which are wrapped in Ptr{ExtPtrSxp} are stored here to prevent garbage collection by Julia.

SXP_TYPES

Ordered collection of R SEXP types, so that the (index - 1) matches the type tag.

R global Environment.

globalEnv[:x] = 1
globalEnv[:x]

jtypExtPtrs

Deprecated alias for JULIA_TYPES_EXT_PTRS