]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 |