Implement pointer_in_range

doc/pointer_in_range.qbk

@@ -0,0 +1,80 @@
+[/
+Copyright 2024 Glen Joseph Fernandes
+(glenjofe@gmail.com)
+
+Distributed under the Boost Software License, Version 1.0.
+(http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[section:pointer_in_range pointer_in_range]
+
+[simplesect Authors]
+
+* Glen Fernandes
+
+[endsimplesect]
+
+[section Overview]
+
+The header <boost/core/pointer_in_range.hpp> provides the function template
+`boost::pointer_in_range` to check if a pointer is in a given range. This
+can be used in constant expressions in C++14 or higher when the compiler has a
+builtin to support `std::is_constant_evaluated`.
+
+[endsect]
+
+[section Examples]
+
+The following is an example of an allocator's deallocation function that does
+nothing if the pointer falls within a small automatically allocated buffer.
+
+```
+template<class T, class N>
+void
+Allocator<T, N>::deallocate(pointer ptr, size_type)
+{
+    if (!boost::pointer_in_range(ptr, &buffer_[0], &buffer_[N])) {
+        ::operator delete(ptr);
+    }
+}
+```
+
+[endsect]
+
+[section Reference]
+
+```
+namespace boost {
+
+template<class T>
+constexpr bool pointer_in_range(const T* ptr, const T* begin, const T* end);
+
+} /* boost */
+```
+
+[section Functions]
+
+[variablelist
+[[`template<class T> constexpr bool pointer_in_range(const T* ptr,
+const T* begin, T* end);`]
+[[variablelist
+[[Returns][`true` if `ptr` is in range `[begin,end)`, otherwise `false`.]]]]]]
+
+[endsect]
+
+[endsect]
+
+[section Notes]
+
+If `boost::pointer_in_range` is not usable in constant expressions the macro
+`BOOST_CORE_NO_CONSTEXPR_POINTER_IN_RANGE` is defined.
+
+[endsect]
+
+[section History]
+
+Glen Fernandes implemented `pointer_in_range`.
+
+[endsect]
+
+[endsect]