generic-library/boost
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
boost/libs/math/doc/html/math_toolkit/sign_functions.html
Edouard DUPIN d0115b733d [DEV] add v1.76.0
2021-10-05 21:37:46 +02:00

253 lines
19 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Sign Manipulation Functions</title>
<link rel="stylesheet" href="../math.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Math Toolkit 3.0.0">
<link rel="up" href="../utils.html" title="Chapter 2. Floating Point Utilities">
<link rel="prev" href="fpclass.html" title="Floating-Point Classification: Infinities and NaNs">
<link rel="next" href="fp_facets.html" title="Facets for Floating-Point Infinities and NaNs">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">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="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>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="math_toolkit.sign_functions"></a><a class="link" href="sign_functions.html" title="Sign Manipulation Functions">Sign Manipulation Functions</a>
</h2></div></div></div>
<h5>
<a name="math_toolkit.sign_functions.h0"></a>
<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>
</h5>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</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">&gt;</span>
</pre>
<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>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
<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>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
<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">&amp;</span> <span class="identifier">z</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</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">&gt;</span>
<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">&amp;</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">U</span><span class="special">&amp;</span> <span class="identifier">y</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
<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">&amp;</span> <span class="identifier">z</span><span class="special">);</span>
<span class="special">}}</span> <span class="comment">// namespaces</span>
</pre>
<h5>
<a name="math_toolkit.sign_functions.h1"></a>
<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>
</h5>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
<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>
</pre>
<p>
Returns a non-zero value if the sign bit is set in variable <span class="emphasis"><em>x</em></span>,
otherwise <code class="computeroutput"><span class="number">0</span></code>.
</p>
<div class="important"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top"><p>
The return value from this function is zero or <span class="emphasis"><em>not-zero</em></span>
and <span class="bold"><strong>not</strong></span> zero or one.
</p></td></tr>
</table></div>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
<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">&amp;</span> <span class="identifier">z</span><span class="special">);</span>
</pre>
<p>
Returns <code class="computeroutput"><span class="number">1</span></code> if <span class="emphasis"><em>x</em></span>
<code class="computeroutput"><span class="special">&gt;</span> <span class="number">0</span></code>,
<code class="computeroutput"><span class="special">-</span><span class="number">1</span></code>
if <span class="emphasis"><em>x</em></span> <code class="computeroutput"><span class="special">&lt;</span> <span class="number">0</span></code>, and <code class="computeroutput"><span class="number">0</span></code>
if <span class="emphasis"><em>x</em></span> is zero.
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</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">&gt;</span>
<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">&amp;</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">U</span><span class="special">&amp;</span> <span class="identifier">y</span><span class="special">);</span>
</pre>
<p>
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>.
</p>
<p>
See <a href="http://www.open-std.org/JTC1/SC22/WG14/www/docs/n1256.pdf" target="_top">C99
7.12.11.1 The copysign functions</a> for more detail.
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
<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">&amp;</span> <span class="identifier">z</span><span class="special">);</span>
</pre>
<p>
Returns a floating-point number with a binary representation where the signbit
is the opposite of the sign bit in <span class="emphasis"><em>x</em></span>, and where the other
bits are the same as in <span class="emphasis"><em>x</em></span>.
</p>
<p>
This function is widely available, but not specified in any standards.
</p>
<p>
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>
is both easier to read and more efficient than
</p>
<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>
</pre>
<p>
For finite values, this function has the same effect as simple negation, the
assignment z = -z, but for nonfinite values, <a href="http://en.wikipedia.org/wiki/Infinity#Computing" target="_top">infinities</a>
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
may be the only portable way to ensure that the sign bit is changed.
</p>
<h6>
<a name="math_toolkit.sign_functions.h2"></a>
<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
bits</a>
</h6>
<p>
One of the bits in the binary representation of a floating-point number gives
the sign, and the remaining bits give the absolute value. That bit is known
as the sign bit. The sign bit is set = 1 for negative numbers, and is not set
= 0 for positive numbers. (This is true for all binary representations of floating-point
numbers that are used by modern microprocessors.)
</p>
<p>
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf" target="_top">C++
TR1</a> specifies <code class="computeroutput"><span class="identifier">copysign</span></code>
functions and function templates for accessing the sign bit.
</p>
<p>
For user-defined types (UDT), the sign may be stored in some other way. They
may also not provide infinity or NaNs. To use these functions with a UDT, it
may be necessary to explicitly specialize them for UDT type T.
</p>
<h6>
<a name="math_toolkit.sign_functions.h3"></a>
<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>
</h6>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
</pre>
<h6>
<a name="math_toolkit.sign_functions.h4"></a>
<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>
</h6>
<p>
The library supports the following binary floating-point formats:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
IEEE 754 single precision
</li>
<li class="listitem">
IEEE 754 double precision
</li>
<li class="listitem">
IEEE 754 extended double precision with 15 exponent bits
</li>
<li class="listitem">
Intel extended double precision
</li>
<li class="listitem">
PowerPC extended double precision
</li>
<li class="listitem">
Motorola 68K extended double precision
</li>
</ul></div>
<p>
The library does not support the VAX floating-point formats. (These are available
on VMS, but the default on VMS is the IEEE 754 floating-point format.)
</p>
<p>
The main portability issues are:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Unsupported floating-point formats.
</li>
<li class="listitem">
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>
to determine endianness.
</li>
<li class="listitem">
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.
</li>
</ul></div>
<p>
The library has passed all tests on the following platforms:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Win32 / MSVC 7.1 / 10.0 / x86 32 and 64-bit, and later Win32
</li>
<li class="listitem">
Win32 / Intel C++ 7.1, 8.1, 9.1 / x86
</li>
<li class="listitem">
Mac OS X / GCC 3.3, 4.0 / ppc
</li>
<li class="listitem">
Linux / Intel C++ 9.1 / x86, ia64
</li>
<li class="listitem">
Linux / GCC 3.3 / x86, x64, ia64, ppc, hppa, mips, m68k
</li>
<li class="listitem">
Linux / GCC 3.4 / x64
</li>
<li class="listitem">
HP-UX / aCC, GCC 4.1 / ia64
</li>
<li class="listitem">
HP-UX / aCC / hppa
</li>
<li class="listitem">
Tru64 / Compaq C++ 7.1 / alpha
</li>
<li class="listitem">
VMS / HP C++ 7.1 / alpha (in IEEE floating-point mode)
</li>
<li class="listitem">
VMS / HP C++ 7.2 / ia64 (in IEEE floating-point mode)
</li>
</ul></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 © 2006-2021 Nikhar Agrawal, Anton Bikineev, Matthew Borland,
Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert Holin, Bruno
Lalande, John Maddock, Evan Miller, Jeremy Murphy, Matthew Pulver, Johan Råde,
Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, Daryle
Walker and Xiaogang Zhang<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<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>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink