#include <copyable_unique_ptr.hpp>

Inheritance diagram for dai::copyable_unique_ptr< T >:

Public Member Functions
Constructors
	copyable_unique_ptr () noexcept

	copyable_unique_ptr (T *raw) noexcept

	copyable_unique_ptr (const T &value)

	copyable_unique_ptr (const copyable_unique_ptr &cu_ptr)

template<typename U >
	copyable_unique_ptr (const std::unique_ptr< U > &u_ptr)

	copyable_unique_ptr (copyable_unique_ptr &&cu_ptr) noexcept

	copyable_unique_ptr (std::unique_ptr< T > &&u_ptr) noexcept

template<typename U >
	copyable_unique_ptr (std::unique_ptr< U > &&u_ptr) noexcept

Assignment
copyable_unique_ptr &	operator= (T *raw) noexcept

copyable_unique_ptr &	operator= (const T &ref)

copyable_unique_ptr &	operator= (const copyable_unique_ptr &cu_ptr)

template<typename U >
copyable_unique_ptr &	operator= (const copyable_unique_ptr< U > &cu_ptr)

copyable_unique_ptr &	operator= (const std::unique_ptr< T > &src)

template<typename U >
copyable_unique_ptr &	operator= (const std::unique_ptr< U > &u_ptr)

copyable_unique_ptr &	operator= (copyable_unique_ptr &&cu_ptr) noexcept

template<typename U >
copyable_unique_ptr &	operator= (copyable_unique_ptr< U > &&cu_ptr) noexcept

copyable_unique_ptr &	operator= (std::unique_ptr< T > &&u_ptr) noexcept

template<typename U >
copyable_unique_ptr &	operator= (std::unique_ptr< U > &&u_ptr) noexcept

Observers

bool	empty () const noexcept

const T *	get () const noexcept

T *	get_mutable () noexcept

const T &	operator* () const

T &	operator* ()

Static Private Member Functions
template<class U >
static T *	CopyOrClone (const T *raw, std::false_type)

template<class U >
static T *	CopyOrClone (const T *raw, std::true_type)

static T *	CopyOrNull (const T *raw)

Related Functions
(Note that these are not member functions.)
template<class charT , class traits , class T >
std::basic_ostream< charT, traits > &	operator<< (std::basic_ostream< charT, traits > &os, const copyable_unique_ptr< T > &cu_ptr)

Detailed Description

template<typename T>
class dai::copyable_unique_ptr< T >

A 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, copyable_unique_ptr supports copy and assignment operations, by insisting that the contained object be "copyable". To be copyable, the class must have either an accessible copy constructor, or it must have an accessible clone method with signature

std::unique_ptr<Foo> Clone() const;

where Foo is the type of the managed object. By "accessible" we mean either that the copy constructor or clone method is public, or friend copyable_unique_ptr<Foo>; appears in Foo's class declaration.

Generally, the API is modeled as closely as possible on the C++ standard std::unique_ptr API and copyable_unique_ptr<T> is interoperable with unique_ptr<T> wherever that makes sense. However, there are some differences:

It always uses a default deleter.
There is no array version.
To allow for future copy-on-write optimizations, there is a distinction between writable and const access, the get() method is modified to return only a const pointer, with get_mutable() added to return a writable pointer. Furthermore, derefencing (operator*()) a mutable pointer will give a mutable reference (in so far as T is not declared const), and dereferencing a const pointer will give a const reference.

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

Usage

In the simplest use case, the instantiation type will match the type of object it references, e.g.:

copyable_unique_ptr<Foo> ptr = make_unique<Foo>(...);

In this case, as long Foo is deemed compatible, the behavior will be as expected, i.e., when ptr copies, it will contain a reference to a new instance of Foo.

copyable_unique_ptr can also be used with polymorphic classes – a copyable_unique_ptr, instantiated on a base class, references an instance of a derived class. When copying the object, we would want the copy to likewise contain an instance of the derived class. For example:

copyable_unique_ptr<Base> cu_ptr = make_unique<Derived>();
copyable_unique_ptr<Base> other_cu_ptr = cu_ptr;           // Triggers a copy.
is_dynamic_castable<Derived>(other_cu_ptr.get());          // Should be true.

