java.util.Date
Date
provides a system-independent abstraction of dates and times, to a
millisecond precision. Dates may be constructed from a year, month, date (day of
month), hour, minute, and second; those six components and the day of the week,
may be extracted; and dates may be compared and converted to a readable string.
public classExamples:Date
{ publicDate
(); publicDate
(long time); publicDate
(int year, int month, int date); publicDate
(int year, int month, int date, int hours, int minutes); publicDate
(int year, int month, int date, int hours, int minutes, int seconds); publicDate
(String s) throws IllegalArgumentException; public StringtoString
(); public booleanequals
(Object obj); public inthashCode
(); public intgetYear
(); public voidsetYear
(int year); public intgetMonth
(); public voidsetMonth
(int month); public intgetDate
(); public voidsetDate
(int date); public intgetDay
(); public intgetHours
(); public voidsetHours
(int hours); public intgetMinutes
(); public voidsetMinutes
(int minutes); public intgetSeconds
(); public voidsetSeconds
(int seconds); public longgetTime
(); public voidsetTime
(long time); public booleanbefore
(Date when); public booleanafter
(Date when); public StringtoLocaleString
(); public StringtoGMTString
(); public intgetTimezoneOffset
(); public static longUTC
(int year, int month, int date, int hours, int minutes, int seconds); public static longparse
(String s) throws IllegalArgumentException; }
Date
class is intended to reflect UTC (Coordinated Universal Time), it may not do so exactly, depending on the host environment of the Java system. Nearly all modern operating systems assume that 1 day = = 86400 seconds in all cases. In UTC, however, about once every year or two there is an extra second, called a "leap second." The leap second is always added as the last second of the day, and nearly always on December 31 or June 30. For example, the last minute of the year 1995 was 61 seconds long, thanks to an added leap second.Most computer clocks are currently not accurate enough to be able to reflect the leap-second distinction. Some computer standards are defined in terms of GMT (Greenwich Mean Time), which is equivalent to UT (Universal Time). GMT is the "civil" name for the standard; UT is the "scientific" name for the same standard. The distinction between UTC and UT is that UTC is based on an atomic clock and UT is based on astronomical observations, which for all practical purposes is an invisibly fine hair to split. Because the earth's rotation is not uniform-it slows down and speeds up in complicated ways-UT does not always flow uniformly. Leap seconds are introduced as needed into UTC so as to keep UTC within 0.9 seconds of UT1, which is a version of UT with certain corrections applied. There are other time and date systems as well; for example, the time scale used by GPS (the satellite-based Global Positioning System) is synchronized to UTC but is not adjusted for leap seconds. An interesting source of further information is the U. S. Naval Observatory, particularly the Directorate of Time at:
http://tycho.usno.navy.miland their definitions of "Systems of Time" at:
http://tycho.usno.navy.mil/systime.htmlIn all methods of class
Date
that accept or return year, month, day of month, hours, minutes, and seconds values, the following representations are used:
21.3.1 public
Date
()
This constructor initializes a newly created Date
object so that it represents the
instant of time that it was created, measured to the nearest millisecond.
21.3.2 public
Date
(long time)
This constructor initializes a newly created Date
object so that it represents the
instant of time that is time
milliseconds after the standard base time known as
"the epoch," namely 00:00:00 GMT on January 1, 1970. See also the method
currentTimeMillis
(§20.18.6) of class System
.
21.3.3 public
Date
(int year, int month, int date)
This constructor initializes a newly created Date
object so that it represents midnight
at the beginning of the day specified by the year
, month
, and date
arguments,
in the local time zone. Thus, it has the same effect as the constructor call
(§21.3.5):
Date(year, month, date, 0, 0, 0)
21.3.4 public
Date
(int year, int month, int date,
int hours, int minutes)
This constructor initializes a newly created Date
object so that it represents the
instant at the start of the minute specified by the year
, month
, date
, hours
, and
minutes
arguments, in the local time zone. Thus, it has the same effect as the constructor
call (§21.3.5):
Date(year, month, date, hours, minutes, 0)
21.3.5 public
Date
(int year, int month, int date,
int hours, int minutes, int seconds)
This constructor initializes a newly created Date
object so that it represents the
instant at the start of the second specified by the year
, month
, date
, hours
,
minutes
, and seconds
arguments, in the local time zone.
21.3.6 public
Date
(String s)
throws IllegalArgumentException
This constructor initializes a newly created Date
object so that it represents the
date and time indicated by the string s, which is interpreted as if by the parse
method (§21.3.31).
21.3.7 public String
toString
()
This Date
object is converted to a String
of the form:
"dow mon dd hh:mm:ss zzz yyyy"where:
dow
is the day of the week (Sun
, Mon
, Tue
, Wed
, Thu
, Fri
, Sat
).
mon
is the month (Jan
, Feb
, Mar
, Apr
, May
, Jun
, Jul
, Aug
, Sep
, Oct
, Nov
, Dec
).
dd
is the day of the month (01
through 31
), as two decimal digits.
hh
is the hour of the day (00
through 23
), as two decimal digits.
mm
is the minute within the hour (00
through 59
), as two decimal digits.
ss
is the second within the minute (00
through 61
), as two decimal digits.
zzz
is the time zone (and may reflect daylight saving time). Standard time zone abbreviations include those recognized by the method parse
(§21.3.31). If time zone information is not available, then zzz
is empty-that is, it consists of no characters at all.
yyyy
is the year, as four decimal digits.
toLocaleString
(§21.3.27) and toGMTString
(§21.3.28).
Overrides the toString
method of Object
(§20.1.2).
21.3.8 public boolean
equals
(Object obj)
The result is true
if and only if the argument is not null
and is a Date
object that
represents the same point in time, to the millisecond, as this Date
object. Thus
two Date
objects are equal if and only if the getTime
method (§21.3.23) returns
the same long
value from both.
Overrides the equals
method of Object
(§20.1.3).
21.3.9 public int
hashCode
()
The result is the exclusive OR of the two halves of the primitive long
value
returned by the getTime
method (§21.3.23). That is, the hash code is the value of
the expression:
(int)(this.getTime()^(this.getTime()>>>32))Overrides the
hashCode
method of Object
(§20.1.4).21.3.10 public int
getYear
()
The returned value is the result of subtracting 1900 from the year that contains or
begins with the instant in time represented by this Date
object, as interpreted in
the local time zone.
21.3.11 public void
setYear
(int year)
This Date
object is modified so that it represents a point in time within the specified
year, with the month, date, hour, minute, and second the same as before, as
interpreted in the local time zone. (Of course, if the date was February 29, for
example, and the year is set to a non-leap year, then the new date will be treated
as if it were on March 1.)
21.3.12 public int
getMonth
()
The returned value is a number (0
through 11
) representing the month that contains
or begins with the instant in time represented by this Date
object, as interpreted
in the local time zone.
21.3.13 public void
setMonth
(int month)
This Date
object is modified so that it represents a point in time within the specified
month, with the year, date, hour, minute, and second the same as before, as
interpreted in the local time zone. If the date was October 31, for example, and the
month is set to June, then the new date will be treated as if it were on July 1,
because June has only 30 days.
21.3.14 public int
getDate
()
The returned value is a number (1
through 31
) representing day of the month that
contains or begins with the instant in time represented by this Date
object, as
interpreted in the local time zone.
21.3.15 public void
setDate
(int date)
This Date
object is modified so that it represents a point in time within the specified
day of the month, with the year, month, hour, minute, and second the same as
before, as interpreted in the local time zone.If the date was April 30, for example,
and the date is set to 31, then it will be treated as if it were on May 1, because
April has only 30 days.
21.3.16 public int
getDay
()
The returned value (0
= Sunday, 1
= Monday, 2
= Tuesday, 3
= Wednesday, 4
=
Thursday, 5
= Friday, 6
= Saturday) represents the day of the week that contains or
begins with the instant in time represented by this Date
object, as interpreted in
the local time zone.
21.3.17 public int
getHours
()
The returned value is a number (0
through 23
) representing the hour within the
day that contains or begins with the instant in time represented by this Date
object, as interpreted in the local time zone.
21.3.18 public void
setHours
(int hours)
This Date
object is modified so that it represents a point in time within the specified
hour of the day, with the year, month, date, minute, and second the same as
before, as interpreted in the local time zone.
21.3.19 public int
getMinutes
()
The returned value is a number (0
through 59
) representing the minute within the
hour that contains or begins with the instant in time represented by this Date
object, as interpreted in the local time zone.
21.3.20 public void
setMinutes
(int minutes)
This Date
object is modified so that it represents a point in time within the specified
minute of the hour, with the year, month, date, hour, and second the same as
before, as interpreted in the local time zone.
21.3.21 public int
getSeconds
()
The returned value is a number (0
through 61
) representing the second within the
minute that contains or begins with the instant in time represented by this Date
object, as interpreted in the local time zone.
21.3.22 public void
setSeconds
(int seconds)
This Date
object is modified so that it represents a point in time within the specified
second of the minute, with the year, month, date, hour, and minute the same
as before, as interpreted in the local time zone.
21.3.23 public long
getTime
()
This method returns the time represented by this Date
object, represented as the
distance, measured in milliseconds, of that time from the epoch (00:00:00 GMT
on January 1, 1970).
21.3.24 public void
setTime
(long time)
This Date
object is modified so that it represents a point in time that is time
milliseconds
after the epoch (00:00:00 GMT on January 1, 1970).
21.3.25 public boolean
before
(Date when)
The result is true
if and only if the instant represented by this Date
object is
strictly earlier than the instant represented by when
.
21.3.26 public boolean
after
(Date when)
The result is true
if and only if the instant represented by this Date
object is
strictly later than the instant represented by when
.
21.3.27 public String
toLocaleString
()
This Date
object is converted to a String
of an implementation-dependent form.
The general intent is that the form should be familiar to the user of the Java application,
wherever it may happen to be running. The intent is comparable to that of
the %c
format supported by the strftime
function of ISO C.
See also methods toString
(§21.3.7) and toGMTString
(§21.3.28).
21.3.28 public String
toGMTString
()
This Date
object is converted to a String
of length 23 or 24 of the form:
"d mon yyyy hh:mm:ss GMT"where:
1
through 31
), as one or two decimal digits.
Jan
, Feb
, Mar
, Apr
, May
, Jun
, Jul
, Aug
, Sep
, Oct
, Nov
, Dec
).
00
through 23
), as two decimal digits.
00
through 59
), as two decimal digits.
00
through 61
), as two decimal digits.
GMT
" to indicate Greenwich Mean Time.
See also methods toString
(§21.3.7) and toLocaleString
(§21.3.27).
21.3.29 public int
getTimezoneOffset
()
This method returns the offset, measured in minutes, for the local time zone relative
to UTC that is appropriate for the time represented by this Date
object.
For example, in Massachusetts, five time zones west of Greenwich:
new Date(96, 1, 14).getTimezoneOffset() returns 300because on February 14, 1996, standard time (Eastern Standard Time) is in use, which is offset five hours from UTC; but:
new Date(96, 5, 1).getTimezoneOffset() returns 240because on May 1, 1996, daylight saving time (Eastern Daylight Time) is in use, which is offset only four hours from UTC.
This method produces the same result as if it computed:
(this.getTime() - UTC(this.getYear(), this.getMonth(), this.getDate(), this.getHours(), this.getMinutes(), this.getSeconds())) / (60 * 1000)
21.3.30 public static long
UTC
(int year, int month, int date,
int hours, int minutes, int seconds)
The arguments are interpreted as a year, month, day of the month, hour of the day,
minute within the hour, and second within the minute, exactly as for the Date
constructor
of six arguments (§21.3.5), except that the arguments are interpreted relative
to UTC rather than to the local time zone. The time indicated is returned
represented as the distance, measured in milliseconds, of that time from the epoch
(00:00:00 GMT on January 1, 1970).
21.3.31 public static long
parse
(String s)
throws IllegalArgumentException
An attempt is made to interpret the string s
as a representation of a date and time.
If the attempt is successful, the time indicated is returned represented as the distance,
measured in milliseconds, of that time from the epoch (00:00:00 GMT on
January 1, 1970). If the attempt fails, an IllegalArgumentException
is thrown.
The string s
is processed from left to right, looking for data of interest.
Any material in s
that is within the ASCII parenthesis characters (
and )
is ignored. Parentheses may be nested. Otherwise, the only characters permitted within s
are these ASCII characters:
abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ 0123456789,+-:/and whitespace characters (§20.5.19).
A consecutive sequence of decimal digits is treated as a decimal number:
+
or -
and a year has already been recognized, then the number is a time-zone offset. If the number is less than 24, it is an offset measured in hours. Otherwise, it is regarded as an offset in minutes, expressed in 24-hour time format without punctuation. A preceding +
means an eastward offset and a preceding -
means a westward offset. Time zone offsets are always relative to UTC (Greenwich). Thus, for example, -5
occurring in the string would mean "five hours west of Greenwich" and +0430
would mean "four hours and thirty minutes east of Greenwich." It is permitted for the string to specify GMT
, UT
, or UTC
redundantly-for example, GMT-5
or utc+0430
.
1
to produce a number in the range 0
to 11
), unless a month has already been recognized, in which case it is regarded as a day of the month.
AM
, ignoring case, is ignored (but the parse fails if an hour has not been recognized or is less than 1
or greater than 12
).
PM
, ignoring case, adds 12
to the hour (but the parse fails if an hour has not been recognized or is less than 1
or greater than 12
).
SUNDAY
, MONDAY
, TUESDAY
, WEDNESDAY
, THURSDAY
, FRIDAY
, or SATURDAY
, ignoring case, is ignored. For example, sat
, Friday
, TUE
, and Thurs
are ignored.
JANUARY
, FEBRUARY
, MARCH
, APRIL
, MAY
, JUNE
, JULY
, AUGUST
, SEPTEMBER
, OCTOBER
, NOVEMBER
, or DECEMBER
, ignoring case, and considering them in the order given here, is recognized as specifying a month and is converted to a number (0
to 11
). For example, aug
, Sept
, april
, and NOV
are recognized as months. So is Ma
, which is recognized as MARCH
, not MAY
.
GMT
, UT
, or UTC
, ignoring case, is treated as referring to UTC.
EST
, CST
, MST
, or PST
, ignoring case, is recognized as referring to the time zone in North America that is five, six, seven, or eight hours west of Greenwich, respectively. Any word that matches EDT
, CDT
, MDT
, or PDT
, ignoring case, is recognized as referring to the same time zone, respectively, during daylight saving time. (In the future, this method may be upgraded to recognize other time zone designations.)
s
has been scanned, it is converted to a time result in one of two ways. If a time zone or time-zone offset has been recognized, then the year, month, day of month, hour, minute, and second are interpreted in UTC (§21.3.30) and then the time-zone offset is applied. Otherwise, the year, month, day of month, hour, minute, and second are interpreted in the local time zone.
Contents | Prev | Next | Index
Java Language Specification (HTML generated by Suzette Pelouch on February 24, 1998)
Copyright © 1996 Sun Microsystems, Inc.
All rights reserved
Please send any comments or corrections to doug.kramer@sun.com