3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>Finding the Next Representable Value in a Specific Direction (nextafter)</title>
5 <link rel="stylesheet" href="../../math.css" type="text/css">
6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
7 <link rel="home" href="../../index.html" title="Math Toolkit 2.11.0">
8 <link rel="up" href="../next_float.html" title="Floating-Point Representation Distance (ULP), and Finding Adjacent Floating-Point Values">
9 <link rel="prev" href="../next_float.html" title="Floating-Point Representation Distance (ULP), and Finding Adjacent Floating-Point Values">
10 <link rel="next" href="float_next.html" title="Finding the Next Greater Representable Value (float_next)">
12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13 <table cellpadding="2" width="100%"><tr>
14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
15 <td align="center"><a href="../../../../../../index.html">Home</a></td>
16 <td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
19 <td align="center"><a href="../../../../../../more/index.htm">More</a></td>
22 <div class="spirit-nav">
23 <a accesskey="p" href="../next_float.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../next_float.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="float_next.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
26 <div class="titlepage"><div><div><h3 class="title">
27 <a name="math_toolkit.next_float.nextafter"></a><a class="link" href="nextafter.html" title="Finding the Next Representable Value in a Specific Direction (nextafter)">Finding the Next Representable
28 Value in a Specific Direction (nextafter)</a>
29 </h3></div></div></div>
31 <a name="math_toolkit.next_float.nextafter.h0"></a>
32 <span class="phrase"><a name="math_toolkit.next_float.nextafter.synopsis"></a></span><a class="link" href="nextafter.html#math_toolkit.next_float.nextafter.synopsis">Synopsis</a>
34 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">next</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
36 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
38 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">FPT</span><span class="special">></span>
39 <span class="identifier">FPT</span> <span class="identifier">nextafter</span><span class="special">(</span><span class="identifier">FPT</span> <span class="identifier">val</span><span class="special">,</span> <span class="identifier">FPT</span> <span class="identifier">direction</span><span class="special">);</span>
41 <span class="special">}}</span> <span class="comment">// namespaces</span>
44 <a name="math_toolkit.next_float.nextafter.h1"></a>
45 <span class="phrase"><a name="math_toolkit.next_float.nextafter.description_nextafter"></a></span><a class="link" href="nextafter.html#math_toolkit.next_float.nextafter.description_nextafter">Description
49 This is an implementation of the <code class="computeroutput"><span class="identifier">nextafter</span></code>
50 function included in the C99 standard. (It is also effectively an implementation
51 of the C99 <code class="computeroutput"><span class="identifier">nexttoward</span></code> legacy
52 function which differs only having a <code class="computeroutput"><span class="keyword">long</span>
53 <span class="keyword">double</span></code> direction, and can generally
54 serve in its place if required).
56 <div class="note"><table border="0" summary="Note">
58 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
59 <th align="left">Note</th>
61 <tr><td align="left" valign="top"><p>
62 The C99 functions must use suffixes f and l to distinguish <code class="computeroutput"><span class="keyword">float</span></code> and <code class="computeroutput"><span class="keyword">long</span>
63 <span class="keyword">double</span></code> versions. C++ uses the template
68 Returns the next representable value after <span class="emphasis"><em>x</em></span> in the
69 direction of <span class="emphasis"><em>y</em></span>. If <code class="computeroutput"><span class="identifier">x</span>
70 <span class="special">==</span> <span class="identifier">y</span></code>
71 then returns <span class="emphasis"><em>x</em></span>. If <span class="emphasis"><em>x</em></span> is non-finite
72 then returns the result of a <a class="link" href="../error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>.
73 If there is no such value in the direction of <span class="emphasis"><em>y</em></span> then
74 returns an <a class="link" href="../error_handling.html#math_toolkit.error_handling.overflow_error">overflow_error</a>.
76 <div class="warning"><table border="0" summary="Warning">
78 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../doc/src/images/warning.png"></td>
79 <th align="left">Warning</th>
81 <tr><td align="left" valign="top"><p>
82 The template parameter FTP must be a floating-point type. An integer type,
83 for example, will produce an unhelpful error message.
86 <div class="tip"><table border="0" summary="Tip">
88 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
89 <th align="left">Tip</th>
91 <tr><td align="left" valign="top"><p>
92 Nearly always, you just want the next or prior representable value, so
93 instead use <code class="computeroutput"><span class="identifier">float_next</span></code>
94 or <code class="computeroutput"><span class="identifier">float_prior</span></code> below.
98 <a name="math_toolkit.next_float.nextafter.h2"></a>
99 <span class="phrase"><a name="math_toolkit.next_float.nextafter.examples_nextafter"></a></span><a class="link" href="nextafter.html#math_toolkit.next_float.nextafter.examples_nextafter">Examples -
103 The two representations using a 32-bit float either side of unity are:
105 <pre class="programlisting"><span class="identifier">The</span> <span class="identifier">nearest</span> <span class="special">(</span><span class="identifier">exact</span><span class="special">)</span> <span class="identifier">representation</span> <span class="identifier">of</span> <span class="number">1.F</span> <span class="identifier">is</span> <span class="number">1.00000000</span>
106 <span class="identifier">nextafter</span><span class="special">(</span><span class="number">1.F</span><span class="special">,</span> <span class="number">999</span><span class="special">)</span> <span class="identifier">is</span> <span class="number">1.00000012</span>
107 <span class="identifier">nextafter</span><span class="special">(</span><span class="number">1</span><span class="special">/</span><span class="identifier">f</span><span class="special">,</span> <span class="special">-</span><span class="number">999</span><span class="special">)</span> <span class="identifier">is</span> <span class="number">0.99999994</span>
109 <span class="identifier">The</span> <span class="identifier">nearest</span> <span class="special">(</span><span class="keyword">not</span> <span class="identifier">exact</span><span class="special">)</span> <span class="identifier">representation</span> <span class="identifier">of</span> <span class="number">0.1F</span> <span class="identifier">is</span> <span class="number">0.100000001</span>
110 <span class="identifier">nextafter</span><span class="special">(</span><span class="number">0.1F</span><span class="special">,</span> <span class="number">10</span><span class="special">)</span> <span class="identifier">is</span> <span class="number">0.100000009</span>
111 <span class="identifier">nextafter</span><span class="special">(</span><span class="number">0.1F</span><span class="special">,</span> <span class="number">10</span><span class="special">)</span> <span class="identifier">is</span> <span class="number">0.099999994</span>
114 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
115 <td align="left"></td>
116 <td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar
117 Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
118 Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
119 Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
120 Daryle Walker and Xiaogang Zhang<p>
121 Distributed under the Boost Software License, Version 1.0. (See accompanying
122 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
127 <div class="spirit-nav">
128 <a accesskey="p" href="../next_float.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../next_float.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="float_next.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>