Main Content

convertTo

Convert datetime values to numeric representations

collapse all in page

Syntax

X = convertTo(D,dateType)
X = convertTo(D,'epochtime',Name,Value)

Description

X = convertTo(D,dateType) converts the datetime values in D to the numeric representation specified by dateType and returns a numeric array. For example, if dateType is 'posixtime', then convertTo converts each element of D to the number of seconds that have elapsed since the epoch of January 1, 1970, 00:00:00 UTC.

All numeric representations describe dates and times with respect to a point in time called an epoch. Computers typically measure time by the number of seconds or clock ticks since the specified epoch.

example

X = convertTo(D,'epochtime',Name,Value) specifies an epoch and number of clock ticks per second using name-value pair arguments. For example, if you specify the epoch as 'Epoch','2001-01-01', then each value in X represents the number of seconds before or after midnight on January 1, 2001.

example

Examples

collapse all

Open Live Script

Create an array of datetime values.

D = datetime(2019,10:12,1,12,0,0)
D = 1x3 datetime
   01-Oct-2019 12:00:00   01-Nov-2019 12:00:00   01-Dec-2019 12:00:00

Convert D to an array of double-precision values representing Excel® date numbers. (To display all the digits of the date numbers, set the numeric display format to longg.)

format longg
X = convertTo(D,'excel')
X = 1×3

                   43739.5                   43770.5                   43800.5

Convert D to an array representing dates and times as .NET times. Since .NET times must be unsigned 64-bit integers, convertTo returns an array having the uint64 data type.

X = convertTo(D,'.net')
X = 1x3 uint64 row vector

   637055280000000000   637082064000000000   637107984000000000
Open Live Script

Create a datetime array. Specify that the time zone is the zone for Tokyo.

D = datetime(2019,10:12,1,12,0,0,'TimeZone','Asia/Tokyo')
D = 1x3 datetime
   01-Oct-2019 12:00:00   01-Nov-2019 12:00:00   01-Dec-2019 12:00:00

Convert D. To represent times as the number of milliseconds that have elapsed since January 1, 2001, specify the Epoch and TicksPerSecond name-value pair arguments. You can specify the epoch as a datetime value or as text formatted to specify a date and time. When you specify 'epochtime', the output is an array of signed 64-bit integers.

X = convertTo(D,'epochtime','Epoch','2001-01-01','TicksPerSecond',1000)
X = 1x3 int64 row vector

   591624000000   594302400000   596894400000

If the time zone of D is unspecified, then the convertTo function treats the elements of D as UTC times when you specify 'epochtime'.

Input Arguments

collapse all

Input dates and times, specified as a datetime array.

Type of output numeric representation, specified as a value in the table.

The value of dateType determines the data type of the output array. Some numeric representations require unsigned or signed 64-bit integers. Depending on these requirements, the output can have the double, uint64, or int64 data type.

Value of dateType

Output Numeric Representation

Output Data Type

'excel'

Number of days since 0-Jan-1900, representing an Excel® date number. This option is equivalent to the exceltime function.

Note: Excel date numbers are rounded to the nearest microsecond.

Note: Excel incorrectly assumes that the year 1900 is a leap year. Therefore, when computing Excel date numbers there is a discontinuity of one extra day between February 28, 1900 and March 1, 1900.

double

'excel1904'

Number of days since 0-Jan-1904, representing an Excel date number. This option is equivalent to the exceltime function.

Note: Excel date numbers are rounded to the nearest microsecond.

Note: Excel incorrectly assumes that the year 1900 is a leap year. Therefore, when computing Excel date numbers there is a discontinuity of one extra day between February 28, 1900 and March 1, 1900.

double

'juliandate'

Number of days since noon UTC 24-Nov-4714 BCE in the proleptic Gregorian calendar, representing the Julian Date. This option is equivalent to the juliandate function.

Note: If the time zone of D is not specified, then convertTo treats the values in D as UTC times, not local times. To represent local times, specify a time zone using the TimeZone property of D before calling the convertTo function.

Example: Convert D using the time zone for Tokyo.

D.TimeZone = 'Asia/Tokyo';
X = convertTo(D,'juliandate')

double

'modifiedjuliandate'

Number of days since midnight UTC 17-Nov-1858, representing the Modified Julian Date. This option is equivalent to the juliandate function.

Note: If the time zone of D is not specified, then convertTo treats the values in D as UTC times, not local times. To represent local times, specify a time zone using the TimeZone property of D before calling the convertTo function.

