SimTK::ReferencePtr< T > Class Template Reference

This is a smart pointer that implements "cross reference" semantics where a pointer data member of some object is intended to refer to some target object in a larger data structure. More...

Public Types
typedef T	element_type
	Type of the contained object. More...
typedef T *	pointer
	Type of a pointer to the contained object. More...
typedef T &	reference
	Type of a reference to the contained object. More...

Public Member Functions
Constructors
	ReferencePtr () noexcept
	Default constructor creates an empty object. More...
	ReferencePtr (std::nullptr_t) noexcept
	Constructor from nullptr is the same as the default constructor. More...
	ReferencePtr (T *tp) noexcept
	Construct from a given pointer stores the pointer. More...
	ReferencePtr (T &t) noexcept
	Construct from a reference stores the address of the supplied object. More...
	ReferencePtr (const ReferencePtr &) noexcept
	Copy constructor unconditionally sets the pointer to null; see class comments for why. More...
	ReferencePtr (ReferencePtr &&src) noexcept
	Move constructor copies the pointer from the source and leaves the source empty. More...
	ReferencePtr (int mustBeZero) noexcept
	(Deprecated) Use ReferencePtr(nullptr) or just ReferencePtr() instead. More...
Assignment
ReferencePtr &	operator= (const ReferencePtr &src) noexcept
	Copy assignment sets the pointer to nullptr (except for a self-assign); see class comments for why. More...
ReferencePtr &	operator= (ReferencePtr &&src) noexcept
	Move assignment copies the pointer from the source and leaves the source empty. More...
ReferencePtr &	operator= (T &t) noexcept
	This form of assignment replaces the currently-referenced object by a reference to the source object; no destruction occurs. More...
ReferencePtr &	operator= (T *tp) noexcept
	This form of assignment replaces the current pointer with the given one; no destruction occurs. More...
Destructor
	~ReferencePtr () noexcept
	Destructor does nothing. More...
Accessors
T *	get () const noexcept
	Return the contained pointer, or null if the container is empty. More...
T &	getRef () const
	Return a reference to the target object. More...
T *	operator-> () const
	Return the contained pointer. More...
T &	operator* () const
	The "dereference" operator returns a reference to the target object. More...
Utility Methods
void	reset (T *tp=nullptr) noexcept
	Replace the stored pointer with a different one; no destruction occurs. More...
void	swap (ReferencePtr &other) noexcept
	Swap the contents of this ReferencePtr with another one. More...
bool	empty () const noexcept
	Return true if this container is empty. More...
	operator bool () const noexcept
	This is a conversion to type bool that returns true if the container is non-null (that is, not empty). More...
T *	release () noexcept
	Extract the pointer from this container, leaving the container empty. More...
void	clear () noexcept
	(Deprecated) Use reset() instead. More...
	operator T* () const noexcept
	(Deprecated) Use get() rather than implicit conversion from ReferencePtr<T> to T*. More...

Related Functions
(Note that these are not member functions.)
template<class T >
void	swap (ReferencePtr< T > &p1, ReferencePtr< T > &p2) noexcept
	This is an overload of the STL std::swap() algorithm which uses the cheap built-in swap() member of the ReferencePtr class. More...
template<class charT , class traits , class T >
std::basic_ostream< charT, traits > &	operator<< (std::basic_ostream< charT, traits > &os, const ReferencePtr< T > &p)
	Output the system-dependent representation of the pointer contained in a ReferencePtr object. More...
template<class T , class U >
bool	operator== (const ReferencePtr< T > &lhs, const ReferencePtr< U > &rhs)
	Compare for equality the managed pointers contained in two compatible ReferencePtr containers. More...
template<class T >
bool	operator== (const ReferencePtr< T > &lhs, std::nullptr_t)
	Comparison against nullptr; same as lhs.empty(). More...
template<class T >
bool	operator== (std::nullptr_t, const ReferencePtr< T > &rhs)
	Comparison against nullptr; same as rhs.empty(). More...
template<class T , class U >
bool	operator< (const ReferencePtr< T > &lhs, const ReferencePtr< U > &rhs)
	Less-than operator for two compatible ReferencePtr containers, comparing the pointers, not the objects they point to. More...
template<class T >
bool	operator< (const ReferencePtr< T > &lhs, std::nullptr_t)
	Less-than comparison against a nullptr. More...
template<class T >
bool	operator< (std::nullptr_t, const ReferencePtr< T > &rhs)
	Less-than comparison of a nullptr against this container. More...
template<class T , class U >
bool	operator!= (const ReferencePtr< T > &lhs, const ReferencePtr< U > &rhs)
	Pointer inequality test defined as !(lhs==rhs). More...
