From adcab0e313c91b28acc7eae2fe1c72af3971493a Mon Sep 17 00:00:00 2001 From: Glen Fernandes Date: Sun, 24 Mar 2019 20:28:17 -0400 Subject: [PATCH 1/2] Update asciidoc to work with Asciidoctor 2.0 --- doc/smart_ptr/intrusive_ptr.adoc | 116 ++++---------- doc/smart_ptr/intrusive_ref_counter.adoc | 25 ++- doc/smart_ptr/local_shared_ptr.adoc | 168 +++++--------------- doc/smart_ptr/make_shared.adoc | 63 ++++---- doc/smart_ptr/make_unique.adoc | 40 ++--- doc/smart_ptr/pointer_cast.adoc | 56 +++---- doc/smart_ptr/shared_array.adoc | 86 +++++------ doc/smart_ptr/shared_ptr.adoc | 188 ++++++----------------- doc/smart_ptr/weak_ptr.adoc | 52 ++----- 9 files changed, 262 insertions(+), 532 deletions(-) diff --git a/doc/smart_ptr/intrusive_ptr.adoc b/doc/smart_ptr/intrusive_ptr.adoc index cb30a04..4f977f7 100644 --- a/doc/smart_ptr/intrusive_ptr.adoc +++ b/doc/smart_ptr/intrusive_ptr.adoc @@ -136,18 +136,14 @@ Provides the type of the template parameter T. intrusive_ptr() noexcept; ``` -[none] -* {blank} -+ +[horizontal] Postconditions:: `get() == 0`. ``` intrusive_ptr(T * p, bool add_ref = true); ``` -[none] -* {blank} -+ +[horizontal] Effects:: `if(p != 0 && add_ref) intrusive_ptr_add_ref(p);`. Postconditions:: `get() == p`. @@ -158,9 +154,7 @@ intrusive_ptr(intrusive_ptr const & r); template intrusive_ptr(intrusive_ptr const & r); ``` -[none] -* {blank} -+ +[horizontal] Effects:: `T * p = r.get(); if(p != 0) intrusive_ptr_add_ref(p);`. Postconditions:: `get() == r.get()`. @@ -171,9 +165,7 @@ intrusive_ptr(intrusive_ptr && r); template intrusive_ptr(intrusive_ptr && r); ``` -[none] -* {blank} -+ +[horizontal] Postconditions:: `get()` equals the old value of `r.get()`. `r.get() == 0`. ### destructor @@ -182,9 +174,7 @@ Postconditions:: `get()` equals the old value of `r.get()`. `r.get() == 0`. ~intrusive_ptr(); ``` -[none] -* {blank} -+ +[horizontal] Effects:: `if(get() != 0) intrusive_ptr_release(get());`. ### assignment @@ -199,9 +189,7 @@ template intrusive_ptr & operator=(intrusive_ptr const & r); intrusive_ptr & operator=(T * r); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `intrusive_ptr(r).swap(*this)`. Returns:: `*this`. @@ -212,9 +200,7 @@ intrusive_ptr & operator=(intrusive_ptr && r); template intrusive_ptr & operator=(intrusive_ptr && r); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `intrusive_ptr(std::move(r)).swap(*this)`. Returns:: `*this`. @@ -224,27 +210,21 @@ Returns:: `*this`. void reset(); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `intrusive_ptr().swap(*this)`. ``` void reset(T * r); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `intrusive_ptr(r).swap(*this)`. ``` void reset(T * r, bool add_ref); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `intrusive_ptr(r, add_ref).swap(*this)`. ### indirection @@ -253,9 +233,7 @@ Effects:: Equivalent to `intrusive_ptr(r, add_ref).swap(*this)`. T & operator*() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requirements:: `get() != 0`. Returns:: `*get()`. @@ -263,9 +241,7 @@ Returns:: `*get()`. T * operator->() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requirements:: `get() != 0`. Returns:: `get()`. @@ -275,9 +251,7 @@ Returns:: `get()`. T * get() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: the stored pointer. ### detach @@ -286,9 +260,7 @@ Returns:: the stored pointer. T * detach() noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: the stored pointer. Postconditions:: `get() == 0`. @@ -306,9 +278,7 @@ the implications are thoroughly understood. explicit operator bool () const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `get() != 0`. NOTE: This conversion operator allows `intrusive_ptr` objects to be used in boolean contexts, @@ -322,9 +292,7 @@ NOTE: On C++03 compilers, the return value is of an unspecified type. void swap(intrusive_ptr & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Exchanges the contents of the two smart pointers. ## Free Functions @@ -336,9 +304,7 @@ template bool operator==(intrusive_ptr const & a, intrusive_ptr const & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `a.get() == b.get()`. ``` @@ -346,9 +312,7 @@ template bool operator!=(intrusive_ptr const & a, intrusive_ptr const & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `a.get() != b.get()`. ``` @@ -356,9 +320,7 @@ template bool operator==(intrusive_ptr const & a, U * b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `a.get() == b`. ``` @@ -366,9 +328,7 @@ template bool operator!=(intrusive_ptr const & a, U * b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `a.get() != b`. ``` @@ -376,9 +336,7 @@ template bool operator==(T * a, intrusive_ptr const & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `a == b.get()`. ``` @@ -386,9 +344,7 @@ template bool operator!=(T * a, intrusive_ptr const & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `a != b.get()`. ``` @@ -396,9 +352,7 @@ template bool operator<(intrusive_ptr const & a, intrusive_ptr const & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `std::less()(a.get(), b.get())`. NOTE: Allows `intrusive_ptr` objects to be used as keys in associative containers. @@ -409,9 +363,7 @@ NOTE: Allows `intrusive_ptr` objects to be used as keys in associative container template void swap(intrusive_ptr & a, intrusive_ptr & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `a.swap(b)`. ### get_pointer @@ -420,9 +372,7 @@ Effects:: Equivalent to `a.swap(b)`. template T * get_pointer(intrusive_ptr const & p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `p.get()`. NOTE: Provided as an aid to generic programming. Used by `mem_fn`. @@ -434,9 +384,7 @@ template intrusive_ptr static_pointer_cast(intrusive_ptr const & r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `intrusive_ptr(static_cast(r.get()))`. ### const_pointer_cast @@ -446,9 +394,7 @@ template intrusive_ptr const_pointer_cast(intrusive_ptr const & r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `intrusive_ptr(const_cast(r.get()))`. ### dynamic_pointer_cast @@ -458,9 +404,7 @@ template intrusive_ptr dynamic_pointer_cast(intrusive_ptr const & r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `intrusive_ptr(dynamic_cast(r.get()))`. ### operator<< @@ -471,8 +415,6 @@ template intrusive_ptr const & p); ``` -[none] -* {blank} -+ +[horizontal] Effects:: `os << p.get();`. Returns:: `os`. diff --git a/doc/smart_ptr/intrusive_ref_counter.adoc b/doc/smart_ptr/intrusive_ref_counter.adoc index 32a28a6..4133c35 100644 --- a/doc/smart_ptr/intrusive_ref_counter.adoc +++ b/doc/smart_ptr/intrusive_ref_counter.adoc @@ -78,12 +78,11 @@ namespace boost { ``` intrusive_ref_counter() noexcept; ``` -:: ``` intrusive_ref_counter(const intrusive_ref_counter&) noexcept; ``` -:: -Postconditions::: `use_count() == 0`. +[horizontal] +Postconditions:: `use_count() == 0`. NOTE: The pointer to the constructed object is expected to be passed to `intrusive_ptr` constructor, assignment operator or `reset` method, which @@ -94,8 +93,8 @@ would increment the reference counter. ``` ~intrusive_ref_counter(); ``` -:: -Effects::: Destroys the counter object. +[horizontal] +Effects:: Destroys the counter object. NOTE: The destructor is protected so that the object can only be destroyed through the `Derived` class. @@ -105,16 +104,16 @@ through the `Derived` class. ``` intrusive_ref_counter& operator=(const intrusive_ref_counter& v) noexcept; ``` -:: -Effects::: Does nothing, reference counter is not modified. +[horizontal] +Effects:: Does nothing, reference counter is not modified. ### use_count ``` unsigned int use_count() const noexcept; ``` -:: -Returns::: The current value of the reference counter. +[horizontal] +Returns:: The current value of the reference counter. NOTE: The returned value may not be actual in multi-threaded applications. @@ -127,8 +126,8 @@ template void intrusive_ptr_add_ref( const intrusive_ref_counter* p) noexcept; ``` -:: -Effects::: Increments the reference counter. +[horizontal] +Effects:: Increments the reference counter. ### intrusive_ptr_release @@ -137,6 +136,6 @@ template void intrusive_ptr_release( const intrusive_ref_counter* p) noexcept; ``` -:: -Effects::: Decrements the reference counter. If the reference counter reaches +[horizontal] +Effects:: Decrements the reference counter. If the reference counter reaches 0, calls `delete static_cast(p)`. diff --git a/doc/smart_ptr/local_shared_ptr.adoc b/doc/smart_ptr/local_shared_ptr.adoc index d7d34dd..3cb807e 100644 --- a/doc/smart_ptr/local_shared_ptr.adoc +++ b/doc/smart_ptr/local_shared_ptr.adoc @@ -227,9 +227,7 @@ constexpr local_shared_ptr() noexcept; ``` constexpr local_shared_ptr(std::nullptr_t) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Constructs an empty `local_shared_ptr`. Postconditions:: `local_use_count() == 0 && get() == 0`. @@ -237,9 +235,7 @@ Postconditions:: `local_use_count() == 0 && get() == 0`. ``` template explicit local_shared_ptr(Y * p); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Constructs a `local_shared_ptr` that owns `shared_ptr( p )`. Postconditions:: `local_use_count() == 1 && get() == p`. @@ -253,9 +249,7 @@ template local_shared_ptr(Y * p, D d); ``` template local_shared_ptr(std::nullptr_t p, D d); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Constructs a `local_shared_ptr` that owns `shared_ptr( p, d )`. Postconditions:: `local_use_count() == 1 && get() == p`. @@ -268,9 +262,7 @@ template local_shared_ptr(Y * p, D d, A a); ``` template local_shared_ptr(std::nullptr_t p, D d, A a); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Constructs a `local_shared_ptr` that owns `shared_ptr( p, d, a )`. Postconditions:: `local_use_count() == 1 && get() == p`. @@ -284,9 +276,7 @@ local_shared_ptr(local_shared_ptr const & r) noexcept; ``` template local_shared_ptr(local_shared_ptr const & r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: `Y*` should be convertible to `T*`. Effects:: If `r` is empty, constructs an empty `local_shared_ptr`; otherwise, constructs a `local_shared_ptr` that shares ownership with `r`. @@ -300,9 +290,7 @@ local_shared_ptr(local_shared_ptr && r) noexcept; ``` template local_shared_ptr(local_shared_ptr && r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: `Y*` should be convertible to `T*`. Effects:: Move-constructs a `local_shared_ptr` from `r`. @@ -316,9 +304,7 @@ template local_shared_ptr( shared_ptr const & r ); ``` template local_shared_ptr( shared_ptr && r ); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Constructs a `local_shared_ptr` that owns `r`. Postconditions:: `local_use_count() == 1`. `get()` returns the old value of `r.get()`. @@ -329,9 +315,7 @@ Throws:: `std::bad_alloc`, or an implementation-defined exception when a resourc ``` template local_shared_ptr(local_shared_ptr const & r, element_type * p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: constructs a `local_shared_ptr` that shares ownership with `r` and stores `p`. Postconditions:: `get() == p && local_use_count() == r.local_use_count()`. @@ -340,9 +324,7 @@ Postconditions:: `get() == p && local_use_count() == r.local_use_count()`. ``` template local_shared_ptr(local_shared_ptr && r, element_type * p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Move-constructs a `local_shared_ptr` from `r`, while storing `p` instead. Postconditions:: `get() == p` and `local_use_count()` equals the old count of `r`. `r` is empty and `r.get() == 0`. @@ -351,9 +333,7 @@ Postconditions:: `get() == p` and `local_use_count()` equals the old count of `r ``` template local_shared_ptr(std::unique_ptr && r); ``` -[none] -* {blank} -+ +[horizontal] Requires:: `Y*` should be convertible to `T*`. Effects:: @@ -368,9 +348,7 @@ Exception safety:: If an exception is thrown, the constructor has no effect. ``` ~local_shared_ptr() noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: - If `*this` is empty, or shares ownership with another `local_shared_ptr` instance (`local_use_count() > 1`), there are no side effects. - Otherwise, destroys the owned `shared_ptr`. @@ -382,9 +360,7 @@ local_shared_ptr & operator=(local_shared_ptr const & r) noexcept; ``` template local_shared_ptr & operator=(local_shared_ptr const & r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `local_shared_ptr(r).swap(*this)`. Returns:: `*this`. @@ -397,18 +373,14 @@ template local_shared_ptr & operator=(local_shared_ptr && r) noexcep ``` template local_shared_ptr & operator=(std::unique_ptr && r); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `local_shared_ptr(std::move(r)).swap(*this)`. Returns:: `*this`. ``` local_shared_ptr & operator=(std::nullptr_t) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `local_shared_ptr().swap(*this)`. Returns:: `*this`. @@ -416,76 +388,58 @@ Returns:: `*this`. ``` void reset() noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `local_shared_ptr().swap(*this)`. ``` template void reset(Y * p); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `local_shared_ptr(p).swap(*this)`. ``` template void reset(Y * p, D d); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `local_shared_ptr(p, d).swap(*this)`. ``` template void reset(Y * p, D d, A a); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `local_shared_ptr(p, d, a).swap(*this)`. ``` template void reset(local_shared_ptr const & r, element_type * p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `local_shared_ptr(r, p).swap(*this)`. ``` template void reset(local_shared_ptr && r, element_type * p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `local_shared_ptr(std::move(r), p).swap(*this)`. ### indirection ``` T & operator*() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: `T` should not be an array type. Returns:: `*get()`. ``` T * operator->() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: `T` should not be an array type. Returns:: `get()`. ``` element_type & operator[](std::ptrdiff_t i) const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: `T` should be an array type. The stored pointer must not be 0. `i >= 0`. If `T` is `U[N]`, `i < N`. Returns:: `get()[i]`. @@ -494,27 +448,21 @@ Returns:: `get()[i]`. ``` element_type * get() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: The stored pointer. ### local_use_count ``` long local_use_count() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: The number of `local_shared_ptr` objects, `*this` included, that share ownership with `*this`, or 0 when `*this` is empty. ### conversions ``` explicit operator bool() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `get() != 0`. NOTE: On C++03 compilers, the return value is of an unspecified type. @@ -525,9 +473,7 @@ template operator shared_ptr() const noexcept; ``` template operator weak_ptr() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: `T*` should be convertible to `Y*`. Returns:: a copy of the owned `shared_ptr`. @@ -535,18 +481,14 @@ Returns:: a copy of the owned `shared_ptr`. ``` void swap(local_shared_ptr & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Exchanges the contents of the two smart pointers. ### owner_before ``` template bool owner_before(local_shared_ptr const & rhs) const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: See the description of `operator<`. ## Free Functions @@ -564,9 +506,7 @@ template template bool operator==(shared_ptr const & a, local_shared_ptr const & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `a.get() == b.get()`. ``` @@ -581,9 +521,7 @@ template template bool operator!=(shared_ptr const & a, local_shared_ptr const & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `a.get() != b.get()`. ``` @@ -592,9 +530,7 @@ template bool operator==(local_shared_ptr const & p, std::nullptr_t) ``` template bool operator==(std::nullptr_t, local_shared_ptr const & p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `p.get() == 0`. ``` @@ -603,18 +539,14 @@ template bool operator!=(local_shared_ptr const & p, std::nullptr_t) ``` template bool operator!=(std::nullptr_t, local_shared_ptr const & p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `p.get() != 0`. ``` template bool operator<(local_shared_ptr const & a, local_shared_ptr const & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: An unspecified value such that - `operator<` is a strict weak ordering as described in section [lib.alg.sorting] of the {cpp} standard; - under the equivalence relation defined by `operator<`, `!(a < b) && !(b < a)`, two `local_shared_ptr` instances @@ -628,9 +560,7 @@ NOTE: The rest of the comparison operators are omitted by design. ``` template void swap(local_shared_ptr & a, local_shared_ptr & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `a.swap(b)`. ### get_pointer @@ -639,9 +569,7 @@ template typename local_shared_ptr::element_type * get_pointer(local_shared_ptr const & p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `p.get()`. NOTE: Provided as an aid to generic programming. Used by `mem_fn`. @@ -651,9 +579,7 @@ NOTE: Provided as an aid to generic programming. Used by `mem_fn`. template local_shared_ptr static_pointer_cast(local_shared_ptr const & r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: The expression `static_cast( (U*)0 )` must be well-formed. Returns:: `local_shared_ptr( r, static_cast::element_type*>(r.get()) )`. @@ -665,9 +591,7 @@ result in undefined behavior, attempting to delete the same object twice. template local_shared_ptr const_pointer_cast(local_shared_ptr const & r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: The expression `const_cast( (U*)0 )` must be well-formed. Returns:: `local_shared_ptr( r, const_cast::element_type*>(r.get()) )`. @@ -676,9 +600,7 @@ Returns:: `local_shared_ptr( r, const_cast::elem template local_shared_ptr dynamic_pointer_cast(local_shared_ptr const & r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: The expression `dynamic_cast( (U*)0 )` must be well-formed. Returns:: - When `dynamic_cast::element_type*>(r.get())` returns a nonzero value `p`, `local_shared_ptr(r, p)`; @@ -689,9 +611,7 @@ Returns:: template local_shared_ptr reinterpret_pointer_cast(local_shared_ptr const & r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: The expression `reinterpret_cast( (U*)0 )` must be well-formed. Returns:: `local_shared_ptr( r, reinterpret_cast::element_type*>(r.get()) )`. @@ -701,9 +621,7 @@ template std::basic_ostream & operator<< (std::basic_ostream & os, local_shared_ptr const & p); ``` -[none] -* {blank} -+ +[horizontal] Effects:: `os << p.get();`. Returns:: `os`. @@ -712,8 +630,6 @@ Returns:: `os`. template D * get_deleter(local_shared_ptr const & p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: If `*this` owns a `shared_ptr` instance `p`, `get_deleter( p )`, otherwise 0. diff --git a/doc/smart_ptr/make_shared.adoc b/doc/smart_ptr/make_shared.adoc index 5b4366c..ed4c901 100644 --- a/doc/smart_ptr/make_shared.adoc +++ b/doc/smart_ptr/make_shared.adoc @@ -174,17 +174,16 @@ the reference counts. template shared_ptr make_shared(Args&&... args); ``` -:: ``` template shared_ptr allocate_shared(const A& a, Args&&... args); ``` -:: -Remarks::: These overloads shall only participate in overload resolution when +[horizontal] +Remarks:: These overloads shall only participate in overload resolution when `T` is not an array type. -Returns::: A `shared_ptr` to an object of type `T`, constructed from +Returns:: A `shared_ptr` to an object of type `T`, constructed from `args\...`. -Examples::: +Examples:: * `auto p = make_shared();` * `auto p = make_shared >(16, 1);` @@ -192,17 +191,16 @@ Examples::: template shared_ptr make_shared(std::size_t n); ``` -:: ``` template shared_ptr allocate_shared(const A& a, std::size_t n); ``` -:: -Remarks::: These overloads shall only participate in overload resolution when +[horizontal] +Remarks:: These overloads shall only participate in overload resolution when `T` is an array type of the form `U[]`. -Returns::: A `shared_ptr` to a sequence of `n` value-initialized objects of +Returns:: A `shared_ptr` to a sequence of `n` value-initialized objects of type `U`. -Examples::: +Examples:: * `auto p = make_shared(1024);` * `auto p = make_shared(6);` @@ -210,17 +208,16 @@ Examples::: template shared_ptr make_shared(); ``` -:: ``` template shared_ptr allocate_shared(const A& a); ``` -:: -Remarks::: These overloads shall only participate in overload resolution when +[horizontal] +Remarks:: These overloads shall only participate in overload resolution when `T` is an array type of the form `U[N]`. -Returns::: A `shared_ptr` to a sequence of `N` value-initialized objects of +Returns:: A `shared_ptr` to a sequence of `N` value-initialized objects of type `U`. -Examples::: +Examples:: * `auto p = make_shared();` * `auto p = make_shared();` @@ -228,17 +225,16 @@ Examples::: template shared_ptr make_shared(std::size_t n, const remove_extent_t& v); ``` -:: ``` template shared_ptr allocate_shared(const A& a, std::size_t n, const remove_extent_t& v); ``` -:: -Remarks::: These overloads shall only participate in overload resolution when +[horizontal] +Remarks:: These overloads shall only participate in overload resolution when `T` is an array type of the form `U[]`. -Returns::: A `shared_ptr` to a sequence of `n` objects of type `U`, each +Returns:: A `shared_ptr` to a sequence of `n` objects of type `U`, each initialized to `v`. -Examples::: +Examples:: * `auto p = make_shared(1024, 1.0);` * `auto p = make_shared(6, {1.0, 0.0});` * `auto p = make_shared[]>(4, {1, 2});` @@ -247,17 +243,16 @@ Examples::: template shared_ptr make_shared(const remove_extent_t& v); ``` -:: ``` template shared_ptr allocate_shared(const A& a, const remove_extent_t& v); ``` -:: -Remarks::: These overloads shall only participate in overload resolution when +[horizontal] +Remarks:: These overloads shall only participate in overload resolution when `T` is an array type of the form `U[N]`. -Returns::: A `shared_ptr` to a sequence of `N` objects of type `U`, each +Returns:: A `shared_ptr` to a sequence of `N` objects of type `U`, each initialized to `v`. -Examples::: +Examples:: * `auto p = make_shared(1.0);` * `auto p = make_shared({1.0, 0.0});` * `auto p = make_shared[4]>({1, 2});` @@ -266,30 +261,28 @@ Examples::: template shared_ptr make_shared_noinit(); ``` -:: ``` template shared_ptr allocate_shared_noinit(const A& a); ``` -:: -Remarks::: These overloads shall only participate in overload resolution when +[horizontal] +Remarks:: These overloads shall only participate in overload resolution when `T` is not an array type, or an array type of the `U[N]`. -Returns::: A `shared_ptr` to a default-initialized object of type `T`, or a +Returns:: A `shared_ptr` to a default-initialized object of type `T`, or a sequence of `N` default-initialized objects of type `U`, respectively. -Example::: `auto p = make_shared_noinit();` +Example:: `auto p = make_shared_noinit();` ``` template shared_ptr make_shared_noinit(std::size_t n); ``` -:: ``` template shared_ptr allocate_shared_noinit(const A& a, std::size_t n); ``` -:: -Remarks::: These overloads shall only participate in overload resolution when +[horizontal] +Remarks:: These overloads shall only participate in overload resolution when `T` is an array type of the form `U[]`. -Returns::: A `shared_ptr` to a sequence of `_n_` default-initialized objects +Returns:: A `shared_ptr` to a sequence of `_n_` default-initialized objects of type `U`. -Example::: `auto p = make_shared_noinit(1024);` +Example:: `auto p = make_shared_noinit(1024);` diff --git a/doc/smart_ptr/make_unique.adoc b/doc/smart_ptr/make_unique.adoc index ae3b325..65b6053 100644 --- a/doc/smart_ptr/make_unique.adoc +++ b/doc/smart_ptr/make_unique.adoc @@ -68,48 +68,48 @@ namespace boost { template std::unique_ptr make_unique(Args&&... args); ``` -:: -Remarks::: These overloads shall only participate in overload resolution when +[horizontal] +Remarks:: These overloads shall only participate in overload resolution when `T` is not an array type. -Returns::: `std::unique_ptr(new T(std::forward(args)\...)`. -Example::: `auto p = make_unique();` +Returns:: `std::unique_ptr(new T(std::forward(args)\...)`. +Example:: `auto p = make_unique();` ``` template std::unique_ptr make_unique(remove_reference_t&& v); ``` -:: -Remarks::: These overloads shall only participate in overload resolution when +[horizontal] +Remarks:: These overloads shall only participate in overload resolution when `T` is not an array type. -Returns::: `std::unique_ptr(new T(std::move(v))`. -Example::: `auto p = make_unique >({1, 2});` +Returns:: `std::unique_ptr(new T(std::move(v))`. +Example:: `auto p = make_unique >({1, 2});` ``` template std::unique_ptr make_unique(std::size_t n); ``` -:: -Remarks::: These overloads shall only participate in overload resolution when +[horizontal] +Remarks:: These overloads shall only participate in overload resolution when `T` is an array type of the form `U[]`. -Returns::: `std::unique_ptr(new U[n]())`. -Example::: `auto p = make_unique(1024);` +Returns:: `std::unique_ptr(new U[n]())`. +Example:: `auto p = make_unique(1024);` ``` template std::unique_ptr make_unique_noinit(); ``` -:: -Remarks::: These overloads shall only participate in overload resolution when +[horizontal] +Remarks:: These overloads shall only participate in overload resolution when `T` is not an array type. -Returns::: `std::unique_ptr(new T)`. -Example::: `auto p = make_unique_noinit();` +Returns:: `std::unique_ptr(new T)`. +Example:: `auto p = make_unique_noinit();` ``` template std::unique_ptr make_unique_noinit(std::size_t n); ``` -:: -Remarks::: These overloads shall only participate in overload resolution when +[horizontal] +Remarks:: These overloads shall only participate in overload resolution when `T` is an array type of the form `U[]`. -Returns::: `std::unique_ptr(new U[n])`. -Example::: `auto p = make_unique_noinit(1024);` +Returns:: `std::unique_ptr(new U[n])`. +Example:: `auto p = make_unique_noinit(1024);` diff --git a/doc/smart_ptr/pointer_cast.adoc b/doc/smart_ptr/pointer_cast.adoc index ccae283..67c5355 100644 --- a/doc/smart_ptr/pointer_cast.adoc +++ b/doc/smart_ptr/pointer_cast.adoc @@ -78,23 +78,23 @@ namespace boost { ``` template T* static_pointer_cast(U* p) noexcept; ``` -:: -Returns::: `static_cast(p)` +[horizontal] +Returns:: `static_cast(p)` ``` template std::shared_ptr static_pointer_cast(const std::shared_ptr& p) noexcept; ``` -:: -Returns::: `std::static_pointer_cast(p)` +[horizontal] +Returns:: `std::static_pointer_cast(p)` ``` template std::unique_ptr static_pointer_cast(std::unique_ptr&& p) noexcept; ``` -:: -Requires::: The expression `static_cast((U*)0)` must be well-formed. -Returns::: `std::unique_ptr(static_cast((U*)0)` must be well-formed. +Returns:: `std::unique_ptr(static_cast::element_type*>(p.release()))`. CAUTION: The seemingly equivalent expression @@ -106,25 +106,25 @@ undefined behavior, attempting to delete the same object twice. ``` template T* dynamic_pointer_cast(U* p) noexcept; ``` -:: -Returns::: `dynamic_cast(p)` +[horizontal] +Returns:: `dynamic_cast(p)` ``` template std::shared_ptr dynamic_pointer_cast(const std::shared_ptr& p) noexcept; ``` -:: -Returns::: `std::dynamic_pointer_cast(p)` +[horizontal] +Returns:: `std::dynamic_pointer_cast(p)` ``` template std::unique_ptr dynamic_pointer_cast(std::unique_ptr&& p) noexcept; ``` -:: -Requires::: +[horizontal] +Requires:: * The expression `static_cast((U*)0)` must be well-formed. * `T` must have a virtual destructor. -Returns::: +Returns:: * When `dynamic_cast::element_type*>(p.get())` returns a non-zero value, `std::unique_ptr(dynamic_cast::element_type*>(p.release()));`. @@ -135,23 +135,23 @@ std::unique_ptr::element_type*>(p.release()));`. ``` template T* const_pointer_cast(U* p) noexcept; ``` -:: -Returns::: `const_cast(p)` +[horizontal] +Returns:: `const_cast(p)` ``` template std::shared_ptr const_pointer_cast(const std::shared_ptr& p) noexcept; ``` -:: -Returns::: `std::const_pointer_cast(p)` +[horizontal] +Returns:: `std::const_pointer_cast(p)` ``` template std::unique_ptr const_pointer_cast(std::unique_ptr&& p) noexcept; ``` -:: -Requires::: The expression `const_cast((U*)0)` must be well-formed. -Returns::: `std::unique_ptr(const_cast((U*)0)` must be well-formed. +Returns:: `std::unique_ptr(const_cast::element_type*>(p.release()))`. ### reinterpret_pointer_cast @@ -159,23 +159,23 @@ std::unique_ptr::element_type*>(p.release()))`. ``` template T* reinterpret_pointer_cast(U* p) noexcept; ``` -:: -Returns::: `reinterpret_cast(p)` +[horizontal] +Returns:: `reinterpret_cast(p)` ``` template std::shared_ptr reinterpret_pointer_cast(const std::shared_ptr& p) noexcept; ``` -:: -Returns::: `std::reinterpret_pointer_cast(p)` +[horizontal] +Returns:: `std::reinterpret_pointer_cast(p)` ``` template std::unique_ptr reinterpret_pointer_cast(std::unique_ptr&& p) noexcept; ``` -:: -Requires::: The expression `reinterpret_cast((U*)0)` must be well-formed. -Returns::: `std::unique_ptr(reinterpret_cast((U*)0)` must be well-formed. +Returns:: `std::unique_ptr(reinterpret_cast::element_type*>(p.release()))`. ## Example diff --git a/doc/smart_ptr/shared_array.adoc b/doc/smart_ptr/shared_array.adoc index 5be074c..756ae3d 100644 --- a/doc/smart_ptr/shared_array.adoc +++ b/doc/smart_ptr/shared_array.adoc @@ -105,42 +105,42 @@ Type:: Provides the type of the stored pointer. ``` explicit shared_array(T* p = 0); ``` -:: -Effects::: Constructs a `shared_array`, storing a copy of `p`, which must be a +[horizontal] +Effects:: Constructs a `shared_array`, storing a copy of `p`, which must be a pointer to an array that was allocated via a C++ `new[]` expression or be 0. Afterwards, the use count is 1 (even if `p == 0`; see `~shared_array`). -Requires::: `T` is a complete type. -Throws::: `std::bad_alloc`. If an exception is thrown, `delete[] p` is called. +Requires:: `T` is a complete type. +Throws:: `std::bad_alloc`. If an exception is thrown, `delete[] p` is called. ``` template shared_array(T* p, D d); ``` -:: -Effects::: Constructs a `shared_array`, storing a copy of `p` and of `d`. +[horizontal] +Effects:: Constructs a `shared_array`, storing a copy of `p` and of `d`. Afterwards, the use count is 1. When the the time comes to delete the array pointed to by `p`, the object `d` is used in the statement `d(p)`. -Requires::: +Requires[horizontal] * `T` is a complete type. * The copy constructor and destructor of `D` must not throw. * Invoking the object `d` with parameter `p` must not throw. -Throws::: `std::bad_alloc`. If an exception is thrown, `d(p)` is called. +Throws:: `std::bad_alloc`. If an exception is thrown, `d(p)` is called. ``` shared_array(const shared_array& v) noexcept; ``` -:: -Effects::: Constructs a `shared_array`, as if by storing a copy of the pointer +[horizontal] +Effects:: Constructs a `shared_array`, as if by storing a copy of the pointer stored in `v`. Afterwards, the use count for all copies is 1 more than the initial use count. -Requires::: `T` is a complete type. +Requires:: `T` is a complete type. ### Destructor ``` ~shared_array() noexcept; ``` -:: -Effects::: Decrements the use count. Then, if the use count is 0, deletes the +[horizontal] +Effects:: Decrements the use count. Then, if the use count is 0, deletes the array pointed to by the stored pointer. Note that `delete[]` on a pointer with a value of 0 is harmless. @@ -149,60 +149,60 @@ a value of 0 is harmless. ``` shared_array& operator=(const shared_array& v) noexcept; ``` -:: -Effects::: Constructs a new `shared_array` as described above, then replaces +[horizontal] +Effects:: Constructs a new `shared_array` as described above, then replaces this `shared_array` with the new one, destroying the replaced object. -Requires::: `T` is a complete type. -Returns::: `*this`. +Requires:: `T` is a complete type. +Returns:: `*this`. ### reset ``` void reset(T* p = 0); ``` -:: -Effects::: Constructs a new `shared_array` as described above, then replaces +[horizontal] +Effects:: Constructs a new `shared_array` as described above, then replaces this `shared_array` with the new one, destroying the replaced object. -Requires::: `T` is a complete type. -Throws::: `std::bad_alloc`. If an exception is thrown, `delete[] p` is called. +Requires:: `T` is a complete type. +Throws:: `std::bad_alloc`. If an exception is thrown, `delete[] p` is called. ``` template void reset(T* p, D d); ``` -:: -Effects::: Constructs a new `shared_array` as described above, then replaces +[horizontal] +Effects:: Constructs a new `shared_array` as described above, then replaces this `shared_array` with the new one, destroying the replaced object. -Requires::: +Requires[horizontal] * `T` is a complete type. * The copy constructor of `D` must not throw. -Throws::: `std::bad_alloc`. If an exception is thrown, `d(p)` is called. +Throws:: `std::bad_alloc`. If an exception is thrown, `d(p)` is called. ### Indexing ``` T& operator[](std::ptrdiff_t n) const noexcept; ``` -Returns::: A reference to element `n` of the array pointed to by the stored +Returns:: A reference to element `n` of the array pointed to by the stored pointer. Behavior is undefined and almost certainly undesirable if the stored pointer is 0, or if `n` is less than 0 or is greater than or equal to the number of elements in the array. -Requires::: `T` is a complete type. +Requires:: `T` is a complete type. ### get ``` T* get() const noexcept; ``` -:: -Returns::: The stored pointer. +[horizontal] +Returns:: The stored pointer. ### unique ``` bool unique() const noexcept; ``` -:: -Returns::: `true` if no other `shared_array` is sharing ownership of the +[horizontal] +Returns:: `true` if no other `shared_array` is sharing ownership of the stored pointer, `false` otherwise. ### use_count @@ -210,8 +210,8 @@ stored pointer, `false` otherwise. ``` long use_count() const noexcept; ``` -:: -Returns::: The number of `shared_array` objects sharing ownership of the +[horizontal] +Returns:: The number of `shared_array` objects sharing ownership of the stored pointer. ### Conversions @@ -219,17 +219,17 @@ stored pointer. ``` explicit operator bool() const noexcept; ``` -:: -Returns::: `get() != 0`. -Requires::: `T` is a complete type. +[horizontal] +Returns:: `get() != 0`. +Requires:: `T` is a complete type. ### swap ``` void swap(shared_array& b) noexcept; ``` -:: -Effects::: Exchanges the contents of the two smart pointers. +[horizontal] +Effects:: Exchanges the contents of the two smart pointers. ## Free Functions @@ -247,8 +247,8 @@ template bool template bool operator<(const shared_array& a, const shared_array& b) noexcept; ``` -:: -Returns::: The result of comparing the stored pointers of the two smart +[horizontal] +Returns:: The result of comparing the stored pointers of the two smart pointers. NOTE: The `operator<` overload is provided to define an ordering so that @@ -265,6 +265,6 @@ mandates that relational operations on pointers are unspecified (5.9 template void swap(shared_array& a, shared_array& b) noexcept; ``` -:: -Returns::: `a.swap(b)`. -Requires::: `T` is a complete type. +[horizontal] +Returns:: `a.swap(b)`. +Requires:: `T` is a complete type. diff --git a/doc/smart_ptr/shared_ptr.adoc b/doc/smart_ptr/shared_ptr.adoc index 64761dd..96ac5c2 100644 --- a/doc/smart_ptr/shared_ptr.adoc +++ b/doc/smart_ptr/shared_ptr.adoc @@ -263,9 +263,7 @@ constexpr shared_ptr() noexcept; ``` constexpr shared_ptr(std::nullptr_t) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Constructs an empty `shared_ptr`. Postconditions:: `use_count() == 0 && get() == 0`. @@ -273,9 +271,7 @@ Postconditions:: `use_count() == 0 && get() == 0`. ``` template explicit shared_ptr(Y * p); ``` -[none] -* {blank} -+ +[horizontal] Requires:: `Y` must be a complete type. The expression `delete[] p`, when `T` is an array type, or `delete p`, when `T` is not an array type, must be well-formed, well-defined, and not throw exceptions. When `T` is `U[N]`, `Y(\*)[N]` must be convertible to `T*`; when `T` is `U[]`, `Y(\*)[]` must be convertible to `T*`; otherwise, `Y\*` must be convertible to `T*`. @@ -309,9 +305,7 @@ template shared_ptr(std::nullptr_t p, D d); ``` template shared_ptr(std::nullptr_t p, D d, A a); ``` -[none] -* {blank} -+ +[horizontal] Requires:: `D` must be `CopyConstructible`. The copy constructor and destructor of `D` must not throw. The expression `d(p)` must be well-formed, well-defined, and not throw exceptions. `A` must be an `Allocator`, as described in section Allocator Requirements [allocator.requirements] of the {cpp} Standard. When `T` is `U[N]`, `Y(\*)[N]` must be convertible to `T*`; when `T` is `U[]`, `Y(\*)[]` must be convertible to `T*`; otherwise, `Y\*` must be convertible to `T*`. @@ -341,9 +335,7 @@ shared_ptr(shared_ptr const & r) noexcept; ``` template shared_ptr(shared_ptr const & r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: `Y*` should be convertible to `T*`. Effects:: If `r` is empty, constructs an empty `shared_ptr`; otherwise, constructs a `shared_ptr` that shares ownership with `r`. @@ -357,9 +349,7 @@ shared_ptr(shared_ptr && r) noexcept; ``` template shared_ptr(shared_ptr && r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: `Y*` should be convertible to `T*`. Effects:: Move-constructs a `shared_ptr` from `r`. @@ -370,9 +360,7 @@ Postconditions:: `*this` contains the old value of `r`. `r` is empty and `r.get( ``` template shared_ptr(shared_ptr const & r, element_type * p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: constructs a `shared_ptr` that shares ownership with `r` and stores `p`. Postconditions:: `get() == p && use_count() == r.use_count()`. @@ -381,9 +369,7 @@ Postconditions:: `get() == p && use_count() == r.use_count()`. ``` template shared_ptr(shared_ptr && r, element_type * p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Move-constructs a `shared_ptr` from `r`, while storing `p` instead. Postconditions:: `get() == p` and `use_count()` equals the old count of `r`. `r` is empty and `r.get() == 0`. @@ -392,9 +378,7 @@ Postconditions:: `get() == p` and `use_count()` equals the old count of `r`. `r` ``` template explicit shared_ptr(weak_ptr const & r); ``` -[none] -* {blank} -+ +[horizontal] Requires:: `Y*` should be convertible to `T*`. Effects:: Constructs a `shared_ptr` that shares ownership with `r` and stores a copy of the pointer stored in `r`. @@ -412,9 +396,7 @@ template shared_ptr(std::auto_ptr & r); ``` template shared_ptr(std::auto_ptr && r); ``` -[none] -* {blank} -+ +[horizontal] Requires:: `Y*` should be convertible to `T*`. Effects:: Constructs a `shared_ptr`, as if by storing a copy of `r.release()`. @@ -429,9 +411,7 @@ Exception safety:: If an exception is thrown, the constructor has no effect. ``` template shared_ptr(std::unique_ptr && r); ``` -[none] -* {blank} -+ +[horizontal] Requires:: `Y*` should be convertible to `T*`. Effects:: @@ -448,9 +428,7 @@ Exception safety:: If an exception is thrown, the constructor has no effect. ``` ~shared_ptr() noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: - If `*this` is empty, or shares ownership with another `shared_ptr` instance (`use_count() > 1`), there are no side effects. - Otherwise, if `*this` owns a pointer `p` and a deleter `d`, `d(p)` is called. @@ -466,9 +444,7 @@ template shared_ptr & operator=(shared_ptr const & r) noexcept; ``` template shared_ptr & operator=(std::auto_ptr & r); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `shared_ptr(r).swap(*this)`. Returns:: `*this`. @@ -499,18 +475,14 @@ template shared_ptr & operator=(std::auto_ptr && r); ``` template shared_ptr & operator=(std::unique_ptr && r); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `shared_ptr(std::move(r)).swap(*this)`. Returns:: `*this`. ``` shared_ptr & operator=(std::nullptr_t) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `shared_ptr().swap(*this)`. Returns:: `*this`. @@ -518,76 +490,58 @@ Returns:: `*this`. ``` void reset() noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `shared_ptr().swap(*this)`. ``` template void reset(Y * p); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `shared_ptr(p).swap(*this)`. ``` template void reset(Y * p, D d); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `shared_ptr(p, d).swap(*this)`. ``` template void reset(Y * p, D d, A a); ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `shared_ptr(p, d, a).swap(*this)`. ``` template void reset(shared_ptr const & r, element_type * p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `shared_ptr(r, p).swap(*this)`. ``` template void reset(shared_ptr && r, element_type * p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `shared_ptr(std::move(r), p).swap(*this)`. ### indirection ``` T & operator*() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: `T` should not be an array type. The stored pointer must not be 0. Returns:: `*get()`. ``` T * operator->() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: `T` should not be an array type. The stored pointer must not be 0. Returns:: `get()`. ``` element_type & operator[](std::ptrdiff_t i) const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: `T` should be an array type. The stored pointer must not be 0. `i >= 0`. If `T` is `U[N]`, `i < N`. Returns:: `get()[i]`. @@ -596,36 +550,28 @@ Returns:: `get()[i]`. ``` element_type * get() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: The stored pointer. ### unique ``` bool unique() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `use_count() == 1`. ### use_count ``` long use_count() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: The number of `shared_ptr` objects, `*this` included, that share ownership with `*this`, or 0 when `*this` is empty. ### conversions ``` explicit operator bool() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `get() != 0`. NOTE: This conversion operator allows `shared_ptr` objects to be used in boolean contexts, like `if(p && p\->valid()) {}`. @@ -639,9 +585,7 @@ NOTE: On C++03 compilers, the return value is of an unspecified type. ``` void swap(shared_ptr & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Exchanges the contents of the two smart pointers. ### owner_before @@ -651,9 +595,7 @@ template bool owner_before(shared_ptr const & rhs) const noexcept; ``` template bool owner_before(weak_ptr const & rhs) const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: See the description of `operator<`. ## Free Functions @@ -663,18 +605,14 @@ Effects:: See the description of `operator<`. template bool operator==(shared_ptr const & a, shared_ptr const & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `a.get() == b.get()`. ``` template bool operator!=(shared_ptr const & a, shared_ptr const & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `a.get() != b.get()`. ``` @@ -683,9 +621,7 @@ template bool operator==(shared_ptr const & p, std::nullptr_t) noexc ``` template bool operator==(std::nullptr_t, shared_ptr const & p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `p.get() == 0`. ``` @@ -694,18 +630,14 @@ template bool operator!=(shared_ptr const & p, std::nullptr_t) noexc ``` template bool operator!=(std::nullptr_t, shared_ptr const & p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `p.get() != 0`. ``` template bool operator<(shared_ptr const & a, shared_ptr const & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: An unspecified value such that - `operator<` is a strict weak ordering as described in section [lib.alg.sorting] of the {cpp} standard; - under the equivalence relation defined by `operator<`, `!(a < b) && !(b < a)`, two `shared_ptr` instances @@ -719,9 +651,7 @@ NOTE: The rest of the comparison operators are omitted by design. ``` template void swap(shared_ptr & a, shared_ptr & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `a.swap(b)`. ### get_pointer @@ -730,9 +660,7 @@ template typename shared_ptr::element_type * get_pointer(shared_ptr const & p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `p.get()`. NOTE: Provided as an aid to generic programming. Used by `mem_fn`. @@ -742,9 +670,7 @@ NOTE: Provided as an aid to generic programming. Used by `mem_fn`. template shared_ptr static_pointer_cast(shared_ptr const & r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: The expression `static_cast( (U*)0 )` must be well-formed. Returns:: `shared_ptr( r, static_cast::element_type*>(r.get()) )`. @@ -756,9 +682,7 @@ result in undefined behavior, attempting to delete the same object twice. template shared_ptr const_pointer_cast(shared_ptr const & r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: The expression `const_cast( (U*)0 )` must be well-formed. Returns:: `shared_ptr( r, const_cast::element_type*>(r.get()) )`. @@ -767,9 +691,7 @@ Returns:: `shared_ptr( r, const_cast::element_type*>(r template shared_ptr dynamic_pointer_cast(shared_ptr const & r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: The expression `dynamic_cast( (U*)0 )` must be well-formed. Returns:: - When `dynamic_cast::element_type*>(r.get())` returns a nonzero value `p`, `shared_ptr(r, p)`; @@ -780,9 +702,7 @@ Returns:: template shared_ptr reinterpret_pointer_cast(shared_ptr const & r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Requires:: The expression `reinterpret_cast( (U*)0 )` must be well-formed. Returns:: `shared_ptr( r, reinterpret_cast::element_type*>(r.get()) )`. @@ -792,9 +712,7 @@ template std::basic_ostream & operator<< (std::basic_ostream & os, shared_ptr const & p); ``` -[none] -* {blank} -+ +[horizontal] Effects:: `os << p.get();`. Returns:: `os`. @@ -803,9 +721,7 @@ Returns:: `os`. template D * get_deleter(shared_ptr const & p) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: If `*this` owns a deleter `d` of type (cv-unqualified) `D`, returns `&d`; otherwise returns 0. ### Atomic Access @@ -817,9 +733,7 @@ NOTE: The function in this section are atomic with respect to the first `shared_ ``` template bool atomic_is_lock_free( shared_ptr const * p ) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `false`. NOTE: This implementation is not lock-free. @@ -830,9 +744,7 @@ template shared_ptr atomic_load( shared_ptr const * p ) noexcept; ``` template shared_ptr atomic_load_explicit( shared_ptr const * p, int ) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `*p`. NOTE: The `int` argument is the `memory_order`, but this implementation does not use it, as it's lock-based @@ -846,9 +758,7 @@ template template void atomic_store_explicit( shared_ptr * p, shared_ptr r, int ) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: `p\->swap(r)`. ``` @@ -860,9 +770,7 @@ template shared_ptr atomic_exchange_explicit( shared_ptr * p, shared_ptr r, int ) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: `p\->swap(r)`. Returns:: The old value of `*p`. @@ -876,9 +784,7 @@ template bool atomic_compare_exchange_explicit( shared_ptr * p, shared_ptr * v, shared_ptr w, int, int ) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: If `*p` is equivalent to `*v`, assigns `w` to `*p`, otherwise assigns `*p` to `*v`. Returns:: `true` if `*p` was equivalent to `*v`, `false` otherwise. Remarks:: Two `shared_ptr` instances are equivalent if they store the same pointer value and _share ownership_. diff --git a/doc/smart_ptr/weak_ptr.adoc b/doc/smart_ptr/weak_ptr.adoc index d51eaa1..75d86dc 100644 --- a/doc/smart_ptr/weak_ptr.adoc +++ b/doc/smart_ptr/weak_ptr.adoc @@ -127,9 +127,7 @@ typedef ... element_type; ``` weak_ptr() noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Constructs an empty `weak_ptr`. Postconditions:: `use_count() == 0`. @@ -142,18 +140,14 @@ weak_ptr(weak_ptr const & r) noexcept; ``` template weak_ptr(weak_ptr const & r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: If `r` is empty, constructs an empty `weak_ptr`; otherwise, constructs a `weak_ptr` that shares ownership with `r` as if by storing a copy of the pointer stored in `r`. Postconditions:: `use_count() == r.use_count()`. ``` weak_ptr(weak_ptr && r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Constructs a `weak_ptr` that has the value `r` held. Postconditions:: `r` is empty. @@ -161,9 +155,7 @@ Postconditions:: `r` is empty. ``` ~weak_ptr() noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Destroys this `weak_ptr` but has no effect on the object its stored pointer points to. ### assignment @@ -179,9 +171,7 @@ template weak_ptr & operator=(weak_ptr const & r) noexcept; ``` template weak_ptr & operator=(shared_ptr const & r) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `weak_ptr(r).swap(*this)`. NOTE: The implementation is free to meet the effects (and the implied guarantees) via different means, without creating a temporary. @@ -190,45 +180,35 @@ NOTE: The implementation is free to meet the effects (and the implied guarantees ``` long use_count() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: 0 if `*this` is empty; otherwise, the number of `shared_ptr` objects that share ownership with `*this`. ### expired ``` bool expired() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `use_count() == 0`. ### lock ``` shared_ptr lock() const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: `expired()? shared_ptr(): shared_ptr(*this)`. ### reset ``` void reset() noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `weak_ptr().swap(*this)`. ### swap ``` void swap(weak_ptr & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Exchanges the contents of the two smart pointers. ``` @@ -237,9 +217,7 @@ template bool owner_before( weak_ptr const & r ) const noexcept; ``` template bool owner_before( shared_ptr const & r ) const noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: See the description of `operator<`. ## Free Functions @@ -249,9 +227,7 @@ Returns:: See the description of `operator<`. template bool operator<(weak_ptr const & a, weak_ptr const & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Returns:: An unspecified value such that - `operator<` is a strict weak ordering as described in section [lib.alg.sorting] of the {cpp} standard; - under the equivalence relation defined by `operator<`, `!(a < b) && !(b < a)`, two `weak_ptr` instances @@ -263,9 +239,7 @@ NOTE: Allows `weak_ptr` objects to be used as keys in associative containers. ``` template void swap(weak_ptr & a, weak_ptr & b) noexcept; ``` -[none] -* {blank} -+ +[horizontal] Effects:: Equivalent to `a.swap(b)`. ## Frequently Asked Questions From d10299159ad6b138e6dcca60d5815b99f080cc08 Mon Sep 17 00:00:00 2001 From: Glen Fernandes Date: Sun, 24 Mar 2019 23:41:04 -0400 Subject: [PATCH 2/2] More asciidoctor changes Reinstate the none/blank trick, but remove the blank line after it in local_shared_ptr.adoc that causes the problem. Also use that trick in place of the nested DLs which don't work with Asciidoctor 2 --- doc/smart_ptr/intrusive_ptr.adoc | 116 ++++++++++---- doc/smart_ptr/intrusive_ref_counter.adoc | 24 ++- doc/smart_ptr/local_shared_ptr.adoc | 169 ++++++++++++++------ doc/smart_ptr/make_shared.adoc | 28 +++- doc/smart_ptr/make_unique.adoc | 20 ++- doc/smart_ptr/pointer_cast.adoc | 50 ++++-- doc/smart_ptr/shared_array.adoc | 60 ++++++-- doc/smart_ptr/shared_ptr.adoc | 188 +++++++++++++++++------ doc/smart_ptr/weak_ptr.adoc | 52 +++++-- 9 files changed, 528 insertions(+), 179 deletions(-) diff --git a/doc/smart_ptr/intrusive_ptr.adoc b/doc/smart_ptr/intrusive_ptr.adoc index 4f977f7..cb30a04 100644 --- a/doc/smart_ptr/intrusive_ptr.adoc +++ b/doc/smart_ptr/intrusive_ptr.adoc @@ -136,14 +136,18 @@ Provides the type of the template parameter T. intrusive_ptr() noexcept; ``` -[horizontal] +[none] +* {blank} ++ Postconditions:: `get() == 0`. ``` intrusive_ptr(T * p, bool add_ref = true); ``` -[horizontal] +[none] +* {blank} ++ Effects:: `if(p != 0 && add_ref) intrusive_ptr_add_ref(p);`. Postconditions:: `get() == p`. @@ -154,7 +158,9 @@ intrusive_ptr(intrusive_ptr const & r); template intrusive_ptr(intrusive_ptr const & r); ``` -[horizontal] +[none] +* {blank} ++ Effects:: `T * p = r.get(); if(p != 0) intrusive_ptr_add_ref(p);`. Postconditions:: `get() == r.get()`. @@ -165,7 +171,9 @@ intrusive_ptr(intrusive_ptr && r); template intrusive_ptr(intrusive_ptr && r); ``` -[horizontal] +[none] +* {blank} ++ Postconditions:: `get()` equals the old value of `r.get()`. `r.get() == 0`. ### destructor @@ -174,7 +182,9 @@ Postconditions:: `get()` equals the old value of `r.get()`. `r.get() == 0`. ~intrusive_ptr(); ``` -[horizontal] +[none] +* {blank} ++ Effects:: `if(get() != 0) intrusive_ptr_release(get());`. ### assignment @@ -189,7 +199,9 @@ template intrusive_ptr & operator=(intrusive_ptr const & r); intrusive_ptr & operator=(T * r); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `intrusive_ptr(r).swap(*this)`. Returns:: `*this`. @@ -200,7 +212,9 @@ intrusive_ptr & operator=(intrusive_ptr && r); template intrusive_ptr & operator=(intrusive_ptr && r); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `intrusive_ptr(std::move(r)).swap(*this)`. Returns:: `*this`. @@ -210,21 +224,27 @@ Returns:: `*this`. void reset(); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `intrusive_ptr().swap(*this)`. ``` void reset(T * r); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `intrusive_ptr(r).swap(*this)`. ``` void reset(T * r, bool add_ref); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `intrusive_ptr(r, add_ref).swap(*this)`. ### indirection @@ -233,7 +253,9 @@ Effects:: Equivalent to `intrusive_ptr(r, add_ref).swap(*this)`. T & operator*() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requirements:: `get() != 0`. Returns:: `*get()`. @@ -241,7 +263,9 @@ Returns:: `*get()`. T * operator->() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requirements:: `get() != 0`. Returns:: `get()`. @@ -251,7 +275,9 @@ Returns:: `get()`. T * get() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: the stored pointer. ### detach @@ -260,7 +286,9 @@ Returns:: the stored pointer. T * detach() noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: the stored pointer. Postconditions:: `get() == 0`. @@ -278,7 +306,9 @@ the implications are thoroughly understood. explicit operator bool () const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `get() != 0`. NOTE: This conversion operator allows `intrusive_ptr` objects to be used in boolean contexts, @@ -292,7 +322,9 @@ NOTE: On C++03 compilers, the return value is of an unspecified type. void swap(intrusive_ptr & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Exchanges the contents of the two smart pointers. ## Free Functions @@ -304,7 +336,9 @@ template bool operator==(intrusive_ptr const & a, intrusive_ptr const & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `a.get() == b.get()`. ``` @@ -312,7 +346,9 @@ template bool operator!=(intrusive_ptr const & a, intrusive_ptr const & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `a.get() != b.get()`. ``` @@ -320,7 +356,9 @@ template bool operator==(intrusive_ptr const & a, U * b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `a.get() == b`. ``` @@ -328,7 +366,9 @@ template bool operator!=(intrusive_ptr const & a, U * b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `a.get() != b`. ``` @@ -336,7 +376,9 @@ template bool operator==(T * a, intrusive_ptr const & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `a == b.get()`. ``` @@ -344,7 +386,9 @@ template bool operator!=(T * a, intrusive_ptr const & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `a != b.get()`. ``` @@ -352,7 +396,9 @@ template bool operator<(intrusive_ptr const & a, intrusive_ptr const & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `std::less()(a.get(), b.get())`. NOTE: Allows `intrusive_ptr` objects to be used as keys in associative containers. @@ -363,7 +409,9 @@ NOTE: Allows `intrusive_ptr` objects to be used as keys in associative container template void swap(intrusive_ptr & a, intrusive_ptr & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `a.swap(b)`. ### get_pointer @@ -372,7 +420,9 @@ Effects:: Equivalent to `a.swap(b)`. template T * get_pointer(intrusive_ptr const & p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `p.get()`. NOTE: Provided as an aid to generic programming. Used by `mem_fn`. @@ -384,7 +434,9 @@ template intrusive_ptr static_pointer_cast(intrusive_ptr const & r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `intrusive_ptr(static_cast(r.get()))`. ### const_pointer_cast @@ -394,7 +446,9 @@ template intrusive_ptr const_pointer_cast(intrusive_ptr const & r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `intrusive_ptr(const_cast(r.get()))`. ### dynamic_pointer_cast @@ -404,7 +458,9 @@ template intrusive_ptr dynamic_pointer_cast(intrusive_ptr const & r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `intrusive_ptr(dynamic_cast(r.get()))`. ### operator<< @@ -415,6 +471,8 @@ template intrusive_ptr const & p); ``` -[horizontal] +[none] +* {blank} ++ Effects:: `os << p.get();`. Returns:: `os`. diff --git a/doc/smart_ptr/intrusive_ref_counter.adoc b/doc/smart_ptr/intrusive_ref_counter.adoc index 4133c35..ef65902 100644 --- a/doc/smart_ptr/intrusive_ref_counter.adoc +++ b/doc/smart_ptr/intrusive_ref_counter.adoc @@ -81,7 +81,9 @@ intrusive_ref_counter() noexcept; ``` intrusive_ref_counter(const intrusive_ref_counter&) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Postconditions:: `use_count() == 0`. NOTE: The pointer to the constructed object is expected to be passed to @@ -93,7 +95,9 @@ would increment the reference counter. ``` ~intrusive_ref_counter(); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Destroys the counter object. NOTE: The destructor is protected so that the object can only be destroyed @@ -104,7 +108,9 @@ through the `Derived` class. ``` intrusive_ref_counter& operator=(const intrusive_ref_counter& v) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Does nothing, reference counter is not modified. ### use_count @@ -112,7 +118,9 @@ Effects:: Does nothing, reference counter is not modified. ``` unsigned int use_count() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: The current value of the reference counter. NOTE: The returned value may not be actual in multi-threaded applications. @@ -126,7 +134,9 @@ template void intrusive_ptr_add_ref( const intrusive_ref_counter* p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Increments the reference counter. ### intrusive_ptr_release @@ -136,6 +146,8 @@ template void intrusive_ptr_release( const intrusive_ref_counter* p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Decrements the reference counter. If the reference counter reaches 0, calls `delete static_cast(p)`. diff --git a/doc/smart_ptr/local_shared_ptr.adoc b/doc/smart_ptr/local_shared_ptr.adoc index 3cb807e..158179b 100644 --- a/doc/smart_ptr/local_shared_ptr.adoc +++ b/doc/smart_ptr/local_shared_ptr.adoc @@ -227,7 +227,9 @@ constexpr local_shared_ptr() noexcept; ``` constexpr local_shared_ptr(std::nullptr_t) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs an empty `local_shared_ptr`. Postconditions:: `local_use_count() == 0 && get() == 0`. @@ -235,7 +237,9 @@ Postconditions:: `local_use_count() == 0 && get() == 0`. ``` template explicit local_shared_ptr(Y * p); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs a `local_shared_ptr` that owns `shared_ptr( p )`. Postconditions:: `local_use_count() == 1 && get() == p`. @@ -249,7 +253,9 @@ template local_shared_ptr(Y * p, D d); ``` template local_shared_ptr(std::nullptr_t p, D d); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs a `local_shared_ptr` that owns `shared_ptr( p, d )`. Postconditions:: `local_use_count() == 1 && get() == p`. @@ -262,7 +268,9 @@ template local_shared_ptr(Y * p, D d, A a); ``` template local_shared_ptr(std::nullptr_t p, D d, A a); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs a `local_shared_ptr` that owns `shared_ptr( p, d, a )`. Postconditions:: `local_use_count() == 1 && get() == p`. @@ -276,7 +284,9 @@ local_shared_ptr(local_shared_ptr const & r) noexcept; ``` template local_shared_ptr(local_shared_ptr const & r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: `Y*` should be convertible to `T*`. Effects:: If `r` is empty, constructs an empty `local_shared_ptr`; otherwise, constructs a `local_shared_ptr` that shares ownership with `r`. @@ -290,7 +300,9 @@ local_shared_ptr(local_shared_ptr && r) noexcept; ``` template local_shared_ptr(local_shared_ptr && r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: `Y*` should be convertible to `T*`. Effects:: Move-constructs a `local_shared_ptr` from `r`. @@ -304,7 +316,9 @@ template local_shared_ptr( shared_ptr const & r ); ``` template local_shared_ptr( shared_ptr && r ); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs a `local_shared_ptr` that owns `r`. Postconditions:: `local_use_count() == 1`. `get()` returns the old value of `r.get()`. @@ -315,7 +329,9 @@ Throws:: `std::bad_alloc`, or an implementation-defined exception when a resourc ``` template local_shared_ptr(local_shared_ptr const & r, element_type * p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: constructs a `local_shared_ptr` that shares ownership with `r` and stores `p`. Postconditions:: `get() == p && local_use_count() == r.local_use_count()`. @@ -324,7 +340,9 @@ Postconditions:: `get() == p && local_use_count() == r.local_use_count()`. ``` template local_shared_ptr(local_shared_ptr && r, element_type * p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Move-constructs a `local_shared_ptr` from `r`, while storing `p` instead. Postconditions:: `get() == p` and `local_use_count()` equals the old count of `r`. `r` is empty and `r.get() == 0`. @@ -333,7 +351,9 @@ Postconditions:: `get() == p` and `local_use_count()` equals the old count of `r ``` template local_shared_ptr(std::unique_ptr && r); ``` -[horizontal] +[none] +* {blank} ++ Requires:: `Y*` should be convertible to `T*`. Effects:: @@ -348,7 +368,9 @@ Exception safety:: If an exception is thrown, the constructor has no effect. ``` ~local_shared_ptr() noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: - If `*this` is empty, or shares ownership with another `local_shared_ptr` instance (`local_use_count() > 1`), there are no side effects. - Otherwise, destroys the owned `shared_ptr`. @@ -360,7 +382,9 @@ local_shared_ptr & operator=(local_shared_ptr const & r) noexcept; ``` template local_shared_ptr & operator=(local_shared_ptr const & r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `local_shared_ptr(r).swap(*this)`. Returns:: `*this`. @@ -373,14 +397,18 @@ template local_shared_ptr & operator=(local_shared_ptr && r) noexcep ``` template local_shared_ptr & operator=(std::unique_ptr && r); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `local_shared_ptr(std::move(r)).swap(*this)`. Returns:: `*this`. ``` local_shared_ptr & operator=(std::nullptr_t) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `local_shared_ptr().swap(*this)`. Returns:: `*this`. @@ -388,58 +416,76 @@ Returns:: `*this`. ``` void reset() noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `local_shared_ptr().swap(*this)`. ``` template void reset(Y * p); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `local_shared_ptr(p).swap(*this)`. ``` template void reset(Y * p, D d); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `local_shared_ptr(p, d).swap(*this)`. ``` template void reset(Y * p, D d, A a); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `local_shared_ptr(p, d, a).swap(*this)`. ``` template void reset(local_shared_ptr const & r, element_type * p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `local_shared_ptr(r, p).swap(*this)`. ``` template void reset(local_shared_ptr && r, element_type * p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `local_shared_ptr(std::move(r), p).swap(*this)`. ### indirection ``` T & operator*() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: `T` should not be an array type. Returns:: `*get()`. ``` T * operator->() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: `T` should not be an array type. Returns:: `get()`. ``` element_type & operator[](std::ptrdiff_t i) const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: `T` should be an array type. The stored pointer must not be 0. `i >= 0`. If `T` is `U[N]`, `i < N`. Returns:: `get()[i]`. @@ -448,21 +494,27 @@ Returns:: `get()[i]`. ``` element_type * get() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: The stored pointer. ### local_use_count ``` long local_use_count() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: The number of `local_shared_ptr` objects, `*this` included, that share ownership with `*this`, or 0 when `*this` is empty. ### conversions ``` explicit operator bool() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `get() != 0`. NOTE: On C++03 compilers, the return value is of an unspecified type. @@ -473,7 +525,9 @@ template operator shared_ptr() const noexcept; ``` template operator weak_ptr() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: `T*` should be convertible to `Y*`. Returns:: a copy of the owned `shared_ptr`. @@ -481,14 +535,18 @@ Returns:: a copy of the owned `shared_ptr`. ``` void swap(local_shared_ptr & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Exchanges the contents of the two smart pointers. ### owner_before ``` template bool owner_before(local_shared_ptr const & rhs) const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: See the description of `operator<`. ## Free Functions @@ -506,7 +564,9 @@ template template bool operator==(shared_ptr const & a, local_shared_ptr const & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `a.get() == b.get()`. ``` @@ -521,7 +581,9 @@ template template bool operator!=(shared_ptr const & a, local_shared_ptr const & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `a.get() != b.get()`. ``` @@ -530,7 +592,9 @@ template bool operator==(local_shared_ptr const & p, std::nullptr_t) ``` template bool operator==(std::nullptr_t, local_shared_ptr const & p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `p.get() == 0`. ``` @@ -539,14 +603,18 @@ template bool operator!=(local_shared_ptr const & p, std::nullptr_t) ``` template bool operator!=(std::nullptr_t, local_shared_ptr const & p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `p.get() != 0`. ``` template bool operator<(local_shared_ptr const & a, local_shared_ptr const & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: An unspecified value such that - `operator<` is a strict weak ordering as described in section [lib.alg.sorting] of the {cpp} standard; - under the equivalence relation defined by `operator<`, `!(a < b) && !(b < a)`, two `local_shared_ptr` instances @@ -560,7 +628,9 @@ NOTE: The rest of the comparison operators are omitted by design. ``` template void swap(local_shared_ptr & a, local_shared_ptr & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `a.swap(b)`. ### get_pointer @@ -569,7 +639,9 @@ template typename local_shared_ptr::element_type * get_pointer(local_shared_ptr const & p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `p.get()`. NOTE: Provided as an aid to generic programming. Used by `mem_fn`. @@ -579,7 +651,9 @@ NOTE: Provided as an aid to generic programming. Used by `mem_fn`. template local_shared_ptr static_pointer_cast(local_shared_ptr const & r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: The expression `static_cast( (U*)0 )` must be well-formed. Returns:: `local_shared_ptr( r, static_cast::element_type*>(r.get()) )`. @@ -591,7 +665,9 @@ result in undefined behavior, attempting to delete the same object twice. template local_shared_ptr const_pointer_cast(local_shared_ptr const & r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: The expression `const_cast( (U*)0 )` must be well-formed. Returns:: `local_shared_ptr( r, const_cast::element_type*>(r.get()) )`. @@ -600,7 +676,9 @@ Returns:: `local_shared_ptr( r, const_cast::elem template local_shared_ptr dynamic_pointer_cast(local_shared_ptr const & r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: The expression `dynamic_cast( (U*)0 )` must be well-formed. Returns:: - When `dynamic_cast::element_type*>(r.get())` returns a nonzero value `p`, `local_shared_ptr(r, p)`; @@ -611,7 +689,9 @@ Returns:: template local_shared_ptr reinterpret_pointer_cast(local_shared_ptr const & r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: The expression `reinterpret_cast( (U*)0 )` must be well-formed. Returns:: `local_shared_ptr( r, reinterpret_cast::element_type*>(r.get()) )`. @@ -621,7 +701,9 @@ template std::basic_ostream & operator<< (std::basic_ostream & os, local_shared_ptr const & p); ``` -[horizontal] +[none] +* {blank} ++ Effects:: `os << p.get();`. Returns:: `os`. @@ -630,6 +712,7 @@ Returns:: `os`. template D * get_deleter(local_shared_ptr const & p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: If `*this` owns a `shared_ptr` instance `p`, `get_deleter( p )`, otherwise 0. - diff --git a/doc/smart_ptr/make_shared.adoc b/doc/smart_ptr/make_shared.adoc index ed4c901..375a91e 100644 --- a/doc/smart_ptr/make_shared.adoc +++ b/doc/smart_ptr/make_shared.adoc @@ -178,7 +178,9 @@ template template shared_ptr allocate_shared(const A& a, Args&&... args); ``` -[horizontal] +[none] +* {blank} ++ Remarks:: These overloads shall only participate in overload resolution when `T` is not an array type. Returns:: A `shared_ptr` to an object of type `T`, constructed from @@ -195,7 +197,9 @@ template template shared_ptr allocate_shared(const A& a, std::size_t n); ``` -[horizontal] +[none] +* {blank} ++ Remarks:: These overloads shall only participate in overload resolution when `T` is an array type of the form `U[]`. Returns:: A `shared_ptr` to a sequence of `n` value-initialized objects of @@ -212,7 +216,9 @@ template template shared_ptr allocate_shared(const A& a); ``` -[horizontal] +[none] +* {blank} ++ Remarks:: These overloads shall only participate in overload resolution when `T` is an array type of the form `U[N]`. Returns:: A `shared_ptr` to a sequence of `N` value-initialized objects of @@ -229,7 +235,9 @@ template shared_ptr template shared_ptr allocate_shared(const A& a, std::size_t n, const remove_extent_t& v); ``` -[horizontal] +[none] +* {blank} ++ Remarks:: These overloads shall only participate in overload resolution when `T` is an array type of the form `U[]`. Returns:: A `shared_ptr` to a sequence of `n` objects of type `U`, each @@ -247,7 +255,9 @@ template template shared_ptr allocate_shared(const A& a, const remove_extent_t& v); ``` -[horizontal] +[none] +* {blank} ++ Remarks:: These overloads shall only participate in overload resolution when `T` is an array type of the form `U[N]`. Returns:: A `shared_ptr` to a sequence of `N` objects of type `U`, each @@ -265,7 +275,9 @@ template template shared_ptr allocate_shared_noinit(const A& a); ``` -[horizontal] +[none] +* {blank} ++ Remarks:: These overloads shall only participate in overload resolution when `T` is not an array type, or an array type of the `U[N]`. Returns:: A `shared_ptr` to a default-initialized object of type `T`, or a @@ -280,7 +292,9 @@ template template shared_ptr allocate_shared_noinit(const A& a, std::size_t n); ``` -[horizontal] +[none] +* {blank} ++ Remarks:: These overloads shall only participate in overload resolution when `T` is an array type of the form `U[]`. Returns:: A `shared_ptr` to a sequence of `_n_` default-initialized objects diff --git a/doc/smart_ptr/make_unique.adoc b/doc/smart_ptr/make_unique.adoc index 65b6053..feb569c 100644 --- a/doc/smart_ptr/make_unique.adoc +++ b/doc/smart_ptr/make_unique.adoc @@ -68,7 +68,9 @@ namespace boost { template std::unique_ptr make_unique(Args&&... args); ``` -[horizontal] +[none] +* {blank} ++ Remarks:: These overloads shall only participate in overload resolution when `T` is not an array type. Returns:: `std::unique_ptr(new T(std::forward(args)\...)`. @@ -78,7 +80,9 @@ Example:: `auto p = make_unique();` template std::unique_ptr make_unique(remove_reference_t&& v); ``` -[horizontal] +[none] +* {blank} ++ Remarks:: These overloads shall only participate in overload resolution when `T` is not an array type. Returns:: `std::unique_ptr(new T(std::move(v))`. @@ -88,7 +92,9 @@ Example:: `auto p = make_unique >({1, 2});` template std::unique_ptr make_unique(std::size_t n); ``` -[horizontal] +[none] +* {blank} ++ Remarks:: These overloads shall only participate in overload resolution when `T` is an array type of the form `U[]`. Returns:: `std::unique_ptr(new U[n]())`. @@ -98,7 +104,9 @@ Example:: `auto p = make_unique(1024);` template std::unique_ptr make_unique_noinit(); ``` -[horizontal] +[none] +* {blank} ++ Remarks:: These overloads shall only participate in overload resolution when `T` is not an array type. Returns:: `std::unique_ptr(new T)`. @@ -108,7 +116,9 @@ Example:: `auto p = make_unique_noinit();` template std::unique_ptr make_unique_noinit(std::size_t n); ``` -[horizontal] +[none] +* {blank} ++ Remarks:: These overloads shall only participate in overload resolution when `T` is an array type of the form `U[]`. Returns:: `std::unique_ptr(new U[n])`. diff --git a/doc/smart_ptr/pointer_cast.adoc b/doc/smart_ptr/pointer_cast.adoc index 67c5355..5c2ef54 100644 --- a/doc/smart_ptr/pointer_cast.adoc +++ b/doc/smart_ptr/pointer_cast.adoc @@ -78,21 +78,27 @@ namespace boost { ``` template T* static_pointer_cast(U* p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `static_cast(p)` ``` template std::shared_ptr static_pointer_cast(const std::shared_ptr& p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `std::static_pointer_cast(p)` ``` template std::unique_ptr static_pointer_cast(std::unique_ptr&& p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: The expression `static_cast((U*)0)` must be well-formed. Returns:: `std::unique_ptr(static_cast::element_type*>(p.release()))`. @@ -106,21 +112,27 @@ undefined behavior, attempting to delete the same object twice. ``` template T* dynamic_pointer_cast(U* p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `dynamic_cast(p)` ``` template std::shared_ptr dynamic_pointer_cast(const std::shared_ptr& p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `std::dynamic_pointer_cast(p)` ``` template std::unique_ptr dynamic_pointer_cast(std::unique_ptr&& p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: * The expression `static_cast((U*)0)` must be well-formed. * `T` must have a virtual destructor. @@ -135,21 +147,27 @@ std::unique_ptr::element_type*>(p.release()));`. ``` template T* const_pointer_cast(U* p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `const_cast(p)` ``` template std::shared_ptr const_pointer_cast(const std::shared_ptr& p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `std::const_pointer_cast(p)` ``` template std::unique_ptr const_pointer_cast(std::unique_ptr&& p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: The expression `const_cast((U*)0)` must be well-formed. Returns:: `std::unique_ptr(const_cast::element_type*>(p.release()))`. @@ -159,21 +177,27 @@ std::unique_ptr::element_type*>(p.release()))`. ``` template T* reinterpret_pointer_cast(U* p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `reinterpret_cast(p)` ``` template std::shared_ptr reinterpret_pointer_cast(const std::shared_ptr& p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `std::reinterpret_pointer_cast(p)` ``` template std::unique_ptr reinterpret_pointer_cast(std::unique_ptr&& p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: The expression `reinterpret_cast((U*)0)` must be well-formed. Returns:: `std::unique_ptr(reinterpret_cast::element_type*>(p.release()))`. @@ -210,4 +234,4 @@ int main() delete ptr; } -``` \ No newline at end of file +``` diff --git a/doc/smart_ptr/shared_array.adoc b/doc/smart_ptr/shared_array.adoc index 756ae3d..18bd669 100644 --- a/doc/smart_ptr/shared_array.adoc +++ b/doc/smart_ptr/shared_array.adoc @@ -105,7 +105,9 @@ Type:: Provides the type of the stored pointer. ``` explicit shared_array(T* p = 0); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs a `shared_array`, storing a copy of `p`, which must be a pointer to an array that was allocated via a C++ `new[]` expression or be 0. Afterwards, the use count is 1 (even if `p == 0`; see `~shared_array`). @@ -115,11 +117,13 @@ Throws:: `std::bad_alloc`. If an exception is thrown, `delete[] p` is called. ``` template shared_array(T* p, D d); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs a `shared_array`, storing a copy of `p` and of `d`. Afterwards, the use count is 1. When the the time comes to delete the array pointed to by `p`, the object `d` is used in the statement `d(p)`. -Requires[horizontal] +Requires:: * `T` is a complete type. * The copy constructor and destructor of `D` must not throw. * Invoking the object `d` with parameter `p` must not throw. @@ -128,7 +132,9 @@ Throws:: `std::bad_alloc`. If an exception is thrown, `d(p)` is called. ``` shared_array(const shared_array& v) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs a `shared_array`, as if by storing a copy of the pointer stored in `v`. Afterwards, the use count for all copies is 1 more than the initial use count. @@ -139,7 +145,9 @@ Requires:: `T` is a complete type. ``` ~shared_array() noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Decrements the use count. Then, if the use count is 0, deletes the array pointed to by the stored pointer. Note that `delete[]` on a pointer with a value of 0 is harmless. @@ -149,7 +157,9 @@ a value of 0 is harmless. ``` shared_array& operator=(const shared_array& v) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs a new `shared_array` as described above, then replaces this `shared_array` with the new one, destroying the replaced object. Requires:: `T` is a complete type. @@ -160,7 +170,9 @@ Returns:: `*this`. ``` void reset(T* p = 0); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs a new `shared_array` as described above, then replaces this `shared_array` with the new one, destroying the replaced object. Requires:: `T` is a complete type. @@ -169,10 +181,12 @@ Throws:: `std::bad_alloc`. If an exception is thrown, `delete[] p` is called. ``` template void reset(T* p, D d); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs a new `shared_array` as described above, then replaces this `shared_array` with the new one, destroying the replaced object. -Requires[horizontal] +Requires:: * `T` is a complete type. * The copy constructor of `D` must not throw. Throws:: `std::bad_alloc`. If an exception is thrown, `d(p)` is called. @@ -193,7 +207,9 @@ Requires:: `T` is a complete type. ``` T* get() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: The stored pointer. ### unique @@ -201,7 +217,9 @@ Returns:: The stored pointer. ``` bool unique() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `true` if no other `shared_array` is sharing ownership of the stored pointer, `false` otherwise. @@ -210,7 +228,9 @@ stored pointer, `false` otherwise. ``` long use_count() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: The number of `shared_array` objects sharing ownership of the stored pointer. @@ -219,7 +239,9 @@ stored pointer. ``` explicit operator bool() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `get() != 0`. Requires:: `T` is a complete type. @@ -228,7 +250,9 @@ Requires:: `T` is a complete type. ``` void swap(shared_array& b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Exchanges the contents of the two smart pointers. ## Free Functions @@ -247,7 +271,9 @@ template bool template bool operator<(const shared_array& a, const shared_array& b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: The result of comparing the stored pointers of the two smart pointers. @@ -265,6 +291,8 @@ mandates that relational operations on pointers are unspecified (5.9 template void swap(shared_array& a, shared_array& b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `a.swap(b)`. Requires:: `T` is a complete type. diff --git a/doc/smart_ptr/shared_ptr.adoc b/doc/smart_ptr/shared_ptr.adoc index 96ac5c2..64761dd 100644 --- a/doc/smart_ptr/shared_ptr.adoc +++ b/doc/smart_ptr/shared_ptr.adoc @@ -263,7 +263,9 @@ constexpr shared_ptr() noexcept; ``` constexpr shared_ptr(std::nullptr_t) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs an empty `shared_ptr`. Postconditions:: `use_count() == 0 && get() == 0`. @@ -271,7 +273,9 @@ Postconditions:: `use_count() == 0 && get() == 0`. ``` template explicit shared_ptr(Y * p); ``` -[horizontal] +[none] +* {blank} ++ Requires:: `Y` must be a complete type. The expression `delete[] p`, when `T` is an array type, or `delete p`, when `T` is not an array type, must be well-formed, well-defined, and not throw exceptions. When `T` is `U[N]`, `Y(\*)[N]` must be convertible to `T*`; when `T` is `U[]`, `Y(\*)[]` must be convertible to `T*`; otherwise, `Y\*` must be convertible to `T*`. @@ -305,7 +309,9 @@ template shared_ptr(std::nullptr_t p, D d); ``` template shared_ptr(std::nullptr_t p, D d, A a); ``` -[horizontal] +[none] +* {blank} ++ Requires:: `D` must be `CopyConstructible`. The copy constructor and destructor of `D` must not throw. The expression `d(p)` must be well-formed, well-defined, and not throw exceptions. `A` must be an `Allocator`, as described in section Allocator Requirements [allocator.requirements] of the {cpp} Standard. When `T` is `U[N]`, `Y(\*)[N]` must be convertible to `T*`; when `T` is `U[]`, `Y(\*)[]` must be convertible to `T*`; otherwise, `Y\*` must be convertible to `T*`. @@ -335,7 +341,9 @@ shared_ptr(shared_ptr const & r) noexcept; ``` template shared_ptr(shared_ptr const & r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: `Y*` should be convertible to `T*`. Effects:: If `r` is empty, constructs an empty `shared_ptr`; otherwise, constructs a `shared_ptr` that shares ownership with `r`. @@ -349,7 +357,9 @@ shared_ptr(shared_ptr && r) noexcept; ``` template shared_ptr(shared_ptr && r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: `Y*` should be convertible to `T*`. Effects:: Move-constructs a `shared_ptr` from `r`. @@ -360,7 +370,9 @@ Postconditions:: `*this` contains the old value of `r`. `r` is empty and `r.get( ``` template shared_ptr(shared_ptr const & r, element_type * p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: constructs a `shared_ptr` that shares ownership with `r` and stores `p`. Postconditions:: `get() == p && use_count() == r.use_count()`. @@ -369,7 +381,9 @@ Postconditions:: `get() == p && use_count() == r.use_count()`. ``` template shared_ptr(shared_ptr && r, element_type * p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Move-constructs a `shared_ptr` from `r`, while storing `p` instead. Postconditions:: `get() == p` and `use_count()` equals the old count of `r`. `r` is empty and `r.get() == 0`. @@ -378,7 +392,9 @@ Postconditions:: `get() == p` and `use_count()` equals the old count of `r`. `r` ``` template explicit shared_ptr(weak_ptr const & r); ``` -[horizontal] +[none] +* {blank} ++ Requires:: `Y*` should be convertible to `T*`. Effects:: Constructs a `shared_ptr` that shares ownership with `r` and stores a copy of the pointer stored in `r`. @@ -396,7 +412,9 @@ template shared_ptr(std::auto_ptr & r); ``` template shared_ptr(std::auto_ptr && r); ``` -[horizontal] +[none] +* {blank} ++ Requires:: `Y*` should be convertible to `T*`. Effects:: Constructs a `shared_ptr`, as if by storing a copy of `r.release()`. @@ -411,7 +429,9 @@ Exception safety:: If an exception is thrown, the constructor has no effect. ``` template shared_ptr(std::unique_ptr && r); ``` -[horizontal] +[none] +* {blank} ++ Requires:: `Y*` should be convertible to `T*`. Effects:: @@ -428,7 +448,9 @@ Exception safety:: If an exception is thrown, the constructor has no effect. ``` ~shared_ptr() noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: - If `*this` is empty, or shares ownership with another `shared_ptr` instance (`use_count() > 1`), there are no side effects. - Otherwise, if `*this` owns a pointer `p` and a deleter `d`, `d(p)` is called. @@ -444,7 +466,9 @@ template shared_ptr & operator=(shared_ptr const & r) noexcept; ``` template shared_ptr & operator=(std::auto_ptr & r); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `shared_ptr(r).swap(*this)`. Returns:: `*this`. @@ -475,14 +499,18 @@ template shared_ptr & operator=(std::auto_ptr && r); ``` template shared_ptr & operator=(std::unique_ptr && r); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `shared_ptr(std::move(r)).swap(*this)`. Returns:: `*this`. ``` shared_ptr & operator=(std::nullptr_t) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `shared_ptr().swap(*this)`. Returns:: `*this`. @@ -490,58 +518,76 @@ Returns:: `*this`. ``` void reset() noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `shared_ptr().swap(*this)`. ``` template void reset(Y * p); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `shared_ptr(p).swap(*this)`. ``` template void reset(Y * p, D d); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `shared_ptr(p, d).swap(*this)`. ``` template void reset(Y * p, D d, A a); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `shared_ptr(p, d, a).swap(*this)`. ``` template void reset(shared_ptr const & r, element_type * p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `shared_ptr(r, p).swap(*this)`. ``` template void reset(shared_ptr && r, element_type * p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `shared_ptr(std::move(r), p).swap(*this)`. ### indirection ``` T & operator*() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: `T` should not be an array type. The stored pointer must not be 0. Returns:: `*get()`. ``` T * operator->() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: `T` should not be an array type. The stored pointer must not be 0. Returns:: `get()`. ``` element_type & operator[](std::ptrdiff_t i) const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: `T` should be an array type. The stored pointer must not be 0. `i >= 0`. If `T` is `U[N]`, `i < N`. Returns:: `get()[i]`. @@ -550,28 +596,36 @@ Returns:: `get()[i]`. ``` element_type * get() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: The stored pointer. ### unique ``` bool unique() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `use_count() == 1`. ### use_count ``` long use_count() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: The number of `shared_ptr` objects, `*this` included, that share ownership with `*this`, or 0 when `*this` is empty. ### conversions ``` explicit operator bool() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `get() != 0`. NOTE: This conversion operator allows `shared_ptr` objects to be used in boolean contexts, like `if(p && p\->valid()) {}`. @@ -585,7 +639,9 @@ NOTE: On C++03 compilers, the return value is of an unspecified type. ``` void swap(shared_ptr & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Exchanges the contents of the two smart pointers. ### owner_before @@ -595,7 +651,9 @@ template bool owner_before(shared_ptr const & rhs) const noexcept; ``` template bool owner_before(weak_ptr const & rhs) const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: See the description of `operator<`. ## Free Functions @@ -605,14 +663,18 @@ Effects:: See the description of `operator<`. template bool operator==(shared_ptr const & a, shared_ptr const & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `a.get() == b.get()`. ``` template bool operator!=(shared_ptr const & a, shared_ptr const & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `a.get() != b.get()`. ``` @@ -621,7 +683,9 @@ template bool operator==(shared_ptr const & p, std::nullptr_t) noexc ``` template bool operator==(std::nullptr_t, shared_ptr const & p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `p.get() == 0`. ``` @@ -630,14 +694,18 @@ template bool operator!=(shared_ptr const & p, std::nullptr_t) noexc ``` template bool operator!=(std::nullptr_t, shared_ptr const & p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `p.get() != 0`. ``` template bool operator<(shared_ptr const & a, shared_ptr const & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: An unspecified value such that - `operator<` is a strict weak ordering as described in section [lib.alg.sorting] of the {cpp} standard; - under the equivalence relation defined by `operator<`, `!(a < b) && !(b < a)`, two `shared_ptr` instances @@ -651,7 +719,9 @@ NOTE: The rest of the comparison operators are omitted by design. ``` template void swap(shared_ptr & a, shared_ptr & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `a.swap(b)`. ### get_pointer @@ -660,7 +730,9 @@ template typename shared_ptr::element_type * get_pointer(shared_ptr const & p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `p.get()`. NOTE: Provided as an aid to generic programming. Used by `mem_fn`. @@ -670,7 +742,9 @@ NOTE: Provided as an aid to generic programming. Used by `mem_fn`. template shared_ptr static_pointer_cast(shared_ptr const & r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: The expression `static_cast( (U*)0 )` must be well-formed. Returns:: `shared_ptr( r, static_cast::element_type*>(r.get()) )`. @@ -682,7 +756,9 @@ result in undefined behavior, attempting to delete the same object twice. template shared_ptr const_pointer_cast(shared_ptr const & r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: The expression `const_cast( (U*)0 )` must be well-formed. Returns:: `shared_ptr( r, const_cast::element_type*>(r.get()) )`. @@ -691,7 +767,9 @@ Returns:: `shared_ptr( r, const_cast::element_type*>(r template shared_ptr dynamic_pointer_cast(shared_ptr const & r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: The expression `dynamic_cast( (U*)0 )` must be well-formed. Returns:: - When `dynamic_cast::element_type*>(r.get())` returns a nonzero value `p`, `shared_ptr(r, p)`; @@ -702,7 +780,9 @@ Returns:: template shared_ptr reinterpret_pointer_cast(shared_ptr const & r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Requires:: The expression `reinterpret_cast( (U*)0 )` must be well-formed. Returns:: `shared_ptr( r, reinterpret_cast::element_type*>(r.get()) )`. @@ -712,7 +792,9 @@ template std::basic_ostream & operator<< (std::basic_ostream & os, shared_ptr const & p); ``` -[horizontal] +[none] +* {blank} ++ Effects:: `os << p.get();`. Returns:: `os`. @@ -721,7 +803,9 @@ Returns:: `os`. template D * get_deleter(shared_ptr const & p) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: If `*this` owns a deleter `d` of type (cv-unqualified) `D`, returns `&d`; otherwise returns 0. ### Atomic Access @@ -733,7 +817,9 @@ NOTE: The function in this section are atomic with respect to the first `shared_ ``` template bool atomic_is_lock_free( shared_ptr const * p ) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `false`. NOTE: This implementation is not lock-free. @@ -744,7 +830,9 @@ template shared_ptr atomic_load( shared_ptr const * p ) noexcept; ``` template shared_ptr atomic_load_explicit( shared_ptr const * p, int ) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `*p`. NOTE: The `int` argument is the `memory_order`, but this implementation does not use it, as it's lock-based @@ -758,7 +846,9 @@ template template void atomic_store_explicit( shared_ptr * p, shared_ptr r, int ) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: `p\->swap(r)`. ``` @@ -770,7 +860,9 @@ template shared_ptr atomic_exchange_explicit( shared_ptr * p, shared_ptr r, int ) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: `p\->swap(r)`. Returns:: The old value of `*p`. @@ -784,7 +876,9 @@ template bool atomic_compare_exchange_explicit( shared_ptr * p, shared_ptr * v, shared_ptr w, int, int ) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: If `*p` is equivalent to `*v`, assigns `w` to `*p`, otherwise assigns `*p` to `*v`. Returns:: `true` if `*p` was equivalent to `*v`, `false` otherwise. Remarks:: Two `shared_ptr` instances are equivalent if they store the same pointer value and _share ownership_. diff --git a/doc/smart_ptr/weak_ptr.adoc b/doc/smart_ptr/weak_ptr.adoc index 75d86dc..d51eaa1 100644 --- a/doc/smart_ptr/weak_ptr.adoc +++ b/doc/smart_ptr/weak_ptr.adoc @@ -127,7 +127,9 @@ typedef ... element_type; ``` weak_ptr() noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs an empty `weak_ptr`. Postconditions:: `use_count() == 0`. @@ -140,14 +142,18 @@ weak_ptr(weak_ptr const & r) noexcept; ``` template weak_ptr(weak_ptr const & r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: If `r` is empty, constructs an empty `weak_ptr`; otherwise, constructs a `weak_ptr` that shares ownership with `r` as if by storing a copy of the pointer stored in `r`. Postconditions:: `use_count() == r.use_count()`. ``` weak_ptr(weak_ptr && r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs a `weak_ptr` that has the value `r` held. Postconditions:: `r` is empty. @@ -155,7 +161,9 @@ Postconditions:: `r` is empty. ``` ~weak_ptr() noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Destroys this `weak_ptr` but has no effect on the object its stored pointer points to. ### assignment @@ -171,7 +179,9 @@ template weak_ptr & operator=(weak_ptr const & r) noexcept; ``` template weak_ptr & operator=(shared_ptr const & r) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `weak_ptr(r).swap(*this)`. NOTE: The implementation is free to meet the effects (and the implied guarantees) via different means, without creating a temporary. @@ -180,35 +190,45 @@ NOTE: The implementation is free to meet the effects (and the implied guarantees ``` long use_count() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: 0 if `*this` is empty; otherwise, the number of `shared_ptr` objects that share ownership with `*this`. ### expired ``` bool expired() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `use_count() == 0`. ### lock ``` shared_ptr lock() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `expired()? shared_ptr(): shared_ptr(*this)`. ### reset ``` void reset() noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `weak_ptr().swap(*this)`. ### swap ``` void swap(weak_ptr & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Exchanges the contents of the two smart pointers. ``` @@ -217,7 +237,9 @@ template bool owner_before( weak_ptr const & r ) const noexcept; ``` template bool owner_before( shared_ptr const & r ) const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: See the description of `operator<`. ## Free Functions @@ -227,7 +249,9 @@ Returns:: See the description of `operator<`. template bool operator<(weak_ptr const & a, weak_ptr const & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: An unspecified value such that - `operator<` is a strict weak ordering as described in section [lib.alg.sorting] of the {cpp} standard; - under the equivalence relation defined by `operator<`, `!(a < b) && !(b < a)`, two `weak_ptr` instances @@ -239,7 +263,9 @@ NOTE: Allows `weak_ptr` objects to be used as keys in associative containers. ``` template void swap(weak_ptr & a, weak_ptr & b) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Equivalent to `a.swap(b)`. ## Frequently Asked Questions