Class used to represent R symbols. More...

#include <Symbol.h>

Inheritance diagram for CXXR::Symbol:

Collaboration diagram for CXXR::Symbol:

Classes
class	const_iterator
	const_iterator for iterating over all standard Symbols. More...

Public Member Functions
unsigned int	dotDotIndex () const
	Index of a double-dot symbol.
bool	isDotDotSymbol () const
	Is this a double-dot symbol?
const String *	name () const
	Access name.
RObject *	evaluate (Environment *env)
	Evaluate object in a specified Environment.
const char *	typeName () const
	Name within R of this type of object.
void	visitReferents (const_visitor *v) const
	Conduct a visitor to the nodes referred to by this one.
Public Member Functions inherited from CXXR::RObject
virtual const PairList *	attributes () const
	Get object attributes.
virtual void	clearAttributes ()
	Remove all attributes.
virtual RObject *	clone () const
	Return pointer to a copy of this object.
void	copyAttribute (const Symbol name, const RObject source)
	Copy an attribute from one RObject to another.
void	copyAttributes (const RObject *source, bool copyS4)
	Copy attributes from one RObject to another.
virtual RObject *	getAttribute (const Symbol *name) const
	Get the value a particular attribute.
virtual bool	hasAttributes () const
	Has this object any attributes?
bool	hasClass () const
	Has this object the class attribute?
bool	isS4Object () const
	Is this an S4 object?
void	maybeTraceMemory (const RObject *src)
	Carry out memory tracing.
void	maybeTraceMemory (const RObject src1, const RObject src2)
	Carry out memory tracing.
void	maybeTraceMemory (const RObject src1, const RObject src2, const RObject *src3)
	Carry out memory tracing.
bool	memoryTraced () const
	Is copying etc. of this object being traced?
virtual unsigned int	packGPBits () const
	Reproduce the `gp` bits field used in CR.
virtual void	setAttribute (const Symbol name, RObject value)
	Set or remove an attribute.
void	setAttributes (const PairList *new_attributes)
	Replace the attributes of an object.
void	setMemoryTracing (bool on)
	Enable/disable tracing of copying etc.
void	setS4Object (bool on)
	Set the status of this RObject as an S4 object.
SEXPTYPE	sexptype () const
	Get an object's SEXPTYPE.
virtual void	unpackGPBits (unsigned int gpbits)
	Interpret the `gp` bits field used in CR.
Public Member Functions inherited from CXXR::GCNode
void	expose () const
	Record that construction of a node is complete.
bool	isExposed () const
	Has this node been exposed to garbage collection?
Public Member Functions inherited from CXXR::HeterogeneousListBase::Link
	Link ()
	Default constructor.
	Link (HeterogeneousListBase *list)
	Appending constructor.
void	freeLink ()
	Detach Link from any list.

Static Public Member Functions
static const_iterator	begin ()
static const_iterator	end ()
static size_t	maxLength ()
	Maximum length of symbol names.
static Symbol *	missingArgument ()
	Missing argument.
static Symbol *	obtain (const String *name)
	Get a pointer to a regular Symbol object.
static Symbol *	obtain (const std::string &name)
	Get a pointer to a regular Symbol object.
static Symbol *	obtainDotDotSymbol (unsigned int n)
	Create a double-dot symbol.
static const char *	staticTypeName ()
	The name by which this type is known in R.
static Symbol *	unboundValue ()
	Unbound value.
Static Public Member Functions inherited from CXXR::RObject
template<class T >
static T *	clone (const T *pattern)
	Return a pointer to a copy of an object.
Static Public Member Functions inherited from CXXR::GCNode
static void *	operator new (size_t bytes)
	Allocate memory.
static void *	operator new (size_t, void *where)
	Placement new for GCNode.
static void	operator delete (void *p, size_t bytes)
	Deallocate memory.
static bool	check ()
	Integrity check.
template<class T >
static T *	expose (T *node)
	Record that construction of a node is complete.
static void	gc ()
	Initiate a garbage collection.
static void	gclite ()
	Lightweight garbage collection.
static void	maybeCheckExposed (const GCNode *node)
	Subject to configuration, check that a GCNode is exposed.
static size_t	numNodes ()
	Number of GCNode objects in existence.

Protected Member Functions
void	detachReferents ()
	Null out all references from this node to other nodes.
Protected Member Functions inherited from CXXR::RObject
	RObject (SEXPTYPE stype=CXXSXP)
	RObject (const RObject &pattern)
	Copy constructor.
Protected Member Functions inherited from CXXR::GCNode
virtual	~GCNode ()
Protected Member Functions inherited from CXXR::HeterogeneousListBase::Link
virtual	~Link ()

Friends
class	boost::serialization::access
class	SchwarzCounter< Symbol >

Additional Inherited Members
Public Attributes inherited from CXXR::RObject
unsigned char	m_named
unsigned	m_missing: 2
unsigned	m_argused: 2
bool	m_active_binding: 1
bool	m_binding_locked: 1

Detailed Description

Class used to represent R symbols.

A Symbol is an R identifier. Each Symbol (except for special symbols, see below) has a name, namely a String giving the textual representation of the identifier. Generally speaking, however, a Symbol object is identified by its address rather than by its name. Consequently, the class enforces the invariant that there is a most one Symbol object with a given name (but this does not apply to special symbols).

Symbols come in two varieties, standard symbols and special symbols, both implemented by this class. Dot-dot symbols are a subvariety of standard symbols.

