CXXR (C++ R) API
Namespaces | Classes | Typedefs | Functions | Variables
CXXR Namespace Reference

Namespace for the CXXR project. More...

Namespaces

namespace  ElementTraits
 Namespace encapsulating traits of R vector element types.
namespace  VectorOps
 Services to support common operations on R vectors and arrays.

Classes

class  Allocator
 STL-compatible allocator front-ending CXXR::MemoryBank. More...
class  ArgList
 Class encapsulating the argument list of a FunctionBase. More...
class  ArgMatcher
 Class to match formal and supplied arguments. More...
class  BuiltInFunction
 R function implemented within the interpreter. More...
class  CachedString
 String object held in a cache. More...
class  CellPool
 Class to manage a pool of memory cells of a fixed size. More...
class  Closure
 Class representing a functional programming closure. More...
class  CommandChronicle
 Record of bindings read by top-level command. More...
struct  Complex
 CXXR's extension of CR's Rcomplex. More...
class  ConsCell
 Element of a singly linked list. More...
class  PairList
 Singly linked list of pairs. More...
class  DotInternalTable
 Table of functions invoked via .Internal(). More...
class  DumbVector
 Vector of 'plain old data'. More...
class  Environment
 Mapping from Symbols to R objects. More...
class  Evaluator
 Framework for R command evaluation. More...
class  Expression
 Singly linked list representing an R expression. More...
class  ExternalPointer
 External pointer. More...
class  FixedVector
 R data vector primarily intended for fixed-size use. More...
class  Frame
 Mapping from Symbols to R objects. More...
class  FunctionBase
 Base class for function types. More...
class  GCEdgeBase
 Untemplated base class for GCEdge. More...
class  GCEdge
 Directed edge in the graph whose nodes are GCNode objects. More...
class  GCNode
 Base class for objects managed by the garbage collector. More...
class  GCRootBase
 Untemplated base class for GCRoot. More...
class  GCRoot
 Smart pointer to protect a GCNode from garbage collection. More...
class  GCStackRootBase
 Untemplated base class for GCStackRoot. More...
class  GCStackRoot
 Smart pointer to protect a GCNode from garbage collection. More...
class  HandleVector
 Vector of RObject::Handle smart pointers. More...
class  HeterogeneousListBase
 Untemplated base class for HeterogeneousList. More...
class  HeterogeneousList
 Doubly-linked list of objects derived from a class Node. More...
class  MemoryBank
 Class to manage memory allocation and deallocation for CXXR. More...
class  NAAugment
 Class template to augment a type with 'not available'. More...
class  NodeStack
 Class implementing a stack of RObject*. More...
class  Promise
 Mechanism for deferred evaluation. More...
class  ProtectStack
 Class implementing CR's 'pointer protection stack'. More...
class  Provenance
 Provenance of a Frame::Binding state. More...
class  RAllocStack
 Class for implementing R_alloc() and kindred functions. More...
class  RHandle
 Smart pointer used to control the copying of RObjects. More...
class  RObject
 Replacement for CR's SEXPREC. More...
class  S11nScope
 Class providing supplementary information for serialization. More...
class  S4Object
 S4 object. More...
class  SchwarzCounter
 Schwarz counter. More...
class  StdFrame
 General-purpose implementation of CXXR::Frame. More...
class  String
 RObject representing a character string. More...
class  Subscripting
 Services to support R subscripting operations. More...
class  Symbol
 Class used to represent R symbols. More...
class  UncachedString
 String object not held in a cache. More...
class  VectorBase
 Untemplated base class for R vectors. More...
class  WeakRef
 Weak reference. More...

Typedefs

typedef CXXR::FixedVector
< Complex, CPLXSXP
ComplexVector
 Vector of complex numbers.
typedef FixedVector< RHandle
<>, EXPRSXP
ExpressionVector
 Expression vector.
typedef FixedVector< int, INTSXPIntVector
 Vector of integer values.
