Simbody  3.6
SimTK::ClonePtr< T > Class Template Reference

Smart pointer with deep copy semantics. 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
 ClonePtr () noexcept
 Default constructor stores a nullptr. More...
 
 ClonePtr (std::nullptr_t) noexcept
 Constructor from nullptr is the same as the default constructor. More...
 
 ClonePtr (T *x) noexcept
 Given a pointer to a writable heap-allocated object, take over ownership of that object. More...
 
 ClonePtr (const T *x)
 Given a pointer to a read-only object, create a new heap-allocated copy of that object via its clone() method and make this ClonePtr the owner of the copy. More...
 
 ClonePtr (const T &x)
 Given a read-only reference to an object, create a new heap-allocated copy of that object via its clone() method and make this ClonePtr object the owner of the copy. More...
 
 ClonePtr (const ClonePtr &src)
 Copy constructor is deep; the new ClonePtr object contains a new copy of the object in the source, created via the source object's clone() method. More...
 
template<class U >
 ClonePtr (const ClonePtr< U > &src)
 Deep copy construction from a compatible ClonePtr. More...
 
 ClonePtr (ClonePtr &&src) noexcept
 Move constructor is very fast and leaves the source empty. More...
 
template<class U >
 ClonePtr (ClonePtr< U > &&src) noexcept
 Move construction from a compatible ClonePtr. More...
 
Assignment
ClonePtroperator= (const ClonePtr &src)
 Copy assignment replaces the currently-held object by a copy of the object held in the source container, created using the source object's clone() method. More...
 
template<class U >
ClonePtroperator= (const ClonePtr< U > &src)
 Copy assignment from a compatible ClonePtr. More...
 
ClonePtroperator= (ClonePtr &&src) noexcept
 Move assignment replaces the currently-held object by the source object, leaving the source empty. More...
 
template<class U >
ClonePtroperator= (ClonePtr< U > &&src) noexcept
 Move assignment from a compatible ClonePtr replaces the currently-held object by the source object, leaving the source empty. More...
 
ClonePtroperator= (const T &x)
 This form of assignment replaces the currently-held object by a heap-allocated copy of the source object, created using its clone() method. More...
 
ClonePtroperator= (T *x) noexcept
 This form of assignment replaces the currently-held object by the given source object and takes over ownership of the source object. More...
 
Destructor
 ~ClonePtr () noexcept
 Destructor deletes the contained object. More...
 
Accessors
const T * get () const noexcept
 Return a const pointer to the contained object if any, or nullptr. More...
 
T * upd () noexcept
 Return a writable pointer to the contained object if any, or nullptr. More...
 
const T & getRef () const
 Return a const reference to the contained object. More...
 
T & updRef ()
 Return a writable reference to the contained object. More...
 
const T * operator-> () const
 Dereference a const pointer to the contained object. More...
 
T * operator-> ()
 Dereference a writable pointer to the contained object. More...
 
const T & operator* () const
 This "dereference" operator returns a const reference to the contained object. More...
 
T & operator* ()
 Return a writable reference to the contained object. More...
 
Utility Methods
void reset () noexcept
 Make this container empty if it isn't already, destructing the contained object if there is one. More...
 
void reset (T *x) noexcept
 Replace the contents of this container with the supplied heap-allocated object, taking over ownership of that object and deleting the current one first if necessary. More...
 
void swap (ClonePtr &other) noexcept
 Swap the contents of this ClonePtr with another one, with ownership changing hands but no copying performed. More...
 
bool empty () const noexcept
 Return true if this container is empty, which is the state the container is in immediately after default construction and various other operations. 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
 Remove the contained object from management by this container and transfer ownership to the caller. More...
 
const T * getPtr () const noexcept
 (Deprecated) Same as get(). More...
 
T * updPtr () noexcept
 (Deprecated) Same as upd(). More...
 
void clear () noexcept
 (Deprecated) Use reset() instead. More...
 

Friends

template<class U >
class ClonePtr
 

Related Functions

(Note that these are not member functions.)

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

Detailed Description

template<class T>
class SimTK::ClonePtr< T >

Smart pointer with deep copy semantics.

