WSJT-X/boost/libs/math/doc/fp_utilities/sign.qbk

138 lines
4.3 KiB
Plaintext

[section:sign_functions Sign Manipulation Functions]
[h4 Synopsis]
``
#include <boost/math/special_functions/sign.hpp>
``
namespace boost{ namespace math{
template<class T>
int signbit(T x);
template <class T>
int sign (const T& z);
template <class T, class U>
T copysign (const T& x, const U& y);
template <class T>
``__sf_result`` changesign (const T& z);
}} // namespaces
[h4 Description]
template<class T>
int signbit(T x);
Returns a non-zero value if the sign bit is set in variable /x/, otherwise `0`.
[important The return value from this function is zero or /not-zero/ and [*not] zero or one.]
template <class T>
int sign (const T& z);
Returns `1` if /x/ `> 0`, `-1` if /x/ `< 0`, and `0` if /x/ is zero.
template <class T, class U>
``__sf_result`` copysign (const T& x, const U& y);
Sets the sign of /x/ to be the same as the sign of /y/.
See [@http://www.open-std.org/JTC1/SC22/WG14/www/docs/n1256.pdf C99 7.12.11.1 The copysign functions]
for more detail.
template <class T>
T changesign (const T& z);
Returns a floating-point number with a binary representation
where the signbit is the opposite of the sign bit in /x/,
and where the other bits are the same as in /x/.
This function is widely available, but not specified in any standards.
Rationale: Not specified by TR1, but `changesign(x)`
is both easier to read and more efficient than
copysign(x, signbit(x) ? 1.0 : -1.0);
For finite values, this function has the same effect as simple negation,
the assignment z = -z, but for nonfinite values,
[@http://en.wikipedia.org/wiki/Infinity#Computing infinities]
and [@http://en.wikipedia.org/wiki/NaN NaNs],
the `changesign(x)` function may be the only portable way
to ensure that the sign bit is changed.
[h5 Sign bits]
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.)
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf C++ TR1]
specifies `copysign` functions and function templates for accessing the sign bit.
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.
[h5 Examples]
signbit(3.5) is zero (or false)
signbit(-7.1) is 1 (or true)
copysign(4.2, 7.9) is 4.2
copysign(3.5 -1.4) is -3.5
copysign(-4.2, 1.0) is 4.2
copysign(-8.6, -3.3) is -8.6
changesign(6.9) is -6.9
changesign(-1.8) is 1.8
[h5 Portability]
The library supports the following binary floating-point formats:
* IEEE 754 single precision
* IEEE 754 double precision
* IEEE 754 extended double precision with 15 exponent bits
* Intel extended double precision
* PowerPC extended double precision
* Motorola 68K extended double precision
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.)
The main portability issues are:
* Unsupported floating-point formats.
* The library depends on the header `boost/detail/endian.hpp` to detemine endianness.
* Code such as `#if defined(__ia64) || defined(__ia64__) || defined(_M_IA64)`
is used to determine the processor type.
The library has passed all tests on the following platforms:
* Win32 / MSVC 7.1 / 10.0 / x86 32 and 64-bit, and later Win32
* Win32 / Intel C++ 7.1, 8.1, 9.1 / x86
* Mac OS X / GCC 3.3, 4.0 / ppc
* Linux / Intel C++ 9.1 / x86, ia64
* Linux / GCC 3.3 / x86, x64, ia64, ppc, hppa, mips, m68k
* Linux / GCC 3.4 / x64
* HP-UX / aCC, GCC 4.1 / ia64
* HP-UX / aCC / hppa
* Tru64 / Compaq C++ 7.1 / alpha
* VMS / HP C++ 7.1 / alpha (in IEEE floating-point mode)
* VMS / HP C++ 7.2 / ia64 (in IEEE floating-point mode)
[endsect] [/section:sign_functions Sign Manipulation Functions]
[/
Copyright 2006 John Maddock and Paul A. Bristow 2011.
Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or copy at
http://www.boost.org/LICENSE_1_0.txt).
]