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)),
);

Implementations

impl<'n> TimeZoneAnnotation<'n>

pub 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"),
);

pub 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()),
);

pub 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",
);

pub 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.

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_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(),
);

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

Converts this time zone annotation into an “owned” value whose lifetime is 'static.

If this was already an “owned” value or a time zone annotation offset, then this is a no-op.

Trait Implementations

impl<'n> Clone for TimeZoneAnnotation<'n>

fn clone(&self) -> TimeZoneAnnotation<'n>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'n> Debug for TimeZoneAnnotation<'n>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'n> From<&'n str> for TimeZoneAnnotation<'n>

fn from(string: &'n str) -> TimeZoneAnnotation<'n>

Converts to this type from the input type.

impl From<Offset> for TimeZoneAnnotation<'static>

fn from(offset: Offset) -> TimeZoneAnnotation<'static>

Converts to this type from the input type.

impl<'n> Hash for TimeZoneAnnotation<'n>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'n> PartialEq for TimeZoneAnnotation<'n>

fn eq(&self, other: &TimeZoneAnnotation<'n>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'n> Eq for TimeZoneAnnotation<'n>

impl<'n> StructuralPartialEq for TimeZoneAnnotation<'n>