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.
Properties
Name |
Type |
Read-Only |
Shared |
---|---|---|---|
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
Methods
Name |
Parameters |
Returns |
Shared |
---|---|---|---|
CopyDate As Date |
|||
Year As Integer, Month As Integer = 1, Day As Integer = 1, hour As Integer = 0, minute As Integer = 0, second As Integer = 0 |
|||
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.