Generate Sequence of Dates and Time

Sequence of Datetime or Duration Values Between Endpoints with Step Size

This example shows how to use the colon (:) operator to generate sequences of datetime or duration values in the same way that you create regularly spaced numeric vectors.

Use Default Step Size

Create a sequence of datetime values starting from November 1, 2013, and ending on November 5, 2013. The default step size is one calendar day.

t1 = datetime(2013,11,1,8,0,0);
t2 = datetime(2013,11,5,8,0,0);
t = t1:t2

t = 1x5 datetime
   01-Nov-2013 08:00:00   02-Nov-2013 08:00:00   03-Nov-2013 08:00:00   04-Nov-2013 08:00:00   05-Nov-2013 08:00:00

Specify Step Size

Specify a step size of 2 calendar days using the caldays function.

t = t1:caldays(2):t2

t = 1x3 datetime
   01-Nov-2013 08:00:00   03-Nov-2013 08:00:00   05-Nov-2013 08:00:00

Specify a step size in units other than days. Create a sequence of datetime values spaced 18 hours apart.

t = t1:hours(18):t2

t = 1x6 datetime
   01-Nov-2013 08:00:00   02-Nov-2013 02:00:00   02-Nov-2013 20:00:00   03-Nov-2013 14:00:00   04-Nov-2013 08:00:00   05-Nov-2013 02:00:00

Use the years, days, minutes, and seconds functions to create datetime and duration sequences using other fixed-length date and time units. Create a sequence of duration values between 0 and 3 minutes, incremented by 30 seconds.

d = 0:seconds(30):minutes(3)

d = 1x7 duration
     0 sec    30 sec    60 sec    90 sec   120 sec   150 sec   180 sec

Compare Fixed-Length Duration and Calendar Duration Step Sizes

Assign a time zone to t1 and t2. In the America/New_York time zone, t1 now occurs just before a daylight saving time change.

t1.TimeZone = 'America/New_York';
t2.TimeZone = 'America/New_York';

If you create the sequence using a step size of one calendar day, then the difference between successive datetime values is not always 24 hours.

t = t1:t2;
dt = diff(t)

dt = 1x4 duration
   24:00:00   25:00:00   24:00:00   24:00:00

Create a sequence of datetime values spaced one fixed-length day apart,

t = t1:days(1):t2

t = 1x5 datetime
   01-Nov-2013 08:00:00   02-Nov-2013 08:00:00   03-Nov-2013 07:00:00   04-Nov-2013 07:00:00   05-Nov-2013 07:00:00

Verify that the difference between successive datetime values is 24 hours.

dt = diff(t)

dt = 1x4 duration
   24:00:00   24:00:00   24:00:00   24:00:00

Integer Step Size

If you specify a step size in terms of an integer, it is interpreted as a number of 24-hour days.

t = t1:1:t2

t = 1x5 datetime
   01-Nov-2013 08:00:00   02-Nov-2013 08:00:00   03-Nov-2013 07:00:00   04-Nov-2013 07:00:00   05-Nov-2013 07:00:00

Add Duration or Calendar Duration to Create Sequence of Dates

This example shows how to add a duration or calendar duration to a datetime to create a sequence of datetime values.

Create a datetime scalar representing November 1, 2013, at 8:00 AM.

t1 = datetime(2013,11,1,8,0,0);

Add a sequence of fixed-length hours to the datetime.

t = t1 + hours(0:2)

t = 1x3 datetime
   01-Nov-2013 08:00:00   01-Nov-2013 09:00:00   01-Nov-2013 10:00:00

Add a sequence of calendar months to the datetime.

t = t1 + calmonths(1:5)

t = 1x5 datetime
   01-Dec-2013 08:00:00   01-Jan-2014 08:00:00   01-Feb-2014 08:00:00   01-Mar-2014 08:00:00   01-Apr-2014 08:00:00

Each datetime in t occurs on the first day of each month.

Verify that the dates in t are spaced 1 month apart.

dt = caldiff(t)

dt = 1x4 calendarDuration
   1mo   1mo   1mo   1mo

Determine the number of days between each date.

dt = caldiff(t,'days')

dt = 1x4 calendarDuration
   31d   31d   28d   31d

