Transient version of Amino::Ptr<T> which allows mutable access to the pointee. More...

#include <Ptr.h>

Inheritance diagram for Amino::MutablePtr< T >:

Public Types
using	element_type = typename Base::element_type
	The type of objects referenced by the Ptr pointer. More...

Public Member Functions
	MutablePtr (T *p)
	Construct a mutable pointer that owns the object pointed by `p`. More...

	MutablePtr (MutablePtr &&) noexcept=default
	Move constructor. More...

	MutablePtr (MutablePtr const &) noexcept=delete
	MutablePtr are not copy constructible. More...

template<class Y , class = if_convertible_from<Y>>
	MutablePtr (MutablePtr< Y > rhs) noexcept
	Move conversion construction from a MutablePtr of a compatible type Y. More...

	~MutablePtr ()
	Destructor. More...

MutablePtr &	operator= (MutablePtr &&) noexcept=default
	Move assignment. More...

MutablePtr &	operator= (MutablePtr const &) noexcept=delete
	MutablePtr are not copy assignable. More...

template<class Y , class = if_convertible_from<Y>>
MutablePtr &	operator= (MutablePtr< Y > rhs) noexcept
	Move conversion assignment from a MutablePtr of a compatible type Y. More...

	operator bool () const
	Returns whether the pointer is non-null. More...

void	reset ()
	Reset the pointer to an empty pointer. More...

void	swap (MutablePtr &rhs) noexcept
	Swap two pointers. More...

Ptr< T >	toImmutable () noexcept
	Conversion to a Ptr (immutable) More...

template<class Y , class >
MutablePtr< T > &	operator= (MutablePtr< Y > rhs) noexcept

Empty constructors
constexpr	MutablePtr () noexcept=default
	Construct an empty MutablePtr. More...

constexpr	MutablePtr (std::nullptr_t) noexcept
	Construct an empty MutablePtr. More...

Accessors
Indirection. Precondition the pointer must not be null or empty Returns the reference to the pointed object
T const &	operator* () const noexcept
	Indirection. More...

T &	operator* () noexcept
	Indirection. More...

T const *	operator-> () const noexcept
	Indirection. More...

T *	operator-> () noexcept
	Indirection. More...

T const *	get () const noexcept
	Accessor. More...

T *	get () noexcept
	Indirection. More...

Friends
template<typename Y >
class	Ptr
	Friendship to allow Ptr to call private constructor passing the control block. More...

template<typename Y >
class	MutablePtr

template<typename Y >
class	PtrGuard

Detailed Description

template<typename T>
class Amino::MutablePtr< T >

Transient version of Amino::Ptr<T> which allows mutable access to the pointee.

Warning: Amino::MutablePtr is NOT replacements for standard smart pointers (like std::unique_ptr). It is only meant to be used within Amino graphs. Therefore, if a value never needs to flow directly into the graph, a standard smart pointer (like std::unique_tr) should be used instead.

This class is similar to a std::unique_ptr<T> in the sense that it has unique ownership over the pointee. But it's different than std::unique_ptr<T> because it still has a control block. It is meant to be used as a TRANSIENT type. It is not meant to be stored in a class or a struct. It is meant to be short-lived to allow mutation on the pointee, but then giving ownership back to a Ptr. (The control block is kept to avoid its unnecessary and inefficient deallocation/reallocation and to ensure that information captured before type-erasure is preserved).

Amino::Ptr<MyClass> ptr = getMyClass();
 
// Can't mutate the pointee from the Ptr.
// I.e. The following code would not compile:
// ptr->modifyYourself();
 
// Must instead get a mutable version of it.
Amino::MutablePtr<MyClass> mutablePtr = ptr.toMutable();
 
// The pointee will have been cloned if necessary, that is if it's
// `use_count() > 1`. This is why it it now safe to mutate it without
// side effects on other referents.
mutablePtr->modifyYourself();
 
// Calling toMutable() clears the Ptr, effectively transferring ownership
// of the pointee to the MutablePtr.
assert(!ptr);
 
