GeographicLib 2.3

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) <karney@alum.mit.edu> 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 **********************************************************************/
107 class GEOGRAPHICLIB_EXPORT Constants {
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 **********************************************************************/
120 static Math::real arcminute()
121 { return Math::degree() / Math::real(Math::dm); }
122 /**
123 * @return the number of radians in an arcsecond.
124 **********************************************************************/
125 static Math::real arcsecond()
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 **********************************************************************/
223 static Math::real kilometer()
224 { return 1000 * meter<real>(); }
225 /**
226 * @return the number of meters in a nautical mile (approximately 1 arc
227 * minute)
228 **********************************************************************/
229 static Math::real nauticalmile()
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 **********************************************************************/
244 static Math::real hectare()
245 { return 10000 * square_meter<real>(); }
246 /**
247 * @return the number of square meters in a square kilometer.
248 **********************************************************************/
249 static Math::real square_kilometer()
250 { return kilometer() * kilometer(); }
251 /**
252 * @return the number of square meters in a square nautical mile.
253 **********************************************************************/
254 static Math::real square_nauticalmile()
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 **********************************************************************/
302 static Math::real surveyfoot()
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
GEOGRAPHICLIB_EXPORT
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:67
real
GeographicLib::Math::real real
Definition: GeodSolve.cpp:29
Math.hpp
Header for GeographicLib::Math class.
GeographicLib::Constants
Constants needed by GeographicLib
Definition: Constants.hpp:107
GeographicLib::Constants::yard
static Math::real yard()
Definition: Constants.hpp:269
GeographicLib::Constants::arcsecond
static Math::real arcsecond()
Definition: Constants.hpp:125
GeographicLib::Constants::square_kilometer
static Math::real square_kilometer()
Definition: Constants.hpp:249
GeographicLib::Constants::degree
static Math::real degree()
Definition: Constants.hpp:116
GeographicLib::Constants::UPS_k0
static T UPS_k0()
Definition: Constants.hpp:205
GeographicLib::Constants::mile
static Math::real mile()
Definition: Constants.hpp:285
GeographicLib::Constants::hectare
static Math::real hectare()
Definition: Constants.hpp:244
GeographicLib::Constants::kilometer
static Math::real kilometer()
Definition: Constants.hpp:223
GeographicLib::Constants::fathom
static Math::real fathom()
Definition: Constants.hpp:273
GeographicLib::Constants::GRS80_J2
static T GRS80_J2()
Definition: Constants.hpp:193
GeographicLib::Constants::square_nauticalmile
static Math::real square_nauticalmile()
Definition: Constants.hpp:254
GeographicLib::Constants::GRS80_GM
static T GRS80_GM()
Definition: Constants.hpp:172
GeographicLib::Constants::surveyfoot
static Math::real surveyfoot()
Definition: Constants.hpp:302
GeographicLib::Constants::furlong
static Math::real furlong()
Definition: Constants.hpp:281
GeographicLib::Constants::arcminute
static Math::real arcminute()
Definition: Constants.hpp:120
GeographicLib::Constants::WGS84_omega
static T WGS84_omega()
Definition: Constants.hpp:159
GeographicLib::Constants::GRS80_a
static T GRS80_a()
Definition: Constants.hpp:165
GeographicLib::Constants::GRS80_omega
static T GRS80_omega()
Definition: Constants.hpp:186
GeographicLib::Constants::UTM_k0
static T UTM_k0()
Definition: Constants.hpp:199
GeographicLib::Constants::square_mile
static Math::real square_mile()
Definition: Constants.hpp:293
GeographicLib::Constants::square_meter
static T square_meter()
Definition: Constants.hpp:239
GeographicLib::Constants::meter
static T meter()
Definition: Constants.hpp:219
GeographicLib::Constants::chain
static Math::real chain()
Definition: Constants.hpp:277
GeographicLib::Constants::foot
static Math::real foot()
Definition: Constants.hpp:264
GeographicLib::Constants::WGS84_f
static T WGS84_f()
Definition: Constants.hpp:141
GeographicLib::Constants::WGS84_a
static T WGS84_a()
Definition: Constants.hpp:135
GeographicLib::Constants::acre
static Math::real acre()
Definition: Constants.hpp:289
GeographicLib::Constants::WGS84_GM
static T WGS84_GM()
Definition: Constants.hpp:152
GeographicLib::Constants::nauticalmile
static Math::real nauticalmile()
Definition: Constants.hpp:229
GeographicLib::GeographicErr
Exception handling for GeographicLib.
Definition: Constants.hpp:316
GeographicLib::GeographicErr::GeographicErr
GeographicErr(const std::string &msg)
Definition: Constants.hpp:325
GeographicLib::Math::degree
static T degree()
Definition: Math.hpp:193
GeographicLib::Math::real
double real
Definition: Math.hpp:100
GeographicLib::Math::dm
@ dm
minutes per degree
Definition: Math.hpp:139
GeographicLib::Math::ds
@ ds
seconds per degree
Definition: Math.hpp:143
GeographicLib
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
std
Definition: NearestNeighbor.hpp:812