[inout.ptr.t]

# 20 Memory management library [[mem]](./#mem)

## 20.3 Smart pointers [[smartptr]](smartptr#inout.ptr.t)

### 20.3.4 Smart pointer adaptors [[smartptr.adapt]](smartptr.adapt#inout.ptr.t)

#### 20.3.4.3 Class template inout_ptr_t [inout.ptr.t]

[1](#1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5662)

inout_ptr_t is a class template used to adapt types
such as smart pointers ([[smartptr]](smartptr "20.3 Smart pointers"))
for functions that use output pointer parameters
whose dereferenced values may first be deleted
before being set to another allocated value[.](#1.sentence-1)

[2](#2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5669)

[*Example [1](#example-1)*: #include <memory>struct star_fish* star_fish_alloc();int star_fish_populate(struct star_fish** ps, const char* description);

struct star_fish_deleter {void operator() (struct star_fish* c) const noexcept;};

using star_fish_ptr = std::unique_ptr<star_fish, star_fish_deleter>;

int main(int, char*[]) { star_fish_ptr peach(star_fish_alloc()); // ...// used, need to re-makeint err = star_fish_populate(std::inout_ptr(peach), "caring clown-fish liker"); return err;}

A unique_ptr can be used with inout_ptr to be passed into an output pointer-style function[.](#2.sentence-1)

The original value will be properly deleted
according to the function it is used with and
a new value reset in its place[.](#2.sentence-2)

â *end example*]

[ð](#lib:inout_ptr_t)

namespace std {template<class Smart, class Pointer, class... Args>class inout_ptr_t {public:constexpr explicit inout_ptr_t(Smart&, Args...);
 inout_ptr_t(const inout_ptr_t&) = delete; constexpr ~inout_ptr_t(); constexpr operator Pointer*() const noexcept; operator void**() const noexcept; private: Smart& s; // *exposition only* tuple<Args...> a; // *exposition only* Pointer p; // *exposition only*};}

[3](#3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5720)

Pointer shall meet the [*Cpp17NullablePointer*](nullablepointer.requirements#:Cpp17NullablePointer "16.4.4.4 Cpp17NullablePointer requirements [nullablepointer.requirements]") requirements[.](#3.sentence-1)

If Smart is a specialization of shared_ptr,
the program is ill-formed[.](#3.sentence-2)

[*Note [1](#note-1)*:

It is impossible to properly acquire unique ownership of the managed resource
from a shared_ptr given its shared ownership model[.](#3.sentence-3)

â *end note*]

[4](#4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5729)

Program-defined specializations of inout_ptr_t that depend on at least one program-defined type
need not meet the requirements for the primary template[.](#4.sentence-1)

[5](#5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5734)

Evaluations of the conversion functions on the same object
may conflict ([[intro.races]](intro.races "6.10.2.2 Data races"))[.](#5.sentence-1)

[ð](#lib:inout_ptr_t,constructor)

`constexpr explicit inout_ptr_t(Smart& smart, Args... args);
`

[6](#6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5744)

*Effects*: Initializes s with smart,a with std​::​forward<Args>(args)..., andp to either

- [(6.1)](#6.1)

smart if is_pointer_v<Smart> is true,

- [(6.2)](#6.2)

otherwise, smart.get()[.](#6.sentence-1)

[7](#7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5754)

*Remarks*: An implementation can call s.release()[.](#7.sentence-1)

[8](#8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5758)

[*Note [2](#note-2)*:

The constructor is not noexcept to allow for a variety of non-terminating and safe implementation strategies[.](#8.sentence-1)

For example, an intrusive pointer implementation with a control block
can allocate in the constructor and safely fail with an exception[.](#8.sentence-2)

â *end note*]

[ð](#lib:inout_ptr_t,destructor)

`constexpr ~inout_ptr_t();
`

[9](#9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5773)

Let SP be*POINTER_OF_OR*(Smart, Pointer) ([[memory.general]](memory.general "20.2.1 General"))[.](#9.sentence-1)

[10](#10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5777)

Let *release-statement* be s.release(); if an implementation does not call s.release() in the constructor[.](#10.sentence-1)

Otherwise, it is empty[.](#10.sentence-2)

[11](#11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5782)

*Effects*: Equivalent to:

- [(11.1)](#11.1)

apply([&](auto&&... args) { s = Smart(static_cast<SP>(p), std::forward<Args>(args)...); }, std::move(a)); if is_pointer_v<Smart> is true;

- [(11.2)](#11.2)

otherwise,*release-statement*;if (p) { apply([&](auto&&... args) { s.reset(static_cast<SP>(p), std::forward<Args>(args)...); }, std::move(a));} if the expressions.reset(static_cast<SP>(p), std​::​forward<Args>(args)...) is well-  
formed;

- [(11.3)](#11.3)

otherwise,*release-statement*;if (p) { apply([&](auto&&... args) { s = Smart(static_cast<SP>(p), std::forward<Args>(args)...); }, std::move(a));} if is_constructible_v<Smart, SP, Args...> is true;

- [(11.4)](#11.4)

otherwise, the program is ill-formed[.](#11.sentence-1)

[ð](#itemdecl:3)

`constexpr operator Pointer*() const noexcept;
`

[12](#12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5826)

*Preconditions*: operator void**() has not been called on *this[.](#12.sentence-1)

[13](#13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5830)

*Returns*: addressof(const_cast<Pointer&>(p))[.](#13.sentence-1)

[ð](#itemdecl:4)

`operator void**() const noexcept;
`

[14](#14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5840)

*Constraints*: is_same_v<Pointer, void*> is false[.](#14.sentence-1)

[15](#15)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5844)

*Mandates*: is_pointer_v<Pointer> is true[.](#15.sentence-1)

[16](#16)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5848)

*Preconditions*: operator Pointer*() has not been called on *this[.](#16.sentence-1)

[17](#17)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5852)

*Returns*: A pointer value v such that:

- [(17.1)](#17.1)

the initial value *v is equivalent to static_cast<void*>(p) and

- [(17.2)](#17.2)

any modification of *v that is not followed by subsequent modification of *this affects the value of p during the destruction of *this,
such that static_cast<void*>(p) == *v[.](#17.sentence-1)

[18](#18)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5865)

*Remarks*: Accessing *v outside the lifetime of *this has undefined behavior[.](#18.sentence-1)

[19](#19)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/memory.tex#L5870)

[*Note [3](#note-3)*:

reinterpret_cast<void**>(static_cast<Pointer*>(*this)) can be a viable implementation strategy for some implementations[.](#19.sentence-1)

â *end note*]
