CppAD: A C++ Algorithmic Differentiation Package 20110419
nan.hpp
Go to the documentation of this file.
00001 /* $Id$ */
00002 # ifndef CPPAD_NAN_INCLUDED
00003 # define CPPAD_NAN_INCLUDED
00004 
00005 /* --------------------------------------------------------------------------
00006 CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-07 Bradley M. Bell
00007 
00008 CppAD is distributed under multiple licenses. This distribution is under
00009 the terms of the 
00010                     Common Public License Version 1.0.
00011 
00012 A copy of this license is included in the COPYING file of this distribution.
00013 Please visit http://www.coin-or.org/CppAD/ for information on other licenses.
00014 -------------------------------------------------------------------------- */
00015 /*
00016 $begin nan$$
00017 $spell
00018         hasnan
00019         cppad
00020         hpp
00021         CppAD
00022         isnan
00023         bool
00024         const
00025 $$
00026 
00027 $section Obtain Nan and Determine if a Value is Nan$$
00028 
00029 $index isnan$$
00030 $index hasnan$$
00031 $index nan$$
00032 
00033 $head Syntax$$
00034 $syntax%# include <cppad/nan.hpp>
00035 %$$
00036 $syntax%%s% = nan(%z%)
00037 %$$
00038 $syntax%%b% = isnan(%s%)
00039 %$$
00040 $syntax%%b% = hasnan(%v%)%$$
00041 
00042 $head Purpose$$
00043 It obtain and check for the value not a number $code nan$$.
00044 The IEEE standard specifies that a floating point value $italic a$$ 
00045 is $code nan$$ if and only if the following returns true
00046 $syntax%
00047         %a% != %a%
00048 %$$ 
00049 Some systems do not get this correct, so we also use the fact that
00050 zero divided by zero should result in a $code nan$$.
00051 To be specific, if a value is not equal to itself or 
00052 if it is equal to zero divided by zero, it is considered to be a $code nan$$.
00053 
00054 $head Include$$
00055 The file $code cppad/nan.hpp$$ is included by $code cppad/cppad.hpp$$
00056 but it can also be included separately with out the rest of 
00057 the $code CppAD$$ routines.
00058 
00059 $subhead Macros$$
00060 $index macro, nan$$
00061 $index macro,  isnan$$
00062 $index nan, macro$$
00063 $index isnan, macro$$
00064 Some C++ compilers use preprocessor symbols called $code nan$$ 
00065 and $code isnan$$.
00066 These preprocessor symbols will no longer be defined after 
00067 this file is included. 
00068 
00069 $head nan$$
00070 This routine returns a $code nan$$ with the same type as $italic z$$.
00071 
00072 $subhead z$$
00073 The argument $italic z$$ has prototype
00074 $syntax%
00075         const %Scalar% &%z% 
00076 %$$
00077 and its value is zero
00078 (see $cref/Scalar/nan/Scalar/$$ for the definition of $italic Scalar$$).
00079 
00080 $subhead s$$
00081 The return value $italic s$$ has prototype
00082 $syntax%
00083         %Scalar% %s%
00084 %$$
00085 It is the value $code nan$$ for this floating point type.
00086 
00087 $head isnan$$
00088 This routine determines if a scalar value is $code nan$$.
00089 
00090 $subhead s$$
00091 The argument $italic s$$ has prototype
00092 $syntax%
00093         const %Scalar% %s%
00094 %$$
00095 
00096 $subhead b$$
00097 The return value $italic b$$ has prototype
00098 $syntax%
00099         bool %b%
00100 %$$
00101 It is true if the value $italic s$$ is $code nan$$.
00102 
00103 $head hasnan$$
00104 This routine determines if a 
00105 $cref/SimpleVector/$$ has an element that is $code nan$$.
00106 
00107 $subhead v$$
00108 The argument $italic v$$ has prototype
00109 $syntax%
00110         const %Vector% &%v%
00111 %$$
00112 (see $cref/Vector/nan/Vector/$$ for the definition of $italic Vector$$).
00113 
00114 $subhead b$$
00115 The return value $italic b$$ has prototype
00116 $syntax%
00117         bool %b%
00118 %$$
00119 It is true if the vector $italic v$$ has a $code nan$$.
00120 
00121 $head Scalar$$
00122 The type $italic Scalar$$ must support the following operations;
00123 $table
00124 $bold Operation$$ $cnext $bold Description$$  $rnext
00125 $syntax%%a% / %b%$$ $cnext
00126         division operator (returns a $italic Scalar$$ object)
00127 $rnext
00128 $syntax%%a% == %b%$$ $cnext
00129         equality operator (returns a $code bool$$ object)
00130 $rnext
00131 $syntax%%a% != %b%$$ $cnext
00132         not equality operator (returns a $code bool$$ object)
00133 $tend
00134 Note that the division operator will be used with $italic a$$ and $italic b$$
00135 equal to zero. For some types (e.g. $code int$$) this may generate
00136 an exception. No attempt is made to catch any such exception.
00137 
00138 $head Vector$$
00139 The type $italic Vector$$ must be a $xref/SimpleVector/$$ class with
00140 elements of type $italic Scalar$$.
00141 
00142 $children%
00143         example/nan.cpp
00144 %$$
00145 $head Example$$
00146 The file $cref/nan.cpp/$$
00147 contains an example and test of this routine.
00148 It returns true if it succeeds and false otherwise.
00149 
00150 $end
00151 */
00152 
00153 # include <cstddef>
00154 
00155 # ifdef nan
00156 # undef nan
00157 # endif
00158 # ifdef isnan
00159 # undef isnan
00160 # endif
00161 
00162 namespace CppAD { // BEGIN CppAD namespace
00163 
00164 template <class Scalar>
00165 inline Scalar nan(const Scalar &zero)
00166 {       return zero / zero;
00167 }
00168 
00169 template <class Scalar>
00170 inline bool isnan(const Scalar &s)
00171 {       static Scalar scalar_nan = nan( Scalar(0) );    
00172         return (s != s) || (s == scalar_nan);
00173 }
00174 
00175 template <class Vector>
00176 bool hasnan(const Vector &v)
00177 {
00178         typedef typename Vector::value_type Scalar;
00179 
00180         bool found_nan;
00181         size_t i;
00182         i   = v.size();
00183         found_nan = false;
00184         while(i--)
00185                 found_nan |= isnan(v[i]);
00186         return found_nan;
00187 }
00188 
00189 } // End CppAD namespace
00190 
00191 # endif