DateAdd Function VB.NET

A String expression (see the first item in Rules at a Glance) or a member of the DateInterval enumeration (see the second item in Rules at a Glance) that specifies the interval of time to add.

An expression denoting the number of time intervals you want to add (it can be positive or Negative

Date representing the starting date to which the interval is to be added

Return Value
A past or future Date that reflects the result of the addition

Description
Returns a Date representing the result of adding (or subtracting, ifnumberis negative) a given number of time periods to or from a given date. For instance, you can calculate the date 178 months before today's date, or the date and time 12,789 minutes from now.

Rules at a Glance

intervalcan be one of the following literal strings:

TABLE

intervalcan also be a member of the DateInterval enum:

Enum DateInterval

Day

DayOfYear

Hour

Minute

Month

Quarter

Second

Week

Weekday

WeekOfYear

End Enum

Ifnumberis positive, the result will be in the future; ifnumberis negative, the result will be in the past. (The meaning of "future" and "past" here is relative todatevalue).

TheDateAddfunction has a built-in calendar algorithm to prevent it from returning an invalid date. For example, you can add 10 minutes to 31 December 1999 23:55, andDateAddautomatically recalculates all elements of the date to return a valid date, in this case 1 January 2000 00:05. This includes leap years: the calendar algorithm takes the presence of 29 February into account for leap years.

Example
DateAdd(DateInterval.Day, 120, #3/3/2001#) ' Returns 7/1/2001

Programming Tips and Gotchas

You can check that a date is valid using theIsDatefunction prior to passing it as a parameter to the function.

To add a number of days todatevalue, use either the day of the year ("y" or DateInterval.DayOfYear), the day ("d" or DateInterval.Day), or the weekday ("w" or DateInterval.Weekday).

DateAddgenerates an error if the result does not lie in the range of dates of the Date data type.

Ifnumbercontains a fractional value, it is rounded to the nearest whole number before being used in the calculation.

You can also use the members of the DateTime structure of the BCL to manipulate dates and times.

A String expression (see the first item in Rules at a Glance) or a member of the DateInterval enumeration (see the second item in Rules at a Glance) that specifies the units of time used to express the difference betweendate1anddate2

The starting and ending dates, whose difference is computed asdate2-date1

A member of the FirstDayOfWeek enum

A member of the FirstWeekOfYear enum

Return Value
A Long specifying the number of time intervals between the two dates

Description
Calculates the number of time intervals between two dates. For example, you can use the function to determine how many days there are between 1 January 1980 and 31 May 1998.

Rules at a Glance

intervalcan be one of the following literal strings:

TABLE

intervalcan also be a member of the DateInterval enum:

Enum DateInterval

Day

DayOfYear

Hour

Minute

Month

Quarter

Second

Week

Weekday

WeekOfYear

End Enum

To calculate the number of days betweendate1anddate2, you can use either of the DateInterval constants, DayOfYear or Day, or the string literals "y" or "d".

Whenintervalis Weekday or "w",DateDiffreturns the number of weeks between the two dates. Ifdate1falls on a Monday,DateDiffcounts the number of Mondays untildate2. It countsdate2, but notdate1. Ifintervalis Week or "ww", however,DateDiffreturns the number of calendar weeks between the two dates. It counts the number of Sundays betweendate1anddate2.DateDiffcountsdate2if it falls on a Sunday, but it doesn't countdate1, even if it does fall on a Sunday.

TheDayOfWeekargument affects calculations that use the Week or "w" and Weekday or "ww"intervalsettings only.

Example

Programming Tips and Gotchas

When working with dates, always check that a date is valid using theIsDatefunction prior to passing it as a function parameter.

Ifdate1ordate2is enclosed in double quotation marks (" ") and you omit the year, the current year is inserted in your code each time thedate1ordate2expression is evaluated. This makes it possible to write code that can be used in different years.

When comparing December 31 to January 1 of the immediately succeeding year,DateDiffwithintervalset equal to Year, or "yyyy" returns 1 even though only a day has elapsed.

DateDiffconsiders the four quarters of the year to be January 1-March 31, April 1-June 30, July 1-September 30, and October 1-December 31. Consequently, when determining the number of quarters between March 31 and April 1 of the same year, for example,DateDiffreturns 1, even though the latter date is only one day after the former.

Ifintervalis Month or "m",DateDiffsimply counts the difference in the months in which the respective dates fall. For example, when determining the number of months between January 31 and February 1 of the same year,DateDiffreturns 1, even though the latter date is only one day after the former.

In calculating the number of hours, minutes, or seconds between two dates, if an explicit time is not specified,DateDiffprovides a default value of midnight (00:00:00).

A String literal (see the second item in Rules at a Glance) or a constant of the DateInterval enum (see the third item in Rules at a Glance) that defines the part of the date/time to extract fromdatevalue

Return Value
An Integer containing the specified part

Description
Extracts an individual component of the date or time (like the month or the second) from a date/time
Value

Rules at a Glance

TheDatePartfunction returns an Integer containing the specified portion of the given date.DatePartis a single function encapsulating the individualYear,Month,Day,Hour,Minute, andSecondfunctions.

intervalcan be one of the following literal strings:

TABLE

interval can also be a member of the DateInterval enum:

Enum DateInterval

Day

DayOfYear

Hour

Minute

Month

Quarter

Second

Week

Weekday

WeekOfYear

End Enum

The firstdayofweekvalue argument can be any of the following members of the FirstDayOfWeek enumeration:

Enum FirstDayOfWeek

System 'uses first day of week setting on local system

Sunday

Monday

Tuesday

Wednesday

Thursday

Friday

Saturday

End Enum

The firstdayofweekvalue argument affects only calculations that use either the Week (or "w") or Weekday (or "ww") interval values.

The firstweekofyearvalue argument can be any of the following members of the FirstWeekOfYear enumeration:

TABLE

Example
MsgBox("Current hour: " & DatePart(DateInterval.Hour, Now))

Programming Tips and Gotchas

When working with dates, always check that a date is valid using the IsDate function prior to passing it as a function parameter.

If you attempt to extract the hours, minutes, or seconds, but datevalue does not contain the necessary time element, the function assumes a time of midnight (0:00:00).

If you specify datevalue within quotation marks (" ") and omit the year, the year is assumed to be the current year taken from the computer's date. For example:

Console.WriteLine(DatePart(DateInterval.Year, cDate("01/03")))

VB .NET/VB 6 Differences

VB 6 lacks the DateInterval enumeration and therefore only accepts a string as the interval argument.

VB 6 supports a number of constants beginning with vb... as values for the firstdayofweekvalue and firstweekofyearvalue arguments. While these are still supported in VB .NET, VB .NET has also added the FirstDayOfWeek and FirstWeekOfYear enumerations.

DateSerial Function

Class
Microsoft.VisualBasic.DateAndTime

Syntax
DateSerial(year, month, day)

Return Value
A Date representing the date specified by the arguments

Description
Returns a Date whose value is specified by the three date components (year, month, and day). For the function to succeed, all three components must be present, and all must be numeric values. The value returned by the function takes the short date format defined by the Regional Settings applet in the Control Panel of the client machine.

Rules at a Glance

If the value of a particular element exceeds its normal limits, DateSerial adjusts the date accordingly. For example, if you tried DateSerial(96,2,31)—February 31, 1996— DateSerial returns March 2, 1996.

You can specify expressions or formulas that evaluate to individual date components as parameters to DateSerial. For example, DateSerial(98,10+9,23) returns 23 March 1999. This makes it easier to use DateSerial to form dates whose individual elements are unknown at design time or that are created on the fly as a result of user input.

Example

Programming Tips and Gotchas

If any of the parameters exceed the range of the Integer data type (-32,768 to 32,767), an error (runtime error 6, "Overflow") is generated.

DateSerial handles two-digit years in the same way as other Visual Basic date functions. A year argument between 0 and 29 is taken to be in the 21st century (2000 to 2029); year arguments between 30 and 99 are taken to be in the 20th century (1930 to 1999). Of course, the safest way to specify a year is to use the full four digits.

DateString Property

Class
Microsoft.VisualBasic.DateAndTime

Syntax
DateString( )

Return Value
A String representing the current system date

Description
Returns or sets a string representing the current system date in the format "mm-dd-yyyy"

Rules at a Glance
The allowed formats for setting the date are "m-d-yyyy," "m-d-y," "m/d/yyyy," and "m/d/y."

Programming Tips and Gotchas

To get or set the current system time as a String, use the TimeString property.

To access the current system date as a Date, use the Today property.

VB .NET/VB 6 Differences
The DateString property is new to VB .NET. It is a replacement for the VB 6 Date statement, which sets the system date, and the Date and Date$ functions, which retrieve the system date.

DateValue Function

Class
Microsoft.VisualBasic.DateAndTime

Syntax
DateValue(stringdate)

Return Value
A Date that represents the date specified by the stringdate argument

Description
Returns a Date containing the date represented by stringdate.
The date value is formatted according to the short date setting defined by the Regional Settings appletin the Control Panel. DateValue can successfully recognize a stringdate in any of the date formats recognized by IsDate. DateValue does not return time values in a date/time string; they are simply dropped. However, if stringdate includes a valid date value but an invalid time value, a runtime error results.

Rules at a Glance

The order of the day, month, and year within stringdate must be the same as the sequence defined by the computer's regional settings.

Only those date separators recognized by IsDate can be used.

If you don't specify a year in your date expression, DateValue uses the current year from the computer's system date.

Example

Programming Tips and Gotchas

When working with dates, always check that a date is valid using the IsDate function prior to passing it as a function argument.

If stringdate includes time information as well as date information, the time information is ignored; however, if only time information is passed to DateValue, an error is generated.

DateValue handles two-digit years in the following manner: Year arguments between 0 and 29 are taken to be in the 21st century (2000 to 2029), while year arguments between 30 and 99 are taken to be in the 20th century (1930 to 1999). Of course, the safest way to specify a year is to use the full four digits.

On Windows NT/2000 systems, the date formats are held as string values in the following registry keys:

The more common approach to date conversion is to use the CDate function. Microsoft also recommends using the C... conversion functions due to their enhanced capabilities and their locale awareness.