CXXR (C++ R)
Public Types | Public Member Functions | Friends
CXXR::Frame::Binding Class Reference

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

#include <Frame.hpp>

List of all members.

Public Types

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

Public Member Functions

 Binding ()
 Default constructor.
PairListasPairList (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 Frameframe () 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.
RObjectrawValue () 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 Symbolsymbol () const
 Bound symbol.
RObjectvalue () 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

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 * 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:
tailValue to be set as the tail (CDR) of the created PairList element.
Returns:
The created PairList element.
void 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_valuePointer (possibly null) to the new value. See function description.
originOrigin of the newly-assigned value.
pair< RObject *, bool > 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 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:
plNon-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 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:
framePointer to the Frame to which this Binding belongs. Must be non-null.
symPointer 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 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:
functionThe function used to implement the active binding.
originOrigin now to be associated with this Binding.
void CXXR::Frame::Binding::setLocking ( bool  on)
inline

Lock/unlock this Binding.

Parameters:
ontrue iff the Binding is to be locked.
void 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_valuePointer (possibly null) to the RObject to which this Binding's Symbol is now to be bound.
originOrigin of the newly assigned value.
quietDon't trigger monitor
const Symbol* CXXR::Frame::Binding::symbol ( ) const
inline

Bound symbol.

Returns:
Pointer to the Symbol bound by this Binding.
RObject * 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 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:
vPointer to the visitor object.

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