Example: Convert D using the time zone for Tokyo.

D.TimeZone = 'Asia/Tokyo';
X = convertTo(D,'modifiedjuliandate')

double

'posixtime'

Number of seconds since 1-Jan-1970 00:00:00 UTC, a point in time known as the Unix epoch. This option is equivalent to the posixtime function.

Unix time, also known as UNIX Epoch time or POSIX time, is the system for measuring time with respect to the Unix epoch. (Unix time ignores leap seconds and therefore does not truly represent UTC.)

Note: If the time zone of D is not specified, then convertTo treats the values in D as UTC times, not local times. To represent local times, specify a time zone using the TimeZone property of D before calling the convertTo function.

Example: Convert D, specifying that its time zone is the time zone for Tokyo.

D.TimeZone = 'Asia/Tokyo';
X = convertTo(D,'posixtime')

double

'yyyymmdd'

Dates as YYYYMMDD numeric values. For example, 20140402 represents April 2, 2014.

double

'datenum'

Number of days since 0-Jan-0000 in the proleptic ISO calendar.

double

'ntp'

Number of "clock ticks" since 1-Jan-1900 00:00:00 UTC, representing a Network Time Protocol (NTP) timestamp where each clock tick is 2^-32 seconds.

uint64

'.net'

Number of "clock ticks" since 1-Jan-0001 00:00:00 UTC, representing a Microsoft® .NET timestamp where each clock tick is 100 ns.

uint64

'ntfs'

Number of "clock ticks" since 1-Jan-1601 00:00:00 UTC, representing an NTFS timestamp where each clock tick is 100 ns.

uint64

'tt2000'

Number of nanoseconds that have elapsed since J2000. The Common Data Format (CDF) defines the CDF_TIME_TT2000 (or TT2000) data type as a high-resolution time type that handles leap seconds for data in CDF files. For more information, see Requirements for handling leap seconds in CDF.

To convert a datetime array to an array of TT2000 times, set the TimeZone property of the input datatime array to UTCLeapSeconds. The UTCLeapSeconds time zone is the only time zone that accounts for leap seconds.

Note: J2000 is January 1, 2000, 12:00 Terrestrial Time (TT). TT differs from UTC due to two factors:

  • Leap seconds

  • Difference of 32.184 seconds between TT and atomic clock timekeeping

As a consequence, J2000 actually occurs 64.184 seconds before noon in the UTCLeapSeconds time zone, at:

D = datetime(2000,1,1,11,58,55,816,"TimeZone","UTCLeapSeconds")
D = 2000-01-01T11:58:55.816Z

Example: Set the time zone of D to UTCLeapSeconds. Then convert D to an array of TT2000 times.

D = datetime(2022,4,1:3,9,30,45, ...
             "TimeZone","UTCLeapSeconds");
D = D'

D = 
  3x1 datetime array
   2022-04-01T09:30:45.000Z
   2022-04-02T09:30:45.000Z
   2022-04-03T09:30:45.000Z

X = convertTo(D,"tt2000")

X =
  3x1 int64 column vector
   702077514184000000
   702163914184000000
   702250314184000000

int64

'epochtime'

Number of seconds since an epoch that you specify. Use this option with the 'Epoch' and 'TicksPerSecond' name-value pair arguments.

Note: If the time zone of D is not specified, then convertTo treats the values in D as UTC times, not local times. To represent local times, specify a time zone using the TimeZone property of D before calling the convertTo function.

Example: Specify the time zone of D. Then convert it to the number of seconds elapsed since January 1, 2001.

D.TimeZone = 'Asia/Tokyo';
X = convertTo(D,'epochtime','Epoch','2001-01-01')

int64

Name-Value Arguments

Specify optional pairs of arguments as Name1=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: convertTo(D,'epochtime','Epoch','2001-01-01','TicksPerSecond',1000) returns the number of milliseconds since the beginning of January 1, 2001.

Point used for time measurements, specified as the comma-separated pair consisting of 'Epoch' and a datetime scalar, character vector, or string scalar.

If the value of 'Epoch' is a character vector or string scalar, then it must represent a date and time in a format that the datetime function recognizes (for example, '2001-01-01' representing January 1, 2001).

The default value is the Unix epoch, representing January 1, 1970, 00:00:00 UTC.

Clock ticks per second, specified as the comma-separated pair consisting of 'TicksPerSecond' and a numeric scalar.

Extended Capabilities

Thread-Based Environment
Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Version History

Introduced in R2018b

See Also

| | | | |

Topics

External Websites