template<class T >
bool	operator!= (const ReferencePtr< T > &lhs, std::nullptr_t)
	nullptr inequality test defined as !(lhs==nullptr). More...
template<class T >
bool	operator!= (std::nullptr_t, const ReferencePtr< T > &rhs)
	nullptr inequality test defined as !(nullptr==rhs). More...
template<class T , class U >
bool	operator> (const ReferencePtr< T > &lhs, const ReferencePtr< U > &rhs)
	Pointer greater-than test defined as rhs < lhs. More...
template<class T >
bool	operator> (const ReferencePtr< T > &lhs, std::nullptr_t)
	nullptr greater-than test defined as nullptr < lhs. More...
template<class T >
bool	operator> (std::nullptr_t, const ReferencePtr< T > &rhs)
	nullptr greater-than test defined as rhs < nullptr. More...
template<class T , class U >
bool	operator>= (const ReferencePtr< T > &lhs, const ReferencePtr< U > &rhs)
	Pointer greater-or-equal test defined as !(lhs < rhs). More...
template<class T >
bool	operator>= (const ReferencePtr< T > &lhs, std::nullptr_t)
	nullptr greater-or-equal test defined as !(lhs < nullptr). More...
template<class T >
bool	operator>= (std::nullptr_t, const ReferencePtr< T > &rhs)
	nullptr greater-or-equal test defined as !(nullptr < rhs). More...
template<class T , class U >
bool	operator<= (const ReferencePtr< T > &lhs, const ReferencePtr< U > &rhs)
	Pointer less-or-equal test defined as !(rhs < lhs) (note reversed arguments). More...
template<class T >
bool	operator<= (const ReferencePtr< T > &lhs, std::nullptr_t)
	nullptr less-or-equal test defined as !(nullptr < lhs) (note reversed arguments). More...
template<class T >
bool	operator<= (std::nullptr_t, const ReferencePtr< T > &rhs)
	nullptr less-or-equal test defined as !(rhs < nullptr) (note reversed arguments). More...
template<class T >
bool	operator!= (const ReferencePtr< T > &lhs, int mustBeZero)
	(Deprecated) Use nullptr instead of 0. More...

Detailed Description

template<class T>
class SimTK::ReferencePtr< T >

This is a smart pointer that implements "cross reference" semantics where a pointer data member of some object is intended to refer to some target object in a larger data structure.

Judicious use of this container will allow you to use compiler-generated copy constructors and copy assignment operators for classes which would otherwise have to implement their own in order to properly initialize these pointer data members, which must not be copied.

The contained pointer is initialized to nullptr on construction, and it is reinitialized to null upon copy construction or copy assignment. That's because we are assuming this is part of copying the entire data structure and copying the old pointer would create a reference into the old data structure rather than the new copy. This pointer does not own the target to which it points, and there is no reference counting so it will become stale if the target is deleted.

The pointer is moved intact for move construction or move assignment. That allows std::vector<ReferencePtr<T>> or SimTK::Array_<ReferencePtr<T>> to behave properly when their contents have to be moved for expansion.

Whether you can write through the pointer is controlled by whether type T is a const type. For example ReferencePtr<int> is equivalent to an int*, while ReferencePtr<const int> is equivalent to a const int*.

This class is entirely inline and has no computational or space overhead; it contains just a single pointer.

See also

ClonePtr, CloneOnWritePtr

Member Typedef Documentation

element_type

template<class T>

typedef T SimTK::ReferencePtr< T >::element_type

Type of the contained object.

pointer

template<class T>

typedef T* SimTK::ReferencePtr< T >::pointer

Type of a pointer to the contained object.

reference

template<class T>

typedef T& SimTK::ReferencePtr< T >::reference

Type of a reference to the contained object.

Constructor & Destructor Documentation

ReferencePtr() [1/7]

template<class T>

SimTK::ReferencePtr< T >::ReferencePtr ( )

inlinenoexcept

Default constructor creates an empty object.

ReferencePtr() [2/7]

template<class T>

SimTK::ReferencePtr< T >::ReferencePtr ( std::nullptr_t  )

inlinenoexcept

Constructor from nullptr is the same as the default constructor.

This is an implicit conversion that allows nullptr to be used to initialize a ReferencePtr.

ReferencePtr() [3/7]

template<class T>

SimTK::ReferencePtr< T >::ReferencePtr ( T *  tp )

inlineexplicitnoexcept

Construct from a given pointer stores the pointer.

ReferencePtr() [4/7]

template<class T>