This works for well-designed polymorphic classes.

Warning: Ill-formed polymorphic classes can lead to fatal type slicing of the referenced object, such that the new copy contains an instance of Base instead of Derived. Some mistakes that would lead to this degenerate behavior:

The Base class's Clone() implementation does not invoke the Derived class's implementation of a suitable virtual method.

Template Parameters

T	The type of the contained object, which must be copyable as defined above. May be an abstract or concrete type.

Definition at line 104 of file copyable_unique_ptr.hpp.

Constructor & Destructor Documentation

◆ copyable_unique_ptr() [1/8]

template<typename T >

dai::copyable_unique_ptr< T >::copyable_unique_ptr ( )

inlinenoexcept

Default constructor stores a nullptr. No heap allocation is performed. The empty() method will return true when called on a default-constructed copyable_unique_ptr.

Definition at line 112 of file copyable_unique_ptr.hpp.

◆ copyable_unique_ptr() [2/8]

template<typename T >

dai::copyable_unique_ptr< T >::copyable_unique_ptr ( T * raw )

inlineexplicitnoexcept

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

Definition at line 116 of file copyable_unique_ptr.hpp.

◆ copyable_unique_ptr() [3/8]

template<typename T >

dai::copyable_unique_ptr< T >::copyable_unique_ptr ( const T & value )

inlineexplicit

Constructs a unique instance of T as a copy of the provided model value.

Definition at line 120 of file copyable_unique_ptr.hpp.

◆ copyable_unique_ptr() [4/8]

template<typename T >

dai::copyable_unique_ptr< T >::copyable_unique_ptr ( const copyable_unique_ptr< T > & cu_ptr )

inline

Copy constructor is deep; the new copyable_unique_ptr object contains a new copy of the object in the source, created via the source object's copy constructor or Clone() method. If the source container is empty this one will be empty also.

Definition at line 126 of file copyable_unique_ptr.hpp.

◆ copyable_unique_ptr() [5/8]

template<typename T >

template<typename U >

dai::copyable_unique_ptr< T >::copyable_unique_ptr ( const std::unique_ptr & u_ptr )

inlineexplicit

Copy constructor from a standard unique_ptr of compatible type. The copy is deep; the new copyable_unique_ptr object contains a new copy of the object in the source, created via the source object's copy constructor or Clone() method. If the source container is empty this one will be empty also.

Definition at line 134 of file copyable_unique_ptr.hpp.

◆ copyable_unique_ptr() [6/8]

template<typename T >

dai::copyable_unique_ptr< T >::copyable_unique_ptr ( copyable_unique_ptr< T > && cu_ptr )

inlinenoexcept

Move constructor is very fast and leaves the source empty. Ownership is transferred from the source to the new copyable_unique_ptr. If the source was empty this one will be empty also. No heap activity occurs.

Definition at line 139 of file copyable_unique_ptr.hpp.

◆ copyable_unique_ptr() [7/8]

template<typename T >

dai::copyable_unique_ptr< T >::copyable_unique_ptr ( std::unique_ptr< T > && u_ptr )

inlineexplicitnoexcept

Move constructor from a standard unique_ptr. The move is very fast and leaves the source empty. Ownership is transferred from the source to the new copyable_unique_ptr. If the source was empty this one will be empty also. No heap activity occurs.

Definition at line 145 of file copyable_unique_ptr.hpp.

◆ copyable_unique_ptr() [8/8]

template<typename T >

template<typename U >

dai::copyable_unique_ptr< T >::copyable_unique_ptr ( std::unique_ptr && u_ptr )

inlineexplicitnoexcept

Move construction from a compatible standard unique_ptr. Type U* must be implicitly convertible to type T*. Ownership is transferred from the source to the new copyable_unique_ptr. If the source was empty this one will be empty also. No heap activity occurs.

Definition at line 152 of file copyable_unique_ptr.hpp.

Member Function Documentation

◆ CopyOrClone() [1/2]

template<typename T >

template<class U >

static T* dai::copyable_unique_ptr< T >::CopyOrClone	(	const T *	raw,
		std::false_type
	)

