public
class
DateUtils
extends Object
| java.lang.Object | |
| ↳ | android.text.format.DateUtils |
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 | |
|---|---|
public
static
final
int[] |
sameMonthTable
This field was deprecated in API level 17. Do not use. |
public
static
final
int[] |
sameYearTable
This field was deprecated in API level 17. Do not use. |
Public constructors | |
|---|---|
DateUtils()
|
|
Public methods | |
|---|---|
static
Formatter
|
formatDateRange(Context context, Formatter formatter, long startMillis, long endMillis, int flags, String timeZone)
Formats a date or a time range according to the local conventions. |
static
Formatter
|
formatDateRange(Context context, Formatter formatter, long startMillis, long endMillis, int flags)
Formats a date or a time range according to the local conventions. |
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(StringBuilder recycle, long elapsedSeconds)
Formats an elapsed time in a format like "MM:SS" or "H:MM:SS" (using a form suited to the current locale), similar to that used on the call-in-progress screen. |
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
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. |
static
String
|
getAMPMString(int ampm)
This method was deprecated
in API level 17.
Use |
static
String
|
getDayOfWeekString(int dayOfWeek, int abbrev)
This method was deprecated
in API level 17.
Use |
static
String
|
getMonthString(int month, int abbrev)
This method was deprecated
in API level 17.
Use |
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, boolean withPreposition)
|
static
CharSequence
|
getRelativeTimeSpanString(long time, long now, long minResolution, int flags)
Returns a string describing 'time' as a time relative to 'now'. |
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(Context c, long millis)
Convenience function to return relative time string without preposition. |
static
boolean
|
isToday(long when)
|
Inherited methods | |
|---|---|
 From
