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
ClonePtr &	operator= (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 >
ClonePtr &	operator= (const ClonePtr< U > &src)
	Copy assignment from a compatible ClonePtr. More...

ClonePtr &	operator= (ClonePtr &&src) noexcept
	Move assignment replaces the currently-held object by the source object, leaving the source empty. More...

template<class U >
ClonePtr &	operator= (ClonePtr< U > &&src) noexcept
	Move assignment from a compatible ClonePtr replaces the currently-held object by the source object, leaving the source empty. More...

ClonePtr &	operator= (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...

ClonePtr &	operator= (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

T	The 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
	)

(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
	)

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
	)

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
	)

◆ operator==() [3/3]

template<class T >

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

◆ operator<() [1/3]

template<class T , class U >

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

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
	)

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
	)

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
	)

◆ operator!=() [2/3]

template<class T >

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

◆ operator!=() [3/3]

template<class T >

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

◆ operator>() [1/3]

template<class T , class U >

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

◆ operator>() [2/3]

template<class T >

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

◆ operator>() [3/3]

template<class T >

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

◆ operator>=() [1/3]

template<class T , class U >

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

◆ operator>=() [2/3]

template<class T >

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

◆ operator>=() [3/3]

template<class T >

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

◆ operator<=() [1/3]

template<class T , class U >

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

◆ operator<=() [2/3]

template<class T >

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

◆ operator<=() [3/3]

template<class T >

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

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

ClonePtr.h

Public Types

Public Member Functions

Friends

Related Functions

Detailed Description

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

Member Typedef Documentation

◆ element_type

◆ pointer

◆ reference

Constructor & Destructor Documentation

◆ ClonePtr() [1/9]

◆ ClonePtr() [2/9]

◆ ClonePtr() [3/9]

◆ ClonePtr() [4/9]

◆ ClonePtr() [5/9]

◆ ClonePtr() [6/9]

◆ ClonePtr() [7/9]

◆ ClonePtr() [8/9]

◆ ClonePtr() [9/9]

◆ ~ClonePtr()

Member Function Documentation

◆ operator=() [1/6]

◆ operator=() [2/6]

◆ operator=() [3/6]

◆ operator=() [4/6]

◆ operator=() [5/6]

◆ operator=() [6/6]

◆ get()

◆ upd()

◆ getRef()

◆ updRef()

◆ operator->() [1/2]

◆ operator->() [2/2]

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ reset() [1/2]

◆ reset() [2/2]

◆ swap()

◆ empty()

◆ operator bool()

◆ release()

◆ getPtr()

◆ updPtr()

◆ clear()

Friends And Related Function Documentation

◆ ClonePtr

◆ swap()

◆ operator<<()

◆ operator==() [1/3]

◆ operator==() [2/3]

◆ operator==() [3/3]

◆ operator<() [1/3]

◆ operator<() [2/3]

◆ operator<() [3/3]

◆ operator!=() [1/3]

◆ operator!=() [2/3]

◆ operator!=() [3/3]

◆ operator>() [1/3]

◆ operator>() [2/3]

◆ operator>() [3/3]

◆ operator>=() [1/3]

◆ operator>=() [2/3]

◆ operator>=() [3/3]

◆ operator<=() [1/3]

◆ operator<=() [2/3]

◆ operator<=() [3/3]

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