Standard symbols are generated using the static member function obtain(), and (as explained above) have the property that there is at most one standard symbol with a given name. This is enforced by an internal table mapping names to standard symbols.

Dot-dot symbols have names of the form '..n', where n is a positive integer. These are preferably generated using the static member function obtainDotDotSymbol() (though they can also be generated using obtain() ), and are used internally by the interpreter to refer to elements of a '...' argument list. (Note that CR does not consistently enforce the 'at most one Symbol per name' rule for dot-dot symbols; CXXR does.)

Special symbols are used to implement certain pseudo-objects (::R_MissingArg and ::R_UnboundValue) that CR expects to have SEXPTYPE SYMSXP. Each special symbol has a blank string as its name, but despite this each of them is a distinct symbol.

Note:: Following the practice with CR's symbol table, Symbol objects, once created, are permanently preserved against garbage collection. There is no inherent reason for this in CXXR, but some packages may rely on it. Consequently there is no need to use smart pointers such as GCStackRoot<Symbol> or GCEdge<Symbol>: plain pointers will do fine.

Member Function Documentation

void Symbol::detachReferents ( )

protectedvirtual

Null out all references from this node to other nodes.

The referents of this node are those objects (derived from GCNode) designated by a GCEdge within this object. This function changes all GCEdges within this object to encapsulate a null pointer. It is used during the sweep phase of a mark-sweep garbage collection to break up unreachable subgraphs, and in particular to remove reference loops from them. After the application of this method, the GCNode should be regarded as a 'zombie', kept in existence only so other nodes can detach their references to it cleanly (using decRefCount()).

Note:: If this method is reimplemented in a derived class, the reimplemented version must remember to invoke detachReferents() for the immediate base class of the derived class, to ensure that all referents of the object get detached.

Reimplemented from CXXR::RObject.

unsigned int CXXR::Symbol::dotDotIndex ( ) const

inline

Index of a double-dot symbol.

Returns:: If this is a Symbol whose name is of the form ..n, where n is a positive integer, returns n. Otherwise returns 0.

Note:: This function returns 0 in the (pathological) case of a Symbol called ..0.

RObject * Symbol::evaluate ( Environment * env )

virtual

Evaluate object in a specified Environment.

Parameters:

env	Pointer to the environment in which evaluation is to take place.

Returns:: Pointer to the result of evaluation.

Reimplemented from CXXR::RObject.

bool CXXR::Symbol::isDotDotSymbol ( ) const

inline

Is this a double-dot symbol?

Returns:: true iff this symbol relates to an element of a ... argument list.

static size_t CXXR::Symbol::maxLength ( )

inlinestatic

Maximum length of symbol names.

Returns:: The maximum permitted length of symbol names.

static Symbol* CXXR::Symbol::missingArgument ( )

inlinestatic

Missing argument.

Returns:: a pointer to the 'missing argument' pseudo-object.

const String* CXXR::Symbol::name ( ) const

inline

Access name.

Returns:: const reference to the name of this Symbol.

static Symbol* CXXR::Symbol::obtain ( const String * name )

inlinestatic

Get a pointer to a regular Symbol object.

If no Symbol with the specified name currently exists, one will be created, and a pointer to it returned. Otherwise a pointer to the existing Symbol will be returned.

Parameters:

name	The name of the required Symbol.

Returns:: Pointer to a Symbol (preexisting or newly created) with the required name.

Symbol * Symbol::obtain ( const std::string & name )

static

Get a pointer to a regular Symbol object.

If no Symbol with the specified name currently exists, one will be created, and a pointer to it returned. Otherwise a pointer to the existing Symbol will be returned.

Parameters:

name	The name of the required Symbol (CE_NATIVE encoding is assumed). At present no check is made that the supplied string is a valid symbol name.

Returns:: Pointer to a Symbol (preexisting or newly created) with the required name.

Symbol * Symbol::obtainDotDotSymbol ( unsigned int n )

static

Create a double-dot symbol.

Parameters:

n	Index number of the required symbol; must be strictly positive.

Returns:: a pointer to the created symbol, whose name will be ..n.

static const char* CXXR::Symbol::staticTypeName ( )

inlinestatic

The name by which this type is known in R.

Returns:: The name by which this type is known in R.

const char * Symbol::typeName ( ) const

virtual

Name within R of this type of object.

Returns:: the name by which this type of object is known within R.

Reimplemented from CXXR::RObject.

static Symbol* CXXR::Symbol::unboundValue ( )

inlinestatic

Unbound value.

This is used as the 'value' of a Symbol that has not been assigned any actual value.

Returns:: a pointer to the 'unbound value' pseudo-object.

void Symbol::visitReferents ( const_visitor * v ) const

virtual

Conduct a visitor to the nodes referred to by this one.

The referents of this node are those objects (derived from GCNode) designated by a GCEdge within this object.

Parameters:

v	Pointer to the visitor object.

Note:: If this method is reimplemented in a derived class, the reimplemented version must remember to invoke visitReferents() for the immediate base class of the derived class, to ensure that all referents of the object get visited. It is suggested that implementations set up stack-based pointers to all the referents of a node before visiting any of them; in that case, if the (recursive) visiting pushes the node out of the processor cache, there is no need to fetch it back in.

Reimplemented from CXXR::RObject.

The documentation for this class was generated from the following files:

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Function Documentation