feedc0de/boost_conversion
1
0
Fork 0
forked from boostorg/conversion
Code Pull Requests Activity

Use boost::addressof and update docs

Browse Source
This commit is contained in:
Antony Polukhin
2020-01-25 10:59:32 +03:00
parent e130cd860c
commit 58c33270a2
3 changed files with 106 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

151
doc/conversion.qbk
View File

@ -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]

11
include/boost/implicit_cast.hpp
View File

@ -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

25
include/boost/polymorphic_cast.hpp
View File

@ -50,17 +50,20 @@
#define BOOST_POLYMORPHIC_CAST_HPP
# include <boost/config.hpp>
# include <boost/assert.hpp>
# include <boost/throw_exception.hpp>
# include <boost/type_traits/is_reference.hpp>
# include <boost/type_traits/remove_reference.hpp>
# include <boost/utility/enable_if.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
@ -108,10 +111,14 @@ namespace boost
// 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)
inline typename boost::enable_if_c<
boost::is_reference<Target>::value, Target
>::type polymorphic_downcast(Source& x)
{
BOOST_ASSERT(dynamic_cast<typename boost::remove_reference<Target>::type *>(&x) == &x);
return static_cast<Target>(x);
typedef typename boost::remove_reference<Target>::type* target_pointer_type;
return *boost::polymorphic_downcast<target_pointer_type>(
boost::addressof(x)
);
}
} // namespace boost