mirror of
https://github.com/boostorg/safe_numerics.git
synced 2026-02-23 16:02:13 +00:00
300 lines
14 KiB
HTML
300 lines
14 KiB
HTML
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
|
<title>Functions</title>
|
|
<link rel="stylesheet" href="boostbook.css" type="text/css">
|
|
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
|
|
<link rel="home" href="index.html" title="Safe Numerics">
|
|
<link rel="up" href="index.html" title="Safe Numerics">
|
|
<link rel="prev" href="types.html" title="Types">
|
|
<link rel="next" href="rationale.html" title="Rationale">
|
|
</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="">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>
|
|
</tr></table>
|
|
<hr>
|
|
<div class="spirit-nav">
|
|
<a accesskey="p" href="types.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="rationale.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.functions"></a>Functions</h2></div></div></div>
|
|
<div class="toc"><dl>
|
|
<dt><span class="section"><a href="functions.html#safe_numerics.safe_cast">safe_cast<T, U></a></span></dt>
|
|
<dd><dl>
|
|
<dt><span class="section"><a href="functions.html#idm449651627264">Synopsis</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651625808">Description</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651623360">Type requirements</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651614336">Preconditions</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651611904">Complexity</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651610752">Header</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651608768">Example of use</a></span></dt>
|
|
</dl></dd>
|
|
<dt><span class="section"><a href="functions.html#safe_numerics.safe_compare">safe_compare<T, U></a></span></dt>
|
|
<dd><dl>
|
|
<dt><span class="section"><a href="functions.html#idm449651605616">Synopsis</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651603696">Description</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651601312">Type requirements</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651592544">Header</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651590560">Example of use</a></span></dt>
|
|
</dl></dd>
|
|
<dt><span class="section"><a href="functions.html#safe_numerics.rationale.overflow">overflow</a></span></dt>
|
|
<dd><dl>
|
|
<dt><span class="section"><a href="functions.html#idm449651587936">Synopsis</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651585920">Description</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651582368">Header</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651580384">Example of use</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651578608">See Also</a></span></dt>
|
|
</dl></dd>
|
|
</dl></div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h3 class="title">
|
|
<a name="safe_numerics.safe_cast"></a>safe_cast<T, U></h3></div></div></div>
|
|
<div class="toc"><dl>
|
|
<dt><span class="section"><a href="functions.html#idm449651627264">Synopsis</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651625808">Description</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651623360">Type requirements</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651614336">Preconditions</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651611904">Complexity</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651610752">Header</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651608768">Example of use</a></span></dt>
|
|
</dl></div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651627264"></a>Synopsis</h4></div></div></div>
|
|
<pre class="programlisting">template<class T, class U>
|
|
T safe_cast(const U & u);</pre>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651625808"></a>Description</h4></div></div></div>
|
|
<p>Converts one <a class="link" href="concepts.html#safe_numerics.numeric" title="Numeric<T>">Numeric</a>
|
|
type to another. Throws an <code class="computeroutput">std::out_of_range</code> exception if
|
|
such a conversion is not possible without changing the value.</p>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651623360"></a>Type requirements</h4></div></div></div>
|
|
<div class="informaltable"><table class="table">
|
|
<colgroup>
|
|
<col align="left">
|
|
<col align="left">
|
|
</colgroup>
|
|
<thead><tr>
|
|
<th align="left">Type</th>
|
|
<th align="left">Requirements</th>
|
|
</tr></thead>
|
|
<tbody>
|
|
<tr>
|
|
<td align="left"><code class="computeroutput">T</code></td>
|
|
<td align="left"><a class="link" href="concepts.html#safe_numerics.numeric" title="Numeric<T>">Numeric</a></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left"><code class="computeroutput">U </code></td>
|
|
<td align="left"><a class="link" href="concepts.html#safe_numerics.numeric" title="Numeric<T>">Numeric</a></td>
|
|
</tr>
|
|
</tbody>
|
|
</table></div>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651614336"></a>Preconditions</h4></div></div></div>
|
|
<p>The value of u must be representabl by the type <code class="computeroutput">T</code>. If
|
|
this is not true, an <code class="computeroutput">std::out_of_range</code> exception will be
|
|
thrown.</p>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651611904"></a>Complexity</h4></div></div></div>
|
|
<p>Constant - O(0).</p>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651610752"></a>Header</h4></div></div></div>
|
|
<p><code class="filename"><a href="../../include/safe_cast.hpp" target="_top">#include
|
|
<boost/numeric/safe_cast.hpp> </a></code></p>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651608768"></a>Example of use</h4></div></div></div>
|
|
<pre class="programlisting">#include <boost/numeric/safe_cast.hpp>
|
|
#include <boost/numeric/safe_integer.hpp>
|
|
|
|
void f(){
|
|
safe_integer<char> i;
|
|
unsigned char j;
|
|
i = 1;
|
|
j = safe_cast<unsigned char>(i); // ok
|
|
i = -1;
|
|
j = safe_cast<unsigned char>(i); // throws std::out_of_range exception
|
|
i = 1024;
|
|
j = safe_cast<unsigned char>(i); // throws std::out_of_range exception
|
|
}</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h3 class="title">
|
|
<a name="safe_numerics.safe_compare"></a>safe_compare<T, U></h3></div></div></div>
|
|
<div class="toc"><dl>
|
|
<dt><span class="section"><a href="functions.html#idm449651605616">Synopsis</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651603696">Description</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651601312">Type requirements</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651592544">Header</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651590560">Example of use</a></span></dt>
|
|
</dl></div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651605616"></a>Synopsis</h4></div></div></div>
|
|
<p>safe_compare is several functions:.</p>
|
|
<pre class="programlisting">template<class T, class U>
|
|
bool safe_compare::less_than(const T & lhs, const U & rhs);
|
|
|
|
template<class T, class U>
|
|
bool safe_compare::less_than_equal(const T & lhs, const U & rhs);
|
|
|
|
template<class T, class U>
|
|
bool safe_compare::greater_than(const T & lhs, const U & rhs);
|
|
|
|
template<class T, class U>
|
|
bool safe_compare::greater_than_equal(const T & lhs, const U & rhs);
|
|
|
|
template<class T, class U>
|
|
bool safe_compare::equal(const T & lhs, const U & rhs);
|
|
|
|
template<class T, class U>
|
|
bool safe_compare::not_equal(const T & lhs, const U & rhs);</pre>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651603696"></a>Description</h4></div></div></div>
|
|
<p>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 guarentees a
|
|
correct result regardless of the types of the arguments.</p>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651601312"></a>Type requirements</h4></div></div></div>
|
|
<div class="informaltable"><table class="table">
|
|
<colgroup>
|
|
<col align="left">
|
|
<col align="left">
|
|
</colgroup>
|
|
<thead><tr>
|
|
<th align="left">Type</th>
|
|
<th align="left">Requirements</th>
|
|
</tr></thead>
|
|
<tbody>
|
|
<tr>
|
|
<td align="left"><code class="computeroutput">T</code></td>
|
|
<td align="left"><a class="link" href="concepts.html#safe_numerics.numeric" title="Numeric<T>">Numeric</a></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left"><code class="computeroutput">U </code></td>
|
|
<td align="left"><a class="link" href="concepts.html#safe_numerics.numeric" title="Numeric<T>">Numeric</a></td>
|
|
</tr>
|
|
</tbody>
|
|
</table></div>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651592544"></a>Header</h4></div></div></div>
|
|
<p><a href="../../include/safe_compare.hpp" target="_top"><code class="filename">#include
|
|
<boost/numeric/safe_compare.hpp> </code></a></p>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651590560"></a>Example of use</h4></div></div></div>
|
|
<pre class="programlisting">#include <boost/numeric/safe_compare.hpp>
|
|
|
|
void f(){
|
|
unsigned char i = 129;
|
|
unsigned int j = 1;
|
|
assert(j < i); // program traps because expression is false. But this is a surprise because 1 < 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<unsigned char> int i = 0x129;
|
|
safe<int> j = 1;
|
|
assert(j < i); // program works as expected
|
|
}</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h3 class="title">
|
|
<a name="safe_numerics.rationale.overflow"></a>overflow</h3></div></div></div>
|
|
<div class="toc"><dl>
|
|
<dt><span class="section"><a href="functions.html#idm449651587936">Synopsis</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651585920">Description</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651582368">Header</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651580384">Example of use</a></span></dt>
|
|
<dt><span class="section"><a href="functions.html#idm449651578608">See Also</a></span></dt>
|
|
</dl></div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651587936"></a>Synopsis</h4></div></div></div>
|
|
<p>This function is invoked by the library whenever it is not possible
|
|
to produce a result for an arithmetic operation.</p>
|
|
<pre class="programlisting">void overflow(char const * const msg);</pre>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651585920"></a>Description</h4></div></div></div>
|
|
<p>If evironment supports C++ exceptions, this function throws the
|
|
exception .</p>
|
|
<p>If the environment does not support C++ exceptions, the user should
|
|
implement this function and expect it to be called when appropriate.
|
|
Otherwise, function is implemented by the library so that it throws the
|
|
standard library exception <code class="computeroutput">std::out_of_range(msg)</code>.</p>
|
|
<p><code class="filename">boost/config.hpp </code>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.</p>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651582368"></a>Header</h4></div></div></div>
|
|
<p><a href="../include/safe_numerics/overflow" target="_top"><code class="computeroutput">#include
|
|
<boost/safe_numerics/overflow.hpp> </code></a></p>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651580384"></a>Example of use</h4></div></div></div>
|
|
<pre class="programlisting">#include <cstdio>
|
|
|
|
void overflow(char const * const msg){
|
|
std::fputs("safe_numerics overflow error:, std::stderr);
|
|
std::fputs(msg, std::stderr);
|
|
std::fputc('\n', std::stderr);
|
|
}</pre>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm449651578608"></a>See Also</h4></div></div></div>
|
|
<p>See <a class="link" href="functions.html#safe_numerics.rationale.overflow" title="overflow">rationale</a> for more
|
|
information on this function</p>
|
|
</div>
|
|
</div>
|
|
</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 © 2012 Robert Ramey<p><a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt">Subject to Boost Software License</a></p>
|
|
</div></td>
|
|
</tr></table>
|
|
<hr>
|
|
<div class="spirit-nav">
|
|
<a accesskey="p" href="types.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="rationale.html"><img src="images/next.png" alt="Next"></a>
|
|
</div>
|
|
</body>
|
|
</html>
|