android.text.format
Class DateUtils

java.lang.Object
  android.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.

Field Summary

static String	ABBREV_MONTH_FORMAT
static String	ABBREV_WEEKDAY_FORMAT
static long	DAY_IN_MILLIS
static int	FORMAT_12HOUR
static int	FORMAT_24HOUR
static int	FORMAT_ABBREV_ALL
static int	FORMAT_ABBREV_MONTH
static int	FORMAT_ABBREV_RELATIVE
static int	FORMAT_ABBREV_TIME
static int	FORMAT_ABBREV_WEEKDAY
static int	FORMAT_CAP_AMPM
static int	FORMAT_CAP_MIDNIGHT
static int	FORMAT_CAP_NOON
static int	FORMAT_CAP_NOON_MIDNIGHT
static int	FORMAT_NO_MIDNIGHT
static int	FORMAT_NO_MONTH_DAY
static int	FORMAT_NO_NOON
static int	FORMAT_NO_NOON_MIDNIGHT
static int	FORMAT_NO_YEAR
static int	FORMAT_NUMERIC_DATE
static int	FORMAT_SHOW_DATE
static int	FORMAT_SHOW_TIME
static int	FORMAT_SHOW_WEEKDAY
static int	FORMAT_SHOW_YEAR
static int	FORMAT_UTC
static long	HOUR_IN_MILLIS
static String	HOUR_MINUTE_24
static int	LENGTH_LONG Request the full spelled-out name.
static int	LENGTH_MEDIUM Request an abbreviated version of the name.
static int	LENGTH_SHORT Request a shorter abbreviated version of the name.
static int	LENGTH_SHORTER Request an even shorter abbreviated version of the name.
static int	LENGTH_SHORTEST Request an even shorter abbreviated version of the name.
static long	MINUTE_IN_MILLIS
static String	MONTH_DAY_FORMAT
static String	MONTH_FORMAT
static String	NUMERIC_MONTH_FORMAT
static int[]	sameMonthTable
static int[]	sameYearTable
static long	SECOND_IN_MILLIS
static long	WEEK_IN_MILLIS
static String	WEEKDAY_FORMAT
static String	YEAR_FORMAT
static String	YEAR_FORMAT_TWO_DIGITS
static long	YEAR_IN_MILLIS

Constructor Summary

DateUtils()

Method Summary

static void	assign(Calendar lval, Calendar rval) Deprecated. use Time
static String	formatDateRange(Context context, long startMillis, long endMillis, int flags) Formats a date or a time range according to the local conventions.
static String	formatDateTime(Context context, long millis, int flags) Formats a date or a time according to the local conventions.
static String	formatElapsedTime(long elapsedSeconds) Formats an elapsed time in the form "MM:SS" or "H:MM:SS" for display on the call-in-progress screen.
static CharSequence	formatSameDayTime(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.
static String	getAMPMString(int ampm) Return a localized string for AM or PM.
static String	getDayOfWeekString(int dayOfWeek, int abbrev) Return a string for the day of the week.
static String	getMonthString(int month, int abbrev) Return a localized string for the day of the week.
static CharSequence	getRelativeDateTimeString(Context c, long time, long minResolution, long transitionResolution, int flags) Return string describing the elapsed time since startTime formatted like "[relative time/date], [time]".
static CharSequence	getRelativeTimeSpanString(Context c, long millis) Convenience function to return relative time string without preposition.
static CharSequence	getRelativeTimeSpanString(Context c, long millis, boolean withPreposition)
static CharSequence	getRelativeTimeSpanString(long startTime) Returns a string describing the elapsed time since startTime.
static CharSequence	getRelativeTimeSpanString(long time, long now, long minResolution) Returns a string describing 'time' as a time relative to 'now'.
static CharSequence	getRelativeTimeSpanString(long time, long now, long minResolution, int flags) Returns a string describing 'time' as a time relative to 'now'.
static boolean	isToday(long when)
static boolean	isUTC(String s) Deprecated. use Time Return true if this date string is local time
static Calendar	newCalendar(boolean zulu) Deprecated. use Time
static boolean	parseDateTime(String str, Calendar cal) Deprecated. use Time
static void	parseDateTime(String tz, String dateTime, Calendar out) Deprecated. use Time
static CharSequence	timeString(long millis) Deprecated. use #DateFormat.getTimeFormat(Context) instead.
static String	writeDateTime(Calendar cal) Deprecated. use Time
static String	writeDateTime(Calendar cal, boolean zulu) Deprecated. use Time
static String	writeDateTime(Calendar cal, StringBuilder sb) Deprecated. use Time

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SECOND_IN_MILLIS

public static final long SECOND_IN_MILLIS

See Also:

Constant Field Values

MINUTE_IN_MILLIS

public static final long MINUTE_IN_MILLIS

See Also:

Constant Field Values

HOUR_IN_MILLIS

public static final long HOUR_IN_MILLIS

See Also:

Constant Field Values

DAY_IN_MILLIS

public static final long DAY_IN_MILLIS

See Also:

Constant Field Values

WEEK_IN_MILLIS

public static final long WEEK_IN_MILLIS

See Also:

Constant Field Values

YEAR_IN_MILLIS

public static final long YEAR_IN_MILLIS

See Also:

Constant Field Values

FORMAT_SHOW_TIME

public static final int FORMAT_SHOW_TIME

See Also:

Constant Field Values

FORMAT_SHOW_WEEKDAY

public static final int FORMAT_SHOW_WEEKDAY

See Also:

Constant Field Values

FORMAT_SHOW_YEAR

public static final int FORMAT_SHOW_YEAR

See Also:

Constant Field Values

FORMAT_NO_YEAR

public static final int FORMAT_NO_YEAR

See Also:

Constant Field Values

FORMAT_SHOW_DATE

public static final int FORMAT_SHOW_DATE

See Also:

Constant Field Values

FORMAT_NO_MONTH_DAY

public static final int FORMAT_NO_MONTH_DAY

See Also:

Constant Field Values

FORMAT_12HOUR

public static final int FORMAT_12HOUR

See Also:

Constant Field Values

FORMAT_24HOUR

public static final int FORMAT_24HOUR

See Also:

Constant Field Values

FORMAT_CAP_AMPM

public static final int FORMAT_CAP_AMPM

See Also:

Constant Field Values

FORMAT_NO_NOON

public static final int FORMAT_NO_NOON

See Also:

Constant Field Values

FORMAT_CAP_NOON

public static final int FORMAT_CAP_NOON

See Also:

Constant Field Values

FORMAT_NO_MIDNIGHT

public static final int FORMAT_NO_MIDNIGHT

See Also:

Constant Field Values

FORMAT_CAP_MIDNIGHT

public static final int FORMAT_CAP_MIDNIGHT

See Also:

Constant Field Values

FORMAT_UTC

public static final int FORMAT_UTC

See Also:

Constant Field Values

FORMAT_ABBREV_TIME

public static final int FORMAT_ABBREV_TIME

See Also:

Constant Field Values

FORMAT_ABBREV_WEEKDAY

public static final int FORMAT_ABBREV_WEEKDAY

See Also:

Constant Field Values

FORMAT_ABBREV_MONTH

public static final int FORMAT_ABBREV_MONTH

See Also:

Constant Field Values

FORMAT_NUMERIC_DATE

public static final int FORMAT_NUMERIC_DATE

See Also:

Constant Field Values

FORMAT_ABBREV_RELATIVE

public static final int FORMAT_ABBREV_RELATIVE

See Also:

Constant Field Values

FORMAT_ABBREV_ALL

public static final int FORMAT_ABBREV_ALL

See Also:

Constant Field Values

FORMAT_CAP_NOON_MIDNIGHT

public static final int FORMAT_CAP_NOON_MIDNIGHT

See Also:

Constant Field Values

FORMAT_NO_NOON_MIDNIGHT

public static final int FORMAT_NO_NOON_MIDNIGHT

See Also:

Constant Field Values

HOUR_MINUTE_24

public static final String HOUR_MINUTE_24

See Also:

Constant Field Values

MONTH_FORMAT

public static final String MONTH_FORMAT

See Also:

Constant Field Values

ABBREV_MONTH_FORMAT

public static final String ABBREV_MONTH_FORMAT

See Also:

Constant Field Values

NUMERIC_MONTH_FORMAT

public static final String NUMERIC_MONTH_FORMAT

See Also:

Constant Field Values

MONTH_DAY_FORMAT

public static final String MONTH_DAY_FORMAT

See Also:

Constant Field Values

YEAR_FORMAT

public static final String YEAR_FORMAT

See Also:

Constant Field Values

YEAR_FORMAT_TWO_DIGITS

public static final String YEAR_FORMAT_TWO_DIGITS

See Also:

Constant Field Values

WEEKDAY_FORMAT

public static final String WEEKDAY_FORMAT

See Also:

Constant Field Values

ABBREV_WEEKDAY_FORMAT

public static final String ABBREV_WEEKDAY_FORMAT

See Also:

Constant Field Values

sameYearTable

public static final int[] sameYearTable

sameMonthTable

public static final int[] sameMonthTable

LENGTH_LONG

public static final int LENGTH_LONG

Request the full spelled-out name. For use with the 'abbrev' parameter of getDayOfWeekString(int, int) and getMonthString(int, int).

See Also:

Constant Field Values

LENGTH_MEDIUM

public static final int LENGTH_MEDIUM

Request an abbreviated version of the name. For use with the 'abbrev' parameter of getDayOfWeekString(int, int) and getMonthString(int, int).

See Also:

Constant Field Values

LENGTH_SHORT

public static final int LENGTH_SHORT

Request a shorter abbreviated version of the name. For use with the 'abbrev' parameter of getDayOfWeekString(int, int) and getMonthString(int, int).

See Also:

Constant Field Values

LENGTH_SHORTER

public static final int LENGTH_SHORTER

Request an even shorter abbreviated version of the name. For use with the 'abbrev' parameter of getDayOfWeekString(int, int) and getMonthString(int, int).

See Also:

Constant Field Values

LENGTH_SHORTEST

public static final int LENGTH_SHORTEST

Request an even shorter abbreviated version of the name. For use with the 'abbrev' parameter of getDayOfWeekString(int, int) and getMonthString(int, int).

See Also:

Constant Field Values

Constructor Detail

DateUtils

public DateUtils()

Method Detail

getDayOfWeekString

public static String getDayOfWeekString(int dayOfWeek,
                                        int abbrev)

Return a string for the day of the week.

Parameters:

dayOfWeek - One of Calendar.SUNDAY, Calendar.MONDAY, etc.

abbrev - One of LENGTH_LONG, LENGTH_SHORT, LENGTH_SHORTER or LENGTH_SHORTEST. For forward compatibility, anything else will return the same as {#LENGTH_MEDIUM}.

Throws:

IndexOutOfBoundsException - if the dayOfWeek is out of bounds.

getAMPMString

public static String getAMPMString(int ampm)

Return a localized string for AM or PM.

Parameters:

ampm - Either Calendar.AM or Calendar.PM.

Returns:

Localized version of "AM" or "PM".

Throws:

IndexOutOfBoundsException - if the ampm is out of bounds.

getMonthString

public static String getMonthString(int month,
                                    int abbrev)

Return a localized string for the day of the week.

Parameters:

month - One of Calendar.JANUARY, Calendar.FEBRUARY, etc.

abbrev - One of LENGTH_LONG, LENGTH_SHORT, LENGTH_SHORTER or LENGTH_SHORTEST. For forward compatibility, anything else will return the same as {#LENGTH_MEDIUM}.

Returns:

Localized day of the week.

getRelativeTimeSpanString

public static CharSequence getRelativeTimeSpanString(long startTime)

Returns a string describing the elapsed time since startTime.

Parameters:

startTime - some time in the past.

Returns:

a String object containing the elapsed time.

See Also:

getRelativeTimeSpanString(long, long, long)

getRelativeTimeSpanString

public static CharSequence getRelativeTimeSpanString(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".

Parameters:

time - the time to describe, in milliseconds

now - the current time in milliseconds

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

getRelativeTimeSpanString

public static CharSequence getRelativeTimeSpanString(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 FORMAT_ABBREV_RELATIVE flag to use abbreviated relative times, like "42 mins ago".

Parameters:

time - the time to describe, in milliseconds

now - the current time in milliseconds

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

flags - a bit mask of formatting options, such as FORMAT_NUMERIC_DATE or FORMAT_ABBREV_RELATIVE

getRelativeDateTimeString

public static CharSequence getRelativeDateTimeString(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

Parameters:

time - some time in the past.

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

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

timeString

public static final CharSequence timeString(long millis)

Deprecated. use #DateFormat.getTimeFormat(Context) instead.

Format a time so it appears like it would in the status bar clock.

formatElapsedTime

public static String formatElapsedTime(long elapsedSeconds)

Formats an elapsed time in the form "MM:SS" or "H:MM:SS" for display on the call-in-progress screen.

Parameters:

elapsedSeconds - the elapsed time in seconds.

formatSameDayTime

public static final CharSequence formatSameDayTime(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 DateFormat.DEFAULT, DateFormat.FULL, DateFormat.LONG, DateFormat.MEDIUM or DateFormat.SHORT

Parameters:

then - the date to format

now - the base time

dateStyle - how to format the date portion.

timeStyle - how to format the time portion.

newCalendar

public static Calendar newCalendar(boolean zulu)

Deprecated. use Time

isToday

public static boolean isToday(long when)

Returns:

true if the supplied when is today else false

isUTC

public static boolean isUTC(String s)

Deprecated. use Time Return true if this date string is local time

parseDateTime

public static boolean parseDateTime(String str,
                                    Calendar cal)
                             throws DateException

Deprecated. use Time

Throws:

DateException

parseDateTime

public static void parseDateTime(String tz,
                                 String dateTime,
                                 Calendar out)
                          throws DateException

Deprecated. use Time

Given a timezone string which can be null, and a dateTime string, set that time into a calendar.

Throws:

DateException

writeDateTime

public static String writeDateTime(Calendar cal)

Deprecated. use Time

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.

Parameters:

cal - the date and time to write

writeDateTime

public static String writeDateTime(Calendar cal,
                                   boolean zulu)

Deprecated. use Time

Return a string containing the date and time in RFC2445 format.

Parameters:

cal - the date and time to write

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.

writeDateTime

public static String writeDateTime(Calendar cal,
                                   StringBuilder sb)

Deprecated. use Time

Return a string containing the date and time in RFC2445 format.

Parameters:

cal - the date and time to write

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)

assign

public static void assign(Calendar lval,
                          Calendar rval)

Deprecated. use Time

formatDateRange

public static String formatDateRange(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.

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

Parameters:

context - the context is required only if the time is shown

startMillis - the start time in UTC milliseconds

endMillis - the end time in UTC milliseconds

flags - a bit mask of options

Returns:

a string containing the formatted date/time range.

formatDateTime

public static String formatDateTime(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 formatDateRange(android.content.Context, long, long, int).

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

Parameters:

context - the context is required only if the time is shown

millis - a point in time in UTC milliseconds

flags - a bit mask of formatting options

Returns:

a string containing the formatted date/time.

getRelativeTimeSpanString

public static CharSequence getRelativeTimeSpanString(Context c,
                                                     long millis,
                                                     boolean withPreposition)

Parameters:

withPreposition - If true, the string returned will include the correct preposition ("at 9:20am", "on 10/12/2008" or "on May 29").

Returns:

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

getRelativeTimeSpanString

public static CharSequence getRelativeTimeSpanString(Context c,
                                                     long millis)

Convenience function to return relative time string without preposition.

Parameters:

c - context for resources

millis - time in milliseconds

Returns:

CharSequence containing relative time.

See Also:

getRelativeTimeSpanString(Context, long, boolean)