Skip to content

Commit

Permalink
attempt to move pointer to common ancestor
Browse files Browse the repository at this point in the history
  • Loading branch information
@robertramey
robertramey committed Jul 4, 2015
2 parents bb96ebf + e7ab1a0 commit 78111d1
Show file tree
Hide file tree
Showing 19 changed files with 406 additions and 66 deletions.
68 changes: 44 additions & 24 deletions doc/boostbook/db2html.xsl
View file
Original file line number Diff line number Diff line change
@@ -1,35 +1,46 @@
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

<!-- ************** HTML ************** -->
<xsl:import href="http://www.boost.org/tools/boostbook/xsl/html.xsl"/>

<!-- The root of the Boost directory - not used here! -->
<!-- <xsl:param name="boost.root" select="'file:///c:/BoostRelease/'"/> -->
<!-- use boost directorys for css stylesheets and images, etc - again not used here -->
<!-- <xsl:param name="boost.defaults" select="'Boost'"/> -->

<!-- use stylesheet inside of the html directory -->
<xsl:param name="html.stylesheet" select="'boostbook.css'" />
<!-- use the images inside of the html directory -->
<xsl:param name="boost.graphics.root" select="'images/'" />
<!-- enable spirit type nav bar which is the current boost design -->
<xsl:param name="nav.layout">horizontal</xsl:param>
<!-- directory "libraries" to boost page -->
<xsl:param name="boost.libraries">http://www.boost.org/doc/libs</xsl:param>
<xsl:param name="boost.home_link">file:///index.html</xsl:param>

<xsl:param name="chunk.section.depth" select="2"/>
<!--
Make library documentation header using some elements from boostbook stylesheets.
Override boost book implemenation of header.navigation with our own
-->
<xsl:template name = "header.navigation">
<xsl:param name = "prev" select = "/foo"/>
<xsl:param name = "next" select = "/foo"/>
<xsl:param name = "nav.context"/>
<table cellpadding = "2" width = "100%"><tr>
<td valign = "top">
<img href="index.html" height="164px" src="pre-boost.jpg" alt="Library Documentation Index" />
</td>
<td><h2>Safe Numerics</h2></td>
</tr></table>
<xsl:call-template name = "navbar.spirit">
<xsl:with-param name = "prev" select = "$prev"/>
<xsl:with-param name = "next" select = "$next"/>
<xsl:with-param name = "nav.context" select = "$nav.context"/>
</xsl:call-template>
</xsl:template>

<!-- remove "Chapter 1" from first page -->
<xsl:param name="chapter.autolabel" select="0"/>
<!-- don't make first sections special - leave TOC in different file -->
<xsl:param name="chunk.first.sections" select="1"></xsl:param>
<!-- leave the html files in the directory ../html -->
<xsl:param name="base.dir" select="'../html/'"/>
<!-- substitute the pre-boost logo for the boost one -->
<xsl:param name = "boost.image.src">pre-boost.jpg</xsl:param>
<xsl:param name = "boost.image.alt">pre-boost</xsl:param>
<xsl:param name = "boost.image.w">30%</xsl:param>
<xsl:param name = "boost.image.h">30%</xsl:param>

<!-- ******* Table of Contents ******** -->
<!-- How far down sections get TOC's -->
<xsl:param name = "toc.section.depth" select="2" />

<!-- Max depth in each TOC: -->
<xsl:param name = "toc.max.depth" select="2" />

<!-- How far down we go with TOC's -->
<xsl:param name="generate.section.toc.level" select="1" />

<!-- ************ Chunking ************ -->

<!--
BoostBook takes a section node id like safe_numeric.safe_cast
Expand All @@ -55,6 +66,15 @@ the "safe_numeric/" from the above example.
</xsl:choose>
</xsl:template>

</xsl:stylesheet>
<!-- don't make first sections special - leave TOC in different file -->
<xsl:param name="chunk.first.sections" select="3" />

<!-- How far down we chunk nested sections -->
<!--
Note: each chunk have to start with a section with an id
Otherwise the chunk (i.e. file) will be lost. There is no
checking of this
-->
<xsl:param name="chunk.section.depth" select="1" />

</xsl:stylesheet>
58 changes: 58 additions & 0 deletions doc/boostbook/overflow.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.1//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<section id="safe_numerics.rationale.overflow">
<title id="safe_numerics.functions.overflow">overflow</title>

