1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Sign Manipulation Functions</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.12.0"> 8<link rel="up" href="../utils.html" title="Chapter 2. Floating Point Utilities"> 9<link rel="prev" href="fpclass.html" title="Floating-Point Classification: Infinities and NaNs"> 10<link rel="next" href="fp_facets.html" title="Facets for Floating-Point Infinities and NaNs"> 11</head> 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> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="fpclass.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../utils.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="fp_facets.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 27<a name="math_toolkit.sign_functions"></a><a class="link" href="sign_functions.html" title="Sign Manipulation Functions">Sign Manipulation Functions</a> 28</h2></div></div></div> 29<h5> 30<a name="math_toolkit.sign_functions.h0"></a> 31 <span class="phrase"><a name="math_toolkit.sign_functions.synopsis"></a></span><a class="link" href="sign_functions.html#math_toolkit.sign_functions.synopsis">Synopsis</a> 32 </h5> 33<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">sign</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 34</pre> 35<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> 36 37<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> 38<span class="keyword">int</span> <span class="identifier">signbit</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span> 39 40<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> 41<span class="keyword">int</span> <span class="identifier">sign</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">z</span><span class="special">);</span> 42 43<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">></span> 44<span class="identifier">T</span> <span class="identifier">copysign</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">U</span><span class="special">&</span> <span class="identifier">y</span><span class="special">);</span> 45 46<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> 47<a class="link" href="result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">changesign</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">z</span><span class="special">);</span> 48 49<span class="special">}}</span> <span class="comment">// namespaces</span> 50</pre> 51<h5> 52<a name="math_toolkit.sign_functions.h1"></a> 53 <span class="phrase"><a name="math_toolkit.sign_functions.description"></a></span><a class="link" href="sign_functions.html#math_toolkit.sign_functions.description">Description</a> 54 </h5> 55<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> 56<span class="keyword">int</span> <span class="identifier">signbit</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span> 57</pre> 58<p> 59 Returns a non-zero value if the sign bit is set in variable <span class="emphasis"><em>x</em></span>, 60 otherwise <code class="computeroutput"><span class="number">0</span></code>. 61 </p> 62<div class="important"><table border="0" summary="Important"> 63<tr> 64<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td> 65<th align="left">Important</th> 66</tr> 67<tr><td align="left" valign="top"><p> 68 The return value from this function is zero or <span class="emphasis"><em>not-zero</em></span> 69 and <span class="bold"><strong>not</strong></span> zero or one. 70 </p></td></tr> 71</table></div> 72<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> 73<span class="keyword">int</span> <span class="identifier">sign</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">z</span><span class="special">);</span> 74</pre> 75<p> 76 Returns <code class="computeroutput"><span class="number">1</span></code> if <span class="emphasis"><em>x</em></span> 77 <code class="computeroutput"><span class="special">></span> <span class="number">0</span></code>, 78 <code class="computeroutput"><span class="special">-</span><span class="number">1</span></code> 79 if <span class="emphasis"><em>x</em></span> <code class="computeroutput"><span class="special"><</span> <span class="number">0</span></code>, and <code class="computeroutput"><span class="number">0</span></code> 80 if <span class="emphasis"><em>x</em></span> is zero. 81 </p> 82<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">></span> 83<a class="link" href="result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">copysign</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">U</span><span class="special">&</span> <span class="identifier">y</span><span class="special">);</span> 84</pre> 85<p> 86 Sets the sign of <span class="emphasis"><em>x</em></span> to be the same as the sign of <span class="emphasis"><em>y</em></span>. 87 </p> 88<p> 89 See <a href="http://www.open-std.org/JTC1/SC22/WG14/www/docs/n1256.pdf" target="_top">C99 90 7.12.11.1 The copysign functions</a> for more detail. 91 </p> 92<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> 93<span class="identifier">T</span> <span class="identifier">changesign</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">z</span><span class="special">);</span> 94</pre> 95<p> 96 Returns a floating-point number with a binary representation where the signbit 97 is the opposite of the sign bit in <span class="emphasis"><em>x</em></span>, and where the other 98 bits are the same as in <span class="emphasis"><em>x</em></span>. 99 </p> 100<p> 101 This function is widely available, but not specified in any standards. 102 </p> 103<p> 104 Rationale: Not specified by TR1, but <code class="computeroutput"><span class="identifier">changesign</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code> 105 is both easier to read and more efficient than 106 </p> 107<pre class="programlisting"><span class="identifier">copysign</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">signbit</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">?</span> <span class="number">1.0</span> <span class="special">:</span> <span class="special">-</span><span class="number">1.0</span><span class="special">);</span> 108</pre> 109<p> 110 For finite values, this function has the same effect as simple negation, the 111 assignment z = -z, but for nonfinite values, <a href="http://en.wikipedia.org/wiki/Infinity#Computing" target="_top">infinities</a> 112 and <a href="http://en.wikipedia.org/wiki/NaN" target="_top">NaNs</a>, the <code class="computeroutput"><span class="identifier">changesign</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code> function 113 may be the only portable way to ensure that the sign bit is changed. 114 </p> 115<h6> 116<a name="math_toolkit.sign_functions.h2"></a> 117 <span class="phrase"><a name="math_toolkit.sign_functions.sign_bits"></a></span><a class="link" href="sign_functions.html#math_toolkit.sign_functions.sign_bits">Sign 118 bits</a> 119 </h6> 120<p> 121 One of the bits in the binary representation of a floating-point number gives 122 the sign, and the remaining bits give the absolute value. That bit is known 123 as the sign bit. The sign bit is set = 1 for negative numbers, and is not set 124 = 0 for positive numbers. (This is true for all binary representations of floating-point 125 numbers that are used by modern microprocessors.) 126 </p> 127<p> 128 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf" target="_top">C++ 129 TR1</a> specifies <code class="computeroutput"><span class="identifier">copysign</span></code> 130 functions and function templates for accessing the sign bit. 131 </p> 132<p> 133 For user-defined types (UDT), the sign may be stored in some other way. They 134 may also not provide infinity or NaNs. To use these functions with a UDT, it 135 may be necessary to explicitly specialize them for UDT type T. 136 </p> 137<h6> 138<a name="math_toolkit.sign_functions.h3"></a> 139 <span class="phrase"><a name="math_toolkit.sign_functions.examples"></a></span><a class="link" href="sign_functions.html#math_toolkit.sign_functions.examples">Examples</a> 140 </h6> 141<pre class="programlisting"><span class="identifier">signbit</span><span class="special">(</span><span class="number">3.5</span><span class="special">)</span> <span class="identifier">is</span> <span class="identifier">zero</span> <span class="special">(</span><span class="keyword">or</span> <span class="keyword">false</span><span class="special">)</span> 142<span class="identifier">signbit</span><span class="special">(-</span><span class="number">7.1</span><span class="special">)</span> <span class="identifier">is</span> <span class="number">1</span> <span class="special">(</span><span class="keyword">or</span> <span class="keyword">true</span><span class="special">)</span> 143<span class="identifier">copysign</span><span class="special">(</span><span class="number">4.2</span><span class="special">,</span> <span class="number">7.9</span><span class="special">)</span> <span class="identifier">is</span> <span class="number">4.2</span> 144<span class="identifier">copysign</span><span class="special">(</span><span class="number">3.5</span> <span class="special">-</span><span class="number">1.4</span><span class="special">)</span> <span class="identifier">is</span> <span class="special">-</span><span class="number">3.5</span> 145<span class="identifier">copysign</span><span class="special">(-</span><span class="number">4.2</span><span class="special">,</span> <span class="number">1.0</span><span class="special">)</span> <span class="identifier">is</span> <span class="number">4.2</span> 146<span class="identifier">copysign</span><span class="special">(-</span><span class="number">8.6</span><span class="special">,</span> <span class="special">-</span><span class="number">3.3</span><span class="special">)</span> <span class="identifier">is</span> <span class="special">-</span><span class="number">8.6</span> 147<span class="identifier">changesign</span><span class="special">(</span><span class="number">6.9</span><span class="special">)</span> <span class="identifier">is</span> <span class="special">-</span><span class="number">6.9</span> 148<span class="identifier">changesign</span><span class="special">(-</span><span class="number">1.8</span><span class="special">)</span> <span class="identifier">is</span> <span class="number">1.8</span> 149</pre> 150<h6> 151<a name="math_toolkit.sign_functions.h4"></a> 152 <span class="phrase"><a name="math_toolkit.sign_functions.portability"></a></span><a class="link" href="sign_functions.html#math_toolkit.sign_functions.portability">Portability</a> 153 </h6> 154<p> 155 The library supports the following binary floating-point formats: 156 </p> 157<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 158<li class="listitem"> 159 IEEE 754 single precision 160 </li> 161<li class="listitem"> 162 IEEE 754 double precision 163 </li> 164<li class="listitem"> 165 IEEE 754 extended double precision with 15 exponent bits 166 </li> 167<li class="listitem"> 168 Intel extended double precision 169 </li> 170<li class="listitem"> 171 PowerPC extended double precision 172 </li> 173<li class="listitem"> 174 Motorola 68K extended double precision 175 </li> 176</ul></div> 177<p> 178 The library does not support the VAX floating-point formats. (These are available 179 on VMS, but the default on VMS is the IEEE 754 floating-point format.) 180 </p> 181<p> 182 The main portability issues are: 183 </p> 184<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 185<li class="listitem"> 186 Unsupported floating-point formats. 187 </li> 188<li class="listitem"> 189 The library depends on the header <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">detail</span><span class="special">/</span><span class="identifier">endian</span><span class="special">.</span><span class="identifier">hpp</span></code> 190 to determine endianness. 191 </li> 192<li class="listitem"> 193 Code such as <code class="computeroutput"><span class="preprocessor">#if</span> <span class="identifier">defined</span><span class="special">(</span><span class="identifier">__ia64</span><span class="special">)</span> <span class="special">||</span> <span class="identifier">defined</span><span class="special">(</span><span class="identifier">__ia64__</span><span class="special">)</span> <span class="special">||</span> <span class="identifier">defined</span><span class="special">(</span><span class="identifier">_M_IA64</span><span class="special">)</span></code> is used to determine the processor type. 194 </li> 195</ul></div> 196<p> 197 The library has passed all tests on the following platforms: 198 </p> 199<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 200<li class="listitem"> 201 Win32 / MSVC 7.1 / 10.0 / x86 32 and 64-bit, and later Win32 202 </li> 203<li class="listitem"> 204 Win32 / Intel C++ 7.1, 8.1, 9.1 / x86 205 </li> 206<li class="listitem"> 207 Mac OS X / GCC 3.3, 4.0 / ppc 208 </li> 209<li class="listitem"> 210 Linux / Intel C++ 9.1 / x86, ia64 211 </li> 212<li class="listitem"> 213 Linux / GCC 3.3 / x86, x64, ia64, ppc, hppa, mips, m68k 214 </li> 215<li class="listitem"> 216 Linux / GCC 3.4 / x64 217 </li> 218<li class="listitem"> 219 HP-UX / aCC, GCC 4.1 / ia64 220 </li> 221<li class="listitem"> 222 HP-UX / aCC / hppa 223 </li> 224<li class="listitem"> 225 Tru64 / Compaq C++ 7.1 / alpha 226 </li> 227<li class="listitem"> 228 VMS / HP C++ 7.1 / alpha (in IEEE floating-point mode) 229 </li> 230<li class="listitem"> 231 VMS / HP C++ 7.2 / ia64 (in IEEE floating-point mode) 232 </li> 233</ul></div> 234</div> 235<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 236<td align="left"></td> 237<td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar 238 Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, 239 Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan 240 Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, 241 Daryle Walker and Xiaogang Zhang<p> 242 Distributed under the Boost Software License, Version 1.0. (See accompanying 243 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>) 244 </p> 245</div></td> 246</tr></table> 247<hr> 248<div class="spirit-nav"> 249<a accesskey="p" href="fpclass.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../utils.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="fp_facets.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 250</div> 251</body> 252</html> 253