typedef FixedVector< RHandle
<>, VECSXP
ListVector
 General vector of RHandle<RObject>.
typedef CXXR::FixedVector< int,
LGLSXP
LogicalVector
 Vector of truth values.
typedef CXXR::FixedVector
< Rbyte, RAWSXP
RawVector
 Vector of 'raw bytes'.
typedef CXXR::FixedVector
< double, REALSXP
RealVector
 Vector of real numbers.
typedef FixedVector< RHandle
< String >, STRSXP
StringVector
 Vector of strings.

Functions

template<typename T1 , typename T2 >
bool operator== (const Allocator< T1 > &, const Allocator< T2 > &) throw ()
template<typename T1 , typename T2 >
bool operator!= (const Allocator< T1 > &, const Allocator< T2 > &) throw ()
bool operator== (ConsCell::iterator l, ConsCell::iterator r)
bool operator!= (ConsCell::iterator l, ConsCell::iterator r)
bool operator== (ConsCell::const_iterator l, ConsCell::const_iterator r)
bool operator!= (ConsCell::const_iterator l, ConsCell::const_iterator r)
RObjectcar0 (ConsCell *cc)
 cc ? cc->car() : 0
void ccdump (std::ostream &os, const ConsCell &cc, size_t margin=0)
 (For debugging.)
size_t listLength (const ConsCell *start)
 Number of elements in list.
PairListtail0 (ConsCell *cc)
 cc ? cc->tail() : 0
template<typename T >
bool isNA (const T &t)
 Does a value represent a distinct 'not available' status?
template<typename T >
const T & NA ()
 Value to be used if 'not available'.
std::pair< Environment
*, FunctionBase * > 
findFunction (const Symbol *symbol, Environment *env, bool inherits=true)
 Search for a Binding of a Symbol to a FunctionBase.
template<typename UnaryPredicate >
std::pair< Environment
*, RObject * > 
findTestedValue (const Symbol *symbol, Environment *env, UnaryPredicate pred, bool inherits)
 Search for a Binding whose value satisfies a predicate.
RObjectevaluate (RObject *object, Environment *env)
 Shorthand for Evaluator::evaluate().
void frameReadPairList (Frame *frame, PairList *bindings)
 Incorporate bindings defined by a PairList into a Frame.
bool isMissingArgument (const Symbol *sym, Frame *frame)
 Does a Symbol correspond to a missing argument?
RObjectforceIfPromise (RObject *object)
 Use forced value if RObject is a Promise.
void SEXP_downcast_error (const char *given, const char *wanted)
 Not for general use.
template<typename PtrOut , typename PtrIn >
PtrOut SEXP_downcast (PtrIn s, bool allow_null=true)
bool isASCII (const std::string &str)
 Is a std::string entirely ASCII?
StringVectorasStringVector (const std::string &str, cetype_t encoding=CE_NATIVE)
 Create a StringVector containing a single std::string.
void strdump (std::ostream &os, const StringVector &sv, std::size_t margin=0)
 (For debugging.)
bool isDotSymbol (const Symbol *symbol)
 Does Symbol's name start with '.'?
bool isDotDotSymbol (const Symbol *symbol)
 Does Symbol's name start with '..'?
R_len_t length (RObject *s)
 Shorthand for Rf_length().

Variables

