dateshift - Shift date or generate sequence of dates and times - MATLAB (original) (raw)
Shift date or generate sequence of dates and times
Syntax
Description
t2 = dateshift([t](#bugc7jv-1%5Fsep%5Fshared-t),'start',[unit](#bugc7jv-1-unit)) shifts the dates and times in the input datetime array. The function shifts each element of the array back to the beginning of the unit of time specified by unit. The output t2 is the same size as the input 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](#bugc7jv-1%5Fsep%5Fshared-t),'end',[unit](#bugc7jv-1-unit)) shifts the dates and times ahead to the end of the unit of time specified byunit.
- 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](#bugc7jv-1%5Fsep%5Fshared-t),'dayofweek',[dow](#bugc7jv-1-dow)) shifts to the specified day of the week that occurs on or after eachdatetime value in array t. If a date in t already falls on the specified day of the week, thendateshift returns the same date.
t2 = dateshift([t](#bugc7jv-1%5Fsep%5Fshared-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](#bugc7jv-1%5Fsep%5Fshared-t),'dayofweek','weekday') shifts to the weekday (Monday–Friday) that occurs on or after eachdatetime value in array t.
t2 = dateshift(___,[rule](#bugc7jv-1-rule)) shifts each element in array t according to the pattern specified byrule. You can use this syntax with any of the arguments in the previous syntaxes.
Examples
Create a datetime value with the current date.
Shift the date to the start of the year.
t2 = dateshift(t,'start','year')
t2 = datetime 01-Jan-2025
Create a datetime value with the current date.
Shift the date to the end of the same month.
t2 = dateshift(t,'end','month')
t2 = datetime 28-Feb-2025
Create a datetime value.
Shift the date to the start of the next month.
t2 = dateshift(t,'start','month','next')
t2 = datetime 01-Mar-2025
Shift the date to the end of the next month.
t3 = dateshift(t,'end','month','next')
t3 = datetime 31-Mar-2025
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 = 1×2 datetime Sunday, 03 Aug 2014 Tuesday, 15 Apr 2014
Shift the dates forward to the next Friday.
t2 = dateshift(t,'dayofweek','Friday')
t2 = 1×2 datetime Friday, 08 Aug 2014 Friday, 18 Apr 2014
Shift the dates backward to the previous Monday.
t3 = dateshift(t,'dayofweek','Monday','previous')
t3 = 1×2 datetime Monday, 28 Jul 2014 Monday, 14 Apr 2014
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 = 1×2 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 = 1×2 datetime Sunday, 30 May 2021 Saturday, 05 Jun 2021
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 = 1×2 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 = 1×2 datetime Monday, 31 May 2021 Friday, 04 Jun 2021
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, 01 Feb 2025
t2 = dateshift(t,'end','week',5)
t2 = datetime Saturday, 08 Mar 2025
Generate a sequence of dates consisting of the next three occurrences of Friday. (If you specify a day of the week by name, then specify a name that is valid for your locale.)
t2 = dateshift(t,'dayofweek','Friday',1:3)
t2 = 1×3 datetime 07-Feb-2025 14-Feb-2025 21-Feb-2025
Input Arguments
Input date and time, specified as a datetime array.
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')
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 between1–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 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 rounddatetime 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 inrule.The input arguments t andrule 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 thosedatetime 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
Thedateshift function fully supports tall arrays. For more information, see Tall Arrays.
Version History
Introduced in R2014b