This is similar to std::unique_ptr in that it does not permit shared ownership of the contained object. However, unlike std::unique_ptr, ClonePtr supports copy and assignment operations, by insisting that the contained object have a clone() method that returns a pointer to a heap-allocated deep copy of the concrete object. The API is modeled as closely as possible on the C++11 std::unique_ptr API. However, it always uses a default deleter. Also, in keeping with Simbody's careful distinction between writable and const access, and for compatibility with CloneOnWritePtr, the get() method is modified to return only a const pointer, with upd() (update) added to return a writable pointer.

This class is entirely inline and has no computational or space overhead except when cloning is required; it contains just a single pointer and does no reference counting.

Template Parameters
TThe type of the contained object, which must have a clone() method. May be an abstract or concrete type.
See also
CloneOnWritePtr, ReferencePtr

Member Typedef Documentation

◆ element_type

template<class T>
typedef T SimTK::ClonePtr< T >::element_type

Type of the contained object.

◆ pointer

template<class T>
typedef T* SimTK::ClonePtr< T >::pointer

Type of a pointer to the contained object.

◆ reference

template<class T>
typedef T& SimTK::ClonePtr< T >::reference

Type of a reference to the contained object.

Constructor & Destructor Documentation

◆ ClonePtr() [1/9]

template<class T>
SimTK::ClonePtr< T >::ClonePtr ( )
inlinenoexcept

Default constructor stores a nullptr.

No heap allocation is performed. The empty() method will return true when called on a default-constructed ClonePtr.

◆ ClonePtr() [2/9]