Symbol *const Bracket2Symbol
Symbol *const BracketSymbol
Symbol *const BraceSymbol
Symbol *const ClassSymbol
Symbol *const ConnIdSymbol
Symbol *const DimNamesSymbol
Symbol *const DimSymbol
Symbol *const DollarSymbol
Symbol *const DotClassSymbol
Symbol *const DotDeviceSymbol
Symbol *const DotDevicesSymbol
Symbol *const DotGenericSymbol
Symbol *const DotGenericCallEnvSymbol
Symbol *const DotGenericDefEnvSymbol
Symbol *const DotGroupSymbol
Symbol *const DotMethodSymbol
Symbol *const DotMethodsSymbol
Symbol *const DotdefinedSymbol
Symbol *const DotsSymbol
Symbol *const DottargetSymbol
Symbol *const DoubleColonSymbol
Symbol *const DropSymbol
Symbol *const ExactSymbol
Symbol *const LastvalueSymbol
Symbol *const LevelsSymbol
Symbol *const ModeSymbol
Symbol *const NameSymbol
Symbol *const NamesSymbol
Symbol *const NaRmSymbol
Symbol *const PackageSymbol
Symbol *const PreviousSymbol
Symbol *const QuoteSymbol
Symbol *const RowNamesSymbol
Symbol *const S3MethodsTableSymbol
Symbol *const SeedsSymbol
Symbol *const TripleColonSymbol
Symbol *const TspSymbol
Symbol *const CommentSymbol
Symbol *const SourceSymbol
Symbol *const DotEnvSymbol
Symbol *const RecursiveSymbol
Symbol *const SrcfileSymbol
Symbol *const SrcrefSymbol
Symbol *const WholeSrcrefSymbol
Symbol *const TmpvalSymbol
Symbol *const UseNamesSymbol

Detailed Description

Namespace for the CXXR project.

CXXR is a project to refactorize the R interpreter into C++.


Typedef Documentation

Expression vector.

The vector contains smart pointers of type RObject::Handle<RObject>, where the intention is that these pointers should point to language objects.

Todo:
Replace the encapsulated pointer type RObject* with something stricter (but is needs to embrace Symbol as well as Expression).

Vector of strings.

Note that the StringVector(size_t) constructor will fill the constructed vector with blank strings rather than with NULL.


Function Documentation

StringVector* CXXR::asStringVector ( const std::string &  str,
cetype_t  encoding = CE_NATIVE 
)
inline

Create a StringVector containing a single std::string.

This constructor constructs a StringVector containing a single element, and initializes that element to represent a specified string and encoding.

Parameters:
strThe required text of the single vector element.
encodingThe required encoding of the single vector element. Only CE_NATIVE, CE_UTF8 or CE_LATIN1 are permitted in this context (checked).
RObject* CXXR::car0 ( ConsCell cc)
inline

cc ? cc->car() : 0

Parameters:
ccPointer to the ConsCell whose 'car' object is required.
Returns:
a null pointer if cc is itself null, otherwise a pointer (possibly null) to the 'car' object of cc.
Deprecated:
This is a utility function used to implement CADR(SEXP) and kindred functions in the C interface. Its use for other purposes is deprecated.
void CXXR::ccdump ( std::ostream &  os,
const ConsCell cc,
size_t  margin = 0 
)

(For debugging.)

Note:
The name and interface of this function may well change.
RObject* CXXR::evaluate ( RObject object,
Environment env 
)
inline

Shorthand for Evaluator::evaluate().

Parameters:
objectPointer to the RObject to be evaluated. May be null, in which case the function returns a null pointer.
envPointer to the environment in which evaluation is to take place. May be null only if object is null.
Returns:
Pointer to the result of evaluation.
std::pair<Environment*, FunctionBase*> CXXR::findFunction ( const Symbol symbol,
Environment *  env,
bool  inherits = true 
)

Search for a Binding of a Symbol to a FunctionBase.

This function looks for a Binding of symbol, and tests whether the Binding's value is a FunctionBase.

If a Binding of symbol to a Promise is encountered, the Promise is forced before testing whether the value of the Promise is a FunctionBase. In this case, if the predicate is satisfied, the result of evaluating the Promise is part of the returned value.

If, in the course of searching for a suitable Binding, a Binding of symbol to Symbol::missingArgument() (R_MissingArg) is encountered, an error is raised.

Read/write monitors are invoked in the following circumstances: (i) If a Promise is forced, any read monitor for the relevant Binding is called before forcing it, and any write monitor for the symbol's Binding is called immediately afterwards. (ii) If this function succeeds in finding a Binding to a FunctionBase, then any read monitor for that Binding is called.