inlinestaticprivate

Definition at line 352 of file copyable_unique_ptr.hpp.

◆ CopyOrClone() [2/2]

template<typename T >

template<class U >

static T* dai::copyable_unique_ptr< T >::CopyOrClone	(	const T *	raw,
		std::true_type
	)

inlinestaticprivate

Definition at line 347 of file copyable_unique_ptr.hpp.

◆ CopyOrNull()

template<typename T >

static T* dai::copyable_unique_ptr< T >::CopyOrNull ( const T * raw )

inlinestaticprivate

Definition at line 360 of file copyable_unique_ptr.hpp.

◆ empty()

template<typename T >

bool dai::copyable_unique_ptr< 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.

Definition at line 272 of file copyable_unique_ptr.hpp.

◆ get()

template<typename T >

const T* dai::copyable_unique_ptr< 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 get_mutable() here for that purpose.

Definition at line 280 of file copyable_unique_ptr.hpp.

◆ get_mutable()

template<typename T >

T* dai::copyable_unique_ptr< T >::get_mutable ( )

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.

Warning: If copyable_unique_ptr is instantiated on a const template parameter (e.g., copyable_unique_ptr<const Foo>), then get_mutable() returns a const pointer.

Definition at line 294 of file copyable_unique_ptr.hpp.

◆ operator*() [1/2]

template<typename T >

T& dai::copyable_unique_ptr< T >::operator* ( )

inline

Return a writable reference to the contained object (if T is itself not const). Note that you need write access to this container in order to get write access to the object it contains.

We strongly recommend, that, if dereferencing a copyable_unique_ptr without the intention of mutating the underlying value, prefer to dereference a const copyable_unique_ptr (or use *my_ptr.get()) and not a mutable copyable_unique_ptr. As "copy-on-write" behavior is introduced in the future, this recommended practice will prevent unwanted copies of the underlying value.

If copyable_unique_ptr is instantiated on a const template parameter (e.g., copyable_unique_ptr<const Foo>), then operator*() must return a const reference.

Precondition: this != nullptr reports true.

Definition at line 340 of file copyable_unique_ptr.hpp.

◆ operator*() [2/2]

template<typename T >

const T& dai::copyable_unique_ptr< T >::operator* ( ) const

inline

Return a const reference to the contained object. Note that this is different from std::unique_ptr::operator*() which would return a non-const reference (if T is non-const), even if the container itself is const. For a const copyable_unique_ptr will always return a const reference to its contained value.

Warning: Currently copyable_unique_ptr is a std::unique_ptr. As such, a const copyable_unique_ptr<Foo> can be upcast to a const unique_ptr<Foo> and the parent's behavior will provide a mutable reference. This is strongly discouraged and will break as the implementation of this class changes to shore up this gap in the const correctness protection.

Precondition: this != nullptr reports true.

Definition at line 320 of file copyable_unique_ptr.hpp.

◆ operator=() [1/10]

template<typename T >

copyable_unique_ptr& dai::copyable_unique_ptr< T >::operator= ( const copyable_unique_ptr< T > & cu_ptr )

inline

Copy assignment from copyable_unique_ptr replaces the currently-held object by a copy of the object held in the source container, created using the source object's copy constructor or 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.

Definition at line 182 of file copyable_unique_ptr.hpp.

◆ operator=() [2/10]

template<typename T >

template<typename U >

copyable_unique_ptr& dai::copyable_unique_ptr< T >::operator= ( const copyable_unique_ptr & cu_ptr )

inline

Copy assignment from a compatible copyable_unique_ptr replaces the currently-held object by a copy of the object held in the source container, created using the source object's copy constructor or 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.

Definition at line 193 of file copyable_unique_ptr.hpp.

◆ operator=() [3/10]

template<typename T >

copyable_unique_ptr& dai::copyable_unique_ptr< T >::operator= ( const std::unique_ptr< T > & src )

inline

Copy assignment from a standard unique_ptr replaces the currently-held object by a copy of the object held in the source container, created using the source object's copy constructor or 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.

Definition at line 203 of file copyable_unique_ptr.hpp.

◆ operator=() [4/10]

