addtodate

(Not recommended; use duration or calendarDuration) Add time to serial date number

addtodate is not recommended. Use the datetime data type to represent points in time, and duration or calendarDuration values to add time to datetime values. For more information on updating your code, see Version History or Replace Discouraged Instances of Serial Date Numbers and Date Strings.

Syntax

dt = addtodate(d,t,timeUnit)

Description

dt = addtodate(d,t,timeUnit) adds the length of time t to the serial date number d and returns the result as another serial date number dt. The input argument timeUnit specifies the time unit of t. For example, addtodate(d,12,"hours") adds 12 hours to the date and time represented by d.

Examples

Add Time to Serial Date Numbers

Create a serial date number that represents January 1, 2022.

d = datenum("2022-01-01")

d = 
738522

Add 14 days to d. For display, convert the date number to a datetime value.

dt = addtodate(d,14,"day")

dt = 
738536

datetime(dt,"ConvertFrom","datenum")

ans = datetime
   15-Jan-2022

Subtract 12 hours from dt by specifying the second input argument as a negative number.

dt = addtodate(dt,-12,"hour")

dt = 
7.3854e+05

datetime(dt,"ConvertFrom","datenum")

ans = datetime
   14-Jan-2022 12:00:00

If the added length of time is large enough, then dt rolls over into the appropriate time period, either forward or backward. For example, adding 30 days to dt shifts the date into February.

dt = addtodate(dt,30,"day");
datetime(dt,"ConvertFrom","datenum")

ans = datetime
   13-Feb-2022 12:00:00

Input Arguments

d — Input date and time

serial date number

Input date and time, specified as a serial date number.

t — Length of time

integer

Length of time to add to d, specified as an integer between –10¹⁶ and 10¹⁶, inclusive.

timeUnit — Time unit of t

"year" | "month" | "day" | "hour" | "minute" | "second" | "millisecond"

Time unit of t, specified as one of the listed values.

Version History

Introduced before R2006a

R2022b: Not recommended

There are no plans to remove addtodate. However, the datetime, duration, and calendarDuration data types are recommended instead. The datetime data type provides flexible date and time formats, storage out to nanosecond precision, and properties to account for time zones and daylight saving time. You can add lengths of time to datetime values by using duration values (for hours, minutes, and seconds) or calendarDuration values (for calendar years, quarters, months, weeks, or days).

For example, convert a serial date number to a datetime value. Then add an array of hours, in 4-hour increments, by using the hours function to create an array of duration values. The result is an array of datetime values.

d = 738522;
d = datetime(d,"ConvertFrom","datenum")

d = datetime
   01-Jan-2022

d = d + hours(0:4:12)

d = 1x4 datetime array
   01-Jan-2022 00:00:00   01-Jan-2022 04:00:00   01-Jan-2022 08:00:00   01-Jan-2022 12:00:00

Add 3 calendar months and 2 calendar weeks to a datetime value that represents January 1, 2022, 12:00 p.m. by using the calmonths and calweeks functions to create calendarDuration values. The result is a datetime value that represents April 15, 2022, 12:00 p.m.

d = datetime("01-Jan-2022 12:00:00");
d = d + calmonths(3) + calweeks(2)

d = datetime
   15-Apr-2022 12:00:00