#include <Teuchos_Ptr.hpp>
Public Member Functions | |
Ptr (ENull null_in=null) | |
Default construct to NULL. | |
Ptr (T *ptr) | |
Construct given a raw pointer. | |
Ptr (const Ptr< T > &ptr) | |
Copy construct from same type. | |
template<class T2 > | |
Ptr (const Ptr< T2 > &ptr) | |
Copy construct from another type. | |
Ptr< T > & | operator= (const Ptr< T > &ptr) |
Shallow copy of the underlying pointer. | |
T * | operator-> () const |
Pointer (-> ) access to members of underlying object. | |
T & | operator* () const |
Dereference the underlying object. | |
T * | get () const |
Get the raw C++ pointer to the underlying object. | |
T * | getRawPtr () const |
Get the raw C++ pointer to the underlying object. | |
const Ptr< T > & | assert_not_null () const |
Throws std::logic_error if this->get()==NULL , otherwise returns reference to *this . | |
Related Functions | |
(Note that these are not member functions.) | |
template<typename T > | |
Ptr< T > | outArg (T &arg) |
create a non-persisting output argument for a function call. | |
template<typename T > | |
Ptr< const T > | ptrInArg (T &arg) |
create a general Ptr input argument for a function call from a reference. | |
template<typename T > | |
Ptr< T > | optInArg (T &arg) |
create a non-persisting const input argument for a function call. | |
template<typename T > | |
Ptr< const T > | constOptInArg (T &arg) |
create a non-persisting const input argument for a function call. | |
template<typename T > | |
Ptr< T > | ptrRef (T &arg) |
Create a pointer to a object from an object reference. | |
template<typename T > | |
Ptr< T > | ptr (T *p) |
Create a pointer to an object from a raw pointer. | |
template<typename T > | |
Ptr< const T > | constPtr (T &arg) |
Create a pointer from a const object given a non-const object reference. | |
template<class T > | |
bool | is_null (const Ptr< T > &p) |
Returns if is null or not. | |
template<class T > | |
bool | operator== (const Ptr< T > &p, ENull) |
Returns true if p.get()==NULL . | |
template<class T > | |
bool | operator!= (const Ptr< T > &p, ENull) |
Returns true if p.get()!=NULL . | |
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. | |
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. | |
template<class T2 , class T1 > | |
Ptr< T2 > | ptr_implicit_cast (const Ptr< T1 > &p1) |
Implicit cast of underlying Ptr type from T1* to T2* . | |
template<class T2 , class T1 > | |
Ptr< T2 > | ptr_static_cast (const Ptr< T1 > &p1) |
Static cast of underlying Ptr type from T1* to T2* . | |
template<class T2 , class T1 > | |
Ptr< T2 > | ptr_const_cast (const Ptr< T1 > &p1) |
Constant cast of underlying Ptr type from T1* to T2* . | |
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* . |
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 92 of file Teuchos_Ptr.hpp.
Teuchos::Ptr< T >::Ptr | ( | ENull | null_in = null |
) | [inline] |
Default construct to NULL.
Postconditons:
this->get() == NULL
Definition at line 446 of file Teuchos_Ptr.hpp.
Teuchos::Ptr< T >::Ptr | ( | T * | ptr | ) | [inline, explicit] |
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 ment to avoid cases where an uninitialized pointer is used to implicitly initialize one of these objects.
Definition at line 452 of file Teuchos_Ptr.hpp.
Teuchos::Ptr< T >::Ptr | ( | const Ptr< T > & | ptr | ) | [inline] |
Copy construct from same type.
Postconditons:
this->get() == ptr.get()
Definition at line 458 of file Teuchos_Ptr.hpp.
Copy construct from another type.
Postconditons:
this->get() == ptr.get()
(unless virtual base classes are involved) Definition at line 465 of file Teuchos_Ptr.hpp.
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 513 of file Teuchos_Ptr.hpp.
T * Teuchos::Ptr< T >::get | ( | ) | const [inline] |
T * Teuchos::Ptr< T >::getRawPtr | ( | ) | const [inline] |
T & Teuchos::Ptr< T >::operator* | ( | ) | const [inline] |
Dereference the underlying object.
Preconditions:
this->get() != NULL
(throws std::logic_error
) Definition at line 489 of file Teuchos_Ptr.hpp.
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 479 of file Teuchos_Ptr.hpp.
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 471 of file Teuchos_Ptr.hpp.
Ptr< const T > constOptInArg | ( | T & | arg | ) | [related] |
create a non-persisting const input argument for a function call.
Definition at line 215 of file Teuchos_Ptr.hpp.
Ptr< const T > constPtr | ( | T & | arg | ) | [related] |
Create a pointer from a const object given a non-const object reference.
Warning! Do not call this function of T
is already const or a compilation error will occur!
Definition at line 252 of file Teuchos_Ptr.hpp.
bool is_null | ( | const Ptr< T > & | p | ) | [related] |
bool operator!= | ( | const Ptr< T1 > & | p1, | |
const Ptr< T2 > & | p2 | |||
) | [related] |
Return true if two Ptr
objects do not point to the same object.
Definition at line 312 of file Teuchos_Ptr.hpp.
bool operator== | ( | const Ptr< T1 > & | p1, | |
const Ptr< T2 > & | p2 | |||
) | [related] |
Return true if two Ptr
objects point to the same object.
Definition at line 300 of file Teuchos_Ptr.hpp.
Ptr< T > optInArg | ( | T & | arg | ) | [related] |
create a non-persisting const input argument for a function call.
Definition at line 204 of file Teuchos_Ptr.hpp.
Ptr< T > outArg | ( | T & | arg | ) | [related] |
create a non-persisting output argument for a function call.
Definition at line 181 of file Teuchos_Ptr.hpp.
Ptr< T > ptr | ( | T * | p | ) | [related] |
Constant cast of underlying Ptr
type from T1*
to T2*
.
This function will compile only if (const_cast<T2*>(p1.get());
) compiles.
Definition at line 365 of file Teuchos_Ptr.hpp.
Ptr< T2 > ptr_dynamic_cast | ( | const Ptr< T1 > & | p1, | |
bool | throw_on_fail = false | |||
) | [related] |
Dynamic cast of underlying Ptr
type from T1*
to T2*
.
p1 | [in] The smart pointer casting from | |
throw_on_fail | [in] If true then if the cast fails (for p1.get()!=NULL) then a |
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 397 of file Teuchos_Ptr.hpp.
Implicit cast of underlying Ptr
type from T1*
to T2*
.
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 330 of file Teuchos_Ptr.hpp.
Static cast of underlying Ptr
type from T1*
to T2*
.
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 350 of file Teuchos_Ptr.hpp.
Ptr< const T > ptrInArg | ( | T & | arg | ) | [related] |
create a general Ptr
input argument for a function call from a reference.
Definition at line 193 of file Teuchos_Ptr.hpp.
Ptr< T > ptrRef | ( | T & | arg | ) | [related] |
Create a pointer to a object from an object reference.
Definition at line 226 of file Teuchos_Ptr.hpp.