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(t,'dayofweek','weekend')

t2 = dateshift(t,'dayofweek','weekday')

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.

For example, if you shift 9:14 a.m., June 27, 2021 to the start of the hour, then the shifted value is 9:00 a.m., June 27, 2021. If you shift it to the start of the month, then the shifted value is 12:00 a.m., June 1, 2021.

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 day, hour, minute, or second. For example, if you shift 9:14 a.m., June 27, 2021 to the end of the hour, then the shifted value is 10:00 a.m., June 27, 2021.

• The end of a year, quarter, month, or week is midnight at the beginning of the last day of that year, quarter, month, or week. For example, if you shift 9:14 a.m., June 27, 2021 to the end of the month, then the shifted value is 12:00 a.m., June 30, 2021.

t2 = dateshift(t,'dayofweek',dow) shifts to the specified day of the week that occurs on or after each datetime value in array t. If a date in t already falls on the specified day of the week, then dateshift returns the same date.

t2 = dateshift(t,'dayofweek','weekend') shifts to the weekend day (either Saturday or Sunday) that occurs on or after each datetime value in array t.

t2 = dateshift(t,'dayofweek','weekday') shifts to the weekday (Monday–Friday) that occurs on or after each datetime value in array t.

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 Start of Year

Create a datetime value with the current date.

t = datetime('today')

t = datetime
   19-Aug-2023

Shift the date to the start of the year.

t2 = dateshift(t,'start','year')

t2 = datetime
   01-Jan-2023

Shift Current Date to End of Month

Create a datetime value with the current date.

t = datetime('today')

t = datetime
   19-Aug-2023

Shift the date to the end of the same month.

t2 = dateshift(t,'end','month')

t2 = datetime
   31-Aug-2023

Start and End of Next Month

Create a datetime value.

t = datetime('today')

t = datetime
   19-Aug-2023

Shift the date to the start of the next month.

t2 = dateshift(t,'start','month','next')

t2 = datetime
   01-Sep-2023

Shift the date to the end of the next month.

t3 = dateshift(t,'end','month','next')

t3 = datetime
   30-Sep-2023

Shift Dates to Specific Days of Week

Create a datetime array. Format it to display day of the week and the date.

Shift an array of dates forward to the next Friday.

t = [datetime(2014,08,03) datetime(2014,04,15)];
t.Format = 'eeee, dd MMM yyyy'

t = 1x2 datetime
   Sunday, 03 Aug 2014    Tuesday, 15 Apr 2014

Shift the dates forward to the next Friday.

t2 = dateshift(t,'dayofweek','Friday')

t2 = 1x2 datetime
   Friday, 08 Aug 2014   Friday, 18 Apr 2014

Shift the dates backward to the previous Monday.

t3 = dateshift(t,'dayofweek','Monday','previous')

t3 = 1x2 datetime
   Monday, 28 Jul 2014   Monday, 14 Apr 2014

Shift to Weekend Days

Create a datetime array. Format it to display day of the week and the date.

t = [datetime(2021,5,30) datetime(2021,6,4)];
t.Format = 'eeee, dd MMM yyyy'

t = 1x2 datetime
   Sunday, 30 May 2021   Friday, 04 Jun 2021

Shift to the first weekend day that occurs on or after each value in t. Because Sunday is already a weekend day, the first datetime value is not shifted. But the second value shifts from Friday to Saturday.

t2 = dateshift(t,'dayofweek','weekend')

t2 = 1x2 datetime
   Sunday, 30 May 2021     Saturday, 05 Jun 2021

Shift to Weekday

Create a datetime array. Format it to display day of the week and the date.

t = [datetime(2021,5,30) datetime(2021,6,4)];
t.Format = 'eeee, dd MMM yyyy'

t = 1x2 datetime
   Sunday, 30 May 2021   Friday, 04 Jun 2021

Shift to the first weekday that occurs on or after each value in t. Sunday shifts to Monday. But because Friday is already a weekday, the second datetime value is not shifted.

t2 = dateshift(t,'dayofweek','weekday')

t2 = 1x2 datetime
   Monday, 31 May 2021   Friday, 04 Jun 2021

Determine Future Date by Using Numeric Rule

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

t = datetime('today');
t.Format = 'eeee, dd MMM yyyy'

t = datetime
   Saturday, 19 Aug 2023

t2 = dateshift(t,'end','week',5)

t2 = datetime
   Saturday, 23 Sep 2023

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
   19-Aug-2023

t2 = dateshift(t,'dayofweek','Friday',1:3)

t2 = 1x3 datetime
   25-Aug-2023   01-Sep-2023   08-Sep-2023

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 these values:

• 'year'

• 'quarter'

• 'month'

• 'week'

• 'day'

• 'hour'

• 'minute'

• 'second'

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

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

dow — Name or number for day of week

string scalar | character vector | integer between 1–7

Name or number for a day of the week, specified as a string scalar or character vector that is a localized day name or an integer between 1–7.

Integers between 1–7 correspond to days of the week, as shown in the table.

1	Sunday
2	Monday
3	Tuesday
4	Wednesday
5	Thursday
6	Friday
7	Saturday

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. You can use this rule to round 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.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

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

Version History

Introduced in R2014b