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.

The default time zone is the time zone of the device.

Properties

Name	Type	Read-Only
Day	Integer	✓
DayOfWeek	Integer	✓
DayOfYear	Integer	✓
Hour	Integer	✓
IsDaylightSavingsTime	Boolean	✓
Minute	Integer	✓
Month	Integer	✓
Nanosecond	Integer	✓
Second	Integer	✓
SecondsFrom1970	Double	✓
SQLDate	String	✓
SQLDateTime	String	✓
Timezone	TimeZone	✓
WeekOfYear	Integer	✓
Year	Integer	✓

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
	interval As DateInterval
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
	format As String, locale As Locale = Nil	String
	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 in the specified TimeZone. If no time zone was specified, the time zone is that of the device.

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.

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. The default is the time zone of the device. This is also referred to as the Current time zone.

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.

AddInterval(interval As DateInterval) As DateTime

Adds the specified interval 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.

This method is shared.

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 current timezone if timezone is Nil).

This method is shared.

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

ToString(format As String, locale As Locale = Nil) As String

ToString(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.

The format parameter is expected to be ICU Date/Time Format syntax. For example, MM-dd-yy for the date and hh:mm:ss for the time, or MM-dd-yy hh:mm:ss for both. You can use yyyy to display a four digit year. The format string is case-sensitive. MM must be used for date.

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 project types on all supported operating systems.

DateTime

Description

Properties

Methods

Enumerations

FormatStyles

Property descriptions

Method descriptions

Notes

Operators

Sample code

Compatibility

See also