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 30Returns 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 37Returns `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 42Sets the sign of /x/ to be the same as the sign of /y/. 43 44See [@http://www.open-std.org/JTC1/SC22/WG14/www/docs/n1256.pdf C99 7.12.11.1 The copysign functions] 45for more detail. 46 47 template <class T> 48 T changesign (const T& z); 49 50Returns a floating-point number with a binary representation 51where the signbit is the opposite of the sign bit in /x/, 52and where the other bits are the same as in /x/. 53 54This function is widely available, but not specified in any standards. 55 56Rationale: Not specified by TR1, but `changesign(x)` 57is both easier to read and more efficient than 58 59 copysign(x, signbit(x) ? 1.0 : -1.0); 60 61For finite values, this function has the same effect as simple negation, 62the assignment z = -z, but for nonfinite values, 63[@http://en.wikipedia.org/wiki/Infinity#Computing infinities] 64and [@http://en.wikipedia.org/wiki/NaN NaNs], 65the `changesign(x)` function may be the only portable way 66to ensure that the sign bit is changed. 67 68[h5 Sign bits] 69One of the bits in the binary representation of a floating-point number gives the sign, 70and the remaining bits give the absolute value. 71That bit is known as the sign bit. 72The 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 74that are used by modern microprocessors.) 75 76[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf C++ TR1] 77specifies `copysign` functions and function templates for accessing the sign bit. 78 79For user-defined types (UDT), the sign may be stored in some other way. 80They may also not provide infinity or NaNs. 81To use these functions with a UDT, 82it 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 97The 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 106The 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 109The main portability issues are: 110 111* Unsupported floating-point formats. 112* The library depends on the header `boost/detail/endian.hpp` to determine endianness. 113* Code such as `#if defined(__ia64) || defined(__ia64__) || defined(_M_IA64)` 114is used to determine the processor type. 115 116The 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 138