[util.smartptr.shared] - C++20 → C++23

Files changed (1) hide show

tmp/tmp4jkfpwnx/{from.md → to.md} +73 -66

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

@@ -1,6 +1,8 @@
-### Class template `shared_ptr` <a id="util.smartptr.shared">[[util.smartptr.shared]]</a>
 The `shared_ptr` class template stores a pointer, usually obtained via
 `new`. `shared_ptr` implements semantics of shared ownership; the last
 remaining owner of the pointer is responsible for destroying the object,
 or otherwise releasing the resources associated with the stored pointer.
@@ -90,11 +92,11 @@ in standard containers. Specializations of `shared_ptr` shall be
 contextually convertible to `bool`, allowing their use in boolean
 expressions and declarations in conditions.
 The template parameter `T` of `shared_ptr` may be an incomplete type.
-[*Note 1*: `T` may be a function type. — *end note*]
 [*Example 1*:
 ``` cpp
 if (shared_ptr<X> px = dynamic_pointer_cast<X>(py)) {
@@ -112,11 +114,11 @@ races.
 For the purposes of subclause [[smartptr]], a pointer type `Y*` is said
 to be *compatible with* a pointer type `T*` when either `Y*` is
 convertible to `T*` or `Y` is `U[N]` and `T` is cv `U[]`.
-#### Constructors <a id="util.smartptr.shared.const">[[util.smartptr.shared.const]]</a>
 In the constructor definitions below, enables `shared_from_this` with
 `p`, for a pointer `p` of type `Y*`, means that if `Y` has an
 unambiguous and accessible base class that is a specialization of
 `enable_shared_from_this` [[util.smartptr.enab]], then `remove_cv_t<Y>*`
@@ -140,18 +142,18 @@ constexpr shared_ptr() noexcept;
 ``` cpp
 template<class Y> explicit shared_ptr(Y* p);
 ```
-*Mandates:* `Y` is a complete type.
 *Constraints:* When `T` is an array type, the expression `delete[] p` is
 well-formed and either `T` is `U[N]` and `Y(*)[N]` is convertible to
 `T*`, or `T` is `U[]` and `Y(*)[]` is convertible to `T*`. When `T` is
 not an array type, the expression `delete p` is well-formed and `Y*` is
 convertible to `T*`.
 *Preconditions:* The expression `delete[] p`, when `T` is an array type,
 or `delete p`, when `T` is not an array type, has well-defined behavior,
 and does not throw exceptions.
 *Effects:* When `T` is not an array type, constructs a `shared_ptr`
@@ -162,11 +164,11 @@ with `p`. If an exception is thrown, `delete p` is called when `T` is
 not an array type, `delete[] p` otherwise.
 *Ensures:* `use_count() == 1 && get() == p`.
 *Throws:* `bad_alloc`, or an *implementation-defined* exception when a
-resource other than memory could not be obtained.
 ``` cpp
 template<class Y, class D> shared_ptr(Y* p, D d);
 template<class Y, class D, class A> shared_ptr(Y* p, D d, A a);
 template<class D> shared_ptr(nullptr_t p, D d);
@@ -182,22 +184,23 @@ well-formed expression. For the first two overloads:
 - If `T` is not an array type, then `Y*` is convertible to `T*`.
 *Preconditions:* Construction of `d` and a deleter of type `D`
 initialized with `std::move(d)` do not throw exceptions. The expression
 `d(p)` has well-defined behavior and does not throw exceptions. `A`
-meets the *Cpp17Allocator* requirements ([[cpp17.allocator]]).
 *Effects:* Constructs a `shared_ptr` object that owns the object `p` and
 the deleter `d`. When `T` is not an array type, the first and second
 constructors enable `shared_from_this` with `p`. The second and fourth
 constructors shall use a copy of `a` to allocate memory for internal
 use. If an exception is thrown, `d(p)` is called.
 *Ensures:* `use_count() == 1 && get() == p`.
 *Throws:* `bad_alloc`, or an *implementation-defined* exception when a
-resource other than memory could not be obtained.
 ``` cpp
 template<class Y> shared_ptr(const shared_ptr<Y>& r, element_type* p) noexcept;
 template<class Y> shared_ptr(shared_ptr<Y>&& r, element_type* p) noexcept;
 ```
@@ -206,13 +209,13 @@ template<class Y> shared_ptr(shared_ptr<Y>&& r, element_type* p) noexcept;
 ownership with the initial value of `r`.
 *Ensures:* `get() == p`. For the second overload, `r` is empty and
 `r.get() == nullptr`.
-[*Note 1*: To avoid the possibility of a dangling pointer, the user of
-this constructor should ensure that `p` remains valid at least until the
-ownership group of `r` is destroyed. — *end note*]
 [*Note 2*: This constructor allows creation of an empty `shared_ptr`
 instance with a non-null stored pointer. — *end note*]
 ``` cpp
@@ -235,12 +238,12 @@ template<class Y> shared_ptr(shared_ptr<Y>&& r) noexcept;
 *Constraints:* For the second constructor, `Y*` is compatible with `T*`.
 *Effects:* Move constructs a `shared_ptr` instance from `r`.
-*Ensures:* `*this` shall contain the old value of `r`. `r` shall be
-empty. `r.get() == nullptr`.
 ``` cpp
 template<class Y> explicit shared_ptr(const weak_ptr<Y>& r);
 ```
@@ -261,15 +264,15 @@ template<class Y, class D> shared_ptr(unique_ptr<Y, D>&& r);
 *Constraints:* `Y*` is compatible with `T*` and
 `unique_ptr<Y, D>::pointer` is convertible to `element_type*`.
 *Effects:* If `r.get() == nullptr`, equivalent to `shared_ptr()`.
 Otherwise, if `D` is not a reference type, equivalent to
-`shared_ptr(r.release(), r.get_deleter())`. Otherwise, equivalent to
-`shared_ptr(r.release(), ref(r.get_deleter()))`. If an exception is
-thrown, the constructor has no effect.
-#### Destructor <a id="util.smartptr.shared.dest">[[util.smartptr.shared.dest]]</a>
 ``` cpp
 ~shared_ptr();
 ```
@@ -279,42 +282,42 @@ thrown, the constructor has no effect.
   instance (`use_count() > 1`), there are no side effects.
 - Otherwise, if `*this` owns an object `p` and a deleter `d`, `d(p)` is
   called.
 - Otherwise, `*this` owns a pointer `p`, and `delete p` is called.
-[*Note 1*: Since the destruction of `*this` decreases the number of
 instances that share ownership with `*this` by one, after `*this` has
 been destroyed all `shared_ptr` instances that shared ownership with
 `*this` will report a `use_count()` that is one less than its previous
 value. — *end note*]
-#### Assignment <a id="util.smartptr.shared.assign">[[util.smartptr.shared.assign]]</a>
 ``` cpp
 shared_ptr& operator=(const shared_ptr& r) noexcept;
 template<class Y> shared_ptr& operator=(const shared_ptr<Y>& r) noexcept;
 ```
 *Effects:* Equivalent to `shared_ptr(r).swap(*this)`.
 *Returns:* `*this`.
-[*Note 1*:
 The use count updates caused by the temporary object construction and
-destruction are not observable side effects, so the implementation may
 meet the effects (and the implied guarantees) via different means,
 without creating a temporary. In particular, in the example:
 ``` cpp
 shared_ptr<int> p(new int);
 shared_ptr<void> q(p);
 p = p;
 q = p;
 ```
-both assignments may be no-ops.
 — *end note*]
 ``` cpp
 shared_ptr& operator=(shared_ptr&& r) noexcept;
@@ -331,11 +334,11 @@ template<class Y, class D> shared_ptr& operator=(unique_ptr<Y, D>&& r);
 *Effects:* Equivalent to `shared_ptr(std::move(r)).swap(*this)`.
 *Returns:* `*this`.
-#### Modifiers <a id="util.smartptr.shared.mod">[[util.smartptr.shared.mod]]</a>
 ``` cpp
 void swap(shared_ptr& r) noexcept;
 ```
@@ -363,11 +366,11 @@ template<class Y, class D> void reset(Y* p, D d);
 template<class Y, class D, class A> void reset(Y* p, D d, A a);
 ```
 *Effects:* Equivalent to `shared_ptr(p, d, a).swap(*this)`.
-#### Observers <a id="util.smartptr.shared.obs">[[util.smartptr.shared.obs]]</a>
 ``` cpp
 element_type* get() const noexcept;
 ```
@@ -375,11 +378,11 @@ element_type* get() const noexcept;
 ``` cpp
 T& operator*() const noexcept;
 ```
-*Preconditions:* `get() != 0`.
 *Returns:* `*get()`.
 *Remarks:* When `T` is an array type or cv `void`, it is unspecified
 whether this member function is declared. If it is declared, it is
@@ -389,11 +392,11 @@ well-formed.
 ``` cpp
 T* operator->() const noexcept;
 ```
-*Preconditions:* `get() != 0`.
 *Returns:* `get()`.
 *Remarks:* When `T` is an array type, it is unspecified whether this
 member function is declared. If it is declared, it is unspecified what
@@ -402,47 +405,47 @@ necessarily the definition) of the function shall be well-formed.
 ``` cpp
 element_type& operator[](ptrdiff_t i) const;
 ```
-*Preconditions:* `get() != 0 && i >= 0`. If `T` is `U[N]`, `i < N`.
 *Returns:* `get()[i]`.
-*Remarks:* When `T` is not an array type, it is unspecified whether this
-member function is declared. If it is declared, it is unspecified what
-its return type is, except that the declaration (although not
-necessarily the definition) of the function shall be well-formed.
 *Throws:* Nothing.
 ``` cpp
 long use_count() const noexcept;
 ```
 *Returns:* The number of `shared_ptr` objects, `*this` included, that
 share ownership with `*this`, or `0` when `*this` is empty.
-*Synchronization:* None.
-[*Note 1*: `get() == nullptr` does not imply a specific return value of
 `use_count()`. — *end note*]
-[*Note 2*: `weak_ptr<T>::lock()` can affect the return value of
 `use_count()`. — *end note*]
-[*Note 3*: When multiple threads can affect the return value of
-`use_count()`, the result should be treated as approximate. In
-particular, `use_count() == 1` does not imply that accesses through a
-previously destroyed `shared_ptr` have in any sense
-completed. — *end note*]
 ``` cpp
 explicit operator bool() const noexcept;
 ```
-*Returns:* `get() != 0`.
 ``` cpp
 template<class U> bool owner_before(const shared_ptr<U>& b) const noexcept;
 template<class U> bool owner_before(const weak_ptr<U>& b) const noexcept;
 ```
@@ -454,11 +457,11 @@ template<class U> bool owner_before(const weak_ptr<U>& b) const noexcept;
 - under the equivalence relation defined by `owner_before`,
   `!a.owner_before(b) && !b.owner_before(a)`, two `shared_ptr` or
   `weak_ptr` instances are equivalent if and only if they share
   ownership or are both empty.
-#### Creation <a id="util.smartptr.shared.create">[[util.smartptr.shared.create]]</a>
 The common requirements that apply to all `make_shared`,
 `allocate_shared`, `make_shared_for_overwrite`, and
 `allocate_shared_for_overwrite` overloads, unless specified otherwise,
 are described below.
@@ -472,34 +475,34 @@ template<class T, ...>
   shared_ptr<T> make_shared_for_overwrite(args);
 template<class T, class A, ...>
   shared_ptr<T> allocate_shared_for_overwrite(const A& a, args);
 ```
-*Preconditions:* `A` meets the *Cpp17Allocator* requirements
-([[cpp17.allocator]]).
 *Effects:* Allocates memory for an object of type `T` (or `U[N]` when
 `T` is `U[]`, where `N` is determined from *args* as specified by the
 concrete overload). The object is initialized from *args* as specified
 by the concrete overload. The `allocate_shared` and
 `allocate_shared_for_overwrite` templates use a copy of `a` (rebound for
 an unspecified `value_type`) to allocate memory. If an exception is
 thrown, the functions have no effect.
 *Returns:* A `shared_ptr` instance that stores and owns the address of
 the newly constructed object.
-*Ensures:* `r.get() != 0 && r.use_count() == 1`, where `r` is the return
-value.
 *Throws:* `bad_alloc`, or an exception thrown from `allocate` or from
 the initialization of the object.
 *Remarks:*
 - Implementations should perform no more than one memory allocation.
-  \[*Note 1*: This provides efficiency equivalent to an intrusive smart
   pointer. — *end note*]
 - When an object of an array type `U` is specified to have an initial
   value of `u` (of the same type), this shall be interpreted to mean
   that each array element of the object has as its initial value the
   corresponding element from `u`.
@@ -551,11 +554,11 @@ the initialization of the object.
   expression `allocator_traits<A2>::destroy(a2, pv)` where `pv` points
   to that object of type `remove_cv_t<U>` and `a2` of type `A2` is a
   rebound copy of the allocator `a` passed to `allocate_shared` such
   that its `value_type` is `remove_cv_t<U>`.
-[*Note 1*: These functions will typically allocate more memory than
 `sizeof(T)` to allow for internal bookkeeping structures such as
 reference counts. — *end note*]
 ``` cpp
 template<class T, class... Args>
@@ -565,11 +568,11 @@ template<class T, class A, class... Args>
 ```
 *Constraints:* `T` is not an array type.
 *Returns:* A `shared_ptr` to an object of type `T` with an initial value
-`T(forward<Args>(args)...)`.
 *Remarks:* The `shared_ptr` constructors called by these functions
 enable `shared_from_this` with the address of the newly constructed
 object of type `T`.
@@ -725,11 +728,11 @@ shared_ptr<double[]> p = make_shared_for_overwrite<double[]>(1024);
   // shared_ptr to a default-initialized double[1024], where each element has an indeterminate value
 ```
 — *end example*]
-#### Comparison <a id="util.smartptr.shared.cmp">[[util.smartptr.shared.cmp]]</a>
 ``` cpp
 template<class T, class U>
   bool operator==(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;
 ```
@@ -748,30 +751,34 @@ template<class T, class U>
   strong_ordering operator<=>(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;
 ```
 *Returns:* `compare_three_way()(a.get(), b.get())`.
-[*Note 1*: Defining a comparison function allows `shared_ptr` objects
-to be used as keys in associative containers. — *end note*]
 ``` cpp
 template<class T>
   strong_ordering operator<=>(const shared_ptr<T>& a, nullptr_t) noexcept;
 ```
-*Returns:* `compare_three_way()(a.get(), nullptr)`.
-#### Specialized algorithms <a id="util.smartptr.shared.spec">[[util.smartptr.shared.spec]]</a>
 ``` cpp
 template<class T>
   void swap(shared_ptr<T>& a, shared_ptr<T>& b) noexcept;
 ```
 *Effects:* Equivalent to `a.swap(b)`.
-#### Casts <a id="util.smartptr.shared.cast">[[util.smartptr.shared.cast]]</a>
 ``` cpp
 template<class T, class U>
   shared_ptr<T> static_pointer_cast(const shared_ptr<U>& r) noexcept;
 template<class T, class U>
@@ -788,11 +795,11 @@ shared_ptr<T>(R, static_cast<typename shared_ptr<T>::element_type*>(r.get()))
 ```
 where *`R`* is `r` for the first overload, and `std::move(r)` for the
 second.
-[*Note 1*: The seemingly equivalent expression
 `shared_ptr<T>(static_cast<T*>(r.get()))` will eventually result in
 undefined behavior, attempting to delete the same object
 twice. — *end note*]
 ``` cpp
@@ -802,12 +809,12 @@ template<class T, class U>
   shared_ptr<T> dynamic_pointer_cast(shared_ptr<U>&& r) noexcept;
 ```
 *Mandates:* The expression `dynamic_cast<T*>((U*)nullptr)` is
 well-formed. The expression
-`dynamic_cast<typename shared_ptr<T>::element_type*>(r.get())` is well
-formed.
 *Preconditions:* The expression
 `dynamic_cast<typename shared_ptr<T>::element_type*>(r.get())` has
 well-defined behavior.
@@ -816,11 +823,11 @@ well-defined behavior.
 - When `dynamic_cast<typename shared_ptr<T>::element_type*>(r.get())`
   returns a non-null value `p`, `shared_ptr<T>(`*`R`*`, p)`, where *`R`*
   is `r` for the first overload, and `std::move(r)` for the second.
 - Otherwise, `shared_ptr<T>()`.
-[*Note 2*: The seemingly equivalent expression
 `shared_ptr<T>(dynamic_cast<T*>(r.get()))` will eventually result in
 undefined behavior, attempting to delete the same object
 twice. — *end note*]
 ``` cpp
@@ -839,11 +846,11 @@ shared_ptr<T>(R, const_cast<typename shared_ptr<T>::element_type*>(r.get()))
 ```
 where *`R`* is `r` for the first overload, and `std::move(r)` for the
 second.
-[*Note 3*: The seemingly equivalent expression
 `shared_ptr<T>(const_cast<T*>(r.get()))` will eventually result in
 undefined behavior, attempting to delete the same object
 twice. — *end note*]
 ``` cpp
@@ -863,16 +870,16 @@ shared_ptr<T>(R, reinterpret_cast<typename shared_ptr<T>::element_type*>(r.get()
 ```
 where *`R`* is `r` for the first overload, and `std::move(r)` for the
 second.
-[*Note 4*: The seemingly equivalent expression
 `shared_ptr<T>(reinterpret_cast<T*>(r.get()))` will eventually result in
 undefined behavior, attempting to delete the same object
 twice. — *end note*]
-#### `get_deleter` <a id="util.smartptr.getdeleter">[[util.smartptr.getdeleter]]</a>
 ``` cpp
 template<class D, class T>
   D* get_deleter(const shared_ptr<T>& p) noexcept;
 ```
@@ -880,16 +887,16 @@ template<class D, class T>
 *Returns:* If `p` owns a deleter `d` of type cv-unqualified `D`, returns
 `addressof(d)`; otherwise returns `nullptr`. The returned pointer
 remains valid as long as there exists a `shared_ptr` instance that owns
 `d`.
-[*Note 1*: It is unspecified whether the pointer remains valid longer
 than that. This can happen if the implementation doesn’t destroy the
 deleter until all `weak_ptr` instances that share ownership with `p`
 have been destroyed. — *end note*]
-#### I/O <a id="util.smartptr.shared.io">[[util.smartptr.shared.io]]</a>
 ``` cpp
 template<class E, class T, class Y>
   basic_ostream<E, T>& operator<<(basic_ostream<E, T>& os, const shared_ptr<Y>& p);
 ```

+#### Class template `shared_ptr` <a id="util.smartptr.shared">[[util.smartptr.shared]]</a>
+##### General <a id="util.smartptr.shared.general">[[util.smartptr.shared.general]]</a>
 The `shared_ptr` class template stores a pointer, usually obtained via
 `new`. `shared_ptr` implements semantics of shared ownership; the last
 remaining owner of the pointer is responsible for destroying the object,
 or otherwise releasing the resources associated with the stored pointer.
 contextually convertible to `bool`, allowing their use in boolean
 expressions and declarations in conditions.
 The template parameter `T` of `shared_ptr` may be an incomplete type.
+[*Note 1*: `T` can be a function type. — *end note*]
 [*Example 1*:
 ``` cpp
 if (shared_ptr<X> px = dynamic_pointer_cast<X>(py)) {
 For the purposes of subclause [[smartptr]], a pointer type `Y*` is said
 to be *compatible with* a pointer type `T*` when either `Y*` is
 convertible to `T*` or `Y` is `U[N]` and `T` is cv `U[]`.
+##### Constructors <a id="util.smartptr.shared.const">[[util.smartptr.shared.const]]</a>
 In the constructor definitions below, enables `shared_from_this` with
 `p`, for a pointer `p` of type `Y*`, means that if `Y` has an
 unambiguous and accessible base class that is a specialization of
 `enable_shared_from_this` [[util.smartptr.enab]], then `remove_cv_t<Y>*`
 ``` cpp
 template<class Y> explicit shared_ptr(Y* p);
 ```
 *Constraints:* When `T` is an array type, the expression `delete[] p` is
 well-formed and either `T` is `U[N]` and `Y(*)[N]` is convertible to
 `T*`, or `T` is `U[]` and `Y(*)[]` is convertible to `T*`. When `T` is
 not an array type, the expression `delete p` is well-formed and `Y*` is
 convertible to `T*`.
+*Mandates:* `Y` is a complete type.
 *Preconditions:* The expression `delete[] p`, when `T` is an array type,
 or `delete p`, when `T` is not an array type, has well-defined behavior,
 and does not throw exceptions.
 *Effects:* When `T` is not an array type, constructs a `shared_ptr`
 not an array type, `delete[] p` otherwise.
 *Ensures:* `use_count() == 1 && get() == p`.
 *Throws:* `bad_alloc`, or an *implementation-defined* exception when a
+resource other than memory cannot be obtained.
 ``` cpp
 template<class Y, class D> shared_ptr(Y* p, D d);
 template<class Y, class D, class A> shared_ptr(Y* p, D d, A a);
 template<class D> shared_ptr(nullptr_t p, D d);
 - If `T` is not an array type, then `Y*` is convertible to `T*`.
 *Preconditions:* Construction of `d` and a deleter of type `D`
 initialized with `std::move(d)` do not throw exceptions. The expression
 `d(p)` has well-defined behavior and does not throw exceptions. `A`
+meets the *Cpp17Allocator*
+requirements [[allocator.requirements.general]].
 *Effects:* Constructs a `shared_ptr` object that owns the object `p` and
 the deleter `d`. When `T` is not an array type, the first and second
 constructors enable `shared_from_this` with `p`. The second and fourth
 constructors shall use a copy of `a` to allocate memory for internal
 use. If an exception is thrown, `d(p)` is called.
 *Ensures:* `use_count() == 1 && get() == p`.
 *Throws:* `bad_alloc`, or an *implementation-defined* exception when a
+resource other than memory cannot be obtained.
 ``` cpp
 template<class Y> shared_ptr(const shared_ptr<Y>& r, element_type* p) noexcept;
 template<class Y> shared_ptr(shared_ptr<Y>&& r, element_type* p) noexcept;
 ```
 ownership with the initial value of `r`.
 *Ensures:* `get() == p`. For the second overload, `r` is empty and
 `r.get() == nullptr`.
+[*Note 1*: Use of this constructor leads to a dangling pointer unless
+`p` remains valid at least until the ownership group of `r` is
+destroyed. — *end note*]
 [*Note 2*: This constructor allows creation of an empty `shared_ptr`
 instance with a non-null stored pointer. — *end note*]
 ``` cpp
 *Constraints:* For the second constructor, `Y*` is compatible with `T*`.
 *Effects:* Move constructs a `shared_ptr` instance from `r`.
+*Ensures:* `*this` contains the old value of `r`. `r` is empty, and
+`r.get() == nullptr`.
 ``` cpp
 template<class Y> explicit shared_ptr(const weak_ptr<Y>& r);
 ```
 *Constraints:* `Y*` is compatible with `T*` and
 `unique_ptr<Y, D>::pointer` is convertible to `element_type*`.
 *Effects:* If `r.get() == nullptr`, equivalent to `shared_ptr()`.
 Otherwise, if `D` is not a reference type, equivalent to
+`shared_ptr(r.release(), std::move(r.get_deleter()))`. Otherwise,
+equivalent to `shared_ptr(r.release(), ref(r.get_deleter()))`. If an
+exception is thrown, the constructor has no effect.
+##### Destructor <a id="util.smartptr.shared.dest">[[util.smartptr.shared.dest]]</a>
 ``` cpp
 ~shared_ptr();
 ```
   instance (`use_count() > 1`), there are no side effects.
 - Otherwise, if `*this` owns an object `p` and a deleter `d`, `d(p)` is
   called.
 - Otherwise, `*this` owns a pointer `p`, and `delete p` is called.
+[*Note 2*: Since the destruction of `*this` decreases the number of
 instances that share ownership with `*this` by one, after `*this` has
 been destroyed all `shared_ptr` instances that shared ownership with
 `*this` will report a `use_count()` that is one less than its previous
 value. — *end note*]
+##### Assignment <a id="util.smartptr.shared.assign">[[util.smartptr.shared.assign]]</a>
 ``` cpp
 shared_ptr& operator=(const shared_ptr& r) noexcept;
 template<class Y> shared_ptr& operator=(const shared_ptr<Y>& r) noexcept;
 ```
 *Effects:* Equivalent to `shared_ptr(r).swap(*this)`.
 *Returns:* `*this`.
+[*Note 3*:
 The use count updates caused by the temporary object construction and
+destruction are not observable side effects, so the implementation can
 meet the effects (and the implied guarantees) via different means,
 without creating a temporary. In particular, in the example:
 ``` cpp
 shared_ptr<int> p(new int);
 shared_ptr<void> q(p);
 p = p;
 q = p;
 ```
+both assignments can be no-ops.
 — *end note*]
 ``` cpp
 shared_ptr& operator=(shared_ptr&& r) noexcept;
 *Effects:* Equivalent to `shared_ptr(std::move(r)).swap(*this)`.
 *Returns:* `*this`.
+##### Modifiers <a id="util.smartptr.shared.mod">[[util.smartptr.shared.mod]]</a>
 ``` cpp
 void swap(shared_ptr& r) noexcept;
 ```
 template<class Y, class D, class A> void reset(Y* p, D d, A a);
 ```
 *Effects:* Equivalent to `shared_ptr(p, d, a).swap(*this)`.
+##### Observers <a id="util.smartptr.shared.obs">[[util.smartptr.shared.obs]]</a>
 ``` cpp
 element_type* get() const noexcept;
 ```
 ``` cpp
 T& operator*() const noexcept;
 ```
+*Preconditions:* `get() != nullptr`.
 *Returns:* `*get()`.
 *Remarks:* When `T` is an array type or cv `void`, it is unspecified
 whether this member function is declared. If it is declared, it is
 ``` cpp
 T* operator->() const noexcept;
 ```
+*Preconditions:* `get() != nullptr`.
 *Returns:* `get()`.
 *Remarks:* When `T` is an array type, it is unspecified whether this
 member function is declared. If it is declared, it is unspecified what
 ``` cpp
 element_type& operator[](ptrdiff_t i) const;
 ```
+*Preconditions:* `get() != nullptr && i >= 0`. If `T` is `U[N]`,
+`i < N`.
 *Returns:* `get()[i]`.
 *Throws:* Nothing.
+*Remarks:* When `T` is not an array type, it is unspecified whether this
+member function is declared. If it is declared, it is unspecified what
+its return type is, except that the declaration (although not
+necessarily the definition) of the function shall be well-formed.
 ``` cpp
 long use_count() const noexcept;
 ```
+*Synchronization:* None.
 *Returns:* The number of `shared_ptr` objects, `*this` included, that
 share ownership with `*this`, or `0` when `*this` is empty.
+[*Note 4*: `get() == nullptr` does not imply a specific return value of
 `use_count()`. — *end note*]
+[*Note 5*: `weak_ptr<T>::lock()` can affect the return value of
 `use_count()`. — *end note*]
+[*Note 6*: When multiple threads might affect the return value of
+`use_count()`, the result is approximate. In particular,
+`use_count() == 1` does not imply that accesses through a previously
+destroyed `shared_ptr` have in any sense completed. — *end note*]
 ``` cpp
 explicit operator bool() const noexcept;
 ```
+*Returns:* `get() != nullptr`.
 ``` cpp
 template<class U> bool owner_before(const shared_ptr<U>& b) const noexcept;
 template<class U> bool owner_before(const weak_ptr<U>& b) const noexcept;
 ```
 - under the equivalence relation defined by `owner_before`,
   `!a.owner_before(b) && !b.owner_before(a)`, two `shared_ptr` or
   `weak_ptr` instances are equivalent if and only if they share
   ownership or are both empty.
+##### Creation <a id="util.smartptr.shared.create">[[util.smartptr.shared.create]]</a>
 The common requirements that apply to all `make_shared`,
 `allocate_shared`, `make_shared_for_overwrite`, and
 `allocate_shared_for_overwrite` overloads, unless specified otherwise,
 are described below.
   shared_ptr<T> make_shared_for_overwrite(args);
 template<class T, class A, ...>
   shared_ptr<T> allocate_shared_for_overwrite(const A& a, args);
 ```
+*Preconditions:* `A` meets the *Cpp17Allocator*
+requirements [[allocator.requirements.general]].
 *Effects:* Allocates memory for an object of type `T` (or `U[N]` when
 `T` is `U[]`, where `N` is determined from *args* as specified by the
 concrete overload). The object is initialized from *args* as specified
 by the concrete overload. The `allocate_shared` and
 `allocate_shared_for_overwrite` templates use a copy of `a` (rebound for
 an unspecified `value_type`) to allocate memory. If an exception is
 thrown, the functions have no effect.
+*Ensures:* `r.get() != nullptr && r.use_count() == 1`, where `r` is the
+return value.
 *Returns:* A `shared_ptr` instance that stores and owns the address of
 the newly constructed object.
 *Throws:* `bad_alloc`, or an exception thrown from `allocate` or from
 the initialization of the object.
 *Remarks:*
 - Implementations should perform no more than one memory allocation.
+  \[*Note 3*: This provides efficiency equivalent to an intrusive smart
   pointer. — *end note*]
 - When an object of an array type `U` is specified to have an initial
   value of `u` (of the same type), this shall be interpreted to mean
   that each array element of the object has as its initial value the
   corresponding element from `u`.
   expression `allocator_traits<A2>::destroy(a2, pv)` where `pv` points
   to that object of type `remove_cv_t<U>` and `a2` of type `A2` is a
   rebound copy of the allocator `a` passed to `allocate_shared` such
   that its `value_type` is `remove_cv_t<U>`.
+[*Note 7*: These functions will typically allocate more memory than
 `sizeof(T)` to allow for internal bookkeeping structures such as
 reference counts. — *end note*]
 ``` cpp
 template<class T, class... Args>
 ```
 *Constraints:* `T` is not an array type.
 *Returns:* A `shared_ptr` to an object of type `T` with an initial value
+`T(std::forward<Args>(args)...)`.
 *Remarks:* The `shared_ptr` constructors called by these functions
 enable `shared_from_this` with the address of the newly constructed
 object of type `T`.
   // shared_ptr to a default-initialized double[1024], where each element has an indeterminate value
 ```
 — *end example*]
+##### Comparison <a id="util.smartptr.shared.cmp">[[util.smartptr.shared.cmp]]</a>
 ``` cpp
 template<class T, class U>
   bool operator==(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;
 ```
   strong_ordering operator<=>(const shared_ptr<T>& a, const shared_ptr<U>& b) noexcept;
 ```
 *Returns:* `compare_three_way()(a.get(), b.get())`.
+[*Note 8*: Defining a comparison operator function allows `shared_ptr`
+objects to be used as keys in associative containers. — *end note*]
 ``` cpp
 template<class T>
   strong_ordering operator<=>(const shared_ptr<T>& a, nullptr_t) noexcept;
 ```
+*Returns:*
+``` cpp
+compare_three_way()(a.get(), static_cast<typename shared_ptr<T>::element_type*>(nullptr).
+```
+##### Specialized algorithms <a id="util.smartptr.shared.spec">[[util.smartptr.shared.spec]]</a>
 ``` cpp
 template<class T>
   void swap(shared_ptr<T>& a, shared_ptr<T>& b) noexcept;
 ```
 *Effects:* Equivalent to `a.swap(b)`.
+##### Casts <a id="util.smartptr.shared.cast">[[util.smartptr.shared.cast]]</a>
 ``` cpp
 template<class T, class U>
   shared_ptr<T> static_pointer_cast(const shared_ptr<U>& r) noexcept;
 template<class T, class U>
 ```
 where *`R`* is `r` for the first overload, and `std::move(r)` for the
 second.
+[*Note 9*: The seemingly equivalent expression
 `shared_ptr<T>(static_cast<T*>(r.get()))` will eventually result in
 undefined behavior, attempting to delete the same object
 twice. — *end note*]
 ``` cpp
   shared_ptr<T> dynamic_pointer_cast(shared_ptr<U>&& r) noexcept;
 ```
 *Mandates:* The expression `dynamic_cast<T*>((U*)nullptr)` is
 well-formed. The expression
+`dynamic_cast<typename shared_ptr<T>::element_type*>(r.get())` is
+well-formed.
 *Preconditions:* The expression
 `dynamic_cast<typename shared_ptr<T>::element_type*>(r.get())` has
 well-defined behavior.
 - When `dynamic_cast<typename shared_ptr<T>::element_type*>(r.get())`
   returns a non-null value `p`, `shared_ptr<T>(`*`R`*`, p)`, where *`R`*
   is `r` for the first overload, and `std::move(r)` for the second.
 - Otherwise, `shared_ptr<T>()`.
+[*Note 10*: The seemingly equivalent expression
 `shared_ptr<T>(dynamic_cast<T*>(r.get()))` will eventually result in
 undefined behavior, attempting to delete the same object
 twice. — *end note*]
 ``` cpp
 ```
 where *`R`* is `r` for the first overload, and `std::move(r)` for the
 second.
+[*Note 11*: The seemingly equivalent expression
 `shared_ptr<T>(const_cast<T*>(r.get()))` will eventually result in
 undefined behavior, attempting to delete the same object
 twice. — *end note*]
 ``` cpp
 ```
 where *`R`* is `r` for the first overload, and `std::move(r)` for the
 second.
+[*Note 12*: The seemingly equivalent expression
 `shared_ptr<T>(reinterpret_cast<T*>(r.get()))` will eventually result in
 undefined behavior, attempting to delete the same object
 twice. — *end note*]
+##### `get_deleter` <a id="util.smartptr.getdeleter">[[util.smartptr.getdeleter]]</a>
 ``` cpp
 template<class D, class T>
   D* get_deleter(const shared_ptr<T>& p) noexcept;
 ```
 *Returns:* If `p` owns a deleter `d` of type cv-unqualified `D`, returns
 `addressof(d)`; otherwise returns `nullptr`. The returned pointer
 remains valid as long as there exists a `shared_ptr` instance that owns
 `d`.
+[*Note 13*: It is unspecified whether the pointer remains valid longer
 than that. This can happen if the implementation doesn’t destroy the
 deleter until all `weak_ptr` instances that share ownership with `p`
 have been destroyed. — *end note*]
+##### I/O <a id="util.smartptr.shared.io">[[util.smartptr.shared.io]]</a>
 ``` cpp
 template<class E, class T, class Y>
   basic_ostream<E, T>& operator<<(basic_ostream<E, T>& os, const shared_ptr<Y>& p);
 ```

Diff to HTML by rtfpessoa