DateTimeZone.SwitchZone
Moves a datetime with a time zone to a different fixed zone offset, given in hours and optional minutes.
DateTimeZone.SwitchZone(dateTimeZone as datetimezone, hours as number, optional minutes as nullable number) as datetimezoneReturns: The same moment shown in the new offset, as a datetime with a time zone value.
What it does
DateTimeZone.SwitchZone shows a moment in another time zone by applying a fixed offset. A timestamp of 22:00 UTC becomes 14:00 at an offset of minus eight hours. The important limit is that the offset is fixed. It does not follow daylight saving time, so a zone that changes its clock twice a year needs a different offset in summer and in winter.
Syntax and arguments
- dateTimeZone: a datetime with a time zone, such as a UTC timestamp.
- hours: the offset in hours. Pacific standard time is -8, and Eastern standard time is -5.
- minutes (optional): extra minutes for an offset that is not a whole number of hours.
Example
A bank reports payments in UTC. The controller wants to see which payments were received on the local business day in Pacific time, during a winter month when the Pacific offset is minus eight hours.
let
Payment = #datetimezone(2026, 1, 15, 22, 0, 0, 0, 0, 0),
Pacific = DateTimeZone.SwitchZone(Payment, -8),
LocalDateTime = DateTime.From(Pacific),
LocalDate = DateTime.Date(LocalDateTime)
in
{LocalDateTime, LocalDate}
22:00 UTC on January 15, 2026 is 14:00 in Pacific standard time on the same day, so the payment belongs to January 15 for the local business day. The same UTC time in late October would be in daylight saving time, when Pacific is minus seven, so the offset would need to change.
Example: a second, different use
Convert a UTC timestamp to Eastern time in winter, using minus five hours, before grouping the transactions by day.
Things to watch
- The offset does not follow daylight saving. In summer, Pacific time is minus seven, so a fixed minus eight is an hour wrong for part of the year.
- For a report that spans a daylight saving change, split the data by date and apply the right offset to each part, or convert in the source system.
- A fixed offset is fine for a single month when you know which offset applies.
- Check the result against a known transaction before you rely on it.
In business terms
Cut-off testing for international payments and bank files depends on the local date of each transaction. A wrong offset moves a payment to the wrong day, which is exactly the kind of error that auditors test for at period end.