Simple wrapper class for raw pointers to single objects where no persisting relationship exists. More...

#include <Teuchos_PtrDecl.hpp>

Public Member Functions
	Ptr (ENull null_in=null)
	Default construct to NULL. More...

	Ptr (T *ptr)
	Construct given a raw pointer. More...

	Ptr (const Ptr< T > &ptr)
	Copy construct from same type. More...

template<class T2 >
	Ptr (const Ptr< T2 > &ptr)
	Copy construct from another type. More...

Ptr< T > &	operator= (const Ptr< T > &ptr)
	Shallow copy of the underlying pointer. More...

T *	operator-> () const
	Pointer (`->`) access to members of underlying object. More...

T &	operator* () const
	Dereference the underlying object. More...

T *	get () const
	Get the raw C++ pointer to the underlying object. More...

T *	getRawPtr () const
	Get the raw C++ pointer to the underlying object. More...

bool	is_null () const
	Return true if the wrapped raw pointer is NULL, else return false. More...

const Ptr< T > &	assert_not_null () const
	Throws `std::logic_error` if `this->get()==NULL`, otherwise returns reference to `*this`. More...

const Ptr< T >	ptr () const
	Return a copy of *this. More...

Ptr< const T >	getConst () const
	Return a Ptr<const T> version of *this. More...

Related Functions
(Note that these are not member functions.)
template<typename T >
Ptr< T >	outArg (T &arg)
	create a non-persisting (required or optional) output argument for a function call. More...

template<typename T >
Ptr< T >	inOutArg (T &arg)
	create a non-persisting (required or optional) input/output argument for a function call. More...

template<typename T >
Ptr< T >	inoutArg (T &arg)
	create a non-persisting (required or optional) input/output argument for a function call. More...

template<typename T >
Ptr< const T >	ptrInArg (T &arg)
	create a general `Ptr` input argument for a function call from a reference. More...

template<typename T >
Ptr< T >	optInArg (T &arg)
	create a non-persisting non-const optional input argument for a function call. More...

template<typename T >
Ptr< const T >	constOptInArg (T &arg)
	create a non-persisting const optional input argument for a function call. More...

template<typename T >
Ptr< T >	ptrFromRef (T &arg)
	Create a pointer to a object from an object reference. More...

template<typename T >
Ptr< T >	ptr (T *p)
	Create a pointer to an object from a raw pointer. More...

template<typename T >
Ptr< const T >	constPtr (T &arg)
	Create a pointer from a const object given a non-const object reference. More...

template<class T >
bool	is_null (const Ptr< T > &p)
	Returns true if `p.get()==NULL`. More...

template<class T >
bool	nonnull (const Ptr< T > &p)
	Returns true if `p.get()!=NULL` More...

template<class T >
bool	operator== (const Ptr< T > &p, ENull)
	Returns true if `p.get()==NULL`. More...

template<class T >
bool	operator!= (const Ptr< T > &p, ENull)
	Returns true if `p.get()!=NULL`. More...

template<class T1 , class T2 >
bool	operator== (const Ptr< T1 > &p1, const Ptr< T2 > &p2)
	Return true if two `Ptr` objects point to the same object. More...

template<class T1 , class T2 >
bool	operator!= (const Ptr< T1 > &p1, const Ptr< T2 > &p2)
	Return true if two `Ptr` objects do not point to the same object. More...

template<class T2 , class T1 >
Ptr< T2 >	ptr_implicit_cast (const Ptr< T1 > &p1)
	Implicit cast of underlying `Ptr` type from `T1` to `T2`. More...

template<class T2 , class T1 >
Ptr< T2 >	ptr_static_cast (const Ptr< T1 > &p1)
	Static cast of underlying `Ptr` type from `T1` to `T2`. More...

template<class T2 , class T1 >
Ptr< T2 >	ptr_const_cast (const Ptr< T1 > &p1)
	Constant cast of underlying `Ptr` type from `T1` to `T2`. More...

template<class T2 , class T1 >
Ptr< T2 >	ptr_dynamic_cast (const Ptr< T1 > &p1, bool throw_on_fail=false)
	Dynamic cast of underlying `Ptr` type from `T1` to `T2`. More...

template<class T >
std::ostream &	operator<< (std::ostream &out, const Ptr< T > &p)
	Output stream inserter. More...

Detailed Description

template<class T>
class Teuchos::Ptr< T >

Simple wrapper class for raw pointers to single objects where no persisting relationship exists.

This class is meant to replace all but the lowest-level use of raw pointers that point to single objects where the use of RCP is not justified for performance or semantic reasons. When built in optimized mode, this class should impart little time overhead and should be exactly equivalent in the memory footprint to a raw C++ pointer and the only extra runtime overhead will be the default initalization to NULL.

The main advantages of using this class over a raw pointer however are:

