Convert Date and Time to Julian Date or POSIX Time

You can convert datetime arrays to represent points in time in specialized numeric formats. In general, these formats represent a point in time as the number of seconds or days that have elapsed since a specified starting point. For example, the Julian date is the number of days and fractional days that have elapsed since the beginning of the Julian period. The POSIX® time is the number of seconds that have elapsed since 00:00:00 1-Jan-1970 UTC (Coordinated Universal Time). MATLAB® provides the juliandate and posixtime functions to convert datetime arrays to Julian dates and POSIX times.

While datetime arrays are not required to have a time zone, converting "unzoned" datetime values to Julian dates or POSIX times can lead to unexpected results. To ensure the expected result, specify the time zone before conversion.

Specify Time Zone Before Conversion

You can specify a time zone for a datetime array, but you are not required to do so. In fact, by default the datetime function creates an "unzoned" datetime array.

Create a datetime value for the current date and time.

d = datetime("now")

d = datetime
   05-Sep-2024 15:21:02

d is constructed from the local time on your machine and has no time zone associated with it. In many contexts, you might assume that you can treat the times in an unzoned datetime array as local times. However, the juliandate and posixtime functions treat the times in unzoned datetime arrays as UTC times, not local times. To avoid any ambiguity, it is recommended that you avoid using juliandate and posixtime on unzoned datetime arrays. For example, avoid using posixtime(datetime("now")) in your code.

If your datetime array has values that do not represent UTC times, specify the time zone using the TimeZone name-value pair argument so that juliandate and posixtime interpret the datetime values correctly.

d = datetime("now","TimeZone","America/New_York")

d = datetime
   05-Sep-2024 15:21:02

As an alternative, you can specify the TimeZone property after you create the array.

d.TimeZone = "America/Los_Angeles"

d = datetime
   05-Sep-2024 12:21:02

To see a complete list of time zones, use the timezones function.

Convert Zoned and Unzoned Datetime Values to Julian Dates

A Julian date is the number of days (including fractional days) since noon on November 24, 4714 BCE, in the proleptic Gregorian calendar, or January 1, 4713 BCE, in the proleptic Julian calendar. To convert datetime arrays to Julian dates, use the juliandate function.

Create a datetime array and specify its time zone.

DZ = datetime("2016-07-29 10:05:24") + calmonths(1:3);
DZ.TimeZone = "America/New_York"

DZ = 1x3 datetime
   29-Aug-2016 10:05:24   29-Sep-2016 10:05:24   29-Oct-2016 10:05:24

Convert D to the equivalent Julian dates.

format longG
JDZ = juliandate(DZ)

JDZ = 1×3

          2457630.08708333          2457661.08708333          2457691.08708333

Create an unzoned copy of DZ. Convert D to the equivalent Julian dates. As D has no time zone, juliandate treats the times as UTC times.

D = DZ;
D.TimeZone = "";
JD = juliandate(D)

JD = 1×3

          2457629.92041667          2457660.92041667          2457690.92041667

Compare JDZ and JD. The differences are equal to the time zone offset between UTC and the America/New_York time zone in fractional days.

JDZ - JD 

ans = 1×3

         0.166666666511446         0.166666666511446         0.166666666511446

Convert Zoned and Unzoned Datetime Values to POSIX Times

The POSIX time is the number of seconds (including fractional seconds) elapsed since 00:00:00 1-Jan-1970 UTC (Coordinated Universal Time), ignoring leap seconds. To convert datetime arrays to POSIX times, use the posixtime function.

Create a datetime array and specify its time zone.

DZ = datetime("2016-07-29 10:05:24") + calmonths(1:3);
DZ.TimeZone = "America/New_York"

DZ = 1x3 datetime
   29-Aug-2016 10:05:24   29-Sep-2016 10:05:24   29-Oct-2016 10:05:24

Convert D to the equivalent POSIX times.

PTZ = posixtime(DZ)

PTZ = 1×3

                1472479524                1475157924                1477749924

Create an unzoned copy of DZ. Convert D to the equivalent POSIX times. As D has no time zone, posixtime treats the times as UTC times.

D = DZ;
D.TimeZone = "";
PT = posixtime(D)

PT = 1×3

                1472465124                1475143524                1477735524

Compare PTZ and PT. The differences are equal to the time zone offset between UTC and the America/New_York time zone in seconds.

PTZ - PT

ans = 1×3

       14400       14400       14400