Main Content

# dateshift

Shift date or generate sequence of dates and times

## 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` value 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 23-Feb-2021 ```

Shift the date to the end of the same month.

`t2 = dateshift(t,'end','month')`
```t2 = datetime 28-Feb-2021 ```

Define the current date.

`t = datetime('today')`
```t = datetime 23-Feb-2021 ```

Shift the date to the start of the next month.

`t2 = dateshift(t,'start','month','next')`
```t2 = datetime 01-Mar-2021 ```

Shift the date to the end of the next month.

`t2 = dateshift(t,'end','month','next')`
```t2 = datetime 31-Mar-2021 ```

Shift an array of dates forward to the next Friday.

`t = datetime([2014,08,03;2014,04,15])`
```t = 2x1 datetime 03-Aug-2014 15-Apr-2014 ```
`t2 = dateshift(t,'dayofweek','Friday')`
```t2 = 2x1 datetime 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 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 23-Feb-2021 ```
`t2 = dateshift(t,'end','week',5)`
```t2 = datetime 03-Apr-2021 ```

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

`t = datetime('today')`
```t = datetime 23-Feb-2021 ```
`t2 = dateshift(t,'dayofweek','Friday',1:3)`
```t2 = 1x3 datetime 26-Feb-2021 05-Mar-2021 12-Mar-2021 ```

## 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'`

Example: `t2 = dateshift(t,'start','hour')`

Example: `t2 = dateshift(t,'end','month')`

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: ```t2 = dateshift(t,'dayofweek','Sunday')```

Example: `t2 = dateshift(t,'dayofweek',1)`

Rule for shifting `datetime` values, specified as `'next'`, `'previous'`, `'nearest'`, `'current'`, a scalar integer, or an array of integers.

The table describes the rules for shifting `datetime` values.

RuleDescription

`'next'`

Shift `datetime` value to next unit of time or specified day of week.

Note: This rule is the default rule for the `'dayofweek'` input argument.

`'previous'`

Shift `datetime` value to previous unit of time or specified day of week.

`'nearest'`

Shift `datetime` value to nearest occurrence of the unit of time or specified day of week.

In effect, this rule rounds `datetime` values.

`'current'`

Shift `datetime` value within the current unit of time, or to the specified day within the current week.

Note: This rule is the default rule for the `'start'` and `'end'` input arguments.

`1`

Equivalent to the `'next'` rule.

`n`, where `n` > `1`

Equivalent to the `'next'` rule applied `n` times.

`0`

Equivalent to the `'current'` rule.

`-1`

Equivalent to the `'previous'` rule.

`-n`, where `n` > `1`

Equivalent to the `'previous'` rule applied `n` times.

Array of integers

Shifts each value in `t` according to the rule specified by the corresponding integer in `rule`.

The input arguments `t` and `rule` must have the same size, or one of them must be scalar.

Behavior When `datetime` Values Match `'dayofweek'` Argument

If you specify `'dayofweek'` and `t` contains `datetime` values that fall on the specified 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','Thursday',rule)` returns a `datetime` value with a date of December 24, 2015 if `rule` is `'next'`, `'previous'`, `'nearest'`, `1`, or `-1`, because December 24, 2015 is a Thursday.

## See Also

Introduced in R2014b

Download ebook