138 lines
4.3 KiB
Plaintext
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).
|
|
]
|
|
|