template<class T>
SimTK::ClonePtr< T >::ClonePtr ( 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 ClonePtr.

◆ ClonePtr() [3/9]

template<class T>
SimTK::ClonePtr< T >::ClonePtr ( T *  x)
inlineexplicitnoexcept

Given a pointer to a writable heap-allocated object, take over ownership of that object.

The clone() method is not invoked.

◆ ClonePtr() [4/9]

template<class T>
SimTK::ClonePtr< T >::ClonePtr ( const T *  x)
inlineexplicit

Given a pointer to a read-only object, create a new heap-allocated copy of that object via its clone() method and make this ClonePtr the owner of the copy.

Ownership of the original object is not affected. If the supplied pointer is null, the resulting ClonePtr will be empty.

◆ ClonePtr() [5/9]

template<class T>
SimTK::ClonePtr< T >::ClonePtr ( const T &  x)
inlineexplicit

Given a read-only reference to an object, create a new heap-allocated copy of that object via its clone() method and make this ClonePtr object the owner of the copy.

Ownership of the original object is not affected.

◆ ClonePtr() [6/9]

template<class T>
SimTK::ClonePtr< T >::ClonePtr ( const ClonePtr< T > &  src)
inline

Copy constructor is deep; the new ClonePtr object contains a new copy of the object in the source, created via the source object's clone() method.

If the source container is empty this one will be empty also.

◆ ClonePtr() [7/9]

template<class T>
template<class U >
SimTK::ClonePtr< T >::ClonePtr ( const ClonePtr< U > &  src)
inline

Deep copy construction from a compatible ClonePtr.

Type U* must be implicitly convertible to type T*. The new ClonePtr object contains a new copy of the object in the source, created via the source object's clone() method. If the source container is empty this one will be empty also.

◆ ClonePtr() [8/9]

template<class T>
SimTK::ClonePtr< T >::ClonePtr ( ClonePtr< T > &&  src)
inlinenoexcept

Move constructor is very fast and leaves the source empty.

Ownership is transferred from the source to the new ClonePtr. If the source was empty this one will be empty also. No heap activity occurs.

◆ ClonePtr() [9/9]

template<class T>
template<class U >
SimTK::ClonePtr< T >::ClonePtr ( ClonePtr< U > &&  src)
inlinenoexcept

Move construction from a compatible ClonePtr.

Type U* must be implicitly convertible to type T*. Ownership is transferred from the source to the new ClonePtr. If the source was empty this one will be empty also. No heap activity occurs.

◆ ~ClonePtr()

template<class T>
SimTK::ClonePtr< T >::~ClonePtr ( )
inlinenoexcept

Destructor deletes the contained object.

See also
reset()

Member Function Documentation

◆ operator=() [1/6]

template<class T>
ClonePtr& SimTK::ClonePtr< T >::operator= ( const ClonePtr< T > &  src)
inline

Copy assignment replaces the currently-held object by a copy of the object held in the source container, created using the source object's clone() method.

The currently-held object (if any) is deleted. If the source container is empty this one will be empty also after the assignment. Nothing happens if the source and destination are the same container.

◆ operator=() [2/6]

template<class T>
template<class U >
ClonePtr& SimTK::ClonePtr< T >::operator= ( const ClonePtr< U > &  src)
inline

Copy assignment from a compatible ClonePtr.

Type U* must be implicitly convertible to type T*. The currently-held object is replaced by a copy of the object held in the source container, created using the source object's clone() method. The currently-held object (if any) is deleted. If the source container is empty this one will be empty also after the assignment.

◆ operator=() [3/6]

template<class T>
ClonePtr& SimTK::ClonePtr< T >::operator= ( ClonePtr< T > &&  src)
inlinenoexcept

Move assignment replaces the currently-held object by the source object, leaving the source empty.

The currently-held object (if any) is deleted. The clone() method is not invoked. Nothing happens if the source and destination are the same containers.

◆ operator=() [4/6]

template<class T>
template<class U >
ClonePtr& SimTK::ClonePtr< T >::operator= ( ClonePtr< U > &&  src)
inlinenoexcept

Move assignment from a compatible ClonePtr replaces the currently-held object by the source object, leaving the source empty.

Type U* must be implicitly convertible to type T*. The currently-held object (if any) is deleted. The clone() method is not invoked.

◆ operator=() [5/6]

template<class T>
ClonePtr& SimTK::ClonePtr< T >::operator= ( const T &  x)
inline

This form of assignment replaces the currently-held object by a heap-allocated copy of the source object, created using its clone() method.

The currently-held object (if any) is deleted.

◆ operator=() [6/6]

template<class T>
ClonePtr& SimTK::ClonePtr< T >::operator= ( T *  x)
inlinenoexcept

This form of assignment replaces the currently-held object by the given source object and takes over ownership of the source object.

The currently-held object (if any) is deleted.

◆ get()

template<class T>
const T* SimTK::ClonePtr< T >::get ( ) const
inlinenoexcept

Return a const pointer to the contained object if any, or nullptr.

Note that this is different than get() for the standard smart pointers like std::unique_ptr which return a writable pointer. Use upd() here for that purpose.

See also
upd(), getRef()

◆ upd()

template<class T>
T* SimTK::ClonePtr< T >::upd ( )
inlinenoexcept

Return a writable pointer to the contained object if any, or nullptr.

Note that you need write access to this container in order to get write access to the object it contains.

See also
get(), updRef()

◆ getRef()

template<class T>
const T& SimTK::ClonePtr< T >::getRef ( ) const
inline

Return a const reference to the contained object.

Don't call this if this container is empty.

See also
get()

◆ updRef()

template<class T>
T& SimTK::ClonePtr< T >::updRef ( )
inline

Return a writable reference to the contained object.

Don't call this if this container is empty.

See also
upd()

◆ operator->() [1/2]

template<class T>
const T* SimTK::ClonePtr< T >::operator-> ( ) const
inline

Dereference a const pointer to the contained object.

This will fail if the container is empty.

◆ operator->() [2/2]

template<class T>
T* SimTK::ClonePtr< T >::operator-> ( )
inline

Dereference a writable pointer to the contained object.

This will fail if the container is empty.

◆ operator*() [1/2]

template<class T>
const T& SimTK::ClonePtr< T >::operator* ( ) const
inline

This "dereference" operator returns a const reference to the contained object.

This will fail if the container is empty.

◆ operator*() [2/2]

template<class T>
T& SimTK::ClonePtr< T >::operator* ( )
inline

Return a writable reference to the contained object.

This will fail if the container is empty.

◆ reset() [1/2]

template<class T>
void SimTK::ClonePtr< T >::reset ( )
inlinenoexcept

Make this container empty if it isn't already, destructing the contained object if there is one.

The container is restored to its default-constructed state.

See also
empty()

◆ reset() [2/2]

template<class T>
void SimTK::ClonePtr< T >::reset ( T *  x)
inlinenoexcept

Replace the contents of this container with the supplied heap-allocated object, taking over ownership of that object and deleting the current one first if necessary.

Nothing happens if the supplied pointer is the same as the one already being managed.

◆ swap()

template<class T>
void SimTK::ClonePtr< T >::swap ( ClonePtr< T > &  other)
inlinenoexcept

Swap the contents of this ClonePtr with another one, with ownership changing hands but no copying performed.

This is very fast; no heap activity occurs. Both containers must have been instantiated with the identical type.

◆ empty()

template<class T>
bool SimTK::ClonePtr< T >::empty ( ) const
inlinenoexcept

Return true if this container is empty, which is the state the container is in immediately after default construction and various other operations.

◆ operator bool()

template<class T>
SimTK::ClonePtr< 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::ClonePtr< T >::release ( )
inlinenoexcept

Remove the contained object from management by this container and transfer ownership to the caller.

A writable pointer to the object is returned. No object destruction occurs. This ClonePtr is left empty.

◆ getPtr()

template<class T>
const T* SimTK::ClonePtr< T >::getPtr ( ) const
inlinenoexcept

(Deprecated) Same as get().

Use get() instead; it is more like the API for std::unique_ptr.

◆ updPtr()

template<class T>
T* SimTK::ClonePtr< T >::updPtr ( )
inlinenoexcept

(Deprecated) Same as upd().

Use upd() instead; it is a better match for get() modeled after the API for std::unique_ptr.

◆ clear()

template<class T>
void SimTK::ClonePtr< T >::clear ( )
inlinenoexcept

(Deprecated) Use reset() instead.

Friends And Related Function Documentation

◆ ClonePtr

template<class T>
template<class U >
friend class ClonePtr
friend

◆ swap()

template<class T >
void swap ( ClonePtr< T > &  p1,
ClonePtr< T > &  p2 
)
related

This is an overload of the STL std::swap() algorithm which uses the cheap built-in swap() member of the ClonePtr 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 ClonePtr< T > &  p 
)
related

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

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

