jem::Ref< T > Class Template Reference

Provides `safe' access to a collectable object. More...

#include <jem/base/Ref.h>

Public Member Functions
	Ref ()
	Constructs a Ref with the value NIL. More...
	Ref (const Nil &nil)
	Constructs a Ref with the value NIL. More...
	Ref (T *rhs)
	Creates a Ref that points to an existing object. More...
	Ref (const Ref &rhs)
	Constructs a copy of another Ref. More...
	Ref (const Ref< U > &rhs)
	Conversion constructor. More...
Ref &	operator= (const Ref &rhs)
	Copies another Ref object. More...
bool	operator== (const Ref &rhs) const
	Tests whether two Ref instances point two the same object. More...
bool	operator== (const Nil &nil) const
	Tests whether this Ref does not point to an object. More...
bool	operator!= (const Ref &rhs) const
	Tests whether two Ref instances do not point two the same object. More...
bool	operator!= (const Nil &nil) const
	Tests whether this Ref points to an object. More...
T *	operator-> () const
	Returns a pointer to the object that this Ref is pointing to. More...
T &	operator* () const
	Returns a reference to the object that this Ref is pointing to. More...
void	swap (Ref &rhs)
	Interchanges two Ref objects. More...
Collectable *	getBase () const
	Returns a pointer to the Collectable subobject of the object this Ref is pointing to. More...
T *	get () const
	Returns a pointer to the object that this Ref is pointing to. More...

Related Functions
(Note that these are not member functions.)
template<class T , class A >
Ref< T >	newInstance (const A &a)
	Creates a collectable object of type T. More...
template<class T , class A , class B >
Ref< T >	newInstance (const A &a, const B &b)
	Creates a collectable object of type T. More...
template<class T , class A , class B , class C >
Ref< T >	newInstance (const A &a, const B &b, const C &c)
	Creates a collectable object of type T. More...
template<class T , class A , class B , class C , class D >
Ref< T >	newInstance (const A &a, const B &b, const C &c, const D &d)
	Creates a collectable object of type T. More...
template<class U , class T >
Ref< U >	staticCast (const Ref< T > &r)
	Mimics a static cast expression. More...
template<class U , class T >
Ref< U >	dynamicCast (const Ref< T > &r)
	Mimics a dynamic cast expression. More...
template<class U , class T >
Ref< U >	checkedCast (const Ref< T > &r)
	Mimics a dynamic cast expression and checks whether the cast succeeded. More...
template<class T >
void	swap (Ref< T > &lhs, Ref< T > &rhs)
	Interchanges two Ref objects. More...

Detailed Description

template<class T>
class jem::Ref< T >

The template class Ref encapsulates a pointer of type T* that points to a collectable object. Unlike a normal pointer, however, a Ref instance guarantees that the collectable object is not deleted. That is, the collectable object will not be deleted as long as it can be reached through one or more Ref instances.

A Ref that contains a NULL pointer is said to have the value NIL. To be precise, NIL is a pre-defined instance of the class Nil. Because several members of the Ref class have been overloaded for an argument of type Nil, one can use NIL as a special Ref object. Example:

Ref<Object> obj = NIL;

if ( obj == NIL )
{
  throw NullPointerException ();
}

A Ref can point to any object as long as the runtime type of the object is unambiguously derived from the Collectable class. This means that the type T does not have to be derived from the Collectable class. Example:

class Foo { ... };

class Bar : public Foo, public Collectable { ... };

...

Ref<Bar>  bar = newInstance<Bar>();
Ref<Foo>  foo = bar;                 // OK: the runtime type of
                                     //     foo is Bar.

See also

WeakRef.

Examples:

Database.cpp, DataParser.cpp, Event.cpp, game-of-life.cpp, GzipFileReader.cpp, GzipFileWriter.cpp, meshgen.cpp, and TextInput.cpp.

Constructor & Destructor Documentation

template<class T>

jem::Ref< T >::Ref

(

)

Constructs a Ref with the value NIL.

Postcondition

this == NIL &&
this->get() == NULL

template<class T>

jem::Ref< T >::Ref

(

const Nil &

nil

)

Constructs a Ref with the value NIL.

Parameters

nil	- an instance of the class Nil. This is a dummy parameter that is not actually used.

Postcondition

this == NIL &&
this->get() == NULL

template<class T>

jem::Ref< T >::Ref

(

T *

rhs

)

Creates a Ref that points to the collectable object rhs.

Parameters

rhs	- a pointer to an object of type T, or NULL.

Precondition

The type T must be derived from the Collectable class.

Postcondition

this->get() == rhs

Note

This is the only function that requires that the type T is derived from the Collectable class.

template<class T>

jem::Ref< T >::Ref

(

const Ref< T > &

rhs

)

Constructs a Ref that points to the same object as the Ref rhs.

Parameters

rhs	- the Ref to be copied.

Postcondition

this->get() == rhs.get()

template<class T>

jem::Ref< T >::Ref

(

const Ref< U > &

rhs

)

Creates a Ref that points to a subobject of the object pointed to by the Ref rhs. Example:

class Foo { ... };
class Bar : public Foo { ... };

Ref<Bar>  bar ( newInstance<Bar>() );

Ref<Foo>  foo ( bar );  // `foo' now points to the Foo
                        // subobject of the Bar object pointed 
                        // to by `bar'.

Parameters

