Skip to main content

relate_model/
point.rs

1//! The point axis vocabulary: the two spellings of each coordinate
2//! (`x`/`longitude`, `y`/`latitude`, `z`/`height`) and the geographic-SRID
3//! predicate. One home for the alias fact, consulted by the `point()` input
4//! readers, the component accessors and the wire encoder.
5
6/// One point axis with both of its spellings: the cartesian name and the
7/// geographic name denote the same coordinate (`x` is `longitude`). The one
8/// alias vocabulary the `point()` input readers, the component accessors and
9/// the wire encoder consult, so the pairs are never spelled at a fourth site.
10#[derive(Clone, Copy, Debug, PartialEq, Eq)]
11pub struct PointAxis {
12    /// The axis position: 0 = x/longitude, 1 = y/latitude, 2 = z/height.
13    pub index: usize,
14    /// The cartesian spelling.
15    pub cartesian: &'static str,
16    /// The geographic spelling.
17    pub geographic: &'static str,
18}
19
20impl PointAxis {
21    /// Whether `key` is either spelling of this axis.
22    pub fn names(self, key: &str) -> bool {
23        key == self.cartesian || key == self.geographic
24    }
25
26    /// The spelling this axis uses on a point of the given family.
27    pub fn key(self, geographic: bool) -> &'static str {
28        if geographic {
29            self.geographic
30        } else {
31            self.cartesian
32        }
33    }
34}
35
36/// The three point axes in x/y/z order.
37pub const POINT_AXES: [PointAxis; 3] = [
38    PointAxis {
39        index: 0,
40        cartesian: "x",
41        geographic: "longitude",
42    },
43    PointAxis {
44        index: 1,
45        cartesian: "y",
46        geographic: "latitude",
47    },
48    PointAxis {
49        index: 2,
50        cartesian: "z",
51        geographic: "height",
52    },
53];
54
55/// The axis a coordinate key names, or `None` for a non-coordinate key.
56pub fn point_axis(key: &str) -> Option<PointAxis> {
57    POINT_AXES.into_iter().find(|axis| axis.names(key))
58}
59
60/// The three coordinate key spellings a point of the given family uses.
61pub fn point_axis_keys(geographic: bool) -> [&'static str; 3] {
62    [
63        POINT_AXES[0].key(geographic),
64        POINT_AXES[1].key(geographic),
65        POINT_AXES[2].key(geographic),
66    ]
67}
68
69/// Whether an SRID is geographic (longitude/latitude keys, `wgs-84*` CRS).
70pub fn is_geographic(srid: i32) -> bool {
71    matches!(srid, 4326 | 4979)
72}
73
74/// Neo4j's longitude wrap into `[-180, 180]`, keeping both endpoints
75/// (180.0 → 180.0, -180.0 → -180.0, 180.5 → -179.5, -200.0 → 160.0,
76/// -540.0 → -180.0). This is the stored geographic-longitude domain for
77/// the producers that uphold it — the engine's `point()` constructor and
78/// the Query API typed decoders — so the POINT index's envelope clip
79/// (which assumes the domain) and the residual scan cannot disagree
80/// (LABS-1236). Bolt point parameters are stored bit-for-bit instead, by
81/// ADR-0177 §2.
82pub fn wrap_longitude(longitude: f64) -> f64 {
83    let mut x = longitude;
84    if !(-180.0..=180.0).contains(&x) {
85        x %= 360.0;
86        if x > 180.0 {
87            x -= 360.0;
88        } else if x < -180.0 {
89            x += 360.0;
90        }
91    }
92    // Normalize -0.0 (from -360 % 360) to +0.0.
93    if x == 0.0 {
94        0.0
95    } else {
96        x
97    }
98}
99
100#[cfg(test)]
101mod tests {
102    use super::*;
103
104    #[test]
105    fn longitude_wraps_into_the_stored_domain() {
106        for (longitude, wrapped) in [
107            (0.0, 0.0),
108            (180.0, 180.0),
109            (-180.0, -180.0),
110            (180.5, -179.5),
111            (-200.0, 160.0),
112            (370.0, 10.0),
113            (-540.0, -180.0),
114            (540.0, 180.0),
115        ] {
116            assert_eq!(wrap_longitude(longitude), wrapped, "{longitude}");
117        }
118        // -360 % 360 is -0.0; the wrap normalizes it to +0.0.
119        assert!(wrap_longitude(-360.0).is_sign_positive());
120        // Extreme longitudes stay finite and in range.
121        for longitude in [1e30, -1e30, 1e300, -1e300, f64::MAX, -f64::MAX] {
122            let wrapped = wrap_longitude(longitude);
123            assert!(
124                wrapped.is_finite() && (-180.0..=180.0).contains(&wrapped),
125                "longitude {longitude} wrapped to {wrapped}"
126            );
127        }
128    }
129}