public class Time extends Object
Calendar
and
GregorianCalendar
classes. An instance of the Time class represents
a moment in time, specified with second precision. It is modelled after
struct tm, and in fact, uses struct tm to implement most of the
functionality.Modifier and Type | Field and Description |
---|---|
boolean |
allDay
True if this is an allDay event.
|
static int |
EPOCH_JULIAN_DAY
The Julian day of the epoch, that is, January 1, 1970 on the Gregorian
calendar.
|
static int |
FRIDAY |
long |
gmtoff
Offset from UTC (in seconds).
|
int |
hour
Hour of day [0-23]
|
static int |
HOUR |
int |
isDst
This time is in daylight savings time.
|
int |
minute
Minute [0-59]
|
static int |
MINUTE |
static int |
MONDAY |
static int |
MONDAY_BEFORE_JULIAN_EPOCH
The Julian day of the Monday in the week of the epoch, December 29, 1969
on the Gregorian calendar.
|
int |
month
Month [0-11]
|
static int |
MONTH |
static int |
MONTH_DAY |
int |
monthDay
Day of month [1-31]
|
static int |
SATURDAY |
int |
second
Seconds [0-61] (2 leap seconds allowed)
|
static int |
SECOND |
static int |
SUNDAY |
static int |
THURSDAY |
String |
timezone
The timezone for this Time.
|
static String |
TIMEZONE_UTC |
static int |
TUESDAY |
static int |
WEDNESDAY |
static int |
WEEK_DAY |
static int |
WEEK_NUM |
int |
weekDay
Day of week [0-6]
|
int |
year
Year.
|
static int |
YEAR |
static int |
YEAR_DAY |
int |
yearDay
Day of year [0-365]
|
Constructor and Description |
---|
Time()
Construct a Time object in the default timezone.
|
Time(String timezone)
Construct a Time object in the timezone named by the string
argument "timezone".
|
Time(Time other)
A copy constructor.
|
Modifier and Type | Method and Description |
---|---|
boolean |
after(Time that)
Returns true if the time represented by this Time object occurs after
the given time.
|
boolean |
before(Time that)
Returns true if the time represented by this Time object occurs before
the given time.
|
void |
clear(String timezone)
Clears all values, setting the timezone to the given timezone.
|
static int |
compare(Time a,
Time b)
Compare two
Time objects and return a negative number if a is less than b , a positive number if a is greater than
b , or 0 if they are equal. |
String |
format(String format)
Print the current value given the format string provided.
|
String |
format2445()
Format according to RFC 2445 DATETIME type.
|
String |
format3339(boolean allDay)
Return a string in the RFC 3339 format.
|
int |
getActualMaximum(int field)
Return the maximum possible value for the given field given the value of
the other fields.
|
static String |
getCurrentTimezone()
Returns the timezone string that is currently set for the device.
|
static int |
getJulianDay(long millis,
long gmtoff)
Computes the Julian day number, given the UTC milliseconds
and the offset (in seconds) from UTC.
|
static int |
getJulianMondayFromWeeksSinceEpoch(int week)
Takes a number of weeks since the epoch and calculates the Julian day of
the Monday for that week.
|
int |
getWeekNumber()
Computes the week number according to ISO 8601.
|
static int |
getWeeksSinceEpochFromJulianDay(int julianDay,
int firstDayOfWeek)
Returns the week since
EPOCH_JULIAN_DAY (Jan 1, 1970) adjusted
for first day of week. |
static boolean |
isEpoch(Time time)
Returns true if the day of the given time is the epoch on the Julian Calendar
(January 1, 1970 on the Gregorian calendar).
|
long |
normalize(boolean ignoreDst)
Ensures the values in each field are in range.
|
boolean |
parse(String s)
Parses a date-time string in either the RFC 2445 format or an abbreviated
format that does not include the "time" field.
|
boolean |
parse3339(String s)
Parse a time in RFC 3339 format.
|
void |
set(int monthDay,
int month,
int year)
Sets the date from the given fields.
|
void |
set(int second,
int minute,
int hour,
int monthDay,
int month,
int year)
Sets the fields.
|
void |
set(long millis)
Sets the fields in this Time object given the UTC milliseconds.
|
void |
set(Time that)
Copy the value of that to this Time object.
|
long |
setJulianDay(int julianDay)
Sets the time from the given Julian day number, which must be based on
the same timezone that is set in this Time object.
|
void |
setToNow()
Sets the time of the given Time object to the current time.
|
void |
switchTimezone(String timezone)
Convert this time object so the time represented remains the same, but is
instead located in a different timezone.
|
long |
toMillis(boolean ignoreDst)
Converts this time to milliseconds.
|
String |
toString()
Return the current time in YYYYMMDDTHHMMSS
|
public static final String TIMEZONE_UTC
public static final int EPOCH_JULIAN_DAY
public static final int MONDAY_BEFORE_JULIAN_EPOCH
public boolean allDay
public int second
public int minute
public int hour
public int monthDay
public int month
public int year
public int weekDay
public int yearDay
public int isDst
public long gmtoff
public String timezone
public static final int SECOND
public static final int MINUTE
public static final int HOUR
public static final int MONTH_DAY
public static final int MONTH
public static final int YEAR
public static final int WEEK_DAY
public static final int YEAR_DAY
public static final int WEEK_NUM
public static final int SUNDAY
public static final int MONDAY
public static final int TUESDAY
public static final int WEDNESDAY
public static final int THURSDAY
public static final int FRIDAY
public static final int SATURDAY
public Time(String timezone)
timezone
- string containing the timezone to use.TimeZone
public Time()
public Time(Time other)
other
- public long normalize(boolean ignoreDst)
If "ignoreDst" is true, then this method sets the "isDst" field to -1 (the "unknown" value) before normalizing. It then computes the correct value for "isDst".
See toMillis(boolean)
for more information about when to
use true or false for "ignoreDst".
public void switchTimezone(String timezone)
public int getActualMaximum(int field)
field
- one of the constants for HOUR, MINUTE, SECOND, etc.public void clear(String timezone)
timezone
- the timezone to use.public static int compare(Time a, Time b)
Time
objects and return a negative number if a
is less than b
, a positive number if a
is greater than
b
, or 0 if they are equal.a
- first Time
instance to compareb
- second Time
instance to comparea
is earlier, a positive result if
a
is earlier, or 0 if they are equal.NullPointerException
- if either argument is null
IllegalArgumentException
- if allDay
is true but hour
, minute
, and second
are not 0.public String format(String format)
format
- a string containing the desired format.public String toString()
public boolean parse(String s)
allDay
field of this Time class is set to true and the hour
,
minute
, and second
fields are set to zero;
otherwise (a time field was included in the date-time string)
allDay
is set to false. The fields weekDay
,
yearDay
, and gmtoff
are always set to zero,
and the field isDst
is set to -1 (unknown). To set those
fields, call normalize(boolean)
after parsing.
To parse a date-time string and convert it to UTC milliseconds, do
something like this:
Time time = new Time(); String date = "20081013T160000Z"; time.parse(date); long millis = time.normalize(false);
s
- the string to parseTimeFormatException
- if s cannot be parsed.public boolean parse3339(String s)
If the string contains a time and time offset, then the time offset will be used to convert the time value to UTC.
If the given string contains just a date (with no time field), then
the allDay
field is set to true and the hour
,
minute
, and second
fields are set to zero.
Returns true if the resulting time value is in UTC time.
s
- the string to parseTimeFormatException
- if s cannot be parsed.public static String getCurrentTimezone()
public void setToNow()
public long toMillis(boolean ignoreDst)
normalize(boolean)
.
If "ignoreDst" is false, then this method uses the current setting of the "isDst" field and will adjust the returned time if the "isDst" field is wrong for the given time. See the sample code below for an example of this.
If "ignoreDst" is true, then this method ignores the current setting of the "isDst" field in this Time object and will instead figure out the correct value of "isDst" (as best it can) from the fields in this Time object. The only case where this method cannot figure out the correct value of the "isDst" field is when the time is inherently ambiguous because it falls in the hour that is repeated when switching from Daylight-Saving Time to Standard Time.
Here is an example where toMillis(true) adjusts the time, assuming that DST changes at 2am on Sunday, Nov 4, 2007.
Time time = new Time(); time.set(4, 10, 2007); // set the date to Nov 4, 2007, 12am time.normalize(); // this sets isDst = 1 time.monthDay += 1; // changes the date to Nov 5, 2007, 12am millis = time.toMillis(false); // millis is Nov 4, 2007, 11pm millis = time.toMillis(true); // millis is Nov 5, 2007, 12am
To avoid this problem, use toMillis(true) after adding or subtracting days or explicitly setting the "monthDay" field. On the other hand, if you are adding or subtracting hours or minutes, then you should use toMillis(false).
You should also use toMillis(false) if you want
to read back the same milliseconds that you set with set(long)
or set(Time)
or after parsing a date string.
public void set(long millis)
millis
- the time in UTC milliseconds since the epoch.public String format2445()
The same as format("%Y%m%dT%H%M%S").
public void set(Time that)
public void set(int second, int minute, int hour, int monthDay, int month, int year)
normalize(boolean)
if you need those.public void set(int monthDay, int month, int year)
normalize(boolean)
if you need those.monthDay
- the day of the month (in the range [1,31])month
- the zero-based month number (in the range [0,11])year
- the yearpublic boolean before(Time that)
that
- a given Time object to compare againstpublic boolean after(Time that)
that
- a given Time object to compare againstpublic int getWeekNumber()
In IS0 8601, weeks start on Monday. The first week of the year (week 1) is defined by ISO 8601 as the first week with four or more of its days in the starting year. Or equivalently, the week containing January 4. Or equivalently, the week with the year's first Thursday in it.
The week number can be calculated by counting Thursdays. Week N contains the Nth Thursday of the year.
public String format3339(boolean allDay)
If allDay is true, expresses the time as Y-M-D
Otherwise, if the timezone is UTC, expresses the time as Y-M-D-T-H-M-S UTC
Otherwise the time is expressed the time as Y-M-D-T-H-M-S +- GMT
allDay
- public static boolean isEpoch(Time time)
time
- the time to testpublic static int getJulianDay(long millis, long gmtoff)
Use toMillis(boolean)
to get the milliseconds.
millis
- the time in UTC millisecondsgmtoff
- the offset from UTC in secondspublic long setJulianDay(int julianDay)
Sets the time from the given Julian day number, which must be based on the same timezone that is set in this Time object. The "gmtoff" field need not be initialized because the given Julian day may have a different GMT offset than whatever is currently stored in this Time object anyway. After this method returns all the fields will be normalized and the time will be set to 12am at the beginning of the given Julian day.
The only exception to this is if 12am does not exist for that day because of daylight saving time. For example, Cairo, Eqypt moves time ahead one hour at 12am on April 25, 2008 and there are a few other places that also change daylight saving time at 12am. In those cases, the time will be set to 1am.
julianDay
- the Julian day in the timezone for this Time objectpublic static int getWeeksSinceEpochFromJulianDay(int julianDay, int firstDayOfWeek)
EPOCH_JULIAN_DAY
(Jan 1, 1970) adjusted
for first day of week. This takes a julian day and the week start day and
calculates which week since EPOCH_JULIAN_DAY
that day occurs in,
starting at 0. *Do not* use this to compute the ISO week number for the
year.julianDay
- The julian day to calculate the week number forfirstDayOfWeek
- Which week day is the first day of the week, see
SUNDAY
public static int getJulianMondayFromWeeksSinceEpoch(int week)
EPOCH_JULIAN_DAY
is considered week 0. It returns the Julian day
for the Monday week weeks after the Monday of the week containing the
epoch.week
- Number of weeks since the epoch