Dateclass | date.h[134], misc.t[2163] |
Superclass Tree | Subclass Tree | Global Objects | Property Summary | Method Summary | Property Details | Method Details |
The date/time value is stored internally in terms of universal time (UTC). This makes it independent of locations and time zones. When a new Date object is created for a given calendar day or clock time, that source value is assumed to be in terms of the local wall clock time of the machine it's running on, but a different time zone can be explicitly specified instead; the Date object automatically translates that local time value to UTC for storage. Likewise, when a Date is formatted to a string representation, or when calendar or clock components are extracted from it, the formatted or extracted value is translated by default to the local time zone, but a different time zone can be specified.
You can create a Date object from a number of other representations for date values:
new Date() - creates a Date representing the current date and time.
new Date('string', refTZ?, refDate?) - parses the string as a date
value. 'refTZ' is an optional TimeZone object; if provided,
the date string will be interpreted as a local time in that
zone, unless the string contains a timezone specifier. The
default timezone if 'refTZ' is missing is the local system's
time zone. 'refDate' is an optional Date object that's used
to fill in certain missing date elements in the string. If
the string doesn't specify the year (e.g., 'March 1'), the
year is taken from refDate; if the string only specifies only
a time, the date is taken from refDate. If the date uses a
two-digit year number ('5/15/92'), the century is inferred
from the reference date by finding the year closest to the
reference year (for example, if it's currently 2012, '92' is
interpreted as 1992, since that's closer to 2012 than is
2092). The date parser accepts numerous common human-readable
formats and several standard computer formats. For a full
list of, see the System Manual. The parser uses the locale
settings from setLocaleInfo() to match month names, weekday
names, etc; the default settings are for US English format.
new Date(number, 'J') - 'number' can be an integer or a BigNumber.
This creates a Date object representing the given number of
days after January 1, 4713 BCE on the Julian calendar, at
noon UTC. The fractional part is the fraction of a day
past noon; for example, a fractional portion of 0.25
represents 1/4 of a day, or 6 hours, so it represents a
clock time of 18:00 UTC (6 hours past noon).
new Date(number, 'U') - 'number' can be an integer or a BigNumber.
This creates a Date object representing the given number of
seconds after standard Unix Epoch (1/1/1970 00:00:00 UTC),
or before the Epoch if the value is negative. If 'number'
is a BigNumber, it can specify fractions of a second, which
the Date object will round to the nearest milliseconds.
This constructor format is provided because "seconds since
1/1/1970" is the standard representation of time on Unix-like
systems, and as a result it's also common in file formats.
new Date(year, month, day, tz?) - midnight on year/month/day (all
given as integers), in the given local time zone 'tz' (given
as a TimeZone object or a string giving a time zone name).
The default time zone if 'tz' is omitted is the system's
local time zone. The year must be given as the full year
with century, e.g., 2012, not just 12; the latter is valid
but is taken literally as the first-century year 12. The
month is 1-12 for January to December. The day is simply
the calendar day of the month (e.g., 5 for January 5). The
year can zero or negative. Note that because year 0 is a
valid year in Date's calendar system, negative years are off
by one from the "BC" convention: in the AD/BC convention,
the year before AD 1 is 1 BC, not AD 0; so on our calendar,
year 0 corresponds to 1 BC, -1 is 2 BC, etc.
new Date(year, month, day, hour, minute, seconds, ms, tz?) - the
given date and time value, with each element as an integer.
The value is in terms of the given local time zone 'tz',
or the system's local time zone if 'tz' is omitted. 'ms'
is the number of milliseconds (0-999).
Date arithmetic: the following operators perform calendar calculations on the date value:
Date + integer - add days to the date
Date - integer - subtract days from date
Date + BigNumber - add days (which can include fractional days)
Date - BigNumber - subtract days (which can include fractional days)
Date - Date - number of days between dates (with fractional days)
Adding an integer or BigNumber returns a new Date object representing the result; Date objects are immutable, so the original Date value isn't changed by the operation.
Subtracting one Date from another yields a BigNumber with the difference in days between the two dates. Note that this might have a fractional part, because the difference might not be whole days; for example, subtracting 13:00 from 19:00 on the same day yields 0.25, which is 1/4 of a 24-hour day, or 6 hours.. Like all Date arithmetic, subtraction works in universal time, so the subtraction yields the true time difference between the events even if they were created from times in different time zones. For example, subtracting 1 PM Eastern Time from 1 PM Pacific Time on the same day yields 0.125 (1/8 of a day, or 3 hours).
The comparison operators (< > <= >=) compare two Date values by order of occurrence in time. For example, a > b is true if a is later than b. The comparison is done in universal time, so the comparison yields the actual event order, not the nominal local time order. For example, 2 PM Eastern Time is earlier than 1 PM Pacific Time on any given day.
Time zone specifications: when a time zone is specified in a constructor or method argument, you can supply a TimeZone object, or a string with the name of a time zone, using the same formats that the TimeZone constructor accepts. See the TimeZone object for more information. The default if you don't specify a time zone is
Modified in misc.t[2163]:
Add a method to Date as a workaround for a library bug
intrinsic class
Date : Object
Date
Object
addInterval
compareTo
findWeekday
formatDate
formatJulianDate
getClockTime
getDate
getHMS
getISOWeekDate
getJulianDate
getJulianDay
Inherited from Object
:
callInherited
createIterator
createLiveIterator
forEach
getPropList
getPropParams
getSuperclassList
isClass
isTransient
mapAll
ofKind
propDefined
propInherited
propType
valToSymbol
addInterval (interval) | date.h[280] |
compareTo (date) | date.h[204] |
findWeekday (weekday, which, tz?) | date.h[292] |
formatDate (format, tz?) | date.h[188] |
formatJulianDate (format, tz?) | date.h[194] |
getClockTime (tz?) | date.h[269] |
getDate (tz?) | date.h[214] |
getHMS ( ) | misc.t[2169] |
getISOWeekDate (tz?) | date.h[259] |
getJulianDate (tz?) | date.h[243] |
getJulianDay ( ) | date.h[233] |
The return value is a BigNumber value giving the Julian day corresponding to this Date value, including a fractional part for the time past noon UTC on that date.
Note that there's no local time zone involved in this calculation, since the Julian day number is specifically defined in terms of universal time.