[ceph.git] / ceph / src / 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 them 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` to detemine endianness.
* 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 32 and 64-bit, and later Win32
* 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).
]
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