1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
[/
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, alloc_destroy]
[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(p, 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 Args>
void alloc_construct(A& a, T* p, Args&&... args);
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);
template<class A, class T, class I>
void alloc_construct_n(A& a, T* p, std::size_t n, I begin);
} /* 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 Args> void alloc_construct(A& a, T* p,
Args&&... args);`]
[[variablelist
[[Requires][`A` is an /Allocator/]]
[[Effects]
[`std::allocator_traits<A>::construct(a, p, std::forward<Args>(args)...)`.]]]]]
[[`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])`.]]]]]
[[`template<class A, class T, class I> void alloc_construct_n(A& a, T* p,
std::size_t n, I begin);`]
[[variablelist
[[Requires]
[[itemized_list
[`A` is an /Allocator/][`I` is an /InputIterator/]]]]
[[Effects]
[Constructs each `i`-th element in order by calling
`std::allocator_traits<A>::construct(a, &p[i], *begin++])`.]]
[[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 Compatibility]
When `BOOST_NO_CXX11_ALLOCATOR` is defined, and the C++11 allocator model is
not supported, these functions invoke constructors and destructors directly
without going through the supplied allocator.
[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 and Boost.Histogram.
[endsect]
[endsect]
|
