cxxutils.h

00001 /*
00002  *  This file is part of Healpix_cxx.
00003  *
00004  *  Healpix_cxx is free software; you can redistribute it and/or modify
00005  *  it under the terms of the GNU General Public License as published by
00006  *  the Free Software Foundation; either version 2 of the License, or
00007  *  (at your option) any later version.
00008  *
00009  *  Healpix_cxx is distributed in the hope that it will be useful,
00010  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00011  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00012  *  GNU General Public License for more details.
00013  *
00014  *  You should have received a copy of the GNU General Public License
00015  *  along with Healpix_cxx; if not, write to the Free Software
00016  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
00017  *
00018  *  For more information about HEALPix, see http://healpix.jpl.nasa.gov
00019  */
00020 
00021 /*
00022  *  Healpix_cxx is being developed at the Max-Planck-Institut fuer Astrophysik
00023  *  and financially supported by the Deutsches Zentrum fuer Luft- und Raumfahrt
00024  *  (DLR).
00025  */
00026 
00027 /*! \file cxxutils.h
00028  *  Various convenience functions used by the Planck LevelS package.
00029  *
00030  *  Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007 Max-Planck-Society
00031  *  \author Martin Reinecke \author Reinhard Hell
00032  */
00033 
00034 #ifndef PLANCK_CXXUTILS_H
00035 #define PLANCK_CXXUTILS_H
00036 
00037 #include <algorithm>
00038 #include <string>
00039 #include <map>
00040 #include <cmath>
00041 #include "message_error.h"
00042 #include "lsconstants.h"
00043 
00044 /*! \defgroup mathutilsgroup Mathematical helper functions */
00045 /*! \{ */
00046 
00047 //! Returns \e true if | \a a-b | < \a epsilon * | \a b |, else \e false.
00048 template<typename F> inline bool approx (F a, F b, F epsilon=1e-5)
00049   {
00050   using namespace std;
00051   return abs(a-b) < (epsilon*abs(b));
00052   }
00053 
00054 //! Returns \e true if | \a a-b | < \a epsilon, else \e false.
00055 template<typename F> inline bool abs_approx (F a, F b, F epsilon=1e-5)
00056   {
00057   using namespace std;
00058   return abs(a-b) < epsilon;
00059   }
00060 
00061 //! Returns the largest integer which is smaller than (or equal to) \a arg.
00062 template<typename I, typename F> inline I ifloor (F arg)
00063   {
00064   return (arg>=0) ? I(arg) : I(arg)-1;
00065   }
00066 
00067 //! Returns the integer which is nearest to \a arg.
00068 template<typename I, typename F> inline I nearest (F arg)
00069   {
00070   arg += 0.5;
00071   return (arg>=0) ? I(arg) : I(arg)-1;
00072   }
00073 
00074 //! Returns \a v1+v2 if \a v1<0, \a v1-v2 if \a v1>=v2, else \a v1.
00075 /*! \a v1 can be positive or negative; \a v2 must be positive. */
00076 template<typename T> inline T weak_modulo (T v1, T v2)
00077   { return (v1>=0) ? ((v1<v2) ? v1 : (v1-v2)) : (v1+v2); }
00078 
00079 //! Returns the remainder of the division \a v1/v2.
00080 /*! The result is non-negative.
00081     \a v1 can be positive or negative; \a v2 must be positive. */
00082 inline double fmodulo (double v1, double v2)
00083   {
00084   using namespace std;
00085   return (v1>=0) ? ((v1<v2) ? v1 : fmod(v1,v2)) : (fmod(v1,v2)+v2);
00086   }
00087 
00088 //! Returns the remainder of the division \a v1/v2.
00089 /*! The result is non-negative.
00090     \a v1 can be positive or negative; \a v2 must be positive. */
00091 template<typename I> inline I imodulo (I v1, I v2)
00092   { return (v1>=0) ? ((v1<v2) ? v1 : (v1%v2)) : ((v1%v2)+v2); }
00093 
00094 //! Returns -1 if \a signvalue is negative, else +1.
00095 template<typename T> inline T sign (const T& signvalue)
00096   { return (signvalue>=0) ? 1 : -1; }
00097 
00098 //! Returns the integer \a n, which fulfills \a n*n<=arg<(n+1)*(n+1).
00099 template<typename I> inline unsigned int isqrt (I arg)
00100   {
00101   using namespace std;
00102   if (sizeof(I)<=4)
00103     return unsigned (sqrt(arg+0.5));
00104   long double arg2 = arg;
00105   return unsigned (sqrt(arg2+0.5));
00106   }
00107 
00108 //! Returns the largest integer \a n that fulfills \a 2^n<=arg.
00109 template<typename I> inline unsigned int ilog2 (I arg)
00110   {
00111   unsigned int res=0;
00112   while (arg > 0x0000FFFF) { res+=16; arg>>=16; }
00113   if (arg > 0x000000FF) { res|=8; arg>>=8; }
00114   if (arg > 0x0000000F) { res|=4; arg>>=4; }
00115   if (arg > 0x00000003) { res|=2; arg>>=2; }
00116   if (arg > 0x00000001) { res|=1; }
00117   return res;
00118   }
00119 
00120 //! Returns \a atan2(y,x) if \a x!=0 or \a y!=0; else returns 0.
00121 inline double safe_atan2 (double y, double x)
00122   {
00123   using namespace std;
00124   return ((x==0.) && (y==0.)) ? 0.0 : atan2(y,x);
00125   }
00126 
00127 //! Returns an index to the left of two interpolation values.
00128 /*! \a begin points to an array containing a sequence of values
00129     sorted in ascending order. The length of the array is \a len.
00130     If \a val is lower than the first element, 0 is returned.
00131     If \a val is higher than the last element, \a len-2
00132     is returned. Else, the index of the largest element smaller
00133     than \a val is returned. */
00134 template<typename T> inline int interpol_left
00135   (const T *begin, int len, const T &val)
00136   {
00137   const T *end = begin+len;
00138   const T *iter = std::lower_bound (begin, end, val);
00139   if (iter==begin) return 0;
00140   if (iter==end) return len-2;
00141   return (iter-begin)-1;
00142   }
00143 
00144 //! Returns an index to the nearest interpolation value.
00145 /*! \a begin points to an array containing a sequence of values
00146     sorted in ascending order. The length of the array is \a len.
00147     If \a val is lower than the first element, 0 is returned.
00148     If \a val is higher than the last element, \a len-1 is returned.
00149     Else, the index of the nearest element within the sequence of
00150     values is returned. */
00151 template<typename T> inline int interpol_nearest
00152   (const T *begin, int len, const T &val)
00153   {
00154   int left = interpol_left(begin, len, val);
00155   T delleft = val-(*(begin+left));
00156   T delright = (*(begin+left+1))-val;
00157   if (delright<0) return left+1;
00158   return (delright<delleft) ? (left+1) : left;
00159   }
00160 
00161 /*! \} */
00162 
00163 /*! \defgroup fileutilsgroup File-handling helper functions */
00164 /*! \{ */
00165 
00166 //! If the file \a filename is present, return \p true, else \p false.
00167 bool file_present (const std::string &filename);
00168 
00169 //! Removes the file \a filename
00170 void remove_file (const std::string &filename);
00171 
00172 /*! \} */
00173 
00174 /*! \defgroup assertgroup Assertions */
00175 /*! \{ */
00176 
00177 //! Throws a Message_error containing \a msg if \a testval is false.
00178 inline void planck_assert (bool testval, const std::string &msg)
00179   {
00180   if (testval) return;
00181   throw Message_error ("Assertion failed: "+msg);
00182   }
00183 //! Throws a Message_error containing \a msg if \a testval is false.
00184 inline void planck_assert (bool testval, const char *msg)
00185   {
00186   if (testval) return;
00187   throw Message_error ("Assertion failed: "+std::string(msg));
00188   }
00189 
00190 //! Checks the presence of the file \a filename.
00191 /*! If the file is not present, a Message_error is thrown. */
00192 void assert_present (const std::string &filename);
00193 
00194 //! Checks the absence of the file \a filename.
00195 /*! If the file is present, a Message_error is thrown. */
00196 void assert_not_present (const std::string &filename);
00197 
00198 /*! \} */
00199 
00200 /*! \defgroup stringutilsgroup String handling helper functions */
00201 /*! \{ */
00202 
00203 //! Returns the string \a orig without leading and trailing whitespace.
00204 std::string trim (const std::string &orig);
00205 
00206 //! Returns a string containing the text representation of \a x.
00207 /*! Care is taken that no information is lost in the conversion. */
00208 template<typename T> std::string dataToString(const T &x);
00209 template<> std::string dataToString (const bool &x);
00210 template<> std::string dataToString (const std::string &x);
00211 template<> std::string dataToString (const float &x);
00212 template<> std::string dataToString (const double &x);
00213 
00214 /*! Returns a string containing the text representation of \a x, padded
00215     with leading zeroes to \a width characters. */
00216 std::string intToString(int x, int width);
00217 
00218 //! Reads a value of a given datatype from a string
00219 template<typename T> void stringToData (const std::string &x, T &value);
00220 template<> void stringToData (const std::string &x, std::string &value);
00221 template<> void stringToData (const std::string &x, bool &value);
00222 
00223 //! Reads a value of a given datatype from a string
00224 template<typename T> inline T stringToData (const std::string &x)
00225   { T result; stringToData(x,result); return result; }
00226 
00227 //! Parses the file \a filename and returns the key/value pairs in \a dict.
00228 void parse_file (const std::string &filename,
00229   std::map<std::string,std::string> &dict);
00230 
00231 //! Case-insensitive string comparison
00232 /*! Returns \a true, if \a a and \a b differ only in capitalisation,
00233     else \a false. */
00234 bool equal_nocase (const std::string &a, const std::string &b);
00235 
00236 //! Returns lowercase version of \a input.
00237 std::string tolower(const std::string &input);
00238 
00239 /*! \} */
00240 
00241 //! Indicates progress by printing the percentage of \a now/total.
00242 /*! A message is only printed if it has changed since \a now-1/total.
00243     The output is followed by a carriage return, not a newline. */
00244 void announce_progress (int now, int total);
00245 //! Indicates progress by printing the percentage of \a now/total.
00246 /*! A message is only printed if it has changed since \a last/total.
00247     The output is followed by a carriage return, not a newline. */
00248 void announce_progress (double now, double last, double total);
00249 /*! This function should be called after a sequence of announce_progress()
00250     calls has finished. */
00251 void end_announce_progress ();
00252 
00253 //! Prints a banner containing \a name. Useful for displaying program names.
00254 void announce (const std::string &name);
00255 
00256 /*! Prints a banner containing \a name and checks if \a argc==argc_expected.
00257     If not, a usage description is given and the program is terminated. */
00258 void module_startup (const std::string &name, int argc, const char **argv,
00259   int argc_expected, const std::string &argv_expected);
00260 
00261 //! Returns an appropriate FITS repetition count for a map with \a npix pixels.
00262 inline unsigned int healpix_repcount (int npix)
00263   {
00264   if (npix<1024) return 1;
00265   if ((npix%1024)==0) return 1024;
00266   return isqrt (npix/12);
00267   }
00268 #endif