tzf-rs: a fast timezone finder for Rust.

[!NOTE]

This package uses simplified shape data so it is not entirely accurate around the border.

• Released documentation: docs.rs/tzf-rs
• Latest documentation(not released yet): ringsaturn.github.io/tzf-rs
• Try it online: tzf-web

Build options

By default, the binary is built as well. If you don't want/need it, you can omit the default features and build like this:

cargo build --no-default-features

Or add in the below way:

cargo add tzf-rs --no-default-features

Best Practices

It's expensive to init tzf-rs's Finder/FuzzyFinder/DefaultFinder, so please consider reusing instances or creating one as a global variable. Below is a global variable example:

use lazy_static::lazy_static;
use tzf_rs::DefaultFinder;

lazy_static! {
    static ref FINDER: DefaultFinder = DefaultFinder::new();
}

fn main() {
    print!("{:?}\n", FINDER.get_tz_name(116.3883, 39.9289));
    print!("{:?}\n", FINDER.get_tz_names(116.3883, 39.9289));
}

For reuse, racemap/rust-tz-service provides a good example.

A Redis protocol demo could be used here: ringsaturn/redizone.

Performance

The tzf-rs package is intended for high-performance geospatial query services, such as weather forecasting APIs. Most queries can be returned within a very short time, averaging around 3,000 nanoseconds (about 1,000ns slower than with Go repo tzf. I will continue improving this - you can track progress here).

Here is what has been done to improve performance:

1. Using pre-indexing to handle most queries takes approximately 1000 nanoseconds.
2. Using a finely-tuned Ray Casting algorithm package ringsaturn/geometry-rs to verify whether a polygon contains a point.

That's all. There are no black magic tricks inside the tzf-rs.

Below is a benchmark run on global cities(about 14K), and avg time is about 3,000 ns per query:

// require toolchain.channel=nightly 

#![feature(test)]
#[cfg(test)]
mod benches_default {

    use tzf_rs::DefaultFinder;
    extern crate test;
    use test::Bencher;
    #[bench]
    fn bench_default_finder_random_city(b: &mut Bencher) {
        let finder: DefaultFinder = DefaultFinder::default();

        b.iter(|| {
            let city = cities_json::get_random_cities();
            let _ = finder.get_tz_name(city.lng, city.lat);
        });
    }
}

test benches_default::bench_default_finder_random_city ... bench:       1,220.19 ns/iter (+/- 54.36)

Criterion result	Pic
PDF
Regression

You can view more details from latest benchmark from GitHub Actions logs.

References

I have written an article about the history of tzf, its Rust port, and its Rust port's Python binding; you can view it here.

• Original Go repo: ringsaturn/tzf
• Binary timezone data: ringsaturn/tzf-rel
• Geometry: use ringsaturn/geometry-rs which is tidwall/geometry's Rust port.
• Continuous Benchmark compared with other packages: ringsaturn/tz-benchmark

Bindings

• Ruby, see HarlemSquirrel/tzf-rb
• Python, see ringsaturn/tzfpy
• Wasm, see ringsaturn/tzf-wasm

Command line

The binary helps in debugging tzf-rs and using it in (scripting) languages without bindings. Either specify the coordinates as parameters to get a single time zone, or to look up multiple coordinates efficiently specify the ordering and pipe them to the binary one pair of coordinates per line.

tzf --lng 116.3883 --lat 39.9289
echo -e "116.3883 39.9289\n116.3883, 39.9289" | tzf --stdin-order lng-lat

LICENSE

This project is licensed under the MIT license. The data is licensed under the ODbL license, same as evansiroky/timezone-boundary-builder