datetime - Arrays that represent points in time - MATLAB (original) (raw)

Arrays that represent points in time

Description

The datetime data type represents points in time, such as August 24, 2020, 10:50:30 a.m. A datetime array specifies the year, month, day, hour, minute, and second components associated with each point in time stored in the array (using the proleptic ISO calendar).

Also, datetime arrays provide:

• Flexible formats for both output display and input text parsing.
• Storage for fractional seconds out to nanosecond precision.
• Properties to account for time zones, daylight saving time, and leap seconds.

Creation

Syntax

Description

`t` = datetime returns a scalardatetime array corresponding to the current date and time.

`t` = datetime([relativeDay](#d126e368165)) uses the date specified by relativeDay. TherelativeDay input can be 'today','tomorrow', 'yesterday', or'now'.

example

`t` = datetime([DateStrings](#d126e368225)) creates an array of datetime values from the text inDateStrings representing points in time.

`t` = datetime([DateStrings](#d126e368225),'InputFormat',[infmt](#d126e368278)) interprets DateStrings using the format specified byinfmt. All values in the input argumentDateStrings must have the same format.

To avoid ambiguities between similar formats, specify'InputFormat' and its corresponding value,infmt.

To control the display format of t, specify the'Format' name-value pair argument, or set theFormat property of t.

example

`t` = datetime([DateVectors](#d126e368422)) creates a column vector of datetime values from the date vectors inDateVectors.

example

`t` = datetime([Y,M,D](#d126e368531)) creates an array of datetime values for corresponding elements of theY, M, and D (year, month, day) arrays. The arrays must be of the same size (or any can be a scalar). You also can specify the input arguments as a date vector,[Y M D].

`t` = datetime([Y,M,D,H,MI,S](#d126e368623)) also creates H, MI, andS (hour, minute, and second) arrays. All arrays must be of the same size (or any can be a scalar). You also can specify the input arguments as a date vector, [Y M D H MI S].

`t` = datetime([Y,M,D,H,MI,S,MS](#d126e368723)) adds an MS (millisecond) array. All arrays must be of the same size (or any can be a scalar).

`t` = datetime([X](#d126e368818),'ConvertFrom',[dateType](#d126e368859)) converts the numeric values in X to adatetime array t. ThedateType argument specifies the type of values inX.

If X contains POSIX® times or Julian dates that represent local times, then specify the appropriate time zone for t using the'TimeZone' name-value pair argument. If you do not specify a time zone, then the POSIX times or Julian dates in X are treated as UTC times, not local times.

example

`t` = datetime(___,[Name,Value](#namevaluepairarguments)) specifies additional options using one or more name-value pair arguments, in addition to any of the input arguments in the previous syntaxes. For example, you can specify the display format of t using the 'Format' name-value pair argument.

For best performance when creating datetime values from text, specify either 'Format' or 'InputFormat' and its corresponding value, infmt.

Input Arguments

expand all

Day relative to the current date, specified as one of the following values.

Text representing dates and times, specified as a character array, a cell array of character vectors, or a string array. Thedatetime function first attempts to match the format of DateStrings to common formats. If you know the format, specify 'InputFormat' and its corresponding infmt value, or the'Format' name-value pair argument.

Example: '24-Oct-2014 12:45:07'

Example: {'15-Oct-2013','20-Nov-2014'}

Example: ["11-Nov-2016","12-Dec-2016"]

Data Types: char | cell | string

Format of the input text representing dates and times, specified as a character vector or string scalar that contains letter identifiers:

• If infmt does not include a date specifier, then datetime assumes that the values inDateStrings occur during the current day.
• If infmt does not include a time specifier, then datetime assumes that the values inDateStrings occur at midnight.

This table shows several common input formats and includes examples of the formatted input for the date, Saturday, April 19, 2014 at 9:41:06.12345 PM in New York City.

For input text that represents fractional seconds, you can specifyinfmt with up to nine S characters to indicate fractional second digits. For example,'yyyy-MM-dd HH:mm:ss.SSS' is a format for text that represents dates and times to millisecond precision.

For a complete list of valid letter identifiers, see the Format property for datetime arrays. You can use most of the identifiers as both input formats and display formats. However, do not useMMMMM or any of the e identifiers to interpret input text, as these identifiers are for display only.

Note

The letter identifiers that datetime accepts are different from the identifiers used by thedatestr, datenum, anddatevec functions.

Data Types: char | string

Date vectors, specified as an m-by-6 orm-by-3 matrix containing m full or partial date vectors, respectively.

• A full date vector has six elements, specifying year, month, day, hour, minute, and second, in that order.
• A partial date vector has three elements, specifying year, month, and day, in that order.

Each element of DateVector should be a positive or negative integer value except for the seconds element, which can be fractional. If an element falls outside the conventional range,datetime adjusts both that date vector element and the previous element. For example, if the minutes element is70, then datetime increases the hours element by 1 and sets the minutes element to 10. If the minutes element is -15, then datetime decreases the hours element by 1 and sets the minutes element to 45.

• If any value is a NaN, then the corresponding datetime value is aNaT.
• If any value is Inf or-Inf, then the correspondingdatetime value is aInf or -Inf.

Example: [2014 10 24 12 45 07]

Example: [2014 10 24]

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Year, month, and day arrays specified as numeric arrays. These arrays must be the same size, or any one can be a scalar.Y,M,D should be integer values.

• If Y,M,D are all scalars or all column vectors, then you can specify the input arguments as a date vector, [Y M D].
• If an element of the Y,M, or D inputs falls outside the conventional range, thendatetime adjusts both that element and the same element of the previous input. For details, see the description for the DateVectors input argument.
• If any value is a NaN, then the corresponding datetime value is aNaT.
• If any value is Inf or-Inf, then the correspondingdatetime value is aInf or -Inf.

Example: 2003,10,24

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Year, month, day, hour, minute, and second arrays specified as numeric arrays. These arrays must be the same size, or any one can be a scalar. Specify fractional seconds as part of the seconds input,S. The Y,M,D,H,MI arrays must contain integer values.

• If Y,M,D,H,MI,S are all scalars or all column vectors, then you can specify the input arguments as a date vector[Y M D H MI S].
• If an element of the Y,M, D,H, MI, orS inputs falls outside the conventional range, then datetime adjusts both that element and the same element of the previous input. For details, see the description for the DateVectors input argument.
• If any value is a NaN, then the corresponding datetime value is aNaT.
• If any value is Inf or-Inf, then the correspondingdatetime value is aInf or -Inf.

Example: 2003,10,24,12,45,07.451

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Year, month, day, hour, minute, second, and millisecond arrays, specified as numeric arrays. These arrays must be the same size, or any one can be a scalar. The Y,M,D,H,MI,S arrays must contain integer values. MS can contain fractional milliseconds.

If an element of the Y, M,D, H, MI,S, or MS inputs falls outside the conventional range, then datetime adjusts both that element and the same element of the previous input. For details, see the description for the DateVectors input argument.

• If any value is a NaN, then the corresponding datetime value is aNaT.
• If any value is Inf or-Inf, then the correspondingdatetime value is aInf or -Inf.

Example: 2003,10,24,12,45,07,10.52

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Numeric values, specified as an array.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Type of values in X, specified as one of these values.

Name-Value Arguments

expand all

Specify optional pairs of arguments asName1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'Format','eeee MMMM d, y','TimeZone','local' applies a display format to datetime values and specifies the local time zone.

Display format of the values in the output array, specified as the comma-separated pair consisting of 'Format' and one of the following values.

If you specify your own format, then you must use valid letter identifiers. For a complete list of valid letter identifiers, see the Format property.

The factory default format depends on your system locale. To change the default display format, see Default datetime Format.

If you specify a DateStrings input but do not specify the 'InputFormat' parameter, thendatetime tries to use theFormat value to interpretDateStrings.

Example: 'Format','eeee, MMMM d, yyyy HH:mm:ss' displays a date and time such as Wednesday, April 9, 2014 21:41:06.

Data Types: char | string

Locale of DateStrings input argument values, specified as the comma-separated pair consisting of'Locale' and a character vector or string scalar. The Locale value determines howdatetime interpretsDateStrings. However, it does not determine how the output datetime values display.

The Locale value can be:

• "system", to specify your system locale.
• A string scalar or character vector in the form_`xx`__ _`YY`_, where xx is a lowercase ISO 639-1 two-letter code that specifies a language, and YY is an uppercase ISO 3166-1 alpha-2 code that specifies a country.

This table lists some common values for the locale.

You can use the 'Locale' name-value pair only when you use the DateStrings input argument.

Example: 'Locale',"de_DE"

Note

The Locale value determines how input text values are interpreted. The output datetime values always display in the language specified by the Locale option in the Datetime format section of the MATLAB® Settings window.

• To change the default datetime locale for display, seeModify Command Window Settings.
• To convert datetime values to text using a different locale, use the char,cellstr, or string functions.

Data Types: char | string

Start year of the 100-year date range in which a two-character year resides, specified as the comma-separated pair consisting of'PivotYear' and an integer. Use a pivot year to interpret dates that specify the year as two characters. That is, the pivot year has an effect only when the infmt argument includes y oryy.

You can use the 'PivotYear' name-value pair only when you use the DateStrings input argument.

Example: 'PivotYear',1900

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Time zone, specified as the comma-separated pair consisting of'TimeZone' and a character vector or string scalar that specifies the time zone.

The datetime function uses the value of'TimeZone' to interpret the input data and set the TimeZone property of the output array. If the input data are character vectors or strings that include a time zone, then the datetime function converts all values to the specified time zone.

For more information and a list of time zones, see the TimeZone property.

Data Types: char | string

Properties

expand all

Display format, specified as 'default', a character vector, or a string scalar.

If you specify a format of your own, then it must use valid letter identifiers that correspond to the Unicode® Locale Data Markup Language (LDML) standard for dates and times. For more information on the LDML, see Unicode Technical Standard #35, particularly the Date Field Symbol Table.

Example: 'eeee, MMMM d, yyyy HH:mm:ss' displays a date and time such as Wednesday, April 9, 2014 21:41:06.

To separate fields, you can include nonletter characters such as a hyphen, space, colon, or any non-ASCII characters. To include the lettersA-Z and a-z as literal characters in the format, enclose them in single quotes.

Example: 'uuuu-MM-dd''T''HH:mm:ss' displays a date and time, such as 2014-04-09T21:41:06.

Note

The letter identifiers that datetime accepts are different from the identifiers used by the datestr,datenum, and datevec functions.

The factory default format depends on your system locale. To change the default display format, see Default datetime Format.

Examples of Common Formats

This table lists common display formats. The examples show formatted output for the date, Wednesday, April 9, 2014 at 9:41:06.12345 PM, in New York City.

All Date and Time Formats

Use these identifiers to specify the display formats of date and time fields. The display formats show output for the date, Wednesday, April 9, 2014 at 9:41:06.12345 PM, in New York City.

Note

Some identifiers modify their behavior based on locale, input data, the values of other identifiers, or the presence of extra identifiers.

Effects of locale:

• When displaying or interpreting localized names, such as day or month names, datetime identifiers follow established international standards.
• To ensure similar behavior across different locales, avoid using identifiers with locale-dependent behavior. In general, such identifiers specify locale-dependent day or month names, or time zone offsets that are locale dependent.
  Locale-dependent identifiers includeMMM, MMMM,eee, eeee,z, andZZZZ.

Effects of large year values:

• datetime values later than 144683 years CE or before 140743 BCE display only the year numbers, regardless of the identifiers specified by theFormat property.

Effects of day and year identifiers:

• If you read a two-digit year number and specify the format as y or yy, then the pivot year determines the century to which the year belongs.
• If you read a day-of-year number and specify a format that contains identifiers for both the day of year (D) and Gregorian year (y), thendatetime might not read the day-of-year number correctly. Use ISO year (u) in place ofy.
• Use one or more u identifiers instead of y identifiers to represent the year when working with year numbers near zero.

Effects of extra identifiers:

• In general, if you specify more instances of an identifier than are shown in the table, thendatetime pads the display format for that identifier with leading zeros.
  For example, if you specify the hours identifier asHHHH, as in uuuu-MM-dd HHHH:mm:ss, then the display for January 1, 2024, 12:30 p.m. pads the hours field with two leading zeros.
  d = datetime(2024,1,1,12,30,0);
  d.Format = "uuuu-MM-dd HHHH:mm:ss"
  d =
  datetime
  2024-01-01 0012:30:00
  Similarly, leading zeros are typically ignored in text inputs, in cases where ignoring those zeros results in an input format that datetime can still parse.
  d = datetime("2024-01-01 0012:30:00")
  d =
  datetime
  2024-01-01 12:30:00

Time Zone Offset Formats

Use these identifiers to specify the display format of the time zone offset. A time zone offset is the amount of time that a specific datetime is offset from UTC. A time zone has rules for determining the time zone offset, and the offset can differ at different times of the year. Include a time zone offset identifier in the display format for a datetime array when you want to ensure that the time components are displayed unambiguously.

Time zone, specified as a character vector or string scalar. You can set this property to change the time zone after you have created adatetime array.

To set the time zone and calculate time zone offsets, thedatetime data type uses code and data provided by the Internet Assigned Numbers Authority (IANA) in the IANA Time Zone Database. The version currently used bydatetime includes recent updates from the IANA. (To get the version used by datetime, return the second output of the timezones function.)

This table lists the values that you can specify to set theTimeZone property.

This table lists some common names of time zone regions from the IANA Time Zone Database.

Data Types: char | string

Year number of each value in the datetime array, specified as a numeric array that is the same size and shape as thedatetime array. Each year number is an integer value based on the ISO calendar. Years in the current era are positive and years in the previous era are zero or negative. For example, the year number of 1 BCE is 0.

If you set the Year property to a nonleap year for adatetime value that occurs on a leap day (February 29), then the Day and Month properties change to March 1.

Month number of each value in the datetime array, specified as a numeric array that is the same size and shape as thedatetime array. Each month number is an integer value from 1 to 12. If you set a value outside that range, then theYear property adjusts accordingly, and theMonth property stays within the range 1 to 12. For example, month 0 corresponds to month 12 of the previous year. For historical dates, the month number is based on the proleptic Gregorian calendar.

Day-of-month number of each value in the datetime array, specified as a numeric array that is the same size and shape as thedatetime array. Each day-of-month number is an integer value from 1 to 28, 29, 30, or 31, depending on the month and year. If you set a value outside that range, then the Month andYear properties adjust accordingly, and theDay property stays within the appropriate range. For example, day 0 corresponds to the last day of the previous month. For historical dates, the day number is based on the proleptic Gregorian calendar.

Hour number of each value in the datetime array, specified as a numeric array that is the same size and shape as thedatetime array. Each hour number is an integer value from 0 to 23. If you set a value outside that range, then theDay, Month, andYear properties adjust accordingly, and theHour property stays within the appropriate range. For example, hour -1 corresponds to hour 23 of the previous day.

These conditions apply to datetime arrays with a specific time zone that follows daylight saving time:

• When you specify a value for the Hour property that would create a nonexistent datetime in the hour gap when daylight saving time begins, the value of theHour property adjusts to the next hour.
• When you specify a value for the Hour property that would create an ambiguous datetime in the hour overlap when daylight saving time ends, the datetime adjusts to the second of the two times (in standard time) with that hour.

Minute number of each value in the datetime array, specified as a numeric array that is the same size and shape as thedatetime array. Each minute number is an integer value from 0 to 59. If you specify a value outside that range, then theHour, Day,Month, and Year properties adjust accordingly, and the Minute property stays within the appropriate range. For example, minute -1 corresponds to minute 59 of the previous hour.

Second number of each value in the datetime array, specified as a numeric array that is the same size and shape as thedatetime array. Each second value is a floating-point value ordinarily ranging from 0 to less than 60. If you set a value outside that range, then the Minute, Hour,Day, Month, andYear properties adjust accordingly, and theSecond property stays within the appropriate range. For example, second -1 corresponds to second 59 of the previous minute.

A datetime array with a TimeZone value of 'UTCLeapSeconds' has seconds ranging from 0 to less than 61. The values from 60 to 61 represent datetimes that occur during a leap second. (For the list of leap seconds supported by thedatetime data type, see leapseconds.)

This property is read-only.

System time zone setting, specified as a character vector or string scalar. The system where MATLAB is running determines this time zone setting.

Example: America/New_York

Examples

collapse all

Specify the current date and time in the local system time zone.

t = datetime('now','TimeZone','local','Format','d-MMM-y HH:mm:ss Z')

t = datetime 1-Feb-2025 08:58:47 -0500

Specify the current date and time in the time zone represented by Seoul, Korea.

t = datetime('now','TimeZone','Asia/Seoul','Format','d-MMM-y HH:mm:ss Z')

t = datetime 1-Feb-2025 22:58:47 +0900

Create a datetime array from a cell array of character vectors.

DateStrings = {'2014-05-26';'2014-08-03'}; t = datetime(DateStrings,'InputFormat','yyyy-MM-dd')

t = 2×1 datetime 26-May-2014 03-Aug-2014

The datetime values in t display using the default format, and not the format of the input dates.

Starting in R2016b, you can create string arrays with the string function and convert them to datetime values.

str = ["2016-03-24","2016-04-19"]

str = 1×2 string "2016-03-24" "2016-04-19"

Convert the strings, specifying the input format as yyyy-MM-dd. The format must be specified as a character vector, even though str is a string array.

t = datetime(str,'InputFormat','yyyy-MM-dd')

t = 1×2 datetime 24-Mar-2016 19-Apr-2016

Create a datetime value from text that represents a date and time to millisecond precision. To convert text in a format that the datetime function cannot parse without more information, specify the 'InputFormat' name-value pair argument.

d = '2018-06-25 11:23:37.712'; t = datetime(d,'InputFormat','yyyy-MM-dd HH:mm:ss.SSS')

t = datetime 25-Jun-2018 11:23:37

The conversion does keep the fractional seconds. However, by default datetime arrays do not display fractional seconds. To display them, specify either the 'Format' name-value pair or the Format property.

t.Format = 'MMM dd, yyyy HH:mm:ss.SSS'

t = datetime Jun 25, 2018 11:23:37.712

The 'InputFormat' argument applies only to conversions from input text. The Format property specifies the display for any datetime array.

Convert dates in ISO 8601 format to datetime values.

Create a cell array of character vectors containing dates in ISO 8601 format. In this format, the letter T is used as a delimiter that separates a date and a time. Each character vector includes a time zone offset. The letter Z indicates no offset from UTC.

DateStrings = {'2014-05-26T13:30-05:00';'2014-08-26T13:30-04:00';'2014-09-26T13:30Z'}

DateStrings = 3×1 cell {'2014-05-26T13:30-05:00'} {'2014-08-26T13:30-04:00'} {'2014-09-26T13:30Z' }

Convert the character vectors to datetime values. When specifying the input format, enclose the letter T in single quotes to indicate that it is a literal character. Specify the time zone of the output datetime array using the TimeZone name-value pair argument.

t = datetime(DateStrings,'InputFormat','uuuu-MM-dd''T''HH:mmXXX','TimeZone','UTC')

t = 3×1 datetime 26-May-2014 18:30:00 26-Aug-2014 17:30:00 26-Sep-2014 13:30:00

The datetime values in t display in the default format.

Create a cell array of character vectors containing dates in French.

C = {'8 avril 2013','9 mai 2013';'10 juin 2014','11 juillet 2014'}

C = 2×2 cell {'8 avril 2013'} {'9 mai 2013' } {'10 juin 2014'} {'11 juillet 2014'}

Convert the character vectors in C to datetime values. If your computer is set to a locale that uses English, you must specify the 'Locale' name-value pair argument to indicate that the strings are in French.

t = datetime(C,'InputFormat','d MMMM yyyy','Locale','fr_FR')

t = 2×2 datetime 08-Apr-2013 09-May-2013 10-Jun-2014 11-Jul-2014

The datetime values in t display in the default format, and in the language MATLAB® uses depending on your system locale.

Create a datetime array from individual arrays of year, month, and day values.

Create sample numeric arrays of year values Y and day values D. In this case, the month value M is a scalar.

Y = [2014;2013;2012]; M = 01; D = [31;30;31];

Create the datetime array.

t = 3×1 datetime 31-Jan-2014 30-Jan-2013 31-Jan-2012

Specify a custom display format for the output, using the Format name-value pair argument.

t = datetime(Y,M,D,'Format','eeee, MMMM d, y')

t = 3×1 datetime Friday, January 31, 2014
Wednesday, January 30, 2013 Tuesday, January 31, 2012

Create a sample array of Excel® date numbers that represent a number of days since January 0, 1900.

X = [39558, 39600; 39700, 39800]

X = 2×2

   39558       39600
   39700       39800

Convert the values in X to datetime values.

t = datetime(X,'ConvertFrom','excel')

t = 2×2 datetime 20-Apr-2008 01-Jun-2008 09-Sep-2008 18-Dec-2008

Tips

• For a list of datetime functions, see Dates and Time.
• For a list of core MATLAB functions that accept datetime arrays as input arguments, see Core Functions Supporting Date and Time Arrays.

Extended Capabilities

expand all

Thedatetime function supports tall arrays with the following usage notes and limitations:

• Always specify the input datetime format when creating a tall datetime array for a string array or character vectors in a cell array.
• If you specify 'Format' as 'preserveinput', then MATLAB might need to evaluate the tall array to determine the format.

For more information, see Tall Arrays.

Usage notes and limitations:

• When you create a datetime array from the text inDateStrings, specify the input formatinfmt.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2014b

expand all

datetime format parsing performance is significantly faster for common date and time formats. Most date and time formats that are composed of letter identifiers separated by common delimiters see improved performance.

• Letter identifiers specify format components such as date fields, time fields, and time zone offsets. For a list of identifiers, see thedatetime Format property.
• Common delimiters are ":", ";",",", ".", "-","/", and the space character.

Examples of common input formats are:

• "dd.MM.uuuu"
• "MM/dd/uuuu"
• "uuuu MM dd"
• "HH:mm, dd MMMM uuuu Z"
• "uuuu MMM dd HH:mm:ss.SSS a ZZZZZ"
• "uuuu-MM-dd'T'HH:mm"
• "QQQ/uuuu"

In R2025a, there is no improvement for input formats that includeD, G, Q,QQ, W, y,yy, and z. (Only the identifiers listed in the previous sentence are affected. There can still be a performance improvement when you use identifiers such as QQQ oryyyy.)

Code that uses the datetime function to parse and convert text is generally about 4–17x faster, depending on the size and format of the input array. For example, this code shows an example of the parsing performance improvement. It creates a string array of dates that use periods as delimiters. The dates in the string array use the dd.MM.uuuu format. Then the code uses the datetime function to parse and convert the string array. The code is about 9.6x faster than in the previous release.

function timingTest

s = randi([1,31],1e6,1) + ".10.2024";

d = datetime(s,InputFormat="dd.MM.uuuu");

end

The approximate execution times are:

R2024b: 3.27 s

R2025a: 0.34 s

The code was timed on a Windows® 11, AMD EPYC™ 74F3 24-Core Processor @ 3.19 GHz test system using thetimeit function.

datetime format parsing performance is significantly faster when parsing common formats that include localized names or time zone offsets. This list shows a few examples of such formats, which are part of ongoing efforts to improve datetime format parsing performance:

• dd-MMM-uuuu HH:mm:ss
• MMMM/dd/uuuu
• QQQ-uuuu
• uuuu-MM-dd HH:mm:ss Z
• uuuu-MM-dd HH:mm:ss.SSS xxx

For example, this code creates a string array of dates that use a localized abbreviation for the month of April. The dates in the string array use thedd-MMM-uuuu HH:mm:ss format, where the MMM specifier represents the abbreviated month name. Then the code uses thedatetime function to parse and convert the string array. The code is about 17x faster than in the previous release.

function timingTest s = "23-Apr-2024 11:30:" + randi([10,59],10000,1); for i = 1:100 d = datetime(s, ... InputFormat="dd-MMM-uuuu HH:mm:ss", ... Locale="en_US"); end end

The approximate execution times are:

R2024a: 4.75 s

R2024b: 0.27 s

Similarly, this code creates a string array of dates that have a time zone offset of -0400. The dates in the string array use theuuuu-MM-dd HH:mm:ss.SSS Z format, where theZ specifier represents the time zone offset. Then the code uses the datetime function to parse and convert the string array. The code is about 5.8x faster than in the previous release.

function timingTest s = "2024-04-23 11:32:48." + randi(999,10000,1) + " -0400"; for i = 1:100 d = datetime(s, ... InputFormat="uuuu-MM-dd HH:mm:ss.SSS Z", ... TimeZone="local"); end end

The approximate execution times are:

R2024a: 6.35 s

R2024b: 1.10 s

In both cases, the code was timed on a Windows 11, AMD EPYC 74F3 24-Core Processor @ 3.19 GHz test system using thetimeit function.

You can specify a time zone offset for a datetime array by using a duration value.

To specify an offset when you use the datetime function, specify the TimeZone name-value argument.

t = datetime("now",TimeZone=hours(5))

To specify an offset after you create a datetime array, assign the offset to its TimeZone property.

t = datetime("now") t.TimeZone = hours(5)

datetime format parsing performance is significantly faster when parsing some common formats. In general, performance is best for text timestamps in formats that use only numeric specifiers, such as the ISO 8601 format. This list shows a few examples of such formats, which are part of ongoing efforts to improve datetime format parsing performance:

• uuuu-MM-dd and yyyy-MM-dd
• MM/dd/uuuu and MM/dd/yyyy
• uuuu-MM-dd'T'HH:mm:ss.SSS'Z' andyyyy-MM-dd'T'HH:mm:ss.SSS'Z'

For example, this code creates and then parses a string array that contains a series of dates. The dates in the string array have theuuuu-MM-dd numeric format. The datetime function recognizes the format, parses the strings, and returnsdatetime values. The code is about 16x faster than in the previous release.

function timingTest() d1 = datetime(2024,1,1:10000); s = string(d1,"uuuu-MM-dd");

for i = 1:100 d2 = datetime(s); end end

The approximate execution times are:

R2023b: 3.13 s

R2024a: 0.19 s

The code was timed on a Windows 11, AMD® EPYC 74F3 24-Core Processor @ 3.19 GHz test system using thetimeit function:

Starting in R2020a, when you specify one- or two-letter identifiers for the day-of-week, month, or quarter in the 'InputFormat' name-value argument, these identifiers no longer recognize names. They recognize digits only.

Similarly, three-letter identifiers for abbreviated day-of-week, month, and quarter names no longer recognize full names. They recognize only abbreviations.

The table shows these identifiers with examples of both recognized and unrecognized values.

In previous releases, all these one-, two-, and three-letter identifiers recognized both abbreviated and full names for day-of-week, month, and quarter respectively. For example, ee recognized Wed as Wednesday, MM recognized Apr as April, andQQ recognized Q2 as the second quarter. Similarly, eee recognized Wednesday,MMM recognized April, andQQQ recognized 2nd quarter.

For more information on format identifiers, see the Format property ofdatetime.