Module tz

Available on crate features dep_jiff and alloc only.

Routines for interacting with time zones and the zoneinfo database.

The main type in this module is TimeZone. For most use cases, you may not even need to interact with this type at all. For example, this code snippet converts a civil datetime to a zone aware datetime:

use jiff::civil::date;

let zdt = date(2024, 7, 10).at(20, 48, 0, 0).intz("America/New_York")?;
assert_eq!(zdt.to_string(), "2024-07-10T20:48:00-04:00[America/New_York]");

And this example parses a zone aware datetime from a string:

use jiff::Zoned;

let zdt: Zoned = "2024-07-10 20:48[america/new_york]".parse()?;
assert_eq!(zdt.year(), 2024);
assert_eq!(zdt.month(), 7);
assert_eq!(zdt.day(), 10);
assert_eq!(zdt.hour(), 20);
assert_eq!(zdt.minute(), 48);
assert_eq!(zdt.offset().seconds(), -4 * 60 * 60);
assert_eq!(zdt.time_zone().iana_name(), Some("America/New_York"));

Yet, neither of the above examples require uttering TimeZone. This is because the datetime types in this crate provide higher level abstractions for working with time zone identifiers. Nevertheless, sometimes it is useful to work with a TimeZone directly. For example, if one has a TimeZone, then conversion from a Timestamp to a Zoned is infallible:

use jiff::{tz::TimeZone, Timestamp, Zoned};

let tz = TimeZone::get("America/New_York")?;
let ts = Timestamp::UNIX_EPOCH;
let zdt = ts.to_zoned(tz);
assert_eq!(zdt.to_string(), "1969-12-31T19:00:00-05:00[America/New_York]");

The IANA Time Zone Database

Since a time zone is a set of rules for determining the civil time, via an offset from UTC, in a particular geographic region, a database is required to represent the full complexity of these rules in practice. The standard database is widespread use is the IANA Time Zone Database. On Unix systems, this is typically found at /usr/share/zoneinfo, and Jiff will read it automatically. On Windows systems, there is no canonical Time Zone Database installation, and so Jiff embeds it into the compiled artifact. (This does not happen on Unix by default.)

See the TimeZoneDatabase for more information.

The system or “local” time zone

In many cases, the operating system manages a “default” time zone. It might, for example, be how the date program converts a Unix timestamp to a time that is “local” to you.

Unfortunately, there is no universal approach to discovering a system’s default time zone. Instead, Jiff uses heuristics like reading /etc/localtime on Unix, and calling GetDynamicTimeZoneInformation on Windows. But in all cases, Jiff will always use the IANA Time Zone Database for implementing time zone transition rules. (For example, Windows specific APIs for time zone transitions are not supported by Jiff.)

Moreover, Jiff supports reading the TZ environment variable, as specified by POSIX, on all systems.

TO get the system’s default time zone, use TimeZone::system.

Structs

• AmbiguousTimestamp
  A possibly ambiguous Timestamp, created by TimeZone::to_ambiguous_timestamp.
• AmbiguousZoned
  A possibly ambiguous Zoned, created by TimeZone::to_ambiguous_zoned.
• Offset
  Represents a fixed time zone offset.
• OffsetArithmetic
  Options for Offset::checked_add and Offset::checked_sub.
• TimeZone
  A representation of a time zone.
• TimeZoneDatabase
  A handle to a IANA Time Zone Database.
• TimeZoneFollowingTransitions
  An iterator over time zone transitions going forward in time.
• TimeZoneNameIter
  An iterator over the time zone identifiers in a TimeZoneDatabase.
• TimeZonePrecedingTransitions
  An iterator over time zone transitions going backward in time.
• TimeZoneTransition
  A representation a single time zone transition.

Enums

• AmbiguousOffset
  A possibly ambiguous Offset.
• Disambiguation
  Configuration for resolving ambiguous datetimes in a particular time zone.
• Dst
  An enum indicating whether a particular datetime is in DST or not.
• OffsetConflict
  Configuration for resolving disparities between an offset and a time zone.

Functions

• db
  Returns a copy of the global TimeZoneDatabase.
• offset
  Creates a new time zone offset in a const context from a given number of hours.