boost/libs/math/doc/fp_utilities/sign.qbk

[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 then 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
* 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
* 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).
]