Class

DateTime


Description

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

Methods

Name

Parameters

Returns

Shared

AddInterval

years As Integer, months As Integer, days As Integer, hours As Integer, minutes As Integer, seconds As Integer, nanoseconds As Integer

DateTime

Constructor

secondsFrom1970 As Double, timeZone As TimeZone = Nil

Constructor

source As Date

Constructor

source As DateTime

Constructor

Year As Integer, Month As Integer, Day As Integer, hour As Integer = 0, minute As Integer = 0, second As Integer = 0, nanosecond As Integer = 0, timeZone As TimeZone = Nil

FromString

dateValue As String, locale As Locale = Nil, timeZone As TimeZone = Nil

DateTime

Now

timeZone As TimeZone = Nil

DateTime

SubtractInterval

years As Integer, months As Integer, days As Integer, minutes As Integer, seconds As Integer, nanoseconds As Integer

DateTime

ToString

loc As Locale = Nil, dateStyle As DateTime.FormatStyles = DateTime.FormatStyles.Medium, timeStyle As DateTime.FormatStyles = DateTime.FormatStyles.Medium

String

Enumerations

DateTime.FormatStyles

FormatStyles

These are the various styles that can be used to convert a Date to String with the ToString method.

Enum

Description

Example

Short

The short date or time format

12/1/2022 - 12:23PM

Medium

The medium date or time format

Dec 1, 2022 - 12:23:06 PM

Long

The long date or time format

December 1, 2022 - 12:23:06 PM CDT

Full

The full date or time format

Thursday, December 1, 2022 - 12:23:06 PM Central Daylight Time

None

Prevents the date or time value from displaying.

Property descriptions


DateTime.Day

Day As Integer

The day number of the date.

This property is read-only.

The following displays the current day:

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

DateTime.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 DateTime = DateTime.Now
Label1.Text = d.DayOfWeek.ToString

DateTime.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 DateTime = DateTime.Now
Label1.Text = d.DayOfYear.ToString

DateTime.Hour

Hour As Integer

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

This property is read-only.

The following example displays the current hour.

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

DateTime.IsDaylightSavingsTime

IsDaylightSavingsTime As Boolean

Indicates whether the DateTime is in daylight savings time or not.

This property is read-only.

The following example displays the current hour.

Var d As DateTime = DateTime.Now
Label1.Text = If(d.IsDaylightSavingsTime, "Yes", "No")

DateTime.Minute

Minute As Integer

The minute number of the time portion of the date.

This property is read-only.

The following code displays the current minute.

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

DateTime.Month

Month As Integer

The month number of the date.

This property is read-only.

The following code displays the current month:

Var d As DateTime = DateTime.Now
MonthLabel.Text = d.Month.ToString

DateTime.Nanosecond

Nanosecond As Integer

The nanoseconds of the time portion of the date. A nanosecond is one billionth of a second.

This property is read-only.

Get the current nanosecond:

Var d As DateTime = DateTime.Now
Var nanosecond As Integer = d.Nanosecond

DateTime.Second

Second As Integer

The second number of the time portion of the date.

This property is read-only.

The following code displays the Second property.

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

DateTime.SecondsFrom1970

SecondsFrom1970 As Double

The number of seconds since the first 1 January 1970, 00:00 GMT.

This property is read-only.

This value is also referred to as the Unix epoch, Unix time or Unix timestamp.

You can save this value (in a file or database, for example) and use a Constructor to create a new Date instance for it. Negative values indicate seconds before 1 January 1970, 00:00 GMT.

Get the seconds since 1970 and use it to create a new date:

Var d1 As DateTime = DateTime.Now
Var seconds As Double = d1.SecondsFrom1970
Var d2 As New DateTime(seconds, TimeZone.Current)
// Both d1 and d2 have the same date value

Calculate the number of days between two dates:

Var d1 As New DateTime(2018, 8, 1)
Var d2 As New DateTime(2015, 3, 1)
// Subtract seconds and convert seconds to days
Var days As Double = (d1.SecondsFrom1970 - d2.SecondsFrom1970) / (24 * 60 * 60)