Parameters:
symbolNon-null pointer to the Symbol for which a Binding is sought.
envPointer to the Environment in which the search for a Binding is to start. Must not be null.
inheritsIf false, only the Frame of env will be searched; if true, the search will propagate as necessary to enclosing environments until either a Binding to a FunctionBase is found, or the chain of enclosing environments is exhausted.
Returns:
If a Binding to a FunctionBase was found, the first element of the pair is a pointer to the Environment in which it was found, and the second element is the value of the Binding, except that if the value was a Promise, the second element is the result of evaluating the Promise. If no Binding to a FunctionBase was found, both elements of the pair are null pointers.
template<typename UnaryPredicate >
std::pair<Environment*, RObject*> CXXR::findTestedValue ( const Symbol symbol,
Environment *  env,
UnaryPredicate  pred,
bool  inherits 
)

Search for a Binding whose value satisfies a predicate.

This function looks for a Binding of symbol, and tests whether the Binding's value satisfies a predicate pred.

If a Binding of symbol to a Promise is encountered, the Promise is forced before applying the predicate to the result of evaluating the Promise. In this case, if the predicate is satisfied, the result of evaluating the Promise is part of the returned value.

Read/write monitors are invoked in the following circumstances: (i) If a Promise is forced, any read monitor for the relevant Binding is called before forcing it, and any write monitor for the symbol's Binding is called immediately afterwards. (ii) If this function succeeds in finding a Binding satisfying the predicate, then any read monitor for that Binding is called.

Template Parameters:
UnaryPredicateA type of function or function object capable of accepting const RObject* and returning bool.
Parameters:
symbolPointer to the Symbol for which a Binding is sought.
envPointer to the Environment in which the search for a Binding is to start. Must not be null.
predThe UnaryPredicate object to be used to test candidate values.
inheritsIf false, only the Frame of env will be searched; if true, the search will propagate as necessary to enclosing environments until either a Binding satisfying the predicate is found, or the chain of enclosing environments is exhausted.
Returns:
If a Binding satisfying the predicate was found, the first element of of the pair is a pointer to the Environment in which it was found, and the second element is the value of the Binding, except that if the value was a Promise, the second element is the result of evaluating the Promise. If no Binding satisfying the predicate was found, both elements of the pair are null pointers.
RObject* CXXR::forceIfPromise ( RObject object)
inline

Use forced value if RObject is a Promise.

Parameters:
objectPointer, possibly null, to an RObject.
Returns:
If object points to a Promise, the Promise is forced and the value of the Promise returned. Otherwise object itself is returned.
void CXXR::frameReadPairList ( Frame *  frame,
PairList *  bindings 
)

Incorporate bindings defined by a PairList into a Frame.

Raises an error if the Frame is locked, or an attempt is made to modify a binding that is locked.

Parameters:
framePointer to the Frame into which new or modified bindings are to be incorporated.
bindingsList of symbol-value pairs defining bindings to be incorporated into the environment. Every element of this list must have a Symbol as its tag (checked). If the list contains duplicate tags, later symbol-value pairs override earlier ones. Each resulting binding is locked and/or set active according to the m_active_binding and m_binding_locked fields of the corresponding PairList element.
bool CXXR::isASCII ( const std::string &  str)

Is a std::string entirely ASCII?

Parameters:
strThe string to be examined.
Returns:
false if str contains at least one non-ASCII character, otherwise true. In particular the function returns true for an empty string.
bool CXXR::isDotDotSymbol ( const Symbol symbol)
inline

Does Symbol's name start with '..'?

Parameters:
symbolpointer to Symbol to be tested, or a null pointer in which case the function returns false.
Returns:
true if the Symbol's name starts with '..'.
bool CXXR::isDotSymbol ( const Symbol symbol)
inline

Does Symbol's name start with '.'?

Parameters:
symbolpointer to Symbol to be tested, or a null pointer in which case the function returns false.
Returns:
true if the Symbol's name starts with '.'.
bool CXXR::isMissingArgument ( const Symbol *  sym,
Frame *  frame 
)

