GeographicLib  2.1.2
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-2022) <charles@karney.com> and licensed
6  * under the MIT/X11 License. For more information, see
7  * https://geographiclib.sourceforge.io/
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 #include <ctime>
19 #include <cstring>
20 
21 #if defined(_MSC_VER)
22 // Squelch warnings about constant conditional expressions and unsafe gmtime
23 # pragma warning (push)
24 # pragma warning (disable: 4127 4996)
25 #endif
26 
27 namespace GeographicLib {
28 
29  /**
30  * \brief Some utility routines for %GeographicLib
31  *
32  * Example of use:
33  * \include example-Utility.cpp
34  **********************************************************************/
36  private:
37  static bool gregorian(int y, int m, int d) {
38  // The original cut over to the Gregorian calendar in Pope Gregory XIII's
39  // time had 1582-10-04 followed by 1582-10-15. Here we implement the
40  // switch over used by the English-speaking world where 1752-09-02 was
41  // followed by 1752-09-14. We also assume that the year always begins
42  // with January 1, whereas in reality it often was reckoned to begin in
43  // March.
44  return 100 * (100 * y + m) + d >= 17520914; // or 15821015
45  }
46  static bool gregorian(int s) {
47  return s >= 639799; // 1752-09-14
48  }
49  public:
50 
51  /**
52  * Convert a date to the day numbering sequentially starting with
53  * 0001-01-01 as day 1.
54  *
55  * @param[in] y the year (must be positive).
56  * @param[in] m the month, Jan = 1, etc. (must be positive). Default = 1.
57  * @param[in] d the day of the month (must be positive). Default = 1.
58  * @return the sequential day number.
59  **********************************************************************/
60  static int day(int y, int m = 1, int d = 1);
61 
62  /**
63  * Convert a date to the day numbering sequentially starting with
64  * 0001-01-01 as day 1.
65  *
66  * @param[in] y the year (must be positive).
67  * @param[in] m the month, Jan = 1, etc. (must be positive). Default = 1.
68  * @param[in] d the day of the month (must be positive). Default = 1.
69  * @param[in] check whether to check the date.
70  * @exception GeographicErr if the date is invalid and \e check is true.
71  * @return the sequential day number.
72  **********************************************************************/
73  static int day(int y, int m, int d, bool check);
74 
75  /**
76  * Given a day (counting from 0001-01-01 as day 1), return the date.
77  *
78  * @param[in] s the sequential day number (must be positive)
79  * @param[out] y the year.
80  * @param[out] m the month, Jan = 1, etc.
81  * @param[out] d the day of the month.
82  **********************************************************************/
83  static void date(int s, int& y, int& m, int& d);
84 
85  /**
86  * Given a date as a string in the format yyyy, yyyy-mm, or yyyy-mm-dd,
87  * return the numeric values for the year, month, and day. No checking is
88  * done on these values. The string "now" is interpreted as the present
89  * date (in UTC).
90  *
91  * @param[in] s the date in string format.
92  * @param[out] y the year.
93  * @param[out] m the month, Jan = 1, etc.
94  * @param[out] d the day of the month.
95  * @exception GeographicErr is \e s is malformed.
96  **********************************************************************/
97  static void date(const std::string& s, int& y, int& m, int& d);
98 
99  /**
100  * Given the date, return the day of the week.
101  *
102  * @param[in] y the year (must be positive).
103  * @param[in] m the month, Jan = 1, etc. (must be positive).
104  * @param[in] d the day of the month (must be positive).
105  * @return the day of the week with Sunday, Monday--Saturday = 0,
106  * 1--6.
107  **********************************************************************/
108  static int dow(int y, int m, int d) { return dow(day(y, m, d)); }
109 
110  /**
111  * Given the sequential day, return the day of the week.
112  *
113  * @param[in] s the sequential day (must be positive).
114  * @return the day of the week with Sunday, Monday--Saturday = 0,
115  * 1--6.
116  **********************************************************************/
117  static int dow(int s) {
118  return (s + 5) % 7; // The 5 offset makes day 1 (0001-01-01) a Saturday.
119  }
120 
121  /**
122  * Convert a string representing a date to a fractional year.
123  *
124  * @tparam T the type of the argument.
125  * @param[in] s the string to be converted.
126  * @exception GeographicErr if \e s can't be interpreted as a date.
127  * @return the fractional year.
128  *
129  * The string is first read as an ordinary number (e.g., 2010 or 2012.5);
130  * if this is successful, the value is returned. Otherwise the string
131  * should be of the form yyyy-mm or yyyy-mm-dd and this is converted to a
132  * number with 2010-01-01 giving 2010.0 and 2012-07-03 giving 2012.5. The
133  * string "now" is interpreted as the present date.
134  **********************************************************************/
135  template<typename T> static T fractionalyear(const std::string& s) {
136  try {
137  return val<T>(s);
138  }
139  catch (const std::exception&) {}
140  int y, m, d;
141  date(s, y, m, d);
142  int t = day(y, m, d, true);
143  return T(y) + T(t - day(y)) / T(day(y + 1) - day(y));
144  }
145 
146  /**
147  * Convert a object of type T to a string.
148  *
149  * @tparam T the type of the argument.
150  * @param[in] x the value to be converted.
151  * @param[in] p the precision used (default &minus;1).
152  * @exception std::bad_alloc if memory for the string can't be allocated.
153  * @return the string representation.
154  *
155  * If \e p &ge; 0, then the number fixed format is used with \e p bits of
156  * precision. With \e p < 0, there is no manipulation of the format,
157  * except that <code>boolalpha</code> is used to represent bools as "true"
158  * and "false". There is an overload of this function if T is Math::real;
159  * this deals with inf and nan.
160  **********************************************************************/
161  template<typename T> static std::string str(T x, int p = -1) {
162  std::ostringstream s;
163  if (p >= 0) s << std::fixed << std::setprecision(p);
164  s << std::boolalpha << x; return s.str();
165  }
166 
167  /**
168  * Trim the white space from the beginning and end of a string.
169  *
170  * @param[in] s the string to be trimmed
171  * @return the trimmed string
172  **********************************************************************/
173  static std::string trim(const std::string& s);
174 
175  /**
176  * Lookup up a character in a string.
177  *
178  * @param[in] s the string to be searched.
179  * @param[in] c the character to look for.
180  * @return the index of the first occurrence character in the string or
181  * &minus;1 is the character is not present.
182  *
183  * \e c is converted to upper case before search \e s. Therefore, it is
184  * intended that \e s should not contain any lower case letters.
185  **********************************************************************/
186  static int lookup(const std::string& s, char c);
187 
188  /**
189  * Lookup up a character in a char*.
190  *
191  * @param[in] s the char* string to be searched.
192  * @param[in] c the character to look for.
193  * @return the index of the first occurrence character in the string or
194  * &minus;1 is the character is not present.
195  *
196  * \e c is converted to upper case before search \e s. Therefore, it is
197  * intended that \e s should not contain any lower case letters.
198  **********************************************************************/
199  static int lookup(const char* s, char c);
200 
201  /**
202  * Convert a string to type T.
203  *
204  * @tparam T the type of the return value.
205  * @param[in] s the string to be converted.
206  * @exception GeographicErr is \e s is not readable as a T.
207  * @return object of type T.
208  *
209  * White space at the beginning and end of \e s is ignored.
210  *
211  * Special handling is provided for some types.
212  *
213  * If T is a floating point type, then inf and nan are recognized.
214  *
215  * If T is bool, then \e s should either be string a representing 0 (false)
216  * or 1 (true) or one of the strings
217  * - "false", "f", "nil", "no", "n", "off", or "" meaning false,
218  * - "true", "t", "yes", "y", or "on" meaning true;
219  * .
220  * case is ignored.
221  *
222  * If T is std::string, then \e s is returned (with the white space at the
223  * beginning and end removed).
224  **********************************************************************/
225  template<typename T> static T val(const std::string& s) {
226  // If T is bool, then the specialization val<bool>() defined below is
227  // used.
228  T x;
229  std::string errmsg, t(trim(s));
230  do { // Executed once (provides the ability to break)
231  std::istringstream is(t);
232  if (!(is >> x)) {
233  errmsg = "Cannot decode " + t;
234  break;
235  }
236  int pos = int(is.tellg()); // Returns -1 at end of string?
237  if (!(pos < 0 || pos == int(t.size()))) {
238  errmsg = "Extra text " + t.substr(pos) + " at end of " + t;
239  break;
240  }
241  return x;
242  } while (false);
243  x = std::numeric_limits<T>::is_integer ? 0 : nummatch<T>(t);
244  if (x == 0)
245  throw GeographicErr(errmsg);
246  return x;
247  }
248 
249  /**
250  * Match "nan" and "inf" (and variants thereof) in a string.
251  *
252  * @tparam T the type of the return value (this should be a floating point
253  * type).
254  * @param[in] s the string to be matched.
255  * @return appropriate special value (&plusmn;&infin;, nan) or 0 if none is
256  * found.
257  *
258  * White space is not allowed at the beginning or end of \e s.
259  **********************************************************************/
260  template<typename T> static T nummatch(const std::string& s) {
261  if (s.length() < 3)
262  return 0;
263  std::string t(s);
264  for (std::string::iterator p = t.begin(); p != t.end(); ++p)
265  *p = char(std::toupper(*p));
266  for (size_t i = s.length(); i--;)
267  t[i] = char(std::toupper(s[i]));
268  int sign = t[0] == '-' ? -1 : 1;
269  std::string::size_type p0 = t[0] == '-' || t[0] == '+' ? 1 : 0;
270  std::string::size_type p1 = t.find_last_not_of('0');
271  if (p1 == std::string::npos || p1 + 1 < p0 + 3)
272  return 0;
273  // Strip off sign and trailing 0s
274  t = t.substr(p0, p1 + 1 - p0); // Length at least 3
275  if (t == "NAN" || t == "1.#QNAN" || t == "1.#SNAN" || t == "1.#IND" ||
276  t == "1.#R")
277  return Math::NaN<T>();
278  else if (t == "INF" || t == "1.#INF" || t == "INFINITY")
279  return sign * Math::infinity<T>();
280  return 0;
281  }
282 
283  /**
284  * Read a simple fraction, e.g., 3/4, from a string to an object of type T.
285  *
286  * @tparam T the type of the return value.
287  * @param[in] s the string to be converted.
288  * @exception GeographicErr is \e s is not readable as a fraction of type
289  * T.
290  * @return object of type T
291  *
292  * \note The msys shell under Windows converts arguments which look like
293  * pathnames into their Windows equivalents. As a result the argument
294  * "-1/300" gets mangled into something unrecognizable. A workaround is to
295  * use a floating point number in the numerator, i.e., "-1.0/300". (Recent
296  * versions of the msys shell appear \e not to have this problem.)
297  **********************************************************************/
298  template<typename T> static T fract(const std::string& s) {
299  std::string::size_type delim = s.find('/');
300  return
301  !(delim != std::string::npos && delim >= 1 && delim + 2 <= s.size()) ?
302  val<T>(s) :
303  // delim in [1, size() - 2]
304  val<T>(s.substr(0, delim)) / val<T>(s.substr(delim + 1));
305  }
306 
307  /**
308  * Read data of type ExtT from a binary stream to an array of type IntT.
309  * The data in the file is in (bigendp ? big : little)-endian format.
310  *
311  * @tparam ExtT the type of the objects in the binary stream (external).
312  * @tparam IntT the type of the objects in the array (internal).
313  * @tparam bigendp true if the external storage format is big-endian.
314  * @param[in] str the input stream containing the data of type ExtT
315  * (external).
316  * @param[out] array the output array of type IntT (internal).
317  * @param[in] num the size of the array.
318  * @exception GeographicErr if the data cannot be read.
319  **********************************************************************/
320  template<typename ExtT, typename IntT, bool bigendp>
321  static void readarray(std::istream& str, IntT array[], size_t num) {
322 #if GEOGRAPHICLIB_PRECISION < 4
323  if (sizeof(IntT) == sizeof(ExtT) &&
324  std::numeric_limits<IntT>::is_integer ==
325  std::numeric_limits<ExtT>::is_integer)
326  {
327  // Data is compatible (aside from the issue of endian-ness).
328  str.read(reinterpret_cast<char*>(array), num * sizeof(ExtT));
329  if (!str.good())
330  throw GeographicErr("Failure reading data");
331  if (bigendp != Math::bigendian) { // endian mismatch -> swap bytes
332  for (size_t i = num; i--;)
333  array[i] = Math::swab<IntT>(array[i]);
334  }
335  }
336  else
337 #endif
338  {
339  const int bufsize = 1024; // read this many values at a time
340  ExtT buffer[bufsize]; // temporary buffer
341  int k = int(num); // data values left to read
342  int i = 0; // index into output array
343  while (k) {
344  int n = (std::min)(k, bufsize);
345  str.read(reinterpret_cast<char*>(buffer), n * sizeof(ExtT));
346  if (!str.good())
347  throw GeographicErr("Failure reading data");
348  for (int j = 0; j < n; ++j)
349  // fix endian-ness and cast to IntT
350  array[i++] = IntT(bigendp == Math::bigendian ? buffer[j] :
351  Math::swab<ExtT>(buffer[j]));
352  k -= n;
353  }
354  }
355  return;
356  }
357 
358  /**
359  * Read data of type ExtT from a binary stream to a vector array of type
360  * IntT. The data in the file is in (bigendp ? big : little)-endian
361  * format.
362  *
363  * @tparam ExtT the type of the objects in the binary stream (external).
364  * @tparam IntT the type of the objects in the array (internal).
365  * @tparam bigendp true if the external storage format is big-endian.
366  * @param[in] str the input stream containing the data of type ExtT
367  * (external).
368  * @param[out] array the output vector of type IntT (internal).
369  * @exception GeographicErr if the data cannot be read.
370  **********************************************************************/
371  template<typename ExtT, typename IntT, bool bigendp>
372  static void readarray(std::istream& str, std::vector<IntT>& array) {
373  if (array.size() > 0)
374  readarray<ExtT, IntT, bigendp>(str, &array[0], array.size());
375  }
376 
377  /**
378  * Write data in an array of type IntT as type ExtT to a binary stream.
379  * The data in the file is in (bigendp ? big : little)-endian format.
380  *
381  * @tparam ExtT the type of the objects in the binary stream (external).
382  * @tparam IntT the type of the objects in the array (internal).
383  * @tparam bigendp true if the external storage format is big-endian.
384  * @param[out] str the output stream for the data of type ExtT (external).
385  * @param[in] array the input array of type IntT (internal).
386  * @param[in] num the size of the array.
387  * @exception GeographicErr if the data cannot be written.
388  **********************************************************************/
389  template<typename ExtT, typename IntT, bool bigendp>
390  static void writearray(std::ostream& str, const IntT array[], size_t num)
391  {
392 #if GEOGRAPHICLIB_PRECISION < 4
393  if (sizeof(IntT) == sizeof(ExtT) &&
394  std::numeric_limits<IntT>::is_integer ==
395  std::numeric_limits<ExtT>::is_integer &&
396  bigendp == Math::bigendian)
397  {
398  // Data is compatible (including endian-ness).
399  str.write(reinterpret_cast<const char*>(array), num * sizeof(ExtT));
400  if (!str.good())
401  throw GeographicErr("Failure writing data");
402  }
403  else
404 #endif
405  {
406  const int bufsize = 1024; // write this many values at a time
407  ExtT buffer[bufsize]; // temporary buffer
408  int k = int(num); // data values left to write
409  int i = 0; // index into output array
410  while (k) {
411  int n = (std::min)(k, bufsize);
412  for (int j = 0; j < n; ++j)
413  // cast to ExtT and fix endian-ness
414  buffer[j] = bigendp == Math::bigendian ? ExtT(array[i++]) :
415  Math::swab<ExtT>(ExtT(array[i++]));
416  str.write(reinterpret_cast<const char*>(buffer), n * sizeof(ExtT));
417  if (!str.good())
418  throw GeographicErr("Failure writing data");
419  k -= n;
420  }
421  }
422  return;
423  }
424 
425  /**
426  * Write data in an array of type IntT as type ExtT to a binary stream.
427  * The data in the file is in (bigendp ? big : little)-endian format.
428  *
429  * @tparam ExtT the type of the objects in the binary stream (external).
430  * @tparam IntT the type of the objects in the array (internal).
431  * @tparam bigendp true if the external storage format is big-endian.
432  * @param[out] str the output stream for the data of type ExtT (external).
433  * @param[in] array the input vector of type IntT (internal).
434  * @exception GeographicErr if the data cannot be written.
435  **********************************************************************/
436  template<typename ExtT, typename IntT, bool bigendp>
437  static void writearray(std::ostream& str, std::vector<IntT>& array) {
438  if (array.size() > 0)
439  writearray<ExtT, IntT, bigendp>(str, &array[0], array.size());
440  }
441 
442  /**
443  * Parse a KEY [=] VALUE line.
444  *
445  * @param[in] line the input line.
446  * @param[out] key the KEY.
447  * @param[out] value the VALUE.
448  * @param[in] equals character representing "equals" to separate KEY and
449  * VALUE, if NULL (the default) use first space character.
450  * @param[in] comment character to use as the comment character; if
451  * non-NULL, this character and everything after it is discarded; default
452  * is '#'.
453  * @exception std::bad_alloc if memory for the internal strings can't be
454  * allocated.
455  * @return whether a key was found.
456  *
457  * The \e comment character (default is '#') and everything after it are
458  * discarded and the result trimmed of leading and trailing white space.
459  * Use the \e equals delimiter character (or, if it is NULL -- the default,
460  * the first white space) to separate \e key and \e value. \e key and \e
461  * value are trimmed of leading and trailing white space. If \e key is
462  * empty, then \e value is set to "" and false is returned.
463  **********************************************************************/
464  static bool ParseLine(const std::string& line,
465  std::string& key, std::string& value,
466  char equals = '\0', char comment = '#');
467 
468  /**
469  * Set the binary precision of a real number.
470  *
471  * @param[in] ndigits the number of bits of precision. If ndigits is 0
472  * (the default), then determine the precision from the environment
473  * variable GEOGRAPHICLIB_DIGITS. If this is undefined, use ndigits =
474  * 256 (i.e., about 77 decimal digits).
475  * @return the resulting number of bits of precision.
476  *
477  * This only has an effect when GEOGRAPHICLIB_PRECISION = 5. The
478  * precision should only be set once and before calls to any other
479  * GeographicLib functions. (Several functions, for example Math::pi(),
480  * cache the return value in a static local variable. The precision needs
481  * to be set before a call to any such functions.) In multi-threaded
482  * applications, it is necessary also to set the precision in each thread
483  * (see the example GeoidToGTX.cpp).
484  *
485  * \note Use Math::digits() to return the current precision in bits.
486  **********************************************************************/
487  static int set_digits(int ndigits = 0);
488 
489  };
490 
491  /**
492  * The specialization of Utility::val<T>() for strings.
493  *
494  * @param[in] s the string to be converted.
495  * @exception GeographicErr is \e s is not readable as a T.
496  * @return the string trimmed of its whitespace.
497  **********************************************************************/
498  template<> inline std::string Utility::val<std::string>(const std::string& s)
499  { return trim(s); }
500 
501  /**
502  * The specialization of Utility::val<T>() for bools.
503  *
504  * @param[in] s the string to be converted.
505  * @exception GeographicErr is \e s is not readable as a T.
506  * @return boolean value.
507  *
508  * \e s should either be string a representing 0 (false)
509  * or 1 (true) or one of the strings
510  * - "false", "f", "nil", "no", "n", "off", or "" meaning false,
511  * - "true", "t", "yes", "y", or "on" meaning true;
512  * .
513  * case is ignored.
514  **********************************************************************/
515  template<> inline bool Utility::val<bool>(const std::string& s) {
516  std::string t(trim(s));
517  if (t.empty()) return false;
518  bool x;
519  {
520  std::istringstream is(t);
521  if (is >> x) {
522  int pos = int(is.tellg()); // Returns -1 at end of string?
523  if (!(pos < 0 || pos == int(t.size())))
524  throw GeographicErr("Extra text " + t.substr(pos) +
525  " at end of " + t);
526  return x;
527  }
528  }
529  for (std::string::iterator p = t.begin(); p != t.end(); ++p)
530  *p = char(std::tolower(*p));
531  switch (t[0]) { // already checked that t isn't empty
532  case 'f':
533  if (t == "f" || t == "false") return false;
534  break;
535  case 'n':
536  if (t == "n" || t == "nil" || t == "no") return false;
537  break;
538  case 'o':
539  if (t == "off") return false;
540  else if (t == "on") return true;
541  break;
542  case 't':
543  if (t == "t" || t == "true") return true;
544  break;
545  case 'y':
546  if (t == "y" || t == "yes") return true;
547  break;
548  default:
549  break;
550  }
551  throw GeographicErr("Cannot decode " + t + " as a bool");
552  }
553 
554  /**
555  * Convert a Math::real object to a string.
556  *
557  * @param[in] x the value to be converted.
558  * @param[in] p the precision used (default &minus;1).
559  * @exception std::bad_alloc if memory for the string can't be allocated.
560  * @return the string representation.
561  *
562  * If \e p &ge; 0, then the number fixed format is used with p bits of
563  * precision. With p < 0, there is no manipulation of the format. This is
564  * an overload of str<T> which deals with inf and nan.
565  **********************************************************************/
566  template<> inline std::string Utility::str<Math::real>(Math::real x, int p) {
567  using std::isfinite;
568  if (!isfinite(x))
569  return x < 0 ? std::string("-inf") :
570  (x > 0 ? std::string("inf") : std::string("nan"));
571  std::ostringstream s;
572 #if GEOGRAPHICLIB_PRECISION == 4
573  // boost-quadmath treats precision == 0 as "use as many digits as
574  // necessary" (see https://svn.boost.org/trac/boost/ticket/10103 and
575  // https://github.com/boostorg/multiprecision/issues/416)
576  // Fixed by https://github.com/boostorg/multiprecision/pull/389
577  if (p == 0) {
578  using std::signbit; using std::fabs;
579  using std::round; using std::fmod;
580  int n = signbit(x) ? -1 : 1; x = fabs(x);
581  Math::real ix = round(x); // Rounds ties away from zero (up for positive)
582  // Implement the "round ties to even" rule
583  if (2 * (ix - x) == 1 && fmod(ix, Math::real(2)) == 1) --ix;
584  s << std::fixed << std::setprecision(1) << n*ix;
585  std::string r(s.str());
586  // strip off trailing ".0"
587  return r.substr(0, (std::max)(int(r.size()) - 2, 0));
588  }
589 #endif
590  if (p >= 0) s << std::fixed << std::setprecision(p);
591  s << x; return s.str();
592  }
593 
594 } // namespace GeographicLib
595 
596 #if defined(_MSC_VER)
597 # pragma warning (pop)
598 #endif
599 
600 #endif // GEOGRAPHICLIB_UTILITY_HPP
Header for GeographicLib::Constants class.
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:67
Exception handling for GeographicLib.
Definition: Constants.hpp:316
static const bool bigendian
Definition: Math.hpp:184
Some utility routines for GeographicLib.
Definition: Utility.hpp:35
static void readarray(std::istream &str, std::vector< IntT > &array)
Definition: Utility.hpp:372
static void writearray(std::ostream &str, std::vector< IntT > &array)
Definition: Utility.hpp:437
static T fractionalyear(const std::string &s)
Definition: Utility.hpp:135
static void readarray(std::istream &str, IntT array[], size_t num)
Definition: Utility.hpp:321
static void writearray(std::ostream &str, const IntT array[], size_t num)
Definition: Utility.hpp:390
static int dow(int y, int m, int d)
Definition: Utility.hpp:108
static int dow(int s)
Definition: Utility.hpp:117
static T fract(const std::string &s)
Definition: Utility.hpp:298
static T val(const std::string &s)
Definition: Utility.hpp:225
static T nummatch(const std::string &s)
Definition: Utility.hpp:260
static std::string trim(const std::string &s)
Definition: Utility.cpp:149
static std::string str(T x, int p=-1)
Definition: Utility.hpp:161
Namespace for GeographicLib.
Definition: Accumulator.cpp:12