// Assign back to the Ptr once we're done mutating it.
ptr = std::move(mutablePtr);
 
// Or equivalently:
// ptr = mutablePtr.toImmutable();
 
assert(ptr);
assert(ptr.unique());

Equivalently, an Amino::PtrGuard<T> can be used for more convenience and safety.

Similarly to std::unique_ptr, MutablePtr are not copy constructible nor copy assignable. They are default constructible, move constructible and move assignable.

Template Parameters

T	The type of objects referenced by the MutablePtr pointer.

Definition at line 761 of file Ptr.h.

Member Typedef Documentation

◆ element_type

template<typename T >

using Amino::MutablePtr< T >::element_type = typename Base::element_type

The type of objects referenced by the Ptr pointer.

Definition at line 780 of file Ptr.h.

Constructor & Destructor Documentation

◆ MutablePtr() [1/6]

template<typename T >

constexpr Amino::MutablePtr< T >::MutablePtr ( )

constexprdefaultnoexcept

Construct an empty MutablePtr.

Postcondition: get() == nullptr

◆ MutablePtr() [2/6]

template<typename T >

constexpr Amino::MutablePtr< T >::MutablePtr ( std::nullptr_t )

inlineconstexprnoexcept

Construct an empty MutablePtr.

Postcondition: get() == nullptr

Definition at line 1323 of file Ptr.h.

◆ MutablePtr() [3/6]

template<typename T >

Amino::MutablePtr< T >::MutablePtr ( T * p )

inline

Construct a mutable pointer that owns the object pointed by p.

Definition at line 1329 of file Ptr.h.

◆ MutablePtr() [4/6]

template<typename T >

Amino::MutablePtr< T >::MutablePtr ( MutablePtr< T > && )

defaultnoexcept

Move constructor.

◆ MutablePtr() [5/6]

template<typename T >

Amino::MutablePtr< T >::MutablePtr ( MutablePtr< T > const & )

deletenoexcept

MutablePtr are not copy constructible.

◆ MutablePtr() [6/6]

template<typename T >

template<class Y , class >

Amino::MutablePtr< T >::MutablePtr ( MutablePtr< Y > rhs )

inlinenoexcept

Move conversion construction from a MutablePtr of a compatible type Y.

Definition at line 1337 of file Ptr.h.

◆ ~MutablePtr()

template<typename T >

Amino::MutablePtr< T >::~MutablePtr

inline

Destructor.

Definition at line 1345 of file Ptr.h.

Member Function Documentation

◆ get() [1/2]

template<typename T >

T const * Amino::MutablePtr< T >::get ( ) const

inlinenoexcept

Accessor.

Returns: the pointer to the pointed object

Definition at line 838 of file Ptr.h.

◆ get() [2/2]

template<typename T >

T * Amino::MutablePtr< T >::get ( )

inlinenoexcept

Indirection.

Precondition: the pointer must not be null

Returns: the pointer to the pointed object

Definition at line 839 of file Ptr.h.

◆ operator bool()

template<typename T >

Amino::MutablePtr< T >::operator bool ( ) const

inlineexplicit

Returns whether the pointer is non-null.

Returns: get() != 0

Definition at line 845 of file Ptr.h.

◆ operator*() [1/2]

template<typename T >

T const & Amino::MutablePtr< T >::operator* ( ) const

inlinenoexcept

Indirection.

Precondition: the pointer must not be null

Returns: the pointer to the pointed object

Definition at line 829 of file Ptr.h.

References Amino::Ptr< T >::get().

◆ operator*() [2/2]

template<typename T >

T & Amino::MutablePtr< T >::operator* ( )

inlinenoexcept

Indirection.

Precondition: the pointer must not be null

Returns: the pointer to the pointed object

Definition at line 830 of file Ptr.h.

References Amino::Ptr< T >::get().

◆ operator->() [1/2]

template<typename T >

T const * Amino::MutablePtr< T >::operator-> ( ) const

inlinenoexcept

Indirection.

Precondition: the pointer must not be null

Returns: the pointer to the pointed object

Definition at line 833 of file Ptr.h.

