Struct `TimeZoneAnnotation`

pub struct TimeZoneAnnotation<'n> { /* private fields */ }

An RFC 9557 time zone annotation, for use with Pieces.

A time zone annotation is either a time zone name (typically an IANA time zone identifier) like America/New_York, or an offset like -05:00. This is normally an implementation detail of parsing into a Zoned, but the raw annotation can be accessed via Pieces::time_zone_annotation after parsing into a Pieces.

The lifetime parameter refers to the lifetime of the time zone name. The lifetime is static when the time zone annotation is offset or if the name is owned. An owned value can be produced via TimeZoneAnnotation::into_owned when the alloc crate feature is enabled.

Construction

If you're using Pieces, then its Pieces::with_time_zone_name and Pieces::with_time_zone_offset methods should absolve you of needing to build values of this type explicitly. But if the need arises, there are From impls for &str (time zone annotation name) and Offset (time zone annotation offset) for this type.

Example

use jiff::{fmt::temporal::{Pieces, TimeZoneAnnotation}, tz::offset};

// A time zone annotation from a name:
let pieces = Pieces::parse("2025-01-02T16:47-05[America/New_York]")?;
assert_eq!(
    pieces.time_zone_annotation().unwrap(),
    &TimeZoneAnnotation::from("America/New_York"),
);

// A time zone annotation from an offset:
let pieces = Pieces::parse("2025-01-02T16:47-05[-05:00]")?;
assert_eq!(
    pieces.time_zone_annotation().unwrap(),
    &TimeZoneAnnotation::from(offset(-5)),
);

# Ok::<(), Box<dyn std::error::Error>>(())

Implementations

`impl<'n> TimeZoneAnnotation<'n>`

fn kind(&self) -> &TimeZoneAnnotationKind<'n>

Returns the "kind" of this annotation. The kind is either a name or an offset.

Example

use jiff::fmt::temporal::{Pieces, TimeZoneAnnotation};

// A time zone annotation from a name, which doesn't necessarily have
// to point to a valid IANA time zone.
let pieces = Pieces::parse("2025-01-02T16:47-05[Australia/Bluey]")?;
assert_eq!(
    pieces.time_zone_annotation().unwrap(),
    &TimeZoneAnnotation::from("Australia/Bluey"),
);

# Ok::<(), Box<dyn std::error::Error>>(())

fn is_critical(&self) -> bool

Returns true when this time zone is marked as "critical." This occurs when the time zone annotation is preceded by a !. It is meant to signify that, basically, implementations should error if the annotation is invalid in some way. And when it's absent, it's left up to the implementation's discretion about what to do (including silently ignoring the invalid annotation).

Generally speaking, Jiff ignores this altogether for time zone annotations and behaves as if it's always true. But it's exposed here for callers to query in case it's useful.

Example

use jiff::fmt::temporal::{Pieces, TimeZoneAnnotation};

// not critical
let pieces = Pieces::parse("2025-01-02T16:47-05[Australia/Bluey]")?;
assert_eq!(
    Some(false),
    pieces.time_zone_annotation().map(|a| a.is_critical()),
);

// critical
let pieces = Pieces::parse("2025-01-02T16:47-05[!Australia/Bluey]")?;
assert_eq!(
    Some(true),
    pieces.time_zone_annotation().map(|a| a.is_critical()),
);

# Ok::<(), Box<dyn std::error::Error>>(())

fn to_time_zone(&self) -> Result<TimeZone, Error>

A convenience routine for converting this annotation into a time zone.

This can fail if the annotation contains a name that couldn't be found in the global time zone database. If you need to use something other than the global time zone database, then use TimeZoneAnnotation::to_time_zone_with.

Note that it may be more convenient to use Pieces::to_time_zone.

Example

use jiff::{fmt::temporal::Pieces, tz::TimeZone};

let pieces = Pieces::parse("2025-01-02T16:47-05[Australia/Tasmania]")?;
let ann = pieces.time_zone_annotation().unwrap();
assert_eq!(
    ann.to_time_zone().unwrap(),
    TimeZone::get("Australia/Tasmania").unwrap(),
);

let pieces = Pieces::parse("2025-01-02T16:47-05[Australia/Bluey]")?;
let ann = pieces.time_zone_annotation().unwrap();
assert_eq!(
    ann.to_time_zone().unwrap_err().to_string(),
    "failed to find time zone `Australia/Bluey` in time zone database",
);

# Ok::<(), Box<dyn std::error::Error>>(())

fn to_time_zone_with(&self, db: &TimeZoneDatabase) -> Result<TimeZone, Error>

This is like TimeZoneAnnotation::to_time_zone, but permits the caller to pass in their own time zone database.

Note that it may be more convenient to use Pieces::to_time_zone_with.

Example

use jiff::{fmt::temporal::Pieces, tz::TimeZone};

let pieces = Pieces::parse("2025-01-02T16:47-05[Australia/Tasmania]")?;
let ann = pieces.time_zone_annotation().unwrap();
assert_eq!(
    ann.to_time_zone_with(jiff::tz::db()).unwrap(),
    TimeZone::get("Australia/Tasmania").unwrap(),
);

# Ok::<(), Box<dyn std::error::Error>>(())

fn into_owned(self) -> TimeZoneAnnotation<'static>