DateAdd Function (Visual Basic)

Article
11/16/2012

Returns a Date value containing a date and time value to which a specified time interval has been added.

Public Overloads Function DateAdd( _
   ByVal Interval As DateInterval, _
   ByVal Number As Double, _
   ByVal DateValue As DateTime _
) As DateTime
' -or-
Public Overloads Function DateAdd( _
   ByVal Interval As String, _
   ByVal Number As Double, _
   ByVal DateValue As Object _
) As DateTime

Parameters

Interval
Required. DateInterval enumeration value or String expression representing the time interval you want to add.
Number
Required. Double. Floating-point expression representing the number of intervals you want to add. Number can be positive (to get date/time values in the future) or negative (to get date/time values in the past). Any fractional part of Number is ignored.
DateValue
Required. Date. An expression representing the date and time to which the interval is to be added. DateValue itself is not changed in the calling program.

Settings

The Interval argument can have one of the following settings.

Enumeration value	String	Unit of time interval to add
DateInterval.Day	d	Day; truncated to integral value
DateInterval.DayOfYear	y	Day; truncated to integral value
DateInterval.Hour	h	Hour; truncated to integral value
DateInterval.Minute	n	Minute; truncated to integral value
DateInterval.Month	m	Month; truncated to integral value
DateInterval.Quarter	q	Quarter; truncated to integral value
DateInterval.Second	s	Second; truncated to integral value
DateInterval.Weekday	w	Day; truncated to integral value
DateInterval.WeekOfYear	ww	Week; truncated to integral value
DateInterval.Year	yyyy	Year; truncated to integral value

Exceptions

Exception type	Error number	Condition
InvalidCastException	13	DateValue is not coercible to Date.
ArgumentException	5	Interval is invalid.
ArgumentOutOfRangeException	9	Calculated date is before 00:00:00 on January 1 of the year 1, or later than 23:59:59 on December 31, 9999.

See the "Error number" column if you are upgrading Visual Basic 6.0 applications that use unstructured error handling. (You can compare the error number against the Number Property (Err Object).) However, when possible, you should consider replacing such error control with Structured Exception Handling Overview for Visual Basic.

Remarks

You can use the DateAdd function to add or subtract a specified time interval from a date. For example, you can calculate a date 30 days from today or a time 45 minutes before now.

To add days to DateValue, you can use DateInterval.Day, DateInterval.DayOfYear, or DateInterval.Weekday. These are treated as equivalent because DayOfYear and Weekday are not meaningful time intervals.

The DateAdd function never returns an invalid date. If necessary, the day part of the resulting date is adjusted downward to the last day of the resulting month in the resulting year. The following example adds one month to January 31:

Dim NextMonth As Date = DateAdd(DateInterval.Month, 1, #1/31/1995#)

In this example, DateAdd returns #2/28/1995#, not #2/31/1995#. If DateValue is #1/31/1996#, it returns #2/29/1996# because 1996 is a leap year.

Note

DateAdd uses the current calendar setting from the CurrentCulture property of the CultureInfo class in the System.Globalization namespace. The default CurrentCulture values are determined by Control Panel settings.

Since every Date value is supported by a DateTime structure, its methods give you additional options in adding time intervals. For example, you can add a fractional number of days, rounded to the nearest millisecond, to a Date variable as follows:

Dim NextTime As Date = Now        ' Current date and time.
NextTime = NextTime.AddDays(3.4)  ' Increment by 3 2/5 days.

Example

This example takes a date and, using the DateAdd function, displays a corresponding date a specified number of months in the future.

Dim Msg, Number, StartDate As String   'Declare variables.
Dim Months As Double 
Dim SecondDate As Date 
Dim IntervalType As DateInterval
IntervalType = DateInterval.Month   ' Specifies months as interval.
StartDate = InputBox("Enter a date")
SecondDate = CDate(StartDate)
Number = InputBox("Enter number of months to add")
Months = Val(Number)
Msg = "New date: " & DateAdd(IntervalType, Months, SecondDate)
MsgBox(Msg)

Requirements

Namespace: Microsoft.VisualBasic

Module: DateAndTime

Assembly: Visual Basic Runtime Library (in Microsoft.VisualBasic.dll)

Share via