class
java.lang.Object
| |
String ABBREV_MONTH_FORMAT
This constant was deprecated
in API level 17.
Use SimpleDateFormat instead.
This is not actually a useful month name in all locales.
Constant Value: "%b"
int FORMAT_ABBREV_RELATIVE
Constant Value: 262144 (0x00040000)
int FORMAT_ABBREV_WEEKDAY
Constant Value: 32768 (0x00008000)
int FORMAT_CAP_NOON_MIDNIGHT
Constant Value: 5120 (0x00001400)
int FORMAT_NO_NOON_MIDNIGHT
Constant Value: 2560 (0x00000a00)
int FORMAT_NUMERIC_DATE
Constant Value: 131072 (0x00020000)
int FORMAT_UTC
This constant was deprecated
in API level 9.
Use
formatDateRange
and pass in Time.TIMEZONE_UTC for the timeZone instead.
Constant Value: 8192 (0x00002000)
long HOUR_IN_MILLIS
Constant Value: 3600000 (0x000000000036ee80)
String HOUR_MINUTE_24
This constant was deprecated
in API level 17.
Use SimpleDateFormat instead.
This is not actually the preferred 24-hour date format in all locales.
Constant Value: "%H:%M"
int LENGTH_LONG
This constant was deprecated
in API level 17.
Use SimpleDateFormat instead.
Request the full spelled-out name. For use with the 'abbrev' parameter of
getDayOfWeekString(int, int) and getMonthString(int, int).
Constant Value: 10 (0x0000000a)
int LENGTH_MEDIUM
This constant was deprecated
in API level 17.
Use SimpleDateFormat instead.
Request an abbreviated version of the name. For use with the 'abbrev'
parameter of getDayOfWeekString(int, int) and getMonthString(int, int).
Constant Value: 20 (0x00000014)
int LENGTH_SHORT
This constant was deprecated
in API level 17.
Use SimpleDateFormat instead.
Request a shorter abbreviated version of the name.
For use with the 'abbrev' parameter of getDayOfWeekString(int, int) and getMonthString(int, int).
Constant Value: 30 (0x0000001e)
int LENGTH_SHORTER
This constant was deprecated
in API level 17.
Use SimpleDateFormat instead.
Request an even shorter abbreviated version of the name.
Do not use this. Currently this will always return the same result
as LENGTH_SHORT.
Constant Value: 40 (0x00000028)
int LENGTH_SHORTEST
This constant was deprecated
in API level 17.
Use SimpleDateFormat instead.
Request an even shorter abbreviated version of the name.
For use with the 'abbrev' parameter of getDayOfWeekString(int, int) and getMonthString(int, int).
Constant Value: 50 (0x00000032)
long MINUTE_IN_MILLIS
Constant Value: 60000 (0x000000000000ea60)
long SECOND_IN_MILLIS
Constant Value: 1000 (0x00000000000003e8)
long WEEK_IN_MILLIS
Constant Value: 604800000 (0x00000000240c8400)
long YEAR_IN_MILLIS
This constant is actually the length of 364 days, not of a year!
Constant Value: 31449600000 (0x00000007528ad000)
int[] sameMonthTable
This field was deprecated
in API level 17.
Do not use.
int[] sameYearTable
This field was deprecated
in API level 17.
Do not use.
Formatter formatDateRange (Context context, Formatter formatter, long startMillis, long endMillis, int flags, String timeZone)
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):
The flags argument is a bitmask of options from the following list:
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_SHOW_YEAR is not 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. You should not use this flag because in some locales these terms cannot be capitalized, and in many others it doesn't make sense to do so even though it is possible.
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". You should probably not use this flag because in many locales it will not make sense to capitalize the term.
If FORMAT_NO_MIDNIGHT is set and 12-hour time is used, then "12am" is shown instead of "midnight".
If FORMAT_CAP_MIDNIGHT is set and 12-hour time is used, then "Midnight" is shown instead of "midnight". You should probably not use this flag because in many locales it will not make sense to capitalize the term.
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 time zone is used for the start and end milliseconds unless a time zone is specified. If a time zone is specified it will be used regardless of the FORMAT_UTC flag.
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".
If the end date ends at 12:00am at the beginning of a day, it is formatted as the end of the previous day in two scenarios:
| Parameters | |
|---|---|
context |
Context:
the context is required only if the time is shown |
formatter |
Formatter:
the Formatter used for formatting the date range.
Note: be sure to call setLength(0) on StringBuilder passed to
the Formatter constructor unless you want the results to accumulate. |
startMillis |
long:
the start time in UTC milliseconds |
endMillis |
long:
the end time in UTC milliseconds |
flags |
int:
a bit mask of options |
timeZone |
String:
the time zone to compute the string in. Use null for local
or if the FORMAT_UTC flag is being used. |
| Returns | |
|---|---|
Formatter |
the formatter with the formatted date/time range appended to the string buffer. |
Formatter formatDateRange (Context context, Formatter formatter, long startMillis, long endMillis, int flags)
Formats a date or a time range according to the local conventions.
Note that this is a convenience method for formatting the date or
time range in the local time zone. If you want to specify the time
zone please use
formatDateRange.
| Parameters | |
|---|---|
context |
Context:
the context is required only if the time is shown |
formatter |
Formatter:
the Formatter used for formatting the date range.
Note: be sure to call setLength(0) on StringBuilder passed to
the Formatter constructor unless you want the results to accumulate. |
startMillis |
long:
the start time in UTC milliseconds |
endMillis |
long:
the end time in UTC milliseconds |
flags |
int:
a bit mask of options See
formatDateRange |
| Returns | |
|---|---|
Formatter |
a string containing the formatted date/time range. |
String formatDateRange (Context context, long startMillis, long endMillis, int flags)
Formats a date or a time range according to the local conventions.
Note that this is a convenience method. Using it involves creating an
internal Formatter instance on-the-fly, which is
somewhat costly in terms of memory and time. This is probably acceptable
if you use the method only rarely, but if you rely on it for formatting a
large number of dates, consider creating and reusing your own
Formatter instance and use the version of
formatDateRange
that takes a Formatter.
| Parameters | |
|---|---|
context |
Context:
the context is required only if the time is shown |
startMillis |
long:
the start time in UTC milliseconds |
endMillis |
long:
the end time in UTC milliseconds |
flags |
int:
a bit mask of options See
formatDateRange |
| Returns | |
|---|---|
String |
a string containing the formatted date/time range. |
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(Context, Formatter, 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):
| Parameters | |
|---|---|
context |
Context:
the context is required only if the time is shown |
millis |
long:
a point in time in UTC milliseconds |
flags |
int:
a bit mask of formatting options |
| Returns | |
|---|---|
String |
a string containing the formatted date/time. |
String formatElapsedTime (StringBuilder recycle, long elapsedSeconds)
Formats an elapsed time in a format like "MM:SS" or "H:MM:SS" (using a form suited to the current locale), similar to that used on the call-in-progress screen.
| Parameters | |
|---|---|
recycle |
StringBuilder:
StringBuilder to recycle, or null to use a temporary one. |
elapsedSeconds |
long:
the elapsed time in seconds.
|
| Returns | |
|---|---|
String |
|
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 |
long:
the elapsed time in seconds.
|
| Returns | |
|---|---|
String |
|
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
DEFAULT,
FULL,
LONG,
MEDIUM
or
SHORT
| Parameters | |
|---|---|
then |
long:
the date to format |
now |
long:
the base time |
dateStyle |
int:
how to format the date portion. |
timeStyle |
int:
how to format the time portion.
|
| Returns | |
|---|---|
CharSequence |
|
String getAMPMString (int ampm)
This method was deprecated
in API level 17.
Use SimpleDateFormat instead.
Return a localized string for AM or PM.
| Parameters | |
|---|---|
ampm |
int:
Either Calendar.AM or Calendar.PM. |
| Returns | |
|---|---|
String |
Localized version of "AM" or "PM". |
| Throws | |
|---|---|
IndexOutOfBoundsException |
if the ampm is out of bounds. |
String getDayOfWeekString (int dayOfWeek, int abbrev)
This method was deprecated
in API level 17.
Use SimpleDateFormat instead.
Return a string for the day of the week.
| Parameters | |
|---|---|
dayOfWeek |
int:
One of Calendar.SUNDAY,
Calendar.MONDAY, etc. |
abbrev |
int:
One of LENGTH_LONG, LENGTH_SHORT,
LENGTH_MEDIUM, or LENGTH_SHORTEST.
Note that in most languages, LENGTH_SHORT
will return the same as LENGTH_MEDIUM.
Undefined lengths will return LENGTH_MEDIUM
but may return something different in the future. |
| Returns | |
|---|---|
String |
|
| Throws | |
|---|---|
IndexOutOfBoundsException |
if the dayOfWeek is out of bounds. |
String getMonthString (int month, int abbrev)
This method was deprecated
in API level 17.
Use SimpleDateFormat instead.
Return a localized string for the month of the year.
| Parameters | |
|---|---|
month |
int:
One of Calendar.JANUARY,
Calendar.FEBRUARY, etc. |
abbrev |
int:
One of LENGTH_LONG, LENGTH_MEDIUM,
or LENGTH_SHORTEST.
Undefined lengths will return LENGTH_MEDIUM
but may return something different in the future. |
| Returns | |
|---|---|
String |
Localized month of the year. |
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.
| Parameters | |
|---|---|
c |
Context
|
time |
long:
some time in the past. |
minResolution |
long:
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 |
long:
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 "7 days ago" to "Dec 12"
when using WEEK_IN_MILLIS.
|
flags |
int
|
| Returns | |
|---|---|
CharSequence |
|
CharSequence getRelativeTimeSpanString (Context c, long millis, boolean withPreposition)
| Parameters | |
|---|---|
c |
Context
|
millis |
long
|
withPreposition |
boolean:
If true, the string returned will include the correct
preposition ("at 9:20am", "on 10/12/2008" or "on May 29").
|
| Returns | |
|---|---|
CharSequence |
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:
|
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 |
long:
the time to describe, in milliseconds |
now |
long:
the current time in milliseconds |
minResolution |
long:
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 |
int:
a bit mask of formatting options, such as
FORMAT_NUMERIC_DATE or
FORMAT_ABBREV_RELATIVE
|
| Returns | |
|---|---|
CharSequence |
|
CharSequence getRelativeTimeSpanString (long startTime)
Returns a string describing the elapsed time since startTime.
The minimum timespan to report is set to MINUTE_IN_MILLIS.
| Parameters | |
|---|---|
startTime |
long:
some time in the past. |
| Returns | |
|---|---|
CharSequence |
a String object containing the elapsed time. |
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 |
long:
the time to describe, in milliseconds |
now |
long:
the current time in milliseconds |
minResolution |
long:
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
|
| Returns | |
|---|---|
CharSequence |
|
CharSequence getRelativeTimeSpanString (Context c, long millis)
Convenience function to return relative time string without preposition.
| Parameters | |
|---|---|
c |
Context:
context for resources |
millis |
long:
time in milliseconds |
| Returns | |
|---|---|
CharSequence |
CharSequence containing relative time. |
boolean isToday (long when)
| Parameters | |
|---|---|
when |
long
|
| Returns | |
|---|---|
boolean |
true if the supplied when is today else false |
Developers