DateTime.SQLDate

SQLDate As String

Returns the date in SQL date format, YYYY-MM-DD.

This property is read-only.

This is an example for a SQL date: 2019-09-03

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

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

DateTime.SQLDateTime

SQLDateTime As String

Returns the date in SQL date/time format, YYYY-MM-DD HH:MM:SS.

This property is read-only.

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

The following code displays the current SQL date/time.

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

DateTime.TimeZone

TimeZone As TimeZone

The time zone in which the time portion of the DateTime occurs.

This property is read-only.


DateTime.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 DateTime = DateTime.Now
MessageBox("Week: " + d.WeekOfYear.ToString)

DateTime.Year

Year As Integer

The year portion of the date.

This property is read-only.

The following code displays the current year.

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

Method descriptions


DateTime.AddInterval

AddInterval(years As Integer, months As Integer, days As Integer, hours As Integer, minutes As Integer, seconds As Integer, nanoseconds As Integer) As DateTime

Adds the specified interval values to get a new DateTime.

You can also use the + and - operators to add DateIntervals to DateTime objects.

Get the date two months from today:

Var twoMonths As New DateInterval
twoMonths.Months = 2 // 2 month interval

// Get date two months from today
Var future As DateTime = DateTime.Now + twoMonths

// Get date two months before today
Var past As DateTime = DateTime.Now - twoMonths

// Next month
Var nextMonth As DateTime = DateTime.Now.AddInterval(0, 1)

DateTime.Constructor

Constructor(secondsFrom1970 as Double, timeZone as TimeZone = Nil)

Note

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

Creates a date using number of seconds since 1 January 1970, 00:00 GMT. Use a negative value to specify a date before 1 January 1970.


DateTime.Constructor

Constructor(source As Date)

Note

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

Creates a new DateTime object that has the same date information as the passed Date. Use this to convert a Date to a DateTime.


DateTime.Constructor

Constructor(source As DateTime)

Note

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

Creates a new DateTime object that has the same date time information as the passed DateTime.


DateTime.Constructor

Constructor(Year as Integer, Month as Integer, Day as Integer, hour as Integer = 0, minute as Integer = 0, second as Integer = 0, nanosecond as Integer = 0, timeZone as TimeZone = Nil)

Note

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

Creates a new date object based upon the parameters passed.

This example creates a new DateTime of April 1st, 1996:

Var d As New DateTime(1996, 4, 1)

DateTime.FromString

FromString(dateValue As String, locale As Locale = Nil, timeZone As TimeZone = Nil) As DateTime

Converts a textual date/time to an actual DateTime using the optional locale and time zone.

If you do not pass in a time zone, the resulting date is in the current time zone.

When no locale is specified, the dateValue parameter can be in either SQLDate (YYYY-MM-DD) or SQLDateTime (YYYY-MM-DD HH:MM:SS) formats.

If you specify a locale, the dateValue text must be formatted to match the locale you specify. For example, specifying the locale as “en-US” would then require the format to be MM/DD/YYYY.

Use format patterns from: Unicode Date Format Patterns.

If you supply a dateValue that that is not in the proper format, a RuntimeException is raised with a Parse Error.

Convert text values to a date:

Var SQLDateTime As String = "2019-08-01 11:00"
Var myDate1 As DateTime = DateTime.FromString(SQLDateTime)

Var SQLDate As String = "2019-08-01"
Var myDate2 As DateTime = DateTime.FromString(SQLDate)

Var dateValue As String = DateTime.Now.ToString(Locale.Current)
Var myDate3 As DateTime = DateTime.FromString(dateValue, Locale.Current, TimeZone.Current)

DateTime.Now

Now(timeZone As TimeZone = Nil) As DateTime

The current date and time (using the local timezone if timezone is Nil).

Get the current date and time:

Var d As DateTime = DateTime.Now

