Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English version of the page.

## 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 array Columns 1 through 3 01-Nov-2013 08:00:00 02-Nov-2013 08:00:00 03-Nov-2013 08:00:00 Columns 4 through 5 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 array 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 array Columns 1 through 3 01-Nov-2013 08:00:00 02-Nov-2013 02:00:00 02-Nov-2013 20:00:00 Columns 4 through 6 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 array 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 array 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 array Columns 1 through 3 01-Nov-2013 08:00:00 02-Nov-2013 08:00:00 03-Nov-2013 07:00:00 Columns 4 through 5 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 array 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 array Columns 1 through 3 01-Nov-2013 08:00:00 02-Nov-2013 08:00:00 03-Nov-2013 07:00:00 Columns 4 through 5 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 array 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 array Columns 1 through 3 01-Dec-2013 08:00:00 01-Jan-2014 08:00:00 01-Feb-2014 08:00:00 Columns 4 through 5 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 array 1mo 1mo 1mo 1mo ```

Determine the number of days between each date.

`dt = caldiff(t,'days')`
```dt = 1x4 calendarDuration array 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 array Columns 1 through 5 31-Jan-2014 28-Feb-2014 31-Mar-2014 30-Apr-2014 31-May-2014 Columns 6 through 10 30-Jun-2014 31-Jul-2014 31-Aug-2014 30-Sep-2014 31-Oct-2014 Columns 11 through 12 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 array 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 array 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 27-Aug-2018 Mon ```

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 array 27-Aug-2018 Mon 03-Sep-2018 Mon 10-Sep-2018 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 array 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 array 30-Apr-2014 31-May-2014 30-Jun-2014 ```

Determine the number of days between each date.

`dt = caldiff(t,'days')`
```dt = 1x2 calendarDuration array 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 27-Aug-2018 13:37:28 ```
`t = dateshift(t1,'start','hour',0:4)`
```t = 1x5 datetime array Columns 1 through 3 27-Aug-2018 13:00:00 27-Aug-2018 14:00:00 27-Aug-2018 15:00:00 Columns 4 through 5 27-Aug-2018 16:00:00 27-Aug-2018 17: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 array 27-Aug-2018 12:00:00 27-Aug-2018 13:00:00 27-Aug-2018 14:00:00 ```