LCOV - code coverage report
Current view: top level - geospatial - geoencode.h (source / functions) Hit Total Coverage
Test: Test Coverage for xapian-core 954b5873a738 Lines: 0 2 0.0 %
Date: 2019-06-30 05:20:33 Functions: 0 1 0.0 %
Branches: 0 0 -

           Branch data     Line data    Source code
       1                 :            : /** @file geoencode.h
       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                 :          0 : decode(const std::string & value, double & lat_ref, double & lon_ref)
      81                 :            : {
      82                 :          0 :     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 */

Generated by: LCOV version 1.11