DateTimeZone.SwitchZone
DateTimeZoneAdjusts a datetimezone value to a different UTC offset while preserving the instant in time.
Syntax
DateTimeZone.SwitchZone(dateTimeZone as nullable datetimezone, timezoneHours as number, optional timezoneMinutes as nullable number) as nullable datetimezoneParameters
| Name | Type | Required | Description |
|---|---|---|---|
dateTimeZone | datetimezone | Yes | The datetimezone value to convert to a new timezone. |
timezoneHours | number | Yes | The hour component of the target UTC offset (e.g., -5 for EST, 1 for CET). |
timezoneMinutes | number | No | The minutes component of the target UTC offset. Defaults to 0. Use 30 for offsets like UTC+5:30. |
Return Value
datetimezone — A datetimezone value representing the same instant in time expressed with the new UTC offset.
Remarks
DateTimeZone.SwitchZone converts a datetimezone value to a new UTC offset while preserving the absolute point in time (the underlying UTC moment). The date and time components are adjusted accordingly. For example, switching 2024-03-15T14:30:00+05:00 to UTC+0 yields 2024-03-15T09:30:00+00:00 — the same instant expressed in a different timezone.
This is the key difference from DateTime.AddZone, which merely annotates a datetime with an offset without adjusting the time. Use DateTimeZone.SwitchZone when you need to convert between timezones (preserving the instant), and use DateTime.AddZone when you need to label a datetime that already represents local time in the target zone.
Use the optional timezoneMinutes parameter for non-whole-hour offsets such as UTC+5:30 (India Standard Time), UTC+9:30 (Australian Central Standard Time), or UTC+5:45 (Nepal Time). A common normalization pattern is switching all datetimezone values to +00:00 (UTC) for consistent storage and comparison, then switching to a display timezone on demand.
Examples
Example 1: Normalize mixed timezone timestamps to UTC
#table(
type table [Original = datetimezone, AsUTC = datetimezone],
{
{#datetimezone(2024, 3, 15, 8, 30, 0, -5, 0), DateTimeZone.SwitchZone(#datetimezone(2024, 3, 15, 8, 30, 0, -5, 0), 0)},
{#datetimezone(2024, 3, 15, 14, 0, 0, 1, 0), DateTimeZone.SwitchZone(#datetimezone(2024, 3, 15, 14, 0, 0, 1, 0), 0)},
{#datetimezone(2024, 3, 16, 9, 15, 0, 5, 30), DateTimeZone.SwitchZone(#datetimezone(2024, 3, 16, 9, 15, 0, 5, 30), 0)}
}
)Original | AsUTC | |
|---|---|---|
| 1 | 3/15/2024 1:30:00 PM | 3/15/2024 1:30:00 PM |
| 2 | 3/15/2024 1:00:00 PM | 3/15/2024 1:00:00 PM |
| 3 | 3/16/2024 3:45:00 AM | 3/16/2024 3:45:00 AM |
Example 2: Switch to a specific offset
#table(
type table [NewYork = datetimezone, Tokyo = datetimezone],
{{#datetimezone(2024, 3, 15, 9, 0, 0, -5, 0),
DateTimeZone.SwitchZone(#datetimezone(2024, 3, 15, 9, 0, 0, -5, 0), 9)}}
)NewYork | Tokyo | |
|---|---|---|
| 1 | 3/15/2024 2:00:00 PM | 3/15/2024 2:00:00 PM |
Example 3: Switch to a half-hour offset (India Standard Time)
#table(
type table [UTC = datetimezone, IST = datetimezone],
{{#datetimezone(2024, 3, 15, 8, 0, 0, 0, 0),
DateTimeZone.SwitchZone(#datetimezone(2024, 3, 15, 8, 0, 0, 0, 0), 5, 30)}}
)UTC | IST | |
|---|---|---|
| 1 | 3/15/2024 8:00:00 AM | 3/15/2024 8:00:00 AM |