Use boost::addressof and update docs

To make it clear:
       Base* base = new Base();

       static_cast<Derived*>(base)                 ===> OK
       static_cast<Derived&>(*base)                ===> OK

       boost::polymorphic_downcast<Derived*>(base)  ===> OK
       boost::polymorphic_downcast<Derived&>(*base) ===> IMPOSSIBLE

    boost::polymorphic_downcast being a kind of "debug-safe version" of
    static_cast, it should provide the same capabilities.

    This patch extend boost::polymorphic_downcast to support references just
    like static_cast does.
    This is achieved by introducing a partial specialization for references.
    Unit tests have been updated accordingly.

doc/conversion.qbk

@@ -1,5 +1,7 @@
 [/
     Copyright 2016 Mikhail Maximov.
+    Copyright 2020 Antony Polukhin.
+
     Distributed under the Boost Software License, Version 1.0. (See accompanying
     file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)
 ]
@@ -8,15 +10,15 @@
     [quickbook 1.6]
     [compatibility-mode 1.5]
     [id conversion]
-    [version 1.6]
+    [version 1.7]
     [authors [Stroustrup, Bjarne], [Abrahams, Dave], [Rasin, Boris], [Polukhin, Antony]]
-    [copyright 2001 Beman Dawes, 2014-2019 Antony Polukhin]
+    [copyright 2001 Beman Dawes, 2014-2020 Antony Polukhin]
     [license
         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])
     ]
-    [source-mode teletype]
+    [source-mode c++]
 ]
 
 [/ QuickBook Document version 1.5 ]
@@ -44,7 +46,7 @@ the Boost Conversion Library is supplied by several headers:
   provides [@boost:libs/lexical_cast/doc/html/index.html `lexical_cast<>`] general literal text conversions, such as an `int` represented as a `string`, or vice-versa. 
 
 [endsect]
-  
+
 [section Polymorphic casts]
 Pointers to polymorphic objects (objects of classes which define at
 least one virtual function) are sometimes downcast or crosscast.
