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

   1 [section:sign_functions Sign Manipulation Functions]
   2
   3 [h4 Synopsis]
   4
   5 ``
   6 #include <boost/math/special_functions/sign.hpp>
   7 ``
   8
   9    namespace boost{ namespace math{
  10
  11    template<class T>
  12    int signbit(T x);
  13
  14    template <class T>
  15    int sign (const T& z);
  16
  17    template <class T, class U>
  18    T copysign (const T& x, const U& y);
  19
  20    template <class T>
  21    ``__sf_result`` changesign (const T& z);
  22
  23    }} // namespaces
  24
  25 [h4 Description]
  26
  27    template<class T>
  28    int signbit(T x);
  29
  30 Returns a non-zero value if the sign bit is set in variable /x/, otherwise `0`.
  31
  32 [important The return value from this function is zero or /not-zero/ and [*not] zero or one.]
  33
  34    template <class T>
  35    int sign (const T& z);
  36
  37 Returns `1` if /x/ `> 0`, `-1` if /x/ `< 0`, and `0` if /x/ is zero.
  38
  39    template <class T, class U>
  40    ``__sf_result`` copysign (const T& x, const U& y);
  41
  42 Sets the sign of /x/ to be the same as the sign of /y/.
  43
  44 See [@http://www.open-std.org/JTC1/SC22/WG14/www/docs/n1256.pdf C99 7.12.11.1 The copysign functions]
  45 for more detail.
  46
  47    template <class T>
  48    T changesign (const T& z);
  49
  50 Returns a floating-point number with a binary representation
  51 where the signbit is the opposite of the sign bit in /x/,
  52 and where the other bits are the same as in /x/.
  53
  54 This function is widely available, but not specified in any standards.
  55
  56 Rationale: Not specified by TR1, but `changesign(x)`
  57 is both easier to read and more efficient than
  58
  59   copysign(x, signbit(x) ? 1.0 : -1.0);
  60
  61 For finite values, this function has the same effect as simple negation,
  62 the assignment z = -z, but for nonfinite values,
  63 [@http://en.wikipedia.org/wiki/Infinity#Computing infinities]
  64 and [@http://en.wikipedia.org/wiki/NaN NaNs],
  65 the `changesign(x)` function may be the only portable way
  66 to ensure that the sign bit is changed.
  67
  68 [h5 Sign bits]
  69 One of the bits in the binary representation of a floating-point number gives the sign,
  70 and the remaining bits give the absolute value.
  71 That bit is known as the sign bit.
  72 The sign bit is set = 1 for negative numbers, and is not set = 0 for positive numbers.
  73 (This is true for all binary representations of floating-point numbers
  74 that are used by modern microprocessors.)
  75
  76 [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf C++ TR1]
  77 specifies `copysign` functions and function templates for accessing the sign bit.
  78
  79 For user-defined types (UDT), the sign may be stored in some other way.
  80 They may also not provide infinity or NaNs.
  81 To use these functions with a UDT,
  82 it may be necessary to explicitly specialize them for UDT type T.
  83
  84 [h5 Examples]
  85
  86   signbit(3.5) is zero (or false)
  87   signbit(-7.1) is 1 (or true)
  88   copysign(4.2, 7.9) is 4.2
  89   copysign(3.5 -1.4) is -3.5
  90   copysign(-4.2, 1.0) is 4.2
  91   copysign(-8.6, -3.3) is -8.6
  92   changesign(6.9) is -6.9
  93   changesign(-1.8) is 1.8
  94
  95 [h5 Portability]
  96
  97 The library supports the following binary floating-point formats:
  98
  99 * IEEE 754 single precision
 100 * IEEE 754 double precision
 101 * IEEE 754 extended double precision with 15 exponent bits
 102 * Intel extended double precision
 103 * PowerPC extended double precision
 104 * Motorola 68K extended double precision
 105
 106 The library does not support the VAX floating-point formats.
 107 (These are available on VMS, but the default on VMS is the IEEE 754 floating-point format.)
 108
 109 The main portability issues are:
 110
 111 * Unsupported floating-point formats.
 112 * The library depends on the header `boost/detail/endian.hpp` to detemine endianness.
 113 * Code such as `#if defined(__ia64) || defined(__ia64__) || defined(_M_IA64)`
 114 is used to determine the processor type.
 115
 116 The library has passed all tests on the following platforms:
 117
 118 * Win32 / MSVC 7.1 / 10.0 / x86 32 and 64-bit, and later Win32
 119 * Win32 / Intel C++ 7.1, 8.1, 9.1 / x86
 120 * Mac OS X / GCC 3.3, 4.0 / ppc
 121 * Linux / Intel C++ 9.1 / x86, ia64
 122 * Linux / GCC 3.3 / x86, x64, ia64, ppc, hppa, mips, m68k
 123 * Linux / GCC 3.4 / x64
 124 * HP-UX / aCC, GCC 4.1 / ia64
 125 * HP-UX / aCC / hppa
 126 * Tru64 / Compaq C++ 7.1 / alpha
 127 * VMS / HP C++ 7.1 / alpha     (in IEEE floating-point mode)
 128 * VMS / HP C++ 7.2 / ia64      (in IEEE floating-point mode)
 129
 130 [endsect] [/section:sign_functions Sign Manipulation Functions]
 131 [/
 132   Copyright 2006 John Maddock and Paul A. Bristow 2011.
 133   Distributed under the Boost Software License, Version 1.0.
 134   (See accompanying file LICENSE_1_0.txt or copy at
 135   http://www.boost.org/LICENSE_1_0.txt).
 136 ]
 137