Class

Date


Warning

This item was deprecated in version 2019r2. Please use DateTime as a replacement.

Description

A Date object stores the number of seconds since 12:00 AM, January 1, 1904, i.e., "1904-01-01 00:00:00". Properties of a Date enable you to get and set a day value only, a date/time, or only a time.

Methods

Name

Parameters

Returns

Shared

Constructor

Constructor

CopyDate As Date

Constructor

Year As Integer, Month As Integer = 1, Day As Integer = 1, hour As Integer = 0, minute As Integer = 0, second As Integer = 0

Constructor

Year As Integer, Month As Integer = 1, Day As Integer = 1, hour As Integer = 0, minute As Integer = 0, second As Integer = 0, GMTOffset As Double

Property descriptions


Date.AbbreviatedDate

AbbreviatedDate As String

Reports the Date in the user's abbreviated Date format as a String based on the user's locale and formatting even if the user's locale is a Unicode-only locale.

This property is read-only.

Changing the user's system settings for this format will change the format that AbbreviatedDate uses. On Mac, the AbbreviatedDate property is controlled by the Medium format setting. On Windows, it is an abbreviated version of the Long Date format.

The following code displays the current Date in the AbbreviatedDate format.

Dim d As New Date
Label1.Text = d.AbbreviatedDate

Date.Day

Day As Integer

The day number of the Date.

The following displays the current day:

Var d As Date = Date.Now
Label1.Text = d.Day.ToString

Date.DayOfWeek

DayOfWeek As Integer

The day of the week as an integer: 1=Sunday, 7=Saturday.

This property is read-only.

The following displays the current day of the week.

Var d As Date = Date.Now
Label1.Text = d.DayOfWeek.ToString

Date.DayOfYear

DayOfYear As Integer

The number days into the year that the Date falls on.

This property is read-only.

The following code displays the current day of the year.

Var d As Date = Date.Now
Label1.Text = d.DayOfYear.ToString

Date.GMTOffset

GMTOffset As Double

The difference between local time and Greenwich Mean Time (aka UTC) in hours. Changing the GMTOffset changes the time stored by the Date object.

The following code changes the GMT offset.

Dim d As New Date
d.Day = 13
d.Month = 8
d.Year = 1956
d.GMTOffset = -7

Date.Hour

Hour As Integer

The hour number of the time portion of the Date, using a 24-hour clock.

The following example displays the current hour.

Var d As Date = Date.Now
Label1.Text = d.Hour.ToString

Date.LongDate

LongDate As String

Reports the Date in the user's long Date format as a string based on the user's locale and formatting even if the user's locale is a Unicode-only locale.

This property is read-only.

For example (US default format): Wednesday, December 31, 1997. The LongDate property uses the Long format on Windows and the Full format on Mac. Changing the user's system settings for these formats changes the format that the LongDate property uses.

The following example displays the current Date in the LongDate format for the user's operating system.

Dim d As New Date
Label1.Text = d.LongDate

Date.LongTime

LongTime As String

Reports the Date in the user's long time format as a string based on the user's locale and formatting even if the user's locale is a Unicode-only locale.

This property is read-only.

For example (US format): 2:32:40 PM.

The following example displays the current time in the LongTime format.

Dim d As New Date
d.GMTOffset = -7

Label1.Text = d.Longtime

Date.Minute

Minute As Integer

The minute number of the time portion of the Date.

The following code displays the current minute.

Var d As Date = Date.Now
Label1.Text = d.Minute.ToString

Date.Month

Month As Integer

The month number of the Date.

The following code displays the current month:

Var d As Date = Date.Now
MonthLabel.Value = d.Month.ToString

Date.Second

Second As Integer

The second number of the time portion of the Date.

The following code displays the Second property.

Var d As Date = Date.Now
Label1.Text = d.Second.ToString

Date.ShortDate

ShortDate As String

Reports the Date in the user's short Date format as a string based on the user's locale and formatting even if the user's locale is a Unicode-only locale.

This property is read-only.

For example (US format): 12/31/97. The ShortDate format uses the Short format on both Windows and Mac. Changing this format changes the format that the ShortDate property uses.

The following code displays today's Date in the ShortDate format.

Dim d As New Date
Label1.Text = d.ShortDate

Date.ShortTime

ShortTime As String

Reports the Date in the user's short time format as a string based on the user's locale and formatting even if the user's locale is a Unicode-only locale.

This property is read-only.

This is an example of the short time (US format): 2:32 PM.

The following code reports the current time in the ShortTime format.

Dim d As New Date

Label1.Text = d.ShortTime

Date.SQLDate

SQLDate As String

Gets and sets the Date in SQL Date format, YYYY-MM-DD. Passing a bad string will result in an UnsupportedFormatException.

This is an example for a SQL Date: 2008-09-03

The following code displays the SQLDate value for the current Date.

Var d As Date = Date.Now
Label1.Text = d.SQLDate

Date.SQLDateTime

SQLDateTime As String

Gets and sets the Date in SQL date/time format, YYYY-MM-DD HH:MM:SS. Passing a bad string will result in an UnsupportedFormatException.

This is an example of an SQL date/time: 2008-09-03 13:39:16

The following code displays the current SQL date/time.

Var d As Date = Date.Now
Label1.Text = d.SQLDateTime

Date.TotalSeconds

TotalSeconds As Double

