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.

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.

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.

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

Shift Current Date to End of Current Month

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

Shift Current Date to Next Month

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 Dates to Specific Day of Week

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

Determine Future Date

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 Sequence of Dates Falling on Specific Day of Week

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

t — Input date and time

datetime array

Input date and time, specified as a datetime array.

unit — Unit of time

'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second'

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')

dow — Day of week

scalar integer | character vector | string scalar

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 — Rule for shifting datetime values

'next' | 'previous' | 'nearest' | 'current' | scalar integer | array of integers

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.

Rule	Description
'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.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

This function fully supports tall arrays. For more information, see Tall Arrays.

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).