Struct WeekdayTimePeriod 

pub struct WeekdayTimePeriod<Tz>
where
    Tz: TimeZone,
{
    start: NaiveWeekdayTime,
    end: NaiveWeekdayTime,
    tz: Tz,
}

Available on crate feature time only.

A half-open time period within a week.

This type represents a time period that occurs weekly. For example, it can represent “Monday 09:00 to Tuesday 17:00”.

The period is defined as [start, end) (start is inclusive and end is exclusive).

The word “period” is used here instead of “interval” to avoid confusion with Interval, which represents an absolute range between two fixed points in time.

There’s no ISO 8601 equivalent for this type.

Format

The string representation is in the format <start>/<end> <offset>. <start> and <end> are in the format defined by NaiveWeekdayTime, which is <weekday>-<time>. <offset> is a fixed offset in the format ±HH:MM.

Wrapping behavior

Since the period recurs weekly, it is allowed to wrap around the end of the week. For example, the period Fri-18:00/Mon-06:00 +00:00 is valid and represents a time range that spans the weekend.

Normal period

In this case start < end, which means the period is within a single week.

For example, Tue-09:00/Sun-22:00 +00:00 spans from Tuesday 9 AM to Sunday 10 PM. Here’s a visual representation:

 |        Week 1        |        Week 2        |
Mon  Tue     Sat  Sun  Mon  Tue     Sat  Sun  Mon  Tue
-|----+--...--+----+----|----+--...--+----+----|----+-
 |    ^            ^    |                      |
 |  start         end   |                      |

The repeating nature of the period is not shown in this diagram for clarity.

Wrapping period

If start >= end, the time range wraps around. It starts in one week and ends in the next.

For example, Sat-12:00/Tue-15:00 +00:00 spans from Saturday 12 PM to the following Tuesday 3 PM. Here’s the visual representation again:

 |        Week 1        |        Week 2        |
Mon  Tue     Sat  Sun  Mon  Tue     Sat  Sun  Mon  Tue
-|----+--...--+----+----|----+--...--+----+----|----+-
 |            ^         |    ^                 |
 |          start       |   end                |

The repeating nature of the period is not shown in this diagram for clarity.

Periods with start == end are called “full-week periods” and represent the entire week. All full-week periods are equivalent.

You might be tempted to think that the endpoint should not be included for full-week periods. The period is half-open, after all. Keep in mind that the period repeats weekly, so the endpoint is effectively included since it is the start of the next period.

It’s impossible to represent an empty period.

Time zone handling

Due to the messy nature of time zones (daylight saving time, historical changes, etc.), this type currently only supports fixed offset time zones for most operations.

Fields

start: NaiveWeekdayTime

end: NaiveWeekdayTime

tz: Tz

Implementations

impl<Tz> WeekdayTimePeriod<Tz>

where Tz: TimeZone,

pub const fn new( start: NaiveWeekdayTime, end: NaiveWeekdayTime, timezone: Tz, ) -> WeekdayTimePeriod<Tz>

Creates a new weekday time period from its components.

See the type documentation for details about the period semantics.

pub const fn timezone(&self) -> &Tz

Returns the associated time zone.

pub fn is_full_week(&self) -> bool

Returns whether the period represents the full week.

See the type documentation for details.

impl WeekdayTimePeriod<FixedOffset>

pub const fn new_fixed( start: NaiveWeekdayTime, end: NaiveWeekdayTime, offset: FixedOffset, ) -> WeekdayTimePeriod<FixedOffset>

Creates a new weekday time period with a fixed offset timezone.

See the type documentation for details about the period semantics.

pub fn start_utc(&self) -> NaiveWeekdayTime

Returns the start time in UTC.

This is only implemented for WeekdayTimePeriod<FixedOffset> because for the general case the start time in UTC will vary depending on the date.

pub fn end_utc(&self) -> NaiveWeekdayTime

Returns the end time in UTC.

See the explanation in start_utc for why this is only implemented for WeekdayTimePeriod<FixedOffset>.

impl WeekdayTimePeriod<FixedOffset>

pub fn interval_in_week(&self, week: &IsoWeek) -> Option<Interval<FixedOffset>>

Returns the earliest interval that overlaps with the given week.

If the resulting interval is unrepresentable, returns None. This can happen if the week is at the extreme ends of the date range.

For a non-wrapping period, this is the only interval in the given week. For a wrapping period, each week contains two intervals. One that starts in the previous week and ends in the current week, and one that starts in the current week and ends in the next week. This function returns the former since by definition it is the earliest interval.

In other words, this function returns the interval that ends in the given week.

Example

use hb_time::{
    Datelike as _, FixedOffset, NaiveDate, NaiveTime, NaiveWeekdayTime, Weekday,
    WeekdayTimePeriod,
};

let period = WeekdayTimePeriod::new_fixed(
    NaiveWeekdayTime::new(Weekday::Mon, NaiveTime::from_hms_opt(9, 0, 0).unwrap()),
    NaiveWeekdayTime::new(Weekday::Tue, NaiveTime::from_hms_opt(12, 0, 0).unwrap()),
    FixedOffset::east_opt(0).unwrap(),
);

// 2025-09-22 is a Monday
let week = NaiveDate::from_ymd_opt(2025, 9, 22).unwrap().iso_week();
let interval = period.interval_in_week(&week).unwrap();

// Since this is a non-wrapping period, the interval starts at Mon 09:00 ...
assert_eq!(
    interval.start().naive_utc().date(),
    NaiveDate::from_ymd_opt(2025, 9, 22).unwrap()
);
assert_eq!(
    interval.start().time(),
    NaiveTime::from_hms_opt(9, 0, 0).unwrap()
);

// ... and ends at Tue 12:00
assert_eq!(
    interval.end().naive_utc().date(),
    NaiveDate::from_ymd_opt(2025, 9, 23).unwrap()
);
assert_eq!(
    interval.end().time(),
    NaiveTime::from_hms_opt(12, 0, 0).unwrap()
);

pub fn interval_for_datetime( &self, dt: DateTime<FixedOffset>, ) -> Option<Interval<FixedOffset>>

Returns the first interval that ends after the given datetime.

If the datetime falls within an interval, that interval is returned. Otherwise, the next one is returned. This means that the datetime is either strictly inside of the returned interval, or ahead of it.

Returns None if the interval is unrepresentable. This only happens if the dt is already at the edge of the representable range.

Trait Implementations

impl<Tz> Clone for WeekdayTimePeriod<Tz>

where Tz: Clone + TimeZone,

fn clone(&self) -> WeekdayTimePeriod<Tz>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for WeekdayTimePeriod<FixedOffset>

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for WeekdayTimePeriod<FixedOffset>

fn deserialize<D>( deserializer: D, ) -> Result<WeekdayTimePeriod<FixedOffset>, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for WeekdayTimePeriod<FixedOffset>

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

Formats the value using the given formatter.

impl FromStr for WeekdayTimePeriod<FixedOffset>

type Err = ParseError

The associated error which can be returned from parsing.

fn from_str( s: &str, ) -> Result<WeekdayTimePeriod<FixedOffset>, <WeekdayTimePeriod<FixedOffset> as FromStr>::Err>

Parses a string s to return a value of this type.

impl PartialEq for WeekdayTimePeriod<FixedOffset>

fn eq(&self, other: &WeekdayTimePeriod<FixedOffset>) -> 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 Serialize for WeekdayTimePeriod<FixedOffset>

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for WeekdayTimePeriod<FixedOffset>