Add functions to store and retrieve extra bit in osmium::Location

The way coordinates in OSM work, storing a "location" needs 8 bytes, 4
bytes each for the longitude and latitude. But the longitude goes from
-180° to +180° while the latitude only goes from -90° to +90°, so there
is one unused bit in those 8 bytes that always has the same value as
the sign bit.

Sometimes it can be useful to use that single bit for something, because
there are many processing steps where we need to store *all* locations
of all nodes anyway and because there are so many nodes, every bit we
can save, counts.

So this adds some functionality to the osmium::Location class for
storing and retrieving the extra bit without affecting the rest of the
use of the Location class. This code does not attach any specific
meaning to that extra bit, that is for users of the functionality to
decide.

Internal storage is backwards compatible for valid coordinates and
the "undefined" coordinate. Behaviour for invalid coordinates has
changed.

For all of this to be activated you need to define the macro
OSMIUM_LOCATION_WITH_EXTRA_BIT in your source code before including
osmium/osm/location.hpp.

Fixes #395

Author: joto

include/osmium/osm/location.hpp

@@ -34,6 +34,7 @@ DEALINGS IN THE SOFTWARE.
 */
 
 #include <algorithm>
+#include <cassert>
 #include <cmath>
 #include <cstdint>
 #include <cstring>
@@ -267,6 +268,13 @@ namespace osmium {
      *
      * Coordinates are never checked on whether they are inside bounds.
      * Call valid() to check this.
+     *
+     * If the macro OSMIUM_LOCATION_WITH_EXTRA_BIT is defined, Location values
+     * can store one extra bit of information, because one bit is not needed
+     * for the y coordinate. Use the functions set/clear/toggle/get_extra_bit()
+     * to access it. The extra bit will always be cleared for new locations or
+     * by setting the y coordinate of a location. You can not store an extra
+     * bit on an invalid location.
      */
     class Location {
 
@@ -277,6 +285,31 @@ namespace osmium {
             return static_cast<double>(detail::coordinate_precision);
         }
 
+#ifdef OSMIUM_LOCATION_WITH_EXTRA_BIT
+
+        /**
+         * For normal y coordinates, bit 30 is always equal to bit 31. So
+         * we can use that to store one extra piece of information.
+         */
+        enum {
+            mask_b30 = 1UL << 30UL
+        };
+
+        static constexpr int32_t remove_extra_bit(int32_t v) noexcept {
+            if (v == undefined_coordinate) {
+                return v;
+            }
+            auto const value = static_cast<uint32_t>(v);
+            auto const n30 = value & ~mask_b30;
+            auto const b30 = (value >> 1UL) & mask_b30;
+            return static_cast<int32_t>(n30 | b30);
+        }
+#else
+        static constexpr int32_t remove_extra_bit(int32_t v) noexcept {
+            return v;
+        }
+#endif
+
     public:
 
         // this value is used for a coordinate to mark it as undefined
@@ -310,7 +343,7 @@ namespace osmium {
          */
         constexpr Location(const int32_t x, const int32_t y) noexcept :
             m_x(x),
-            m_y(y) {
+            m_y(remove_extra_bit(y)) {
         }
 
         /**
@@ -320,7 +353,7 @@ namespace osmium {
          */
         constexpr Location(const int64_t x, const int64_t y) noexcept :
             m_x(static_cast<int32_t>(x)),
-            m_y(static_cast<int32_t>(y)) {
+            m_y(remove_extra_bit(static_cast<int32_t>(y))) {
         }
 
         /**
@@ -329,7 +362,7 @@ namespace osmium {
          */
         Location(const double lon, const double lat) :
             m_x(double_to_fix(lon)),
-            m_y(double_to_fix(lat)) {
+            m_y(remove_extra_bit(double_to_fix(lat))) {
         }
 
         /**
@@ -379,16 +412,21 @@ namespace osmium {
         }
 
         constexpr int32_t y() const noexcept {
-            return m_y;
+            return remove_extra_bit(m_y);
         }
 
         Location& set_x(const int32_t x) noexcept {
             m_x = x;
             return *this;
         }
 
+        /**
+         * Set the y coordinate of the location.
+         *
+         * This will always clear the extra bit.
+         */
         Location& set_y(const int32_t y) noexcept {
-            m_y = y;
+            m_y = remove_extra_bit(y);
             return *this;
         }
 
@@ -479,6 +517,73 @@ namespace osmium {
             return as_string_without_check(iterator, separator);
         }
 
+#ifdef OSMIUM_LOCATION_WITH_EXTRA_BIT
+        /**
+         * Get extra bit from location.
+         */
+        constexpr bool get_extra_bit() const noexcept {
+            assert(m_y != undefined_coordinate);
+
+            auto const b = static_cast<uint32_t>(m_y);
+            auto const b31 = b >> 31UL;
+            auto const b30 = (b >> 30UL) & 1UL;
+            return b30 ^ b31;
+        }
+
+        /**
+         * Set extra bit on location.
+         *
+         * @pre valid()
+         */
+        constexpr void set_extra_bit() noexcept {
+            assert(m_y != undefined_coordinate);
+
+            auto const b = static_cast<uint32_t>(m_y);
+            auto const n30 = b & ~mask_b30;
+            auto const b30 = (~b >> 1UL) & mask_b30;
+            m_y = static_cast<int32_t>(n30 | b30);
+        }
+
+        /**
+         * Set or clear extra bit on location.
+         *
+         * @pre valid()
+         */
+        constexpr void set_extra_bit(bool value) noexcept {
+            assert(m_y != undefined_coordinate);
+
+            auto const b = static_cast<uint32_t>(m_y);
+            auto const n30 = b & ~mask_b30;
+            auto const b30 = ((b >> 31UL) ^ value) << 30UL;
+            m_y = static_cast<int32_t>(n30 | b30);
+        }
+
+        /**
+         * Clear extra bit on location.
+         *
+         * @pre valid()
+         */
+        constexpr void clear_extra_bit() noexcept {
+            assert(m_y != undefined_coordinate);
+
+            m_y = y();
+        }
+
+        /**
+         * Toggle extra bit on location.
+         *
+         * @pre valid()
+         */
+        constexpr void toggle_extra_bit() noexcept {
+            assert(m_y != undefined_coordinate);
+
+            auto const b = static_cast<uint32_t>(m_y);
+            auto const n30 = b & ~mask_b30;
+            auto const b30 = ~b & mask_b30;
+            m_y = static_cast<int32_t>(n30 | b30);
+        }
+#endif
+
     }; // class Location
 
     /**

test/CMakeLists.txt

@@ -129,6 +129,7 @@ add_unit_test(osm test_changeset ENABLE_IF ${ZLIB_FOUND} LIBS ${ZLIB_LIBRARIES})
 add_unit_test(osm test_crc ENABLE_IF ${ZLIB_FOUND} LIBS ${ZLIB_LIBRARIES})
 add_unit_test(osm test_entity_bits)
 add_unit_test(osm test_location)
+add_unit_test(osm test_location_extra)
 add_unit_test(osm test_metadata)
 add_unit_test(osm test_node ENABLE_IF ${ZLIB_FOUND} LIBS ${ZLIB_LIBRARIES})
 add_unit_test(osm test_node_ref)

test/t/osm/test_location.cpp

@@ -1,5 +1,9 @@
 #include "catch.hpp"
 
+// This file contains the same tests as test_location_extra.cpp, except those
+// tests specific to the location extra bit. OSMIUM_LOCATION_WITH_EXTRA_BIT is
+// not set.
+
 #include <osmium/osm/location.hpp>
 
 #include <cstdint>