template<typename T >

template<typename U >

copyable_unique_ptr& dai::copyable_unique_ptr< T >::operator= ( const std::unique_ptr & u_ptr )

inline

Copy assignment from a compatible standard unique_ptr replaces the currently-held object by a copy of the object held in the source container, created using the source object's copy constructor or 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.

Definition at line 219 of file copyable_unique_ptr.hpp.

◆ operator=() [5/10]

template<typename T >

copyable_unique_ptr& dai::copyable_unique_ptr< T >::operator= ( const T & ref )

inline

This form of assignment replaces the currently-held object by a heap-allocated copy of the source object, created using its copy constructor or Clone() method. The currently-held object (if any) is deleted.

Definition at line 171 of file copyable_unique_ptr.hpp.

◆ operator=() [6/10]

template<typename T >

copyable_unique_ptr& dai::copyable_unique_ptr< T >::operator= ( copyable_unique_ptr< T > && cu_ptr )

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 instance is not copied. Nothing happens if the source and destination are the same containers.

Definition at line 230 of file copyable_unique_ptr.hpp.

◆ operator=() [7/10]

template<typename T >

template<typename U >

copyable_unique_ptr& dai::copyable_unique_ptr< T >::operator= ( copyable_unique_ptr && cu_ptr )

inlinenoexcept

Move assignment replaces the currently-held object by the compatible source object, leaving the source empty. The currently-held object (if any) is deleted. The instance is not copied. Nothing happens if the source and destination are the same containers.

Definition at line 240 of file copyable_unique_ptr.hpp.

◆ operator=() [8/10]

template<typename T >

copyable_unique_ptr& dai::copyable_unique_ptr< T >::operator= ( std::unique_ptr< T > && u_ptr )

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 instance is not copied. Nothing happens if the source and destination are the same containers.

Definition at line 249 of file copyable_unique_ptr.hpp.

◆ operator=() [9/10]

template<typename T >

template<typename U >

copyable_unique_ptr& dai::copyable_unique_ptr< T >::operator= ( std::unique_ptr && u_ptr )

inlinenoexcept

Move assignment replaces the currently-held object by the compatible source object, leaving the source empty. The currently-held object (if any) is deleted. The instance is not copied. Nothing happens if the source and destination are the same containers.

Definition at line 259 of file copyable_unique_ptr.hpp.

◆ operator=() [10/10]

template<typename T >

copyable_unique_ptr& dai::copyable_unique_ptr< T >::operator= ( T * raw )

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.

Definition at line 162 of file copyable_unique_ptr.hpp.

Friends And Related Function Documentation

◆ operator<<()

template<class charT , class traits , class T >

std::basic_ostream< charT, traits > & operator<<	(	std::basic_ostream< charT, traits > &	os,
		const copyable_unique_ptr< T > &	cu_ptr
	)

Definition at line 374 of file copyable_unique_ptr.hpp.

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

copyable_unique_ptr.hpp

Public Member Functions

Static Private Member Functions

Related Functions

Detailed Description

template<typename T> class dai::copyable_unique_ptr< T >

Constructor & Destructor Documentation

◆ copyable_unique_ptr() [1/8]

◆ copyable_unique_ptr() [2/8]

◆ copyable_unique_ptr() [3/8]

◆ copyable_unique_ptr() [4/8]

◆ copyable_unique_ptr() [5/8]

◆ copyable_unique_ptr() [6/8]

◆ copyable_unique_ptr() [7/8]

◆ copyable_unique_ptr() [8/8]

Member Function Documentation

◆ CopyOrClone() [1/2]

◆ CopyOrClone() [2/2]

◆ CopyOrNull()

◆ empty()

◆ get()

◆ get_mutable()

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator=() [1/10]

◆ operator=() [2/10]

◆ operator=() [3/10]

◆ operator=() [4/10]

◆ operator=() [5/10]

◆ operator=() [6/10]

◆ operator=() [7/10]

◆ operator=() [8/10]

◆ operator=() [9/10]

◆ operator=() [10/10]

Friends And Related Function Documentation

◆ operator<<()

template<typename T>
class dai::copyable_unique_ptr< T >