GeographicLib  1.35
Utility.hpp
Go to the documentation of this file.
1 /**
2  * \file Utility.hpp
3  * \brief Header for GeographicLib::Utility class
4  *
5  * Copyright (c) Charles Karney (2011-2012) <charles@karney.com> and licensed
6  * under the MIT/X11 License. For more information, see
7  * http://geographiclib.sourceforge.net/
8  **********************************************************************/
9 
10 #if !defined(GEOGRAPHICLIB_UTILITY_HPP)
11 #define GEOGRAPHICLIB_UTILITY_HPP 1
12 
14 #include <iomanip>
15 #include <vector>
16 #include <sstream>
17 #include <cctype>
18 
19 #if defined(_MSC_VER)
20 // Squelch warnings about constant conditional expressions
21 # pragma warning (push)
22 # pragma warning (disable: 4127)
23 #endif
24 
25 namespace GeographicLib {
26 
27  /**
28  * \brief Some utility routines for %GeographicLib
29  *
30  * Example of use:
31  * \include example-Utility.cpp
32  **********************************************************************/
34  private:
35  static bool gregorian(int y, int m, int d) {
36  // The original cut over to the Gregorian calendar in Pope Gregory XIII's
37  // time had 1582-10-04 followed by 1582-10-15. Here we implement the
38  // switch over used by the English-speaking world where 1752-09-02 was
39  // followed by 1752-09-14. We also assume that the year always begins
40  // with January 1, whereas in reality it often was reckoned to begin in
41  // March.
42  return 100 * (100 * y + m) + d >= 17520914; // or 15821004
43  }
44  static bool gregorian(int s) {
45  return s >= 639799; // 1752-09-14
46  }
47  public:
48 
49  /**
50  * Convert a date to the day numbering sequentially starting with
51  * 0001-01-01 as day 1.
52  *
53  * @param[in] y the year (must be positive).
54  * @param[in] m the month, Jan = 1, etc. (must be positive). Default = 1.
55  * @param[in] d the day of the month (must be positive). Default = 1.
56  * @return the sequential day number.
57  **********************************************************************/
58  static int day(int y, int m = 1, int d = 1) throw() {
59  // Convert from date to sequential day and vice versa
60  //
61  // Here is some code to convert a date to sequential day and vice
62  // versa. The sequential day is numbered so that January 1, 1 AD is day 1
63  // (a Saturday). So this is offset from the "Julian" day which starts the
64  // numbering with 4713 BC.
65  //
66  // This is inspired by a talk by John Conway at the John von Neumann
67  // National Supercomputer Center when he described his Doomsday algorithm
68  // for figuring the day of the week. The code avoids explicitly doing ifs
69  // (except for the decision of whether to use the Julian or Gregorian
70  // calendar). Instead the equivalent result is achieved using integer
71  // arithmetic. I got this idea from the routine for the day of the week
72  // in MACLisp (I believe that that routine was written by Guy Steele).
73  //
74  // There are three issues to take care of
75  //
76  // 1. the rules for leap years,
77  // 2. the inconvenient placement of leap days at the end of February,
78  // 3. the irregular pattern of month lengths.
79  //
80  // We deal with these as follows:
81  //
82  // 1. Leap years are given by simple rules which are straightforward to
83  // accommodate.
84  //
85  // 2. We simplify the calculations by moving January and February to the
86  // previous year. Here we internally number the months March–December,
87  // January, February as 0–9, 10, 11.
88  //
89  // 3. The pattern of month lengths from March through January is regular
90  // with a 5-month period—31, 30, 31, 30, 31, 31, 30, 31, 30, 31, 31. The
91  // 5-month period is 153 days long. Since February is now at the end of
92  // the year, we don't need to include its length in this part of the
93  // calculation.
94  bool greg = gregorian(y, m, d);
95  y += (m + 9) / 12 - 1; // Move Jan and Feb to previous year,
96  m = (m + 9) % 12; // making March month 0.
97  return
98  (1461 * y) / 4 // Julian years converted to days. Julian year is 365 +
99  // 1/4 = 1461/4 days.
100  // Gregorian leap year corrections. The 2 offset with respect to the
101  // Julian calendar synchronizes the vernal equinox with that at the time
102  // of the Council of Nicea (325 AD).
103  + (greg ? (y / 100) / 4 - (y / 100) + 2 : 0)
104  + (153 * m + 2) / 5 // The zero-based start of the m'th month
105  + d - 1 // The zero-based day
106  - 305; // The number of days between March 1 and December 31.
107  // This makes 0001-01-01 day 1
108  }
109 
110  /**
111  * Convert a date to the day numbering sequentially starting with
112  * 0001-01-01 as day 1.
113  *
114  * @param[in] y the year (must be positive).
115  * @param[in] m the month, Jan = 1, etc. (must be positive). Default = 1.
116  * @param[in] d the day of the month (must be positive). Default = 1.
117  * @param[in] check whether to check the date.
118  * @exception GeographicErr if the date is invalid and \e check is true.
119  * @return the sequential day number.
120  **********************************************************************/
121  static int day(int y, int m, int d, bool check) {
122  int s = day(y, m, d);
123  if (!check)
124  return s;
125  int y1, m1, d1;
126  date(s, y1, m1, d1);
127  if (!(s > 0 && y == y1 && m == m1 && d == d1))
128  throw GeographicErr("Invalid date " +
129  str(y) + "-" + str(m) + "-" + str(d)
130  + (s > 0 ? "; use " +
131  str(y1) + "-" + str(m1) + "-" + str(d1) :
132  " before 0001-01-01"));
133  return s;
134  }
135 
136  /**
137  * Given a day (counting from 0001-01-01 as day 1), return the date.
138  *
139  * @param[in] s the sequential day number (must be positive)
140  * @param[out] y the year.
141  * @param[out] m the month, Jan = 1, etc.
142  * @param[out] d the day of the month.
143  **********************************************************************/
144  static void date(int s, int& y, int& m, int& d) throw() {
145  int c = 0;
146  bool greg = gregorian(s);
147  s += 305; // s = 0 on March 1, 1BC
148  if (greg) {
149  s -= 2; // The 2 day Gregorian offset
150  // Determine century with the Gregorian rules for leap years. The
151  // Gregorian year is 365 + 1/4 - 1/100 + 1/400 = 146097/400 days.
152  c = (4 * s + 3) / 146097;
153  s -= (c * 146097) / 4; // s = 0 at beginning of century
154  }
155  y = (4 * s + 3) / 1461; // Determine the year using Julian rules.
156  s -= (1461 * y) / 4; // s = 0 at start of year, i.e., March 1
157  y += c * 100; // Assemble full year
158  m = (5 * s + 2) / 153; // Determine the month
159  s -= (153 * m + 2) / 5; // s = 0 at beginning of month
160  d = s + 1; // Determine day of month
161  y += (m + 2) / 12; // Move Jan and Feb back to original year
162  m = (m + 2) % 12 + 1; // Renumber the months so January = 1
163  }
164 
165  /**
166  * Given a date as a string in the format yyyy, yyyy-mm, or yyyy-mm-dd,
167  * return the numeric values for the year, month, and day. No checking is
168  * done on these values.
169  *
170  * @param[in] s the date in string format.
171  * @param[out] y the year.
172  * @param[out] m the month, Jan = 1, etc.
173  * @param[out] d the day of the month.
174  * @exception GeographicErr is \e s is malformed.
175  **********************************************************************/
176  static void date(const std::string& s, int& y, int& m, int& d) {
177  int y1, m1 = 1, d1 = 1;
178  const char* digits = "0123456789";
179  std::string::size_type p1 = s.find_first_not_of(digits);
180  if (p1 == std::string::npos)
181  y1 = num<int>(s);
182  else if (s[p1] != '-')
183  throw GeographicErr("Delimiter not hyphen in date " + s);
184  else if (p1 == 0)
185  throw GeographicErr("Empty year field in date " + s);
186  else {
187  y1 = num<int>(s.substr(0, p1));
188  if (++p1 == s.size())
189  throw GeographicErr("Empty month field in date " + s);
190  std::string::size_type p2 = s.find_first_not_of(digits, p1);
191  if (p2 == std::string::npos)
192  m1 = num<int>(s.substr(p1));
193  else if (s[p2] != '-')
194  throw GeographicErr("Delimiter not hyphen in date " + s);
195  else if (p2 == p1)
196  throw GeographicErr("Empty month field in date " + s);
197  else {
198  m1 = num<int>(s.substr(p1, p2 - p1));
199  if (++p2 == s.size())
200  throw GeographicErr("Empty day field in date " + s);
201  d1 = num<int>(s.substr(p2));
202  }
203  }
204  y = y1; m = m1; d = d1;
205  }
206 
207  /**
208  * Given the date, return the day of the week.
209  *
210  * @param[in] y the year (must be positive).
211  * @param[in] m the month, Jan = 1, etc. (must be positive).
212  * @param[in] d the day of the month (must be positive).
213  * @return the day of the week with Sunday, Monday--Saturday = 0,
214  * 1--6.
215  **********************************************************************/
216  static int dow(int y, int m, int d) throw() { return dow(day(y, m, d)); }
217 
218  /**
219  * Given the sequential day, return the day of the week.
220  *
221  * @param[in] s the sequential day (must be positive).
222  * @return the day of the week with Sunday, Monday--Saturday = 0,
223  * 1--6.
224  **********************************************************************/
225  static int dow(int s) throw() {
226  return (s + 5) % 7; // The 5 offset makes day 1 (0001-01-01) a Saturday.
227  }
228 
229  /**
230  * Convert a string representing a date to a fractional year.
231  *
232  * @tparam T the type of the argument.
233  * @param[in] s the string to be converted.
234  * @exception GeographicErr if \e s can't be interpreted as a date.
235  * @return the fractional year.
236  *
237  * The string is first read as an ordinary number (e.g., 2010 or 2012.5);
238  * if this is successful, the value is returned. Otherwise the string
239  * should be of the form yyyy-mm or yyyy-mm-dd and this is converted to a
240  * number with 2010-01-01 giving 2010.0 and 2012-07-03 giving 2012.5.
241  **********************************************************************/
242  template<typename T> static T fractionalyear(const std::string& s) {
243  try {
244  return num<T>(s);
245  }
246  catch (const std::exception&) {
247  }
248  int y, m, d;
249  date(s, y, m, d);
250  int t = day(y, m, d, true);
251  return T(y) + T(t - day(y)) / T(day(y + 1) - day(y));
252  }
253 
254  /**
255  * Convert a object of type T to a string.
256  *
257  * @tparam T the type of the argument.
258  * @param[in] x the value to be converted.
259  * @param[in] p the precision used (default &minus;1).
260  * @exception std::bad_alloc if memory for the string can't be allocated.
261  * @return the string representation.
262  *
263  * If \e p &ge; 0, then the number fixed format is used with p bits of
264  * precision. With p < 0, there is no manipulation of the format.
265  **********************************************************************/
266  template<typename T> static std::string str(T x, int p = -1) {
267  if (!std::numeric_limits<T>::is_integer && !Math::isfinite<T>(x))
268  return x < 0 ? std::string("-inf") :
269  (x > 0 ? std::string("inf") : std::string("nan"));
270  std::ostringstream s;
271  if (p >= 0) s << std::fixed << std::setprecision(p);
272  s << x; return s.str();
273  }
274 
275  /**
276  * Convert a string to an object of type T.
277  *
278  * @tparam T the type of the return value.
279  * @param[in] s the string to be converted.
280  * @exception GeographicErr is \e s is not readable as a T.
281  * @return object of type T
282  **********************************************************************/
283  template<typename T> static T num(const std::string& s) {
284  T x;
285  std::string errmsg;
286  do { // Executed once (provides the ability to break)
287  std::istringstream is(s);
288  if (!(is >> x)) {
289  errmsg = "Cannot decode " + s;
290  break;
291  }
292  int pos = int(is.tellg()); // Returns -1 at end of string?
293  if (!(pos < 0 || pos == int(s.size()))) {
294  errmsg = "Extra text " + s.substr(pos) + " at end of " + s;
295  break;
296  }
297  return x;
298  } while (false);
299  x = std::numeric_limits<T>::is_integer ? 0 : nummatch<T>(s);
300  if (x == 0)
301  throw GeographicErr(errmsg);
302  return x;
303  }
304 
305  /**
306  * Match "nan" and "inf" (and variants thereof) in a string.
307  *
308  * @tparam T the type of the return value.
309  * @param[in] s the string to be matched.
310  * @return appropriate special value (&plusmn;&infin;, nan) or 0 if none is
311  * found.
312  **********************************************************************/
313  template<typename T> static T nummatch(const std::string& s) {
314  if (s.length() < 3)
315  return 0;
316  std::string t;
317  t.resize(s.length());
318  std::transform(s.begin(), s.end(), t.begin(), (int(*)(int))std::toupper);
319  for (size_t i = s.length(); i--;)
320  t[i] = char(std::toupper(s[i]));
321  int sign = t[0] == '-' ? -1 : 1;
322  std::string::size_type p0 = t[0] == '-' || t[0] == '+' ? 1 : 0;
323  std::string::size_type p1 = t.find_last_not_of('0');
324  if (p1 == std::string::npos || p1 + 1 < p0 + 3)
325  return 0;
326  // Strip off sign and trailing 0s
327  t = t.substr(p0, p1 + 1 - p0); // Length at least 3
328  if (t == "NAN" || t == "1.#QNAN" || t == "1.#SNAN" || t == "1.#IND" ||
329  t == "1.#R")
330  return Math::NaN<T>();
331  else if (t == "INF" || t == "1.#INF")
332  return sign * Math::infinity<T>();
333  return 0;
334  }
335 
336  /**
337  * Read a simple fraction, e.g., 3/4, from a string to an object of type T.
338  *
339  * @tparam T the type of the return value.
340  * @param[in] s the string to be converted.
341  * @exception GeographicErr is \e s is not readable as a fraction of type T.
342  * @return object of type T
343  **********************************************************************/
344  template<typename T> static T fract(const std::string& s) {
345  std::string::size_type delim = s.find('/');
346  return
347  !(delim != std::string::npos && delim >= 1 && delim + 2 <= s.size()) ?
348  num<T>(s) :
349  // delim in [1, size() - 2]
350  num<T>(s.substr(0, delim)) / num<T>(s.substr(delim + 1));
351  }
352 
353  /**
354  * Lookup up a character in a string.
355  *
356  * @param[in] s the string to be searched.
357  * @param[in] c the character to look for.
358  * @return the index of the first occurrence character in the string or
359  * &minus;1 is the character is not present.
360  *
361  * \e c is converted to upper case before search \e s. Therefore, it is
362  * intended that \e s should not contain any lower case letters.
363  **********************************************************************/
364  static int lookup(const std::string& s, char c) throw() {
365  std::string::size_type r = s.find(char(toupper(c)));
366  return r == std::string::npos ? -1 : int(r);
367  }
368 
369  /**
370  * Read data of type ExtT from a binary stream to an array of type IntT.
371  * The data in the file is in (bigendp ? big : little)-endian format.
372  *
373  * @tparam ExtT the type of the objects in the binary stream (external).
374  * @tparam IntT the type of the objects in the array (internal).
375  * @tparam bigendp true if the external storage format is big-endian.
376  * @param[in] str the input stream containing the data of type ExtT
377  * (external).
378  * @param[out] array the output array of type IntT (internal).
379  * @param[in] num the size of the array.
380  * @exception GeographicErr if the data cannot be read.
381  **********************************************************************/
382  template<typename ExtT, typename IntT, bool bigendp>
383  static inline void readarray(std::istream& str,
384  IntT array[], size_t num) {
385  if (sizeof(IntT) == sizeof(ExtT) &&
386  std::numeric_limits<IntT>::is_integer ==
387  std::numeric_limits<ExtT>::is_integer) {
388  // Data is compatible (aside from the issue of endian-ness).
389  str.read(reinterpret_cast<char *>(array), num * sizeof(ExtT));
390  if (!str.good())
391  throw GeographicErr("Failure reading data");
392  if (bigendp != Math::bigendian) { // endian mismatch -> swap bytes
393  for (size_t i = num; i--;)
394  array[i] = Math::swab<IntT>(array[i]);
395  }
396  } else {
397  const int bufsize = 1024; // read this many values at a time
398  ExtT buffer[bufsize]; // temporary buffer
399  int k = int(num); // data values left to read
400  int i = 0; // index into output array
401  while (k) {
402  int n = (std::min)(k, bufsize);
403  str.read(reinterpret_cast<char *>(buffer), n * sizeof(ExtT));
404  if (!str.good())
405  throw GeographicErr("Failure reading data");
406  for (int j = 0; j < n; ++j)
407  // fix endian-ness and cast to IntT
408  array[i++] = IntT(bigendp == Math::bigendian ? buffer[j] :
409  Math::swab<ExtT>(buffer[j]));
410  k -= n;
411  }
412  }
413  return;
414  }
415 
416  /**
417  * Read data of type ExtT from a binary stream to a vector array of type
418  * IntT. The data in the file is in (bigendp ? big : little)-endian
419  * format.
420  *
421  * @tparam ExtT the type of the objects in the binary stream (external).
422  * @tparam IntT the type of the objects in the array (internal).
423  * @tparam bigendp true if the external storage format is big-endian.
424  * @param[in] str the input stream containing the data of type ExtT
425  * (external).
426  * @param[out] array the output vector of type IntT (internal).
427  * @exception GeographicErr if the data cannot be read.
428  **********************************************************************/
429  template<typename ExtT, typename IntT, bool bigendp>
430  static inline void readarray(std::istream& str,
431  std::vector<IntT>& array) {
432  readarray<ExtT, IntT, bigendp>(str, &array[0], array.size());
433  }
434 
435  /**
436  * Write data in an array of type IntT as type ExtT to a binary stream.
437  * The data in the file is in (bigendp ? big : little)-endian format.
438  *
439  * @tparam ExtT the type of the objects in the binary stream (external).
440  * @tparam IntT the type of the objects in the array (internal).
441  * @tparam bigendp true if the external storage format is big-endian.
442  * @param[out] str the output stream for the data of type ExtT (external).
443  * @param[in] array the input array of type IntT (internal).
444  * @param[in] num the size of the array.
445  * @exception GeographicErr if the data cannot be written.
446  **********************************************************************/
447  template<typename ExtT, typename IntT, bool bigendp>
448  static inline void writearray(std::ostream& str,
449  const IntT array[], size_t num) {
450  if (sizeof(IntT) == sizeof(ExtT) &&
451  std::numeric_limits<IntT>::is_integer ==
452  std::numeric_limits<ExtT>::is_integer &&
453  bigendp == Math::bigendian) {
454  // Data is compatible (including endian-ness).
455  str.write(reinterpret_cast<const char *>(array), num * sizeof(ExtT));
456  if (!str.good())
457  throw GeographicErr("Failure writing data");
458  } else {
459  const int bufsize = 1024; // write this many values at a time
460  ExtT buffer[bufsize]; // temporary buffer
461  int k = int(num); // data values left to write
462  int i = 0; // index into output array
463  while (k) {
464  int n = (std::min)(k, bufsize);
465  for (int j = 0; j < n; ++j)
466  // cast to ExtT and fix endian-ness
467  buffer[j] = bigendp == Math::bigendian ? ExtT(array[i++]) :
468  Math::swab<ExtT>(ExtT(array[i++]));
469  str.write(reinterpret_cast<const char *>(buffer), n * sizeof(ExtT));
470  if (!str.good())
471  throw GeographicErr("Failure writing data");
472  k -= n;
473  }
474  }
475  return;
476  }
477 
478  /**
479  * Write data in an array of type IntT as type ExtT to a binary stream.
480  * The data in the file is in (bigendp ? big : little)-endian format.
481  *
482  * @tparam ExtT the type of the objects in the binary stream (external).
483  * @tparam IntT the type of the objects in the array (internal).
484  * @tparam bigendp true if the external storage format is big-endian.
485  * @param[out] str the output stream for the data of type ExtT (external).
486  * @param[in] array the input vector of type IntT (internal).
487  * @exception GeographicErr if the data cannot be written.
488  **********************************************************************/
489  template<typename ExtT, typename IntT, bool bigendp>
490  static inline void writearray(std::ostream& str,
491  std::vector<IntT>& array) {
492  writearray<ExtT, IntT, bigendp>(str, &array[0], array.size());
493  }
494 
495  /**
496  * Parse a KEY VALUE line.
497  *
498  * @param[in] line the input line.
499  * @param[out] key the key.
500  * @param[out] val the value.
501  * @exception std::bad_alloc if memory for the internal strings can't be
502  * allocated.
503  * @return whether a key was found.
504  *
505  * A # character and everything after it are discarded. If the results is
506  * just white space, the routine returns false (and \e key and \e val are
507  * not set). Otherwise the first token is taken to be the key and the rest
508  * of the line (trimmed of leading and trailing white space) is the value.
509  **********************************************************************/
510  static bool ParseLine(const std::string& line,
511  std::string& key, std::string& val);
512 
513  };
514 
515 } // namespace GeographicLib
516 
517 #if defined(_MSC_VER)
518 # pragma warning (pop)
519 #endif
520 
521 #endif // GEOGRAPHICLIB_UTILITY_HPP
static T fract(const std::string &s)
Definition: Utility.hpp:344
static int day(int y, int m, int d, bool check)
Definition: Utility.hpp:121
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:52
static void readarray(std::istream &str, std::vector< IntT > &array)
Definition: Utility.hpp:430
static void readarray(std::istream &str, IntT array[], size_t num)
Definition: Utility.hpp:383
Some utility routines for GeographicLib.
Definition: Utility.hpp:33
static void date(const std::string &s, int &y, int &m, int &d)
Definition: Utility.hpp:176
static T fractionalyear(const std::string &s)
Definition: Utility.hpp:242
static void writearray(std::ostream &str, std::vector< IntT > &array)
Definition: Utility.hpp:490
static T nummatch(const std::string &s)
Definition: Utility.hpp:313
static void writearray(std::ostream &str, const IntT array[], size_t num)
Definition: Utility.hpp:448
static int dow(int s)
Definition: Utility.hpp:225
static void date(int s, int &y, int &m, int &d)
Definition: Utility.hpp:144
static std::string str(T x, int p=-1)
Definition: Utility.hpp:266
static int dow(int y, int m, int d)
Definition: Utility.hpp:216
static const bool bigendian
Definition: Math.hpp:122
static T num(const std::string &s)
Definition: Utility.hpp:283
Exception handling for GeographicLib.
Definition: Constants.hpp:320
Header for GeographicLib::Constants class.
static int lookup(const std::string &s, char c)
Definition: Utility.hpp:364
static int day(int y, int m=1, int d=1)
Definition: Utility.hpp:58