Ptr objects always default construct to null
Ptr objects will throw exceptions on attempts to dereference the underlying null pointer when debugging support is compiled in.
Ptr does not allow array-like operations like ptr[i], ++ptr or ptr+i that can only result in disaster when the a pointer points to only a single object that can not be assumed to be part of an array of objects.
Ptr is part of a system of types defined in Teuchos that keeps your code away from raw pointers which are the cause of most defects in C++ code.

Debugging support is compiled in when the macro TEUCHOS_DEBUG is defined which happens automatically when –enable-teuchos-debug is specified on the configure line. When debugging support is not compiled in, the only overhead imparted by this class is it's default initialization to null. Therefore, this class can provide for very high performance on optimized builds of the code.

An implicit conversion from a raw pointer to a Ptr object is okay since we don't assume any ownership of the object, hense the constructor taking a raw pointer is not declared explicit. However, this class does not support an implicit conversion to a raw pointer since we want to limit the exposure of raw pointers in our software. If we have to convert back to a raw pointer, then we want to make that explicit by calling get().

This class should be used to replace most raw uses of C++ pointers to single objects where using the RCP class is not appropriate, unless the runtime cost of null-initialization it too expensive.

Definition at line 71 of file Teuchos_PtrDecl.hpp.

Constructor & Destructor Documentation

template<class T >

Teuchos::Ptr< T >::Ptr ( ENull null_in = null )

inline

Default construct to NULL.

Postconditons:

this->get() == NULL

Definition at line 27 of file Teuchos_Ptr.hpp.

template<class T>

Teuchos::Ptr< T >::Ptr ( T * ptr )

inlineexplicit

Construct given a raw pointer.

Postconditons:

this->get() == ptr

Note: This constructor is declared explicit so there is no implicit conversion from a raw C++ pointer to a Ptr object. This is meant to avoid cases where an uninitialized pointer is used to implicitly initialize one of these objects.

Definition at line 33 of file Teuchos_Ptr.hpp.

template<class T>

Teuchos::Ptr< T >::Ptr ( const Ptr< T > & ptr )

inline

Copy construct from same type.

Postconditons:

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

Definition at line 39 of file Teuchos_Ptr.hpp.

template<class T >

template<class T2 >

Teuchos::Ptr< T >::Ptr ( const Ptr< T2 > & ptr )

inline

Copy construct from another type.

Postconditons:

this->get() == ptr.get() (unless virtual base classes are involved)

Definition at line 49 of file Teuchos_Ptr.hpp.

Member Function Documentation

template<class T>

Ptr< T > & Teuchos::Ptr< T >::operator= ( const Ptr< T > & ptr )

inline

Shallow copy of the underlying pointer.

Postconditons:

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

Definition at line 58 of file Teuchos_Ptr.hpp.

template<class T >

T * Teuchos::Ptr< T >::operator-> ( ) const

inline

Pointer (->) access to members of underlying object.

Preconditions:

this->get() != NULL (throws std::logic_error)

Definition at line 69 of file Teuchos_Ptr.hpp.

template<class T >

T & Teuchos::Ptr< T >::operator* ( ) const

inline

Dereference the underlying object.

Preconditions:

this->get() != NULL (throws std::logic_error)

Definition at line 78 of file Teuchos_Ptr.hpp.

template<class T >

T * Teuchos::Ptr< T >::get ( ) const

inline

Get the raw C++ pointer to the underlying object.

Definition at line 87 of file Teuchos_Ptr.hpp.

template<class T >

T * Teuchos::Ptr< T >::getRawPtr ( ) const

inline

Get the raw C++ pointer to the underlying object.

Definition at line 95 of file Teuchos_Ptr.hpp.

template<class T >

bool Teuchos::Ptr< T >::is_null ( ) const

inline

Return true if the wrapped raw pointer is NULL, else return false.

Definition at line 111 of file Teuchos_Ptr.hpp.

template<class T >

const Ptr< T > & Teuchos::Ptr< T >::assert_not_null ( ) const

inline

Throws std::logic_error if this->get()==NULL, otherwise returns reference to *this.

Definition at line 102 of file Teuchos_Ptr.hpp.

template<class T >

const Ptr< T > Teuchos::Ptr< T >::ptr ( ) const

inline

Return a copy of *this.

Definition at line 117 of file Teuchos_Ptr.hpp.

template<class T >

Ptr< const T > Teuchos::Ptr< T >::getConst ( ) const

inline

Return a Ptr<const T> version of *this.

Definition at line 124 of file Teuchos_Ptr.hpp.

Friends And Related Function Documentation

template<typename T >

Ptr< T > outArg ( T & arg )

Definition at line 194 of file Teuchos_PtrDecl.hpp.

template<typename T >

Ptr< T > inOutArg ( T & arg )

Examples:: test/MemoryManagement/RCP_test.cpp.

