Build 1.0_r1(from source)

android.pim
Class Time

java.lang.Object
  extended by android.pim.Time

public class Time
extends Object

The Time class is a faster replacement for the java.util.Calendar and java.util.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.


Field Summary
 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
           
 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 Summary
Time()
          Construct a Time object in the local timezone.
Time(String timezone)
          Construct a Time object in the timezone named by the string argument "timezone".
Time(Time other)
          A copy constructor.
 
Method Summary
 boolean after(Time that)
           
 boolean before(Time that)
           
 void clear(String timezone)
          Clears all values, setting the timezone to the given timezone.
static int compare(Time a, Time b)
          return a negative number if a is less than b, a positive number if a is greater than b, and 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)
           
 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.
 int getWeekNumber()
          Computes the week number according to ISO 8601.
static boolean isEpoch(Time time)
           
 long normalize(boolean ignoreDst)
          Ensures the values in each field are in range.
 void parse(String s)
          Parse a time in the current zone in YYYYMMDDTHHMMSS format.
 boolean parse2445(String s)
          Parse a time in RFC 2445 format.
 boolean parse3339(String s)
          Parse a time in RFC 3339 format.
 void set(int monthDay, int month, int year)
           
 void set(int second, int minute, int hour, int monthDay, int month, int year)
          Set 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 format
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

TIMEZONE_UTC

public static final String TIMEZONE_UTC
See Also:
Constant Field Values

EPOCH_JULIAN_DAY

public static final int EPOCH_JULIAN_DAY
The Julian day of the epoch, that is, January 1, 1970 on the Gregorian calendar.

See Also:
Constant Field Values

allDay

public boolean allDay
True if this is an allDay event. The hour, minute, second fields are all zero, and the date is displayed the same in all time zones.


second

public int second
Seconds [0-61] (2 leap seconds allowed)


minute

public int minute
Minute [0-59]


hour

public int hour
Hour of day [0-23]


monthDay

public int monthDay
Day of month [1-31]


month

public int month
Month [0-11]


year

public int year
Year. TBD. Is this years since 1900 like in struct tm?


weekDay

public int weekDay
Day of week [0-6]


yearDay

public int yearDay
Day of year [0-365]


isDst

public int isDst
This time is in daylight savings time. One of:

gmtoff

public long gmtoff
Offset from UTC (in seconds).


timezone

public String timezone
The timezone for this Time. Should not be null.


SECOND

public static final int SECOND
See Also:
Constant Field Values

MINUTE

public static final int MINUTE
See Also:
Constant Field Values

HOUR

public static final int HOUR
See Also:
Constant Field Values

MONTH_DAY

public static final int MONTH_DAY
See Also:
Constant Field Values

MONTH

public static final int MONTH
See Also:
Constant Field Values

YEAR

public static final int YEAR
See Also:
Constant Field Values

WEEK_DAY

public static final int WEEK_DAY
See Also:
Constant Field Values

YEAR_DAY

public static final int YEAR_DAY
See Also:
Constant Field Values

WEEK_NUM

public static final int WEEK_NUM
See Also:
Constant Field Values

SUNDAY

public static final int SUNDAY
See Also:
Constant Field Values

MONDAY

public static final int MONDAY
See Also:
Constant Field Values

TUESDAY

public static final int TUESDAY
See Also:
Constant Field Values

WEDNESDAY

public static final int WEDNESDAY
See Also:
Constant Field Values

THURSDAY

public static final int THURSDAY
See Also:
Constant Field Values

FRIDAY

public static final int FRIDAY
See Also:
Constant Field Values

SATURDAY

public static final int SATURDAY
See Also:
Constant Field Values
Constructor Detail

Time

public Time(String timezone)
Construct a Time object in the timezone named by the string argument "timezone". The time is initialized to Jan 1, 1970.


Time

public Time()
Construct a Time object in the local timezone. The time is initialized to Jan 1, 1970.


Time

public Time(Time other)
A copy constructor. Construct a Time object by copying the given Time object. No normalization occurs.

Parameters:
other -
Method Detail

normalize

public long normalize(boolean ignoreDst)
Ensures the values in each field are in range. For example if the current value of this calendar is March 32, normalize() will convert it to April 1. It also fills in weekDay, yearDay, isDst and gmtoff.

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".