The number of seconds since 12:00AM, January 1, 1904, local time.

TotalSeconds is the "master" property from which other ways of expressing date/time are derived. A negative value of TotalSeconds indicates a Date/Time prior to January 1, 1904. Very, very large values of TotalSeconds will cause the value to be set to zero.

On Windows (due to the Windows API being used), it is not possible to go back further than 1 January 1601.

You can use TotalSeconds to calculate elapsed seconds:

Dim d1 As New Date
Dim startTime As Double = d1.TotalSeconds
' Do some long process
d2 = New Date
Dim endTime As Double = d2.TotalSeconds
Dim elapsedSeconds = endTime - startTime

Date.WeekOfYear

WeekOfYear As Integer

The number of the week of the year the Date falls in.

This property is read-only.

The first week is numbered 1. The first week may be incomplete. If January 1 falls on a Saturday, then the next day is in week 2.

The following code displays the current week of the year.

Var d As Date = Date.Now
MessageBox("Week: " + d.WeekOfYear.ToString)

Date.Year

Year As Integer

The year portion of the Date.

The following code displays the current year.

Var d As Date = Date.Now
Label1.Text = d.Year.ToString

Method descriptions


Date.Constructor

Constructor

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Sets the new Date object to be equal to the current Date (and time).


Date.Constructor

Constructor(CopyDate as Date)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Sets the new Date object to have the same Date information as the passed Date.


Date.Constructor

Constructor(Year as Integer, Month as Integer = 1, Day as Integer = 1, hour as Integer = 0, minute as Integer = 0, second as Integer = 0)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Sets the new Date object to the passed Year, Month, and Day, Hour, Minute. and Second.


Date.Constructor

Constructor(Year as Integer, Month as Integer = 1, Day as Integer = 1, hour as Integer = 0, minute as Integer = 0, second as Integer = 0, GMTOffset as Double)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Sets the new Date object to the passed Year, Month, Day, Hour, Minute, Second, and GMTOffset. Requires setting the GMT offset.

The following code sets the date/time value using the constructor and displays it in a Label.

Dim d As New Date(1956, 8, 13, 8, 23, 0, -7)
Label1.Text = d.SQLDateTime

Notes

Note

On Windows (due to the Windows API being used), it is not possible to go back further than 1 January 1601.

When you create and instantiate a Date object, it is initialized to the current Date and time. Therefore the order of assignment is important: when dealing with a day that exists in one month when the current system Date is in another (such as December 31 when you're in November), setting the Day before the month can result in an unexpected (here 12/01/2011) or even invalid Date. Not setting the year before entering Feb 29 will cause oddities if the current year is not a leap year.

Because Date implements Operator Compare, you can use the normal comparison operators to compare Date values.

If you try to set the Date or date/time and the format is incorrect, an UnsupportedFormatException is raised.

The Date properties of FolderItems can be accessed via the CreationDate and ModificationDate properties of FolderItem objects. You can get the current Date and time by creating a new Date and reading the values of the Year, Month, Day, Hour, Minute, and Second properties.

In the following code:

Dim v As Variant
Dim d As Date
d = New Date
v = d

What is actually happening is that the Variant stores the value of the TotalSeconds property as a Double, along with the type information that it is a Date (the Variant's Type property = 7).

Although Date is a class that is subclassed from Object, VarType identifies a Date as a Date data type (Type=7) rather than an Object (Type=9).

Use the DateTime function to convert a Date string to a Date value.

The TotalSeconds property is the “master” property that stores the date/time associated with a Date. The other property values are derived from TotalSeconds. If you change the value of the TotalSeconds property, the values of the Year, Month, Day, Hour, Minute, and Second properties change to reflect the second on which TotalSeconds occurs. Conversely, if you change any of these properties, the value of TotalSeconds changes commensurately.

The Date properties that return formatted Date or time information are affected by the user's operating system settings. The user's system settings control the formats that are used.

You can use the Str function to obtain the string value of the Date in SQL date/time format, i.e., the following gets the string value of the current date/time:

Dim d As New Date
MsgBox(Str(d))

On Windows, the Regional and Language Options panel determines how dates are formatted. On macOS, the Date formats are specified in the Languages & Region System Preferences panel.

If you need to control the exact appearance of date/time information, the best way is to extract the information yourself and manage the formatting using string manipulation functions.

The DateTime function accepts a Date as a string and converts it to a Date object. It accepts only Date strings that are in any of the formats specified by the user's system settings.

Sample code

This code creates a Date object and sets it to 15 April, 2012.

Dim d As New Date(2012, 4, 15)

This code creates a Date and displays the current Date in a message box.

Dim d As New Date
MsgBox(d.ShortDate)

This code sets a Date object to 10 February 1954.

Dim d As New Date
d.Year = 1954
d.Month = 2
d.Day = 10
MsgBox(d.ShortDate)

The following code compares a specific Date to the current Date:

Dim d As New Date
d.Year = 2012
d.Month = 12
d.Day = 5

Dim today As New Date ' Newly created dates default to the current date and time

If d < today Then
  MsgBox("That's before today!")
End If

If d > today Then
  MsgBox("That's after today!")
End If

If d = today Then
  MsgBox("That's today!")
End If

Compatibility

All project types on all supported operating systems.

See also

Object parent class; System, DateTime, Str, System functions; FolderItem, DateTime classes