diff --git a/doc/smart_ptr/intrusive_ref_counter.adoc b/doc/smart_ptr/intrusive_ref_counter.adoc index 32a28a6..ef65902 100644 --- a/doc/smart_ptr/intrusive_ref_counter.adoc +++ b/doc/smart_ptr/intrusive_ref_counter.adoc @@ -78,12 +78,13 @@ namespace boost { ``` intrusive_ref_counter() noexcept; ``` -:: ``` intrusive_ref_counter(const intrusive_ref_counter&) noexcept; ``` -:: -Postconditions::: `use_count() == 0`. +[none] +* {blank} ++ +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 +95,10 @@ would increment the reference counter. ``` ~intrusive_ref_counter(); ``` -:: -Effects::: Destroys the counter object. +[none] +* {blank} ++ +Effects:: Destroys the counter object. NOTE: The destructor is protected so that the object can only be destroyed through the `Derived` class. @@ -105,16 +108,20 @@ through the `Derived` class. ``` intrusive_ref_counter& operator=(const intrusive_ref_counter& v) noexcept; ``` -:: -Effects::: Does nothing, reference counter is not modified. +[none] +* {blank} ++ +Effects:: Does nothing, reference counter is not modified. ### use_count ``` unsigned int use_count() const noexcept; ``` -:: -Returns::: The current value of the reference counter. +[none] +* {blank} ++ +Returns:: The current value of the reference counter. NOTE: The returned value may not be actual in multi-threaded applications. @@ -127,8 +134,10 @@ template void intrusive_ptr_add_ref( const intrusive_ref_counter* p) noexcept; ``` -:: -Effects::: Increments the reference counter. +[none] +* {blank} ++ +Effects:: Increments the reference counter. ### intrusive_ptr_release @@ -137,6 +146,8 @@ template void intrusive_ptr_release( const intrusive_ref_counter* p) noexcept; ``` -:: -Effects::: Decrements the reference counter. If the reference counter reaches +[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 d7d34dd..158179b 100644 --- a/doc/smart_ptr/local_shared_ptr.adoc +++ b/doc/smart_ptr/local_shared_ptr.adoc @@ -716,4 +716,3 @@ template * {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 5b4366c..375a91e 100644 --- a/doc/smart_ptr/make_shared.adoc +++ b/doc/smart_ptr/make_shared.adoc @@ -174,17 +174,18 @@ 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 +[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 +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 +193,18 @@ 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 +[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 +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 +212,18 @@ Examples::: template shared_ptr make_shared(); ``` -:: ``` template shared_ptr allocate_shared(const A& a); ``` -:: -Remarks::: These overloads shall only participate in overload resolution when +[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 +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 +231,18 @@ 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 +[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 +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 +251,18 @@ 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 +[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 +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 +271,32 @@ 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 +[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 +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 +[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 +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..feb569c 100644 --- a/doc/smart_ptr/make_unique.adoc +++ b/doc/smart_ptr/make_unique.adoc @@ -68,48 +68,58 @@ namespace boost { template std::unique_ptr make_unique(Args&&... args); ``` -:: -Remarks::: These overloads shall only participate in overload resolution when +[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)\...)`. -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 +[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))`. -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 +[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]())`. -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 +[none] +* {blank} ++ +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 +[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])`. -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..5c2ef54 100644 --- a/doc/smart_ptr/pointer_cast.adoc +++ b/doc/smart_ptr/pointer_cast.adoc @@ -78,23 +78,29 @@ namespace boost { ``` template T* static_pointer_cast(U* p) noexcept; ``` -:: -Returns::: `static_cast(p)` +[none] +* {blank} ++ +Returns:: `static_cast(p)` ``` template std::shared_ptr static_pointer_cast(const std::shared_ptr& p) noexcept; ``` -:: -Returns::: `std::static_pointer_cast(p)` +[none] +* {blank} ++ +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 +112,31 @@ undefined behavior, attempting to delete the same object twice. ``` template T* dynamic_pointer_cast(U* p) noexcept; ``` -:: -Returns::: `dynamic_cast(p)` +[none] +* {blank} ++ +Returns:: `dynamic_cast(p)` ``` template std::shared_ptr dynamic_pointer_cast(const std::shared_ptr& p) noexcept; ``` -:: -Returns::: `std::dynamic_pointer_cast(p)` +[none] +* {blank} ++ +Returns:: `std::dynamic_pointer_cast(p)` ``` template std::unique_ptr dynamic_pointer_cast(std::unique_ptr&& p) noexcept; ``` -:: -Requires::: +[none] +* {blank} ++ +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 +147,29 @@ std::unique_ptr::element_type*>(p.release()));`. ``` template T* const_pointer_cast(U* p) noexcept; ``` -:: -Returns::: `const_cast(p)` +[none] +* {blank} ++ +Returns:: `const_cast(p)` ``` template std::shared_ptr const_pointer_cast(const std::shared_ptr& p) noexcept; ``` -:: -Returns::: `std::const_pointer_cast(p)` +[none] +* {blank} ++ +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 +177,29 @@ std::unique_ptr::element_type*>(p.release()))`. ``` template T* reinterpret_pointer_cast(U* p) noexcept; ``` -:: -Returns::: `reinterpret_cast(p)` +[none] +* {blank} ++ +Returns:: `reinterpret_cast(p)` ``` template std::shared_ptr reinterpret_pointer_cast(const std::shared_ptr& p) noexcept; ``` -:: -Returns::: `std::reinterpret_pointer_cast(p)` +[none] +* {blank} ++ +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 @@ -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 5be074c..18bd669 100644 --- a/doc/smart_ptr/shared_array.adoc +++ b/doc/smart_ptr/shared_array.adoc @@ -105,42 +105,50 @@ 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 +[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`). -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`. +[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::: +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. -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 +[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. -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 +[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,60 +157,70 @@ 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 +[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. -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 +[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. -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 +[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::: +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. +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. +[none] +* {blank} ++ +Returns:: The stored pointer. ### unique ``` bool unique() const noexcept; ``` -:: -Returns::: `true` if no other `shared_array` is sharing ownership of the +[none] +* {blank} ++ +Returns:: `true` if no other `shared_array` is sharing ownership of the stored pointer, `false` otherwise. ### use_count @@ -210,8 +228,10 @@ stored pointer, `false` otherwise. ``` long use_count() const noexcept; ``` -:: -Returns::: The number of `shared_array` objects sharing ownership of the +[none] +* {blank} ++ +Returns:: The number of `shared_array` objects sharing ownership of the stored pointer. ### Conversions @@ -219,17 +239,21 @@ stored pointer. ``` explicit operator bool() const noexcept; ``` -:: -Returns::: `get() != 0`. -Requires::: `T` is a complete type. +[none] +* {blank} ++ +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. +[none] +* {blank} ++ +Effects:: Exchanges the contents of the two smart pointers. ## Free Functions @@ -247,8 +271,10 @@ 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 +[none] +* {blank} ++ +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 +291,8 @@ 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. +[none] +* {blank} ++ +Returns:: `a.swap(b)`. +Requires:: `T` is a complete type.