boostorg/conversion
1
0
Fork 1
mirror of https://github.com/boostorg/conversion.git synced 2025-07-30 04:27:24 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #10 from very-cool-name/quickbook_doc

Browse Source 
Moved documentation from html to Boost Quickbook.
This commit is contained in:
Antony Polukhin
2016-12-26 23:30:40 +04:00
committed by GitHub
parent cbe18465d7 eafe2d352e
commit 993685b7d0
4 changed files with 268 additions and 243 deletions
Download Patch File Download Diff File Expand all files Collapse all files

196
cast.htm
View File

@ -1,196 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta name="generator" content=
"Microsoft FrontPage 5.0">
<meta http-equiv="Content-Type" content=
"text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Header boost/polymorphic_cast.hpp Documentation</title>
<style>
.copyright
{
color: #666666;
font-size: small;
}
</style>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<h1><img src="../../boost.png" alt="boost.png (6897 bytes)" align=
"middle" width="277" height="86">Header <a href=
"../../boost/polymorphic_cast.hpp">boost/polymorphic_cast.hpp</a></h1>
<h2><a name="Cast Functions">Cast Functions</a></h2>
<p>The header <a href="../../boost/polymorphic_cast.hpp">boost/polymorphic_cast.hpp</a> provides
<code><a href="#Polymorphic_cast">polymorphic_cast</a></code> and
<code><a href="#Polymorphic_cast">polymorphic_downcast</a></code>
function templates designed to complement the C++ built-in casts.</p> <p>The header <a href="../../boost/polymorphic_pointer_cast.hpp">boost/polymorphic_pointer_cast.hpp</a> provides
<code><a href="#Polymorphic_cast">polymorphic_pointer_cast</a></code> and
<code><a href="#Polymorphic_cast">polymorphic_pointer_downcast</a></code> function templates.
<p>The program <a href="test/cast_test.cpp">cast_test.cpp</a> can be used to
verify these function templates work as expected.</p>
<h3><a name="Polymorphic_cast">Polymorphic casts</a></h3>
<p>Pointers to polymorphic objects (objects of classes which define at
least one virtual function) are sometimes downcast or crosscast.
Downcasting means casting from a base class to a derived class.
Crosscasting means casting across an inheritance hierarchy diagram, such
as from one base to the other in a <code>Y</code> diagram hierarchy.</p>
<p>Such casts can be done with old-style casts, but this approach is
never to be recommended. Old-style casts are sorely lacking in type
safety, suffer poor readability, and are difficult to locate with search
tools.</p>
<p>The C++ built-in <code>static_cast</code> can be used for efficiently
downcasting pointers to polymorphic objects, but provides no error
detection for the case where the pointer being cast actually points to
the wrong derived class. The <code>polymorphic_downcast</code> template retains
the efficiency of <code>static_cast</code> for non-debug compilations, but for
debug compilations adds safety via an assert() that a <code>dynamic_cast</code>
succeeds.</p>
<p>The C++ built-in <code>dynamic_cast</code> can be used for downcasts and
crosscasts of pointers to polymorphic objects, but error notification in
the form of a returned value of 0 is inconvenient to test, or worse yet,
easy to forget to test. The throwing form of <code>dynamic_cast</code>, which
works on references, can be used on pointers through the ugly expression
&amp;<code>dynamic_cast&lt;T&amp;&gt;(*p)</code>, which causes undefined
behavior if <code>p</code> is <code>0</code>. The <code>polymorphic_cast</code>
template performs a <code>dynamic_cast</code> on a pointer, and throws an
exception if the <code>dynamic_cast</code> returns 0.</p>
<p>A <code>polymorphic_downcast</code> should be used for
downcasts that you are certain should succeed. Error checking is
only performed in translation units where <code>NDEBUG</code> is
not defined, via
<pre> assert( dynamic_cast&lt;Derived&gt;(x) == x )
</pre> where <code>x</code> is the source pointer. This approach
ensures that not only is a non-zero pointer returned, but also
that it is correct in the presence of multiple inheritance.
Attempts to crosscast using <code>polymorphic_downcast</code> will
fail to compile.
<b>Warning:</b> Because <code>polymorphic_downcast</code> uses assert(), it
violates the One Definition Rule (ODR) if NDEBUG is inconsistently
defined across translation units. [See ISO Std 3.2]
<p>
For crosscasts, or when the success of a cast can only be known at
runtime, or when efficiency is not important,
<code>polymorphic_cast</code> is preferred. </p>
<p>The C++ built-in <code>dynamic_cast</code> 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.</p>
<p>While <code>polymorphic_downcast</code> and <code>polymorphic_cast</code> work with built-in pointer types only,
<code>polymorphic_pointer_downcast</code> and <code>polymorphic_pointer_cast</code> are more generic versions
with support for any pointer type for which the following expressions would be valid:<br><br>
<p> For <code>polymorphic_pointer_downcast</code>:</p>
<code>&nbsp;&nbsp;static_pointer_cast&lt;Derived&gt;(p);<br>&nbsp;&nbsp;dynamic_pointer_cast&lt;Derived&gt;(p);</code><br><br>
<p> For <code>polymorphic_pointer_cast</code>:</p>
<code>&nbsp;&nbsp;dynamic_pointer_cast&lt;Derived&gt;(p);<br>&nbsp;&nbsp;!p; // conversion to bool with negation</code><br><br>
<p>This includes C++ built-in pointers, <code>std::shared_ptr, boost::shared_ptr, boost::intrusive_ptr</code>, etc.</p>
<h3>polymorphic_cast, polymorphic_downcast, polymorphic_pointer_cast and polymorphic_pointer_downcast synopsis</h3>
<blockquote>
<pre>namespace boost {
template &lt;class Derived, class Base&gt;
inline Derived polymorphic_cast(Base* x);
// Throws: std::bad_cast if ( dynamic_cast&lt;Derived&gt;(x) == 0 )
// Returns: dynamic_cast&lt;Derived&gt;(x)
template &lt;class Derived, class Base&gt;
inline Derived polymorphic_downcast(Base* x);
// Effects: assert( dynamic_cast&lt;Derived&gt;(x) == x );
// Returns: static_cast&lt;Derived&gt;(x)
template &lt;class Derived, class Base&gt;
inline auto polymorphic_pointer_cast(Base x);
// Throws: std::bad_cast if ( dynamic_pointer_cast&lt;Derived&gt;(x) == 0 )
// Returns: dynamic_pointer_cast&lt;Derived&gt;(x)
template &lt;class Derived, class Base&gt;
inline auto polymorphic_pointer_downcast(Base x);
// Effects: assert( dynamic_pointer_cast&lt;Derived&gt;(x) == x );
// Returns: static_pointer_cast&lt;Derived&gt;(x)
}
</pre>
</blockquote>
<h3>polymorphic_downcast example</h3>
<blockquote>
<pre>#include &lt;boost/polymorphic_cast.hpp&gt;
...
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&lt;Banana*&gt;(fruit);
...
</pre>
</blockquote>
<h3>polymorphic_pointer_downcast example</h3>
<blockquote>
<pre>#include &lt;boost/polymorphic_pointer_cast.hpp&gt;
class Fruit { public: virtual ~Fruit(){} };
class Banana : public Fruit {};
// use one of these:
typedef Fruit* FruitPtr;
typedef std::shared_ptr&lt;Fruit&gt; FruitPtr;
typedef boost::shared_ptr&lt;Fruit&gt; FruitPtr;
typedef boost::intrusive_ptr&lt;Fruit&gt; FruitPtr;
void f(FruitPtr fruit)
{
// ... logic which leads us to believe it is a banana
auto banana = boost::polymorphic_pointer_downcast&lt;Banana&gt;(fruit);
...
}
</pre>
</blockquote>
<h3>History</h3>
<p><code>polymorphic_cast</code> was suggested by Bjarne Stroustrup in "The C++
Programming Language".<br>
<code>polymorphic_downcast</code> was contributed by <a href=
"http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a>.<br>
<code>polymorphic_pointer_downcast</code> was contributed by <a href=
"http://www.boost.org/people/boris_rasin.htm">Boris Rasin</a> and
<code>polymorphic_pointer_cast</code> by Antony Polukhin.<br>
An old
<code>numeric_cast</code> that was contributed by <a href=
"http://www.boost.org/people/kevlin_henney.htm">Kevlin Henney</a> is now superseeded by the <a href="../numeric/conversion/doc/html/index.html">Boost Numeric Conversion Library</a></p>
<hr>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan
-->June 23, 2005<!--webbot bot="Timestamp" endspan i-checksum="30348"
--></p>
<p class="copyright">&copy; Copyright boost.org 1999.
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>)
</p>
</body>
</html>

