Update C implementation to expose integer conversion and encoding functions.

Author: drinckes

c/src/olc.c

@@ -82,23 +82,13 @@ int OLC_IsFull(const char* code, size_t size) {
   return is_full(&info);
 }
 
-int OLC_Encode(const OLC_LatLon* location, size_t length, char* code,
-               int maxlen) {
+void OLC_LocationToIntegers(const OLC_LatLon* degrees,
+                            OLC_LatLonIntegers* integers) {
   // Multiply degrees by precision. Use lround to explicitly round rather than
   // truncate, which causes issues when using values like 0.1 that do not have
   // precise floating point representations.
-  long long int lat = lround(location->lat * kGridLatPrecisionInverse);
-  long long int lng = lround(location->lon * kGridLonPrecisionInverse);
-  // Limit the maximum number of digits in the code.
-  if (length > kMaximumDigitCount) {
-    length = kMaximumDigitCount;
-  }
-  if (length < kMinimumDigitCount) {
-    length = kMinimumDigitCount;
-  }
-  if (length < kPairCodeLength && length % 2 == 1) {
-    length = length + 1;
-  }
+  long long int lat = lround(degrees->lat * kGridLatPrecisionInverse);
+  long long int lon = lround(degrees->lon * kGridLonPrecisionInverse);
   // Convert latitude to positive range (0..2*degrees*precision) and clip.
   lat += OLC_kLatMaxDegrees * kGridLatPrecisionInverse;
   if (lat < 0) {
@@ -108,16 +98,35 @@ int OLC_Encode(const OLC_LatLon* location, size_t length, char* code,
     lat = 2 * OLC_kLatMaxDegrees * kGridLatPrecisionInverse - 1;
   }
   // Convert longitude to the positive range and normalise.
-  lng += OLC_kLonMaxDegrees * kGridLonPrecisionInverse;
-  if (lng < 0) {
+  lon += OLC_kLonMaxDegrees * kGridLonPrecisionInverse;
+  if (lon < 0) {
     // If after adding 180 it is still less than zero, do integer division
     // on a full longitude (360) and add the remainder.
-    lng = lng % (2 * OLC_kLonMaxDegrees * kGridLonPrecisionInverse) +
+    lon = lon % (2 * OLC_kLonMaxDegrees * kGridLonPrecisionInverse) +
           (2 * OLC_kLonMaxDegrees * kGridLonPrecisionInverse);
-  } else if (lng >= 2 * OLC_kLonMaxDegrees * kGridLonPrecisionInverse) {
+  } else if (lon >= 2 * OLC_kLonMaxDegrees * kGridLonPrecisionInverse) {
     // If it's greater than 360, just get the integer division remainder.
-    lng = lng % (2 * OLC_kLonMaxDegrees * kGridLonPrecisionInverse);
+    lon = lon % (2 * OLC_kLonMaxDegrees * kGridLonPrecisionInverse);
   }
+  integers->lat = lat;
+  integers->lon = lon;
+}
+
+int OLC_EncodeIntegers(const OLC_LatLonIntegers* location, size_t length,
+                       char* code, int maxlen) {
+  // Limit the maximum number of digits in the code.
+  if (length > kMaximumDigitCount) {
+    length = kMaximumDigitCount;
+  }
+  if (length < kMinimumDigitCount) {
+    length = kMinimumDigitCount;
+  }
+  if (length < kPairCodeLength && length % 2 == 1) {
+    length = length + 1;
+  }
+
+  long long int lat = location->lat;
+  long long int lon = location->lon;
 
   // Reserve characters for the code digits, the separator and the null
   // terminator.
@@ -129,30 +138,30 @@ int OLC_Encode(const OLC_LatLon* location, size_t length, char* code,
   if (length > kPairCodeLength) {
     for (size_t i = kMaximumDigitCount - kPairCodeLength; i >= 1; i--) {
       int lat_digit = lat % kGridRows;
-      int lng_digit = lng % kGridCols;
+      int lng_digit = lon % kGridCols;
       fullcode[kSeparatorPosition + 2 + i] =
           kAlphabet[lat_digit * kGridCols + lng_digit];
       lat /= kGridRows;
-      lng /= kGridCols;
+      lon /= kGridCols;
     }
   } else {
     lat /= pow(kGridRows, kGridCodeLength);
-    lng /= pow(kGridCols, kGridCodeLength);
+    lon /= pow(kGridCols, kGridCodeLength);
   }
 
   // Add the pair after the separator.
   fullcode[kSeparatorPosition + 1] = kAlphabet[lat % kEncodingBase];
-  fullcode[kSeparatorPosition + 2] = kAlphabet[lng % kEncodingBase];
+  fullcode[kSeparatorPosition + 2] = kAlphabet[lon % kEncodingBase];
   lat /= kEncodingBase;
-  lng /= kEncodingBase;
+  lon /= kEncodingBase;
 
   // Compute the pair section before the separator in reverse order.
   // Even indices contain latitude and odd contain longitude.
   for (int i = (kPairCodeLength / 2 + 1); i >= 0; i -= 2) {
     fullcode[i] = kAlphabet[lat % kEncodingBase];
-    fullcode[i + 1] = kAlphabet[lng % kEncodingBase];
+    fullcode[i + 1] = kAlphabet[lon % kEncodingBase];
     lat /= kEncodingBase;
-    lng /= kEncodingBase;
+    lon /= kEncodingBase;
   }
   // Replace digits with padding if necessary.
   if (length < kSeparatorPosition) {
@@ -170,6 +179,13 @@ int OLC_Encode(const OLC_LatLon* location, size_t length, char* code,
   return length;
 }
 
+int OLC_Encode(const OLC_LatLon* location, size_t length, char* code,
+               int maxlen) {
+  OLC_LatLonIntegers integers;
+  OLC_LocationToIntegers(location, &integers);
+  return OLC_EncodeIntegers(&integers, length, code, maxlen);
+}
+
 int OLC_EncodeDefault(const OLC_LatLon* location, char* code, int maxlen) {
   return OLC_Encode(location, kPairCodeLength, code, maxlen);
 }

c/src/olc.h

@@ -22,53 +22,71 @@
 #define OLC_MAKE_VERSION_STR(major, minor, patch) \
   OLC_MAKE_VERSION_STR_IMPL(major, minor, patch)
 
-// Current version, as a number and a string
+// Current version, as a number and a string.
 #define OLC_VERSION_NUM \
   OLC_MAKE_VERSION_NUM(OLC_VERSION_MAJOR, OLC_VERSION_MINOR, OLC_VERSION_PATCH)
 #define OLC_VERSION_STR \
   OLC_MAKE_VERSION_STR(OLC_VERSION_MAJOR, OLC_VERSION_MINOR, OLC_VERSION_PATCH)
 
-// A pair of doubles representing latitude / longitude
+// A pair of doubles representing latitude and longitude.
 typedef struct OLC_LatLon {
   double lat;
   double lon;
 } OLC_LatLon;
 
-// An area defined by two corners (lo and hi) and a code length
+// A pair of clipped, normalised positive range integers representing latitude
+// and longitude. This is used internally in the encoding methods to avoid
+// floating-point precision issues.
+typedef struct OLC_LatLonIntegers {
+  long long int lat;
+  long long int lon;
+} OLC_LatLonIntegers;
+
+// Convert a location in degrees into the integer values necessary to reliably
+// encode it.
+void OLC_LocationToIntegers(const OLC_LatLon* degrees,
+                            OLC_LatLonIntegers* integers);
+
+// An area defined by two corners (lo and hi) and a code length.
 typedef struct OLC_CodeArea {
   OLC_LatLon lo;
   OLC_LatLon hi;
   size_t len;
 } OLC_CodeArea;
 
-// Get the center coordinates for an area
+// Get the center coordinates for an area.
 void OLC_GetCenter(const OLC_CodeArea* area, OLC_LatLon* center);
 
-// Get the effective length for a code
+// Get the effective length for a code.
 size_t OLC_CodeLength(const char* code, size_t size);
 
 // Check for the three obviously-named conditions
 int OLC_IsValid(const char* code, size_t size);
 int OLC_IsShort(const char* code, size_t size);
 int OLC_IsFull(const char* code, size_t size);
 
-// Encode location with given code length (indicates precision) into an OLC
-// Return the string length of the code
+// Encode location with given code length (indicates precision) into an OLC.
+// Return the string length of the code.
 int OLC_Encode(const OLC_LatLon* location, size_t code_length, char* code,
                int maxlen);
 
-// Encode location with default code length into an OLC
-// Return the string length of the code
+// Encode using integer values. This is only exposed for testing and should
+// not be called from client code.
+int OLC_EncodeIntegers(const OLC_LatLonIntegers* location, size_t code_length,
+                       char* code, int maxlen);
+
+// Encode location with default code length into an OLC.
+// Return the string length of the code.
 int OLC_EncodeDefault(const OLC_LatLon* location, char* code, int maxlen);
 
-// Decode OLC into the original location
+// Decode OLC into the original location.
 int OLC_Decode(const char* code, size_t size, OLC_CodeArea* decoded);
 
-// Compute a (shorter) OLC for a given code and a reference location
+// Compute a (shorter) OLC for a given code and a reference location.
 int OLC_Shorten(const char* code, size_t size, const OLC_LatLon* reference,
                 char* buf, int maxlen);
 
-// Given shorter OLC and reference location, compute original (full length) OLC
+// Given shorter OLC and reference location, compute original (full length) OLC.
 int OLC_RecoverNearest(const char* short_code, size_t size,
                        const OLC_LatLon* reference, char* code, int maxlen);