# 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.

Note: This page has been translated by MathWorks. Please click here
To view all translated materials including this page, select Japan from the country navigator on the bottom of this 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.

## See Also

#### Introduced in R2014b

Was this topic helpful?

#### The Manager's Guide to Solving the Big Data Conundrum

Download white paper