@@ -58,6 +60,7 @@ safety, suffer poor readability, and are difficult to locate with search
 tools.
 
 [#polymorphic_downcast]
+[section polymorphic_downcast]
 
 The C++ built-in `static_cast` can be used for efficiently
 downcasting pointers to polymorphic objects, but provides no error
@@ -68,11 +71,11 @@ debug compilations adds safety via an `assert()` that a `dynamic_cast`
 succeeds.
 
 A `polymorphic_downcast` should be used for
-downcasts that you are certain should succeed.  Error checking is
+downcasts that you are certain should succeed. Error checking is
 only performed in translation units where `NDEBUG` is
 not defined, via
 ```
-	assert( dynamic_cast<Derived>(x) == x )
+    assert( dynamic_cast<Derived>(x) == x )
 ```
 where `x` is the source pointer.  This approach
 ensures that not only is a non-zero pointer returned, but also
@@ -81,10 +84,26 @@ Attempts to crosscast using `polymorphic_downcast` will
 fail to compile.
 
 [warning Because `polymorphic_downcast` uses `assert()`, it
-violates the One Definition Rule (ODR) if NDEBUG is inconsistently
+violates the One Definition Rule (ODR) if `NDEBUG` is inconsistently
 defined across translation units. See ISO Std 3.2]
 
+[h4 Example:]
+```
+    #include <boost/polymorphic_cast.hpp>
+    ...
+    class Fruit { public: virtual ~Fruit(){}; ... };
+    class Banana : public Fruit { ... };
+    ...
+    void f( Fruit * fruit ) {
+      // ... logic which leads us to believe it is a Banana
+      Banana * banana = boost::polymorphic_downcast<Banana*>(fruit);
+      ...
+    }
+```
+[endsect]
+
 [#polymorphic_cast]
+[section polymorphic_cast]
 
 The C++ built-in `dynamic_cast` can be used for downcasts and
 crosscasts of pointers to polymorphic objects, but error notification in
@@ -102,88 +121,88 @@ or when efficiency is not important, `polymorphic_cast` is preferred.
 The C++ built-in `dynamic_cast` must be used to cast references rather than pointers.
 It is also the only cast that can be used to check whether a given interface is supported; in that case a return of 0 isn't an error condition.
 
+[endsect]
+
+
 [#polymorphic_pointer_cast]
+[section polymorphic_pointer_cast]
 While `polymorphic_downcast` and `polymorphic_cast` work with built-in pointer types only,
 `polymorphic_pointer_downcast` and `polymorphic_pointer_cast` are more generic versions
 with support for any pointer type for which the following expressions would be valid:
 
 For `polymorphic_pointer_downcast`:
 ```
-	static_pointer_cast<Derived>(p);
-	dynamic_pointer_cast<Derived>(p);
+    static_pointer_cast<Derived>(p);
+    dynamic_pointer_cast<Derived>(p);
 ```
 For `polymorphic_pointer_cast`:
 ```
-	dynamic_pointer_cast<Derived>(p);
-	!p; // conversion to bool with negation
+    dynamic_pointer_cast<Derived>(p);
+    !p; // conversion to bool with negation
 ```
 
 This includes C++ built-in pointers, `std::shared_ptr`,
 `boost::shared_ptr`, `boost::intrusive_ptr`, etc.
 
-[endsect]
-[section `polymorphic_cast`, `polymorphic_downcast`, `polymorphic_pointer_cast` and `polymorphic_pointer_downcast` synopsis]
+
+[h4 Example:]
 ```
-	namespace boost {
+    #include <boost/polymorphic_pointer_cast.hpp>
 
-	template <class Derived, class Base>
-	inline Derived polymorphic_cast(Base* x);
-	// Throws: std::bad_cast if ( dynamic_cast<Derived>(x) == 0 )
-	// Returns: dynamic_cast<Derived>(x)
+    class Fruit { public: virtual ~Fruit(){} };
+    class Banana : public Fruit {};
 
-	template <class Derived, class Base>
-	inline Derived polymorphic_downcast(Base* x);
-	// Effects: assert( dynamic_cast<Derived>(x) == x );
-	// Returns: static_cast<Derived>(x)
+    // Use one of these:
+    typedef Fruit* FruitPtr;
+    typedef std::shared_ptr<Fruit> FruitPtr;
+    typedef boost::shared_ptr<Fruit> FruitPtr;
+    typedef boost::intrusive_ptr<Fruit> FruitPtr;
 
-	template <class Derived, class Base>
-	inline auto polymorphic_pointer_cast(Base x);
-	// Throws: std::bad_cast if ( dynamic_pointer_cast<Derived>(x) == 0 )
-	// Returns: dynamic_pointer_cast<Derived>(x)
+    void f(FruitPtr fruit) {
+      // ... logic which leads us to believe it is a banana
+      auto banana = boost::polymorphic_pointer_downcast<Banana>(fruit);
+      ...
+    }
+```
 
-	template <class Derived, class Base>
-	inline auto polymorphic_pointer_downcast(Base x);
-	// Effects: assert( dynamic_pointer_cast<Derived>(x) == x );
-	// Returns: static_pointer_cast<Derived>(x)
+[endsect]
 
-	}
+[endsect]
+
+[section Synopsis]
+```
+    namespace boost {
+
+    // Throws: std::bad_cast if ( dynamic_cast<Derived>(x) == 0 )
+    // Returns: dynamic_cast<Derived>(x)
+    template <class Derived, class Base>
+    inline Derived polymorphic_cast(Base* x);
+
+    // Effects: assert( dynamic_cast<Derived>(x) == x );
+    // Returns: static_cast<Derived>(x)
+    template <class Derived, class Base>
+    inline Derived polymorphic_downcast(Base* x);
+
+    // Effects: assert( dynamic_cast<Derived>(&x) == &x );
+    // Returns: static_cast<Derived>(x)
+    template <class Derived, class Base>
+    inline Derived polymorphic_downcast(Base& x);
+
+    // Throws: std::bad_cast if ( dynamic_pointer_cast<Derived>(x) == 0 )
+    // Returns: dynamic_pointer_cast<Derived>(x)
+    template <class Derived, class Base>
+    inline auto polymorphic_pointer_cast(Base x);
+
+    // Effects: assert( dynamic_pointer_cast<Derived>(x) == x );
+    // Returns: static_pointer_cast<Derived>(x)
+    template <class Derived, class Base>
+    inline auto polymorphic_pointer_downcast(Base x);
+
+    }
 ```
 [endsect]
-[section `polymorphic_downcast` example]
-```
-	#include <boost/polymorphic_cast.hpp>
-	...
-	class Fruit { public: virtual ~Fruit(){}; ... };
-	class Banana : public Fruit { ... };
-	...
-	void f( Fruit * fruit ) {
-	  // ... logic which leads us to believe it is a Banana
-	  Banana * banana = boost::polymorphic_downcast<Banana*>(fruit);
-	  ...
-	}
-```
-[endsect]
-[section `polymorphic_pointer_downcast` example]
-```
-	#include <boost/polymorphic_pointer_cast.hpp>
 
-	class Fruit { public: virtual ~Fruit(){} };
-	class Banana : public Fruit {};
 
-	// use one of these:
-
-	typedef Fruit* FruitPtr;
-	typedef std::shared_ptr<Fruit> FruitPtr;
-	typedef boost::shared_ptr<Fruit> FruitPtr;
-	typedef boost::intrusive_ptr<Fruit> FruitPtr;
-
-	void f(FruitPtr fruit) {
-	  // ... logic which leads us to believe it is a banana
-	  auto banana = boost::polymorphic_pointer_downcast<Banana>(fruit);
-	  ...
-	}
-```
-[endsect]
 [section History]
 `polymorphic_cast` was suggested by Bjarne Stroustrup in "The C++ Programming Language".
 
@@ -192,6 +211,8 @@ This includes C++ built-in pointers, `std::shared_ptr`,
 `polymorphic_pointer_downcast` was contributed by [@http://www.boost.org/people/boris_rasin.htm Boris Rasin]
 and `polymorphic_pointer_cast` by Antony Polukhin.
 
+`polymorphic_downcast` overload for references was contributed by Julien Delacroix.
+
 An old `numeric_cast` that was contributed by [@http://www.boost.org/people/kevlin_henney.htm Kevlin Henney]
-is now superseeded by the [@boost:numeric_conversion/doc/html/html/boost_numericconversion/improved_numeric_cast__.html Boost Numeric Conversion Library]
+is now superseded by the [@boost:numeric_conversion/doc/html/html/boost_numericconversion/improved_numeric_cast__.html Boost Numeric Conversion Library]
 [endsect]

include/boost/implicit_cast.hpp

@@ -2,8 +2,9 @@
 // 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)
-#ifndef IMPLICIT_CAST_DWA200356_HPP
-# define IMPLICIT_CAST_DWA200356_HPP
+
+#ifndef BOOST_IMPLICIT_CAST_DWA200356_HPP
+#define BOOST_IMPLICIT_CAST_DWA200356_HPP
 
 namespace boost {
 
@@ -26,11 +27,7 @@ inline T implicit_cast (typename boost::detail::icast_identity<T>::type x) {
     return x;
 }
 
-// incomplete return type now is here
-//template <typename T>
-//void implicit_cast (...);
-
 } // namespace boost
 
 
-#endif // IMPLICIT_CAST_DWA200356_HPP
+#endif // BOOST_IMPLICIT_CAST_DWA200356_HPP

include/boost/polymorphic_cast.hpp

@@ -50,14 +50,20 @@
 #define BOOST_POLYMORPHIC_CAST_HPP
 
 # include <boost/config.hpp>
-# include <boost/assert.hpp>
-# include <boost/throw_exception.hpp>
-# include <typeinfo>
 
 #ifdef BOOST_HAS_PRAGMA_ONCE
 #   pragma once
 #endif
 
+# include <boost/assert.hpp>
+# include <boost/core/addressof.hpp>
+# include <boost/core/enable_if.hpp>
+# include <boost/throw_exception.hpp>
+# include <boost/type_traits/is_reference.hpp> 
+# include <boost/type_traits/remove_reference.hpp>
+
+# include <typeinfo>
+
 namespace boost
 {
 //  See the documentation for descriptions of how to choose between
@@ -79,7 +85,7 @@ namespace boost
 
 //  polymorphic_downcast  ----------------------------------------------------//
 
-    //  BOOST_ASSERT() checked polymorphic downcast.  Crosscasts prohibited.
+    //  BOOST_ASSERT() checked raw pointer polymorphic downcast.  Crosscasts prohibited.
 
     //  WARNING: Because this cast uses BOOST_ASSERT(), it violates
     //  the One Definition Rule if used in multiple translation units
@@ -95,6 +101,26 @@ namespace boost
         return static_cast<Target>(x);
     }
 
+    //  BOOST_ASSERT() checked reference polymorphic downcast.  Crosscasts prohibited.
+
+    //  WARNING: Because this cast uses BOOST_ASSERT(), it violates
+    //  the One Definition Rule if used in multiple translation units
+    //  where BOOST_DISABLE_ASSERTS, BOOST_ENABLE_ASSERT_HANDLER
+    //  NDEBUG are defined inconsistently.
+
+    //  Contributed by Julien Delacroix
+
+    template <class Target, class Source>
+    inline typename boost::enable_if_c<
+        boost::is_reference<Target>::value, Target
+    >::type polymorphic_downcast(Source& x)
+    {
+        typedef typename boost::remove_reference<Target>::type* target_pointer_type;
+        return *boost::polymorphic_downcast<target_pointer_type>(
+            boost::addressof(x)
+        );
+    }
+
 } // namespace boost
 
 #endif  // BOOST_POLYMORPHIC_CAST_HPP

test/polymorphic_cast_test.cpp

@@ -172,20 +172,23 @@ static void test_polymorphic_pointer_cast()
 
 static void test_polymorphic_downcast()
 {
-    Base * base = new Derived;
+    Base *base_pointer = new Derived;
 
-    Derived * derived = boost::polymorphic_downcast<Derived*>( base );
+    // test raw pointer cast
+    Derived *derived_pointer = boost::polymorphic_downcast<Derived *>(base_pointer);
 
-    BOOST_TEST( derived != 0 );
+    BOOST_TEST(derived_pointer != 0);
 
-    if( derived != 0 )
+    if (derived_pointer != 0)
     {
-        BOOST_TEST_EQ( derived->kind(), "Derived" );
+        BOOST_TEST_EQ(derived_pointer->kind(), "Derived");
     }
 
-    // polymorphic_downcast can't do crosscasts
+    // test reference cast
+    Derived& derived_ref = boost::polymorphic_downcast<Derived&>(*base_pointer);
+    BOOST_TEST_EQ(derived_ref.kind(), "Derived");
 
-    delete base;
+    delete base_pointer;
 }
 
 static void test_polymorphic_pointer_downcast_builtin()
@@ -278,17 +281,32 @@ static void test_polymorphic_pointer_cast_fail()
 
 static void test_polymorphic_downcast_fail()
 {
-    Base * base = new Base;
+    Base * base_pointer = new Base;
 
-    int old_count = assertion_failed_count;
-    expect_assertion = true;
+    {
+        // test raw pointer cast
 
-    BOOST_TEST_THROWS( boost::polymorphic_downcast<Derived*>( base ), expected_assertion ); // should assert
+        int old_count = assertion_failed_count;
+        expect_assertion = true;
 
-    BOOST_TEST_EQ( assertion_failed_count, old_count + 1 );
-    expect_assertion = false;
+        BOOST_TEST_THROWS(boost::polymorphic_downcast<Derived *>(base_pointer), expected_assertion); // should assert
 
-    delete base;
+        BOOST_TEST_EQ(assertion_failed_count, old_count + 1);
+        expect_assertion = false;
+    }
+    {
+        // test reference cast
+
+        int old_count = assertion_failed_count;
+        expect_assertion = true;
+
+        BOOST_TEST_THROWS(boost::polymorphic_downcast<Derived &>(*base_pointer), expected_assertion); // should assert
+
+        BOOST_TEST_EQ(assertion_failed_count, old_count + 1);
+        expect_assertion = false;
+    }
+
+    delete base_pointer;
 }
 
 static void test_polymorphic_pointer_downcast_builtin_fail()