xapian-core/geospatial/geoencode.h

   1 /** @file
   2  * @brief Encodings for geospatial coordinates.
   3  */
   4 /* Copyright (C) 2011 Richard Boulton
   5  * Based closely on a python version, copyright (C) 2010 Olly Betts
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining a copy
   8  * of this software and associated documentation files (the "Software"), to
   9  * deal in the Software without restriction, including without limitation the
  10  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  11  * sell copies of the Software, and to permit persons to whom the Software is
  12  * furnished to do so, subject to the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included in
  15  * all copies or substantial portions of the Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  20  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  21  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  22  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  23  * IN THE SOFTWARE.
  24  */
  25
  26 #ifndef XAPIAN_INCLUDED_GEOENCODE_H
  27 #define XAPIAN_INCLUDED_GEOENCODE_H
  28
  29 #include <string>
  30
  31 namespace GeoEncode {
  32
  33 /** Encode a coordinate and append it to a string.
  34  *
  35  * @param lat The latitude coordinate in degrees (ranging from -90 to +90)
  36  * @param lon The longitude coordinate in degrees (any range is valid -
  37  *            longitudes will be wrapped).  Note that decoding will return
  38  *            longitudes in the range 0 <= value < 360.
  39  * @param result The string to append the result to.
  40  *
  41  * @returns true if the encoding was successful, false if there was an error.
  42  * If there was an error, the result value will be unmodified.  The only cause
  43  * of error is out-of-range latitudes.  If there was no error, the string will
  44  * have been extended by 6 bytes.
  45  */
  46 extern bool
  47 encode(double lat, double lon, std::string & result);
  48
  49 /** Decode a coordinate from a buffer.
  50  *
  51  * @param value A pointer to the start of the buffer to decode.
  52  * @param len The length of the buffer in bytes.  The buffer must be at least 2
  53  *            bytes long (this constraint is not checked).
  54  * @param lat_ref A reference to a value to return the latitude in.
  55  * @param lon_ref A reference to a value to return the longitude in.
  56  *
  57  * @returns The decoded coordinate.
  58  *
  59  * No errors will be returned; any junk at the end of the value (ie, after the
  60  * first 6 bytes) will be ignored, and it is possible for invalid inputs to
  61  * result in out-of-range longitudes.
  62  */
  63 extern void
  64 decode(const char * value, size_t len, double & lat_ref, double & lon_ref);
  65
  66 /** Decode a coordinate from a string.
  67  *
  68  * @param value The string to decode.  This must be at least 2 bytes long (this
  69  *              constraint is not checked).
  70  * @param lat_ref A reference to a value to return the latitude in.
  71  * @param lon_ref A reference to a value to return the longitude in.
  72  *
  73  * @returns The decoded coordinate.
  74  *
  75  * No errors will be returned; any junk at the end of the value (ie, after the
  76  * first 6 bytes) will be ignored, and it is possible for invalid inputs to
  77  * result in out-of-range longitudes.
  78  */
  79 static inline void
  80 decode(const std::string & value, double & lat_ref, double & lon_ref)
  81 {
  82     return GeoEncode::decode(value.data(), value.size(), lat_ref, lon_ref);
  83 }
  84
  85 /** A class for decoding coordinates within a bounding box.
  86  *
  87  *  This class aborts decoding if it is easily able to determine that the
  88  *  encoded coordinate supplied is outside the bounding box, avoiding some
  89  *  unnecessary work.
  90  */
  91 class DecoderWithBoundingBox {
  92     /** Longitude at western edge of bounding box.
  93      */
  94     double lon1;
  95
  96     /** Longitude at eastern edge of bounding box.
  97      */
  98     double lon2;
  99
 100     /** Minimum latitude in bounding box.
 101      */
 102     double min_lat;
 103
 104     /** Maximum latitude in bounding box.
 105      */
 106     double max_lat;
 107
 108     /** First byte of encoded form of coordinates with lon1.
 109      */
 110     unsigned char start1;
 111
 112     /** First byte of encoded form of coordinates with lon2.
 113      */
 114     unsigned char start2;
 115
 116     /** True if either of the poles are included in the range.
 117      */
 118     bool include_poles;
 119
 120     /** Flag; true if the longitude range is discontinuous (ie, goes over the
 121      *  boundary at which longitudes wrap from 360 to 0).
 122      */
 123     bool discontinuous_longitude_range;
 124
 125   public:
 126     /** Create a decoder with a bounding box.
 127      *
 128      *  The decoder will decode any encoded coordinates which lie inside the
 129      *  bounding box, and return false for any which lie outside the bounding
 130      *  box.
 131      *
 132      *  @param lat1 The latitude of the southern edge of the bounding box.
 133      *  @param lon1 The longitude of the western edge of the bounding box.
 134      *  @param lat2 The latitude of the northern edge of the bounding box.
 135      *  @param lon2 The longitude of the eastern edge of the bounding box.
 136      */
 137     DecoderWithBoundingBox(double lat1, double lon1, double lat2, double lon2);
 138
 139     /** Decode a coordinate.
 140      *
 141      *  @param value The coordinate to decode.
 142      *  @param lat_ref A reference to a value to return the latitude in.
 143      *  @param lon_ref A reference to a value to return the longitude in.
 144      *
 145      *  @returns true if the coordinate was in the bounding box (in which case,
 146      *           @a result will have been updated to contain the coordinate),
 147      *           or false if the coordinate is outside the bounding box.
 148      *
 149      *  Note; if this returns false, the values of @a lat_ref and @a lon_ref
 150      *  may not have been updated, or may have been updated to incorrect
 151      *  values, due to aborting decoding of the coordinate part-way through.
 152      */
 153     bool decode(const std::string & value,
 154                 double & lat_ref, double & lon_ref) const;
 155 };
 156
 157 }
 158
 159 #endif /* XAPIAN_INCLUDED_GEOENCODE_H */