# convertTo

Convert `datetime` values to numeric representations

## Syntax

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

## Description

example

````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.```

## Examples

collapse all

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 4.3739 4.3770 4.3800 ```

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 ```

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`

`'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 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.

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.

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