Simbody  3.7
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
ReferencePtroperator= (const ReferencePtr &src) noexcept
 Copy assignment sets the pointer to nullptr (except for a self-assign); see class comments for why. More...
 
ReferencePtroperator= (ReferencePtr &&src) noexcept
 Move assignment copies the pointer from the source and leaves the source empty. More...
 
ReferencePtroperator= (T &t) noexcept
 This form of assignment replaces the currently-referenced object by a reference to the source object; no destruction occurs. More...
 
ReferencePtroperator= (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: