20 General utilities library [utilities]

Effects: Constructs an empty shared_ptr object.

Postconditions: use_count() == 0 && get() == nullptr.

Requires: p shall be convertible to T*. Y shall be a complete type. The expression delete p shall be well formed, shall have well defined behavior, and shall not throw exceptions.

Effects: Constructs a shared_ptr object that owns the pointer p.

Postconditions: use_count() == 1 && get() == p.

Throws: bad_alloc, or an implementation-defined exception when a resource other than memory could not be obtained.

Exception safety: If an exception is thrown, delete p is called.

Requires: p shall be convertible to T*. D shall be CopyConstructible. The copy constructor and destructor of D shall not throw exceptions. The expression d(p) shall be well formed, shall have well defined behavior, and shall not throw exceptions. A shall be an allocator ([allocator.requirements]). The copy constructor and destructor of A shall not throw exceptions.

Effects: Constructs a shared_ptr object that owns the object p and the deleter d. The second and fourth constructors shall use a copy of a to allocate memory for internal use.

Postconditions: use_count() == 1 && get() == p.

Throws: bad_alloc, or an implementation-defined exception when a resource other than memory could not be obtained.

Exception safety: If an exception is thrown, d(p) is called.

Effects: Constructs a shared_ptr instance that stores p and shares ownership with r.

Postconditions: get() == p && use_count() == r.use_count()

[ Note: To avoid the possibility of a dangling pointer, the user of this constructor must ensure that p remains valid at least until the ownership group of r is destroyed.  — end note ]

[ Note: This constructor allows creation of an empty shared_ptr instance with a non-null stored pointer.  — end note ]

Remark: The second constructor shall not participate in overload resolution unless Y* is implicitly convertible to T*.

Effects: If r is empty, constructs an empty shared_ptr object; otherwise, constructs a shared_ptr object that shares ownership with r.

Postconditions: get() == r.get() && use_count() == r.use_count().

Remark: The second constructor shall not participate in overload resolution unless Y* is convertible to T*.

Effects: Move-constructs a shared_ptr instance from r.

Postconditions: *this shall contain the old value of r. r shall be empty. r.get() == nullptr.

Requires: Y* shall be convertible to T*.

Effects: Constructs a shared_ptr object that shares ownership with r and stores a copy of the pointer stored in r.

Postconditions: use_count() == r.use_count().

Throws: bad_weak_ptr when r.expired().

Exception safety: If an exception is thrown, the constructor has no effect.

Requires: r.release() shall be convertible to T*. Y shall be a complete type. The expression delete r.release() shall be well formed, shall have well defined behavior, and shall not throw exceptions.

Effects: Constructs a shared_ptr object that stores and owns r.release().

Postconditions: use_count() == 1 && r.get() == nullptr.

Throws: bad_alloc, or an implementation-defined exception when a resource other than memory could not be obtained.

Exception safety: If an exception is thrown, the constructor has no effect.

Effects: Equivalent to shared_ptr(r.release(), r.get_deleter()) when D is not a reference type, otherwise shared_ptr(r.release(), ref(r.get_deleter())).

Exception safety: If an exception is thrown, the constructor has no effect.

Effects:

• (1.1)

  If *this is empty or shares ownership with another shared_ptr instance (use_count() > 1), there are no side effects.

• (1.2)

  Otherwise, if *this owns an object p and a deleter d, d(p) is called.

• (1.3)

  Otherwise, *this owns a pointer p, and delete p is called.

Effects: Equivalent to shared_ptr(r).swap(*this).

Returns: *this.

[ Note: 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:

shared_ptr<int> p(new int);
shared_ptr<void> q(p);
p = p;
q = p;

both assignments may be no-ops.  — end note ]

Effects: Equivalent to shared_ptr(std::move(r)).swap(*this).

Returns: *this.

Effects: Equivalent to shared_ptr(std::move(r)).swap(*this).

Returns: *this

Effects: Exchanges the contents of *this and r.

Effects: Equivalent to shared_ptr().swap(*this).

Effects: Equivalent to shared_ptr(p).swap(*this).

Effects: Equivalent to shared_ptr(p, d).swap(*this).

Effects: Equivalent to shared_ptr(p, d, a).swap(*this).

Returns: the stored pointer.

Requires: get() != 0.

Returns: *get().

Remarks: When T is void, 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.

Requires: get() != 0.

Returns: get().

Returns: the number of shared_ptr objects, *this included, that share ownership with *this, or 0 when *this is empty.

[ Note: use_count() is not necessarily efficient. — end note ]

Returns: use_count() == 1.

[ Note: unique() may be faster than use_count(). If you are using unique() to implement copy on write, do not rely on a specific value when get() == nullptr.  — end note ]

Returns: get() != 0.

Returns: An unspecified value such that

• (12.1)

  x.owner_before(y) defines a strict weak ordering as defined in [alg.sorting];

• (12.2)

  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.

Requires: The expression ::new (pv) T(std::forward<Args>(args)...), where pv has type void* and points to storage suitable to hold an object of type T, shall be well formed. A shall be an allocator ([allocator.requirements]). The copy constructor and destructor of A shall not throw exceptions.

Effects: Allocates memory suitable for an object of type T and constructs an object in that memory via the placement new expression ::new (pv) T(std::forward<Args>(args)...). The template allocate_shared uses a copy of a 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 of type T.

Postconditions: get() != 0 && use_count() == 1

Throws: bad_alloc, or an exception thrown from A::allocate or from the constructor of T.

Remarks: Implementations should perform no more than one memory allocation. [ Note: This provides efficiency equivalent to an intrusive smart pointer.  — end note ]

[ Note: These functions will typically allocate more memory than sizeof(T) to allow for internal bookkeeping structures such as the reference counts.  — end note ]

Returns: a.get() == b.get().

Returns: less<V>()(a.get(), b.get()), where V is the composite pointer type (Clause [expr]) of T* and U*.

[ Note: Defining a comparison operator allows shared_ptr objects to be used as keys in associative containers.  — end note ]

Returns: !a.

Returns: (bool)a.

Returns: The first function template returns less<T*>()(a.get(), nullptr). The second function template returns less<T*>()(nullptr, a.get()).

Returns: The first function template returns nullptr < a. The second function template returns a < nullptr.

Returns: The first function template returns !(nullptr < a). The second function template returns !(a < nullptr).

Returns: The first function template returns !(a < nullptr). The second function template returns !(nullptr < a).

Effects: Equivalent to a.swap(b).

Requires: The expression static_cast<T*>(r.get()) shall be well formed.

Returns: If r is empty, an empty shared_ptr<T>; otherwise, a shared_ptr<T> object that stores static_cast<T*>(r.get()) and shares ownership with r.

Postconditions: w.get() == static_cast<T*>(r.get()) and w.use_count() == r.use_count(), where w is the return value.

[ Note: 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 ]

Requires: The expression dynamic_cast<T*>(r.get()) shall be well formed and shall have well defined behavior.

Returns:

• (6.1)

  When dynamic_cast<T*>(r.get()) returns a nonzero value, a shared_ptr<T> object that stores a copy of it and shares ownership with r;

• (6.2)

  Otherwise, an empty shared_ptr<T> object.

Postcondition: w.get() == dynamic_cast<T*>(r.get()), where w is the return value.

[ Note: 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 ]

Requires: The expression const_cast<T*>(r.get()) shall be well formed.

Returns: If r is empty, an empty shared_ptr<T>; otherwise, a shared_ptr<T> object that stores const_cast<T*>(r.get()) and shares ownership with r.

Postconditions: w.get() == const_cast<T*>(r.get()) and w.use_count() == r.use_count(), where w is the return value.

[ Note: 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 ]

Returns: If p owns a deleter d of type cv-unqualified D, returns &d; otherwise returns nullptr. The returned pointer remains valid as long as there exists a shared_ptr instance that owns d. [ Note: 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 ]

Effects: os << p.get();.

Returns: os.