References Amino::Ptr< T >::get().

◆ operator->() [2/2]

template<typename T >

T * Amino::MutablePtr< T >::operator-> ( )

inlinenoexcept

Indirection.

Precondition: the pointer must not be null

Returns: the pointer to the pointed object

Definition at line 834 of file Ptr.h.

References Amino::Ptr< T >::get().

◆ operator=() [1/4]

template<typename T >

MutablePtr & Amino::MutablePtr< T >::operator= ( MutablePtr< T > && )

defaultnoexcept

Move assignment.

◆ operator=() [2/4]

template<typename T >

MutablePtr & Amino::MutablePtr< T >::operator= ( MutablePtr< T > const & )

deletenoexcept

MutablePtr are not copy assignable.

◆ operator=() [3/4]

template<typename T >

template<class Y , class = if_convertible_from<Y>>

MutablePtr & Amino::MutablePtr< T >::operator= ( MutablePtr< Y > rhs )

noexcept

Move conversion assignment from a MutablePtr of a compatible type Y.

◆ operator=() [4/4]

template<typename T >

template<class Y , class >

MutablePtr< T > & Amino::MutablePtr< T >::operator= ( MutablePtr< Y > rhs )

inlinenoexcept

Definition at line 1353 of file Ptr.h.

◆ reset()

template<typename T >

void Amino::MutablePtr< T >::reset ( )

inline

Reset the pointer to an empty pointer.

This is equivalent to *this = Ptr().

Postcondition: get() == nullptr; use_count() == 0

Definition at line 848 of file Ptr.h.

◆ swap()

template<typename T >

void Amino::MutablePtr< T >::swap ( MutablePtr< T > & rhs )

noexcept

Swap two pointers.

Exchanges the contents of the two Ptr.

Parameters

[in] rhs the pointer to swap with

Definition at line 1362 of file Ptr.h.

References Amino::swap().

◆ toImmutable()

template<typename T >

Amino::Ptr< T > Amino::MutablePtr< T >::toImmutable

noexcept

Conversion to a Ptr (immutable)

This member function allows one to convert a MutablePtr<X> to a Ptr<X>. This effectively only transfer ownership of the pointee to the Ptr. No copy of the pointee is made.

Note: This function can be useful to be explicit about the conversion, but it is effectively equivalent to creating a Ptr with a MutablePtr rvalue. In other words:

Amino::MutablePtr<T> mutablePtr = getMyMutablePtr();
 
// The following code:
Amino::Ptr<T> ptr = mutablePtr.toImmutable();
 
// Is equivalent to:
Amino::Ptr<T> ptr = std::move(mutablePtr);

Postcondition: get() == nullptr

Returns: a Ptr to the object

Definition at line 1369 of file Ptr.h.

References Amino::Ptr< T >::swap().

Friends And Related Function Documentation

◆ MutablePtr

template<typename T >

template<typename Y >

friend class MutablePtr

friend

Definition at line 899 of file Ptr.h.

◆ Ptr

template<typename T >

template<typename Y >

friend class Ptr

friend

Friendship to allow Ptr to call private constructor passing the control block.

Definition at line 896 of file Ptr.h.

◆ PtrGuard

template<typename T >

template<typename Y >

friend class PtrGuard

friend

Definition at line 902 of file Ptr.h.

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ element_type

Constructor & Destructor Documentation

◆ MutablePtr() [1/6]

◆ MutablePtr() [2/6]

◆ MutablePtr() [3/6]

◆ MutablePtr() [4/6]

◆ MutablePtr() [5/6]

◆ MutablePtr() [6/6]

◆ ~MutablePtr()

Member Function Documentation

◆ get() [1/2]

◆ get() [2/2]

◆ operator bool()

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator->() [1/2]

◆ operator->() [2/2]

◆ operator=() [1/4]

◆ operator=() [2/4]

◆ operator=() [3/4]

◆ operator=() [4/4]

◆ reset()

◆ swap()

◆ toImmutable()

Friends And Related Function Documentation

◆ MutablePtr

◆ Ptr

◆ PtrGuard