Add horoscope-api, synastry, and backend services
- horoscope-api: Swiss Ephemeris natal charts, timezone/place resolution, POST /v1/natal and POST /v1/synastry - backend: users with roles, email/password and Google login, saved charts, synastries and invites, analyses with credit ledger, public shares, admin - shared crates: astro-engine, db (migrations), horoscope-client, service-kit - docker-compose with postgres, legacy Java project for reference Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012vLHzh5qUhFtmJhzkcTbXL
This commit is contained in:
@@ -0,0 +1,16 @@
|
||||
[package]
|
||||
name = "geo-tz"
|
||||
description = "Offline place lookup (GeoNames) and historical time zone resolution (IANA tzdb with backzone)"
|
||||
edition.workspace = true
|
||||
version.workspace = true
|
||||
license.workspace = true
|
||||
publish.workspace = true
|
||||
|
||||
[dependencies]
|
||||
deunicode.workspace = true
|
||||
jiff.workspace = true
|
||||
serde.workspace = true
|
||||
thiserror.workspace = true
|
||||
|
||||
[dev-dependencies]
|
||||
jiff.workspace = true
|
||||
@@ -0,0 +1,125 @@
|
||||
//! Offline geography and historical civil time.
|
||||
//!
|
||||
//! * [`places`]: country and populated-place lookup from GeoNames dumps.
|
||||
//! * [`tz`]: IANA time zone database (compiled with `backzone`, so every
|
||||
//! country keeps its own pre-1970 daylight saving history) and conversion of
|
||||
//! local civil time to UTC, including DST gaps and folds.
|
||||
//! * [`Atlas`]: both together, plus time zone selection for a birth place.
|
||||
|
||||
pub mod places;
|
||||
pub mod text;
|
||||
pub mod tz;
|
||||
|
||||
use std::path::Path;
|
||||
|
||||
use serde::Serialize;
|
||||
|
||||
pub use places::{Country, Place, PlaceIndex, PlaceMatch};
|
||||
pub use tz::{AmbiguityPolicy, LocalizedTime, TimeZones, TransitionKind};
|
||||
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum GeoError {
|
||||
#[error("failed to load {what}: {reason}")]
|
||||
Data { what: String, reason: String },
|
||||
#[error("unknown country: {0}")]
|
||||
UnknownCountry(String),
|
||||
#[error("no place named '{query}' found in {country}")]
|
||||
PlaceNotFound { query: String, country: String },
|
||||
#[error("unknown GeoNames id: {0}")]
|
||||
UnknownPlaceId(u64),
|
||||
#[error("place {place} (GeoNames {id}) is in {actual}, not in {expected}")]
|
||||
PlaceCountryMismatch { id: u64, place: String, actual: String, expected: String },
|
||||
#[error("unknown time zone: {0}")]
|
||||
UnknownTimeZone(String),
|
||||
#[error("no time zone could be determined for {0}")]
|
||||
NoTimeZone(String),
|
||||
#[error(
|
||||
"local time {datetime} occurs twice in {zone} (clocks were turned back): \
|
||||
offset {earlier} or {later}; set ambiguous_time to \"earlier\" or \"later\""
|
||||
)]
|
||||
AmbiguousTime { datetime: String, zone: String, earlier: String, later: String },
|
||||
#[error(
|
||||
"local time {datetime} does not exist in {zone} (clocks were turned forward from {earlier} to {later}); \
|
||||
set ambiguous_time to \"earlier\" or \"later\" to interpret it with the offset before or after the change"
|
||||
)]
|
||||
NonexistentTime { datetime: String, zone: String, earlier: String, later: String },
|
||||
#[error("invalid date/time: {0}")]
|
||||
InvalidDateTime(String),
|
||||
}
|
||||
|
||||
/// How the time zone of a chart was chosen.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
|
||||
#[serde(rename_all = "snake_case")]
|
||||
pub enum ZoneSource {
|
||||
/// Given explicitly in the request.
|
||||
Request,
|
||||
/// Time zone of the matched GeoNames place.
|
||||
Place,
|
||||
/// The country has a single time zone.
|
||||
Country,
|
||||
/// Time zone of the nearest populated place in the same country.
|
||||
NearestPlace,
|
||||
/// Nearest reference location of the country's zones in `zone.tab`.
|
||||
ZoneTab,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize)]
|
||||
pub struct ZoneChoice {
|
||||
pub zone: String,
|
||||
pub source: ZoneSource,
|
||||
}
|
||||
|
||||
pub struct Atlas {
|
||||
pub places: PlaceIndex,
|
||||
pub zones: TimeZones,
|
||||
}
|
||||
|
||||
impl Atlas {
|
||||
/// Loads `geonames/` and `zoneinfo/` from the data directory.
|
||||
pub fn load(data_dir: &Path) -> Result<Self, GeoError> {
|
||||
let zones = TimeZones::load(&data_dir.join("zoneinfo"))?;
|
||||
let places = PlaceIndex::load(&data_dir.join("geonames"))?;
|
||||
Ok(Self { places, zones })
|
||||
}
|
||||
|
||||
/// Chooses the time zone for a birth place.
|
||||
///
|
||||
/// Priority: explicit zone > zone of the matched place > the country's only
|
||||
/// zone > zone of the nearest populated place in the country > nearest
|
||||
/// `zone.tab` reference point of the country.
|
||||
pub fn choose_zone(
|
||||
&self,
|
||||
country: &Country,
|
||||
explicit: Option<&str>,
|
||||
place: Option<&Place>,
|
||||
coordinates: (f64, f64),
|
||||
) -> Result<ZoneChoice, GeoError> {
|
||||
if let Some(zone) = explicit {
|
||||
self.zones.get(zone)?;
|
||||
return Ok(ZoneChoice { zone: zone.to_string(), source: ZoneSource::Request });
|
||||
}
|
||||
if let Some(p) = place.filter(|p| self.zones.exists(&p.timezone)) {
|
||||
return Ok(ZoneChoice { zone: p.timezone.clone(), source: ZoneSource::Place });
|
||||
}
|
||||
let country_zones = self.zones.zones_of(&country.iso2);
|
||||
if let [only] = country_zones {
|
||||
return Ok(ZoneChoice { zone: only.name.clone(), source: ZoneSource::Country });
|
||||
}
|
||||
let (lat, lon) = coordinates;
|
||||
if let Some((nearest, _)) = self.places.nearest(&country.iso2, lat, lon, |p| self.zones.exists(&p.timezone)) {
|
||||
return Ok(ZoneChoice { zone: nearest.timezone.clone(), source: ZoneSource::NearestPlace });
|
||||
}
|
||||
country_zones
|
||||
.iter()
|
||||
.min_by(|a, b| {
|
||||
text::distance_km(lat, lon, a.latitude, a.longitude).total_cmp(&text::distance_km(
|
||||
lat,
|
||||
lon,
|
||||
b.latitude,
|
||||
b.longitude,
|
||||
))
|
||||
})
|
||||
.map(|z| ZoneChoice { zone: z.name.clone(), source: ZoneSource::ZoneTab })
|
||||
.ok_or_else(|| GeoError::NoTimeZone(country.name.clone()))
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,288 @@
|
||||
//! Countries and populated places from GeoNames dumps (CC BY 4.0).
|
||||
//!
|
||||
//! Loaded files (see `scripts/fetch-deps.sh`):
|
||||
//! * `countryInfo.txt`, `admin1CodesASCII.txt`
|
||||
//! * `cities*.txt` (worldwide, e.g. cities500) and `full_XX.txt` (every
|
||||
//! populated place of country XX). Duplicates are merged by GeoNames id.
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::fs;
|
||||
use std::path::Path;
|
||||
|
||||
use serde::Serialize;
|
||||
|
||||
use crate::GeoError;
|
||||
use crate::text::{distance_km, normalize};
|
||||
|
||||
#[derive(Debug, Clone, Serialize)]
|
||||
pub struct Country {
|
||||
/// ISO 3166-1 alpha-2 code.
|
||||
pub iso2: String,
|
||||
/// ISO 3166-1 alpha-3 code.
|
||||
pub iso3: String,
|
||||
pub name: String,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize)]
|
||||
pub struct Place {
|
||||
pub geonames_id: u64,
|
||||
pub name: String,
|
||||
pub country_code: String,
|
||||
/// First-level administrative division (county, state, ...).
|
||||
pub region: Option<String>,
|
||||
pub latitude: f64,
|
||||
pub longitude: f64,
|
||||
pub elevation: Option<i32>,
|
||||
pub population: u64,
|
||||
/// GeoNames feature code (PPL, PPLA, PPLC, PPLX, PPLH, ...).
|
||||
pub feature_code: String,
|
||||
/// IANA time zone of the place.
|
||||
pub timezone: String,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize)]
|
||||
pub struct PlaceMatch {
|
||||
#[serde(flatten)]
|
||||
pub place: Place,
|
||||
/// Which name matched the query.
|
||||
pub matched_name: String,
|
||||
/// Ranking score (higher is better).
|
||||
pub score: f64,
|
||||
}
|
||||
|
||||
pub struct PlaceIndex {
|
||||
countries: Vec<Country>,
|
||||
/// normalized ISO2 / ISO3 / name -> index into `countries`
|
||||
country_keys: HashMap<String, usize>,
|
||||
places: Vec<Place>,
|
||||
/// normalized name -> (place index, is primary name)
|
||||
names: HashMap<String, Vec<(u32, bool)>>,
|
||||
by_id: HashMap<u64, u32>,
|
||||
by_country: HashMap<String, Vec<u32>>,
|
||||
pub downloaded: Option<String>,
|
||||
}
|
||||
|
||||
fn data_err(what: &Path, reason: impl ToString) -> GeoError {
|
||||
GeoError::Data { what: what.display().to_string(), reason: reason.to_string() }
|
||||
}
|
||||
|
||||
fn read(path: &Path) -> Result<String, GeoError> {
|
||||
fs::read_to_string(path).map_err(|e| data_err(path, e))
|
||||
}
|
||||
|
||||
impl PlaceIndex {
|
||||
pub fn load(dir: &Path) -> Result<Self, GeoError> {
|
||||
let mut index = PlaceIndex {
|
||||
countries: Vec::new(),
|
||||
country_keys: HashMap::new(),
|
||||
places: Vec::new(),
|
||||
names: HashMap::new(),
|
||||
by_id: HashMap::new(),
|
||||
by_country: HashMap::new(),
|
||||
downloaded: fs::read_to_string(dir.join("DOWNLOADED")).ok().map(|s| s.trim().to_string()),
|
||||
};
|
||||
index.load_countries(&dir.join("countryInfo.txt"))?;
|
||||
let regions = load_regions(&dir.join("admin1CodesASCII.txt"))?;
|
||||
|
||||
let mut files: Vec<_> = fs::read_dir(dir)
|
||||
.map_err(|e| data_err(dir, e))?
|
||||
.flatten()
|
||||
.map(|e| e.path())
|
||||
.filter(|p| {
|
||||
let name = p.file_name().and_then(|n| n.to_str()).unwrap_or_default();
|
||||
name.ends_with(".txt") && (name.starts_with("cities") || name.starts_with("full_"))
|
||||
})
|
||||
.collect();
|
||||
// Country files first: they are the most complete for their country.
|
||||
files.sort_by_key(|p| !p.file_name().is_some_and(|n| n.to_string_lossy().starts_with("full_")));
|
||||
if files.is_empty() {
|
||||
return Err(data_err(dir, "no cities*.txt or full_*.txt GeoNames dump found"));
|
||||
}
|
||||
for file in files {
|
||||
index.load_places(&file, ®ions)?;
|
||||
}
|
||||
Ok(index)
|
||||
}
|
||||
|
||||
fn load_countries(&mut self, path: &Path) -> Result<(), GeoError> {
|
||||
for line in read(path)?.lines().filter(|l| !l.starts_with('#') && !l.is_empty()) {
|
||||
let f: Vec<&str> = line.split('\t').collect();
|
||||
if f.len() < 5 {
|
||||
continue;
|
||||
}
|
||||
let idx = self.countries.len();
|
||||
self.countries.push(Country { iso2: f[0].into(), iso3: f[1].into(), name: f[4].into() });
|
||||
for key in [f[0], f[1], f[4]] {
|
||||
self.country_keys.entry(normalize(key)).or_insert(idx);
|
||||
}
|
||||
}
|
||||
if self.countries.is_empty() {
|
||||
return Err(data_err(path, "no countries"));
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn load_places(&mut self, path: &Path, regions: &HashMap<String, String>) -> Result<(), GeoError> {
|
||||
let content = read(path)?;
|
||||
for line in content.lines() {
|
||||
let f: Vec<&str> = line.split('\t').collect();
|
||||
// geonameid name asciiname alternatenames lat lon fclass fcode cc cc2
|
||||
// admin1 admin2 admin3 admin4 population elevation dem timezone moddate
|
||||
if f.len() < 19 || f[6] != "P" {
|
||||
continue;
|
||||
}
|
||||
let Ok(id) = f[0].parse::<u64>() else { continue };
|
||||
if self.by_id.contains_key(&id) {
|
||||
continue;
|
||||
}
|
||||
let (Ok(lat), Ok(lon)) = (f[4].parse::<f64>(), f[5].parse::<f64>()) else { continue };
|
||||
let idx = self.places.len() as u32;
|
||||
let country_code = f[8].to_string();
|
||||
let place = Place {
|
||||
geonames_id: id,
|
||||
name: f[1].to_string(),
|
||||
region: regions.get(&format!("{}.{}", f[8], f[10])).cloned(),
|
||||
latitude: lat,
|
||||
longitude: lon,
|
||||
elevation: f[15].parse().ok().or_else(|| f[16].parse().ok().filter(|&d: &i32| d > -9999)),
|
||||
population: f[14].parse().unwrap_or(0),
|
||||
feature_code: f[7].to_string(),
|
||||
timezone: f[17].to_string(),
|
||||
country_code: country_code.clone(),
|
||||
};
|
||||
|
||||
let mut keys: Vec<(String, bool)> = vec![(normalize(f[1]), true), (normalize(f[2]), true)];
|
||||
keys.extend(
|
||||
f[3].split(',')
|
||||
.filter(|n| n.len() > 1 && !n.contains("http") && !n.chars().all(|c| c.is_ascii_digit()))
|
||||
.map(|n| (normalize(n), false)),
|
||||
);
|
||||
keys.sort_by(|a, b| a.0.cmp(&b.0).then(b.1.cmp(&a.1)));
|
||||
keys.dedup_by(|a, b| a.0 == b.0);
|
||||
for (key, primary) in keys.into_iter().filter(|(k, _)| !k.is_empty()) {
|
||||
self.names.entry(key).or_default().push((idx, primary));
|
||||
}
|
||||
|
||||
self.by_id.insert(id, idx);
|
||||
self.by_country.entry(country_code).or_default().push(idx);
|
||||
self.places.push(place);
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub fn len(&self) -> usize {
|
||||
self.places.len()
|
||||
}
|
||||
|
||||
pub fn is_empty(&self) -> bool {
|
||||
self.places.is_empty()
|
||||
}
|
||||
|
||||
pub fn countries(&self) -> &[Country] {
|
||||
&self.countries
|
||||
}
|
||||
|
||||
/// Looks up a country by ISO alpha-2, alpha-3 or English name.
|
||||
pub fn country(&self, query: &str) -> Result<&Country, GeoError> {
|
||||
self.country_keys
|
||||
.get(&normalize(query))
|
||||
.map(|&i| &self.countries[i])
|
||||
.ok_or_else(|| GeoError::UnknownCountry(query.to_string()))
|
||||
}
|
||||
|
||||
pub fn by_id(&self, id: u64) -> Result<&Place, GeoError> {
|
||||
self.by_id.get(&id).map(|&i| &self.places[i as usize]).ok_or(GeoError::UnknownPlaceId(id))
|
||||
}
|
||||
|
||||
/// Searches populated places of a country by name. Exact (normalized)
|
||||
/// matches on any name come first; if there are none, prefix matches are
|
||||
/// returned. `region` optionally filters by first-level division name.
|
||||
pub fn search(&self, country: &Country, query: &str, region: Option<&str>, limit: usize) -> Vec<PlaceMatch> {
|
||||
let q = normalize(query);
|
||||
if q.is_empty() {
|
||||
return Vec::new();
|
||||
}
|
||||
let region = region.map(normalize).filter(|r| !r.is_empty());
|
||||
let region_ok = |p: &Place| match (®ion, &p.region) {
|
||||
(None, _) => true,
|
||||
(Some(r), Some(pr)) => normalize(pr).contains(r.as_str()),
|
||||
(Some(_), None) => false,
|
||||
};
|
||||
|
||||
let mut matches: Vec<PlaceMatch> = self
|
||||
.names
|
||||
.get(&q)
|
||||
.into_iter()
|
||||
.flatten()
|
||||
.map(|&(i, primary)| (&self.places[i as usize], primary))
|
||||
.filter(|(p, _)| p.country_code == country.iso2 && region_ok(p))
|
||||
.map(|(p, primary)| PlaceMatch {
|
||||
matched_name: query.trim().to_string(),
|
||||
score: score(p, if primary { 2.0 } else { 1.0 }),
|
||||
place: p.clone(),
|
||||
})
|
||||
.collect();
|
||||
|
||||
if matches.is_empty() {
|
||||
matches = self
|
||||
.by_country
|
||||
.get(&country.iso2)
|
||||
.into_iter()
|
||||
.flatten()
|
||||
.map(|&i| &self.places[i as usize])
|
||||
.filter(|p| region_ok(p))
|
||||
.filter(|p| normalize(&p.name).starts_with(&q))
|
||||
.map(|p| PlaceMatch { matched_name: p.name.clone(), score: score(p, 0.0), place: p.clone() })
|
||||
.collect();
|
||||
}
|
||||
|
||||
matches.sort_by(|a, b| b.score.total_cmp(&a.score).then(a.place.geonames_id.cmp(&b.place.geonames_id)));
|
||||
matches.dedup_by_key(|m| m.place.geonames_id);
|
||||
matches.truncate(limit);
|
||||
matches
|
||||
}
|
||||
|
||||
/// Nearest populated place of the country that satisfies `accept`.
|
||||
pub fn nearest(
|
||||
&self,
|
||||
country_iso2: &str,
|
||||
lat: f64,
|
||||
lon: f64,
|
||||
accept: impl Fn(&Place) -> bool,
|
||||
) -> Option<(&Place, f64)> {
|
||||
self.by_country
|
||||
.get(country_iso2)?
|
||||
.iter()
|
||||
.map(|&i| &self.places[i as usize])
|
||||
.filter(|p| accept(p))
|
||||
.map(|p| (p, distance_km(lat, lon, p.latitude, p.longitude)))
|
||||
.min_by(|a, b| a.1.total_cmp(&b.1))
|
||||
}
|
||||
}
|
||||
|
||||
/// Ranking: name quality (primary > alternate > prefix), then administrative
|
||||
/// importance, then population.
|
||||
fn score(p: &Place, name_quality: f64) -> f64 {
|
||||
let importance = match p.feature_code.as_str() {
|
||||
"PPLC" => 6.0,
|
||||
"PPLA" => 5.0,
|
||||
"PPLA2" => 4.0,
|
||||
"PPLA3" | "PPLA4" | "PPLA5" | "PPLG" => 3.0,
|
||||
"PPL" => 2.0,
|
||||
"PPLX" | "PPLL" | "PPLS" | "PPLF" => 1.0,
|
||||
// historical/abandoned places last, but still findable (old birth records)
|
||||
"PPLH" | "PPLQ" | "PPLW" => 0.5,
|
||||
_ => 1.0,
|
||||
};
|
||||
name_quality * 100.0 + importance * 10.0 + (p.population as f64 + 1.0).log10()
|
||||
}
|
||||
|
||||
fn load_regions(path: &Path) -> Result<HashMap<String, String>, GeoError> {
|
||||
Ok(read(path)?
|
||||
.lines()
|
||||
.filter_map(|l| {
|
||||
let mut f = l.split('\t');
|
||||
Some((f.next()?.to_string(), f.next()?.to_string()))
|
||||
})
|
||||
.collect())
|
||||
}
|
||||
@@ -0,0 +1,53 @@
|
||||
//! Name normalization and geodesy helpers.
|
||||
|
||||
/// Normalizes a place or country name for matching: transliterates to ASCII,
|
||||
/// lowercases, and collapses everything that is not a letter or digit into
|
||||
/// single spaces ("Hódmezővásárhely" -> "hodmezovasarhely",
|
||||
/// "Budapest XIII. kerület" -> "budapest xiii kerulet").
|
||||
pub fn normalize(name: &str) -> String {
|
||||
let ascii = deunicode::deunicode(name);
|
||||
let mut out = String::with_capacity(ascii.len());
|
||||
let mut pending_space = false;
|
||||
for c in ascii.chars() {
|
||||
if c.is_ascii_alphanumeric() {
|
||||
if pending_space && !out.is_empty() {
|
||||
out.push(' ');
|
||||
}
|
||||
pending_space = false;
|
||||
out.push(c.to_ascii_lowercase());
|
||||
} else {
|
||||
pending_space = true;
|
||||
}
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
/// Great-circle distance in kilometers.
|
||||
pub fn distance_km(lat1: f64, lon1: f64, lat2: f64, lon2: f64) -> f64 {
|
||||
const EARTH_RADIUS_KM: f64 = 6371.0;
|
||||
let (p1, p2) = (lat1.to_radians(), lat2.to_radians());
|
||||
let dp = (lat2 - lat1).to_radians();
|
||||
let dl = (lon2 - lon1).to_radians();
|
||||
let a = (dp / 2.0).sin().powi(2) + p1.cos() * p2.cos() * (dl / 2.0).sin().powi(2);
|
||||
2.0 * EARTH_RADIUS_KM * a.sqrt().min(1.0).asin()
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn normalizes_names() {
|
||||
assert_eq!(normalize("Hódmezővásárhely"), "hodmezovasarhely");
|
||||
assert_eq!(normalize(" Budapest XIII. kerület "), "budapest xiii kerulet");
|
||||
assert_eq!(normalize("Kolozsvár"), "kolozsvar");
|
||||
assert_eq!(normalize("Москва"), "moskva");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn distances() {
|
||||
// Budapest - Szeged ~ 161 km
|
||||
let d = distance_km(47.4979, 19.0402, 46.253, 20.14824);
|
||||
assert!((155.0..170.0).contains(&d), "{d}");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,280 @@
|
||||
//! IANA time zone database access and local-time resolution.
|
||||
//!
|
||||
//! The zoneinfo directory is compiled by `scripts/fetch-deps.sh` with
|
||||
//! `PACKRATDATA=backzone PACKRATLIST=zone.tab`: every zone listed in
|
||||
//! `zone.tab` keeps its own history before 1970 instead of being linked to
|
||||
//! a zone that merely agrees since 1970 (e.g. Europe/Oslo is not folded into
|
||||
//! Europe/Berlin, so Norway's 1959-1965 summer time is preserved).
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::fs;
|
||||
use std::path::Path;
|
||||
|
||||
use jiff::Timestamp;
|
||||
use jiff::civil::DateTime;
|
||||
use jiff::tz::{AmbiguousOffset, Offset, TimeZone, TimeZoneDatabase};
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
use crate::GeoError;
|
||||
|
||||
/// What to do when a local time is ambiguous (clocks turned back, the hour
|
||||
/// happens twice) or does not exist (clocks turned forward).
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "snake_case")]
|
||||
pub enum AmbiguityPolicy {
|
||||
/// Return an error that explains both possibilities.
|
||||
#[default]
|
||||
Reject,
|
||||
/// Use the offset in effect before the transition (usually summer time in autumn).
|
||||
Earlier,
|
||||
/// Use the offset in effect after the transition.
|
||||
Later,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
|
||||
#[serde(rename_all = "snake_case")]
|
||||
pub enum TransitionKind {
|
||||
/// The local time did not exist (clocks turned forward).
|
||||
Gap,
|
||||
/// The local time happened twice (clocks turned back).
|
||||
Fold,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize)]
|
||||
pub struct Transition {
|
||||
pub kind: TransitionKind,
|
||||
pub offset_before: String,
|
||||
pub offset_after: String,
|
||||
pub resolved_with: AmbiguityPolicy,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize)]
|
||||
pub struct LocalizedTime {
|
||||
/// IANA zone name; `None` for a fixed offset given in the request.
|
||||
pub zone: Option<String>,
|
||||
/// Local civil time as given.
|
||||
pub local: String,
|
||||
/// The same instant in UTC (RFC 3339).
|
||||
pub utc: String,
|
||||
#[serde(skip)]
|
||||
pub timestamp: Timestamp,
|
||||
pub utc_offset: String,
|
||||
pub utc_offset_seconds: i32,
|
||||
/// Daylight saving (summer) time was in effect.
|
||||
pub dst: bool,
|
||||
/// Zone abbreviation, e.g. CET, CEST, LMT.
|
||||
pub abbreviation: String,
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
pub transition: Option<Transition>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize)]
|
||||
pub struct ZoneTabEntry {
|
||||
pub name: String,
|
||||
/// Reference location of the zone (its principal city).
|
||||
pub latitude: f64,
|
||||
pub longitude: f64,
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
pub comment: Option<String>,
|
||||
}
|
||||
|
||||
pub struct TimeZones {
|
||||
db: TimeZoneDatabase,
|
||||
pub version: String,
|
||||
zone_tab: HashMap<String, Vec<ZoneTabEntry>>,
|
||||
}
|
||||
|
||||
impl TimeZones {
|
||||
pub fn load(dir: &Path) -> Result<Self, GeoError> {
|
||||
let err = |reason: String| GeoError::Data { what: dir.display().to_string(), reason };
|
||||
let zone_tab_path = dir.join("zone.tab");
|
||||
let content = fs::read_to_string(&zone_tab_path).map_err(|e| err(format!("zone.tab: {e}")))?;
|
||||
let mut zone_tab: HashMap<String, Vec<ZoneTabEntry>> = HashMap::new();
|
||||
for line in content.lines().filter(|l| !l.starts_with('#') && !l.trim().is_empty()) {
|
||||
let f: Vec<&str> = line.split('\t').collect();
|
||||
if f.len() < 3 {
|
||||
continue;
|
||||
}
|
||||
let Some((latitude, longitude)) = parse_iso6709(f[1]) else { continue };
|
||||
zone_tab.entry(f[0].to_string()).or_default().push(ZoneTabEntry {
|
||||
name: f[2].to_string(),
|
||||
latitude,
|
||||
longitude,
|
||||
comment: f.get(3).map(|c| c.to_string()),
|
||||
});
|
||||
}
|
||||
let db = TimeZoneDatabase::from_dir(dir).map_err(|e| err(e.to_string()))?;
|
||||
let version = fs::read_to_string(dir.join("VERSION")).map(|s| s.trim().to_string()).unwrap_or_default();
|
||||
let tz = Self { db, version, zone_tab };
|
||||
// Fail fast on an empty or broken directory.
|
||||
tz.get("Europe/Budapest").map_err(|e| err(e.to_string()))?;
|
||||
Ok(tz)
|
||||
}
|
||||
|
||||
pub fn get(&self, name: &str) -> Result<TimeZone, GeoError> {
|
||||
self.db.get(name).map_err(|_| GeoError::UnknownTimeZone(name.to_string()))
|
||||
}
|
||||
|
||||
pub fn exists(&self, name: &str) -> bool {
|
||||
!name.is_empty() && self.db.get(name).is_ok()
|
||||
}
|
||||
|
||||
/// Zones of a country according to `zone.tab`.
|
||||
pub fn zones_of(&self, iso2: &str) -> &[ZoneTabEntry] {
|
||||
self.zone_tab.get(iso2).map(Vec::as_slice).unwrap_or_default()
|
||||
}
|
||||
|
||||
/// Converts local civil time in `zone` to an instant.
|
||||
pub fn localize(&self, zone: &str, local: DateTime, policy: AmbiguityPolicy) -> Result<LocalizedTime, GeoError> {
|
||||
let tz = self.get(zone)?;
|
||||
let ambiguous = tz.to_ambiguous_timestamp(local);
|
||||
let (timestamp, transition) = match ambiguous.offset() {
|
||||
AmbiguousOffset::Unambiguous { offset } => (to_timestamp(local, offset)?, None),
|
||||
AmbiguousOffset::Gap { before, after } | AmbiguousOffset::Fold { before, after } => {
|
||||
let kind = if matches!(ambiguous.offset(), AmbiguousOffset::Gap { .. }) {
|
||||
TransitionKind::Gap
|
||||
} else {
|
||||
TransitionKind::Fold
|
||||
};
|
||||
let offset = match policy {
|
||||
AmbiguityPolicy::Earlier => before,
|
||||
AmbiguityPolicy::Later => after,
|
||||
AmbiguityPolicy::Reject => {
|
||||
let (datetime, zone) = (local.to_string(), zone.to_string());
|
||||
let (earlier, later) = (format_offset(before), format_offset(after));
|
||||
return Err(match kind {
|
||||
TransitionKind::Fold => GeoError::AmbiguousTime { datetime, zone, earlier, later },
|
||||
TransitionKind::Gap => GeoError::NonexistentTime { datetime, zone, earlier, later },
|
||||
});
|
||||
}
|
||||
};
|
||||
let transition = Transition {
|
||||
kind,
|
||||
offset_before: format_offset(before),
|
||||
offset_after: format_offset(after),
|
||||
resolved_with: policy,
|
||||
};
|
||||
(to_timestamp(local, offset)?, Some(transition))
|
||||
}
|
||||
};
|
||||
|
||||
let info = tz.to_offset_info(timestamp);
|
||||
let offset = info.offset();
|
||||
Ok(LocalizedTime {
|
||||
zone: Some(zone.to_string()),
|
||||
local: local.to_string(),
|
||||
utc: timestamp.to_string(),
|
||||
timestamp,
|
||||
utc_offset: format_offset(offset),
|
||||
utc_offset_seconds: offset.seconds(),
|
||||
dst: info.dst().is_dst(),
|
||||
abbreviation: info.abbreviation().to_string(),
|
||||
transition,
|
||||
})
|
||||
}
|
||||
|
||||
/// Converts local civil time with an explicitly given UTC offset.
|
||||
pub fn localize_fixed(&self, local: DateTime, offset_seconds: i32) -> Result<LocalizedTime, GeoError> {
|
||||
let offset = Offset::from_seconds(offset_seconds).map_err(|e| GeoError::InvalidDateTime(e.to_string()))?;
|
||||
let timestamp = to_timestamp(local, offset)?;
|
||||
Ok(LocalizedTime {
|
||||
zone: None,
|
||||
local: local.to_string(),
|
||||
utc: timestamp.to_string(),
|
||||
timestamp,
|
||||
utc_offset: format_offset(offset),
|
||||
utc_offset_seconds: offset_seconds,
|
||||
dst: false,
|
||||
abbreviation: format_offset(offset),
|
||||
transition: None,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
fn to_timestamp(local: DateTime, offset: Offset) -> Result<Timestamp, GeoError> {
|
||||
offset.to_timestamp(local).map_err(|e| GeoError::InvalidDateTime(e.to_string()))
|
||||
}
|
||||
|
||||
/// `+02:00`, or `+01:16:20` when the offset has seconds (local mean time).
|
||||
pub fn format_offset(offset: Offset) -> String {
|
||||
let total = offset.seconds();
|
||||
let sign = if total < 0 { '-' } else { '+' };
|
||||
let abs = total.unsigned_abs();
|
||||
let (h, m, s) = (abs / 3600, (abs / 60) % 60, abs % 60);
|
||||
if s == 0 { format!("{sign}{h:02}:{m:02}") } else { format!("{sign}{h:02}:{m:02}:{s:02}") }
|
||||
}
|
||||
|
||||
/// Parses an offset like `+02:00`, `-05:30`, `+01:16:20`, `+0200` or `Z`.
|
||||
pub fn parse_offset(text: &str) -> Option<i32> {
|
||||
let t = text.trim();
|
||||
if t.eq_ignore_ascii_case("z") || t.eq_ignore_ascii_case("utc") {
|
||||
return Some(0);
|
||||
}
|
||||
let (sign, rest) = match t.as_bytes().first()? {
|
||||
b'+' => (1, &t[1..]),
|
||||
b'-' => (-1, &t[1..]),
|
||||
_ => return None,
|
||||
};
|
||||
let parts: Vec<&str> = if rest.contains(':') {
|
||||
rest.split(':').collect()
|
||||
} else if rest.len() == 4 && rest.chars().all(|c| c.is_ascii_digit()) {
|
||||
vec![&rest[..2], &rest[2..]]
|
||||
} else {
|
||||
vec![rest]
|
||||
};
|
||||
let nums: Vec<i32> = parts.iter().map(|p| p.parse::<i32>().ok()).collect::<Option<_>>()?;
|
||||
let (h, m, s) = match nums.as_slice() {
|
||||
[h] => (*h, 0, 0),
|
||||
[h, m] => (*h, *m, 0),
|
||||
[h, m, s] => (*h, *m, *s),
|
||||
_ => return None,
|
||||
};
|
||||
if !(0..=18).contains(&h) || !(0..60).contains(&m) || !(0..60).contains(&s) {
|
||||
return None;
|
||||
}
|
||||
Some(sign * (h * 3600 + m * 60 + s))
|
||||
}
|
||||
|
||||
/// Parses ISO 6709 coordinates as used in zone.tab: `+4730+01905` or
|
||||
/// `+404251-0740023`.
|
||||
fn parse_iso6709(s: &str) -> Option<(f64, f64)> {
|
||||
let split = s[1..].find(['+', '-'])? + 1;
|
||||
let (lat, lon) = s.split_at(split);
|
||||
Some((parse_dms(lat, 2)?, parse_dms(lon, 3)?))
|
||||
}
|
||||
|
||||
fn parse_dms(s: &str, degree_digits: usize) -> Option<f64> {
|
||||
let sign = if s.starts_with('-') { -1.0 } else { 1.0 };
|
||||
let digits = &s[1..];
|
||||
let num = |r: std::ops::Range<usize>| digits.get(r).and_then(|d| d.parse::<f64>().ok());
|
||||
let d = num(0..degree_digits)?;
|
||||
let m = num(degree_digits..degree_digits + 2)?;
|
||||
let sec = if digits.len() > degree_digits + 2 { num(degree_digits + 2..degree_digits + 4)? } else { 0.0 };
|
||||
Some(sign * (d + m / 60.0 + sec / 3600.0))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn iso6709() {
|
||||
let (lat, lon) = parse_iso6709("+4730+01905").unwrap();
|
||||
assert!((lat - 47.5).abs() < 1e-9 && (lon - (19.0 + 5.0 / 60.0)).abs() < 1e-9);
|
||||
let (lat, lon) = parse_iso6709("+404251-0740023").unwrap();
|
||||
assert!((lat - 40.714_166).abs() < 1e-5 && (lon + 74.006_388).abs() < 1e-5);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn offsets() {
|
||||
assert_eq!(parse_offset("+02:00"), Some(7200));
|
||||
assert_eq!(parse_offset("-05:30"), Some(-19800));
|
||||
assert_eq!(parse_offset("+01:16:20"), Some(4580));
|
||||
assert_eq!(parse_offset("+0100"), Some(3600));
|
||||
assert_eq!(parse_offset("Z"), Some(0));
|
||||
assert_eq!(parse_offset("2"), None);
|
||||
assert_eq!(parse_offset("+25:00"), None);
|
||||
assert_eq!(format_offset(Offset::from_seconds(4580).unwrap()), "+01:16:20");
|
||||
assert_eq!(format_offset(Offset::from_seconds(-12600).unwrap()), "-03:30");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,124 @@
|
||||
//! Tests against the real downloaded data (`scripts/fetch-deps.sh`).
|
||||
|
||||
use std::path::PathBuf;
|
||||
use std::sync::OnceLock;
|
||||
|
||||
use geo_tz::{AmbiguityPolicy, Atlas, GeoError, TransitionKind, ZoneSource};
|
||||
use jiff::civil::date;
|
||||
|
||||
fn atlas() -> &'static Atlas {
|
||||
static ATLAS: OnceLock<Atlas> = OnceLock::new();
|
||||
ATLAS.get_or_init(|| {
|
||||
let dir = std::env::var_os("ASTRO_DATA_DIR")
|
||||
.map(PathBuf::from)
|
||||
.unwrap_or_else(|| PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../data"));
|
||||
Atlas::load(&dir).expect("data directory (run scripts/fetch-deps.sh)")
|
||||
})
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn country_lookup() {
|
||||
let a = atlas();
|
||||
assert_eq!(a.places.country("HU").unwrap().name, "Hungary");
|
||||
assert_eq!(a.places.country("hun").unwrap().iso2, "HU");
|
||||
assert_eq!(a.places.country("hungary").unwrap().iso2, "HU");
|
||||
assert!(matches!(a.places.country("XX"), Err(GeoError::UnknownCountry(_))));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn place_search_handles_accents_villages_and_foreign_names() {
|
||||
let a = atlas();
|
||||
let hu = a.places.country("HU").unwrap();
|
||||
let szeged = &a.places.search(hu, "Szeged", None, 5)[0];
|
||||
assert_eq!(szeged.place.geonames_id, 715429);
|
||||
assert_eq!(szeged.place.timezone, "Europe/Budapest");
|
||||
|
||||
let hmv = a.places.search(hu, "hodmezovasarhely", None, 5);
|
||||
assert_eq!(hmv[0].place.name, "Hódmezővásárhely");
|
||||
|
||||
// a tiny village (population well below 500) from the full HU list
|
||||
let village = a.places.search(hu, "Iborfia", None, 5);
|
||||
assert!(!village.is_empty(), "small villages must be found");
|
||||
|
||||
// Hungarian name of a Romanian city
|
||||
let ro = a.places.country("RO").unwrap();
|
||||
let cluj = &a.places.search(ro, "Kolozsvár", None, 5)[0];
|
||||
assert_eq!(cluj.place.name, "Cluj-Napoca");
|
||||
assert_eq!(cluj.place.timezone, "Europe/Bucharest");
|
||||
|
||||
// prefix fallback
|
||||
assert!(!a.places.search(hu, "Hódmező", None, 5).is_empty());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn zone_choice() {
|
||||
let a = atlas();
|
||||
let hu = a.places.country("HU").unwrap();
|
||||
let z = a.choose_zone(hu, None, None, (47.5, 19.0)).unwrap();
|
||||
assert_eq!((z.zone.as_str(), z.source), ("Europe/Budapest", ZoneSource::Country));
|
||||
|
||||
// multi-zone country resolved from coordinates (Denver)
|
||||
let us = a.places.country("US").unwrap();
|
||||
let z = a.choose_zone(us, None, None, (39.74, -104.99)).unwrap();
|
||||
assert_eq!((z.zone.as_str(), z.source), ("America/Denver", ZoneSource::NearestPlace));
|
||||
|
||||
assert!(a.choose_zone(hu, Some("Mars/Olympus"), None, (0.0, 0.0)).is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn hungarian_dst_history() {
|
||||
let tz = &atlas().zones;
|
||||
// 1985 summer: CEST
|
||||
let t = tz.localize("Europe/Budapest", date(1985, 7, 14).at(14, 30, 0, 0), AmbiguityPolicy::Reject).unwrap();
|
||||
assert_eq!((t.utc_offset.as_str(), t.dst, t.abbreviation.as_str()), ("+02:00", true, "CEST"));
|
||||
assert_eq!(t.utc, "1985-07-14T12:30:00Z");
|
||||
// 1970 summer: Hungary had no DST between 1958 and 1979
|
||||
let t = tz.localize("Europe/Budapest", date(1970, 7, 1).at(12, 0, 0, 0), AmbiguityPolicy::Reject).unwrap();
|
||||
assert_eq!((t.utc_offset.as_str(), t.dst), ("+01:00", false));
|
||||
// 1956 summer: DST was used
|
||||
let t = tz.localize("Europe/Budapest", date(1956, 7, 1).at(12, 0, 0, 0), AmbiguityPolicy::Reject).unwrap();
|
||||
assert_eq!((t.utc_offset.as_str(), t.dst), ("+02:00", true));
|
||||
// before 1890: local mean time of Budapest
|
||||
let t = tz.localize("Europe/Budapest", date(1880, 3, 1).at(12, 0, 0, 0), AmbiguityPolicy::Reject).unwrap();
|
||||
assert_eq!((t.utc_offset.as_str(), t.abbreviation.as_str()), ("+01:16:20", "LMT"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn backzone_keeps_national_history() {
|
||||
let tz = &atlas().zones;
|
||||
// Norway had summer time 1959-1965, Germany did not (1950-1979).
|
||||
let oslo = tz.localize("Europe/Oslo", date(1960, 7, 1).at(12, 0, 0, 0), AmbiguityPolicy::Reject).unwrap();
|
||||
let berlin = tz.localize("Europe/Berlin", date(1960, 7, 1).at(12, 0, 0, 0), AmbiguityPolicy::Reject).unwrap();
|
||||
assert!(oslo.dst && !berlin.dst, "oslo {oslo:?} berlin {berlin:?}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn dst_gaps_and_folds() {
|
||||
let tz = &atlas().zones;
|
||||
// 2023-10-29 02:30 happened twice in Budapest
|
||||
let fold = date(2023, 10, 29).at(2, 30, 0, 0);
|
||||
assert!(matches!(
|
||||
tz.localize("Europe/Budapest", fold, AmbiguityPolicy::Reject),
|
||||
Err(GeoError::AmbiguousTime { .. })
|
||||
));
|
||||
let early = tz.localize("Europe/Budapest", fold, AmbiguityPolicy::Earlier).unwrap();
|
||||
let late = tz.localize("Europe/Budapest", fold, AmbiguityPolicy::Later).unwrap();
|
||||
assert_eq!((early.utc_offset.as_str(), late.utc_offset.as_str()), ("+02:00", "+01:00"));
|
||||
assert_eq!(early.transition.as_ref().unwrap().kind, TransitionKind::Fold);
|
||||
|
||||
// 2023-03-26 02:30 did not exist
|
||||
let gap = date(2023, 3, 26).at(2, 30, 0, 0);
|
||||
assert!(matches!(
|
||||
tz.localize("Europe/Budapest", gap, AmbiguityPolicy::Reject),
|
||||
Err(GeoError::NonexistentTime { .. })
|
||||
));
|
||||
let t = tz.localize("Europe/Budapest", gap, AmbiguityPolicy::Earlier).unwrap();
|
||||
assert_eq!(t.transition.unwrap().kind, TransitionKind::Gap);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn fixed_offset() {
|
||||
let t = atlas().zones.localize_fixed(date(1944, 5, 1).at(10, 0, 0, 0), 7200).unwrap();
|
||||
assert_eq!(t.utc, "1944-05-01T08:00:00Z");
|
||||
assert_eq!(t.zone, None);
|
||||
}
|
||||
Reference in New Issue
Block a user