[smartptr.adapt] - C++20 → C++23

Files changed (1) hide show

tmp/tmpzusq7x74/{from.md → to.md} +358 -0

tmp/tmpzusq7x74/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,358 @@

+### Smart pointer adaptors <a id="smartptr.adapt">[[smartptr.adapt]]</a>
+#### Class template `out_ptr_t` <a id="out.ptr.t">[[out.ptr.t]]</a>
+`out_ptr_t` is a class template used to adapt types such as smart
+pointers [[smartptr]] for functions that use output pointer parameters.
+[*Example 1*:
+``` cpp
+#include <memory>
+#include <cstdio>
+int fopen_s(std::FILE** f, const char* name, const char* mode);
+struct fclose_deleter {
+  void operator()(std::FILE* f) const noexcept {
+    std::fclose(f);
+  }
+};
+int main(int, char*[]) {
+  constexpr const char* file_name = "ow.o";
+  std::unique_ptr<std::FILE, fclose_deleter> file_ptr;
+  int err = fopen_s(std::out_ptr<std::FILE*>(file_ptr), file_name, "r+b");
+  if (err != 0)
+    return 1;
+  // *file_ptr is valid
+  return 0;
+}
+```
+`unique_ptr` can be used with `out_ptr` to be passed into an output
+pointer-style function, without needing to hold onto an intermediate
+pointer value and manually delete it on error or failure.
+— *end example*]
+``` cpp
+namespace std {
+  template<class Smart, class Pointer, class... Args>
+  class out_ptr_t {
+  public:
+    explicit out_ptr_t(Smart&, Args...);
+    out_ptr_t(const out_ptr_t&) = delete;
+    ~out_ptr_t();
+    operator Pointer*() const noexcept;
+    operator void**() const noexcept;
+  private:
+    Smart& s;                   // exposition only
+    tuple<Args...> a;           // exposition only
+    Pointer p;                  // exposition only
+  };
+}
+```
+`Pointer` shall meet the *Cpp17NullablePointer* requirements. If `Smart`
+is a specialization of `shared_ptr` and `sizeof...(Args) == 0`, the
+program is ill-formed.
+[*Note 1*: It is typically a user error to reset a `shared_ptr` without
+specifying a deleter, as `shared_ptr` will replace a custom deleter upon
+usage of `reset`, as specified in
+[[util.smartptr.shared.mod]]. — *end note*]
+Program-defined specializations of `out_ptr_t` that depend on at least
+one program-defined type need not meet the requirements for the primary
+template.
+Evaluations of the conversion functions on the same object may conflict
+[[intro.races]].
+``` cpp
+explicit out_ptr_t(Smart& smart, Args... args);
+```
+*Effects:* Initializes `s` with `smart`, `a` with
+`std::forward<Args>(args)...`, and value-initializes `p`. Then,
+equivalent to:
+- ``` cpp
+  s.reset();
+  ```
+  if the expression `s.reset()` is well-formed;
+- otherwise,
+  ``` cpp
+  s = Smart();
+  ```
+  if `is_constructible_v<Smart>` is `true`;
+- otherwise, the program is ill-formed.
+[*Note 1*: The constructor is not `noexcept` to allow for a variety of
+non-terminating and safe implementation strategies. For example, an
+implementation can allocate a `shared_ptr`’s internal node in the
+constructor and let implementation-defined exceptions escape safely. The
+destructor can then move the allocated control block in directly and
+avoid any other exceptions. — *end note*]
+``` cpp
+~out_ptr_t();
+```
+Let `SP` be *`POINTER_OF_OR`*`(Smart, Pointer)` [[memory.general]].
+*Effects:* Equivalent to:
+-
+  ``` cpp
+  if (p) {
+    apply([&](auto&&... args) {
+      s.reset(static_cast<SP>(p), std::forward<Args>(args)...); }, std::move(a));
+  }
+  ```
+  if the expression
+  `s.reset(static_cast<SP>(p), std::forward<Args>(args)...)` is
+  well-formed;
+- otherwise,
+  ``` cpp
+  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`;
+- otherwise, the program is ill-formed.
+``` cpp
+operator Pointer*() const noexcept;
+```
+*Preconditions:* `operator void**()` has not been called on `*this`.
+*Returns:* `addressof(const_cast<Pointer&>(p))`.
+``` cpp
+operator void**() const noexcept;
+```
+*Constraints:* `is_same_v<Pointer, void*>` is `false`.
+*Mandates:* `is_pointer_v<Pointer>` is `true`.
+*Preconditions:* `operator Pointer*()` has not been called on `*this`.
+*Returns:* A pointer value `v` such that:
+- the initial value `*v` is equivalent to `static_cast<void*>(p)` and
+- any modification of `*v` that is not followed by a subsequent
+  modification of `*this` affects the value of `p` during the
+  destruction of `*this`, such that `static_cast<void*>(p) == *v`.
+*Remarks:* Accessing `*v` outside the lifetime of `*this` has undefined
+behavior.
+[*Note 2*: `reinterpret_cast<void**>(static_cast<Pointer*>(*this))` can
+be a viable implementation strategy for some
+implementations. — *end note*]
+#### Function template `out_ptr` <a id="out.ptr">[[out.ptr]]</a>
+``` cpp
+template<class Pointer = void, class Smart, class... Args>
+  auto out_ptr(Smart& s, Args&&... args);
+```
+Let `P` be `Pointer` if `is_void_v<Pointer>` is `false`, otherwise
+*`POINTER_OF`*`(Smart)`.
+*Returns:*
+`out_ptr_t<Smart, P, Args&&...>(s, std::forward<Args>(args)...)`
+#### Class template `inout_ptr_t` <a id="inout.ptr.t">[[inout.ptr.t]]</a>
+`inout_ptr_t` is a class template used to adapt types such as smart
+pointers [[smartptr]] for functions that use output pointer parameters
+whose dereferenced values may first be deleted before being set to
+another allocated value.
+[*Example 1*:
+``` cpp
+#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-make
+  int 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. The original value will be properly deleted
+according to the function it is used with and a new value reset in its
+place.
+— *end example*]
+``` cpp
+namespace std {
+  template<class Smart, class Pointer, class... Args>
+  class inout_ptr_t {
+  public:
+    explicit inout_ptr_t(Smart&, Args...);
+    inout_ptr_t(const inout_ptr_t&) = delete;
+    ~inout_ptr_t();
+    operator Pointer*() const noexcept;
+    operator void**() const noexcept;
+  private:
+    Smart& s;                   // exposition only
+    tuple<Args...> a;           // exposition only
+    Pointer p;                  // exposition only
+  };
+}
+```
+`Pointer` shall meet the *Cpp17NullablePointer* requirements. If `Smart`
+is a specialization of `shared_ptr`, the program is ill-formed.
+[*Note 1*: It is impossible to properly acquire unique ownership of the
+managed resource from a `shared_ptr` given its shared ownership
+model. — *end note*]
+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.
+Evaluations of the conversion functions on the same object may conflict
+[[intro.races]].
+``` cpp
+explicit inout_ptr_t(Smart& smart, Args... args);
+```
+*Effects:* Initializes `s` with `smart`, `a` with
+`std::forward<Args>(args)...`, and `p` to either
+- `smart` if `is_pointer_v<Smart>` is `true`,
+- otherwise, `smart.get()`.
+*Remarks:* An implementation can call `s.release()`.
+[*Note 1*: The constructor is not `noexcept` to allow for a variety of
+non-terminating and safe implementation strategies. For example, an
+intrusive pointer implementation with a control block can allocate in
+the constructor and safely fail with an exception. — *end note*]
+``` cpp
+~inout_ptr_t();
+```
+Let `SP` be *`POINTER_OF_OR`*`(Smart, Pointer)` [[memory.general]].
+Let *release-statement* be `s.release();` if an implementation does not
+call `s.release()` in the constructor. Otherwise, it is empty.
+*Effects:* Equivalent to:
+-
+  ``` cpp
+  if (p) {
+    apply([&](auto&&... args) {
+      s = Smart( static_cast<SP>(p), std::forward<Args>(args)...); }, std::move(a));
+  }
+  ```
+  if `is_pointer_v<Smart>` is `true`;
+- otherwise,
+  ``` cpp
+  release-statement;
+  if (p) {
+    apply([&](auto&&... args) {
+      s.reset(static_cast<SP>(p), std::forward<Args>(args)...); }, std::move(a));
+  }
+  ```
+  if the expression
+  `s.reset(static_cast<SP>(p), std::forward<Args>(args)...)` is well-
+  formed;
+- otherwise,
+  ``` cpp
+  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`;
+- otherwise, the program is ill-formed.
+``` cpp
+operator Pointer*() const noexcept;
+```
+*Preconditions:* `operator void**()` has not been called on `*this`.
+*Returns:* `addressof(const_cast<Pointer&>(p))`.
+``` cpp
+operator void**() const noexcept;
+```
+*Constraints:* `is_same_v<Pointer, void*>` is `false`.
+*Mandates:* `is_pointer_v<Pointer>` is `true`.
+*Preconditions:* `operator Pointer*()` has not been called on `*this`.
+*Returns:* A pointer value `v` such that:
+- the initial value `*v` is equivalent to `static_cast<void*>(p)` and
+- 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`.
+*Remarks:* Accessing `*v` outside the lifetime of `*this` has undefined
+behavior.
+[*Note 2*: `reinterpret_cast<void**>(static_cast<Pointer*>(*this))` can
+be a viable implementation strategy for some
+implementations. — *end note*]
+#### Function template `inout_ptr` <a id="inout.ptr">[[inout.ptr]]</a>
+``` cpp
+template<class Pointer = void, class Smart, class... Args>
+  auto inout_ptr(Smart& s, Args&&... args);
+```
+Let `P` be `Pointer` if `is_void_v<Pointer>` is `false`, otherwise
+*`POINTER_OF`*`(Smart)`.
+*Returns:*
+`inout_ptr_t<Smart, P, Args&&...>(s, std::forward<Args>(args)...)`.

Diff to HTML by rtfpessoa