Definition at line 206 of file Teuchos_PtrDecl.hpp.

template<typename T >

Ptr< T > inoutArg ( T & arg )

Definition at line 218 of file Teuchos_PtrDecl.hpp.

template<typename T >

Ptr< const T > ptrInArg ( T & arg )

Definition at line 230 of file Teuchos_PtrDecl.hpp.

template<typename T >

Ptr< T > optInArg ( T & arg )

Definition at line 242 of file Teuchos_PtrDecl.hpp.

template<typename T >

Ptr< const T > constOptInArg ( T & arg )

Definition at line 254 of file Teuchos_PtrDecl.hpp.

template<typename T >

Ptr< T > ptrFromRef ( T & arg )

Definition at line 265 of file Teuchos_PtrDecl.hpp.

template<typename T >

Ptr< T > ptr ( T * p )

Examples:: ArrayRCP_test.cpp.

Definition at line 296 of file Teuchos_PtrDecl.hpp.

template<typename T >

Ptr< const T > constPtr ( T & arg )

Warning! Do not call this function if T is already const or a compilation error will occur!

Definition at line 311 of file Teuchos_PtrDecl.hpp.

template<class T >

bool is_null ( const Ptr< T > & p )

Definition at line 322 of file Teuchos_PtrDecl.hpp.

template<class T >

bool nonnull ( const Ptr< T > & p )

Definition at line 333 of file Teuchos_PtrDecl.hpp.

template<class T >

bool operator==	(	const Ptr< T > &	p,
		ENull
	)

Definition at line 344 of file Teuchos_PtrDecl.hpp.

template<class T >

bool operator!=	(	const Ptr< T > &	p,
		ENull
	)

Definition at line 355 of file Teuchos_PtrDecl.hpp.

template<class T1 , class T2 >

bool operator==	(	const Ptr< T1 > &	p1,
		const Ptr< T2 > &	p2
	)

Definition at line 366 of file Teuchos_PtrDecl.hpp.

template<class T1 , class T2 >

bool operator!=	(	const Ptr< T1 > &	p1,
		const Ptr< T2 > &	p2
	)

Definition at line 378 of file Teuchos_PtrDecl.hpp.

template<class T2 , class T1 >

Ptr< T2 > ptr_implicit_cast ( const Ptr< T1 > & p1 )

The function will compile only if (T2* p2 = p1.get();) compiles.

This is to be used for conversions up an inheritance hierarchy and from non-const to const and any other standard implicit pointer conversions allowed by C++.

Definition at line 396 of file Teuchos_PtrDecl.hpp.

template<class T2 , class T1 >

Ptr< T2 > ptr_static_cast ( const Ptr< T1 > & p1 )

The function will compile only if (static_cast<T2*>(p1.get());) compiles.

This can safely be used for conversion down an inheritance hierarchy with polymorphic types only if dynamic_cast<T2>(p1.get()) == static_cast<T2>(p1.get()). If not then you have to use ptr_dynamic_cast<T2>(p1).

Definition at line 416 of file Teuchos_PtrDecl.hpp.

template<class T2 , class T1 >

Ptr< T2 > ptr_const_cast ( const Ptr< T1 > & p1 )

This function will compile only if (const_cast<T2*>(p1.get());) compiles.

Definition at line 431 of file Teuchos_PtrDecl.hpp.

template<class T2 , class T1 >

Ptr< T2 > ptr_dynamic_cast	(	const Ptr< T1 > &	p1,
		bool	throw_on_fail = `false`
	)

Parameters

p1	[in] The smart pointer casting from
throw_on_fail	[in] If `true` then if the cast fails (for `p1.get()!=NULL) then a std::bad_cast std::exception is thrown with a very informative error message.`

Postconditions:

If ( p1.get()!=NULL && throw_on_fail==true && dynamic_cast<T2*>(p1.get())==NULL ) == true then an std::bad_cast std::exception is thrown with a very informative error message.
If ( p1.get()!=NULL && dynamic_cast<T2*>(p1.get())!=NULL ) == true then return.get() == dynamic_cast<T2*>(p1.get()).
If ( p1.get()!=NULL && throw_on_fail==false && dynamic_cast<T2*>(p1.get())==NULL ) == true then return.get() == NULL.
If ( p1.get()==NULL ) == true then return.get() == NULL.

This function will compile only if (dynamic_cast<T2*>(p1.get());) compiles.

Definition at line 463 of file Teuchos_PtrDecl.hpp.

template<class T >

std::ostream & operator<<	(	std::ostream &	out,
		const Ptr< T > &	p
	)

The implementation of this function just print pointer addresses and therefore puts no restrictions on the data types involved.

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

Public Member Functions

Related Functions

Detailed Description

template<class T> class Teuchos::Ptr< T >

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

template<class T>
class Teuchos::Ptr< T >