DateTime.SubtractInterval

SubtractInterval(years As Integer, months As Integer, days As Integer, minutes As Integer, seconds As Integer, nanoseconds As Integer) As DateTime

Subtracts the specified interval values to get a new DateTime.

You can also use the - operator to subtract DateIntervals from DateTime objects.

Get the date two months ago:

Var twoMonths As New DateInterval
twoMonths.Months = 2 // 2 month interval

// Get date that was two months ago
Var past As DateTime = DateTime.Now - twoMonths

// Get date two months after today
Var future As DateTime = DateTime.Now + twoMonths

// last month
Var lastMonth As DateTime = DateTime.Now.SubtractInterval(0, 1)

DateTime.ToString

ToString(loc As Locale = Nil, dateStyle As DateTime.FormatStyles = DateTime.FormatStyles.Medium, timeStyle As DateTime.FormatStyles = DateTime.FormatStyles.Medium) As String

Converts the DateTime (along with the time component) to a string format using the optional locale and formats.

If you don’t provide a locale or use a Nil locale, then the current locale (Locale.Current) is used.

To get date values without locale information, use SQLDate or SQLDateTime.

Use a Locale to get a date to use for display purposes. If you provide a Locale, then the specific output formats use what is defined in the locale settings for your OS. Refer to FormatStyles for more information.

Also refer to Introduction to app localization for information on how you can display localized values, particularly with web apps.

To get just the date portion you have to specify a Locale (not Raw). This example uses the current system locale to get just the date part for display:

Var d As DateTime = DateTime.Now
Var s As String = d.ToString(Locale.Current, DateTime.FormatStyles.Short, DateTime.FormatStyles.None)
// s = 10/31/17 (this varies by date and your system locale settings)

To display just the time portion you have to specify a Locale and then provide a FormatStyle for the time:

Var d As DateTime = DateTime.Now
Var s As String = d.ToString(Locale.Current, DateTime.FormatStyles.None, DateTime.FormatStyles.Short)
// s = 12:24 PM (this varies by time and your system locale settings)

Notes

Note

The oldest date DateTime can accept is 0001-01-01 00:00.

To create a DateTime object, you must set date/time you want. You can do this via Now or by passing date/time information to one of the constructors. If you’re going to change a date, use AddInterval, the + operator, SubtractInterval or the - operator as these will handle things like leap years, time zone differences and more.

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

If you pass invalid values (such as 32 for the day, 13 for the month) when creating a DateTime, an InvalidArgumentException 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:

Var v As Variant
Var d As DateTime
d = DateTime.Now
v = d

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

When using ToString with FormatStyles to get a formatted date or time, the actual format in which the date or time will appear is affected by the user’s operating system settings. The user’s system settings control the ultimate formats that are used.

You can use the ToString function to obtain the string value of the date in default system date/time format, i.e., the following gets the string value of the current date/time:

Var d As DateTime = DateTime.Now
MessageBox(d.ToString)

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.


Operators

  • You can use the + operator to add a DateTime and an Interval together to get a new DateTime.

  • You can use the - operator to subtract a DateInterval from a DateTime to get a new DateTime.

  • You can use the - operator to subtract a DateTime from a DateTime to get a new DateInterval.

Sample code

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

Var d As New DateTime(2012, 4, 15)

This code displays the current date in a message box.

Var d As DateTime = DateTime.Now
MessageBox(d.ToString(Locale.Current))

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

Var d As New DateTime(2012, 12, 5)
Var today As DateTime = DateTime.Now

If d < DateTime.Now Then
  MessageBox(d.ToString + " is earlier than now!")
End If

If d > today Then
  MessageBox(d.ToString + " is later than now!")
End If

If d.Year = today.Year And d.Month = today.Month _
  And d.Day = today.Day Then
  MessageBox("The dates match.")
End If

Compatibility

All projects types on all supported operating systems.

See also

Object parent class; System.Microseconds, System.Ticks functions; FolderItem, DateInterval, TimeZone classes