DateTime
@Serializable { simple=true }
const class DateTime : Obj
DateTime represents an absolute instance in time. Fantom time is normalized as nanosecond ticks since 1 Jan 2000 UTC with a supported range of 1901 to 2099. Fantom time does not support leap seconds (same as Java and UNIX). An instance of DateTime also models the date and time of an absolute instance against a specific TimeZone.
Also see docLang.
Parse the string into a DateTime from the programmatic encoding defined by toStr
Make for the specified date and time values
Default value is "2000-01-01T00:00:00Z UTC"
Get the date component of this timestamp
Subtract a duration to compute a new time
Compare based on nanosecond ticks
Return the week number of the year as a number between 1 and 53 using the given weekday as the start of the week (defaults to current locale)
This method computes the day of month (1-31) for a given weekday
Return if this time is within daylight savings time for its associated time zone
Return the delta between this and the given time
Return the day of the year as a number between 1 and 365 (or 1 to 366 if a leap year)
Parse a string into a DateTime using the given pattern
Get the year as a number such as 2007
Get the time zone associated with this date time
Get the number of nanoseconds (the fraction of seconds) as a number between 0 and 999,999,999
Convenience for toTimeZone(TimeZone.rel)
Get the day of the week for this time
Convert this DateTime to the specific timezone
Get this date in Java milliseconds since the epoch of 1 Jan 1970
Return the number of hours for this date and this timezone
Get the whole seconds of the time as a number between 0 and 59
Get the minutes of the time as a number between 0 and 59
Get the hour of the time as a number between 0 and 23
Parse an HTTP date according to the RFC 2616 section 3.3.1
Return the current time using TimeZone.cur
Get the boot time of the Fantom VM with TimeZone.cur
Return a new DateTime with this time's nanosecond ticks truncated according to the specified accuracy
Return the current time as nanosecond ticks since 1 Jan 2000 UTC, but with the guarantee that every call returns a unique value for the lifetime of this VM
Format this instance according to ISO 8601 using the pattern
Get the day of the month as a number between 1 and 31
Get the time zone's abbreviation for this time
Format this time for use in an MIME or HTTP message according to RFC 2616 using the RFC 1123 format
Return programmatic string encoding formatted as follows
Return a DateTime for the beginning of the current day at midnight
Format this time according to the specified pattern
Return number of nanosecond ticks since 1 Jan 2000 UTC
Return the current time using TimeZone.utc
Get this DateTime as a Fantom expression suitable for code generation
Create date for Java milliseconds since the epoch of 1 Jan 1970 using the specified timezone (defaults to current)
Parse an ISO 8601 timestamp
Return if the specified year is a leap year
Add a duration to compute a new time
Return if the time portion is "00:00:00"
Make for nanosecond ticks since 1 Jan 2000 UTC
Get the month of this date
Return the current time as nanosecond ticks since 1 Jan 2000 UTC
Two times are equal if they have identical nanosecond ticks
Get the time component of this timestamp
Return nanosecond ticks for the hashcode
Convenience for toTimeZone(TimeZone.utc)
static DateTime boot()
Get the boot time of the Fantom VM with TimeZone.cur
virtual Int compare(Obj obj)
Compare based on nanosecond ticks.
Date date()
Get the date component of this timestamp.
Int day()
Get the day of the month as a number between 1 and 31.
Int dayOfYear()
Return the day of the year as a number between 1 and 365 (or 1 to 366 if a leap year).
const static DateTime : defVal
Default value is "2000-01-01T00:00:00Z UTC".
Bool dst()
Return if this time is within daylight savings time for its associated time zone.
virtual Bool equals(Obj? that)
Two times are equal if they have identical nanosecond ticks.
DateTime floor(Duration accuracy)
Return a new DateTime with this time's nanosecond ticks truncated according to the specified accuracy. For example floor(1min) will truncate this time to the minute such that seconds are 0.0. This method is strictly based on absolute ticks, it does not take into account wall-time rollovers.
static DateTime? fromHttpStr(Str s, Bool checked)
Parse an HTTP date according to the RFC 2616 section 3.3.1. If invalid format and checked is false return null, otherwise throw ParseErr. The following date formats are supported:
Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123 Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format
static DateTime? fromIso(Str s, Bool checked)
Parse an ISO 8601 timestamp. If invalid format and checked is false return null, otherwise throw ParseErr. The following formats are supported:
YYYY-MM-DD'T'hh:mm:ss[.FFFFFFFFF] YYYY-MM-DD'T'hh:mm:ss[.FFFFFFFFF]+HH:MM YYYY-MM-DD'T'hh:mm:ss[.FFFFFFFFF]-HH:MM
If a timezone offset is specified, then one of the predefined "Etc/GMT+x" timezones are used for the result:
DateTime("2009-01-15T12:00:00Z") => 2009-01-15T12:00:00Z UTC
DateTime("2009-01-15T12:00:00-05:00") => 2009-01-15T12:00:00-05:00 GMT+5
Also see toIso, fromStr, and fromHttpStr.
static DateTime? fromJava(Int millis, TimeZone tz, Bool negIsNull)
Create date for Java milliseconds since the epoch of 1 Jan 1970 using the specified timezone (defaults to current). If millis are less than or equal to zero then return null or a date before 1970 depending on the negIsNull flag.
static DateTime? fromLocale(Str str, Str pattern, TimeZone tz, Bool checked)
Parse a string into a DateTime using the given pattern. If string is not a valid format then return null or raise ParseErr based on checked flag. See toLocale for pattern syntax.
The timezone is inferred from the zone pattern, or else the given tz parameter is used for the timezone. The z pattern will match "hh:mm", "hhmm", or "hh". If only a zone offset is available and it doesn't match the expected tz parameter, then use a "GMT+/-" timezone. Note that if offset is a fractional hour such as GMT-3:30, then result will have ticks, but its tz will be floored hour based GMT timezone such as GMT-3.
static new fromStr(Str s, Bool checked)
Parse the string into a DateTime from the programmatic encoding defined by toStr. If the string cannot be parsed into a valid DateTime and checked is false then return null, otherwise throw ParseErr. Also see fromIso and fromHttpStr.
virtual Int hash()
Return nanosecond ticks for the hashcode.
Int hour()
Get the hour of the time as a number between 0 and 23.
Int hoursInDay()
Return the number of hours for this date and this timezone. Days which transition to DST will be 23 hours and days which transition back to standard time will be 25 hours. Note there is one timezone "Lord_Howe" which has a 30min offset which is not handled by this method (WTF).
static Bool isLeapYear(Int year)
Return if the specified year is a leap year.
Bool isMidnight()
Return if the time portion is "00:00:00".
static new make(Int year, Month month, Int day, Int hour, Int min, Int sec, Int ns, TimeZone tz)
Make for the specified date and time values:
- year: 1901-2099
- month: Month enumeration
- day: 1-31
- hour: 0-23
- min: 0-59
- sec: 0-59
- ns: 0-999_999_999
- tz: time zone used to map date/time to ns ticks
Throw ArgErr if any of the parameters are out of range.
static DateTime makeTicks(Int ticks, TimeZone tz)
Make for nanosecond ticks since 1 Jan 2000 UTC. Throw ArgErr if ticks represent a year out of the range 1901 to 2099.
DateTime midnight()
Return a DateTime for the beginning of the current day at midnight.
Int min()
Get the minutes of the time as a number between 0 and 59.
@Operator
DateTime minus(Duration duration)
Subtract a duration to compute a new time. This method works off absolute time, so subtracting 1days means to subtract 24 hours from the ticks. This might be a different time of day if on a DST boundry. Use Date.minus for daily increments.
Example:
prevHour := DateTime.now - 1hr
@Operator
Duration minusDateTime(DateTime time)
Return the delta between this and the given time.
Example:
elapsed := DateTime.now - startTime
Month month()
Get the month of this date.
Int nanoSec()
Get the number of nanoseconds (the fraction of seconds) as a number between 0 and 999,999,999.
static DateTime now(Duration? tolerance)
Return the current time using TimeZone.cur. The tolerance parameter specifies that you are willing to use a cached DateTime instance as long as (now - cached <= tolerance). If tolerance is null, then this method always creates a new DateTime instance. Using tolerance can increase performance and save memory. The tolerance default is 250ms.
If you are using time to calculate relative time periods, then use Duration.now instead. Duration is more efficient and won't cause you grief when the system clock is modified.
static Int nowTicks()
Return the current time as nanosecond ticks since 1 Jan 2000 UTC.
static Int nowUnique()
Return the current time as nanosecond ticks since 1 Jan 2000 UTC, but with the guarantee that every call returns a unique value for the lifetime of this VM. Since most platforms don't actually support nanosecond resolution, the unused nanoseconds are used as a counter to ensure uniqueness. However, bursts of calls may result in a drift from the actual system time. For example, if the platform's clock supports millisecond resolution, then calling this method more than one million times within a millisecond will introduce a millisecond drift (1,000,000ns in a ms).
static DateTime nowUtc(Duration? tolerance)
Return the current time using TimeZone.utc. See now for a description of the tolerance parameter.
@Operator
DateTime plus(Duration duration)
Add a duration to compute a new time. This method works off absolute time, so adding 1days means to add 24 hours to the ticks. This might be a different time of day if on a DST boundry. Use Date.plus for daily increments.
Example:
nextHour := DateTime.now + 1hr
Int sec()
Get the whole seconds of the time as a number between 0 and 59.
Int ticks()
Return number of nanosecond ticks since 1 Jan 2000 UTC. Dates before this epoch will return a negative integer.
Time time()
Get the time component of this timestamp.
Str toCode()
Get this DateTime as a Fantom expression suitable for code generation.
Str toHttpStr()
Format this time for use in an MIME or HTTP message according to RFC 2616 using the RFC 1123 format:
Sun, 06 Nov 1994 08:49:37 GMT
Str toIso()
Format this instance according to ISO 8601 using the pattern:
YYYY-MM-DD'T'hh:mm:ss.FFFz
Int toJava()
Get this date in Java milliseconds since the epoch of 1 Jan 1970.
Str toLocale(Str? pattern, Locale locale)
Format this time according to the specified pattern. If pattern is null, then a localized default is used. Any ASCII letter in the pattern is interpreted as follows:
YY Two digit year 07 YYYY Four digit year 2007 M One/two digit month 6, 11 MM Two digit month 06, 11 MMM Three letter abbr month Jun, Nov MMMM Full month June, November D One/two digit day 5, 28 DD Two digit day 05, 28 DDD Day with suffix 1st, 2nd, 3rd, 24th WWW Three letter abbr weekday Tue WWWW Full weekday Tuesday Q Quarter number 3 QQQ Quarter with suffix 3rd QQQQ Quarter spelled out 3rd Quarter V One/two digit week of year 1,52 VV Two digit week of year 01,52 VVV Week of year with suffix 1st,52nd h One digit 24 hour (0-23) 3, 22 hh Two digit 24 hour (0-23) 03, 22 k One digit 12 hour (1-12) 3, 11 kk Two digit 12 hour (1-12) 03, 11 m One digit minutes (0-59) 4, 45 mm Two digit minutes (0-59) 04, 45 s One digit seconds (0-59) 4, 45 ss Two digit seconds (0-59) 04, 45 SS Optional seconds (only if non-zero) f* Fractional secs trailing zeros F* Fractional secs no trailing zeros a Lower case a/p for am/pm a, p aa Lower case am/pm am, pm A Upper case A/P for am/pm A, P AA Upper case AM/PM AM, PM z Time zone offset Z, +03:00 (ISO 8601, XML Schema) zzz Time zone abbr EST, EDT zzzz Time zone name New_York 'xyz' Literal characters '' Single quote literal
A symbol immediately preceding a "F" pattern with no fraction to print is skipped.
Examples:
YYYY-MM-DD'T'hh:mm:ss.FFFz => 2009-01-16T09:57:35.097-05:00 DD MMM YYYY => 06 Jan 2009 DD/MMM/YY => 06/Jan/09 MMMM D, YYYY => January 16, 2009 hh:mm:ss.fff zzzz => 09:58:54.845 New_York k:mma => 9:58a k:mmAA => 9:58AM
DateTime toRel()
Convenience for toTimeZone(TimeZone.rel). See docLang.
virtual Str toStr()
Return programmatic string encoding formatted as follows:
"YYYY-MM-DD'T'hh:mm:ss.FFFFFFFFFz zzzz"
See toLocale for the pattern legend. The base of the string encoding conforms to ISO 8601 and XML Schema Part 2. The Fantom format also appends the timezone name to avoid the ambiguities associated with interpreting the time zone offset. Also see toIso and toHttpStr.
Examples:
"2000-04-03T00:00:00.123Z UTC" "2006-10-31T01:02:03-05:00 New_York" "2009-03-10T11:33:20Z London" "2009-03-01T12:00:00+01:00 Amsterdam"
DateTime toTimeZone(TimeZone tz)
Convert this DateTime to the specific timezone. The absolute point time as ticks remains the same, but the date and time fields will be converted to represent the new time zone. However if converting to or from TimeZone.rel then the resulting DateTime has the same day and time. Also see toUtc and toRel.
Example:
dt := DateTime("2010-06-03T10:30:00-04:00 New_York")
dt.toUtc => 2010-06-03T14:30:00Z UTC
dt.toRel => 2010-06-03T10:30:00Z Rel
DateTime toUtc()
Convenience for toTimeZone(TimeZone.utc).
TimeZone tz()
Get the time zone associated with this date time.
Str tzAbbr()
Get the time zone's abbreviation for this time. See TimeZone.stdAbbr and TimeZone.dstAbbr.
Int weekOfYear(Weekday startOfWeek)
Return the week number of the year as a number between 1 and 53 using the given weekday as the start of the week (defaults to current locale).
Weekday weekday()
Get the day of the week for this time.
static Int weekdayInMonth(Int year, Month mon, Weekday weekday, Int pos)
This method computes the day of month (1-31) for a given weekday. The pos parameter specifies the first, second, third, or fourth occurence of the weekday. A negative pos is used to compute the last (or second to last, etc) weekday in the month.
Examples:
// compute the second monday in Apr 2007 weekdayInMonth(2007, Month.apr, Weekday.mon, 2) // compute the last sunday in Oct 2007 weekdayInMonth(2007, Month.oct, Weekday.sun, -1)
Int year()
Get the year as a number such as 2007.