<section>
<title>Synopsis</title>

<para>This function is invoked by the library whenever it is not possible
to produce a result for an arithmetic operation.</para>

<para><programlisting>void overflow(char const * const msg);</programlisting></para>
</section>

<section>
<title>Description</title>

<para>If environment supports C++ exceptions, this function throws the
exception .</para>

<para>If the environment does not support C++ exceptions, the user should
implement this function and expect it to be called when
appropriate.</para>

<para><filename>boost/config.hpp </filename>defines BOOST_NO_EXCEPTIONS
when the environment doesn't support exceptions. It is by checking for the
definition of this macro that the system determines whether or not
exceptions are supported.</para>
</section>

<section>
<title>Header</title>

<para><ulink url="../include/safe_numerics/overflow"><code>#include
&lt;boost/safe_numerics/overflow.hpp&gt; </code></ulink></para>
</section>

<section>
<title>Example of use</title>

<programlisting>#include &lt;cstdio&gt;

void overflow(char const * const msg){
std::fputs("safe_numerics overflow error:, std::stderr);
std::fputs(msg, std::stderr);
std::fputc('\n', std::stderr);
}</programlisting>
</section>

<section>
<title>See Also</title>

<para>See <link
linkend="safe_numerics.rationale.overflow">rationale</link> for more
information on this function</para>
</section>
</section>
92 changes: 92 additions & 0 deletions doc/boostbook/safe_cast.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.1//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<section id="safe_numerics.safe_cast">
<title>safe_cast&lt;T, U&gt;</title>

<section>
<title>Synopsis</title>

<programlisting>template&lt;class T, class U&gt;
T safe_cast(const U &amp; u);</programlisting>
</section>

<section>
<title>Description</title>

<para>Converts one <link linkend="safe_numerics.numeric">Numeric</link>
type to another. Throws an <code>std::out_of_range</code> exception if
such a conversion is not possible without changing the value. This
function is part of the implementation of the safe numerics library. It's
been made publicly because it might be useful in related contexts.</para>
</section>

<section>
<title>Type requirements</title>

<informaltable>
<tgroup cols="2">
<colspec align="left"/>

<colspec align="left" colwidth="3*"/>

<thead>
<row>
<entry align="left">Type</entry>

<entry align="left">Requirements</entry>
</row>
</thead>

<tbody>
<row>
<entry><code>T</code></entry>

<entry><link
linkend="safe_numerics.numeric">Numeric</link></entry>
</row>

<row>
<entry><code>U </code></entry>

<entry><link
linkend="safe_numerics.numeric">Numeric</link></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>

<section>
<title>Preconditions</title>

<para>The value of u must be representable by the type <code>T</code>. If
this is not true, an <code>std::out_of_range</code> exception will be
thrown.</para>
</section>

<section>
<title>Header</title>

<para><filename><ulink url="../../include/safe_cast.hpp">#include
&lt;boost/numeric/safe_cast.hpp&gt; </ulink></filename></para>
</section>

<section>
<title>Example of use</title>

<programlisting>#include &lt;boost/numeric/safe_cast.hpp&gt;
#include &lt;boost/numeric/safe_integer.hpp&gt;

void f(){
safe_integer&lt;char&gt; i;
unsigned char j;
i = 1;
j = safe_cast&lt;unsigned char&gt;(i); // ok
i = -1;
j = safe_cast&lt;unsigned char&gt;(i); // throws std::out_of_range exception
i = 1024;
j = safe_cast&lt;unsigned char&gt;(i); // throws std::out_of_range exception
}</programlisting>
</section>
</section>
106 changes: 106 additions & 0 deletions doc/boostbook/safe_compare.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.1//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<section id="safe_numerics.safe_compare">
<title>safe_compare&lt;T, U&gt;</title>

<section>
<title>Synopsis</title>

<para>safe_compare is several functions:.</para>

<programlisting>template&lt;class T, class U&gt;
bool safe_compare::less_than(const T &amp; lhs, const U &amp; rhs);

template&lt;class T, class U&gt;
bool safe_compare::less_than_equal(const T &amp; lhs, const U &amp; rhs);

template&lt;class T, class U&gt;
bool safe_compare::greater_than(const T &amp; lhs, const U &amp; rhs);

template&lt;class T, class U&gt;
bool safe_compare::greater_than_equal(const T &amp; lhs, const U &amp; rhs);

template&lt;class T, class U&gt;
bool safe_compare::equal(const T &amp; lhs, const U &amp; rhs);

template&lt;class T, class U&gt;
bool safe_compare::not_equal(const T &amp; lhs, const U &amp; rhs);</programlisting>
</section>

<section>
<title>Description</title>

<para>With normal comparison operators, comparison of unsigned types to
signed types will be done by converting the unsigned type to a signed type
before comparing. Unfortunately this is not always possible. Most C++
compilers will emit an warning message when this is possible but won't
check that an error is made in the conversion. This function guarantees a
correct result regardless of the types of the arguments. It's used in the
implementation of the safe numerics library. It has been made publicly
accessible in because it might be useful in other contexts.</para>
</section>

<section>
<title>Type requirements</title>

<informaltable>
<tgroup cols="2">
<colspec align="left"/>

<colspec align="left" colwidth="3*"/>

<thead>
<row>
<entry align="left">Type</entry>

<entry align="left">Requirements</entry>
</row>
</thead>

<tbody>
<row>
<entry><code>T</code></entry>

<entry><link
linkend="safe_numerics.numeric">Numeric</link></entry>
</row>

<row>
<entry><code>U </code></entry>

<entry><link
linkend="safe_numerics.numeric">Numeric</link></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>

<section>
<title>Header</title>

<para><ulink url="../../include/safe_compare.hpp"><filename>#include
&lt;boost/numeric/safe_compare.hpp&gt; </filename></ulink></para>
</section>

<section>
<title>Example of use</title>

<programlisting>#include &lt;boost/numeric/safe_compare.hpp&gt;

void f(){
unsigned char i = 129;
unsigned int j = 1;
assert(j &lt; i); // program traps because expression is false. But this is a surprise because 1 &lt; 129
assert( safe_compare::less_than(j,i)); // expression is true as we would expect
}

// safe_compare is used to implement comparison operators for safe types. So we can do this:
void g(){
safe&lt;unsigned char&gt; int i = 0x129;
safe&lt;int&gt; j = 1;
assert(j &lt; i); // program works as expected
}</programlisting>
</section>
</section>
24 changes: 10 additions & 14 deletions doc/html/acknowledgements.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,36 +7,32 @@
<link rel="home" href="index.html" title="Safe Numerics">
<link rel="up" href="index.html" title="Safe Numerics">
<link rel="prev" href="change_log.html" title="Change Log">
<link rel="next" href="references.html" title="References">
<link rel="next" href="bibliography.html" title="Bibliography">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="pre-boost" width="30%" height="30%" src="pre-boost.jpg"></td>
<td align="center"><a href="../../index.html">Home</a></td>
<td align="center"><a href="http://www.boost.org/doc/libs">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../more/index.htm">More</a></td>
<td valign="top"><img href="index.html" height="164px" src="pre-boost.jpg" alt="Library Documentation Index"></td>
<td><h2>Safe Numerics</h2></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="change_log.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="references.html"><img src="images/next.png" alt="Next"></a>
<a accesskey="p" href="change_log.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="bibliography.html"><img src="images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="safe_numerics.acknowledgements"></a>Acknowledgements</h2></div></div></div>
<p><a href="http://safeint.codeplex.com/releases/view/73792" target="_top">David
LeBlanc's</a> is the author of <a href="http://safeint.codeplex.com/releases/view/73792" target="_top">SafeInt3</a>
library which motivated this work</p>
<p><a href="http://channel9.msdn.com/Shows/Going+Deep/David-LeBlanc-Inside-SafeInt" target="_top">David
LeBlanc</a> is the author of <a href="https://safeint.codeplex.com" target="_top">SafeInt3</a> library which
motivated this work</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2012 Robert Ramey<p><a href="???" target="_top">Subject to Boost Software License</a></p>
<td align="right"><div class="copyright-footer">Copyright &#169; 2012 Robert Ramey<p><a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt"&gt;Subject
to Boost Software License</a></p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="change_log.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="references.html"><img src="images/next.png" alt="Next"></a>
<a accesskey="p" href="change_log.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="bibliography.html"><img src="images/next.png" alt="Next"></a>
</div>
</body>
</html>
Loading

0 comments on commit 78111d1

Please sign in to comment.