Returns:
the UTC milliseconds since the epoch

switchTimezone

public void switchTimezone(String timezone)
Convert this time object so the time represented remains the same, but is instead located in a different timezone. This method automatically calls normalize() in some cases


getActualMaximum

public int getActualMaximum(int field)
Return the maximum possible value for the given field given the value of the other fields. Requires that it be normalized for MONTH_DAY and YEAR_DAY.


clear

public void clear(String timezone)
Clears all values, setting the timezone to the given timezone. Sets isDst to a negative value to mean "unknown".


compare

public static int compare(Time a,
                          Time b)
return a negative number if a is less than b, a positive number if a is greater than b, and 0 if they are equal.


format

public String format(String format)
Print the current value given the format string provided. See man strftime for what means what. The final string must be less than 256 characters.


toString

public String toString()
Return the current time in YYYYMMDDTHHMMSS format

Overrides:
toString in class Object
Returns:
String a printable representation for the receiver.

parse

public void parse(String s)
Parse a time in the current zone in YYYYMMDDTHHMMSS format.


parse2445

public boolean parse2445(String s)
Parse a time in RFC 2445 format. Returns whether or not the time is in UTC (ends with Z).

Parameters:
s - the string to parse
Returns:
true if the resulting time value is in UTC time

parse3339

public boolean parse3339(String s)
Parse a time in RFC 3339 format. This method also parses simple dates (that is, strings that contain no time or time offset). If the string contains a time and time offset, then the time offset will be used to convert the time value to UTC. Returns true if the resulting time value is in UTC time.

Parameters:
s - the string to parse
Returns:
true if the resulting time value is in UTC time

getCurrentTimezone

public static String getCurrentTimezone()
Returns the timezone string that is currently set for the device.


setToNow

public void setToNow()
Sets the time of the given Time object to the current time.


toMillis

public long toMillis(boolean ignoreDst)
Converts this time to milliseconds. Suitable for interacting with the standard java libraries. The time is in UTC milliseconds since the epoch. This does an implicit normalization to compute the milliseconds but does not change any of the fields in this Time object. If you want to normalize the fields in this Time object and also get the milliseconds then use 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(2007, 10, 4);  // 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.


set

public void set(long millis)
Sets the fields in this Time object given the UTC milliseconds. After this method returns, all the fields are normalized. This also sets the "isDst" field to the correct value.

Parameters:
millis - the time in UTC milliseconds since the epoch.

format2445

public String format2445()
Format according to RFC 2445 DATETIME type.

The same as format("%Y%m%dT%H%M%S").


set

public void set(Time that)
Copy the value of that to this Time object. No normalization happens.


set

public void set(int second,
                int minute,
                int hour,
                int monthDay,
                int month,
                int year)
Set the fields. Sets weekDay, yearDay and gmtoff to 0. Call normalize() if you need those.


set

public void set(int monthDay,
                int month,
                int year)

before

public boolean before(Time that)

after

public boolean after(Time that)

getWeekNumber

public int getWeekNumber()
Computes the week number according to ISO 8601. The current Time object must already be normalized because this method uses the yearDay and weekDay fields. 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.

Returns:
the ISO week number.

format3339

public String format3339(boolean allDay)

isEpoch

public static boolean isEpoch(Time time)

getJulianDay

public static int getJulianDay(long millis,
                               long gmtoff)
Computes the Julian day number, given the UTC milliseconds and the offset (in seconds) from UTC. The Julian day for a given date will be the same for every timezone. For example, the Julian day for July 1, 2008 is 2454649. This is the same value no matter what timezone is being used. The Julian day is useful for testing if two events occur on the same day and for determining the relative time of an event from the present ("yesterday", "3 days ago", etc.).

Use toMillis(boolean) to get the milliseconds.

Parameters:
millis - the time in UTC milliseconds
gmtoff - the offset from UTC in seconds
Returns:
the Julian day

setJulianDay

public 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.

Parameters:
julianDay - the Julian day in the timezone for this Time object
Returns:
the UTC milliseconds for the beginning of the Julian day

Build 1.0_r1(from source)

Please submit a feedback, bug or feature