GeographicLib  1.51
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-2020) <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 // For reference, here is a table of Visual Studio and _MSC_VER
40 // correspondences:
41 //
42 // _MSC_VER Visual Studio
43 // 1100 vc5
44 // 1200 vc6
45 // 1300 vc7
46 // 1310 vc7.1 (2003)
47 // 1400 vc8 (2005)
48 // 1500 vc9 (2008)
49 // 1600 vc10 (2010)
50 // 1700 vc11 (2012)
51 // 1800 vc12 (2013) First version of VS to include enough C++11 support
52 // 1900 vc14 (2015)
53 // 191[0-9] vc15 (2017)
54 // 192[0-9] vc16 (2019)
55 
56 #if defined(_MSC_VER) && defined(GEOGRAPHICLIB_SHARED_LIB) && \
57  GEOGRAPHICLIB_SHARED_LIB
58 # if GEOGRAPHICLIB_SHARED_LIB > 1
59 # error GEOGRAPHICLIB_SHARED_LIB must be 0 or 1
60 # elif defined(GeographicLib_SHARED_EXPORTS)
61 # define GEOGRAPHICLIB_EXPORT __declspec(dllexport)
62 # else
63 # define GEOGRAPHICLIB_EXPORT __declspec(dllimport)
64 # endif
65 #else
66 # define GEOGRAPHICLIB_EXPORT
67 #endif
68 
69 // Use GEOGRAPHICLIB_DEPRECATED to mark functions, types or variables as
70 // deprecated. Code inspired by Apache Subversion's svn_types.h file (via
71 // MPFR).
72 #if defined(__GNUC__)
73 # if __GNUC__ > 4
74 # define GEOGRAPHICLIB_DEPRECATED(msg) __attribute__((deprecated(msg)))
75 # else
76 # define GEOGRAPHICLIB_DEPRECATED(msg) __attribute__((deprecated))
77 # endif
78 #elif defined(_MSC_VER) && _MSC_VER >= 1300
79 # define GEOGRAPHICLIB_DEPRECATED(msg) __declspec(deprecated(msg))
80 #else
81 # define GEOGRAPHICLIB_DEPRECATED(msg)
82 #endif
83 
84 #include <stdexcept>
85 #include <string>
86 #include <GeographicLib/Math.hpp>
87 
88 /**
89  * \brief Namespace for %GeographicLib
90  *
91  * All of %GeographicLib is defined within the GeographicLib namespace. In
92  * addition all the header files are included via %GeographicLib/Class.hpp.
93  * This minimizes the likelihood of conflicts with other packages.
94  **********************************************************************/
95 namespace GeographicLib {
96 
97  /**
98  * \brief %Constants needed by %GeographicLib
99  *
100  * Define constants specifying the WGS84 ellipsoid, the UTM and UPS
101  * projections, and various unit conversions.
102  *
103  * Example of use:
104  * \include example-Constants.cpp
105  **********************************************************************/
107  private:
108  typedef Math::real real;
109  Constants(); // Disable constructor
110 
111  public:
112  /**
113  * A synonym for Math::degree<real>().
114  **********************************************************************/
115  static Math::real degree() { return Math::degree(); }
116  /**
117  * @return the number of radians in an arcminute.
118  **********************************************************************/
120  { return Math::degree() / 60; }
121  /**
122  * @return the number of radians in an arcsecond.
123  **********************************************************************/
125  { return Math::degree() / 3600; }
126 
127  /** \name Ellipsoid parameters
128  **********************************************************************/
129  ///@{
130  /**
131  * @tparam T the type of the returned value.
132  * @return the equatorial radius of WGS84 ellipsoid (6378137 m).
133  **********************************************************************/
134  template<typename T = real> static T WGS84_a()
135  { return 6378137 * meter<T>(); }
136  /**
137  * @tparam T the type of the returned value.
138  * @return the flattening of WGS84 ellipsoid (1/298.257223563).
139  **********************************************************************/
140  template<typename T = real> static T WGS84_f() {
141  // Evaluating this as 1000000000 / T(298257223563LL) reduces the
142  // round-off error by about 10%. However, expressing the flattening as
143  // 1/298.257223563 is well ingrained.
144  return 1 / ( T(298257223563LL) / 1000000000 );
145  }
146  /**
147  * @tparam T the type of the returned value.
148  * @return the gravitational constant of the WGS84 ellipsoid, \e GM, in
149  * m<sup>3</sup> s<sup>&minus;2</sup>.
150  **********************************************************************/
151  template<typename T = real> static T WGS84_GM()
152  { return T(3986004) * 100000000 + 41800000; }
153  /**
154  * @tparam T the type of the returned value.
155  * @return the angular velocity of the WGS84 ellipsoid, &omega;, in rad
156  * s<sup>&minus;1</sup>.
157  **********************************************************************/
158  template<typename T = real> static T WGS84_omega()
159  { return 7292115 / (T(1000000) * 100000); }
160  /**
161  * @tparam T the type of the returned value.
162  * @return the equatorial radius of GRS80 ellipsoid, \e a, in m.
163  **********************************************************************/
164  template<typename T = real> static T GRS80_a()
165  { return 6378137 * meter<T>(); }
166  /**
167  * @tparam T the type of the returned value.
168  * @return the gravitational constant of the GRS80 ellipsoid, \e GM, in
169  * m<sup>3</sup> s<sup>&minus;2</sup>.
170  **********************************************************************/
171  template<typename T = real> static T GRS80_GM()
172  { return T(3986005) * 100000000; }
173  /**
174  * @tparam T the type of the returned value.
175  * @return the angular velocity of the GRS80 ellipsoid, &omega;, in rad
176  * s<sup>&minus;1</sup>.
177  *
178  * This is about 2 &pi; 366.25 / (365.25 &times; 24 &times; 3600) rad
179  * s<sup>&minus;1</sup>. 365.25 is the number of days in a Julian year and
180  * 365.35/366.25 converts from solar days to sidereal days. Using the
181  * number of days in a Gregorian year (365.2425) results in a worse
182  * approximation (because the Gregorian year includes the precession of the
183  * earth's axis).
184  **********************************************************************/
185  template<typename T = real> static T GRS80_omega()
186  { return 7292115 / (T(1000000) * 100000); }
187  /**
188  * @tparam T the type of the returned value.
189  * @return the dynamical form factor of the GRS80 ellipsoid,
190  * <i>J</i><sub>2</sub>.
191  **********************************************************************/
192  template<typename T = real> static T GRS80_J2()
193  { return T(108263) / 100000000; }
194  /**
195  * @tparam T the type of the returned value.
196  * @return the central scale factor for UTM (0.9996).
197  **********************************************************************/
198  template<typename T = real> static T UTM_k0()
199  {return T(9996) / 10000; }
200  /**
201  * @tparam T the type of the returned value.
202  * @return the central scale factor for UPS (0.994).
203  **********************************************************************/
204  template<typename T = real> static T UPS_k0()
205  { return T(994) / 1000; }
206  ///@}
207 
208  /** \name SI units
209  **********************************************************************/
210  ///@{
211  /**
212  * @tparam T the type of the returned value.
213  * @return the number of meters in a meter.
214  *
215  * This is unity, but this lets the internal system of units be changed if
216  * necessary.
217  **********************************************************************/
218  template<typename T = real> static T meter() { return T(1); }
219  /**
220  * @return the number of meters in a kilometer.
221  **********************************************************************/
223  { return 1000 * meter<real>(); }
224  /**
225  * @return the number of meters in a nautical mile (approximately 1 arc
226  * minute)
227  **********************************************************************/
229  { return 1852 * meter<real>(); }
230 
231  /**
232  * @tparam T the type of the returned value.
233  * @return the number of square meters in a square meter.
234  *
235  * This is unity, but this lets the internal system of units be changed if
236  * necessary.
237  **********************************************************************/
238  template<typename T = real> static T square_meter()
239  { return meter<T>() * meter<T>(); }
240  /**
241  * @return the number of square meters in a hectare.
242  **********************************************************************/
244  { return 10000 * square_meter<real>(); }
245  /**
246  * @return the number of square meters in a square kilometer.
247  **********************************************************************/
249  { return kilometer() * kilometer(); }
250  /**
251  * @return the number of square meters in a square nautical mile.
252  **********************************************************************/
254  { return nauticalmile() * nauticalmile(); }
255  ///@}
256 
257  /** \name Anachronistic British units
258  **********************************************************************/
259  ///@{
260  /**
261  * @return the number of meters in an international foot.
262  **********************************************************************/
263  static Math::real foot()
264  { return real(254 * 12) / 10000 * meter<real>(); }
265  /**
266  * @return the number of meters in a yard.
267  **********************************************************************/
268  static Math::real yard() { return 3 * foot(); }
269  /**
270  * @return the number of meters in a fathom.
271  **********************************************************************/
272  static Math::real fathom() { return 2 * yard(); }
273  /**
274  * @return the number of meters in a chain.
275  **********************************************************************/
276  static Math::real chain() { return 22 * yard(); }
277  /**
278  * @return the number of meters in a furlong.
279  **********************************************************************/
280  static Math::real furlong() { return 10 * chain(); }
281  /**
282  * @return the number of meters in a statute mile.
283  **********************************************************************/
284  static Math::real mile() { return 8 * furlong(); }
285  /**
286  * @return the number of square meters in an acre.
287  **********************************************************************/
288  static Math::real acre() { return chain() * furlong(); }
289  /**
290  * @return the number of square meters in a square statute mile.
291  **********************************************************************/
292  static Math::real square_mile() { return mile() * mile(); }
293  ///@}
294 
295  /** \name Anachronistic US units
296  **********************************************************************/
297  ///@{
298  /**
299  * @return the number of meters in a US survey foot.
300  **********************************************************************/
302  { return real(1200) / 3937 * meter<real>(); }
303  ///@}
304  };
305 
306  /**
307  * \brief Exception handling for %GeographicLib
308  *
309  * A class to handle exceptions. It's derived from std::runtime_error so it
310  * can be caught by the usual catch clauses.
311  *
312  * Example of use:
313  * \include example-GeographicErr.cpp
314  **********************************************************************/
315  class GeographicErr : public std::runtime_error {
316  public:
317 
318  /**
319  * Constructor
320  *
321  * @param[in] msg a string message, which is accessible in the catch
322  * clause via what().
323  **********************************************************************/
324  GeographicErr(const std::string& msg) : std::runtime_error(msg) {}
325  };
326 
327 } // namespace GeographicLib
328 
329 #endif // GEOGRAPHICLIB_CONSTANTS_HPP
static Math::real arcminute()
Definition: Constants.hpp:119
static Math::real mile()
Definition: Constants.hpp:284
static Math::real kilometer()
Definition: Constants.hpp:222
static Math::real yard()
Definition: Constants.hpp:268
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:66
static Math::real square_nauticalmile()
Definition: Constants.hpp:253
GeographicLib::Math::real real
Definition: GeodSolve.cpp:31
static Math::real nauticalmile()
Definition: Constants.hpp:228
static Math::real arcsecond()
Definition: Constants.hpp:124
static Math::real foot()
Definition: Constants.hpp:263
static Math::real surveyfoot()
Definition: Constants.hpp:301
static Math::real furlong()
Definition: Constants.hpp:280
static Math::real hectare()
Definition: Constants.hpp:243
static Math::real degree()
Definition: Constants.hpp:115
static Math::real fathom()
Definition: Constants.hpp:272
static Math::real acre()
Definition: Constants.hpp:288
Header for GeographicLib::Math class.
static Math::real chain()
Definition: Constants.hpp:276
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
static T degree()
Definition: Math.hpp:159
Constants needed by GeographicLib
Definition: Constants.hpp:106
Exception handling for GeographicLib.
Definition: Constants.hpp:315
static Math::real square_kilometer()
Definition: Constants.hpp:248
static Math::real square_mile()
Definition: Constants.hpp:292
GeographicErr(const std::string &msg)
Definition: Constants.hpp:324