diff --git a/doc/smart_ptr/make_shared.adoc b/doc/smart_ptr/make_shared.adoc index 662a05c..dc2d688 100644 --- a/doc/smart_ptr/make_shared.adoc +++ b/doc/smart_ptr/make_shared.adoc @@ -55,36 +55,43 @@ types. [subs=+quotes] ``` namespace boost { + // only if T is not an array type template shared_ptr make_shared(Args&&... args); template shared_ptr allocate_shared(const A& a, Args&&... args); + // only if T is an array type of the form U[] template shared_ptr make_shared(std::size_t n); template shared_ptr allocate_shared(const A& a, std::size_t n); + // only if T is an array type of the form U[N] template shared_ptr make_shared(); template shared_ptr allocate_shared(const A& a); + // only if T is an array type of the form U[] template shared_ptr make_shared(std::size_t n, _see below_ v); template shared_ptr allocate_shared(const A& a, std::size_t n, _see below_ v); + // only if T is an array type of the form U[N] template shared_ptr make_shared(_see below_ v); template shared_ptr allocate_shared(const A& a, _see below_ v); + // only if T is not an array type of the form U[] template shared_ptr make_shared_noinit(); template shared_ptr allocate_shared_noinit(const A& a); + // only if T is an array type of the form U[N] template shared_ptr make_shared_noinit(std::size_t n); template @@ -92,7 +99,7 @@ namespace boost { } ``` -## Free Functions +## Common Requirements The common requirements that apply to all `make_shared` and `allocate_shared` overloads, unless specified otherwise, are described below. @@ -100,8 +107,8 @@ overloads, unless specified otherwise, are described below. Requires:: `A` shall be an _allocator_. The copy constructor and destructor of `A` shall not throw exceptions. -Effects:: Allocates memory for an object of type `T` or `n` objects of `_U_` -(if `T` is an array type of the form `__U__[]` and `n` is determined by +Effects:: Allocates memory for an object of type `T` or `n` objects of `U` +(if `T` is an array type of the form `U[]` and `n` is determined by arguments, as specified by the concrete overload). The object is initialized from arguments as specified by the concrete overload. Uses a rebound copy of `a` (for an unspecified `value_type`) to allocate memory. If an exception is @@ -110,48 +117,49 @@ thrown, the functions have no effect. Returns:: A `shared_ptr` instance that stores and owns the address of the newly constructed object. -Postconditions:: `__r__.get() != 0` and `__r__.use_count() == 1`, where `_r_` +Postconditions:: `r.get() != 0` and `r.use_count() == 1`, where `r` is the return value. -Throws:: An exception thrown from `A::allocate`, or from the initialization -of the object. +Throws:: `std::bad_alloc`, an exception thrown from `A::allocate`, or from the +initialization of the object. Remarks:: * Performs no more than one memory allocation. This provides efficiency equivalent to an intrusive smart pointer. +* The type of `v` is equivalent to `const std::remove_extent_t&`. * When an object of an array type is specified to be initialized to a value of the same type `v`, this shall be interpreted to mean that each array element of the object is initialized to the corresponding element from `v`. * When an object of an array type is specified to be value-initialized, this shall be interpreted to mean that each array element of the object is value-initialized. -* When a (sub)object of non-array type `_U_` is specified to be initialized to +* When a (sub)object of non-array type `U` is specified to be initialized to a value `v`, or constructed from `args$$...$$`, `make_shared` shall perform -this initialization via the expression `::new(__p__) __U__(__expr__)` (where -`_expr_` is `v` or `std::forward(args)$$...$$)` respectively) and `_p_` +this initialization via the expression `::new(p) U(expr)` (where +`_expr_` is `v` or `std::forward(args)$$...$$)` respectively) and `p` has type `void*` and points to storage suitable to hold an object of type -`_U_`. -* When a (sub)object of non-array type `_U_` is specified to be initialized to +`U`. +* When a (sub)object of non-array type `U` is specified to be initialized to a value `v`, or constructed from `args$$...$$`, `allocate_shared` shall perform this initialization via the expression -`std::allocator_traits<__A2__>::construct(__a2__, __p__, __expr__)` (where -`_expr_` is `v` or `std::forward(args)$$...$$)` respectively), `_p_` -points to storage suitable to hold an object of type `_U_`, and `_a2_` of -type `_A2_` is a rebound copy `a` such that its `value_type` is `_U_`. -* When a (sub)object of non-array type `_U_` is specified to be +`std::allocator_traits::construct(a2, p, expr)` (where +`_expr_` is `v` or `std::forward(args)$$...$$)` respectively), `p` +points to storage suitable to hold an object of type `U`, and `a2` of +type `A2` is a rebound copy `a` such that its `value_type` is `U`. +* When a (sub)object of non-array type `U` is specified to be default-initialized, `make_shared_noinit` and `allocate_shared_noinit` shall -perform this initialization via the expression `::new(__p__) __U__`, where -`_p_` has type `void*` and points to storage suitable to hold an object of -type `_U_`. -* When a (sub)object of non-array type `_U_` is specified to be +perform this initialization via the expression `::new(p) U`, where +`p` has type `void*` and points to storage suitable to hold an object of +type `U`. +* When a (sub)object of non-array type `U` is specified to be value-initialized, `make_shared` shall perform this initialization via the -expression `::new(__p__) __U__()`, where `_p_` has type `void*` and points to -storage suitable to hold an object of type `_U_`. -* When a (sub)object of non-array type `_U_` is specified to be +expression `::new(p) U()`, where `p` has type `void*` and points to +storage suitable to hold an object of type `U`. +* When a (sub)object of non-array type `U` is specified to be value-initialized, `allocate_shared` shall perform this initialization via the -expression `std::allocator_traits<__A2__>::construct(__a2__, __p__)`, where -`p` points to storage suitable to hold an object of type `_U_` and `_a2_` of -type `_A2_` is a rebound copy of `a` such that its value_type is `_U_`. +expression `std::allocator_traits::construct(a2, p)`, where +`p` points to storage suitable to hold an object of type `U` and `a2` of +type `A2` is a rebound copy of `a` such that its value_type is `U`. * Array elements are initialized in ascending order of their addresses. * When the lifetime of the object managed by the return value ends, or when the initialization of an array element throws an exception, the initialized @@ -161,6 +169,8 @@ NOTE: These functions will typically allocate more memory than the total size of the element objects to allow for internal bookkeeping structures such as the reference counts. +## Free Functions + ``` template shared_ptr make_shared(Args&&... args); @@ -190,9 +200,9 @@ template ``` :: Remarks::: These overloads shall only participate in overload resolution when -`T` is an array type of the form `__U__[]`. +`T` is an array type of the form `U[]`. Returns::: A `shared_ptr` to a sequence of `n` value-initialized objects of -type `_U_`. +type `U`. Examples::: * `auto p = make_shared(1024);` * `auto p = make_shared(6);` @@ -208,9 +218,9 @@ template ``` :: 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 -type `_U_`. +`T` is an array type of the form `U[N]`. +Returns::: A `shared_ptr` to a sequence of `N` value-initialized objects of +type `U`. Examples::: * `auto p = make_shared();` * `auto p = make_shared();` @@ -218,18 +228,18 @@ Examples::: [subs=+quotes] ``` template - shared_ptr make_shared(std::size_t n, _see below_ v); + shared_ptr make_shared(std::size_t n, _see above_ v); ``` :: [subs=+quotes] ``` template - shared_ptr allocate_shared(const A& a, std::size_t n, _see below_ v); + shared_ptr allocate_shared(const A& a, std::size_t n, _see above_ v); ``` :: 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 +`T` is an array type of the form `U[]`. +Returns::: A `shared_ptr` to a sequence of `n` objects of type `U`, each initialized to `v`. Examples::: * `auto p = make_shared(1024, 1.0);` @@ -239,18 +249,18 @@ Examples::: [subs=+quotes] ``` template - shared_ptr make_shared(_see below_ v); + shared_ptr make_shared(_see above_ v); ``` :: [subs=+quotes] ``` template - shared_ptr allocate_shared(const A& a, _see below_ v); + shared_ptr allocate_shared(const A& a, _see above_ v); ``` :: 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 +`T` is an array type of the form `U[N]`. +Returns::: A `shared_ptr` to a sequence of `N` objects of type `U`, each initialized to `v`. Examples::: * `auto p = make_shared(1.0);` @@ -268,9 +278,9 @@ template ``` :: Remarks::: These overloads shall only participate in overload resolution when -`T` is not an array type, or an array type of the `__U__[__N__]`. +`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 -sequence of `_N_` default-initialized objects of type `_U_`, respectively. +sequence of `N` default-initialized objects of type `U`, respectively. Example::: `auto p = make_shared_noinit();` ``` @@ -284,7 +294,7 @@ template ``` :: Remarks::: These overloads shall only participate in overload resolution when -`T` is an array type of the form `__U__[]`. +`T` is an array type of the form `U[]`. Returns::: A `shared_ptr` to a sequence of `_n_` default-initialized objects -of type `_U_`. -Example::: `auto p = make_shared_noinit(1024);` \ No newline at end of file +of type `U`. +Example::: `auto p = make_shared_noinit(1024);` diff --git a/doc/smart_ptr/make_unique.adoc b/doc/smart_ptr/make_unique.adoc index 13d247c..048f9c6 100644 --- a/doc/smart_ptr/make_unique.adoc +++ b/doc/smart_ptr/make_unique.adoc @@ -40,20 +40,25 @@ feature with `std::make_unique`. [subs=+quotes] ``` namespace boost { + // only if T is not an array type template std::unique_ptr make_unique(Args&&... args); + // only if T is not an array type template std::unique_ptr make_unique(_see below_ v); + // only if T is an array type of the form U[] template - std::unique_ptr make_shared(std::size_t n); + std::unique_ptr make_unique(std::size_t n); + // only if T is not an array type template - std::unique_ptr make_shared_noinit(); + std::unique_ptr make_unique_noinit(); + // only if T is an array type of the form U[] template - std::unique_ptr make_shared_noinit(std::size_t n); + std::unique_ptr make_unique_noinit(std::size_t n); } ``` @@ -78,7 +83,7 @@ template Remarks::: * These overloads shall only participate in overload resolution when `T` is not an array type. -* The type of `v` is `std::remove_reference_t&&`. +* The type of `v` is equivalent to `std::remove_reference_t&&`. Returns::: `std::unique_ptr(new T(std::move(v))`. Example::: `auto p = make_unique >({1, 2});` @@ -88,8 +93,8 @@ template ``` :: Remarks::: These overloads shall only participate in overload resolution when -`T` is an array type of the form `__U__[]`. -Returns::: `std::unique_ptr<__U__[]>(new __U__[n]())`. +`T` is an array type of the form `U[]`. +Returns::: `std::unique_ptr(new U[n]())`. Example::: `auto p = make_unique(1024);` ``` @@ -108,6 +113,6 @@ template ``` :: Remarks::: These overloads shall only participate in overload resolution when -`T` is an array type of the form `__U__[]`. -Returns::: `std::unique_ptr<__U__[]>(new __U__[n])`. -Example::: `auto p = make_unique_noinit(1024);` \ No newline at end of file +`T` is an array type of the form `U[]`. +Returns::: `std::unique_ptr(new U[n])`. +Example::: `auto p = make_unique_noinit(1024);`