tzf-rs Timezone Finder
Work with `tzf-rs`, a fast timezone finder library for Rust that converts longitude/latitude coordinates to timezone names.
What This Skill Does
This skill helps you work with the `tzf-rs` codebase, which provides three finder types for timezone lookups:
**Finder**: Most accurate, uses polygon geometry (~3000ns per query)**FuzzyFinder**: Fast preindex-based lookups (~400ns per query)**DefaultFinder**: Hybrid approach combining both findersInstructions
When working with this codebase, follow these guidelines:
1. Build and Test Commands
**Building:**
Use `cargo build --no-default-features` to build library only (no CLI binary)Use `cargo build` to build with CLI binary includedRun tests with `cargo test`Run benchmarks with `cargo bench`**CLI Usage:**
```bash
Single coordinate lookup
cargo run -- --lng 116.3883 --lat 39.9289
Multiple coordinates from stdin
echo "116.3883 39.9289" | cargo run -- --stdin-order lng-lat
```
**Development:**
Generate license information: `make THIRDPARTY.yml`Install CLI globally: `cargo install --path . --no-default-features`2. Code Architecture Understanding
**Core Library (`src/lib.rs`):**
**Item struct**: Internal representation of timezone polygons**Finder**: Ray-casting algorithm for precise polygon containment**FuzzyFinder**: HashMap-based preindex lookup using map tiles**DefaultFinder**: Hybrid approach combining both finders**Key Dependencies:**
`geometry-rs`: Ray casting polygon containment algorithm`tzf-rel`: Binary timezone data (precompiled protobuf)`prost`: Protocol buffer serialization**Data Sources:**
Simplified data: Built-in via `tzf-rel` dependencyFull accuracy data: External 90MB `combined-with-oceans.bin` file3. Performance Strategy
When implementing or modifying code:
1. Preindex tiles (zoom levels) for fast majority-case lookups
2. Use precise polygon geometry for edge cases and 100% accuracy
3. Apply coordinate shifting for handling simplified polygon gaps
4. Creating Finder instances is expensive - recommend using `lazy_static` or global variables
5. FuzzyFinder uses HashMap for O(1) tile lookups
4. Testing Approach
**Test Files:**
`tests/basic_test.rs`: Core functionality validation`benches/finders.rs`: Performance benchmarking using CriterionGlobal city dataset (`cities-json`) for realistic benchmarks5. Data Handling
**Coordinate Format:**
All coordinates are longitude-latitude pairs (x, y format)**Data Modes:**
Default: Uses reduced/simplified polygon data from `tzf-rel`Full accuracy: Load external protobuf data via `Finder::from_pb()`**Key Functions:**
`deg2num()`: Converts lat/lng to map tile coordinates`get_tz_name()`: Returns single timezone name`get_tz_names()`: Returns all matching timezones (for overlapping areas)6. CLI Binary
The optional CLI tool (`src/bin/tzf.rs`) requires the `clap` feature and supports:
Single coordinate queriesBatch processing from stdinMultiple coordinate formats (lng-lat, lat-lng)7. Implementation Notes
**Coordinate Shifting:**
Use ±0.01, ±0.02 degrees shifts to handle simplified polygon gaps**Performance Optimization:**
Cache Finder instances rather than recreating themUse FuzzyFinder for most lookups, fall back to Finder for precisionConsider DefaultFinder for automatic hybrid approachExample Usage
```bash
Test a specific coordinate
cargo run -- --lng 116.3883 --lat 39.9289
Run benchmarks to verify performance
cargo bench
Build and install CLI tool
cargo install --path . --no-default-features
```
Constraints
Creating Finder instances is expensive - avoid recreating them frequentlyCoordinate format is always longitude first, then latitude (x, y)Full accuracy mode requires external 90MB protobuf fileCLI binary is optional and requires the `clap` feature flag