Representation of a binding of a Symbol to an RObject. More...

#include <Frame.hpp>

Public Types
enum	Origin { EXPLICIT = 0, MISSING, DEFAULTED }
	How the binding arrived at its current setting. More...

Public Member Functions
	Binding ()
	Default constructor.
PairList *	asPairList (PairList *tail=0) const
	Represent this Binding as a PairList element.
void	assign (RObject *new_value, Origin origin=EXPLICIT)
	Bind value to Symbol.
std::pair< RObject *, bool >	forcedValue ()
	Look up bound value, forcing Promises if necessary.
const Frame *	frame () const
	Get pointer to Frame.
void	fromPairList (PairList *pl)
	Get binding information from a PairList element.
void	initialize (Frame frame, const Symbol sym)
	Initialize the Binding.
bool	isActive () const
	Is this an active Binding?
bool	isLocked () const
	Is this Binding locked?
Origin	origin () const
	Origin of this Binding.
RObject *	rawValue () const
	Get raw value bound to the Symbol.
void	setFunction (FunctionBase *function, Origin origin=EXPLICIT)
	Sets this to be an active Binding encapsulating a specified function.
void	setLocking (bool on)
	Lock/unlock this Binding.
void	setValue (RObject *new_value, Origin origin=EXPLICIT, bool quiet=false)
	Define the object to which this Binding's Symbol is bound.
const Symbol *	symbol () const
	Bound symbol.
RObject *	value () const
	Get value bound to the Symbol.
void	visitReferents (const_visitor *v) const
	Auxiliary function to Frame::visitReferents().

Friends
class	boost::serialization::access

Detailed Description

Representation of a binding of a Symbol to an RObject.

A binding may be identified as 'active', in which case it encapsulates a function (i.e. an object of type FunctionBase). The value of the binding, as returned by value(), is then determined by evaluating this function with no arguments. Setting the value of the binding, by calling assign(), simply invokes that same function with the supplied value as its single argument: the encapsulated function is not altered.

Note:: Arguably plain bindings and active bindings ought to be modelled by different classes.

Member Enumeration Documentation

enum CXXR::Frame::Binding::Origin

How the binding arrived at its current setting.

Enumerator:

EXPLICIT	The Binding was specified explicitly, e.g. by supplying an actual argument to a function, or by direct assignment into the relevant Environment.
MISSING	The Binding corresponds to a formal argument of a function, for which no actual value was supplied, and which has no default value. This is the default for newly created Binding objects.
DEFAULTED	The Binding represents the default value of the formal argument of a function call, no actual argument having been supplied.

Constructor & Destructor Documentation

CXXR::Frame::Binding::Binding ( )

inline

Default constructor.

initialize() must be called before the Binding object can be used.

Member Function Documentation

PairList* CXXR::Frame::Binding::asPairList ( PairList * tail = 0 ) const

Represent this Binding as a PairList element.

This function creates a new PairList element which represents the information in the Binding in the form returned by CR's FRAME() function.

If the Binding is active, then the 'car' of the created PairList element will contain a pointer to the encapsulated function.

Parameters:

tail	Value to be set as the tail (CDR) of the created PairList element.

Returns:: The created PairList element.

void CXXR::Frame::Binding::assign	(	RObject *	new_value,
		Origin	origin = `EXPLICIT`
	)

Bind value to Symbol.

In the case of non-active bindings, this function has exactly the same effect as setValue(): it changes the value to which this Binding's symbol is bound to new_value.

For active bindings, it invokes the encapsulated function with new_value as its sole argument.

Raises an error if the Binding is locked.

Parameters:

new_value	Pointer (possibly null) to the new value. See function description.
origin	Origin of the newly-assigned value.

std::pair<RObject*, bool> CXXR::Frame::Binding::forcedValue ( )

Look up bound value, forcing Promises if necessary.

If the value of this Binding is anything other than a Promise, this function returns a pointer to that bound value. However, if the value is a Promise, the function forces the Promise if necessary, and returns a pointer to the value of the Promise.

Returns:: The first element of the returned pair is a pointer - possibly null - to the bound value, or the Promise value if the bound value is a Promise. The second element is true iff the function call resulted in the forcing of a Promise.

