Time

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.

Constant Value: 2440588 (0x00253d8c)

FRIDAY

public static final int FRIDAY

Constant Value: 5 (0x00000005)

HOUR

public static final int HOUR

Constant Value: 3 (0x00000003)

MINUTE

public static final int MINUTE

Constant Value: 2 (0x00000002)

MONDAY

public static final int MONDAY

Constant Value: 1 (0x00000001)

MONDAY_BEFORE_JULIAN_EPOCH

public static final int MONDAY_BEFORE_JULIAN_EPOCH

The Julian day of the Monday in the week of the epoch, December 29, 1969 on the Gregorian calendar.

Constant Value: 2440585 (0x00253d89)

MONTH

public static final int MONTH

Constant Value: 5 (0x00000005)

MONTH_DAY

public static final int MONTH_DAY

Constant Value: 4 (0x00000004)

SATURDAY

public static final int SATURDAY

Constant Value: 6 (0x00000006)

SECOND

public static final int SECOND

Constant Value: 1 (0x00000001)

SUNDAY

public static final int SUNDAY

Constant Value: 0 (0x00000000)

THURSDAY

public static final int THURSDAY

Constant Value: 4 (0x00000004)

TIMEZONE_UTC

public static final String TIMEZONE_UTC

Constant Value: "UTC"

TUESDAY

public static final int TUESDAY

Constant Value: 2 (0x00000002)

WEDNESDAY

public static final int WEDNESDAY

Constant Value: 3 (0x00000003)

WEEK_DAY

public static final int WEEK_DAY

Constant Value: 7 (0x00000007)

WEEK_NUM

public static final int WEEK_NUM

Constant Value: 9 (0x00000009)

YEAR

public static final int YEAR

Constant Value: 6 (0x00000006)

YEAR_DAY

public static final int YEAR_DAY

Constant Value: 8 (0x00000008)

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.

gmtoff

public long gmtoff

Offset in seconds from UTC including any DST offset.

hour

public int hour

Hour of day [0-23]

isDst

public int isDst

This time is in daylight savings time. One of:

• positive - in dst
• 0 - not in dst
• negative - unknown

minute

public int minute

Minute [0-59]

month

public int month

Month [0-11]

monthDay

public int monthDay

Day of month [1-31]

second

public int second

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

timezone

public String timezone

The timezone for this Time. Should not be null.

weekDay

public int weekDay

Day of week [0-6]

year

public int year

Year. For example, 1970.

yearDay

public int yearDay

Day of year [0-365]

Time

public Time ()

Construct a Time object in the default 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.

Time

public Time (String timezoneId)

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

after

public boolean after (Time that)

Returns true if the time represented by this Time object occurs after the given time.

Equivalent to Time.compare(this, that) > 0. See compare(android.text.format.Time, android.text.format.Time) for details.

before

public boolean before (Time that)

Returns true if the time represented by this Time object occurs before the given time.

Equivalent to Time.compare(this, that) < 0. See compare(android.text.format.Time, android.text.format.Time) for details.

clear

public void clear (String timezoneId)

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)

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.

This method can return an incorrect answer when the date / time fields of either Time have been set to a local time that contradicts the available timezone information.

format

public String format (String format)

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

format2445

public String format2445 ()

Format according to RFC 2445 DATE-TIME type.

The same as format("%Y%m%dT%H%M%S"), or format("%Y%m%dT%H%M%SZ") for a Time with a timezone set to "UTC".

format3339

public String format3339 (boolean allDay)

Return a string in the RFC 3339 format.

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

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.

getCurrentTimezone

public static String getCurrentTimezone ()

Returns the timezone string that is currently set for the device.

getJulianDay

public static int getJulianDay (long millis, 
                long gmtoffSeconds)

This method is deprecated.
Use JulianFields.JULIAN_DAY instead.

Computes the Julian day number for a point in time in a particular timezone. The Julian day for a given calendar date is the same for every timezone. For example, the Julian day for July 1, 2008 is 2454649.

Callers must pass the time in UTC millisecond (as can be returned by toMillis(boolean) or normalize(boolean)) and the offset from UTC of the timezone in seconds at that time (as might be in gmtoff).

The Julian day is useful for testing if two events occur on the same calendar date and for determining the relative time of an event from the present ("yesterday", "3 days ago", etc.).

getJulianMondayFromWeeksSinceEpoch

public static int getJulianMondayFromWeeksSinceEpoch (int week)

Takes a number of weeks since the epoch and calculates the Julian day of the Monday for that week. This assumes that the week containing the 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.

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.

getWeeksSinceEpochFromJulianDay

public static int getWeeksSinceEpochFromJulianDay (int julianDay, 
                int firstDayOfWeek)

Returns the week since 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.

isEpoch

public static boolean isEpoch (Time time)

Returns true if the instant of the supplied time would be for the Gregorian calendar date January 1, 1970 for a user observing UTC , i.e. the timezone of the time object is ignored.

See getJulianDay(long, long) for how to determine the Julian day for the timezone of the time object.

This method can return an incorrect answer when the date / time fields have been set to a local time that contradicts the available timezone information.

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 time in milliseconds and sets the correct value for "isDst" if the fields resolve to a valid date / time.

See toMillis(boolean) for more information about when to use true or false for "ignoreDst" and when -1 might be returned.

parse

public 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. For example, all of the following strings are valid:

• "20081013T160000Z"
• "20081013T160000"
• "20081013"

   Time time = new Time();
   String date = "20081013T160000Z";
   time.parse(date);
   long millis = time.normalize(false);
 

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). For example, all of the following strings are valid:

• "2008-10-13T16:00:00.000Z"
• "2008-10-13T16:00:00.000+07:00"
• "2008-10-13T16:00:00.000-07:00"
• "2008-10-13"

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.

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)

Sets the fields. Sets weekDay, yearDay and gmtoff to 0, and isDst to -1. Call normalize(boolean) if you need those.

set

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

Sets the date from the given fields. Also sets allDay to true. Sets weekDay, yearDay and gmtoff to 0, and isDst to -1. Call normalize(boolean) if you need those.

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.

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.

setToNow

public void setToNow ()

Sets the time of the given Time object to the current time.

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.

This method can return incorrect results if the date / time cannot be normalized.

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(4, 10, 2007);  // set the date to Nov 4, 2007, 12am
 time.normalize(false);       // 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(android.text.format.Time) or after parsing a date string.

This method can return -1 when the date / time fields have been set to a local time that conflicts with available timezone information. For example, when daylight savings transitions cause an hour to be skipped: times within that hour will return -1 if isDst = -1.

toString

public String toString ()

Return the current time in YYYYMMDDTHHMMSS<tz> format