Struct TimeZoneAnnotation

struct TimeZoneAnnotation<'n> { ... }

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

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

fn into_owned(self: 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.

impl From for TimeZoneAnnotation<'static>

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

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

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

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

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

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

impl<'n> Freeze for TimeZoneAnnotation<'n>

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

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

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

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

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

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

impl<'n> RefUnwindSafe for TimeZoneAnnotation<'n>

impl<'n> Send for TimeZoneAnnotation<'n>

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

impl<'n> Sync for TimeZoneAnnotation<'n>

impl<'n> Unpin for TimeZoneAnnotation<'n>

impl<'n> UnsafeUnpin for TimeZoneAnnotation<'n>

impl<'n> UnwindSafe for TimeZoneAnnotation<'n>

impl<T> Any for TimeZoneAnnotation<'n>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for TimeZoneAnnotation<'n>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for TimeZoneAnnotation<'n>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> CloneToUninit for TimeZoneAnnotation<'n>

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for TimeZoneAnnotation<'n>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for TimeZoneAnnotation<'n>

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

impl<T, U> Into for TimeZoneAnnotation<'n>

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for TimeZoneAnnotation<'n>

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for TimeZoneAnnotation<'n>

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>