NETGeographicLib  1.38
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Pages
Geohash.h
Go to the documentation of this file.
1 #pragma once
2 /**
3  * \file NETGeographicLib/Geohash.h
4  * \brief Header for NETGeographicLib::Geohash class
5  *
6  * NETGeographicLib is copyright (c) Scott Heiman (2013)
7  * GeographicLib is Copyright (c) Charles Karney (2010-2012)
8  * <charles@karney.com> and licensed under the MIT/X11 License.
9  * For more information, see
10  * http://geographiclib.sourceforge.net/
11  **********************************************************************/
12 
13 namespace NETGeographicLib
14 {
15  /**
16  * \brief .NET wrapper for GeographicLib::Geohash.
17  *
18  * Geohashes are described in
19  * - http://en.wikipedia.org/wiki/Geohash
20  * - http://geohash.org/
21  * .
22  * They provide a compact string representation of a particular geographic
23  * location (expressed as latitude and longitude), with the property that if
24  * trailing characters are dropped from the string the geographic location
25  * remains nearby.
26  *
27  * C# Example:
28  * \include example-Geohash.cs
29  * Managed C++ Example:
30  * \include example-Geohash.cpp
31  * Visual Basic Example:
32  * \include example-Geohash.vb
33  **********************************************************************/
34  public ref class Geohash
35  {
36  private:
37  // hide the constructor since all members of this class are static.
38  Geohash() {}
39  public:
40 
41  /**
42  * Convert from geographic coordinates to a geohash.
43  *
44  * @param[in] lat latitude of point (degrees).
45  * @param[in] lon longitude of point (degrees).
46  * @param[in] len the length of the resulting geohash.
47  * @param[out] geohash the geohash.
48  * @exception GeographicErr if \e la is not in [&minus;90&deg;,
49  * 90&deg;].
50  * @exception GeographicErr if \e lon is not in [&minus;540&deg;,
51  * 540&deg;).
52  * @exception std::bad_alloc if memory for \e geohash can't be allocated.
53  *
54  * Internally, \e len is first put in the range [0, 18].
55  *
56  * If \e lat or \e lon is NaN, the returned geohash is "nan".
57  **********************************************************************/
58  static void Forward(double lat, double lon, int len,
59  [System::Runtime::InteropServices::Out] System::String^% geohash);
60 
61  /**
62  * Convert from a geohash to geographic coordinates.
63  *
64  * @param[in] geohash the geohash.
65  * @param[out] lat latitude of point (degrees).
66  * @param[out] lon longitude of point (degrees).
67  * @param[out] len the length of the geohash.
68  * @param[in] centerp if true (the default) return the center of the
69  * geohash location, otherwise return the south-west corner.
70  * @exception GeographicErr if \e geohash contains illegal characters.
71  *
72  * Only the first 18 characters for \e geohash are considered. The case of
73  * the letters in \e geohash is ignored.
74  *
75  * If the first three characters in \e geohash are "nan", then \e lat and
76  * \e lon are set to NaN.
77  **********************************************************************/
78  static void Reverse(System::String^ geohash,
79  [System::Runtime::InteropServices::Out] double% lat,
80  [System::Runtime::InteropServices::Out] double% lon,
81  [System::Runtime::InteropServices::Out] int% len,
82  bool centerp);
83 
84  /**
85  * The latitude resolution of a geohash.
86  *
87  * @param[in] len the length of the geohash.
88  * @return the latitude resolution (degrees).
89  *
90  * Internally, \e len is first put in the range [0, 18].
91  **********************************************************************/
92  static double LatitudeResolution(int len);
93 
94  /**
95  * The longitude resolution of a geohash.
96  *
97  * @param[in] len the length of the geohash.
98  * @return the longitude resolution (degrees).
99  *
100  * Internally, \e len is first put in the range [0, 18].
101  **********************************************************************/
102  static double LongitudeResolution(int len);
103 
104  /**
105  * The geohash length required to meet a given geographic resolution.
106  *
107  * @param[in] res the minimum of resolution in latitude and longitude
108  * (degrees).
109  * @return geohash length.
110  *
111  * The returned length is in the range [0, 18].
112  **********************************************************************/
113  static int GeohashLength(double res);
114 
115  /**
116  * The geohash length required to meet a given geographic resolution.
117  *
118  * @param[in] latres the resolution in latitude (degrees).
119  * @param[in] lonres the resolution in longitude (degrees).
120  * @return geohash length.
121  *
122  * The returned length is in the range [0, 18].
123  **********************************************************************/
124  static int GeohashLength(double latres, double lonres);
125 
126  /**
127  * The decimal geographic precision required to match a given geohash
128  * length. This is the number of digits needed after decimal point in a
129  * decimal degrees representation.
130  *
131  * @param[in] len the length of the geohash.
132  * @return the decimal precision (may be negative).
133  *
134  * Internally, \e len is first put in the range [0, 18]. The returned
135  * decimal precision is in the range [&minus;2, 12].
136  **********************************************************************/
137  static int DecimalPrecision(int len);
138  };
139 } // namespace NETGeographicLib