[Boost-commit] svn:boost r71278 - trunk/libs/math/doc/sf_and_dist

Subject: [Boost-commit] svn:boost r71278 - trunk/libs/math/doc/sf_and_dist
From: pbristow_at_[hidden]
Date: 2011-04-15 09:58:38

Author: pbristow
Date: 2011-04-15 09:58:38 EDT (Fri, 15 Apr 2011)
New Revision: 71278
URL: http://svn.boost.org/trac/boost/changeset/71278

Log:
Added changesign for nonfinite facets.
Text files modified: 
   trunk/libs/math/doc/sf_and_dist/sign.qbk |    93 +++++++++++++++++++++++++++++++++++++++ 
   1 files changed, 91 insertions(+), 2 deletions(-)

Modified: trunk/libs/math/doc/sf_and_dist/sign.qbk
==============================================================================
--- trunk/libs/math/doc/sf_and_dist/sign.qbk	(original)
+++ trunk/libs/math/doc/sf_and_dist/sign.qbk	2011-04-15 09:58:38 EDT (Fri, 15 Apr 2011)
@@ -16,6 +16,9 @@
 
    template <class T>
    inline T copysign (const T& x, const T& y);
+
+   template <class T>
+   inline T changesign (const T& z);
    
    }} // namespaces
 
@@ -29,16 +32,102 @@
    template <class T>
    inline int sign (const T& z);
    
-Returns `1` if `x > 0`, `-1` if `x < 0`, and `0` if x is zero.
+Returns `1` if /x/ `> 0`, `-1` if /x/ `< 0`, and `0` if /x/ is zero.
 
    template <class T>
    inline T copysign (const T& x, const T& 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>
+   inline 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 then 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
+* 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
+* 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.
+  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).