SimTK::ReferencePtr< T >::ReferencePtr ( T &  t )

inlineexplicitnoexcept

Construct from a reference stores the address of the supplied object.

ReferencePtr() [5/7]

template<class T>

SimTK::ReferencePtr< T >::ReferencePtr ( const ReferencePtr< T > &  )

inlinenoexcept

Copy constructor unconditionally sets the pointer to null; see class comments for why.

ReferencePtr() [6/7]

template<class T>

SimTK::ReferencePtr< T >::ReferencePtr ( ReferencePtr< T > &&  src )

inlinenoexcept

Move constructor copies the pointer from the source and leaves the source empty.

ReferencePtr() [7/7]

template<class T>

SimTK::ReferencePtr< T >::ReferencePtr ( int  mustBeZero )

inlinenoexcept

(Deprecated) Use ReferencePtr(nullptr) or just ReferencePtr() instead.

For backwards compatibility, this allows initialization by "0" rather than nullptr.

~ReferencePtr()

template<class T>

SimTK::ReferencePtr< T >::~ReferencePtr ( )

inlinenoexcept

Destructor does nothing.

Member Function Documentation

operator=() [1/4]

template<class T>

ReferencePtr& SimTK::ReferencePtr< T >::operator= ( const ReferencePtr< T > &  src )

inlinenoexcept

Copy assignment sets the pointer to nullptr (except for a self-assign); see class comments for why.

operator=() [2/4]

template<class T>

ReferencePtr& SimTK::ReferencePtr< T >::operator= ( ReferencePtr< T > &&  src )

inlinenoexcept

Move assignment copies the pointer from the source and leaves the source empty.

Nothing happens for self-assign.

operator=() [3/4]

template<class T>

ReferencePtr& SimTK::ReferencePtr< T >::operator= ( T &  t )

inlinenoexcept

This form of assignment replaces the currently-referenced object by a reference to the source object; no destruction occurs.

operator=() [4/4]

template<class T>

ReferencePtr& SimTK::ReferencePtr< T >::operator= ( T *  tp )

inlinenoexcept

This form of assignment replaces the current pointer with the given one; no destruction occurs.

get()

template<class T>

T* SimTK::ReferencePtr< T >::get ( ) const

inlinenoexcept

Return the contained pointer, or null if the container is empty.

getRef()

template<class T>

T& SimTK::ReferencePtr< T >::getRef ( ) const

inline

Return a reference to the target object.

Fails if the pointer is null.

operator->()

template<class T>

T* SimTK::ReferencePtr< T >::operator-> ( ) const

inline

Return the contained pointer.

This will fail if the container is empty.

operator*()

template<class T>

T& SimTK::ReferencePtr< T >::operator* ( ) const

inline

The "dereference" operator returns a reference to the target object.

This will fail if the container is empty.

reset()

template<class T>

void SimTK::ReferencePtr< T >::reset ( T *  tp = nullptr )

inlinenoexcept

Replace the stored pointer with a different one; no destruction occurs.

swap()

template<class T>

void SimTK::ReferencePtr< T >::swap ( ReferencePtr< T > &  other )

inlinenoexcept

Swap the contents of this ReferencePtr with another one.

This is very fast.

empty()

template<class T>

bool SimTK::ReferencePtr< T >::empty ( ) const

inlinenoexcept

Return true if this container is empty.

operator bool()

template<class T>

SimTK::ReferencePtr< T >::operator bool ( ) const

inlineexplicitnoexcept

This is a conversion to type bool that returns true if the container is non-null (that is, not empty).

release()

template<class T>

T* SimTK::ReferencePtr< T >::release ( )

inlinenoexcept

Extract the pointer from this container, leaving the container empty.

The pointer is returned.

clear()

template<class T>

void SimTK::ReferencePtr< T >::clear ( )

inlinenoexcept

(Deprecated) Use reset() instead.

operator T*()

template<class T>

SimTK::ReferencePtr< T >::operator T* ( ) const

inlinenoexcept

(Deprecated) Use get() rather than implicit conversion from ReferencePtr<T> to T*.

Friends And Related Function Documentation

swap()

template<class T >

void swap ( ReferencePtr< T > &  p1, ReferencePtr< T > &  p2  )

related

This is an overload of the STL std::swap() algorithm which uses the cheap built-in swap() member of the ReferencePtr class.

(This function is defined in the SimTK namespace.)

operator<<()

template<class charT , class traits , class T >

std::basic_ostream< charT, traits > & operator<< ( std::basic_ostream< charT, traits > &  os, const ReferencePtr< T > &  p  )

related

