Deprecated boost/iterator.hpp, emit warnings on inclusion.

The header defines boost::iterator template, which is an alias for
std::iterator, which is itself deprecated since C++17.

Updated test to avoid testing the definition in C++17 onwards
to avoid failures due to deprecation warnings from libc++-13.

doc/changes.qbk

@@ -10,6 +10,7 @@
 
 * Added `boost::allocator_traits`, an implementation of `std::allocator_traits`.
 * Made `boost::pointer_traits` SFINAE friendly.
+* `boost/iterator.hpp` is deprecated and will be removed in a future release. The header defines `boost::iterator` template, which is equivalent to `std::iterator` in `<iterator>` header. However, since `std::iterator` is itself deprecated in C++17, users are advised to remove `boost::iterator` or `std::iterator` use from their code.
 
 [endsect]
 

include/boost/iterator.hpp

@@ -5,7 +5,9 @@
 #ifndef BOOST_ITERATOR_HPP
 #define BOOST_ITERATOR_HPP
 
-// This header is obsolete and will be deprecated.
+#include <boost/config/header_deprecated.hpp>
+
+BOOST_HEADER_DEPRECATED("<iterator>")
 
 #include <iterator>
 #include <cstddef>           // std::ptrdiff_t

test/iterator_test.cpp

@@ -8,8 +8,15 @@
 // http://www.boost.org/LICENSE_1_0.txt
 //
 
+#define BOOST_ALLOW_DEPRECATED_HEADERS
 #define _SILENCE_CXX17_ITERATOR_BASE_CLASS_DEPRECATION_WARNING
 
+#include <boost/config.hpp>
+
+// std::iterator template is deprecated in C++17. Some standard libraries emit warnings
+// that cannot be easily suppressed, so disable the tests in C++17 onwards.
+#if BOOST_CXX_VERSION < 201703
+
 #include <boost/iterator.hpp>
 #include <boost/core/is_same.hpp>
 #include <boost/core/lightweight_test_trait.hpp>
@@ -69,3 +76,11 @@ int main()
 
     return boost::report_errors();
 }
+
+#else // BOOST_CXX_VERSION < 201703
+
+int main()
+{
+}
+
+#endif // BOOST_CXX_VERSION < 201703