Skip to content

Low and high level parsing of system timezone files.

License

Notifications You must be signed in to change notification settings

nicolasbauw/rs-tzfile

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

libtzfile

Current Crates.io Version Current docs Version Downloads badge

This library reads and parses the system timezone information files (TZ Files) provided by IANA.

The default feature is std. With default-features = false, the crate is no_std and uses alloc::vec. In both cases the new() method returns a Tz struct containing the TZfile fields as described in the man page (http://man7.org/linux/man-pages/man5/tzfile.5.html).

  • with no_std the function signature is new(buf: Vec<u8>) where buf is the TZ File data
// no_std
[dependencies]
libtzfile = { version = "3.1.0", default-features = false }
let tzfile = include_bytes!("/usr/share/zoneinfo/America/Phoenix").to_vec();
let tz = Tz::new(tzfile).unwrap();
  • with std which is the default feature the function signature is new(tz: &str) where tz is the TZ File name
// std is the default
[dependencies]
libtzfile = "3.1.0"
use libtzfile::Tz;
let tzfile: &str = "/usr/share/zoneinfo/America/Phoenix";
println!("{:?}", Tz::new(tzfile).unwrap());
Tz { tzh_timecnt_data: [-2717643600, -1633273200, -1615132800, -1601823600, -1583683200, -880210800, -820519140, -812653140, -796845540, -84380400, -68659200], tzh_timecnt_indices: [2, 1, 2, 1, 2, 3, 2, 3, 2, 1, 2], tzh_typecnt: [Ttinfo { tt_utoff: -26898, tt_isdst: 0, tt_abbrind: 0 }, Ttinfo { tt_utoff: -21600, tt_isdst: 1, tt_abbrind: 1 }, Ttinfo { tt_utoff: -25200, tt_isdst: 0, tt_abbrind: 2 }, Ttinfo { tt_utoff: -21600, tt_isdst: 1, tt_abbrind: 3 }], tz_abbr: ["LMT", "MDT", "MST", "MWT"] }

For higher level parsing, you can enable the parse or json features. For instance, to display 2020 DST transitions in France, you can use the transition_times method:

use libtzfile::Tz;
let tzfile: &str = "/usr/share/zoneinfo/Europe/Paris";
println!("{:?}", Tz::new(tzfile).unwrap().transition_times(Some(2020)).unwrap());
[TransitionTime { time: 2020-03-29T01:00:00Z, utc_offset: 7200, isdst: true, abbreviation: "CEST" }, TransitionTime { time: 2020-10-25T01:00:00Z, utc_offset: 3600, isdst: false, abbreviation: "CET" }]

If you want more complete information about the timezone, you can use the zoneinfo method, which returns a more complete structure:

use libtzfile::Tz;
let tzfile: &str = "/usr/share/zoneinfo/Europe/Paris";
println!("{:?}", Tz::new(tzfile).unwrap().zoneinfo().unwrap());
Tzinfo { timezone: "Europe/Paris", utc_datetime: 2020-09-05T16:41:44.279502100Z, datetime: 2020-09-05T18:41:44.279502100+02:00, dst_from: Some(2020-03-29T01:00:00Z), dst_until: Some(2020-10-25T01:00:00Z), dst_period: true, raw_offset: 3600, dst_offset: 7200, utc_offset: +02:00, abbreviation: "CEST", week_number: 36 }

This more complete structure implements the Serialize trait and can be transformed to a json string via a method of the json feature (which includes methods from the parse feature):

use libtzfile::{Tz, TzError};
let tzfile: &str = "/usr/share/zoneinfo/Europe/Paris";
let tz = Tz::new(tzfile)?
    .zoneinfo()?
    .to_json()?;
println!("{}", tz);
{"timezone":"Europe/Paris","utc_datetime":"2020-09-05T18:04:50.546668500Z","datetime":"2020-09-05T20:04:50.546668500+02:00","dst_from":"2020-03-29T01:00:00Z","dst_until":"2020-10-25T01:00:00Z","dst_period":true,"raw_offset":3600,"dst_offset":7200,"utc_offset":"+02:00","abbreviation":"CEST","week_number":36}

This feature is used in my world time API.

The tests (cargo test, cargo test --no-default-features or cargo test --features parse|json) are working with the 2024b timezone database.

License: MIT