00001 /** 00002 * \file Utility.hpp 00003 * \brief Header for GeographicLib::Utility class 00004 * 00005 * Copyright (c) Charles Karney (2011-2012) <charles@karney.com> and licensed 00006 * under the MIT/X11 License. For more information, see 00007 * http://geographiclib.sourceforge.net/ 00008 **********************************************************************/ 00009 00010 #if !defined(GEOGRAPHICLIB_UTILITY_HPP) 00011 #define GEOGRAPHICLIB_UTILITY_HPP 1 00012 00013 #include <GeographicLib/Constants.hpp> 00014 #include <iomanip> 00015 #include <vector> 00016 #include <sstream> 00017 #include <cctype> 00018 00019 #if defined(_MSC_VER) 00020 // Squelch warnings about constant conditional expressions 00021 # pragma warning (push) 00022 # pragma warning (disable: 4127) 00023 #endif 00024 00025 namespace GeographicLib { 00026 00027 /** 00028 * \brief Some utility routines for %GeographicLib 00029 * 00030 * Example of use: 00031 * \include example-Utility.cpp 00032 **********************************************************************/ 00033 class GEOGRAPHICLIB_EXPORT Utility { 00034 private: 00035 static bool gregorian(int y, int m, int d) { 00036 // The original cut over to the Gregorian calendar in Pope Gregory XIII's 00037 // time had 1582-10-04 followed by 1582-10-15. Here we implement the 00038 // switch over used by the English-speaking world where 1752-09-02 was 00039 // followed by 1752-09-14. We also assume that the year always begins 00040 // with January 1, whereas in reality it often was reckoned to begin in 00041 // March. 00042 return 100 * (100 * y + m) + d >= 17520914; // or 15821004 00043 } 00044 static bool gregorian(int s) { 00045 return s >= 639799; // 1752-09-14 00046 } 00047 public: 00048 00049 /** 00050 * Convert a date to the day numbering sequentially starting with 00051 * 0001-01-01 as day 1. 00052 * 00053 * @param[in] y the year (must be positive). 00054 * @param[in] m the month, Jan = 1, etc. (must be positive). Default = 1. 00055 * @param[in] d the day of the month (must be positive). Default = 1. 00056 * @return the sequential day number. 00057 **********************************************************************/ 00058 static int day(int y, int m = 1, int d = 1) { 00059 // Convert from date to sequential day and vice versa 00060 // 00061 // Here is some code to convert a date to sequential day and vice 00062 // versa. The sequential day is numbered so that January 1, 1 AD is day 1 00063 // (a Saturday). So this is offset from the "Julian" day which starts the 00064 // numbering with 4713 BC. 00065 // 00066 // This is inspired by a talk by John Conway at the John von Neumann 00067 // National Supercomputer Center when he described his Doomsday algorithm 00068 // for figuring the day of the week. The code avoids explicitly doing ifs 00069 // (except for the decision of whether to use the Julian or Gregorian 00070 // calendar). Instead the equivalent result is achieved using integer 00071 // arithmetic. I got this idea from the routine for the day of the week 00072 // in MACLisp (I believe that that routine was written by Guy Steele). 00073 // 00074 // There are three issues to take care of 00075 // 00076 // 1. the rules for leap years, 00077 // 2. the inconvenient placement of leap days at the end of February, 00078 // 3. the irregular pattern of month lengths. 00079 // 00080 // We deal with these as follows: 00081 // 00082 // 1. Leap years are given by simple rules which are straightforward to 00083 // accommodate. 00084 // 00085 // 2. We simplify the calculations by moving January and February to the 00086 // previous year. Here we internally number the months March–December, 00087 // January, February as 0–9, 10, 11. 00088 // 00089 // 3. The pattern of month lengths from March through January is regular 00090 // with a 5-month period—31, 30, 31, 30, 31, 31, 30, 31, 30, 31, 31. The 00091 // 5-month period is 153 days long. Since February is now at the end of 00092 // the year, we don't need to include its length in this part of the 00093 // calculation. 00094 bool greg = gregorian(y, m, d); 00095 y += (m + 9) / 12 - 1; // Move Jan and Feb to previous year, 00096 m = (m + 9) % 12; // making March month 0. 00097 return 00098 (1461 * y) / 4 // Julian years converted to days. Julian year is 365 + 00099 // 1/4 = 1461/4 days. 00100 // Gregorian leap year corrections. The 2 offset with respect to the 00101 // Julian calendar synchronizes the vernal equinox with that at the time 00102 // of the Council of Nicea (325 AD). 00103 + (greg ? (y / 100) / 4 - (y / 100) + 2 : 0) 00104 + (153 * m + 2) / 5 // The zero-based start of the m'th month 00105 + d - 1 // The zero-based day 00106 - 305; // The number of days between March 1 and December 31. 00107 // This makes 0001-01-01 day 1 00108 } 00109 00110 /** 00111 * Convert a date to the day numbering sequentially starting with 00112 * 0001-01-01 as day 1. 00113 * 00114 * @param[in] y the year (must be positive). 00115 * @param[in] m the month, Jan = 1, etc. (must be positive). Default = 1. 00116 * @param[in] d the day of the month (must be positive). Default = 1. 00117 * @param[in] check whether to check the date. 00118 * @exception GeographicErr if the date is invalid and \e check is true. 00119 * @return the sequential day number. 00120 **********************************************************************/ 00121 static int day(int y, int m, int d, bool check) { 00122 int s = day(y, m, d); 00123 if (!check) 00124 return s; 00125 int y1, m1, d1; 00126 date(s, y1, m1, d1); 00127 if (!(s > 0 && y == y1 && m == m1 && d == d1)) 00128 throw GeographicErr("Invalid date " + 00129 str(y) + "-" + str(m) + "-" + str(d) 00130 + (s > 0 ? "; use " + 00131 str(y1) + "-" + str(m1) + "-" + str(d1) : 00132 " before 0001-01-01")); 00133 return s; 00134 } 00135 00136 /** 00137 * Given a day (counting from 0001-01-01 as day 1), return the date. 00138 * 00139 * @param[in] s the sequential day number (must be positive) 00140 * @param[out] y the year. 00141 * @param[out] m the month, Jan = 1, etc. 00142 * @param[out] d the day of the month. 00143 **********************************************************************/ 00144 static void date(int s, int& y, int& m, int& d) { 00145 int c = 0; 00146 bool greg = gregorian(s); 00147 s += 305; // s = 0 on March 1, 1BC 00148 if (greg) { 00149 s -= 2; // The 2 day Gregorian offset 00150 // Determine century with the Gregorian rules for leap years. The 00151 // Gregorian year is 365 + 1/4 - 1/100 + 1/400 = 146097/400 days. 00152 c = (4 * s + 3) / 146097; 00153 s -= (c * 146097) / 4; // s = 0 at beginning of century 00154 } 00155 y = (4 * s + 3) / 1461; // Determine the year using Julian rules. 00156 s -= (1461 * y) / 4; // s = 0 at start of year, i.e., March 1 00157 y += c * 100; // Assemble full year 00158 m = (5 * s + 2) / 153; // Determine the month 00159 s -= (153 * m + 2) / 5; // s = 0 at beginning of month 00160 d = s + 1; // Determine day of month 00161 y += (m + 2) / 12; // Move Jan and Feb back to original year 00162 m = (m + 2) % 12 + 1; // Renumber the months so January = 1 00163 } 00164 00165 /** 00166 * Given a date as a string in the format yyyy, yyyy-mm, or yyyy-mm-dd, 00167 * return the numeric values for the year, month, and day. No checking is 00168 * done on these values. 00169 * 00170 * @param[in] s the date in string format. 00171 * @param[out] y the year. 00172 * @param[out] m the month, Jan = 1, etc. 00173 * @param[out] d the day of the month. 00174 * @exception GeographicErr is \e s is malformed. 00175 **********************************************************************/ 00176 static void date(const std::string& s, int& y, int& m, int& d) { 00177 int y1, m1 = 1, d1 = 1; 00178 const char* digits = "0123456789"; 00179 std::string::size_type p1 = s.find_first_not_of(digits); 00180 if (p1 == std::string::npos) 00181 y1 = num<int>(s); 00182 else if (s[p1] != '-') 00183 throw GeographicErr("Delimiter not hyphen in date " + s); 00184 else if (p1 == 0) 00185 throw GeographicErr("Empty year field in date " + s); 00186 else { 00187 y1 = num<int>(s.substr(0, p1)); 00188 if (++p1 == s.size()) 00189 throw GeographicErr("Empty month field in date " + s); 00190 std::string::size_type p2 = s.find_first_not_of(digits, p1); 00191 if (p2 == std::string::npos) 00192 m1 = num<int>(s.substr(p1)); 00193 else if (s[p2] != '-') 00194 throw GeographicErr("Delimiter not hyphen in date " + s); 00195 else if (p2 == p1) 00196 throw GeographicErr("Empty month field in date " + s); 00197 else { 00198 m1 = num<int>(s.substr(p1, p2 - p1)); 00199 if (++p2 == s.size()) 00200 throw GeographicErr("Empty day field in date " + s); 00201 d1 = num<int>(s.substr(p2)); 00202 } 00203 } 00204 y = y1; m = m1; d = d1; 00205 } 00206 00207 /** 00208 * Given the date, return the day of the week. 00209 * 00210 * @param[in] y the year (must be positive). 00211 * @param[in] m the month, Jan = 1, etc. (must be positive). 00212 * @param[in] d the day of the month (must be positive). 00213 * @return the day of the week with Sunday, Monday--Saturday = 0, 00214 * 1--6. 00215 **********************************************************************/ 00216 static int dow(int y, int m, int d) { return dow(day(y, m, d)); } 00217 00218 /** 00219 * Given the sequential day, return the day of the week. 00220 * 00221 * @param[in] s the sequential day (must be positive). 00222 * @return the day of the week with Sunday, Monday--Saturday = 0, 00223 * 1--6. 00224 **********************************************************************/ 00225 static int dow(int s) { 00226 return (s + 5) % 7; // The 5 offset makes day 1 (0001-01-01) a Saturday. 00227 } 00228 00229 /** 00230 * Convert a string representing a date to a fractional year. 00231 * 00232 * @tparam T the type of the argument. 00233 * @param[in] s the string to be converted. 00234 * @exception GeographicErr if \e s can't be interpreted as a date. 00235 * @return the fractional year. 00236 * 00237 * The string is first read as an ordinary number (e.g., 2010 or 2012.5); 00238 * if this is successful, the value is returned. Otherwise the string 00239 * should be of the form yyyy-mm or yyyy-mm-dd and this is converted to a 00240 * number with 2010-01-01 giving 2010.0 and 2012-07-03 giving 2012.5. 00241 **********************************************************************/ 00242 template<typename T> static T fractionalyear(const std::string& s) { 00243 try { 00244 return num<T>(s); 00245 } 00246 catch (const std::exception&) { 00247 } 00248 int y, m, d; 00249 date(s, y, m, d); 00250 int t = day(y, m, d, true); 00251 return T(y) + T(t - day(y)) / T(day(y + 1) - day(y)); 00252 } 00253 00254 /** 00255 * Convert a object of type T to a string. 00256 * 00257 * @tparam T the type of the argument. 00258 * @param[in] x the value to be converted. 00259 * @param[in] p the precision used (default −1). 00260 * @exception std::bad_alloc if memory for the string can't be allocated. 00261 * @return the string representation. 00262 * 00263 * If \e p ≥ 0, then the number fixed format is used with p bits of 00264 * precision. With p < 0, there is no manipulation of the format. 00265 **********************************************************************/ 00266 template<typename T> static std::string str(T x, int p = -1) { 00267 std::ostringstream s; 00268 if (p >= 0) s << std::fixed << std::setprecision(p); 00269 s << x; return s.str(); 00270 } 00271 00272 /** 00273 * Convert a Math::real object to a string. 00274 * 00275 * @param[in] x the value to be converted. 00276 * @param[in] p the precision used (default −1). 00277 * @exception std::bad_alloc if memory for the string can't be allocated. 00278 * @return the string representation. 00279 * 00280 * If \e p ≥ 0, then the number fixed format is used with p bits of 00281 * precision. With p < 0, there is no manipulation of the format. This is 00282 * an overload of str<T> which deals with inf and nan. 00283 **********************************************************************/ 00284 static std::string str(Math::real x, int p = -1) { 00285 if (!Math::isfinite(x)) 00286 return x < 0 ? std::string("-inf") : 00287 (x > 0 ? std::string("inf") : std::string("nan")); 00288 std::ostringstream s; 00289 if (p >= 0) s << std::fixed << std::setprecision(p); 00290 s << x; return s.str(); 00291 } 00292 00293 /** 00294 * Convert a string to an object of type T. 00295 * 00296 * @tparam T the type of the return value. 00297 * @param[in] s the string to be converted. 00298 * @exception GeographicErr is \e s is not readable as a T. 00299 * @return object of type T 00300 **********************************************************************/ 00301 template<typename T> static T num(const std::string& s) { 00302 T x; 00303 std::string errmsg; 00304 do { // Executed once (provides the ability to break) 00305 std::istringstream is(s); 00306 if (!(is >> x)) { 00307 errmsg = "Cannot decode " + s; 00308 break; 00309 } 00310 int pos = int(is.tellg()); // Returns -1 at end of string? 00311 if (!(pos < 0 || pos == int(s.size()))) { 00312 errmsg = "Extra text " + s.substr(pos) + " at end of " + s; 00313 break; 00314 } 00315 return x; 00316 } while (false); 00317 x = std::numeric_limits<T>::is_integer ? 0 : nummatch<T>(s); 00318 if (x == 0) 00319 throw GeographicErr(errmsg); 00320 return x; 00321 } 00322 00323 /** 00324 * Match "nan" and "inf" (and variants thereof) in a string. 00325 * 00326 * @tparam T the type of the return value. 00327 * @param[in] s the string to be matched. 00328 * @return appropriate special value (±∞, nan) or 0 if none is 00329 * found. 00330 **********************************************************************/ 00331 template<typename T> static T nummatch(const std::string& s) { 00332 if (s.length() < 3) 00333 return 0; 00334 std::string t; 00335 t.resize(s.length()); 00336 std::transform(s.begin(), s.end(), t.begin(), (int(*)(int))std::toupper); 00337 for (size_t i = s.length(); i--;) 00338 t[i] = char(std::toupper(s[i])); 00339 int sign = t[0] == '-' ? -1 : 1; 00340 std::string::size_type p0 = t[0] == '-' || t[0] == '+' ? 1 : 0; 00341 std::string::size_type p1 = t.find_last_not_of('0'); 00342 if (p1 == std::string::npos || p1 + 1 < p0 + 3) 00343 return 0; 00344 // Strip off sign and trailing 0s 00345 t = t.substr(p0, p1 + 1 - p0); // Length at least 3 00346 if (t == "NAN" || t == "1.#QNAN" || t == "1.#SNAN" || t == "1.#IND" || 00347 t == "1.#R") 00348 return Math::NaN<T>(); 00349 else if (t == "INF" || t == "1.#INF") 00350 return sign * Math::infinity<T>(); 00351 return 0; 00352 } 00353 00354 /** 00355 * Read a simple fraction, e.g., 3/4, from a string to an object of type T. 00356 * 00357 * @tparam T the type of the return value. 00358 * @param[in] s the string to be converted. 00359 * @exception GeographicErr is \e s is not readable as a fraction of type T. 00360 * @return object of type T 00361 **********************************************************************/ 00362 template<typename T> static T fract(const std::string& s) { 00363 std::string::size_type delim = s.find('/'); 00364 return 00365 !(delim != std::string::npos && delim >= 1 && delim + 2 <= s.size()) ? 00366 num<T>(s) : 00367 // delim in [1, size() - 2] 00368 num<T>(s.substr(0, delim)) / num<T>(s.substr(delim + 1)); 00369 } 00370 00371 /** 00372 * Lookup up a character in a string. 00373 * 00374 * @param[in] s the string to be searched. 00375 * @param[in] c the character to look for. 00376 * @return the index of the first occurrence character in the string or 00377 * −1 is the character is not present. 00378 * 00379 * \e c is converted to upper case before search \e s. Therefore, it is 00380 * intended that \e s should not contain any lower case letters. 00381 **********************************************************************/ 00382 static int lookup(const std::string& s, char c) { 00383 std::string::size_type r = s.find(char(toupper(c))); 00384 return r == std::string::npos ? -1 : int(r); 00385 } 00386 00387 /** 00388 * Read data of type ExtT from a binary stream to an array of type IntT. 00389 * The data in the file is in (bigendp ? big : little)-endian format. 00390 * 00391 * @tparam ExtT the type of the objects in the binary stream (external). 00392 * @tparam IntT the type of the objects in the array (internal). 00393 * @tparam bigendp true if the external storage format is big-endian. 00394 * @param[in] str the input stream containing the data of type ExtT 00395 * (external). 00396 * @param[out] array the output array of type IntT (internal). 00397 * @param[in] num the size of the array. 00398 * @exception GeographicErr if the data cannot be read. 00399 **********************************************************************/ 00400 template<typename ExtT, typename IntT, bool bigendp> 00401 static inline void readarray(std::istream& str, 00402 IntT array[], size_t num) { 00403 #if GEOGRAPHICLIB_PRECISION < 4 00404 if (sizeof(IntT) == sizeof(ExtT) && 00405 std::numeric_limits<IntT>::is_integer == 00406 std::numeric_limits<ExtT>::is_integer) 00407 { 00408 // Data is compatible (aside from the issue of endian-ness). 00409 str.read(reinterpret_cast<char *>(array), num * sizeof(ExtT)); 00410 if (!str.good()) 00411 throw GeographicErr("Failure reading data"); 00412 if (bigendp != Math::bigendian) { // endian mismatch -> swap bytes 00413 for (size_t i = num; i--;) 00414 array[i] = Math::swab<IntT>(array[i]); 00415 } 00416 } 00417 else 00418 #endif 00419 { 00420 const int bufsize = 1024; // read this many values at a time 00421 ExtT buffer[bufsize]; // temporary buffer 00422 int k = int(num); // data values left to read 00423 int i = 0; // index into output array 00424 while (k) { 00425 int n = (std::min)(k, bufsize); 00426 str.read(reinterpret_cast<char *>(buffer), n * sizeof(ExtT)); 00427 if (!str.good()) 00428 throw GeographicErr("Failure reading data"); 00429 for (int j = 0; j < n; ++j) 00430 // fix endian-ness and cast to IntT 00431 array[i++] = IntT(bigendp == Math::bigendian ? buffer[j] : 00432 Math::swab<ExtT>(buffer[j])); 00433 k -= n; 00434 } 00435 } 00436 return; 00437 } 00438 00439 /** 00440 * Read data of type ExtT from a binary stream to a vector array of type 00441 * IntT. The data in the file is in (bigendp ? big : little)-endian 00442 * format. 00443 * 00444 * @tparam ExtT the type of the objects in the binary stream (external). 00445 * @tparam IntT the type of the objects in the array (internal). 00446 * @tparam bigendp true if the external storage format is big-endian. 00447 * @param[in] str the input stream containing the data of type ExtT 00448 * (external). 00449 * @param[out] array the output vector of type IntT (internal). 00450 * @exception GeographicErr if the data cannot be read. 00451 **********************************************************************/ 00452 template<typename ExtT, typename IntT, bool bigendp> 00453 static inline void readarray(std::istream& str, 00454 std::vector<IntT>& array) { 00455 readarray<ExtT, IntT, bigendp>(str, &array[0], array.size()); 00456 } 00457 00458 /** 00459 * Write data in an array of type IntT as type ExtT to a binary stream. 00460 * The data in the file is in (bigendp ? big : little)-endian format. 00461 * 00462 * @tparam ExtT the type of the objects in the binary stream (external). 00463 * @tparam IntT the type of the objects in the array (internal). 00464 * @tparam bigendp true if the external storage format is big-endian. 00465 * @param[out] str the output stream for the data of type ExtT (external). 00466 * @param[in] array the input array of type IntT (internal). 00467 * @param[in] num the size of the array. 00468 * @exception GeographicErr if the data cannot be written. 00469 **********************************************************************/ 00470 template<typename ExtT, typename IntT, bool bigendp> 00471 static inline void writearray(std::ostream& str, 00472 const IntT array[], size_t num) { 00473 #if GEOGRAPHICLIB_PRECISION < 4 00474 if (sizeof(IntT) == sizeof(ExtT) && 00475 std::numeric_limits<IntT>::is_integer == 00476 std::numeric_limits<ExtT>::is_integer && 00477 bigendp == Math::bigendian) 00478 { 00479 // Data is compatible (including endian-ness). 00480 str.write(reinterpret_cast<const char *>(array), num * sizeof(ExtT)); 00481 if (!str.good()) 00482 throw GeographicErr("Failure writing data"); 00483 } 00484 else 00485 #endif 00486 { 00487 const int bufsize = 1024; // write this many values at a time 00488 ExtT buffer[bufsize]; // temporary buffer 00489 int k = int(num); // data values left to write 00490 int i = 0; // index into output array 00491 while (k) { 00492 int n = (std::min)(k, bufsize); 00493 for (int j = 0; j < n; ++j) 00494 // cast to ExtT and fix endian-ness 00495 buffer[j] = bigendp == Math::bigendian ? ExtT(array[i++]) : 00496 Math::swab<ExtT>(ExtT(array[i++])); 00497 str.write(reinterpret_cast<const char *>(buffer), n * sizeof(ExtT)); 00498 if (!str.good()) 00499 throw GeographicErr("Failure writing data"); 00500 k -= n; 00501 } 00502 } 00503 return; 00504 } 00505 00506 /** 00507 * Write data in an array of type IntT as type ExtT to a binary stream. 00508 * The data in the file is in (bigendp ? big : little)-endian format. 00509 * 00510 * @tparam ExtT the type of the objects in the binary stream (external). 00511 * @tparam IntT the type of the objects in the array (internal). 00512 * @tparam bigendp true if the external storage format is big-endian. 00513 * @param[out] str the output stream for the data of type ExtT (external). 00514 * @param[in] array the input vector of type IntT (internal). 00515 * @exception GeographicErr if the data cannot be written. 00516 **********************************************************************/ 00517 template<typename ExtT, typename IntT, bool bigendp> 00518 static inline void writearray(std::ostream& str, 00519 std::vector<IntT>& array) { 00520 writearray<ExtT, IntT, bigendp>(str, &array[0], array.size()); 00521 } 00522 00523 /** 00524 * Parse a KEY VALUE line. 00525 * 00526 * @param[in] line the input line. 00527 * @param[out] key the key. 00528 * @param[out] val the value. 00529 * @exception std::bad_alloc if memory for the internal strings can't be 00530 * allocated. 00531 * @return whether a key was found. 00532 * 00533 * A # character and everything after it are discarded. If the result is 00534 * just white space, the routine returns false (and \e key and \e val are 00535 * not set). Otherwise the first token is taken to be the key and the rest 00536 * of the line (trimmed of leading and trailing white space) is the value. 00537 **********************************************************************/ 00538 static bool ParseLine(const std::string& line, 00539 std::string& key, std::string& val); 00540 00541 /** 00542 * Set the binary precision of a real number. 00543 * 00544 * @param[in] ndigits the number of bits of precision. If ndigits is 0 00545 * (the default), then determine the precision from the environment 00546 * variable GEOGRAPHICLIB_DIGITS. If this is undefined, use ndigits = 00547 * 256 (i.e., about 77 decimal digits). 00548 * @return the resulting number of bits of precision. 00549 * 00550 * This only has an effect when GEOGRAPHICLIB_PRECISION == 5. 00551 **********************************************************************/ 00552 static int set_digits(int ndigits = 0); 00553 00554 }; 00555 00556 } // namespace GeographicLib 00557 00558 #if defined(_MSC_VER) 00559 # pragma warning (pop) 00560 #endif 00561 00562 #endif // GEOGRAPHICLIB_UTILITY_HPP