Squashed 'third_party/boostorg/core/' content from commit e128f4e
Change-Id: Ieb2dc8269dd1750337cfc876826ea7af75f12d63
git-subtree-dir: third_party/boostorg/core
git-subtree-split: e128f4e1b8904d47561700892843f07d5d1160db
diff --git a/doc/checked_delete.qbk b/doc/checked_delete.qbk
new file mode 100644
index 0000000..156eb1b
--- /dev/null
+++ b/doc/checked_delete.qbk
@@ -0,0 +1,138 @@
+[/
+ / Copyright (c) 2002, 2003, 2005 Peter Dimov
+ / Copyright (c) 2014 Glen Fernandes
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See
+ / accompanying file LICENSE_1_0.txt or copy at
+ / http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:checked_delete checked_delete]
+
+[simplesect Authors]
+
+* Beman Dawes
+* Dave Abrahams
+* Vladimir Prus
+* Rainer Deyke
+* John Maddock
+
+[endsimplesect]
+
+[section Overview]
+
+The header `<boost/checked_delete.hpp>` defines two function
+templates, `checked_delete` and `checked_array_delete`, and two
+class templates, `checked_deleter` and `checked_array_deleter`.
+
+The C++ Standard allows, in 5.3.5/5, pointers to incomplete
+class types to be deleted with a delete-expression. When the
+class has a non-trivial destructor, or a class-specific
+operator delete, the behavior is undefined. Some compilers
+issue a warning when an incomplete type is deleted, but
+unfortunately, not all do, and programmers sometimes ignore or
+disable warnings.
+
+A particularly troublesome case is when a smart pointer's
+destructor, such as `boost::scoped_ptr<T>::~scoped_ptr`, is
+instantiated with an incomplete type. This can often lead to
+silent, hard to track failures.
+
+The supplied function and class templates can be used to
+prevent these problems, as they require a complete type, and
+cause a compilation error otherwise.
+
+[endsect]
+
+[section Synopsis]
+
+``
+namespace boost
+{
+ template<class T> void checked_delete(T * p);
+ template<class T> void checked_array_delete(T * p);
+ template<class T> struct checked_deleter;
+ template<class T> struct checked_array_deleter;
+}
+``
+
+[endsect]
+
+[section checked_delete]
+
+[section template<class T> void checked_delete(T * p);]
+
+* *Requires:* `T` must be a complete type. The expression
+ `delete p` must be well-formed.
+* *Effects:* `delete p;`
+
+[endsect]
+
+[endsect]
+
+[section checked_array_delete]
+
+[section template<class T> void checked_array_delete(T * p);]
+
+* *Requires:* `T` must be a complete type. The expression
+ `delete [] p` must be well-formed.
+* *Effects:* `delete [] p;`
+
+[endsect]
+
+[endsect]
+
+[section checked_deleter]
+
+``
+template<class T> struct checked_deleter
+{
+ typedef void result_type;
+ typedef T * argument_type;
+ void operator()(T * p) const;
+};
+``
+
+[section void checked_deleter<T>::operator()(T * p) const;]
+
+* *Requires:* `T` must be a complete type. The expression
+ `delete p` must be well-formed.
+* *Effects:* `delete p;`
+
+[endsect]
+
+[endsect]
+
+[section checked_array_deleter]
+
+``
+template<class T> struct checked_array_deleter
+{
+ typedef void result_type;
+ typedef T * argument_type;
+ void operator()(T * p) const;
+};
+``
+
+[section void checked_array_deleter<T>::operator()(T * p) const;]
+
+* *Requires:* `T` must be a complete type. The expression
+ `delete [] p` must be well-formed.
+* *Effects:* `delete [] p;`
+
+[endsect]
+
+[endsect]
+
+[section Acknowledgements]
+
+The function templates `checked_delete` and
+`checked_array_delete` were originally part of
+`<boost/utility.hpp>`, and the documentation
+acknowledged Beman Dawes, Dave Abrahams,
+Vladimir Prus, Rainer Deyke, John Maddock,
+and others as contributors.
+
+[endsect]
+
+[endsect]