addtodate

Modify date number by field

Syntax

R = addtodate(D, Q, F)


Description

R = addtodate(D, Q, F) adds quantity Q to the indicated date field F of a scalar serial date number D, returning the updated date number R.

The quantity Q to be added can be a positive or negative integer. The absolute value of Q must be less than or equal to 1e16. The date field F must be a character vector or string scalar equal to one of the following: 'year', 'month', 'day', 'hour', 'minute', 'second', or 'millisecond'.

If the addition to the date field causes the field to roll over, the MATLAB^® software adjusts the next more significant fields accordingly. Adding a negative quantity to the indicated date field rolls back the calendar on the indicated field. If the addition causes the field to roll back, MATLAB adjusts the next less significant fields accordingly.

Examples

Modify the hours, days, and minutes of a given date:

t = datenum('07-Apr-2008 23:00:00');
datestr(t)
ans =
   07-Apr-2008 23:00:00

t= addtodate(t, 2, 'hour');
datestr(t)
ans =
   08-Apr-2008 01:00:00

t= addtodate(t, -7, 'day');
datestr(t)
ans =
   01-Apr-2008 01:00:00

t= addtodate(t, 59, 'minute');
datestr(t)
ans =
   01-Apr-2008 01:59:00

Adding 20 days to the given date in late December causes the calendar to roll over to January of the next year:

R = addtodate(datenum('12/24/2007 12:45'), 20, 'day');

datestr(R)
ans =
   13-Jan-2008 12:45:00