rhs	- the Ref to be converted.

Precondition

A pointer of type T* is assignable from a pointer of type U*.

Postcondition

this->get() == static_cast<T>( rhs.get() )

Note

Because this constructor is not declared explicit, it can be used as an implicit conversion constructor.

Member Function Documentation

template<class T>

Ref& jem::Ref< T >::operator=

(

const Ref< T > &

rhs

)

Copies the Ref rhs so that this Ref points to the same object as rhs.

Parameters

rhs	- the Ref to be copied.

Returns

*this

Postcondition

this->get() == rhs.get()

template<class T>

bool jem::Ref< T >::operator==

(

const Ref< T > &

rhs

)

const

Tests whether this Ref and the Ref rhs point to the same object.

Parameters

rhs	- the Ref object to which this Ref object should be compared.

Returns

this->get() == rhs.get()

template<class T>

bool jem::Ref< T >::operator==

(

const Nil &

nil

)

const

Tests whether this Ref does not point to an object.

Parameters

nil	- an instance of the class Nil. This is a dummy parameter that is not actually used.

Returns

this->get() == NULL

template<class T>

bool jem::Ref< T >::operator!=

(

const Ref< T > &

rhs

)

const

Tests whether this Ref and the Ref rhs point to different objects.

Parameters

rhs	- the Ref object this Ref should be compared with.

Returns

this->get() != rhs.get()

template<class T>

bool jem::Ref< T >::operator!=

(

const Nil &

nil

)

const

Tests whether this Ref points to an object.

Parameters

nil	- an instance of the class Nil. This is a dummy parameter that is not actually used.

Returns

this->get() != NULL

template<class T>

T* jem::Ref< T >::operator->

(

)

const

Returns

get()

Precondition

this->get() != NULL

template<class T>

T& jem::Ref< T >::operator*

(

)

const

Returns

*get()

Precondition

this->get() != NULL

template<class T>

void jem::Ref< T >::swap

(

Ref< T > &

rhs

)

Equivalent with:

Ref<T> tmp( *this );

(*this) = rhs;
rhs     = tmp;

Parameters

rhs	- the Ref object with which this Ref should be interchanged.

template<class T>

Collectable* jem::Ref< T >::getBase

(

)

const

Returns

dynamic_cast<Collectable*>( this->get() )

Note

The current implementation does not use a dynamic cast.

template<class T>

T* jem::Ref< T >::get

(

)

const

Returns

A pointer to the object that this Ref is pointing to.

Friends And Related Function Documentation

template<class T , class A >

Ref< T > newInstance ( const A &  a )

related

Equivalent with: new T( a )

Parameters

a	- the argument to be passed to the constructor of type T.

Returns

A Ref pointing to the new object.

template<class T , class A , class B >

Ref< T > newInstance ( const A &  a, const B &  b  )

related

Equivalent with: new T( a, b )

Parameters

a	- the first parameter to be passed to the constructor of type T.
b	- the second parameter to be passed to the constructor of type T.

Returns

A Ref pointing to the new object.

template<class T , class A , class B , class C >

Ref< T > newInstance ( const A &  a, const B &  b, const C &  c  )

related

Equivalent with: new T( a, b, c )

Parameters

a	- the first parameter to be passed to the constructor of type T.
b	- the second parameter to be passed to the constructor of type T.
c	- the third parameter to be passed to the constructor of type T.

Returns

A Ref pointing to the new object.

template<class T , class A , class B , class C , class D >

Ref< T > newInstance ( const A &  a, const B &  b, const C &  c, const D &  d  )

related

Equivalent with: new T( a, b, c, d )

Parameters

a	- the first parameter to be passed to the constructor of type T.
b	- the second parameter to be passed to the constructor of type T.
c	- the third parameter to be passed to the constructor of type T.
d	- the fourth parameter to be passed to the constructor of type T.

Returns

A Ref pointing to the new object.

template<class U , class T >

Ref< U > staticCast ( const Ref< T > &  r )

related

Converts the Ref r, encapsulating a pointer of type T*, to a Ref encapsulating a pointer of type U* using a static cast expression.

Parameters

r	- the Ref that is to be converted.

Returns

A Ref that points to static_cast<U*>( r.get() ).

Postcondition

staticCast<U>( r ).get() == static_cast<U*>( r.get() )

template<class U , class T >

Ref< U > dynamicCast ( const Ref< T > &  r )

related

Converts the Ref r, encapsulating a pointer of type T*, to a Ref encapsulating a pointer of type U* using a dynamic cast expression.

Parameters

r	- the Ref to be converted.

Returns

A Ref that points to dynamic_cast<U*>( r.get() ).

Postcondition

dynamicCast<U>( r ).get() == dynamic_cast<U*>( r.get() )

template<class U , class T >

Ref< U > checkedCast ( const Ref< T > &  r )

related

This function has the same effect as the dynamicCast function except that it throws an exception if the dynamic cast fails.

Parameters

r	- the Ref to be converted.

Returns

dynamicCast<U>( r )

Exceptions

ClassCastException

- if the dynamic cast fails and r is not NIL.

template<class T >

void swap ( Ref< T > &  lhs, Ref< T > &  rhs  )

related

Equivalent with lhs.swap( rhs ).

Parameters

lhs	- the first of the two Ref objects to be swapped.
rhs	- the second Ref objects to be swapped.