Class
Xojo.Core.Date
Warning
This item was deprecated in version 2020r2. Please use DateTime as a replacement.
Description
Used to store date/time values. Once a date is created, it cannot be modified, but you can create new dates by applying a DateInterval to an existing date.
Properties
Name |
Type |
Read-Only |
Shared |
|---|---|---|---|
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
Methods
Name |
Parameters |
Returns |
Shared |
|---|---|---|---|
year As Integer, month As Integer, day As Integer, hour As Integer = 0, minute As Integer = 0, seconds As Integer = 0, nanoseconds As Integer = 0, timezone As TimeZone |
|||
loc As Locale = Nil, dateStyle As Xojo.Core.Date = , timeStyle As Xojo.Core.Date = |
Enumerations
Xojo.Core.Date.FormatStyles
FormatStyles
These are the various styles that can be used to convert a Date to Text with the ToText method.
Enum |
Description |
|---|---|
Short |
The short date or time format: |
Medium |
The medium date or time format: |
Long |
The long date or time format: |
Full |
The full date or time format: |
None |
Prevents the date or time value from displaying. |
Property descriptions
Xojo.Core.Date.Day
Day As Integer
The day of the month as a number. The first day is 1. The last day varies by the month.
This property is read-only.
Get the day:
Var d As Date = Xojo.Core.Date.Now
Var day As Integer = d.Day
Xojo.Core.Date.DayOfWeek
DayOfWeek As Integer
The day of the week, with 1 = Sunday, 2 = Monday, 3 = Tuesday, 4 = Wednesday, 5 = Thursday, 6 = Friday, 7 = Saturday.
This property is read-only.
Ge the day of the week:
Var day As Integer = Xojo.Core.Date.Now.DayOfWeek
Xojo.Core.Date.DayOfYear
DayOfYear As Integer
The number of days into the year, 1-based. January 1st is 1.
This property is read-only.
Get the day of the year:
Var yearDay As Integer = Xojo.Core.Date.Now.DayOfYear
To check to see if a year is a leap year, you can create a date on the last day of the year (Dec 31) and then check DayOfYear to see if it is greater than 365. For example:
Var year As Integer = 2020
Var d1 As New Xojo.Core.Date(year, 12, 31, Xojo.Core.TimeZone.Current)
If d1.DayOfYear > 365 Then
' Leap Year!
Else
' Not a leap year
End If
Xojo.Core.Date.Hour
Hour As Integer
The hour number for the time portion of the date, using a 24-hour clock. For example, 20 is the value for 8 pm.
This property is read-only.
Get the current hour:
Var d As Xojo.Core.Date = Xojo.Core.Date.Now
Var hour As Integer = d.Hour
Xojo.Core.Date.Minute
Minute As Integer
The minute number of the time portion of the date.
This property is read-only.
Get the current minute:
Var d As Date = Xojo.Core.Date.Now
Var minute As Integer = d.Minute
Xojo.Core.Date.Month
Month As Integer
The month number of the date. January is month 1, December is month 12.
This property is read-only.
Get the current month:
Var d As Xojo.Core.Date = Xojo.Core.Date.Now
Var month As Integer = d.Month
Xojo.Core.Date.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 Xojo.Core.Date = Xojo.Core.Date.Now
Var nanosecond As Integer = d.Nanosecond
Xojo.Core.Date.Second
Second As Integer
The second number of the time portion of the date.
This property is read-only.
Get the current second:
Var d As Xojo.Core.Date = Xojo.Core.Date.Now
Var second As Integer = d.Second
Xojo.Core.Date.SecondsFrom1970
SecondsFrom1970 As Double
The number of seconds since the first instant of 1 January 1970, 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 the first instant of 1 January 1970, GMT.
Get the seconds since 1970 and use it to create a new date:
Var d1 As Date = Xojo.Core.Date.Now
Var seconds As Double = d1.SecondsFrom1970
Var d2 As New Date(seconds, Xojo.Core.TimeZone.Current)
' Both d1 and d2 have the same date value
Calculate the number of days between two dates:
Var d1 As New Xojo.Core.Date(2018, 8, 1, Xojo.Core.TimeZone.Current)
Var d2 As New Xojo.Core.Date(2015, 3, 1, Xojo.Core.TimeZone.Current)
' Subtract seconds and convert seconds to days
Var days As Double = (d1.SecondsFrom1970 - d2.SecondsFrom1970) / (24 * 60 * 60)
Xojo.Core.Date.TimeZone
TimeZone As TimeZone
The time zone.
This property is read-only.
Get the time zone:
Var d As Date = Xojo.Core.Date.Now
Var tz As Xojo.Core.TimeZone
tz = d.TimeZone
To change a date to a new time zone, for example GMT:
' myDate is an existing date
Var GMTZone As New Xojo.Core.TimeZone("GMT")
Var GMTDate As New Xojo.Core.Date(myDate.SecondsFrom1970, GMTZone)
Xojo.Core.Date.Year
Year As Integer
The year portion of the date.
This property is read-only.
Get the year:
Var d As Xojo.Core.Date = Xojo.Core.Date.Now
Var year As Integer = d.Year
Method descriptions
Xojo.Core.Date.Add
Add
You use the "+" operator to add a Date and a Xojo.Core.DateInterval to get a new Date.
Get the date two months from today:
Var twoMonths As New Xojo.Core.DateInterval
twoMonths.Months = 2 ' 2 month interval
' Get date two months from today
Var future As Xojo.Core.Date = Xojo.Core.Date.Now + twoMonths
Xojo.Core.Date.Constructor
Constructor(secondsFrom1970 As Double, timezone As TimeZone)
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 from the first instant of 1 January 1970, GMT. Use a negative value to specify a date before this date.
Xojo.Core.Date.Constructor
Constructor(year As Integer, month As Integer, day As Integer, hour As Integer = 0, minute As Integer = 0, seconds As Integer = 0, nanoseconds As Integer = 0, timezone As TimeZone)
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 using the supplied values. Use this method to create a specific date.
Create a new date for Aug 1, 2015:
Var d As New Xojo.Core.Date(2015, 8, 1, Xojo.Core.TimeZone.Current) ' Aug 1, 2015
Create a new date for Sep 1, 2015 at 3:20pm (and 30 seconds):
Var d As New Xojo.Core.Date(2015, 9, 1, 15, 20, 30, 0, Xojo.Core.TimeZone.Current)
Convert a Classic Date to Xojo.Core.Date:
Var d As New Date(2015, 10, 15)
Var xcd As New Xojo.Core.Date(d.Year, d.Month, d.Day, Xojo.Core.TimeZone.Current)
Xojo.Core.Date.FromText
FromText(input As String, loc As Locale = Nil) As DateTime
Converts a textual date to an actual date using the optional locale.
The resulting date is in the current time zone (Xojo.Core.TimeZone.Current).
When no locale is specified, the input text can be in either SQLDate (YYYY-MM-DD) or SQLDateTime (YYYY-MM-DD HH:MM:SS) formats.
If you specify a locale, the input text must be formatted to match the locale you specify.
Use format patterns from: Unicode Date Format Patterns.
If you supply input text that cannot be formatted, then a RuntimeException is raised with a Parse Error.
Convert text values to a date:
Var SQLDateTime As Text = "2015-08-01 11:00"
Var myDate1 As Xojo.Core.Date = Xojo.Core.Date.FromText(SQLDateTime)
Var SQLDate As Text = "2018-06-01"
Var myDate2 As Xojo.Core.Date = Xojo.Core.Date.FromText(SQLDate)
Var dateValue As Text = Xojo.Core.Date.Now.ToText(Xojo.Core.Locale.Current)
Var myDate3 As Xojo.Core.Date = Xojo.Core.Date.FromText(dateValue, Xojo.Core.Locale.Current)
Xojo.Core.Date.Now
Now As DateTime
The current date and time (local timezone).
Get the current date and time:
Var d As Xojo.Core.Date = Xojo.Core.Date.Now
Xojo.Core.Date.Subtract
Subtract
You can subtract a Date from a Date and get a DateInterval.
Get the date two months before today:
Var twoMonths As New Xojo.Core.DateInterval
twoMonths.Months = 2 ' 2 month interval
' Get date two months before today
Var past As Xojo.Core.Date = Xojo.Core.Date.Now - twoMonths
Calculate the interval until January 1, 2030:
Var d2 As New Xojo.Core.Date(2030, 1, 1, Xojo.Core.TimeZone.Current)
Var interval As Xojo.Core.DateInterval
interval = d2 - Xojo.Core.Date.Now
Xojo.Core.Date.ToText
ToText(loc As Locale = Nil, dateStyle As Xojo.Core.Date = Xojo.Core.Date.FormatStyles.Medium, timeStyle As Xojo.Core.Date = Xojo.Core.Date.FormatStyles.Medium) As String
Converts the Date (along with the time component) to a text format using the optional locale and formats.
The default non-locale savvy version (loc is Nil) of ToText returns a date in the SQLDateTime format YYYY-MM-DD HH:MM:SS. When using a loc of Nil, the dateStyle and timeStyle must be FormatStyles.Medium, but since those are the defaults they can be omitted. Because of this there is no need to specifically pass in a loc of Xojo.Locale.Raw.
Example date output with no parameters would be: 2017-10-31 09:38:24
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 the Localization topic for information on how you can display localized values, particularly with web apps.
Display the current date and time in SQLDateTime format (YYYY-MM-DD HH:MM:SS):
Var d As Xojo.Core.Date = Xojo.Core.Date.Now
Var SQLDateTime As Text = d.ToText ' 2017-10-31 09:38:24
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:
Using Xojo.Core
Var d As Date = Date.Now
Var t As Text = d.ToText(Locale.Current, Date.FormatStyles.Short, Date.FormatStyles.None)
' t = 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:
Using Xojo.Core
Var d As Date = Date.Now
Var t As Text = d.ToText(Locale.Current, Date.FormatStyles.None, Date.FormatStyles.Short)
' t = 12:24 PM (this varies by time and your system locale settings)
Notes
Xojo.Core.Date uses ICU (International Components for Unicode) for its date handling, supporting dates starting from 0001-Jan-01 and switching between Julian and Gregorian calendars on 1582-Oct-04.
You cannot use Var d As New Date to get the current date. Instead, use Var d As Date = Date.Now or more simply, just Date.Now.
To compare dates, use the SecondsFrom1970 property:
If myDate.SecondsFrom1970 > yourDate.SecondsFrom1970 Then
' myDate is greater than yourDate
End If
Compatibility
All project types on all supported operating systems.