Output the system-dependent representation of the pointer contained in a ReferencePtr object.

This is equivalent to os << p.get();.

operator==() [1/3]

template<class T , class U >

bool operator== ( const ReferencePtr< T > &  lhs, const ReferencePtr< U > &  rhs  )

related

Compare for equality the managed pointers contained in two compatible ReferencePtr containers.

Returns true if the pointers refer to the same object or if both are null. It must be possible for one of the pointer types T* and U* to be implicitly converted to the other.

operator==() [2/3]

template<class T >

bool operator== ( const ReferencePtr< T > &  lhs, std::nullptr_t    )

related

Comparison against nullptr; same as lhs.empty().

operator==() [3/3]

template<class T >

bool operator== ( std::nullptr_t  , const ReferencePtr< T > &  rhs  )

related

Comparison against nullptr; same as rhs.empty().

operator<() [1/3]

template<class T , class U >

bool operator< ( const ReferencePtr< T > &  lhs, const ReferencePtr< U > &  rhs  )

related

Less-than operator for two compatible ReferencePtr containers, comparing the pointers, not the objects they point to.

Returns true if the lhs pointer tests less than the rhs pointer. A null pointer tests less than any non-null pointer. It must be possible for one of the pointer types T* and U* to be implicitly converted to the other.

operator<() [2/3]

template<class T >

bool operator< ( const ReferencePtr< T > &  lhs, std::nullptr_t    )

related

Less-than comparison against a nullptr.

A null pointer tests less than any non-null pointer and equal to another null pointer, so this method always returns false.

operator<() [3/3]

template<class T >

bool operator< ( std::nullptr_t  , const ReferencePtr< T > &  rhs  )

related

Less-than comparison of a nullptr against this container.

A null pointer tests less than any non-null pointer and equal to another null pointer, so this method returns true unless the container is empty.

operator!=() [1/4]

template<class T , class U >

bool operator!= ( const ReferencePtr< T > &  lhs, const ReferencePtr< U > &  rhs  )

related

Pointer inequality test defined as !(lhs==rhs).

operator!=() [2/4]

template<class T >

bool operator!= ( const ReferencePtr< T > &  lhs, std::nullptr_t    )

related

nullptr inequality test defined as !(lhs==nullptr).

operator!=() [3/4]

template<class T >

bool operator!= ( std::nullptr_t  , const ReferencePtr< T > &  rhs  )

related

nullptr inequality test defined as !(nullptr==rhs).

operator>() [1/3]

template<class T , class U >

bool operator> ( const ReferencePtr< T > &  lhs, const ReferencePtr< U > &  rhs  )

related

Pointer greater-than test defined as rhs < lhs.

operator>() [2/3]

template<class T >

bool operator> ( const ReferencePtr< T > &  lhs, std::nullptr_t    )

related

nullptr greater-than test defined as nullptr < lhs.

operator>() [3/3]

template<class T >

bool operator> ( std::nullptr_t  , const ReferencePtr< T > &  rhs  )

related

nullptr greater-than test defined as rhs < nullptr.

operator>=() [1/3]

template<class T , class U >

bool operator>= ( const ReferencePtr< T > &  lhs, const ReferencePtr< U > &  rhs  )

related

Pointer greater-or-equal test defined as !(lhs < rhs).

operator>=() [2/3]

template<class T >

bool operator>= ( const ReferencePtr< T > &  lhs, std::nullptr_t    )

related

nullptr greater-or-equal test defined as !(lhs < nullptr).

operator>=() [3/3]

template<class T >

bool operator>= ( std::nullptr_t  , const ReferencePtr< T > &  rhs  )

related

nullptr greater-or-equal test defined as !(nullptr < rhs).

operator<=() [1/3]

template<class T , class U >

bool operator<= ( const ReferencePtr< T > &  lhs, const ReferencePtr< U > &  rhs  )

related

Pointer less-or-equal test defined as !(rhs < lhs) (note reversed arguments).

operator<=() [2/3]

template<class T >

bool operator<= ( const ReferencePtr< T > &  lhs, std::nullptr_t    )

related

nullptr less-or-equal test defined as !(nullptr < lhs) (note reversed arguments).

operator<=() [3/3]

template<class T >

bool operator<= ( std::nullptr_t  , const ReferencePtr< T > &  rhs  )

related

nullptr less-or-equal test defined as !(rhs < nullptr) (note reversed arguments).

operator!=() [4/4]

template<class T >

bool operator!= ( const ReferencePtr< T > &  lhs, int  mustBeZero  )

related

(Deprecated) Use nullptr instead of 0.

---

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

• ReferencePtr.h