Move construct and destroy from Smart_Ptr to Core

doc/alloc_construct.qbk

@@ -0,0 +1,125 @@
+[/
+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 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 element in order by calling
+`std::allocator_traits<A>::construct(a, &p[i])`.]]
+[[Remarks]
+[If an exception is thrown, destroys each element in reverse order by
+calling `std::allocator_traits<A>::destroy(a, &p[i])`.]]]]]
+[[`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 element in order by calling
+`std::allocator_traits<A>::construct(a, &p[i], l[i % m])`.]]
+[[Remarks]
+[If an exception is thrown, destroys each element in reverse order by
+calling `std::allocator_traits<A>::destroy(a, &p[i])`.]]]]]]
+
+[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 multiple Boost libraries.
+
+[endsect]
+
+[endsect]