Does a Symbol correspond to a missing argument?

Within a Frame frame, a Symbol sym is considered to correspond to a missing argument if any of the following criteria is satisfied:

  1. sym is itself Symbol::missingArgument() (R_MissingArg).

  2. The binding of sym within frame is flagged as having origin Frame::Binding::MISSING.

  3. sym is bound to Symbol::missingArgument().

  4. sym is bound to a unforced Promise, and forcing the Promise would consist in evaluating a Symbol which - by a recursive application of these criteria - is missing with respect to the Frame of the Environment of the Promise.

Note that unless Criterion 1 applies, sym is not considered missing if it is not bound at all within frame, or if it has an active binding.

Parameters:
symNon-null pointer to the Symbol whose missing status is to be determined.
frameNon-null pointer to the Frame with respect to which missingness is to be determined.
Returns:
true iff sym is missing with respect to frame.
template<typename T >
bool CXXR::isNA ( const T &  t)

Does a value represent a distinct 'not available' status?

This templated function is syntactic sugar for the ElementTraits::IsNA() function objects. It should not be specialized; instead specialize ElementTraits::IsNA itself.

Template Parameters:
TA type capable of being used as the element type of an R data vector.
Parameters:
tA value of type T .
Returns:
true iff t has a distinct value (or possibly, one of a set of distinct values) signifying that the actual value of this quantity is not available.
R_len_t CXXR::length ( RObject *  s)
inline

Shorthand for Rf_length().

Deprecated:
This is provided only for use in code inherited from CR, and is a workaround for the problems that CR's length macro can cause with C++ header files. New code should invoke Rf_length() explicitly.
size_t CXXR::listLength ( const ConsCell start)
inline

Number of elements in list.

Parameters:
startPointer to a ConsCell, possibly null.
Returns:
zero if start is a null pointer, otherwise the number of elements in the list starting at the ConsCell pointed to by start.
template<typename T >
const T& CXXR::NA ( )

Value to be used if 'not available'.

This templated function is syntactic sugar for the ElementTraits::NAFunc() function objects. It should not be specialized; instead specialize ElementTraits::NAFunc itself.

Template Parameters:
TA type capable of being used as the element type of an R data vector.
Returns:
The value of type T to be used if the actual value is not available. This for example is the value that will be used if an element of a vector of T is accessed in R using a NA index.
Note:
For some types, e.g. Rbyte, the value returned is not distinct from ordinary values of the type. See hasDistinctNA().
template<typename PtrOut , typename PtrIn >
PtrOut CXXR::SEXP_downcast ( PtrIn  s,
bool  allow_null = true 
)

Down cast within the RObject class tree.

Template Parameters:
PtrOutCast the pointer to type PtrOut, where PtrOut is a pointer or const pointer to RObject or a class derived from RObject.
PtrInCast the pointer from type PtrIn, where PtrIn is a pointer or const pointer to RObject or a class derived from RObject. This type is usually inferred from the supplied parameter s.
Parameters:
sThe pointer to be cast.
allow_nulltrue iff s is permitted to be a null pointer.
Returns:
The cast pointer.
void CXXR::SEXP_downcast_error ( const char *  given,
const char *  wanted 
)

Not for general use.

(Used by SEXP_downcast() to report an erroneous cast.)

void CXXR::strdump ( std::ostream &  os,
const StringVector sv,
std::size_t  margin = 0 
)

(For debugging.)

Note:
The name and interface of this function may well change.
PairList* CXXR::tail0 ( ConsCell cc)
inline

cc ? cc->tail() : 0

Parameters:
ccPointer to the ConsCell whose tail pointer is required.
Returns:
a null pointer if cc is itself null, otherwise a the tail pointer (possibly null) of cc.
Deprecated:
This is a utility function used to implement CADR(SEXP) and kindred functions in the C interface. Its use for other purposes is deprecated.