Note:: If this Binding's frame has a read monitor set, the function will call it only in the event that a Promise is forced (and in that event the evaluation of the Promise may trigger other read and write monitors).; It is conceivable that forcing a Promise will result in the destruction of this Binding object.

const Frame* CXXR::Frame::Binding::frame ( ) const

inline

Get pointer to Frame.

Returns:: Pointer to the Frame to which this Binding belongs.

void CXXR::Frame::Binding::fromPairList ( PairList * pl )

Get binding information from a PairList element.

This function sets the value of this Binding, and its active, locked and missing status, from the corresponding fields of a PairList element.

If the PairList element defines the Binding as active, then its 'car' is considered to contain a pointer to the active binding function.

Raises an error if the Binding is locked.

Parameters:

pl	Non-null pointer to the PairList element from which binding information is to be obtained. If pl has a tag, it must be a pointer to the Symbol bound by this Binding.

void CXXR::Frame::Binding::initialize	(	Frame *	frame,
		const Symbol *	sym
	)

Initialize the Binding.

This function initializes the Frame and Symbol pointers of this Binding. This function may be called at most once for any Binding object, and must be called before any other use is made of the Binding.

Parameters:

frame	Pointer to the Frame to which this Binding belongs. Must be non-null.
sym	Pointer to the Symbol bound by this Binding. Must be non-null.

bool CXXR::Frame::Binding::isActive ( ) const

inline

Is this an active Binding?

Returns:: true iff this is an active Binding.

bool CXXR::Frame::Binding::isLocked ( ) const

inline

Is this Binding locked?

Returns:: true iff this Binding is locked.

Origin CXXR::Frame::Binding::origin ( ) const

inline

Origin of this Binding.

Returns:: the Origin of this Binding.

RObject* CXXR::Frame::Binding::rawValue ( ) const

inline

Get raw value bound to the Symbol.

'raw' here means that in the case of an active Binding, the function returns a pointer to the encapsulated function rather than the result of evaluating the encapsulated function. This function will not result in the calling of a read monitor.

Returns:: The value bound to a Symbol by this Binding.

void CXXR::Frame::Binding::setFunction	(	FunctionBase *	function,
		Origin	origin = `EXPLICIT`
	)

Sets this to be an active Binding encapsulating a specified function.

When invoked for an existing active Binding, this function simply replaces the encapsulated function.

Raises an error if the Binding is locked.

Also raises an error if the Binding is not currently marked active but has a non-null value. (This is slightly less strict than CR, which only allows active status to be set on a newly created binding.)

Parameters:

function	The function used to implement the active binding.
origin	Origin now to be associated with this Binding.

void CXXR::Frame::Binding::setLocking ( bool on )

inline

Lock/unlock this Binding.

Parameters:

on	true iff the Binding is to be locked.

void CXXR::Frame::Binding::setValue	(	RObject *	new_value,
		Origin	origin = `EXPLICIT`,
		bool	quiet = `false`
	)

Define the object to which this Binding's Symbol is bound.

Raises an error if the Binding is locked or active.

Parameters:

new_value	Pointer (possibly null) to the RObject to which this Binding's Symbol is now to be bound.
origin	Origin of the newly assigned value.
quiet	Don't trigger monitor

const Symbol* CXXR::Frame::Binding::symbol ( ) const

inline

Bound symbol.

Returns:: Pointer to the Symbol bound by this Binding.

RObject* CXXR::Frame::Binding::value ( ) const

Get value bound to the Symbol.

For an active binding, this evaluates the encapsulated function and returns the result rather than returning a pointer to the encapsulated function itself.

Returns:: The value bound to a Symbol by this Binding.

void CXXR::Frame::Binding::visitReferents ( const_visitor * v ) const

Auxiliary function to Frame::visitReferents().

This function conducts a visitor to those objects derived from GCNode which become 'children' of this Binding's Frame as a result of its containing this Binding.

Parameters:

v	Pointer to the visitor object.

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

Frame.hpp ($Id: Frame.hpp 1397 2013-08-16 18:25:59Z arr $)

Public Types

Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation