FileDocCategorySizeDatePackage
DateUtils.javaAPI DocAndroid 1.5 API67747Wed May 06 22:41:56 BST 2009android.text.format

DateUtils

public class DateUtils extends Object
This class contains various date-related utilities for creating text for things like elapsed time and date ranges, strings for days of the week and months, and AM/PM text etc.

Fields Summary
private static final Object
sLock
private static final int[]
sDaysLong
private static final int[]
sDaysMedium
private static final int[]
sDaysShort
private static final int[]
sDaysShorter
private static final int[]
sDaysShortest
private static final int[]
sMonthsLong
private static final int[]
sMonthsMedium
private static final int[]
sMonthsShortest
private static final int[]
sAmPm
private static android.content.res.Configuration
sLastConfig
private static String
sStatusTimeFormat
private static String
sElapsedFormatMMSS
private static String
sElapsedFormatHMMSS
private static final String
FAST_FORMAT_HMMSS
private static final String
FAST_FORMAT_MMSS
private static final char
TIME_PADDING
private static final char
TIME_SEPARATOR
public static final long
SECOND_IN_MILLIS
public static final long
MINUTE_IN_MILLIS
public static final long
HOUR_IN_MILLIS
public static final long
DAY_IN_MILLIS
public static final long
WEEK_IN_MILLIS
public static final long
YEAR_IN_MILLIS
public static final int
FORMAT_SHOW_TIME
public static final int
FORMAT_SHOW_WEEKDAY
public static final int
FORMAT_SHOW_YEAR
public static final int
FORMAT_NO_YEAR
public static final int
FORMAT_SHOW_DATE
public static final int
FORMAT_NO_MONTH_DAY
public static final int
FORMAT_12HOUR
public static final int
FORMAT_24HOUR
public static final int
FORMAT_CAP_AMPM
public static final int
FORMAT_NO_NOON
public static final int
FORMAT_CAP_NOON
public static final int
FORMAT_NO_MIDNIGHT
public static final int
FORMAT_CAP_MIDNIGHT
public static final int
FORMAT_UTC
public static final int
FORMAT_ABBREV_TIME
public static final int
FORMAT_ABBREV_WEEKDAY
public static final int
FORMAT_ABBREV_MONTH
public static final int
FORMAT_NUMERIC_DATE
public static final int
FORMAT_ABBREV_RELATIVE
public static final int
FORMAT_ABBREV_ALL
public static final int
FORMAT_CAP_NOON_MIDNIGHT
public static final int
FORMAT_NO_NOON_MIDNIGHT
public static final String
HOUR_MINUTE_24
public static final String
MONTH_FORMAT
public static final String
ABBREV_MONTH_FORMAT
public static final String
NUMERIC_MONTH_FORMAT
public static final String
MONTH_DAY_FORMAT
public static final String
YEAR_FORMAT
public static final String
YEAR_FORMAT_TWO_DIGITS
public static final String
WEEKDAY_FORMAT
public static final String
ABBREV_WEEKDAY_FORMAT
public static final int[]
sameYearTable
public static final int[]
sameMonthTable
public static final int
LENGTH_LONG
Request the full spelled-out name. For use with the 'abbrev' parameter of {@link #getDayOfWeekString} and {@link #getMonthString}.
public static final int
LENGTH_MEDIUM
Request an abbreviated version of the name. For use with the 'abbrev' parameter of {@link #getDayOfWeekString} and {@link #getMonthString}.
public static final int
LENGTH_SHORT
Request a shorter abbreviated version of the name. For use with the 'abbrev' parameter of {@link #getDayOfWeekString} and {@link #getMonthString}.
public static final int
LENGTH_SHORTER
Request an even shorter abbreviated version of the name. For use with the 'abbrev' parameter of {@link #getDayOfWeekString} and {@link #getMonthString}.
public static final int
LENGTH_SHORTEST
Request an even shorter abbreviated version of the name. For use with the 'abbrev' parameter of {@link #getDayOfWeekString} and {@link #getMonthString}.
private static Time
sNowTime
private static Time
sThenTime
Constructors Summary
Methods Summary
public static voidassign(java.util.Calendar lval, java.util.Calendar rval)

hide
deprecated
use {@link android.text.format.Time}

        // there should be a faster way.
        lval.clear();
        lval.setTimeInMillis(rval.getTimeInMillis());
private static final intcheck(int lowerBound, int upperBound, int value)

hide
deprecated
use {@link android.text.format.Time}

        if (value >= lowerBound && value <= upperBound) {
            return value;
        }
        throw new DateException("field out of bounds.  max=" + upperBound
                                        + " value=" + value);
private static final intctoi(java.lang.String str, int index)

hide
deprecated
use {@link android.text.format.Time}

        char c = str.charAt(index);
        if (c >= '0" && c <= '9") {
            return (int)(c - '0");
        }
        throw new DateException("Expected numeric character.  Got '" +
                                            c + "'");
public static java.lang.StringformatDateRange(android.content.Context context, long startMillis, long endMillis, int flags)
Formats a date or a time range according to the local conventions.

Example output strings (date formats in these examples are shown using the US date format convention but that may change depending on the local settings):

  • 10:15am
  • 3:00pm - 4:00pm
  • 3pm - 4pm
  • 3PM - 4PM
  • 08:00 - 17:00
  • Oct 9
  • Tue, Oct 9
  • October 9, 2007
  • Oct 9 - 10
  • Oct 9 - 10, 2007
  • Oct 28 - Nov 3, 2007
  • Dec 31, 2007 - Jan 1, 2008
  • Oct 9, 8:00am - Oct 10, 5:00pm
  • 12/31/2007 - 01/01/2008

The flags argument is a bitmask of options from the following list:

  • FORMAT_SHOW_TIME
  • FORMAT_SHOW_WEEKDAY
  • FORMAT_SHOW_YEAR
  • FORMAT_NO_YEAR
  • FORMAT_SHOW_DATE
  • FORMAT_NO_MONTH_DAY
  • FORMAT_12HOUR
  • FORMAT_24HOUR
  • FORMAT_CAP_AMPM
  • FORMAT_NO_NOON
  • FORMAT_CAP_NOON
  • FORMAT_NO_MIDNIGHT
  • FORMAT_CAP_MIDNIGHT
  • FORMAT_UTC
  • FORMAT_ABBREV_TIME
  • FORMAT_ABBREV_WEEKDAY
  • FORMAT_ABBREV_MONTH
  • FORMAT_ABBREV_ALL
  • FORMAT_NUMERIC_DATE

If FORMAT_SHOW_TIME is set, the time is shown as part of the date range. If the start and end time are the same, then just the start time is shown.

If FORMAT_SHOW_WEEKDAY is set, then the weekday is shown.

If FORMAT_SHOW_YEAR is set, then the year is always shown. If FORMAT_NO_YEAR is set, then the year is not shown. If neither FORMAT_SHOW_YEAR nor FORMAT_NO_YEAR are set, then the year is shown only if it is different from the current year, or if the start and end dates fall on different years. If both are set, FORMAT_SHOW_YEAR takes precedence.

Normally the date is shown unless the start and end day are the same. If FORMAT_SHOW_DATE is set, then the date is always shown, even for same day ranges.

If FORMAT_NO_MONTH_DAY is set, then if the date is shown, just the month name will be shown, not the day of the month. For example, "January, 2008" instead of "January 6 - 12, 2008".

If FORMAT_CAP_AMPM is set and 12-hour time is used, then the "AM" and "PM" are capitalized.

If FORMAT_NO_NOON is set and 12-hour time is used, then "12pm" is shown instead of "noon".

If FORMAT_CAP_NOON is set and 12-hour time is used, then "Noon" is shown instead of "noon".

If FORMAT_NO_MIDNIGHT is set and 12-hour time is used, then "12am" is shown instead of "midnight".

If FORMAT_CAP_NOON is set and 12-hour time is used, then "Midnight" is shown instead of "midnight".

If FORMAT_12HOUR is set and the time is shown, then the time is shown in the 12-hour time format. You should not normally set this. Instead, let the time format be chosen automatically according to the system settings. If both FORMAT_12HOUR and FORMAT_24HOUR are set, then FORMAT_24HOUR takes precedence.

If FORMAT_24HOUR is set and the time is shown, then the time is shown in the 24-hour time format. You should not normally set this. Instead, let the time format be chosen automatically according to the system settings. If both FORMAT_12HOUR and FORMAT_24HOUR are set, then FORMAT_24HOUR takes precedence.

If FORMAT_UTC is set, then the UTC timezone is used for the start and end milliseconds.

If FORMAT_ABBREV_TIME is set and 12-hour time format is used, then the start and end times (if shown) are abbreviated by not showing the minutes if they are zero. For example, instead of "3:00pm" the time would be abbreviated to "3pm".

If FORMAT_ABBREV_WEEKDAY is set, then the weekday (if shown) is abbreviated to a 3-letter string.

If FORMAT_ABBREV_MONTH is set, then the month (if shown) is abbreviated to a 3-letter string.

If FORMAT_ABBREV_ALL is set, then the weekday and the month (if shown) are abbreviated to 3-letter strings.

If FORMAT_NUMERIC_DATE is set, then the date is shown in numeric format instead of using the name of the month. For example, "12/31/2008" instead of "December 31, 2008".

param
context the context is required only if the time is shown
param
startMillis the start time in UTC milliseconds
param
endMillis the end time in UTC milliseconds
param
flags a bit mask of options
return
a string containing the formatted date/time range.

        Resources res = Resources.getSystem();
        boolean showTime = (flags & FORMAT_SHOW_TIME) != 0;
        boolean showWeekDay = (flags & FORMAT_SHOW_WEEKDAY) != 0;
        boolean showYear = (flags & FORMAT_SHOW_YEAR) != 0;
        boolean noYear = (flags & FORMAT_NO_YEAR) != 0;
        boolean useUTC = (flags & FORMAT_UTC) != 0;
        boolean abbrevWeekDay = (flags & (FORMAT_ABBREV_WEEKDAY | FORMAT_ABBREV_ALL)) != 0;
        boolean abbrevMonth = (flags & (FORMAT_ABBREV_MONTH | FORMAT_ABBREV_ALL)) != 0;
        boolean noMonthDay = (flags & FORMAT_NO_MONTH_DAY) != 0;
        boolean numericDate = (flags & FORMAT_NUMERIC_DATE) != 0;

        // If we're getting called with a single instant in time (from
        // e.g. formatDateTime(), below), then we can skip a lot of
        // computation below that'd otherwise be thrown out.
        boolean isInstant = (startMillis == endMillis);

        Time startDate = useUTC ? new Time(Time.TIMEZONE_UTC) : new Time();
        startDate.set(startMillis);

        Time endDate;
        int dayDistance;
        if (isInstant) {
            endDate = startDate;
            dayDistance = 0;
        } else {
            endDate = useUTC ? new Time(Time.TIMEZONE_UTC) : new Time();
            endDate.set(endMillis);
            int startJulianDay = Time.getJulianDay(startMillis, startDate.gmtoff);
            int endJulianDay = Time.getJulianDay(endMillis, endDate.gmtoff);
            dayDistance = endJulianDay - startJulianDay;
        }

        // If the end date ends at 12am at the beginning of a day,
        // then modify it to make it look like it ends at midnight on
        // the previous day.  This will allow us to display "8pm - midnight",
        // for example, instead of "Nov 10, 8pm - Nov 11, 12am". But we only do
        // this if it is midnight of the same day as the start date because
        // for multiple-day events, an end time of "midnight on Nov 11" is
        // ambiguous and confusing (is that midnight the start of Nov 11, or
        // the end of Nov 11?).
        // If we are not showing the time then also adjust the end date
        // for multiple-day events.  This is to allow us to display, for
        // example, "Nov 10 -11" for an event with a start date of Nov 10
        // and an end date of Nov 12 at 00:00.
        // If the start and end time are the same, then skip this and don't
        // adjust the date.
        if (!isInstant
            && (endDate.hour | endDate.minute | endDate.second) == 0
            && (!showTime || dayDistance <= 1)) {
            endDate.monthDay -= 1;
            endDate.normalize(true /* ignore isDst */);
        }

        int startDay = startDate.monthDay;
        int startMonthNum = startDate.month;
        int startYear = startDate.year;

        int endDay = endDate.monthDay;
        int endMonthNum = endDate.month;
        int endYear = endDate.year;

        String startWeekDayString = "";
        String endWeekDayString = "";
        if (showWeekDay) {
            String weekDayFormat = "";
            if (abbrevWeekDay) {
                weekDayFormat = ABBREV_WEEKDAY_FORMAT;
            } else {
                weekDayFormat = WEEKDAY_FORMAT;
            }
            startWeekDayString = startDate.format(weekDayFormat);
            endWeekDayString = isInstant ? startWeekDayString : endDate.format(weekDayFormat);
        }

        String startTimeString = "";
        String endTimeString = "";
        if (showTime) {
            String startTimeFormat = "";
            String endTimeFormat = "";
            boolean force24Hour = (flags & FORMAT_24HOUR) != 0;
            boolean force12Hour = (flags & FORMAT_12HOUR) != 0;
            boolean use24Hour;
            if (force24Hour) {
                use24Hour = true;
            } else if (force12Hour) {
                use24Hour = false;
            } else {
                use24Hour = DateFormat.is24HourFormat(context);
            }
            if (use24Hour) {
                startTimeFormat = HOUR_MINUTE_24;
                endTimeFormat = HOUR_MINUTE_24;
            } else {
                boolean abbrevTime = (flags & (FORMAT_ABBREV_TIME | FORMAT_ABBREV_ALL)) != 0;
                boolean capAMPM = (flags & FORMAT_CAP_AMPM) != 0;
                boolean noNoon = (flags & FORMAT_NO_NOON) != 0;
                boolean capNoon = (flags & FORMAT_CAP_NOON) != 0;
                boolean noMidnight = (flags & FORMAT_NO_MIDNIGHT) != 0;
                boolean capMidnight = (flags & FORMAT_CAP_MIDNIGHT) != 0;

                boolean startOnTheHour = startDate.minute == 0 && startDate.second == 0;
                boolean endOnTheHour = endDate.minute == 0 && endDate.second == 0;
                if (abbrevTime && startOnTheHour) {
                    if (capAMPM) {
                        startTimeFormat = res.getString(com.android.internal.R.string.hour_cap_ampm);
                    } else {
                        startTimeFormat = res.getString(com.android.internal.R.string.hour_ampm);
                    }
                } else {
                    if (capAMPM) {
                        startTimeFormat = res.getString(com.android.internal.R.string.hour_minute_cap_ampm);
                    } else {
                        startTimeFormat = res.getString(com.android.internal.R.string.hour_minute_ampm);
                    }
                }

                // Don't waste time on setting endTimeFormat when
                // we're dealing with an instant, where we'll never
                // need the end point.  (It's the same as the start
                // point)
                if (!isInstant) {
                    if (abbrevTime && endOnTheHour) {
                        if (capAMPM) {
                            endTimeFormat = res.getString(com.android.internal.R.string.hour_cap_ampm);
                        } else {
                            endTimeFormat = res.getString(com.android.internal.R.string.hour_ampm);
                        }
                    } else {
                        if (capAMPM) {
                            endTimeFormat = res.getString(com.android.internal.R.string.hour_minute_cap_ampm);
                        } else {
                            endTimeFormat = res.getString(com.android.internal.R.string.hour_minute_ampm);
                        }
                    }

                    if (endDate.hour == 12 && endOnTheHour && !noNoon) {
                        if (capNoon) {
                            endTimeFormat = res.getString(com.android.internal.R.string.Noon);
                        } else {
                            endTimeFormat = res.getString(com.android.internal.R.string.noon);
                        }
                    } else if (endDate.hour == 0 && endOnTheHour && !noMidnight) {
                        if (capMidnight) {
                            endTimeFormat = res.getString(com.android.internal.R.string.Midnight);
                        } else {
                            endTimeFormat = res.getString(com.android.internal.R.string.midnight);
                        }
                    }
                }

                if (startDate.hour == 12 && startOnTheHour && !noNoon) {
                    if (capNoon) {
                        startTimeFormat = res.getString(com.android.internal.R.string.Noon);
                    } else {
                        startTimeFormat = res.getString(com.android.internal.R.string.noon);
                    }
                    // Don't show the start time starting at midnight.  Show
                    // 12am instead.
                }
            }

            startTimeString = startDate.format(startTimeFormat);
            endTimeString = isInstant ? startTimeString : endDate.format(endTimeFormat);
        }

        // Show the year if the user specified FORMAT_SHOW_YEAR or if
        // the starting and end years are different from each other
        // or from the current year.  But don't show the year if the
        // user specified FORMAT_NO_YEAR.
        if (showYear) {
            // No code... just a comment for clarity.  Keep showYear
            // on, as they enabled it with FORMAT_SHOW_YEAR.  This
            // takes precedence over them setting FORMAT_NO_YEAR.
        } else if (noYear) {
            // They explicitly didn't want a year.
            showYear = false;
        } else if (startYear != endYear) {
            showYear = true;
        } else {
            // Show the year if it's not equal to the current year.
            Time currentTime = new Time();
            currentTime.setToNow();
            showYear = startYear != currentTime.year;
        }

        String defaultDateFormat, fullFormat, dateRange;
        if (numericDate) {
            defaultDateFormat = res.getString(com.android.internal.R.string.numeric_date);
        } else if (showYear) {
            if (abbrevMonth) {
                if (noMonthDay) {
                    defaultDateFormat = res.getString(com.android.internal.R.string.abbrev_month_year);
                } else {
                    defaultDateFormat = res.getString(com.android.internal.R.string.abbrev_month_day_year);
                }
            } else {
                if (noMonthDay) {
                    defaultDateFormat = res.getString(com.android.internal.R.string.month_year);
                } else {
                    defaultDateFormat = res.getString(com.android.internal.R.string.month_day_year);
                }
            }
        } else {
            if (abbrevMonth) {
                if (noMonthDay) {
                    defaultDateFormat = res.getString(com.android.internal.R.string.abbrev_month);
                } else {
                    defaultDateFormat = res.getString(com.android.internal.R.string.abbrev_month_day);
                }
            } else {
                if (noMonthDay) {
                    defaultDateFormat = res.getString(com.android.internal.R.string.month);
                } else {
                    defaultDateFormat = res.getString(com.android.internal.R.string.month_day);
                }
            }
        }

        if (showWeekDay) {
            if (showTime) {
                fullFormat = res.getString(com.android.internal.R.string.wday1_date1_time1_wday2_date2_time2);
            } else {
                fullFormat = res.getString(com.android.internal.R.string.wday1_date1_wday2_date2);
            }
        } else {
            if (showTime) {
                fullFormat = res.getString(com.android.internal.R.string.date1_time1_date2_time2);
            } else {
                fullFormat = res.getString(com.android.internal.R.string.date1_date2);
            }
        }

        if (noMonthDay && startMonthNum == endMonthNum) {
            // Example: "January, 2008"
            String startDateString = startDate.format(defaultDateFormat);
            return startDateString;
        }

        if (startYear != endYear || noMonthDay) {
            // Different year or we are not showing the month day number.
            // Example: "December 31, 2007 - January 1, 2008"
            // Or: "January - February, 2008"
            String startDateString = startDate.format(defaultDateFormat);
            String endDateString = endDate.format(defaultDateFormat);

            // The values that are used in a fullFormat string are specified
            // by position.
            dateRange = String.format(fullFormat,
                    startWeekDayString, startDateString, startTimeString,
                    endWeekDayString, endDateString, endTimeString);
            return dateRange;
        }

        // Get the month, day, and year strings for the start and end dates
        String monthFormat;
        if (numericDate) {
            monthFormat = NUMERIC_MONTH_FORMAT;
        } else if (abbrevMonth) {
            monthFormat = ABBREV_MONTH_FORMAT;
        } else {
            monthFormat = MONTH_FORMAT;
        }
        String startMonthString = startDate.format(monthFormat);
        String startMonthDayString = startDate.format(MONTH_DAY_FORMAT);
        String startYearString = startDate.format(YEAR_FORMAT);

        String endMonthString = isInstant ? null : endDate.format(monthFormat);
        String endMonthDayString = isInstant ? null : endDate.format(MONTH_DAY_FORMAT);
        String endYearString = isInstant ? null : endDate.format(YEAR_FORMAT);

        if (startMonthNum != endMonthNum) {
            // Same year, different month.
            // Example: "October 28 - November 3"
            // or: "Wed, Oct 31 - Sat, Nov 3, 2007"
            // or: "Oct 31, 8am - Sat, Nov 3, 2007, 5pm"

            int index = 0;
            if (showWeekDay) index = 1;
            if (showYear) index += 2;
            if (showTime) index += 4;
            if (numericDate) index += 8;
            int resId = sameYearTable[index];
            fullFormat = res.getString(resId);

            // The values that are used in a fullFormat string are specified
            // by position.
            dateRange = String.format(fullFormat,
                    startWeekDayString, startMonthString, startMonthDayString,
                    startYearString, startTimeString,
                    endWeekDayString, endMonthString, endMonthDayString,
                    endYearString, endTimeString);
            return dateRange;
        }

        if (startDay != endDay) {
            // Same month, different day.
            int index = 0;
            if (showWeekDay) index = 1;
            if (showYear) index += 2;
            if (showTime) index += 4;
            if (numericDate) index += 8;
            int resId = sameMonthTable[index];
            fullFormat = res.getString(resId);

            // The values that are used in a fullFormat string are specified
            // by position.
            dateRange = String.format(fullFormat,
                    startWeekDayString, startMonthString, startMonthDayString,
                    startYearString, startTimeString,
                    endWeekDayString, endMonthString, endMonthDayString,
                    endYearString, endTimeString);
            return dateRange;
        }

        // Same start and end day
        boolean showDate = (flags & FORMAT_SHOW_DATE) != 0;

        // If nothing was specified, then show the date.
        if (!showTime && !showDate && !showWeekDay) showDate = true;

        // Compute the time string (example: "10:00 - 11:00 am")
        String timeString = "";
        if (showTime) {
            // If the start and end time are the same, then just show the
            // start time.
            if (isInstant) {
                // Same start and end time.
                // Example: "10:15 AM"
                timeString = startTimeString;
            } else {
                // Example: "10:00 - 11:00 am"
                String timeFormat = res.getString(com.android.internal.R.string.time1_time2);
                timeString = String.format(timeFormat, startTimeString, endTimeString);
            }
        }

        // Figure out which full format to use.
        fullFormat = "";
        String dateString = "";
        if (showDate) {
            dateString = startDate.format(defaultDateFormat);
            if (showWeekDay) {
                if (showTime) {
                    // Example: "10:00 - 11:00 am, Tue, Oct 9"
                    fullFormat = res.getString(com.android.internal.R.string.time_wday_date);
                } else {
                    // Example: "Tue, Oct 9"
                    fullFormat = res.getString(com.android.internal.R.string.wday_date);
                }
            } else {
                if (showTime) {
                    // Example: "10:00 - 11:00 am, Oct 9"
                    fullFormat = res.getString(com.android.internal.R.string.time_date);
                } else {
                    // Example: "Oct 9"
                    return dateString;
                }
            }
        } else if (showWeekDay) {
            if (showTime) {
                // Example: "10:00 - 11:00 am, Tue"
                fullFormat = res.getString(com.android.internal.R.string.time_wday);
            } else {
                // Example: "Tue"
                return startWeekDayString;
            }
        } else if (showTime) {
            return timeString;
        }

        // The values that are used in a fullFormat string are specified
        // by position.
        dateRange = String.format(fullFormat, timeString, startWeekDayString, dateString);
        return dateRange;
public static java.lang.StringformatDateTime(android.content.Context context, long millis, int flags)
Formats a date or a time according to the local conventions. There are lots of options that allow the caller to control, for example, if the time is shown, if the day of the week is shown, if the month name is abbreviated, if noon is shown instead of 12pm, and so on. For the complete list of options, see the documentation for {@link #formatDateRange}.

Example output strings (date formats in these examples are shown using the US date format convention but that may change depending on the local settings):

  • 10:15am
  • 3:00pm
  • 3pm
  • 3PM
  • 08:00
  • 17:00
  • noon
  • Noon
  • midnight
  • Midnight
  • Oct 31
  • Oct 31, 2007
  • October 31, 2007
  • 10am, Oct 31
  • 17:00, Oct 31
  • Wed
  • Wednesday
  • 10am, Wed, Oct 31
  • Wed, Oct 31
  • Wednesday, Oct 31
  • Wed, Oct 31, 2007
  • Wed, October 31
  • 10/31/2007

param
context the context is required only if the time is shown
param
millis a point in time in UTC milliseconds
param
flags a bit mask of formatting options
return
a string containing the formatted date/time.

        return formatDateRange(context, millis, millis, flags);
public static java.lang.StringformatElapsedTime(long elapsedSeconds)
Formats an elapsed time in the form "MM:SS" or "H:MM:SS" for display on the call-in-progress screen.

param
elapsedSeconds the elapsed time in seconds.

        return formatElapsedTime(null, elapsedSeconds);
public static java.lang.StringformatElapsedTime(java.lang.StringBuilder recycle, long elapsedSeconds)
Formats an elapsed time in the form "MM:SS" or "H:MM:SS" for display on the call-in-progress screen.

param
recycle {@link StringBuilder} to recycle, if possible
param
elapsedSeconds the elapsed time in seconds.

        initFormatStrings();

        long hours = 0;
        long minutes = 0;
        long seconds = 0;

        if (elapsedSeconds >= 3600) {
            hours = elapsedSeconds / 3600;
            elapsedSeconds -= hours * 3600;
        }
        if (elapsedSeconds >= 60) {
            minutes = elapsedSeconds / 60;
            elapsedSeconds -= minutes * 60;
        }
        seconds = elapsedSeconds;

        String result;
        if (hours > 0) {
            return formatElapsedTime(recycle, sElapsedFormatHMMSS, hours, minutes, seconds);
        } else {
            return formatElapsedTime(recycle, sElapsedFormatMMSS, minutes, seconds);
        }
private static java.lang.StringformatElapsedTime(java.lang.StringBuilder recycle, java.lang.String format, long hours, long minutes, long seconds)
Fast formatting of h:mm:ss

        if (FAST_FORMAT_HMMSS.equals(format)) {
            StringBuilder sb = recycle;
            if (sb == null) {
                sb = new StringBuilder(8);
            } else {
                sb.setLength(0);
            }
            sb.append(hours);
            sb.append(TIME_SEPARATOR);
            if (minutes < 10) { 
                sb.append(TIME_PADDING);
            } else {
                sb.append(toDigitChar(minutes / 10));
            }
            sb.append(toDigitChar(minutes % 10));
            sb.append(TIME_SEPARATOR);
            if (seconds < 10) {
                sb.append(TIME_PADDING);
            } else {
                sb.append(toDigitChar(seconds / 10));
            }
            sb.append(toDigitChar(seconds % 10));
            return sb.toString();
        } else {
            return String.format(format, hours, minutes, seconds);
        }
private static java.lang.StringformatElapsedTime(java.lang.StringBuilder recycle, java.lang.String format, long minutes, long seconds)
Fast formatting of m:ss

        if (FAST_FORMAT_MMSS.equals(format)) {
            StringBuilder sb = recycle;
            if (sb == null) {
                sb = new StringBuilder(8);
            } else {
                sb.setLength(0);
            }
            if (minutes < 10) { 
                sb.append(TIME_PADDING);
            } else {
                sb.append(toDigitChar(minutes / 10));
            }
            sb.append(toDigitChar(minutes % 10));
            sb.append(TIME_SEPARATOR);
            if (seconds < 10) {
                sb.append(TIME_PADDING);
            } else {
                sb.append(toDigitChar(seconds / 10));
            }
            sb.append(toDigitChar(seconds % 10));
            return sb.toString();
        } else {
            return String.format(format, minutes, seconds);
        }
public static final java.lang.CharSequenceformatSameDayTime(long then, long now, int dateStyle, int timeStyle)
Format a date / time such that if the then is on the same day as now, it shows just the time and if it's a different day, it shows just the date.

The parameters dateFormat and timeFormat should each be one of {@link java.text.DateFormat#DEFAULT}, {@link java.text.DateFormat#FULL}, {@link java.text.DateFormat#LONG}, {@link java.text.DateFormat#MEDIUM} or {@link java.text.DateFormat#SHORT}

param
then the date to format
param
now the base time
param
dateStyle how to format the date portion.
param
timeStyle how to format the time portion.

        Calendar thenCal = new GregorianCalendar();
        thenCal.setTimeInMillis(then);
        Date thenDate = thenCal.getTime();
        Calendar nowCal = new GregorianCalendar();
        nowCal.setTimeInMillis(now);

        java.text.DateFormat f;

        if (thenCal.get(Calendar.YEAR) == nowCal.get(Calendar.YEAR)
                && thenCal.get(Calendar.MONTH) == nowCal.get(Calendar.MONTH)
                && thenCal.get(Calendar.DAY_OF_MONTH) == nowCal.get(Calendar.DAY_OF_MONTH)) {
            f = java.text.DateFormat.getTimeInstance(timeStyle);
        } else {
            f = java.text.DateFormat.getDateInstance(dateStyle);
        }
        return f.format(thenDate);
public static java.lang.StringgetAMPMString(int ampm)
Return a localized string for AM or PM.

param
ampm Either {@link Calendar#AM Calendar.AM} or {@link Calendar#PM Calendar.PM}.
throws
IndexOutOfBoundsException if the ampm is out of bounds.
return
Localized version of "AM" or "PM".

        Resources r = Resources.getSystem();
        return r.getString(sAmPm[ampm - Calendar.AM]);
public static java.lang.StringgetDayOfWeekString(int dayOfWeek, int abbrev)
Return a string for the day of the week.

param
dayOfWeek One of {@link Calendar#SUNDAY Calendar.SUNDAY}, {@link Calendar#MONDAY Calendar.MONDAY}, etc.
param
abbrev One of {@link #LENGTH_LONG}, {@link #LENGTH_SHORT}, {@link #LENGTH_SHORTER} or {@link #LENGTH_SHORTEST}. For forward compatibility, anything else will return the same as {#LENGTH_MEDIUM}.
throws
IndexOutOfBoundsException if the dayOfWeek is out of bounds.


                                                                                                         
           
        int[] list;
        switch (abbrev) {
            case LENGTH_LONG:       list = sDaysLong;       break;
            case LENGTH_MEDIUM:     list = sDaysMedium;     break;
            case LENGTH_SHORT:      list = sDaysShort;      break;
            case LENGTH_SHORTER:    list = sDaysShorter;    break;
            case LENGTH_SHORTEST:   list = sDaysShortest;   break;
            default:                list = sDaysMedium;     break;
        }

        Resources r = Resources.getSystem();
        return r.getString(list[dayOfWeek - Calendar.SUNDAY]);
public static java.lang.StringgetMonthString(int month, int abbrev)
Return a localized string for the day of the week.

param
month One of {@link Calendar#JANUARY Calendar.JANUARY}, {@link Calendar#FEBRUARY Calendar.FEBRUARY}, etc.
param
abbrev One of {@link #LENGTH_LONG}, {@link #LENGTH_SHORT}, {@link #LENGTH_SHORTER} or {@link #LENGTH_SHORTEST}. For forward compatibility, anything else will return the same as {#LENGTH_MEDIUM}.
return
Localized day of the week.

        // Note that here we use sMonthsMedium for MEDIUM, SHORT and SHORTER. 
        // This is a shortcut to not spam the translators with too many variations
        // of the same string.  If we find that in a language the distinction
        // is necessary, we can can add more without changing this API.
        int[] list;
        switch (abbrev) {
            case LENGTH_LONG:       list = sMonthsLong;     break;
            case LENGTH_MEDIUM:     list = sMonthsMedium;   break;
            case LENGTH_SHORT:      list = sMonthsMedium;   break;
            case LENGTH_SHORTER:    list = sMonthsMedium;   break;
            case LENGTH_SHORTEST:   list = sMonthsShortest; break;
            default:                list = sMonthsMedium;   break;
        }

        Resources r = Resources.getSystem();
        return r.getString(list[month - Calendar.JANUARY]);
public static java.lang.CharSequencegetRelativeDateTimeString(android.content.Context c, long time, long minResolution, long transitionResolution, int flags)
Return string describing the elapsed time since startTime formatted like "[relative time/date], [time]".

Example output strings for the US date format.

  • 3 mins ago, 10:15 AM
  • yesterday, 12:20 PM
  • Dec 12, 4:12 AM
  • 11/14/2007, 8:20 AM

param
time some time in the past.
param
minResolution the minimum elapsed time (in milliseconds) to report when showing relative times. For example, a time 3 seconds in the past will be reported as "0 minutes ago" if this is set to {@link #MINUTE_IN_MILLIS}.
param
transitionResolution the elapsed time (in milliseconds) at which to stop reporting relative measurements. Elapsed times greater than this resolution will default to normal date formatting. For example, will transition from "6 days ago" to "Dec 12" when using {@link #WEEK_IN_MILLIS}.

        Resources r = Resources.getSystem();

        long now = System.currentTimeMillis();
        long duration = Math.abs(now - time);

        // getRelativeTimeSpanString() doesn't correctly format relative dates
        // above a week or exact dates below a day, so clamp
        // transitionResolution as needed.
        if (transitionResolution > WEEK_IN_MILLIS) {
            transitionResolution = WEEK_IN_MILLIS;
        } else if (transitionResolution < DAY_IN_MILLIS) {
            transitionResolution = DAY_IN_MILLIS;
        }

        CharSequence timeClause = formatDateRange(c, time, time, FORMAT_SHOW_TIME);
        
        String result;
        if (duration < transitionResolution) {
            CharSequence relativeClause = getRelativeTimeSpanString(time, now, minResolution, flags);
            result = r.getString(com.android.internal.R.string.relative_time, relativeClause, timeClause);
        } else {
            CharSequence dateClause = getRelativeTimeSpanString(c, time, false);
            result = r.getString(com.android.internal.R.string.date_time, dateClause, timeClause);
        }

        return result;
private static final java.lang.StringgetRelativeDayString(android.content.res.Resources r, long day, long today)
Returns a string describing a day relative to the current day. For example if the day is today this function returns "Today", if the day was a week ago it returns "7 days ago", and if the day is in 2 weeks it returns "in 14 days".

param
r the resources to get the strings from
param
day the relative day to describe in UTC milliseconds
param
today the current time in UTC milliseconds
return
a formatting string

        Time startTime = new Time();
        startTime.set(day);
        Time currentTime = new Time();
        currentTime.set(today);

        int startDay = Time.getJulianDay(day, startTime.gmtoff);
        int currentDay = Time.getJulianDay(today, currentTime.gmtoff);

        int days = Math.abs(currentDay - startDay);
        boolean past = (today > day);
        
        if (days == 1) {
            if (past) {
                return r.getString(com.android.internal.R.string.yesterday);
            } else {
                return r.getString(com.android.internal.R.string.tomorrow);
            }
        } else if (days == 0) {
            return r.getString(com.android.internal.R.string.today);
        }

        int resId;
        if (past) {
            resId = com.android.internal.R.plurals.num_days_ago;
        } else {
            resId = com.android.internal.R.plurals.in_num_days;
        }
        
        String format = r.getQuantityString(resId, days);
        return String.format(format, days);
public static java.lang.CharSequencegetRelativeTimeSpanString(android.content.Context c, long millis, boolean withPreposition)

return
a relative time string to display the time expressed by millis. Times are counted starting at midnight, which means that assuming that the current time is March 31st, 0:30:
  • "millis=0:10 today" will be displayed as "0:10"
  • "millis=11:30pm the day before" will be displayed as "Mar 30"
If the given millis is in a different year, then the full date is returned in numeric format (e.g., "10/12/2008").
param
withPreposition If true, the string returned will include the correct preposition ("at 9:20am", "on 10/12/2008" or "on May 29").


        long now = System.currentTimeMillis();
        long span = now - millis;

        if (sNowTime == null) {
            sNowTime = new Time();
            sThenTime = new Time();
        }

        sNowTime.set(now);
        sThenTime.set(millis);

        String result;
        int prepositionId;
        if (span < DAY_IN_MILLIS && sNowTime.weekDay == sThenTime.weekDay) {
            // Same day
            int flags = FORMAT_SHOW_TIME;
            result = formatDateRange(c, millis, millis, flags);
            prepositionId = R.string.preposition_for_time;
        } else if (sNowTime.year != sThenTime.year) {
            // Different years
            int flags = FORMAT_SHOW_DATE | FORMAT_SHOW_YEAR | FORMAT_NUMERIC_DATE;
            result = formatDateRange(c, millis, millis, flags);

            // This is a date (like "10/31/2008" so use the date preposition)
            prepositionId = R.string.preposition_for_date;
        } else {
            // Default
            int flags = FORMAT_SHOW_DATE | FORMAT_ABBREV_MONTH;
            result = formatDateRange(c, millis, millis, flags);
            prepositionId = R.string.preposition_for_date;
        }
        if (withPreposition) {
            Resources res = c.getResources();
            result = res.getString(prepositionId, result);
        }
        return result;
public static java.lang.CharSequencegetRelativeTimeSpanString(android.content.Context c, long millis)
Convenience function to return relative time string without preposition.

param
c context for resources
param
millis time in milliseconds
return
{@link CharSequence} containing relative time.
see
#getRelativeTimeSpanString(Context, long, boolean)

        return getRelativeTimeSpanString(c, millis, false /* no preposition */);
public static java.lang.CharSequencegetRelativeTimeSpanString(long startTime)
Returns a string describing the elapsed time since startTime.

param
startTime some time in the past.
return
a String object containing the elapsed time.
see
#getRelativeTimeSpanString(long, long, long)

        return getRelativeTimeSpanString(startTime, System.currentTimeMillis(), MINUTE_IN_MILLIS);
public static java.lang.CharSequencegetRelativeTimeSpanString(long time, long now, long minResolution)
Returns a string describing 'time' as a time relative to 'now'.

Time spans in the past are formatted like "42 minutes ago". Time spans in the future are formatted like "in 42 minutes".

param
time the time to describe, in milliseconds
param
now the current time in milliseconds
param
minResolution the minimum timespan to report. For example, a time 3 seconds in the past will be reported as "0 minutes ago" if this is set to MINUTE_IN_MILLIS. Pass one of 0, MINUTE_IN_MILLIS, HOUR_IN_MILLIS, DAY_IN_MILLIS, WEEK_IN_MILLIS

        int flags = FORMAT_SHOW_DATE | FORMAT_SHOW_YEAR | FORMAT_ABBREV_MONTH;
        return getRelativeTimeSpanString(time, now, minResolution, flags);
public static java.lang.CharSequencegetRelativeTimeSpanString(long time, long now, long minResolution, int flags)
Returns a string describing 'time' as a time relative to 'now'.

Time spans in the past are formatted like "42 minutes ago". Time spans in the future are formatted like "in 42 minutes".

Can use {@link #FORMAT_ABBREV_RELATIVE} flag to use abbreviated relative times, like "42 mins ago".

param
time the time to describe, in milliseconds
param
now the current time in milliseconds
param
minResolution the minimum timespan to report. For example, a time 3 seconds in the past will be reported as "0 minutes ago" if this is set to MINUTE_IN_MILLIS. Pass one of 0, MINUTE_IN_MILLIS, HOUR_IN_MILLIS, DAY_IN_MILLIS, WEEK_IN_MILLIS
param
flags a bit mask of formatting options, such as {@link #FORMAT_NUMERIC_DATE} or {@link #FORMAT_ABBREV_RELATIVE}

        Resources r = Resources.getSystem();
        boolean abbrevRelative = (flags & (FORMAT_ABBREV_RELATIVE | FORMAT_ABBREV_ALL)) != 0;
        
        boolean past = (now >= time);
        long duration = Math.abs(now - time);

        int resId;
        long count;
        if (duration < MINUTE_IN_MILLIS && minResolution < MINUTE_IN_MILLIS) {
            count = duration / SECOND_IN_MILLIS;
            if (past) {
                if (abbrevRelative) {
                    resId = com.android.internal.R.plurals.abbrev_num_seconds_ago;
                } else {
                    resId = com.android.internal.R.plurals.num_seconds_ago;
                }
            } else {
                if (abbrevRelative) {
                    resId = com.android.internal.R.plurals.abbrev_in_num_seconds;
                } else {
                    resId = com.android.internal.R.plurals.in_num_seconds;
                }
            }
        } else if (duration < HOUR_IN_MILLIS && minResolution < HOUR_IN_MILLIS) {
            count = duration / MINUTE_IN_MILLIS;
            if (past) {
                if (abbrevRelative) {
                    resId = com.android.internal.R.plurals.abbrev_num_minutes_ago;
                } else {
                    resId = com.android.internal.R.plurals.num_minutes_ago;
                }
            } else {
                if (abbrevRelative) {
                    resId = com.android.internal.R.plurals.abbrev_in_num_minutes;
                } else {
                    resId = com.android.internal.R.plurals.in_num_minutes;
                }
            }
        } else if (duration < DAY_IN_MILLIS && minResolution < DAY_IN_MILLIS) {
            count = duration / HOUR_IN_MILLIS;
            if (past) {
                if (abbrevRelative) {
                    resId = com.android.internal.R.plurals.abbrev_num_hours_ago;
                } else {
                    resId = com.android.internal.R.plurals.num_hours_ago;
                }
            } else {
                if (abbrevRelative) {
                    resId = com.android.internal.R.plurals.abbrev_in_num_hours;
                } else {
                    resId = com.android.internal.R.plurals.in_num_hours;
                }
            }
        } else if (duration < WEEK_IN_MILLIS && minResolution < WEEK_IN_MILLIS) {
            count = duration / DAY_IN_MILLIS;
            if (past) {
                if (abbrevRelative) {
                    resId = com.android.internal.R.plurals.abbrev_num_days_ago;
                } else {
                    resId = com.android.internal.R.plurals.num_days_ago;
                }
            } else {
                if (abbrevRelative) {
                    resId = com.android.internal.R.plurals.abbrev_in_num_days;
                } else {
                    resId = com.android.internal.R.plurals.in_num_days;
                }
            }
        } else {
            // We know that we won't be showing the time, so it is safe to pass
            // in a null context.
            return formatDateRange(null, time, time, flags);
        }

        String format = r.getQuantityString(resId, (int) count);
        return String.format(format, count);
private static voidinitFormatStrings()

        synchronized (sLock) {
            Resources r = Resources.getSystem();
            Configuration cfg = r.getConfiguration();
            if (sLastConfig == null || !sLastConfig.equals(cfg)) {
                sLastConfig = cfg;
                sStatusTimeFormat = r.getString(com.android.internal.R.string.status_bar_time_format);
                sElapsedFormatMMSS = r.getString(com.android.internal.R.string.elapsed_time_short_format_mm_ss);
                sElapsedFormatHMMSS = r.getString(com.android.internal.R.string.elapsed_time_short_format_h_mm_ss);
            }
        }
public static booleanisToday(long when)

return
true if the supplied when is today else false

        Time time = new Time();
        time.set(when);
        
        int thenYear = time.year;
        int thenMonth = time.month;
        int thenMonthDay = time.monthDay;

        time.set(System.currentTimeMillis());
        return (thenYear == time.year)
                && (thenMonth == time.month) 
                && (thenMonthDay == time.monthDay);
public static booleanisUTC(java.lang.String s)

hide
deprecated
use {@link android.text.format.Time} Return true if this date string is local time

        if (s.length() == 16 && s.charAt(15) == 'Z") {
            return true;
        }
        if (s.length() == 9 && s.charAt(8) == 'Z") {
            // XXX not sure if this case possible/valid
            return true;
        }
        return false;
public static java.util.CalendarnewCalendar(boolean zulu)

hide
deprecated
use {@link android.text.format.Time}

        if (zulu)
            return Calendar.getInstance(TimeZone.getTimeZone("GMT"));

        return Calendar.getInstance();
public static booleanparseDateTime(java.lang.String str, java.util.Calendar cal)

hide
deprecated
use {@link android.text.format.Time}

        int len = str.length();
        boolean dateTime = (len == 15 || len == 16) && str.charAt(8) == 'T";
        boolean justDate = len == 8;
        if (dateTime || justDate) {
            cal.clear();
            cal.set(Calendar.YEAR, 
                            ctoi(str, 0)*1000 + ctoi(str, 1)*100
                            + ctoi(str, 2)*10 + ctoi(str, 3));
            cal.set(Calendar.MONTH,
                            check(0, 11, ctoi(str, 4)*10 + ctoi(str, 5) - 1));
            cal.set(Calendar.DAY_OF_MONTH,
                            check(1, 31, ctoi(str, 6)*10 + ctoi(str, 7)));
            if (dateTime) {
                cal.set(Calendar.HOUR_OF_DAY,
                            check(0, 23, ctoi(str, 9)*10 + ctoi(str, 10)));
                cal.set(Calendar.MINUTE,
                            check(0, 59, ctoi(str, 11)*10 + ctoi(str, 12)));
                cal.set(Calendar.SECOND,
                            check(0, 59, ctoi(str, 13)*10 + ctoi(str, 14)));
            }
            if (justDate) {
                cal.set(Calendar.HOUR_OF_DAY, 0);
                cal.set(Calendar.MINUTE, 0);
                cal.set(Calendar.SECOND, 0);
                return true;
            }
            if (len == 15) {
                return false;
            }
            if (str.charAt(15) == 'Z") {
                return true;
            }
        }
        throw new DateException("Invalid time (expected "
                                + "YYYYMMDDThhmmssZ? got '" + str + "').");
public static voidparseDateTime(java.lang.String tz, java.lang.String dateTime, java.util.Calendar out)
Given a timezone string which can be null, and a dateTime string, set that time into a calendar.

hide
deprecated
use {@link android.text.format.Time}

        TimeZone timezone;
        if (DateUtils.isUTC(dateTime)) {
            timezone = TimeZone.getTimeZone("UTC");
        }
        else if (tz == null) {
            timezone = TimeZone.getDefault();
        }
        else {
            timezone = TimeZone.getTimeZone(tz);
        }

        Calendar local = new GregorianCalendar(timezone);
        DateUtils.parseDateTime(dateTime, local);

        out.setTimeInMillis(local.getTimeInMillis());
public static final java.lang.CharSequencetimeString(long millis)
Format a time so it appears like it would in the status bar clock.

deprecated
use {@link #DateFormat.getTimeFormat(Context)} instead.
hide

        initFormatStrings();
        return DateFormat.format(sStatusTimeFormat, millis);
private static chartoDigitChar(long digit)

        return (char) (digit + '0");
public static java.lang.StringwriteDateTime(java.util.Calendar cal)
Return a string containing the date and time in RFC2445 format. Ensures that the time is written in UTC. The Calendar class doesn't really help out with this, so this is slower than it ought to be.

param
cal the date and time to write
hide
deprecated
use {@link android.text.format.Time}

        TimeZone tz = TimeZone.getTimeZone("GMT");
        GregorianCalendar c = new GregorianCalendar(tz);
        c.setTimeInMillis(cal.getTimeInMillis());
        return writeDateTime(c, true);
public static java.lang.StringwriteDateTime(java.util.Calendar cal, boolean zulu)
Return a string containing the date and time in RFC2445 format.

param
cal the date and time to write
param
zulu If the calendar is in UTC, pass true, and a Z will be written at the end as per RFC2445. Otherwise, the time is considered in localtime.
hide
deprecated
use {@link android.text.format.Time}

        StringBuilder sb = new StringBuilder();
        sb.ensureCapacity(16);
        if (zulu) {
            sb.setLength(16);
            sb.setCharAt(15, 'Z");
        } else {
            sb.setLength(15);
        }
        return writeDateTime(cal, sb);
public static java.lang.StringwriteDateTime(java.util.Calendar cal, java.lang.StringBuilder sb)
Return a string containing the date and time in RFC2445 format.

param
cal the date and time to write
param
sb a StringBuilder to use. It is assumed that setLength has already been called on sb to the appropriate length which is sb.setLength(zulu ? 16 : 15)
hide
deprecated
use {@link android.text.format.Time}

        int n;
       
        n = cal.get(Calendar.YEAR);
        sb.setCharAt(3, (char)('0"+n%10));
        n /= 10;
        sb.setCharAt(2, (char)('0"+n%10));
        n /= 10;
        sb.setCharAt(1, (char)('0"+n%10));
        n /= 10;
        sb.setCharAt(0, (char)('0"+n%10));

        n = cal.get(Calendar.MONTH) + 1;
        sb.setCharAt(5, (char)('0"+n%10));
        n /= 10;
        sb.setCharAt(4, (char)('0"+n%10));

        n = cal.get(Calendar.DAY_OF_MONTH);
        sb.setCharAt(7, (char)('0"+n%10));
        n /= 10;
        sb.setCharAt(6, (char)('0"+n%10));

        sb.setCharAt(8, 'T");

        n = cal.get(Calendar.HOUR_OF_DAY);
        sb.setCharAt(10, (char)('0"+n%10));
        n /= 10;
        sb.setCharAt(9, (char)('0"+n%10));

        n = cal.get(Calendar.MINUTE);
        sb.setCharAt(12, (char)('0"+n%10));
        n /= 10;
        sb.setCharAt(11, (char)('0"+n%10));

        n = cal.get(Calendar.SECOND);
        sb.setCharAt(14, (char)('0"+n%10));
        n /= 10;
        sb.setCharAt(13, (char)('0"+n%10));

        return sb.toString();