net.danlew.android.joda

Class DateUtils

java.lang.Object

net.danlew.android.joda.DateUtils

public class DateUtils
extends java.lang.Object

A replacement for android.text.format.DateUtils that uses Joda-Time classes. It is not a 1:1 implementation of Android's DateUtils. There are a few improvements made: - Deprecated constants have been removed. - Constants which are better represented by Joda-Time classes have been removed. - minResolution has been removed from relative time span methods because they make no sense. All it does is remove meaningful information from the string. E.g., it turns "in 30 seconds" into "in 0 minutes", or "in 5 hours" into "in 0 days". Having 0 of anything doesn't tell the user anything and should not be encouraged. - "now" has been removed from methods as a parameter. There is (AFAIK) no reason to use any time but the current time for now, especially when formatting date/times in relation to now.

Field Summary

Fields

Modifier and Type	Field and Description
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_NO_MIDNIGHT
static int	FORMAT_NO_MONTH_DAY
static int	FORMAT_NO_NOON
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

Constructor Summary

Constructors

Constructor and Description
DateUtils()

Method Summary

Modifier and Type	Method and Description
static java.lang.String	formatDateRange(android.content.Context context, ReadableInstant start, ReadableInstant end, int flags) Formats a date or a time range according to the local conventions.
static java.lang.String	formatDateRange(android.content.Context context, ReadablePartial start, ReadablePartial end, int flags) Formats a date or a time range according to the local conventions.
static java.lang.String	formatDateTime(android.content.Context context, ReadableInstant time, int flags) Formats a date or a time according to the local conventions.
static java.lang.String	formatDateTime(android.content.Context context, ReadablePartial time, int flags) Formats a date or a time according to the local conventions.
static java.lang.CharSequence	formatDuration(android.content.Context context, ReadableDuration readableDuration) Return given duration in a human-friendly format.
static java.lang.String	formatElapsedTime(ReadableDuration elapsedDuration) Formats an elapsed time in the form "MM:SS" or "H:MM:SS" for display on the call-in-progress screen.
static java.lang.String	formatElapsedTime(java.lang.StringBuilder recycle, ReadableDuration elapsedDuration) 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 java.lang.CharSequence	getRelativeDateTimeString(android.content.Context context, ReadableInstant time, ReadablePeriod transitionResolution, int flags) Return string describing the time until/elapsed time since 'time' formatted like "[relative time/date], [time]".
static java.lang.CharSequence	getRelativeDateTimeString(android.content.Context context, ReadablePartial time, ReadablePeriod transitionResolution, int flags) Return string describing the time until/elapsed time since 'time' formatted like "[relative time/date], [time]".
static java.lang.CharSequence	getRelativeTimeSpanString(android.content.Context context, ReadableInstant time) Returns a string describing 'time' as a time relative to the current time.
static java.lang.CharSequence	getRelativeTimeSpanString(android.content.Context ctx, ReadableInstant time, boolean withPreposition) Returns a relative time string to display the time expressed by millis.
static java.lang.CharSequence	getRelativeTimeSpanString(android.content.Context context, ReadableInstant time, int flags) Returns a string describing 'time' as a time relative to 'now'.
static java.lang.CharSequence	getRelativeTimeSpanString(android.content.Context context, ReadablePartial time) Returns a string describing 'time' as a time relative to the current time.
static java.lang.CharSequence	getRelativeTimeSpanString(android.content.Context ctx, ReadablePartial time, boolean withPreposition) Returns a relative time string to display the time expressed by millis.
static java.lang.CharSequence	getRelativeTimeSpanString(android.content.Context context, ReadablePartial time, int flags) Returns a string describing 'time' as a time relative to the current time.
static boolean	isToday(ReadableInstant time) See DateUtils.isToday(long) for full docs.
static boolean	isToday(ReadablePartial time) See DateUtils.isToday(long) for full docs.

Methods inherited from class java.lang.Object

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

Field Detail

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_NO_NOON

public static final int FORMAT_NO_NOON

See Also:

Constant Field Values

FORMAT_NO_MIDNIGHT

public static final int FORMAT_NO_MIDNIGHT

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

Constructor Detail

DateUtils

public DateUtils()

Method Detail

formatDateTime

public static java.lang.String formatDateTime(android.content.Context context,
                                              ReadablePartial time,
                                              int flags)

Formats a date or a time according to the local conventions. Since ReadablePartials don't support all fields, we fill in any blanks needed for formatting by using the epoch (1970-01-01T00:00:00Z). See DateUtils.formatDateTime(android.content.Context, long, int) for full docs.

Parameters:

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

time - a point in time

flags - a bit mask of formatting options

Returns:

a string containing the formatted date/time.

formatDateTime

public static java.lang.String formatDateTime(android.content.Context context,
                                              ReadableInstant time,
                                              int flags)

Formats a date or a time according to the local conventions. See DateUtils.formatDateTime(android.content.Context, long, int) for full docs.

Parameters:

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

time - a point in time

flags - a bit mask of formatting options

Returns:

a string containing the formatted date/time.

formatDateRange

public static java.lang.String formatDateRange(android.content.Context context,
                                               ReadablePartial start,
                                               ReadablePartial end,
                                               int flags)

Formats a date or a time range according to the local conventions. You should ensure that start/end are in the same timezone; formatDateRange() doesn't handle start/end in different timezones well. See DateUtils.formatDateRange(android.content.Context, long, long, int) for full docs.

Parameters:

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

start - the start time

end - the end time

flags - a bit mask of options

Returns:

