3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
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.11.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">
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="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>
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>
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>
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>
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>
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>
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>
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>
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>
49 <span class="special">}}</span> <span class="comment">// namespaces</span>
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>
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>
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>.
62 <div class="important"><table border="0" summary="Important">
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>
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.
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>
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.
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>
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>.
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.
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>
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>.
101 This function is widely available, but not specified in any standards.
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
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>
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.
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
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.)
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.
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.
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>
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>
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>
155 The library supports the following binary floating-point formats:
157 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
158 <li class="listitem">
159 IEEE 754 single precision
161 <li class="listitem">
162 IEEE 754 double precision
164 <li class="listitem">
165 IEEE 754 extended double precision with 15 exponent bits
167 <li class="listitem">
168 Intel extended double precision
170 <li class="listitem">
171 PowerPC extended double precision
173 <li class="listitem">
174 Motorola 68K extended double precision
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.)
182 The main portability issues are:
184 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
185 <li class="listitem">
186 Unsupported floating-point formats.
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 detemine endianness.
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.
197 The library has passed all tests on the following platforms:
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
203 <li class="listitem">
204 Win32 / Intel C++ 7.1, 8.1, 9.1 / x86
206 <li class="listitem">
207 Mac OS X / GCC 3.3, 4.0 / ppc
209 <li class="listitem">
210 Linux / Intel C++ 9.1 / x86, ia64
212 <li class="listitem">
213 Linux / GCC 3.3 / x86, x64, ia64, ppc, hppa, mips, m68k
215 <li class="listitem">
216 Linux / GCC 3.4 / x64
218 <li class="listitem">
219 HP-UX / aCC, GCC 4.1 / ia64
221 <li class="listitem">
224 <li class="listitem">
225 Tru64 / Compaq C++ 7.1 / alpha
227 <li class="listitem">
228 VMS / HP C++ 7.1 / alpha (in IEEE floating-point mode)
230 <li class="listitem">
231 VMS / HP C++ 7.2 / ia64 (in IEEE floating-point mode)
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>)
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>