DateUtils
open class DateUtils
kotlin.Any | |
↳ | 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.
Summary
Constants | |
---|---|
static String |
This is not actually a useful month name in all locales. |
static String | |
static Long | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Int | |
static Long | |
static String |
This is not actually the preferred 24-hour date format in all locales. |
static Int |
Request the full spelled-out name. |
static Int |
Request an abbreviated version of the name. |
static Int |
Request a shorter abbreviated version of the name. |
static Int |
Request an even shorter abbreviated version of the name. |
static Int |
Request an even shorter abbreviated version of the name. |
static Long | |
static String | |
static String | |
static String | |
static Long | |
static String | |
static Long | |
static String | |
static String | |
static Long |
Public constructors | |
---|---|
Public methods | |
---|---|
open static String! |
formatDateRange(context: Context!, startMillis: Long, endMillis: Long, flags: Int) Formats a date or a time range according to the local conventions. |
open static Formatter! |
formatDateRange(context: Context!, formatter: Formatter!, startMillis: Long, endMillis: Long, flags: Int) Formats a date or a time range according to the local conventions. |
open static Formatter! |
formatDateRange(context: Context!, formatter: Formatter!, startMillis: Long, endMillis: Long, flags: Int, timeZone: String!) Formats a date or a time range according to the local conventions. |
open static String! |
formatDateTime(context: Context!, millis: Long, flags: Int) Formats a date or a time according to the local conventions. |
open static String! |
formatElapsedTime(elapsedSeconds: Long) Formats an elapsed time in the form "MM:SS" or "H:MM:SS" for display on the call-in-progress screen. |
open static String! |
formatElapsedTime(recycle: StringBuilder!, elapsedSeconds: Long) 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 CharSequence! |
formatSameDayTime(then: Long, now: Long, dateStyle: Int, timeStyle: Int) 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. |
open static String! |
getAMPMString(ampm: Int) Return a localized string for AM or PM. |
open static String! |
getDayOfWeekString(dayOfWeek: Int, abbrev: Int) Return a string for the day of the week. |
open static String! |
getMonthString(month: Int, abbrev: Int) Return a localized string for the month of the year. |
open static CharSequence! |
getRelativeDateTimeString(c: Context!, time: Long, minResolution: Long, transitionResolution: Long, flags: Int) Return string describing the elapsed time since startTime formatted like "[relative time/date], [time]". |
open static CharSequence! |
getRelativeTimeSpanString(startTime: Long) Returns a string describing the elapsed time since startTime. |
open static CharSequence! |
getRelativeTimeSpanString(time: Long, now: Long, minResolution: Long) Returns a string describing 'time' as a time relative to 'now'. |
open static CharSequence! |
getRelativeTimeSpanString(time: Long, now: Long, minResolution: Long, flags: Int) Returns a string describing 'time' as a time relative to 'now'. |
open static CharSequence! |
getRelativeTimeSpanString(c: Context!, millis: Long, withPreposition: Boolean) |
open static CharSequence! |
getRelativeTimeSpanString(c: Context!, millis: Long) Convenience function to return relative time string without preposition. |
open static Boolean |
Properties | |
---|---|
static IntArray! | |
static IntArray! |
Constants
ABBREV_MONTH_FORMAT
static valABBREV_MONTH_FORMAT: String
Deprecated: Use java.text.SimpleDateFormat
instead.
This is not actually a useful month name in all locales.
Value: "%b"
FORMAT_CAP_NOON_MIDNIGHT
static valFORMAT_CAP_NOON_MIDNIGHT: Int
Deprecated: Deprecated in Java.
Value: 5120
FORMAT_NO_NOON_MIDNIGHT
static valFORMAT_NO_NOON_MIDNIGHT: Int
Deprecated: Deprecated in Java.
Value: 2560
FORMAT_UTC
static valFORMAT_UTC: Int
Deprecated: Use formatDateRange
and pass in Time.TIMEZONE_UTC
for the timeZone instead.
Value: 8192
HOUR_MINUTE_24
static valHOUR_MINUTE_24: String
Deprecated: Use java.text.SimpleDateFormat
instead.
This is not actually the preferred 24-hour date format in all locales.
Value: "%H:%M"
LENGTH_LONG
static valLENGTH_LONG: Int
Deprecated: Use java.text.SimpleDateFormat
instead.
Request the full spelled-out name. For use with the 'abbrev' parameter of getDayOfWeekString
and getMonthString
.
Value: 10
LENGTH_MEDIUM
static valLENGTH_MEDIUM: Int
Deprecated: Use java.text.SimpleDateFormat
instead.
Request an abbreviated version of the name. For use with the 'abbrev' parameter of getDayOfWeekString
and getMonthString
.
Value: 20
LENGTH_SHORT
static valLENGTH_SHORT: Int
Deprecated: Use java.text.SimpleDateFormat
instead.
Request a shorter abbreviated version of the name. For use with the 'abbrev' parameter of getDayOfWeekString
and getMonthString
.
Value: 30
LENGTH_SHORTER
static valLENGTH_SHORTER: Int
Deprecated: Use java.text.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
.
Value: 40
LENGTH_SHORTEST
static valLENGTH_SHORTEST: Int
Deprecated: Use java.text.SimpleDateFormat
instead.
Request an even shorter abbreviated version of the name. For use with the 'abbrev' parameter of getDayOfWeekString
and getMonthString
.
Value: 50
YEAR_IN_MILLIS
static valYEAR_IN_MILLIS: Long
Deprecated: Not all years have the same number of days, and this constant is actually the length of 364 days. Please use other date/time constructs such as java.util.concurrent.TimeUnit
, java.util.Calendar
or java.time.Duration
instead.
Value: 31449600000L
Public constructors
DateUtils
DateUtils()
Public methods
formatDateRange
open static fun formatDateRange(
context: Context!,
startMillis: Long,
endMillis: Long,
flags: Int
): String!
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 java.util.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 java.util.Formatter
instance and use the version of formatDateRange
that takes a java.util.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 |
Return | |
---|---|
String! |
a string containing the formatted date/time range. |
formatDateRange
open static fun formatDateRange(
context: Context!,
formatter: Formatter!,
startMillis: Long,
endMillis: Long,
flags: Int
): Formatter!
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 |
Return | |
---|---|
Formatter! |
a string containing the formatted date/time range. |
formatDateRange
open static fun formatDateRange(
context: Context!,
formatter: Formatter!,
startMillis: Long,
endMillis: Long,
flags: Int,
timeZone: String!
): Formatter!
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_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_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:
- For single day events. This results in "8pm - midnight" instead of "Nov 10, 8pm - Nov 11, 12am".
- When the time is not displayed. This results in "Nov 10 - 11" for an event with a start date of Nov 10 and an end date of Nov 12 at 00:00.
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 id of the time zone to compute the string in. Use null for local or if the FORMAT_UTC flag is being used. |
Return | |
---|---|
Formatter! |
the formatter with the formatted date/time range appended to the string buffer. |
formatDateTime
open static fun formatDateTime(
context: Context!,
millis: Long,
flags: Int
): String!
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.
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 |
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 |
Return | |
---|---|
String! |
a string containing the formatted date/time. |
formatElapsedTime
open static fun formatElapsedTime(elapsedSeconds: Long): String!
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. |
formatElapsedTime
open static fun formatElapsedTime(
recycle: StringBuilder!,
elapsedSeconds: Long
): String!
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. |
formatSameDayTime
static fun formatSameDayTime(
then: Long,
now: Long,
dateStyle: Int,
timeStyle: Int
): CharSequence!
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 java.text.DateFormat#DEFAULT
, java.text.DateFormat#FULL
, java.text.DateFormat#LONG
, java.text.DateFormat#MEDIUM
or java.text.DateFormat#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. |
getAMPMString
open static fungetAMPMString(ampm: Int): String!
Deprecated: Use java.text.SimpleDateFormat
instead.
Return a localized string for AM or PM.
Parameters | |
---|---|
ampm |
Int: Either Calendar.AM or Calendar.PM . |
Return | |
---|---|
String! |
Localized version of "AM" or "PM". |
Exceptions | |
---|---|
java.lang.IndexOutOfBoundsException |
if the ampm is out of bounds. |
getDayOfWeekString
open static fungetDayOfWeekString(
dayOfWeek: Int,
abbrev: Int
): String!
Deprecated: Use java.text.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. |
Exceptions | |
---|---|
java.lang.IndexOutOfBoundsException |
if the dayOfWeek is out of bounds. |
getMonthString
open static fungetMonthString(
month: Int,
abbrev: Int
): String!
Deprecated: Use java.text.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. |
Return | |
---|---|
String! |
Localized month of the year. |
getRelativeDateTimeString
open static fun getRelativeDateTimeString(
c: Context!,
time: Long,
minResolution: Long,
transitionResolution: Long,
flags: Int
): CharSequence!
Return string describing the elapsed time since startTime formatted like "[relative time/date], [time]".
Example output strings for the US date format.
- 3 min. ago, 10:15 AM
- Yesterday, 12:20 PM
- Dec 12, 4:12 AM
- 11/14/2007, 8:20 AM
Parameters | |
---|---|
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 . |
getRelativeTimeSpanString
open static fun getRelativeTimeSpanString(startTime: Long): CharSequence!
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. |
Return | |
---|---|
CharSequence! |
a String object containing the elapsed time. |
getRelativeTimeSpanString
open static fun getRelativeTimeSpanString(
time: Long,
now: Long,
minResolution: Long
): CharSequence!
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 |
getRelativeTimeSpanString
open static fun getRelativeTimeSpanString(
time: Long,
now: Long,
minResolution: Long,
flags: Int
): CharSequence!
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 |
getRelativeTimeSpanString
open static fun getRelativeTimeSpanString(
c: Context!,
millis: Long,
withPreposition: Boolean
): CharSequence!
Parameters | |
---|---|
withPreposition |
Boolean: If true, the string returned will include the correct preposition ("at 9:20am", "on 10/12/2008" or "on May 29"). |
Return | |
---|---|
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:
|
getRelativeTimeSpanString
open static fun getRelativeTimeSpanString(
c: Context!,
millis: Long
): CharSequence!
Convenience function to return relative time string without preposition.
Parameters | |
---|---|
c |
Context!: context for resources |
millis |
Long: time in milliseconds |
Return | |
---|---|
CharSequence! |
CharSequence containing relative time. |
isToday
open static fun isToday(when: Long): Boolean
Return | |
---|---|
Boolean |
true if the supplied when is today else false |