trtz is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install trtz

It will make the trtz command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall trtz uninstalls.

Adding `trtz` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add trtz

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

trtz = "0.1.1"

The trtz library will be automatically available globally. Read the trtz library documentation.

Back to the crate overview.

Readme

trtz

Tiny Rust Timezone — GPS to timezone for embedded.

Overview

trtz allows querying a timezone for any given GPS location using the datasets from timezone-boundary-builder. In contrast to crates like rtz or tzf-rs, trtz mainly focuses on keeping the dataset as small as possible in order to work on embedded devices like an ESP-32. This is achieved by rasterizing the full dataset to a grid and compressing that data with simple run-length encoding. There are multiple datasets available, each with different grid sizes, so you can choose wichever suits you best considering size, performance and usecase (see Feature Flags).

Usage

Add the dependency with your desired dataset.

cargo add trtz -F variant-now,grid-scale-4

Then you can query timezone IDs with find_tz:

let tz = trtz::find_tz(-31.854739354017354, 128.1822207301782);
assert_eq!(Some("Australia/Eucla"), tz);

Feature Flags

Dataset

trtz uses the data from timezone-boundary-builder. They provide three different datasets of different sizes for different usecases, and each either with or without oceans included. The with-oceans feature is enabled by default and switches to the datasets with oceans. For the specific variant, one of these features must be enabled:

variant-comprehensive: largest, only necessary for historical data
variant-1970: also large, valid for all timestamps since 1970
variant-now: smallest, fully sufficient for lookups of current local time

Grid

Additionally, multiple different grid scales can be selected to further control the dataset size. The sizes are specified as fractions of 1° by 1°, so e.g. a grid scale of 4 would have each grid cell be 0.25° by 0.25° in size. The available sizes are:

grid-scale-1: approx. up to 111 km side lengths
grid-scale-2: approx. up to 56 km side lengths
grid-scale-4: approx. up to 28 km side lengths
grid-scale-6: approx. up to 19 km side lengths

Installing the command-line executable

Adding trtz library as a dependency

Adding `trtz` library as a dependency