tzif/
lib.rs

1// This file is part of ICU4X. For terms of use, please see the file
2// called LICENSE at the top level of the ICU4X source tree
3// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
4
5//! A parser for [Time Zone Information Format (`TZif`)](https://tools.ietf.org/id/draft-murchison-tzdist-tzif-00.html) files.
6//!
7//! Also includes a parser for [POSIX time-zone strings](https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html),
8//! which is used by the TZif parser, but also available separately.
9//!
10//! Resources to generate `TZif` files are provided by the [IANA database](https://www.iana.org/time-zones).
11//! `TZif` files are also included in some operating systems.
12//!
13//! # Examples
14//!
15//! ### Parse TZif Files
16//! ```no_run
17//! # use std::path::Path;
18//! let data = tzif::parse_tzif_file(Path::new("path_to_file")).unwrap();
19//! ```
20//!
21//! ### Parse POSIX time-zone strings
22//! ```rust
23//! let data =
24//!     tzif::parse_posix_tz_string(b"WGT3WGST,M3.5.0/-2,M10.5.0/-1").unwrap();
25//! ```
26
27#![warn(missing_docs)]
28
29use combine::{stream, Parser};
30use data::{posix::PosixTzString, tzif::TzifData};
31use error::Error;
32use std::fs::File;
33use std::path::Path;
34/// The parsed data representations.
35pub mod data;
36
37/// The parser implementations.
38pub mod parse;
39
40/// Error types an implementations.
41pub mod error;
42
43/// Parses a `TZif` file at the provided `path`.
44pub fn parse_tzif_file(path: &Path) -> Result<TzifData, Error> {
45    let file = File::open(path)?;
46    let stream = stream::buffered::Stream::new(
47        stream::position::Stream::new(stream::read::Stream::new(file)),
48        0, /* lookahead */
49    );
50    Ok(parse::tzif::tzif().parse(stream)?.0)
51}
52
53/// Parses a POSIX time-zone string from the given bytes.
54pub fn parse_posix_tz_string(bytes: &[u8]) -> Result<PosixTzString, Error> {
55    Ok(parse::posix::posix_tz_string().parse(bytes)?.0)
56}