Struct TimeBucket

Source

pub struct TimeBucket { /* private fields */ }

Expand description

A bucket width together with the calendar it is read against.

See the module documentation for what each width means.

Implementations§

Source §

impl TimeBucket

Source

pub const fn utc(width: BucketWidth) -> Self

A bucket of width, read against UTC.

Source

pub const fn fixed_ns(ns: i64) -> Self

A fixed span of nanoseconds against UTC.

Source

pub fn fixed(span: Duration) -> Self

A fixed span, from a Duration.

A Duration is a fixed span, so this conversion loses nothing — which is exactly why it cannot produce a calendar bucket. For a day in a zone or a calendar month, say so by name: parse with "1d" or "1mo".

Saturates at i64::MAX nanoseconds, about 292 years.

Source

pub const fn in_zone(self, tz: Tz) -> Self

Read this bucket against an IANA time zone.

Source

pub fn with_origin(self, origin: i64) -> Result<Self, BucketParseError>

Align bucket boundaries to origin instead of the default anchor.

The origin is an instant in epoch nanoseconds; what is taken from it is its local position in this bucket’s zone:

a fixed width takes the whole instant, and buckets tile outwards from it in both directions;
a day or week width takes the origin’s local time of day, so a 1d bucket runs 06:00 → 06:00 for a shift that starts at six;
a month or year width takes its local day of month and time of day, so a 1mo bucket runs from the 15th to the 15th for a billing period that starts then.

The origin may sit before, inside or after the data — only where it falls in the cycle matters, not how far away it is. For a width of one unit that is just the phase, so any date with the right time of day (or day of month) will do. For a multi-unit width it also selects which of the n units opens a bucket: 3mo anchored on January gives calendar quarters, anchored on February gives February–April.

It replaces the default anchor entirely, so a 1w bucket with an origin no longer starts on a Monday unless the origin does.

§Errors

BucketParseError if the origin’s local day of month is 29, 30 or 31 for a month or year width. Those days do not exist in every month, so such a boundary is not a monthly one: it would have to be clamped, and a clamp makes the buckets drift (31 January → 28 February → 28 March) or stop being a fixed day of the month. A month-end boundary is a different question this type does not answer.

Source

pub fn with_origin_str(self, text: &str) -> Result<Self, BucketParseError>

Align boundaries to an origin written as text.

Accepts an RFC 3339 instant (2024-01-15T06:00:00+01:00), or a local wall-clock time read in this bucket’s zone: 2024-01-15, 2024-01-15 06:00:00, or 2024-01-15T06:00:00. A bare date is local midnight.

Reading it in the bucket’s own zone is the point: “the billing month starts on the 15th” means the local 15th, and a caller who writes 2024-01-15 against a Europe/Berlin tier means Berlin’s.

§Errors

BucketParseError if the text is not one of those forms, if it is outside the representable range, or if Self::with_origin refuses the resulting day of month.

Source

pub const fn origin(&self) -> Option<i64>

The instant this bucket’s boundaries are aligned to, if any.

Source

pub fn parse( width: &str, timezone: Option<&str>, ) -> Result<Self, BucketParseError>

Parse a width, and optionally a zone.

§Errors

BucketParseError if the width or the zone name is not understood.

Source

pub const fn width(&self) -> BucketWidth

This bucket’s width.

Source

pub fn timezone(&self) -> Option<&'static str>

The IANA zone this bucket is read against, if any.

Source

pub fn nominal_ns(&self) -> i64

Roughly how long a bucket is — see BucketWidth::nominal_ns.

Source

pub fn is_calendar(&self) -> bool

Whether a bucket’s length can vary between one bucket and the next.

True for a calendar width in any zone (February is short in UTC too), and for a day only where a zone has transitions.

Source

pub fn start_of(&self, ts: i64) -> i64

The start of the bucket containing ts.

Source

pub fn next(&self, bucket_start: i64) -> i64

The start of the bucket after the one starting at bucket_start.

Never bucket_start + width. A calendar bucket’s length depends on which bucket it is: February is three days shorter than March, and a local day is 23 or 25 hours on a transition. Code that adds is code that has assumed the calendar away.