a string containing the formatted date/time range

formatDateRange

public static java.lang.String formatDateRange(android.content.Context context,
                                               ReadableInstant start,
                                               ReadableInstant end,
                                               int flags)

Formats a date or a time range according to the local conventions. You should ensure that start/end are in the same timezone; formatDateRange() doesn't handle start/end in different timezones well. See DateUtils.formatDateRange(android.content.Context, long, long, int) for full docs.

Parameters:

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

start - the start time

end - the end time

flags - a bit mask of options

Returns:

a string containing the formatted date/time range

formatElapsedTime

public static java.lang.String formatElapsedTime(ReadableDuration elapsedDuration)

Formats an elapsed time in the form "MM:SS" or "H:MM:SS" for display on the call-in-progress screen. See DateUtils.formatElapsedTime(long) for full docs.

Parameters:

elapsedDuration - the elapsed duration

formatElapsedTime

public static java.lang.String formatElapsedTime(java.lang.StringBuilder recycle,
                                                 ReadableDuration elapsedDuration)

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. See DateUtils.formatElapsedTime(long) for full docs.

Parameters:

recycle - StringBuilder to recycle, or null to use a temporary one.

elapsedDuration - the elapsed duration

isToday

public static boolean isToday(ReadablePartial time)

See DateUtils.isToday(long) for full docs.

Returns:

true if the supplied when is today else false

isToday

public static boolean isToday(ReadableInstant time)

See DateUtils.isToday(long) for full docs.

Returns:

true if the supplied when is today else false

getRelativeTimeSpanString

public static java.lang.CharSequence getRelativeTimeSpanString(android.content.Context context,
                                                               ReadablePartial time)

Returns a string describing 'time' as a time relative to the current time. Missing fields from 'time' are filled in with values from the current time.

See Also:

getRelativeTimeSpanString(Context, ReadableInstant, int)

getRelativeTimeSpanString

public static java.lang.CharSequence getRelativeTimeSpanString(android.content.Context context,
                                                               ReadableInstant time)

Returns a string describing 'time' as a time relative to the current time.

See Also:

getRelativeTimeSpanString(Context, ReadableInstant, int)

getRelativeTimeSpanString

public static java.lang.CharSequence getRelativeTimeSpanString(android.content.Context context,
                                                               ReadablePartial time,
                                                               int flags)

Returns a string describing 'time' as a time relative to the current time.

See Also:

getRelativeTimeSpanString(Context, ReadableInstant, int)

getRelativeTimeSpanString

public static java.lang.CharSequence getRelativeTimeSpanString(android.content.Context context,
                                                               ReadableInstant time,
                                                               int flags)

Returns a string describing 'time' as a time relative to 'now'. See DateUtils.getRelativeTimeSpanString(long) for full docs.

Parameters:

context - the context

time - the time to describe

flags - a bit mask for formatting options, usually FORMAT_ABBREV_RELATIVE

Returns:

a string describing 'time' as a time relative to 'now'.

getRelativeTimeSpanString

public static java.lang.CharSequence getRelativeTimeSpanString(android.content.Context ctx,
                                                               ReadablePartial time,
                                                               boolean withPreposition)

Returns a relative time string to display the time expressed by millis. Missing fields from 'time' are filled in with values from the current time. See DateUtils.getRelativeTimeSpanString(long) for full docs.

Parameters:

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

getRelativeTimeSpanString

public static java.lang.CharSequence getRelativeTimeSpanString(android.content.Context ctx,
                                                               ReadableInstant time,
                                                               boolean withPreposition)

Returns a relative time string to display the time expressed by millis. See DateUtils.getRelativeTimeSpanString(long) for full docs.

Parameters:

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

getRelativeDateTimeString

public static java.lang.CharSequence getRelativeDateTimeString(android.content.Context context,
                                                               ReadablePartial time,
                                                               ReadablePeriod transitionResolution,
                                                               int flags)

Return string describing the time until/elapsed time since 'time' formatted like "[relative time/date], [time]". See DateUtils.getRelativeDateTimeString(android.content.Context, long, long, long, int) for full docs.

Throws:

java.lang.IllegalArgumentException - if using a ReadablePartial without a time component

See Also:

getRelativeDateTimeString(Context, ReadableInstant, ReadablePeriod, int)

getRelativeDateTimeString

public static java.lang.CharSequence getRelativeDateTimeString(android.content.Context context,
                                                               ReadableInstant time,
                                                               ReadablePeriod transitionResolution,
                                                               int flags)

Return string describing the time until/elapsed time since 'time' formatted like "[relative time/date], [time]". See DateUtils.getRelativeDateTimeString(android.content.Context, long, long, long, int) for full docs.

Parameters:

context - the context

time - some time

transitionResolution - the elapsed time (period) at which to stop reporting relative measurements. Periods greater than this resolution will default to normal date formatting. For example, will transition from "6 days ago" to "Dec 12" when using Weeks.ONE. If null, defaults to Days.ONE. Clamps to min value of Days.ONE, max of Weeks.ONE.

flags - flags for getRelativeTimeSpanString() (if duration is less than transitionResolution)

formatDuration

public static java.lang.CharSequence formatDuration(android.content.Context context,
                                                    ReadableDuration readableDuration)

Return given duration in a human-friendly format. For example, "4 minutes" or "1 second". Returns only largest meaningful unit of time, from seconds up to hours. The longest duration it supports is hours. This method assumes that there are 60 minutes in an hour, 60 seconds in a minute and 1000 milliseconds in a second. All currently supplied chronologies use this definition.