◆ operator==() [1/3]

template<class T , class U >
bool operator== ( const ClonePtr< T > &  lhs,
const ClonePtr< U > &  rhs 
)
related

Compare for equality the managed pointers contained in two compatible ClonePtr 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 ClonePtr< 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 ClonePtr< T > &  rhs 
)
related

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

◆ operator<() [1/3]

template<class T , class U >
bool operator< ( const ClonePtr< T > &  lhs,
const ClonePtr< U > &  rhs 
)
related

Less-than operator for two compatible ClonePtr 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 ClonePtr< 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 ClonePtr< 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/3]

template<class T , class U >
bool operator!= ( const ClonePtr< T > &  lhs,
const ClonePtr< U > &  rhs 
)
related

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

◆ operator!=() [2/3]

template<class T >
bool operator!= ( const ClonePtr< T > &  lhs,
std::nullptr_t   
)
related

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

◆ operator!=() [3/3]

template<class T >
bool operator!= ( std::nullptr_t  ,
const ClonePtr< T > &  rhs 
)
related

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

◆ operator>() [1/3]

template<class T , class U >
bool operator> ( const ClonePtr< T > &  lhs,
const ClonePtr< U > &  rhs 
)
related

Pointer greater-than test defined as rhs < lhs.

◆ operator>() [2/3]

template<class T >
bool operator> ( const ClonePtr< 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 ClonePtr< T > &  rhs 
)
related

nullptr greater-than test defined as rhs < nullptr.

◆ operator>=() [1/3]

template<class T , class U >
bool operator>= ( const ClonePtr< T > &  lhs,
const ClonePtr< U > &  rhs 
)
related

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

◆ operator>=() [2/3]

template<class T >
bool operator>= ( const ClonePtr< 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 ClonePtr< T > &  rhs 
)
related

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

◆ operator<=() [1/3]

template<class T , class U >
bool operator<= ( const ClonePtr< T > &  lhs,
const ClonePtr< U > &  rhs 
)
related

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

◆ operator<=() [2/3]

template<class T >
bool operator<= ( const ClonePtr< 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 ClonePtr< T > &  rhs 
)
related

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


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