Add a number of calendar months to the date, January 31, 2014, to create a sequence of dates that fall on the last day of each month.

t = datetime(2014,1,31) + calmonths(0:11)

t = 1x12 datetime
   31-Jan-2014   28-Feb-2014   31-Mar-2014   30-Apr-2014   31-May-2014   30-Jun-2014   31-Jul-2014   31-Aug-2014   30-Sep-2014   31-Oct-2014   30-Nov-2014   31-Dec-2014

Specify Length and Endpoints of Date or Duration Sequence

This example shows how to use the linspace function to create equally spaced datetime or duration values between two specified endpoints.

Create a sequence of five equally spaced dates between April 14, 2014, and August 4, 2014. First, define the endpoints.

A = datetime(2014,04,14);
B = datetime(2014,08,04);

The third input to linspace specifies the number of linearly spaced points to generate between the endpoints.

C = linspace(A,B,5)

C = 1x5 datetime
   14-Apr-2014   12-May-2014   09-Jun-2014   07-Jul-2014   04-Aug-2014

Create a sequence of six equally spaced durations between 1 and 5.5 hours.

A = duration(1,0,0);
B = duration(5,30,0);
C = linspace(A,B,6)

C = 1x6 duration
   01:00:00   01:54:00   02:48:00   03:42:00   04:36:00   05:30:00

Sequence of Datetime Values Using Calendar Rules

This example shows how to use the dateshift function to generate sequences of dates and time where each instance obeys a rule relating to a calendar unit or a unit of time. For instance, each datetime must occur at the beginning a month, on a particular day of the week, or at the end of a minute. The resulting datetime values in the sequence are not necessarily equally spaced.

Dates on Specific Day of Week

Generate a sequence of dates consisting of the next three occurrences of Monday. First, define today's date.

t1 = datetime('today','Format','dd-MMM-yyyy eee')

t1 = datetime
   05-Sep-2024 Thu

The first input to dateshift is always the datetime array from which you want to generate a sequence. Specify 'dayofweek' as the second input to indicate that the datetime values in the output sequence must fall on a specific day of the week. You can specify the day of the week either by number or by name. For example, you can specify Monday either as 2 or 'Monday'.

t = dateshift(t1,'dayofweek',2,1:3)

t = 1x3 datetime
   09-Sep-2024 Mon   16-Sep-2024 Mon   23-Sep-2024 Mon

Dates at Start of Month

Generate a sequence of start-of-month dates beginning with April 1, 2014. Specify 'start' as the second input to dateshift to indicate that all datetime values in the output sequence should fall at the start of a particular unit of time. The third input argument defines the unit of time, in this case, month. The last input to dateshift can be an array of integer values that specifies how t1 should be shifted. In this case, 0 corresponds to the start of the current month, and 4 corresponds to the start of the fourth month from t1.

t1 = datetime(2014,04,01);
t = dateshift(t1,'start','month',0:4)

t = 1x5 datetime
   01-Apr-2014   01-May-2014   01-Jun-2014   01-Jul-2014   01-Aug-2014

Dates at End of Month

Generate a sequence of end-of-month dates beginning with April 1, 2014.

t1 = datetime(2014,04,01);
t = dateshift(t1,'end','month',0:2)

t = 1x3 datetime
   30-Apr-2014   31-May-2014   30-Jun-2014

Determine the number of days between each date.

dt = caldiff(t,'days')

dt = 1x2 calendarDuration
   31d   30d

The dates are not equally spaced.

Other Units of Dates and Time

You can specify other units of time such as week, day, and hour.

t1 = datetime('now')

t1 = datetime
   05-Sep-2024 15:30:47

t = dateshift(t1,'start','hour',0:4)

t = 1x5 datetime
   05-Sep-2024 15:00:00   05-Sep-2024 16:00:00   05-Sep-2024 17:00:00   05-Sep-2024 18:00:00   05-Sep-2024 19:00:00

Previous Occurrences of Dates and Time

Generate a sequence of datetime values beginning with the previous hour. Negative integers in the last input to dateshift correspond to datetime values earlier than t1.

t = dateshift(t1,'start','hour',-1:1)

t = 1x3 datetime
   05-Sep-2024 14:00:00   05-Sep-2024 15:00:00   05-Sep-2024 16:00:00