Documentation

This is machine translation

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

dateshift

Shift date or generate sequence of dates and time

Syntax

``t2 = dateshift(t,'start',unit)``
``t2 = dateshift(t,'end',unit)``
``t2 = dateshift(t,'dayofweek',dow)``
``t2 = dateshift(___,rule)``

Description

````t2 = dateshift(t,'start',unit)` shifts each value in the `datetime` array `t` back to the beginning of the unit of time specified by `unit`. The output `t2` is the same size as `t`.```

example

````t2 = dateshift(t,'end',unit)` shifts the values ahead to the end of the unit of time specified by `unit`. The end of a day, hour, minute, or second is also the beginning of the next one. For example, the end of a day occurs at midnight at the beginning of the next day. The end of a year, quarter, month, or week is midnight at the beginning of the last day of that time period.```

example

````t2 = dateshift(t,'dayofweek',dow)` returns the next occurrence of the specified day of the week on or after each datetime in array `t`. If the date in `t` falls on the specified day of the week, then `dateshift` returns the same date.```

example

````t2 = dateshift(___,rule)` shifts each value in array `t` according to the pattern specified by `rule`. You can use this syntax with any of the arguments in the previous syntaxes.```

Examples

collapse all

Define the current date.

`t = datetime('today')`
```t = datetime 19-Sep-2017 ```

Shift the date to the end of the same month.

`t2 = dateshift(t,'end','month')`
```t2 = datetime 30-Sep-2017 ```

Define the current date.

`t = datetime('today')`
```t = datetime 19-Sep-2017 ```

Shift the date to the start of the next month.

`t2 = dateshift(t,'start','month','next')`
```t2 = datetime 01-Oct-2017 ```

Shift the date to the end of the next month.

`t2 = dateshift(t,'end','month','next')`
```t2 = datetime 31-Oct-2017 ```

Shift an array of dates forward to the next Friday.

`t = datetime([2014,08,03;2014,04,15])`
```t = 2x1 datetime array 03-Aug-2014 15-Apr-2014 ```
`t2 = dateshift(t,'dayofweek','Friday')`
```t2 = 2x1 datetime array 08-Aug-2014 18-Apr-2014 ```

Shift the array of dates backward to the previous Monday.

`t2 = dateshift(t,'dayofweek','Monday','previous')`
```t2 = 2x1 datetime array 28-Jul-2014 14-Apr-2014 ```

Find the date that falls at the end of the fifth week from today.

`t = datetime('today')`
```t = datetime 19-Sep-2017 ```
`t2 = dateshift(t,'end','week',5)`
```t2 = datetime 28-Oct-2017 ```

Generate a sequence of dates consisting of the next three occurrences of Friday.

`t = datetime('today')`
```t = datetime 19-Sep-2017 ```
`t2 = dateshift(t,'dayofweek','Friday',1:3)`
```t2 = 1x3 datetime array 22-Sep-2017 29-Sep-2017 06-Oct-2017 ```

Input Arguments

collapse all

Input date and time, specified as a `datetime` array.

Unit of time, specified as one of the following values:

• `'year'`

• `'quarter'`

• `'month'`

• `'week'`

• `'day'`

• `'hour'`

• `'minute'`

• `'second'`

Day of the week, specified as a scalar integer indicating the day of week number, or a character vector or string scalar containing a localized day name.

Example: `'Sunday'`

Example: 1

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64` | `char` | `string`

Rule for shifting datetime values, specified as a character vector, string scalar, scalar integer, or an array of integer values. If `rule` is a character vector or string, it must be one of the following.

Value of `rule`Description
`'next'`Shift datetime to next unit of time or specified day.
(Default rule for day of week.)
`'previous'`Shift datetime to previous unit of time or specified day.
`'nearest'`Shift datetime to nearest occurrence of unit of time or specified day.
`'current'`Shift datetime within the current unit of time, or to the specified day in the current week.
(Default rule for unit of time.)

If `rule` is an integer or an array of integers, then:

• When used with the input argument, `unit`, `0` corresponds to the start or end of the current unit for each datetime, `1` corresponds to the next unit, `-1` corresponds to the previous unit, and so on.

• When used with the input argument, `dow`, `0` corresponds to the specified day in the current week for each datetime, `1` corresponds to the next occurrence of the specified day, `-1` corresponds to the previous occurrence, and so on.

• `t` and `rule` must be the same size, or one must be a scalar.

If you specify `'dayofweek'` and `t` contains datetime values that fall on that day of the week, then `dateshift` treats those datetime values as the next or previous occurrences of the specified day of the week. For example, `dateshift(datetime(2015,12,24),'dayofweek','thu',rule)` returns a datetime value with a date of December 24, 2015 if `rule` is `'next'`, `'previous'`, `1`, or `-1`, because December 24, 2015 is a Thursday.