42
doc/Jamfile.v2 Normal file
View File

@ -0,0 +1,42 @@
# Copyright (c) 2016 Mikhail Maximov <vigorous.activity -at- gmail.com>
# 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)
project doc/conversion ;
using quickbook ;
import boostbook ;
xml conversion_lib : conversion.qbk ;
boostbook standalone
:
conversion_lib
:
<xsl:param>boost.root=../../../..
# File name of HTML output:
<xsl:param>root.filename=conversion
# How far down we chunk nested sections, basically all of them:
<xsl:param>chunk.section.depth=0
# Don't put the first section on the same page as the TOC:
<xsl:param>chunk.first.sections=0
# How far down sections get TOC's
<xsl:param>toc.section.depth=2
# Max depth in each TOC:
<xsl:param>toc.max.depth=2
# How far down we go with TOC's
<xsl:param>generate.section.toc.level=0
<xsl:param>generate.manifest=0
;
###############################################################################
alias boostdoc
: conversion
:
:
: ;
explicit boostdoc ;
alias boostrelease ;
explicit boostrelease ;

197
doc/conversion.qbk Normal file
View File

@ -0,0 +1,197 @@
[/
Copyright 2016 Mikhail Maximov.
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>)
]
[article The Conversion Library
[quickbook 1.6]
[compatibility-mode 1.5]
[id conversion_lib]
[version 1.6]
[authors [Stroustrup, Bjarne], [Abrahams, Dave], [Rasin, Boris], [Polukhin, Antony]]
[copyright 2001 Beman Dawes]
[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]
]
[/ QuickBook Document version 1.5 ]
[/ Dec, 2016 ]
[section Description]
The Conversion Library improves program safety and clarity by performing
otherwise messy conversions. It includes cast-style function templates designed
to complement the C++ Standard's built-in casts.
To reduce coupling, particularly to standard library IOStreams,
the Boost Conversion Library is supplied by several headers:
# The [@boost:boost/polymorphic_cast.hpp boost/polymorphic_cast.hpp] header
provides [link polymorphic_cast `polymorphic_cast<>`] and
[link polymorphic_downcast `polymorphic_downcast<>`]
to perform safe casting between polymorphic types.
# The [@boost:boost/polymorphic_pointer_cast.hpp boost/polymorphic_pointer_cast.hpp] header
provides [link polymorphic_pointer_cast `polymorphic_pointer_cast<>`] and
[link polymorphic_pointer_cast `polymorphic_pointer_downcast<>`]
# The [@boost:boost/implicit_cast.hpp boost/implicit_cast.hpp] header provides `implicit_cast<>`
to perform implicit casts only (no down-cast, no void*->T*, no U->T if T has only explicit constructors for U).
# The [@boost:boost/lexical_cast.hpp boost/lexical_cast.hpp] header
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.
Downcasting means casting from a base class to a derived class.
Crosscasting means casting across an inheritance hierarchy diagram, such
as from one base to the other in a [^Y] diagram hierarchy.
Such casts can be done with old-style casts, but this approach is
never to be recommended. Old-style casts are sorely lacking in type
safety, suffer poor readability, and are difficult to locate with search
tools.
[#polymorphic_downcast]
The C++ built-in `static_cast` can be used for efficiently
downcasting pointers to polymorphic objects, but provides no error
detection for the case where the pointer being cast actually points to
the wrong derived class. The `polymorphic_downcast` template retains
the efficiency of `static_cast` for non-debug compilations, but for
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
only performed in translation units where `NDEBUG` is
not defined, via
```
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
that it is correct in the presence of multiple inheritance.
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
defined across translation units. See ISO Std 3.2]
[#polymorphic_cast]
The C++ built-in `dynamic_cast` can be used for downcasts and
crosscasts of pointers to polymorphic objects, but error notification in
the form of a returned value of 0 is inconvenient to test, or worse yet,
easy to forget to test. The throwing form of `dynamic_cast`, which
works on references, can be used on pointers through the ugly expression
`&dynamic_cast<T&>(*p), which causes undefined
behavior if `p` is `0`. The `polymorphic_cast`
template performs a `dynamic_cast` on a pointer, and throws an
exception if the `dynamic_cast` returns 0.
For crosscasts, or when the success of a cast can only be known at runtime,
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.
[#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);
```
For `polymorphic_pointer_cast`:
```
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]
```
namespace boost {
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)
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 auto polymorphic_pointer_cast(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_downcast(Base x);
// Effects: assert( dynamic_pointer_cast<Derived>(x) == x );
// Returns: static_pointer_cast<Derived>(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".
`polymorphic_downcast` was contributed by [@http://www.boost.org/people/dave_abrahams.htm Dave Abrahams].
`polymorphic_pointer_downcast` was contributed by [@http://www.boost.org/people/boris_rasin.htm Boris Rasin]
and `polymorphic_pointer_cast` by Antony Polukhin.
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]
[endsect]

76
index.html
View File

@ -1,53 +1,35 @@
<!DOCTYPE html>
<!--
Copyright (c) 2016 Mikhail Maximov
vigorous.activity at gmail dot com
Distributed under the Boost Software License,
Version 1.0. (See accompanying file LICENSE_1_0.txt
or copy at http://boost.org/LICENSE_1_0.txt)
-->
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Boost Conversion Library</title>
<meta charset="utf-8">
<meta http-equiv="refresh" content="0; url=../../doc/html/conversion.html">
<title>Boost.Conversion</title>
<style>
.copyright
{
color: #666666;
font-size: small;
}
body {
background: #fff;
color: #000;
}
a {
color: #00f;
text-decoration: none;
}
</style>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<h1><img border="0" src="../../boost.png" align="center" width="277" height="86">Boost
Conversion Library</h1>
<p>The Conversion Library improves program safety and clarity by performing
otherwise messy conversions.&nbsp; It includes cast-style function templates designed to complement the C++
Standard's built-in casts.</p>
<p>To reduce coupling, particularly to standard library IOStreams, the Boost
Conversion Library is
supplied by several headers:</p>
<ul>
<li>The <a href="cast.htm">boost/polymorphic_cast.hpp and boost/polymorphic_pointer_cast.hpp</a>
headers provide <b>polymorphic_cast&lt;&gt;</b>,
<b>polymorphic_downcast&lt;&gt;</b> and <b>polymorphic_pointer_downcast&lt;&gt;</b> to perform safe casting between
polymorphic types.<br>
</li>
<li>The boost/implicit_cast.hpp header provides <b>implicit_cast&lt;&gt;</b>
to perform implicit casts only (no down-cast, no void*->T*, no U->T if T has only explicit constructors for U).<br>
</li>
<li>The <a href="../../doc/html/boost_lexical_cast.html">boost/lexical_cast</a> header provides <b>lexical_cast&lt;&gt;</b>
general literal text conversions, such as an <code>int</code> represented as
a <code>string</code>, or vice-versa.</li>
</ul>
<hr>
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED"
S-Format="%d %B, %Y" startspan -->June 23, 2005<!--webbot bot="Timestamp" endspan i-checksum="30348" -->
</p>
<p class="copyright">
Copyright 2001 Beman Dawes.
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>)
</p>
<body>
<p>
Automatic redirection failed, please go to
<a href="../../doc/html/conversion.html">../../doc/html/conversion.html</a>
</p>
<p>
&copy; 2014 Antony Polukhin
</p>
</body>
</html>
</html>