1 [section:sign_functions Sign Manipulation Functions]
6 #include <boost/math/special_functions/sign.hpp>
9 namespace boost{ namespace math{
15 int sign (const T& z);
17 template <class T, class U>
18 T copysign (const T& x, const U& y);
21 ``__sf_result`` changesign (const T& z);
30 Returns a non-zero value if the sign bit is set in variable /x/, otherwise `0`.
32 [important The return value from this function is zero or /not-zero/ and [*not] zero or one.]
35 int sign (const T& z);
37 Returns `1` if /x/ `> 0`, `-1` if /x/ `< 0`, and `0` if /x/ is zero.
39 template <class T, class U>
40 ``__sf_result`` copysign (const T& x, const U& y);
42 Sets the sign of /x/ to be the same as the sign of /y/.
44 See [@http://www.open-std.org/JTC1/SC22/WG14/www/docs/n1256.pdf C99 7.12.11.1 The copysign functions]
48 T changesign (const T& z);
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/.
54 This function is widely available, but not specified in any standards.
56 Rationale: Not specified by TR1, but `changesign(x)`
57 is both easier to read and more efficient than
59 copysign(x, signbit(x) ? 1.0 : -1.0);
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.
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.)
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.
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.
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
97 The library supports the following binary floating-point formats:
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
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.)
109 The main portability issues are:
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.
116 The library has passed all tests on the following platforms:
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
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)
130 [endsect] [/section:sign_functions Sign Manipulation Functions]
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).