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
20-Jul-2024 Sat
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
22-Jul-2024 Mon 29-Jul-2024 Mon 05-Aug-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
20-Jul-2024 15:02:10
t = dateshift(t1,'start','hour',0:4)
t = 1x5 datetime
20-Jul-2024 15:00:00 20-Jul-2024 16:00:00 20-Jul-2024 17:00:00 20-Jul-2024 18:00:00 20-Jul-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
20-Jul-2024 14:00:00 20-Jul-2024 15:00:00 20-Jul-2024 16:00:00