Main types¶

The whenever library provides four main date-time types, each with its own purpose and behavior:

The available methods differ between these types based on whether they represent exact time or local time:

type	represents exact time?	represents local time?
`Instant`	✅	❌
`ZonedDateTime`	✅	✅
`OffsetDateTime`	✅	✅
`PlainDateTime`	❌	✅

Exact time methods¶

The exact time classes (Instant, ZonedDateTime, and OffsetDateTime) share several methods for working with exact points in time:

	`Instant`	`ZonedDateTime`	`OffsetDateTime`
`now()`	`🔗`	`🔗`	`🔗`

`timestamp()`	`🔗`	`🔗`	`🔗`
`from_timestamp()` [2]	`🔗`	deprecated, removed in 1.0	deprecated, removed in 1.0

`to_fixed_offset()`	`🔗`	`🔗`	`🔗`
`to_tz()`	`🔗`	`🔗`	`🔗`

`x > other_exact` [3]	`🔗`	`🔗`	`🔗`
`x - other_exact`	`🔗`	`🔗`	`🔗`
`x == other_exact`	`🔗`	`🔗`	`🔗`
`strict_eq()`	`🔗`	`🔗`	`🔗`

`x + TimeDelta`	`🔗`	`🔗`	`🔗`
`round()`	`🔗`	`🔗`	`🔗`

`to_stdlib()`	`🔗`	`🔗`	`🔗`

Timestamp conversion floors at the requested unit in both directions; see To and from timestamps.

Local time methods¶

The local time classes (PlainDateTime, ZonedDateTime, and OffsetDateTime) share several methods for working with local date and time values:

	`PlainDateTime`	`ZonedDateTime`	`OffsetDateTime`
`year`, `month`, etc.	`🔗`	`🔗`	`🔗`
`hour`, `minute`, etc.	`🔗`	`🔗`	`🔗`
`date()`	`🔗`	`🔗`	`🔗`
`time()`	`🔗`	`🔗`	`🔗`

`replace()`	`🔗`	`🔗`	`🔗`
`replace_date()`, `replace_time()`	`🔗`, `🔗`	`🔗`, `🔗`	`🔗`, `🔗`
`add()`, `subtract()`	`🔗`, `🔗`	`🔗`, `🔗`	`🔗`, `🔗`
`since()`, `until()`	`🔗`, `🔗`	`🔗`, `🔗`	`🔗`, `🔗`
`round()`	`🔗`	`🔗`	`🔗`

`start_of()`, `end_of()`	`🔗`, `🔗`	`🔗`, `🔗`	`🔗`, `🔗`

`day_of_week()`	`🔗`	`🔗`	`🔗`
`day_of_year()`	`🔗`	`🔗`	`🔗`
`days_in_month()`	`🔗`	`🔗`	`🔗`
`days_in_year()`	`🔗`	`🔗`	`🔗`
`in_leap_year()`	`🔗`	`🔗`	`🔗`

`to_stdlib()`	`🔗`	`🔗`	`🔗`

Each type’s replacement carries its own resolution: disambiguation= on ZonedDateTime, stale_offset_ok= on OffsetDateTime, and nothing on PlainDateTime. Instant has no replace(), because it has no local fields; see the FAQ.

Note

Although Instant’s debug representation is in UTC, it does not have local time methods. See the FAQ for more details.

Methods on all four types¶

Text in and out is shared by all four types; see ISO 8601 and Pattern format. So is difference(), the exact time between two values:

	`Instant`	`ZonedDateTime`	`OffsetDateTime`	`PlainDateTime`
`format_iso()`, `parse_iso()`	`🔗`, `🔗`	`🔗`, `🔗`	`🔗`, `🔗`	`🔗`, `🔗`
`format()`, `parse()`	`🔗`, `🔗`	`🔗`, `🔗`	`🔗`, `🔗`	`🔗`, `🔗`
`difference()`	`🔗`	`🔗`	`🔗`	`🔗`

Other methods¶

Several other methods are unique to one or more classes:

`Instant`	`ZonedDateTime`	`OffsetDateTime`	`PlainDateTime`
`MIN`, `MAX`			`MIN`, `MAX`
`from_utc()`
`add()`, `subtract()`			`x + TimeDelta`
`format_rfc2822()`, `parse_rfc2822()`		`format_rfc2822()`, `parse_rfc2822()`
	`to_instant()`	`to_instant()`
	`to_plain()`	`to_plain()`
	`offset`	`offset`
			`x == other_plain`
			`x > other_plain`
			`x - other_plain`
			`assume_utc()`
		`assume_tz()`	`assume_tz()`
			`assume_fixed_offset()`
	`tz_id`
	`is_repeated()`
	`dst_offset()`
	`tz_abbrev()`
	`day_length()`
	`next_transition()`
	`prev_transition()`

OffsetDateTime and ZonedDateTime have no MIN and MAX: their earliest and latest values depend on the offset or the time zone.

Note

from_utc() is the field constructor of Instant: Instant(2020, 1, 1) does not exist because it would silently mean UTC. See the FAQ.