Specify Time Zones
In MATLAB®, you can specify time zones for datetime
arrays. This example shows how to create and work with datetime arrays that include time zones.
A time zone is a geographic area that observes a uniform standard time. Time zones include time offsets from Coordinated Universal Time (UTC), time offsets from daylight saving time (DST), and a set of historical changes to those offsets. To set a time zone and calculate time zone offsets, the datetime
data type uses code and data provided by the Internet Assigned Numbers Authority (IANA) in the IANA Time Zone Database.
Display and Search Table of Time Zones
To see a complete table of time zones that are known to MATLAB, use the timezones
function. Every row of the table shows the name of a time zone, its geographic area, its offset from UTC, and its offset due to DST. For time zones that observe DST, the DST offset is applied according to the current and historical rules for those time zones.
AllTimeZones = timezones
AllTimeZones=446×4 table
Name Area UTCOffset DSTOffset
______________________ ______ _________ _________
{'Africa/Abidjan' } Africa 0 0
{'Africa/Accra' } Africa 0 0
{'Africa/Addis_Ababa'} Africa 3 0
{'Africa/Algiers' } Africa 1 0
{'Africa/Asmera' } Africa 3 0
{'Africa/Bamako' } Africa 0 0
{'Africa/Bangui' } Africa 1 0
{'Africa/Banjul' } Africa 0 0
{'Africa/Bissau' } Africa 0 0
{'Africa/Blantyre' } Africa 2 0
{'Africa/Brazzaville'} Africa 1 0
{'Africa/Bujumbura' } Africa 2 0
{'Africa/Cairo' } Africa 2 1
{'Africa/Casablanca' } Africa 0 1
{'Africa/Ceuta' } Africa 1 1
{'Africa/Conakry' } Africa 0 0
⋮
To see the version of the IANA Time Zone Database that MATLAB uses, return the second output from timezones
.
[~,DBversion] = timezones
DBversion = '2024a'
To find the name of a time zone, you can search the Name
variable of the table of time zones. To find the whole name when you know part of the name, you can use the contains
function. For example, find the name of the time zone that corresponds to New York. Replace space characters with underscores in your search string.
TFindex = contains(AllTimeZones.Name,"New_York");
NewYorkZone = AllTimeZones.Name(TFindex)
NewYorkZone = 1x1 cell array
{'America/New_York'}
Display the corresponding row of the time zones table. To match the exact name of the time zone, use the matches
function.
TFindex = matches(AllTimeZones.Name,NewYorkZone); AllTimeZones(TFindex,:)
ans=1×4 table
Name Area UTCOffset DSTOffset
____________________ _______ _________ _________
{'America/New_York'} America -5 1
Create datetime
Values with Time Zones
Every datetime
array has a time zone property. By default, this property is not set, which means the resulting datetime
array is unzoned. You can use unzoned datetime
arrays for local time calculations in which you do not need to consider DST or local times in other time zones.
For example, create a datetime
value for the current time, and display its TimeZone
property. The current date and time values come from your system clock. Without a time zone, the datetime
value cannot calculate the time zone offset relative to UTC.
D = datetime("now")
D = datetime
05-Sep-2024 14:54:33
D.TimeZone
ans = 0x0 empty char array
There are two ways to set the time zone of a datetime
array. The first way is to specify the TimeZone
name-value argument of the datetime
function when creating the datetime
array. Specifying this argument sets the value of the TimeZone
property.
D = datetime("now",TimeZone="America/New_York")
D = datetime
05-Sep-2024 14:54:33
D.TimeZone
ans = 'America/New_York'
The second way is to assign a value to the TimeZone
property after you have created the datetime
array.
D = datetime("now")
D = datetime
05-Sep-2024 14:54:33
D.TimeZone = "America/New_York"
D = datetime
05-Sep-2024 14:54:33
You can also specify the TimeZone
property as a duration that is just a fixed time zone offset from UTC. Such an offset does not incorporate any current or historical offset rules, such as daylight saving time.
For example, specify a time zone offset that is five hours behind UTC. This offset is the same as the UTC offset for America/New_York
, but it does not include any offset for daylight saving time.
D = datetime("now",TimeZone="-05:00")
D = datetime
05-Sep-2024 13:54:33
D.TimeZone
ans = '-05:00'
You can specify TimeZone
as any value in this list:
""
— No time zoneTime zone name — Time zone from IANA Time Zone Database
Time zone offset in
+HH:mm
or-HH:mm
format — Fixed offset from UTCTime zone offset as
duration
scalar (since R2024a) — Fixed offset from UTC, specified using thehours
,minutes
,seconds
, orduration
function"UTC"
— Coordinated Universal Time"UTCLeapSeconds"
— Coordinated Universal Time, but also incorporating leap seconds"local"
— IANA time zone that corresponds to the system time zone
Specify Formats That Include Time Zone Offsets
The default format for datetime
arrays does not include the time zone. However, you can include the time zone offset in the format by using the z
or Z
identifiers.
For example, change the format to include the date, time, and time zone offset using z
. The z
identifier specifies the short localized version of the offset. Its behavior depends on your locale.
D = datetime("now", ... TimeZone="America/New_York", ... Format="dd-MMM-uuuu HH:mm:ss z")
D = datetime
05-Sep-2024 14:54:33 EDT
The Z
identifier specifies a basic format that displays the offset as hours, minutes, and optionally seconds.
D.Format = "dd-MMM-uuuu HH:mm:ss Z"
D = datetime
05-Sep-2024 14:54:33 -0400
You can also specify the long UTC format. For a complete list of time zone offset identifiers, see datetime
.
D.Format = "dd-MMM-uuuu HH:mm:ss ZZZZ"
D = datetime
05-Sep-2024 14:54:33 UTC-04:00
Encode Same Time in Different Time Zone
If you change the time zone of a datetime
value, it still encodes the same point in time. If the offset from UTC changes, then the date and time values change in a way that compensates for the change in the offset.
For example, create a datetime
value in the New York time zone, and format it to display the time zone offset.
D = datetime("today", ... TimeZone="America/New_York", ... Format="dd-MMM-uuuu HH:mm:ss z")
D = datetime
05-Sep-2024 00:00:00 EDT
Then change its time zone to the zone for Los Angeles. The date and time values change to encode the same point in time in a different time zone.
D.TimeZone = "America/Los_Angeles"
D = datetime
04-Sep-2024 21:00:00 PDT
Compare datetime
Values with Different Time Zones
If you compare datetime
values that have different time zones, then the comparison takes the time zone offsets into account. However, you cannot compare zoned and unzoned datetime
arrays because an unzoned array has no known time zone offset. Both arrays must be zoned or unzoned.
For example, create a datetime
value. Then copy it and change its time zone.
NYTime = datetime("today", ... TimeZone="America/New_York", ... Format="dd-MMM-uuuu HH:mm:ss z")
NYTime = datetime
05-Sep-2024 00:00:00 EDT
LATime = NYTime;
LATime.TimeZone = "America/Los_Angeles"
LATime = datetime
04-Sep-2024 21:00:00 PDT
Compare the two values using the ==
operator. The values are equal because they encode the same point in time.
AreTimesEqual = NYTime == LATime
AreTimesEqual = logical
1
There is no actual difference between the two times.
TimeDiff = LATime - NYTime
TimeDiff = duration
00:00:00
Then add two hours to the Los Angeles time.
LATime = LATime + hours(2)
LATime = datetime
04-Sep-2024 23:00:00 PDT
Compare the two times. Despite their date and time values, the time in Los Angeles occurs later than the time in New York.
IsLATimeLater = LATime > NYTime
IsLATimeLater = logical
1
The difference between the times is two hours.
TimeDiff = LATime - NYTime
TimeDiff = duration
02:00:00
Concatenate datetime
Arrays with Different Time Zones
The TimeZone
property applies to every element in a datetime
array. However, you can concatenate datetime
arrays that have different time zones. The concatenated array has the same time zone as the first array. You cannot concatenate zoned and unzoned datetime
arrays because the unzoned array has no known time zone offset. Both arrays must be zoned or unzoned.
For example, concatenate NYTime
and LATime
. The result has the time zone for New York.
combinedNYZone = [NYTime LATime]
combinedNYZone = 1x2 datetime
05-Sep-2024 00:00:00 EDT 05-Sep-2024 02:00:00 EDT
Then concatenate in the reverse order. The result has the time zone for Los Angeles.
combinedLAZone = [LATime NYTime]
combinedLAZone = 1x2 datetime
04-Sep-2024 23:00:00 PDT 04-Sep-2024 21:00:00 PDT
Account for Leap Seconds Using Special Time Zone
A leap second is a one-second adjustment that is applied to UTC. Leap seconds were introduced in 1972 to account for the difference between precise time based on atomic clocks and observed solar time, which varies due to small changes in earth's rotation rate. Those changes do not come in a predictable pattern, so leap seconds have been declared as needed. The leap second data incorporated into MATLAB is provided by the International Earth Rotation and Reference Systems Service (IERS). For more information, see the IERS Bulletins.
The datetime
data type has a special time zone that accounts for leap seconds. For any calculations or comparisons that involve leap seconds, specify the time zone as "UTCLeapSeconds"
. When you use this time zone, the default format includes the date, time, and the letter Z
to indicate UTC, according to the ISO 8601 standard.
todayLS = datetime("today",TimeZone="UTCLeapSeconds")
todayLS = datetime
2024-09-05T00:00:00.000Z
You cannot combine or compare datetime
arrays when one array has leap seconds and the other array does not.
One way to see the effect of leap seconds is to calculate the length of time between today's date and January 1, 1972, in the UTC
and UTCLeapSeconds
time zones. First calculate the duration in the UTC
zone. The duration is shown in hh:mm:ss
format.
durationWithoutLS = datetime("today",TimeZone="UTC") - datetime(1972,1,1,TimeZone="UTC")
durationWithoutLS = duration
461784:00:00
Then calculate the duration in the UTCLeapSeconds
zone. The difference between the two durations is due to the cumulative effect of the leap seconds declared since 1972.
durationWithLS = datetime("today",TimeZone="UTCLeapSeconds") - datetime(1972,1,1,TimeZone="UTCLeapSeconds")
durationWithLS = duration
461784:00:27
To see all the leap seconds known to MATLAB and the dates they were declared, use the leapseconds
function.
LS = leapseconds
LS=27×2 timetable
Date Type CumulativeAdjustment
___________ ____ ____________________
30-Jun-1972 + 1 sec
31-Dec-1972 + 2 sec
31-Dec-1973 + 3 sec
31-Dec-1974 + 4 sec
31-Dec-1975 + 5 sec
31-Dec-1976 + 6 sec
31-Dec-1977 + 7 sec
31-Dec-1978 + 8 sec
31-Dec-1979 + 9 sec
30-Jun-1981 + 10 sec
30-Jun-1982 + 11 sec
30-Jun-1983 + 12 sec
30-Jun-1985 + 13 sec
31-Dec-1987 + 14 sec
31-Dec-1989 + 15 sec
31-Dec-1990 + 16 sec
⋮
The second output returns the IERS Bulletin C version number of the leap second data used in MATLAB.
[~,LSvers] = leapseconds
LSvers = 67
See Also
datetime
| timezones
| leapseconds