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