Read off the zone rather than assumed, and from both sides, since time may be either the first or the second of the two occurrences. Most zones step back an hour; Lord Howe steps back half of one.

Source

local?(year : Int, month : Int, day : Int, hour : Int = 0, minute : Int = 0, second : Int = 0, *, nanosecond : Int = 0, location : Time::Location) : Time | Nil

Returns a Time carrying exactly the wall clock asked for, or nil where that wall clock does not exist.

A DST forward transition leaves a gap of local times that never occur, and Time.local silently resolves one of those to a neighbouring instant whose fields are no longer the ones asked for -- which in some zones even reads as the day before. A date the calendar does not hold at all (the 30th of February) is refused by Time.local outright, and answers nil just the same.

Source

refine_earliest(best : Time, floor : Time, passes : Int32, seeds : Time -> Array(Time), & : Time -> Time | Nil) : Time

Returns the earliest answer at or after floor that block can be brought to give, by re-asking it from the seeds seeds names for each answer in turn.

A VirtualTime fills a rule's unconstrained fields from the hint it is handed, so an answer overshoots whenever the hint carries more detail than the question: a rule naming only a month, asked from the 28th, lands on the 28th of that month rather than on its 1st. Re-asking from the start of the unit the answer fell in brings it back down, and a few rounds of it settle, each seed being coarser than the detail it corrects.

Source

same_wall_clock?(a : Time, b : Time) : Bool

Returns whether the two carry the same wall clock, whatever offset each reads it with.

Source

transition_between(earlier : Time, later : Time) : Time | Nil

Returns the instant at which the UTC offset changes between earlier and later, or nil when the two carry the same offset.

The search runs down to the nanosecond rather than stopping a second short: the result is used both to build materialization hints and to bound stretches of matching time, and a stray fraction of a second in it would carry all the way up through the fields worked out from it.

Source

week(time : Time)

Returns ISO week number (1..53) of specified time

Source

week(time : VirtualTime)

Returns ISO week number (1..53) of specified time

Source

weeks_in_iso_year(year : Int, location : Time::Location) : Int32

Returns the number of weeks -- 52 or 53 -- in the given ISO year.

A year has 53 weeks when it begins on a Thursday, or when it is a leap year beginning on a Wednesday. 2020 was such a year.

Source

weeks_in_year(time : Time)

Returns the number of weeks (52 or 53) in the ISO year that time falls in.

Note that this is the ISO year, which is what Time#calendar_week (and therefore .week) counts weeks within: the first days of January can still belong to the previous ISO year, and the last days of December to the next one.

Source