mirror of
https://github.com/boostorg/core.git
synced 2025-05-10 07:13:54 +00:00
127 lines
3.3 KiB
Plaintext
127 lines
3.3 KiB
Plaintext
[/
|
|
Copyright 2019 Glen Joseph Fernandes
|
|
(glenjofe@gmail.com)
|
|
|
|
Distributed under the Boost Software License, Version 1.0.
|
|
(http://www.boost.org/LICENSE_1_0.txt)
|
|
]
|
|
|
|
[section:alloc_construct alloc_construct]
|
|
|
|
[simplesect Authors]
|
|
|
|
* Glen Fernandes
|
|
|
|
[endsimplesect]
|
|
|
|
[section Overview]
|
|
|
|
The header <boost/core/alloc_construct.hpp> provides function templates
|
|
`alloc_construct`, `alloc_construct_n`, `alloc_destroy`, and `alloc_destroy_n`
|
|
for allocator aware and exception safe construction and destruction of objects
|
|
and arrays.
|
|
|
|
[endsect]
|
|
|
|
[section Example]
|
|
|
|
The following example allocates storage for an array of `n` elements of `T`
|
|
using an allocator `a` and constructs `T` elements in that storage. If any
|
|
exception was thrown during construction of an element, the constructed
|
|
elements are destroyed in reverse order.
|
|
|
|
```
|
|
template<class A>
|
|
auto create(A& a, std::size_t n)
|
|
{
|
|
auto p = a.allocate(n);
|
|
try {
|
|
boost::alloc_construct_n(a, boost::to_address(p), n);
|
|
} catch (...) {
|
|
a.deallocate(n);
|
|
throw;
|
|
}
|
|
return p;
|
|
}
|
|
```
|
|
|
|
[endsect]
|
|
|
|
[section Reference]
|
|
|
|
```
|
|
namespace boost {
|
|
|
|
template<class A, class T>
|
|
void alloc_destroy(A& a, T* p);
|
|
|
|
template<class A, class T>
|
|
void alloc_destroy_n(A& a, T* p, std::size_t n);
|
|
|
|
template<class A, class T, class U>
|
|
void alloc_construct(A& a, T* p, U&&... u);
|
|
|
|
template<class A, class T>
|
|
void alloc_construct_n(A& a, T* p, std::size_t n);
|
|
|
|
template<class A, class T>
|
|
void alloc_construct_n(A& a, T* p, std::size_t n, const T* l, std::size_t m);
|
|
|
|
} /* boost */
|
|
```
|
|
|
|
[section Functions]
|
|
|
|
[variablelist
|
|
[[`template<class A, class T> void alloc_destroy(A& a, T* p);`]
|
|
[[variablelist
|
|
[[Requires][`A` is an /Allocator/]]
|
|
[[Effects][`std::allocator_traits<A>::destroy(a, p)`.]]]]]
|
|
[[`template<class A, class T> void alloc_destroy_n(A& a, T* p,
|
|
std::size_t n);`]
|
|
[[variablelist
|
|
[[Requires][`A` is an /Allocator/]]
|
|
[[Effects]
|
|
[Destroys each ['i]th element in reverse order by calling
|
|
`std::allocator_traits<A>::destroy(a, &p[i])`.]]]]]
|
|
[[`template<class A, class T, class U> void alloc_construct(A& a, T* p,
|
|
U&&... u);`]
|
|
[[variablelist
|
|
[[Requires][`A` is an /Allocator/]]
|
|
[[Effects]
|
|
[`std::allocator_traits<A>::construct(a, p, std::forward<U>(u)...)`.]]]]]
|
|
[[`template<class A, class T> void alloc_construct_n(A& a, T* p,
|
|
std::size_t n);`]
|
|
[[variablelist
|
|
[[Requires][`A` is an /Allocator/]]
|
|
[[Effects]
|
|
[Constructs each ['i]th element in order by calling
|
|
`std::allocator_traits<A>::construct(a, &p[i])`.]]
|
|
[[Remarks]
|
|
[If an exception is thrown destroys each already constructed ['j]th element in
|
|
reverse order by calling `std::allocator_traits<A>::destroy(a, &p[j])`.]]]]]
|
|
[[`template<class A, class T> void alloc_construct_n(A& a, T* p, std::size_t n,
|
|
const T* l, std::size_t m);`]
|
|
[[variablelist
|
|
[[Requires][`A` is an /Allocator/]]
|
|
[[Effects]
|
|
[Constructs each ['i]th element in order by calling
|
|
`std::allocator_traits<A>::construct(a, &p[i], l[i % m])`.]]
|
|
[[Remarks]
|
|
[If an exception is thrown destroys each already constructed ['j]th element in
|
|
reverse order by calling `std::allocator_traits<A>::destroy(a, &p[j])`.]]]]]]
|
|
|
|
[endsect]
|
|
|
|
[endsect]
|
|
|
|
[section Acknowledgments]
|
|
|
|
Glen Fernandes originally implemented this functionality in Boost.Smart_Ptr and
|
|
later moved these functions to Boost.Core for use in other Boost libraries,
|
|
such as Boost.Multi_Array.
|
|
|
|
[endsect]
|
|
|
|
[endsect]
|