GeographicLib  1.50
Constants.hpp
Go to the documentation of this file.
1 /**
2  * \file Constants.hpp
3  * \brief Header for GeographicLib::Constants class
4  *
5  * Copyright (c) Charles Karney (2008-2019) <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_CONSTANTS_HPP)
11 #define GEOGRAPHICLIB_CONSTANTS_HPP 1
12 
13 #include <GeographicLib/Config.h>
14 
15 /**
16  * @relates GeographicLib::Constants
17  * Pack the version components into a single integer. Users should not rely on
18  * this particular packing of the components of the version number; see the
19  * documentation for GEOGRAPHICLIB_VERSION, below.
20  **********************************************************************/
21 #define GEOGRAPHICLIB_VERSION_NUM(a,b,c) ((((a) * 10000 + (b)) * 100) + (c))
22 
23 /**
24  * @relates GeographicLib::Constants
25  * The version of GeographicLib as a single integer, packed as MMmmmmpp where
26  * MM is the major version, mmmm is the minor version, and pp is the patch
27  * level. Users should not rely on this particular packing of the components
28  * of the version number. Instead they should use a test such as \code
29  #if GEOGRAPHICLIB_VERSION >= GEOGRAPHICLIB_VERSION_NUM(1,37,0)
30  ...
31  #endif
32  * \endcode
33  **********************************************************************/
34 #define GEOGRAPHICLIB_VERSION \
35  GEOGRAPHICLIB_VERSION_NUM(GEOGRAPHICLIB_VERSION_MAJOR, \
36  GEOGRAPHICLIB_VERSION_MINOR, \
37  GEOGRAPHICLIB_VERSION_PATCH)
38 
39 /**
40  * @relates GeographicLib::Constants
41  * Is the C++11 static_assert available?
42  **********************************************************************/
43 #if !defined(GEOGRAPHICLIB_HAS_STATIC_ASSERT)
44 # if __cplusplus >= 201103 || defined(__GXX_EXPERIMENTAL_CXX0X__)
45 # define GEOGRAPHICLIB_HAS_STATIC_ASSERT 1
46 # elif defined(_MSC_VER) && _MSC_VER >= 1600
47 // For reference, here is a table of Visual Studio and _MSC_VER
48 // correspondences:
49 //
50 // _MSC_VER Visual Studio
51 // 1100 vc5
52 // 1200 vc6
53 // 1300 vc7
54 // 1310 vc7.1 (2003)
55 // 1400 vc8 (2005)
56 // 1500 vc9 (2008)
57 // 1600 vc10 (2010)
58 // 1700 vc11 (2012)
59 // 1800 vc12 (2013) First version of VS to include enough C++11 support
60 // 1900 vc14 (2015)
61 // 191[0-9] vc15 (2017)
62 // 192[0-9] vc16 (2019)
63 # define GEOGRAPHICLIB_HAS_STATIC_ASSERT 1
64 # else
65 # define GEOGRAPHICLIB_HAS_STATIC_ASSERT 0
66 # endif
67 #endif
68 
69 /**
70  * @relates GeographicLib::Constants
71  * A compile-time assert. Use C++11 static_assert, if available.
72  **********************************************************************/
73 #if !defined(GEOGRAPHICLIB_STATIC_ASSERT)
74 # if GEOGRAPHICLIB_HAS_STATIC_ASSERT
75 # define GEOGRAPHICLIB_STATIC_ASSERT static_assert
76 # else
77 # define GEOGRAPHICLIB_STATIC_ASSERT(cond,reason) \
78  { enum{ GEOGRAPHICLIB_STATIC_ASSERT_ENUM = 1/int(cond) }; }
79 # endif
80 #endif
81 
82 #if defined(_MSC_VER) && defined(GEOGRAPHICLIB_SHARED_LIB) && \
83  GEOGRAPHICLIB_SHARED_LIB
84 # if GEOGRAPHICLIB_SHARED_LIB > 1
85 # error GEOGRAPHICLIB_SHARED_LIB must be 0 or 1
86 # elif defined(GeographicLib_SHARED_EXPORTS)
87 # define GEOGRAPHICLIB_EXPORT __declspec(dllexport)
88 # else
89 # define GEOGRAPHICLIB_EXPORT __declspec(dllimport)
90 # endif
91 #else
92 # define GEOGRAPHICLIB_EXPORT
93 #endif
94 
95 // Use GEOGRAPHICLIB_DEPRECATED to mark functions, types or variables as
96 // deprecated. Code inspired by Apache Subversion's svn_types.h file (via
97 // MPFR).
98 #if defined(__GNUC__)
99 # if __GNUC__ > 4
100 # define GEOGRAPHICLIB_DEPRECATED(msg) __attribute__((deprecated(msg)))
101 # else
102 # define GEOGRAPHICLIB_DEPRECATED(msg) __attribute__((deprecated))
103 # endif
104 #elif defined(_MSC_VER) && _MSC_VER >= 1300
105 # define GEOGRAPHICLIB_DEPRECATED(msg) __declspec(deprecated(msg))
106 #else
107 # define GEOGRAPHICLIB_DEPRECATED(msg)
108 #endif
109 
110 #include <stdexcept>
111 #include <string>
112 #include <GeographicLib/Math.hpp>
113 
114 /**
115  * \brief Namespace for %GeographicLib
116  *
117  * All of %GeographicLib is defined within the GeographicLib namespace. In
118  * addition all the header files are included via %GeographicLib/Class.hpp.
119  * This minimizes the likelihood of conflicts with other packages.
120  **********************************************************************/
121 namespace GeographicLib {
122 
123  /**
124  * \brief %Constants needed by %GeographicLib
125  *
126  * Define constants specifying the WGS84 ellipsoid, the UTM and UPS
127  * projections, and various unit conversions.
128  *
129  * Example of use:
130  * \include example-Constants.cpp
131  **********************************************************************/
133  private:
134  typedef Math::real real;
135  Constants(); // Disable constructor
136 
137  public:
138  /**
139  * A synonym for Math::degree<real>().
140  **********************************************************************/
141  static Math::real degree() { return Math::degree(); }
142  /**
143  * @return the number of radians in an arcminute.
144  **********************************************************************/
146  { return Math::degree() / 60; }
147  /**
148  * @return the number of radians in an arcsecond.
149  **********************************************************************/
151  { return Math::degree() / 3600; }
152 
153  /** \name Ellipsoid parameters
154  **********************************************************************/
155  ///@{
156  /**
157  * @tparam T the type of the returned value.
158  * @return the equatorial radius of WGS84 ellipsoid (6378137 m).
159  **********************************************************************/
160  template<typename T> static T WGS84_a()
161  { return 6378137 * meter<T>(); }
162  /**
163  * A synonym for WGS84_a<real>().
164  **********************************************************************/
165  static Math::real WGS84_a() { return WGS84_a<real>(); }
166  /**
167  * @tparam T the type of the returned value.
168  * @return the flattening of WGS84 ellipsoid (1/298.257223563).
169  **********************************************************************/
170  template<typename T> static T WGS84_f() {
171  // Evaluating this as 1000000000 / T(298257223563LL) reduces the
172  // round-off error by about 10%. However, expressing the flattening as
173  // 1/298.257223563 is well ingrained.
174  return 1 / ( T(298257223563LL) / 1000000000 );
175  }
176  /**
177  * A synonym for WGS84_f<real>().
178  **********************************************************************/
179  static Math::real WGS84_f() { return WGS84_f<real>(); }
180  /**
181  * @tparam T the type of the returned value.
182  * @return the gravitational constant of the WGS84 ellipsoid, \e GM, in
183  * m<sup>3</sup> s<sup>&minus;2</sup>.
184  **********************************************************************/
185  template<typename T> static T WGS84_GM()
186  { return T(3986004) * 100000000 + 41800000; }
187  /**
188  * A synonym for WGS84_GM<real>().
189  **********************************************************************/
190  static Math::real WGS84_GM() { return WGS84_GM<real>(); }
191  /**
192  * @tparam T the type of the returned value.
193  * @return the angular velocity of the WGS84 ellipsoid, &omega;, in rad
194  * s<sup>&minus;1</sup>.
195  **********************************************************************/
196  template<typename T> static T WGS84_omega()
197  { return 7292115 / (T(1000000) * 100000); }
198  /**
199  * A synonym for WGS84_omega<real>().
200  **********************************************************************/
201  static Math::real WGS84_omega() { return WGS84_omega<real>(); }
202  /**
203  * @tparam T the type of the returned value.
204  * @return the equatorial radius of GRS80 ellipsoid, \e a, in m.
205  **********************************************************************/
206  template<typename T> static T GRS80_a()
207  { return 6378137 * meter<T>(); }
208  /**
209  * A synonym for GRS80_a<real>().
210  **********************************************************************/
211  static Math::real GRS80_a() { return GRS80_a<real>(); }
212  /**
213  * @tparam T the type of the returned value.
214  * @return the gravitational constant of the GRS80 ellipsoid, \e GM, in
215  * m<sup>3</sup> s<sup>&minus;2</sup>.
216  **********************************************************************/
217  template<typename T> static T GRS80_GM()
218  { return T(3986005) * 100000000; }
219  /**
220  * A synonym for GRS80_GM<real>().
221  **********************************************************************/
222  static Math::real GRS80_GM() { return GRS80_GM<real>(); }
223  /**
224  * @tparam T the type of the returned value.
225  * @return the angular velocity of the GRS80 ellipsoid, &omega;, in rad
226  * s<sup>&minus;1</sup>.
227  *
228  * This is about 2 &pi; 366.25 / (365.25 &times; 24 &times; 3600) rad
229  * s<sup>&minus;1</sup>. 365.25 is the number of days in a Julian year and
230  * 365.35/366.25 converts from solar days to sidereal days. Using the
231  * number of days in a Gregorian year (365.2425) results in a worse
232  * approximation (because the Gregorian year includes the precession of the
233  * earth's axis).
234  **********************************************************************/
235  template<typename T> static T GRS80_omega()
236  { return 7292115 / (T(1000000) * 100000); }
237  /**
238  * A synonym for GRS80_omega<real>().
239  **********************************************************************/
240  static Math::real GRS80_omega() { return GRS80_omega<real>(); }
241  /**
242  * @tparam T the type of the returned value.
243  * @return the dynamical form factor of the GRS80 ellipsoid,
244  * <i>J</i><sub>2</sub>.
245  **********************************************************************/
246  template<typename T> static T GRS80_J2()
247  { return T(108263) / 100000000; }
248  /**
249  * A synonym for GRS80_J2<real>().
250  **********************************************************************/
251  static Math::real GRS80_J2() { return GRS80_J2<real>(); }
252  /**
253  * @tparam T the type of the returned value.
254  * @return the central scale factor for UTM (0.9996).
255  **********************************************************************/
256  template<typename T> static T UTM_k0()
257  {return T(9996) / 10000; }
258  /**
259  * A synonym for UTM_k0<real>().
260  **********************************************************************/
261  static Math::real UTM_k0() { return UTM_k0<real>(); }
262  /**
263  * @tparam T the type of the returned value.
264  * @return the central scale factor for UPS (0.994).
265  **********************************************************************/
266  template<typename T> static T UPS_k0()
267  { return T(994) / 1000; }
268  /**
269  * A synonym for UPS_k0<real>().
270  **********************************************************************/
271  static Math::real UPS_k0() { return UPS_k0<real>(); }
272  ///@}
273 
274  /** \name SI units
275  **********************************************************************/
276  ///@{
277  /**
278  * @tparam T the type of the returned value.
279  * @return the number of meters in a meter.
280  *
281  * This is unity, but this lets the internal system of units be changed if
282  * necessary.
283  **********************************************************************/
284  template<typename T> static T meter() { return T(1); }
285  /**
286  * A synonym for meter<real>().
287  **********************************************************************/
288  static Math::real meter() { return meter<real>(); }
289  /**
290  * @return the number of meters in a kilometer.
291  **********************************************************************/
293  { return 1000 * meter<real>(); }
294  /**
295  * @return the number of meters in a nautical mile (approximately 1 arc
296  * minute)
297  **********************************************************************/
299  { return 1852 * meter<real>(); }
300 
301  /**
302  * @tparam T the type of the returned value.
303  * @return the number of square meters in a square meter.
304  *
305  * This is unity, but this lets the internal system of units be changed if
306  * necessary.
307  **********************************************************************/
308  template<typename T> static T square_meter()
309  { return meter<real>() * meter<real>(); }
310  /**
311  * A synonym for square_meter<real>().
312  **********************************************************************/
314  { return square_meter<real>(); }
315  /**
316  * @return the number of square meters in a hectare.
317  **********************************************************************/
319  { return 10000 * square_meter<real>(); }
320  /**
321  * @return the number of square meters in a square kilometer.
322  **********************************************************************/
324  { return kilometer() * kilometer(); }
325  /**
326  * @return the number of square meters in a square nautical mile.
327  **********************************************************************/
329  { return nauticalmile() * nauticalmile(); }
330  ///@}
331 
332  /** \name Anachronistic British units
333  **********************************************************************/
334  ///@{
335  /**
336  * @return the number of meters in an international foot.
337  **********************************************************************/
338  static Math::real foot()
339  { return real(254 * 12) / 10000 * meter<real>(); }
340  /**
341  * @return the number of meters in a yard.
342  **********************************************************************/
343  static Math::real yard() { return 3 * foot(); }
344  /**
345  * @return the number of meters in a fathom.
346  **********************************************************************/
347  static Math::real fathom() { return 2 * yard(); }
348  /**
349  * @return the number of meters in a chain.
350  **********************************************************************/
351  static Math::real chain() { return 22 * yard(); }
352  /**
353  * @return the number of meters in a furlong.
354  **********************************************************************/
355  static Math::real furlong() { return 10 * chain(); }
356  /**
357  * @return the number of meters in a statute mile.
358  **********************************************************************/
359  static Math::real mile() { return 8 * furlong(); }
360  /**
361  * @return the number of square meters in an acre.
362  **********************************************************************/
363  static Math::real acre() { return chain() * furlong(); }
364  /**
365  * @return the number of square meters in a square statute mile.
366  **********************************************************************/
367  static Math::real square_mile() { return mile() * mile(); }
368  ///@}
369 
370  /** \name Anachronistic US units
371  **********************************************************************/
372  ///@{
373  /**
374  * @return the number of meters in a US survey foot.
375  **********************************************************************/
377  { return real(1200) / 3937 * meter<real>(); }
378  ///@}
379  };
380 
381  /**
382  * \brief Exception handling for %GeographicLib
383  *
384  * A class to handle exceptions. It's derived from std::runtime_error so it
385  * can be caught by the usual catch clauses.
386  *
387  * Example of use:
388  * \include example-GeographicErr.cpp
389  **********************************************************************/
390  class GeographicErr : public std::runtime_error {
391  public:
392 
393  /**
394  * Constructor
395  *
396  * @param[in] msg a string message, which is accessible in the catch
397  * clause via what().
398  **********************************************************************/
399  GeographicErr(const std::string& msg) : std::runtime_error(msg) {}
400  };
401 
402 } // namespace GeographicLib
403 
404 #endif // GEOGRAPHICLIB_CONSTANTS_HPP
static Math::real arcminute()
Definition: Constants.hpp:145
static Math::real mile()
Definition: Constants.hpp:359
static Math::real kilometer()
Definition: Constants.hpp:292
static Math::real yard()
Definition: Constants.hpp:343
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:92
static Math::real UPS_k0()
Definition: Constants.hpp:271
static Math::real square_nauticalmile()
Definition: Constants.hpp:328
static Math::real WGS84_omega()
Definition: Constants.hpp:201
GeographicLib::Math::real real
Definition: GeodSolve.cpp:31
static Math::real nauticalmile()
Definition: Constants.hpp:298
static Math::real arcsecond()
Definition: Constants.hpp:150
static Math::real foot()
Definition: Constants.hpp:338
static Math::real surveyfoot()
Definition: Constants.hpp:376
static Math::real furlong()
Definition: Constants.hpp:355
static Math::real hectare()
Definition: Constants.hpp:318
static Math::real GRS80_omega()
Definition: Constants.hpp:240
static Math::real meter()
Definition: Constants.hpp:288
static Math::real degree()
Definition: Constants.hpp:141
static Math::real fathom()
Definition: Constants.hpp:347
static Math::real UTM_k0()
Definition: Constants.hpp:261
static Math::real acre()
Definition: Constants.hpp:363
Header for GeographicLib::Math class.
static Math::real chain()
Definition: Constants.hpp:351
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
static T degree()
Definition: Math.hpp:185
static Math::real WGS84_GM()
Definition: Constants.hpp:190
static Math::real square_meter()
Definition: Constants.hpp:313
Constants needed by GeographicLib
Definition: Constants.hpp:132
static Math::real WGS84_a()
Definition: Constants.hpp:165
Exception handling for GeographicLib.
Definition: Constants.hpp:390
static Math::real square_kilometer()
Definition: Constants.hpp:323
static Math::real GRS80_a()
Definition: Constants.hpp:211
static Math::real square_mile()
Definition: Constants.hpp:367
static Math::real GRS80_GM()
Definition: Constants.hpp:222
static Math::real GRS80_J2()
Definition: Constants.hpp:251
static Math::real WGS84_f()
Definition: Constants.hpp:179
GeographicErr(const std::string &msg)
Definition: Constants.hpp:399