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}