convertTo

Convert datetime values to numeric representations

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.

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.

Examples

Convert Dates and Times to Excel and .NET Times

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

Specify Epoch and Clock Ticks

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

D — Input dates and times

datetime array

Input dates and times, specified as a datetime array.

dateType — Type of output numeric representation

'excel' | 'excel1904' | 'juliandate' | 'modifiedjuliandate' | 'posixtime' | ...

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
'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 Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: convertTo(D,'epochtime','Epoch','2001-01-01','TicksPerSecond',1000) returns the number of milliseconds since the beginning of January 1, 2001.

'Epoch' — Point used for time measurements

datetime(1970,1,1,0,0,0,'TimeZone','UTC') (default) | datetime scalar | character vector | string scalar

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.

'TicksPerSecond' — Clock ticks per second

1 (default) | numeric scalar

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