/*
|
* Copyright (C) 2006 The Android Open Source Project
|
*
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
* you may not use this file except in compliance with the License.
|
* You may obtain a copy of the License at
|
*
|
* http://www.apache.org/licenses/LICENSE-2.0
|
*
|
* Unless required by applicable law or agreed to in writing, software
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
* See the License for the specific language governing permissions and
|
* limitations under the License.
|
*/
|
|
package android.text.format;
|
|
import android.annotation.NonNull;
|
import android.annotation.UnsupportedAppUsage;
|
import android.content.Context;
|
import android.os.UserHandle;
|
import android.provider.Settings;
|
import android.text.SpannableStringBuilder;
|
import android.text.Spanned;
|
import android.text.SpannedString;
|
|
import libcore.icu.ICU;
|
import libcore.icu.LocaleData;
|
|
import java.text.SimpleDateFormat;
|
import java.util.Calendar;
|
import java.util.Date;
|
import java.util.GregorianCalendar;
|
import java.util.Locale;
|
import java.util.TimeZone;
|
|
/**
|
* Utility class for producing strings with formatted date/time.
|
*
|
* <p>Most callers should avoid supplying their own format strings to this
|
* class' {@code format} methods and rely on the correctly localized ones
|
* supplied by the system. This class' factory methods return
|
* appropriately-localized {@link java.text.DateFormat} instances, suitable
|
* for both formatting and parsing dates. For the canonical documentation
|
* of format strings, see {@link java.text.SimpleDateFormat}.
|
*
|
* <p>In cases where the system does not provide a suitable pattern,
|
* this class offers the {@link #getBestDateTimePattern} method.
|
*
|
* <p>The {@code format} methods in this class implement a subset of Unicode
|
* <a href="http://www.unicode.org/reports/tr35/#Date_Format_Patterns">UTS #35</a> patterns.
|
* The subset currently supported by this class includes the following format characters:
|
* {@code acdEHhLKkLMmsyz}. Up to API level 17, only {@code adEhkMmszy} were supported.
|
* Note that this class incorrectly implements {@code k} as if it were {@code H} for backwards
|
* compatibility.
|
*
|
* <p>See {@link java.text.SimpleDateFormat} for more documentation
|
* about patterns, or if you need a more complete or correct implementation.
|
* Note that the non-{@code format} methods in this class are implemented by
|
* {@code SimpleDateFormat}.
|
*/
|
public class DateFormat {
|
/**
|
* @deprecated Use a literal {@code '} instead.
|
* @removed
|
*/
|
@Deprecated
|
public static final char QUOTE = '\'';
|
|
/**
|
* @deprecated Use a literal {@code 'a'} instead.
|
* @removed
|
*/
|
@Deprecated
|
public static final char AM_PM = 'a';
|
|
/**
|
* @deprecated Use a literal {@code 'a'} instead; 'A' was always equivalent to 'a'.
|
* @removed
|
*/
|
@Deprecated
|
public static final char CAPITAL_AM_PM = 'A';
|
|
/**
|
* @deprecated Use a literal {@code 'd'} instead.
|
* @removed
|
*/
|
@Deprecated
|
public static final char DATE = 'd';
|
|
/**
|
* @deprecated Use a literal {@code 'E'} instead.
|
* @removed
|
*/
|
@Deprecated
|
public static final char DAY = 'E';
|
|
/**
|
* @deprecated Use a literal {@code 'h'} instead.
|
* @removed
|
*/
|
@Deprecated
|
public static final char HOUR = 'h';
|
|
/**
|
* @deprecated Use a literal {@code 'H'} (for compatibility with {@link SimpleDateFormat}
|
* and Unicode) or {@code 'k'} (for compatibility with Android releases up to and including
|
* Jelly Bean MR-1) instead. Note that the two are incompatible.
|
*
|
* @removed
|
*/
|
@Deprecated
|
public static final char HOUR_OF_DAY = 'k';
|
|
/**
|
* @deprecated Use a literal {@code 'm'} instead.
|
* @removed
|
*/
|
@Deprecated
|
public static final char MINUTE = 'm';
|
|
/**
|
* @deprecated Use a literal {@code 'M'} instead.
|
* @removed
|
*/
|
@Deprecated
|
public static final char MONTH = 'M';
|
|
/**
|
* @deprecated Use a literal {@code 'L'} instead.
|
* @removed
|
*/
|
@Deprecated
|
public static final char STANDALONE_MONTH = 'L';
|
|
/**
|
* @deprecated Use a literal {@code 's'} instead.
|
* @removed
|
*/
|
@Deprecated
|
public static final char SECONDS = 's';
|
|
/**
|
* @deprecated Use a literal {@code 'z'} instead.
|
* @removed
|
*/
|
@Deprecated
|
public static final char TIME_ZONE = 'z';
|
|
/**
|
* @deprecated Use a literal {@code 'y'} instead.
|
* @removed
|
*/
|
@Deprecated
|
public static final char YEAR = 'y';
|
|
|
private static final Object sLocaleLock = new Object();
|
private static Locale sIs24HourLocale;
|
private static boolean sIs24Hour;
|
|
/**
|
* Returns true if times should be formatted as 24 hour times, false if times should be
|
* formatted as 12 hour (AM/PM) times. Based on the user's chosen locale and other preferences.
|
* @param context the context to use for the content resolver
|
* @return true if 24 hour time format is selected, false otherwise.
|
*/
|
public static boolean is24HourFormat(Context context) {
|
return is24HourFormat(context, context.getUserId());
|
}
|
|
/**
|
* Returns true if times should be formatted as 24 hour times, false if times should be
|
* formatted as 12 hour (AM/PM) times. Based on the user's chosen locale and other preferences.
|
* @param context the context to use for the content resolver
|
* @param userHandle the user handle of the user to query.
|
* @return true if 24 hour time format is selected, false otherwise.
|
*
|
* @hide
|
*/
|
@UnsupportedAppUsage
|
public static boolean is24HourFormat(Context context, int userHandle) {
|
final String value = Settings.System.getStringForUser(context.getContentResolver(),
|
Settings.System.TIME_12_24, userHandle);
|
if (value != null) {
|
return value.equals("24");
|
}
|
|
return is24HourLocale(context.getResources().getConfiguration().locale);
|
}
|
|
/**
|
* Returns true if the specified locale uses a 24-hour time format by default, ignoring user
|
* settings.
|
* @param locale the locale to check
|
* @return true if the locale uses a 24 hour time format by default, false otherwise
|
* @hide
|
*/
|
public static boolean is24HourLocale(@NonNull Locale locale) {
|
synchronized (sLocaleLock) {
|
if (sIs24HourLocale != null && sIs24HourLocale.equals(locale)) {
|
return sIs24Hour;
|
}
|
}
|
|
final java.text.DateFormat natural =
|
java.text.DateFormat.getTimeInstance(java.text.DateFormat.LONG, locale);
|
|
final boolean is24Hour;
|
if (natural instanceof SimpleDateFormat) {
|
final SimpleDateFormat sdf = (SimpleDateFormat) natural;
|
final String pattern = sdf.toPattern();
|
is24Hour = hasDesignator(pattern, 'H');
|
} else {
|
is24Hour = false;
|
}
|
|
synchronized (sLocaleLock) {
|
sIs24HourLocale = locale;
|
sIs24Hour = is24Hour;
|
}
|
|
return is24Hour;
|
}
|
|
/**
|
* Returns the best possible localized form of the given skeleton for the given
|
* locale. A skeleton is similar to, and uses the same format characters as, a Unicode
|
* <a href="http://www.unicode.org/reports/tr35/#Date_Format_Patterns">UTS #35</a>
|
* pattern.
|
*
|
* <p>One difference is that order is irrelevant. For example, "MMMMd" will return
|
* "MMMM d" in the {@code en_US} locale, but "d. MMMM" in the {@code de_CH} locale.
|
*
|
* <p>Note also in that second example that the necessary punctuation for German was
|
* added. For the same input in {@code es_ES}, we'd have even more extra text:
|
* "d 'de' MMMM".
|
*
|
* <p>This method will automatically correct for grammatical necessity. Given the
|
* same "MMMMd" input, this method will return "d LLLL" in the {@code fa_IR} locale,
|
* where stand-alone months are necessary. Lengths are preserved where meaningful,
|
* so "Md" would give a different result to "MMMd", say, except in a locale such as
|
* {@code ja_JP} where there is only one length of month.
|
*
|
* <p>This method will only return patterns that are in CLDR, and is useful whenever
|
* you know what elements you want in your format string but don't want to make your
|
* code specific to any one locale.
|
*
|
* @param locale the locale into which the skeleton should be localized
|
* @param skeleton a skeleton as described above
|
* @return a string pattern suitable for use with {@link java.text.SimpleDateFormat}.
|
*/
|
public static String getBestDateTimePattern(Locale locale, String skeleton) {
|
return ICU.getBestDateTimePattern(skeleton, locale);
|
}
|
|
/**
|
* Returns a {@link java.text.DateFormat} object that can format the time according
|
* to the context's locale and the user's 12-/24-hour clock preference.
|
* @param context the application context
|
* @return the {@link java.text.DateFormat} object that properly formats the time.
|
*/
|
public static java.text.DateFormat getTimeFormat(Context context) {
|
final Locale locale = context.getResources().getConfiguration().locale;
|
return new java.text.SimpleDateFormat(getTimeFormatString(context), locale);
|
}
|
|
/**
|
* Returns a String pattern that can be used to format the time according
|
* to the context's locale and the user's 12-/24-hour clock preference.
|
* @param context the application context
|
* @hide
|
*/
|
@UnsupportedAppUsage
|
public static String getTimeFormatString(Context context) {
|
return getTimeFormatString(context, context.getUserId());
|
}
|
|
/**
|
* Returns a String pattern that can be used to format the time according
|
* to the context's locale and the user's 12-/24-hour clock preference.
|
* @param context the application context
|
* @param userHandle the user handle of the user to query the format for
|
* @hide
|
*/
|
@UnsupportedAppUsage
|
public static String getTimeFormatString(Context context, int userHandle) {
|
final LocaleData d = LocaleData.get(context.getResources().getConfiguration().locale);
|
return is24HourFormat(context, userHandle) ? d.timeFormat_Hm : d.timeFormat_hm;
|
}
|
|
/**
|
* Returns a {@link java.text.DateFormat} object that can format the date
|
* in short form according to the context's locale.
|
*
|
* @param context the application context
|
* @return the {@link java.text.DateFormat} object that properly formats the date.
|
*/
|
public static java.text.DateFormat getDateFormat(Context context) {
|
final Locale locale = context.getResources().getConfiguration().locale;
|
return java.text.DateFormat.getDateInstance(java.text.DateFormat.SHORT, locale);
|
}
|
|
/**
|
* Returns a {@link java.text.DateFormat} object that can format the date
|
* in long form (such as {@code Monday, January 3, 2000}) for the context's locale.
|
* @param context the application context
|
* @return the {@link java.text.DateFormat} object that formats the date in long form.
|
*/
|
public static java.text.DateFormat getLongDateFormat(Context context) {
|
final Locale locale = context.getResources().getConfiguration().locale;
|
return java.text.DateFormat.getDateInstance(java.text.DateFormat.LONG, locale);
|
}
|
|
/**
|
* Returns a {@link java.text.DateFormat} object that can format the date
|
* in medium form (such as {@code Jan 3, 2000}) for the context's locale.
|
* @param context the application context
|
* @return the {@link java.text.DateFormat} object that formats the date in long form.
|
*/
|
public static java.text.DateFormat getMediumDateFormat(Context context) {
|
final Locale locale = context.getResources().getConfiguration().locale;
|
return java.text.DateFormat.getDateInstance(java.text.DateFormat.MEDIUM, locale);
|
}
|
|
/**
|
* Gets the current date format stored as a char array. Returns a 3 element
|
* array containing the day ({@code 'd'}), month ({@code 'M'}), and year ({@code 'y'}))
|
* in the order specified by the user's format preference. Note that this order is
|
* <i>only</i> appropriate for all-numeric dates; spelled-out (MEDIUM and LONG)
|
* dates will generally contain other punctuation, spaces, or words,
|
* not just the day, month, and year, and not necessarily in the same
|
* order returned here.
|
*/
|
public static char[] getDateFormatOrder(Context context) {
|
return ICU.getDateFormatOrder(getDateFormatString(context));
|
}
|
|
private static String getDateFormatString(Context context) {
|
final Locale locale = context.getResources().getConfiguration().locale;
|
java.text.DateFormat df = java.text.DateFormat.getDateInstance(
|
java.text.DateFormat.SHORT, locale);
|
if (df instanceof SimpleDateFormat) {
|
return ((SimpleDateFormat) df).toPattern();
|
}
|
|
throw new AssertionError("!(df instanceof SimpleDateFormat)");
|
}
|
|
/**
|
* Given a format string and a time in milliseconds since Jan 1, 1970 GMT, returns a
|
* CharSequence containing the requested date.
|
* @param inFormat the format string, as described in {@link android.text.format.DateFormat}
|
* @param inTimeInMillis in milliseconds since Jan 1, 1970 GMT
|
* @return a {@link CharSequence} containing the requested text
|
*/
|
public static CharSequence format(CharSequence inFormat, long inTimeInMillis) {
|
return format(inFormat, new Date(inTimeInMillis));
|
}
|
|
/**
|
* Given a format string and a {@link java.util.Date} object, returns a CharSequence containing
|
* the requested date.
|
* @param inFormat the format string, as described in {@link android.text.format.DateFormat}
|
* @param inDate the date to format
|
* @return a {@link CharSequence} containing the requested text
|
*/
|
public static CharSequence format(CharSequence inFormat, Date inDate) {
|
Calendar c = new GregorianCalendar();
|
c.setTime(inDate);
|
return format(inFormat, c);
|
}
|
|
/**
|
* Indicates whether the specified format string contains seconds.
|
*
|
* Always returns false if the input format is null.
|
*
|
* @param inFormat the format string, as described in {@link android.text.format.DateFormat}
|
*
|
* @return true if the format string contains {@link #SECONDS}, false otherwise
|
*
|
* @hide
|
*/
|
@UnsupportedAppUsage
|
public static boolean hasSeconds(CharSequence inFormat) {
|
return hasDesignator(inFormat, SECONDS);
|
}
|
|
/**
|
* Test if a format string contains the given designator. Always returns
|
* {@code false} if the input format is {@code null}.
|
*
|
* Note that this is intended for searching for designators, not arbitrary
|
* characters. So searching for a literal single quote would not work correctly.
|
*
|
* @hide
|
*/
|
@UnsupportedAppUsage
|
public static boolean hasDesignator(CharSequence inFormat, char designator) {
|
if (inFormat == null) return false;
|
|
final int length = inFormat.length();
|
|
boolean insideQuote = false;
|
for (int i = 0; i < length; i++) {
|
final char c = inFormat.charAt(i);
|
if (c == QUOTE) {
|
insideQuote = !insideQuote;
|
} else if (!insideQuote) {
|
if (c == designator) {
|
return true;
|
}
|
}
|
}
|
|
return false;
|
}
|
|
/**
|
* Given a format string and a {@link java.util.Calendar} object, returns a CharSequence
|
* containing the requested date.
|
* @param inFormat the format string, as described in {@link android.text.format.DateFormat}
|
* @param inDate the date to format
|
* @return a {@link CharSequence} containing the requested text
|
*/
|
public static CharSequence format(CharSequence inFormat, Calendar inDate) {
|
SpannableStringBuilder s = new SpannableStringBuilder(inFormat);
|
int count;
|
|
LocaleData localeData = LocaleData.get(Locale.getDefault());
|
|
int len = inFormat.length();
|
|
for (int i = 0; i < len; i += count) {
|
count = 1;
|
int c = s.charAt(i);
|
|
if (c == QUOTE) {
|
count = appendQuotedText(s, i);
|
len = s.length();
|
continue;
|
}
|
|
while ((i + count < len) && (s.charAt(i + count) == c)) {
|
count++;
|
}
|
|
String replacement;
|
switch (c) {
|
case 'A':
|
case 'a':
|
replacement = localeData.amPm[inDate.get(Calendar.AM_PM) - Calendar.AM];
|
break;
|
case 'd':
|
replacement = zeroPad(inDate.get(Calendar.DATE), count);
|
break;
|
case 'c':
|
case 'E':
|
replacement = getDayOfWeekString(localeData,
|
inDate.get(Calendar.DAY_OF_WEEK), count, c);
|
break;
|
case 'K': // hour in am/pm (0-11)
|
case 'h': // hour in am/pm (1-12)
|
{
|
int hour = inDate.get(Calendar.HOUR);
|
if (c == 'h' && hour == 0) {
|
hour = 12;
|
}
|
replacement = zeroPad(hour, count);
|
}
|
break;
|
case 'H': // hour in day (0-23)
|
case 'k': // hour in day (1-24) [but see note below]
|
{
|
int hour = inDate.get(Calendar.HOUR_OF_DAY);
|
// Historically on Android 'k' was interpreted as 'H', which wasn't
|
// implemented, so pretty much all callers that want to format 24-hour
|
// times are abusing 'k'. http://b/8359981.
|
if (false && c == 'k' && hour == 0) {
|
hour = 24;
|
}
|
replacement = zeroPad(hour, count);
|
}
|
break;
|
case 'L':
|
case 'M':
|
replacement = getMonthString(localeData,
|
inDate.get(Calendar.MONTH), count, c);
|
break;
|
case 'm':
|
replacement = zeroPad(inDate.get(Calendar.MINUTE), count);
|
break;
|
case 's':
|
replacement = zeroPad(inDate.get(Calendar.SECOND), count);
|
break;
|
case 'y':
|
replacement = getYearString(inDate.get(Calendar.YEAR), count);
|
break;
|
case 'z':
|
replacement = getTimeZoneString(inDate, count);
|
break;
|
default:
|
replacement = null;
|
break;
|
}
|
|
if (replacement != null) {
|
s.replace(i, i + count, replacement);
|
count = replacement.length(); // CARE: count is used in the for loop above
|
len = s.length();
|
}
|
}
|
|
if (inFormat instanceof Spanned) {
|
return new SpannedString(s);
|
} else {
|
return s.toString();
|
}
|
}
|
|
private static String getDayOfWeekString(LocaleData ld, int day, int count, int kind) {
|
boolean standalone = (kind == 'c');
|
if (count == 5) {
|
return standalone ? ld.tinyStandAloneWeekdayNames[day] : ld.tinyWeekdayNames[day];
|
} else if (count == 4) {
|
return standalone ? ld.longStandAloneWeekdayNames[day] : ld.longWeekdayNames[day];
|
} else {
|
return standalone ? ld.shortStandAloneWeekdayNames[day] : ld.shortWeekdayNames[day];
|
}
|
}
|
|
private static String getMonthString(LocaleData ld, int month, int count, int kind) {
|
boolean standalone = (kind == 'L');
|
if (count == 5) {
|
return standalone ? ld.tinyStandAloneMonthNames[month] : ld.tinyMonthNames[month];
|
} else if (count == 4) {
|
return standalone ? ld.longStandAloneMonthNames[month] : ld.longMonthNames[month];
|
} else if (count == 3) {
|
return standalone ? ld.shortStandAloneMonthNames[month] : ld.shortMonthNames[month];
|
} else {
|
// Calendar.JANUARY == 0, so add 1 to month.
|
return zeroPad(month+1, count);
|
}
|
}
|
|
private static String getTimeZoneString(Calendar inDate, int count) {
|
TimeZone tz = inDate.getTimeZone();
|
if (count < 2) { // FIXME: shouldn't this be <= 2 ?
|
return formatZoneOffset(inDate.get(Calendar.DST_OFFSET) +
|
inDate.get(Calendar.ZONE_OFFSET),
|
count);
|
} else {
|
boolean dst = inDate.get(Calendar.DST_OFFSET) != 0;
|
return tz.getDisplayName(dst, TimeZone.SHORT);
|
}
|
}
|
|
private static String formatZoneOffset(int offset, int count) {
|
offset /= 1000; // milliseconds to seconds
|
StringBuilder tb = new StringBuilder();
|
|
if (offset < 0) {
|
tb.insert(0, "-");
|
offset = -offset;
|
} else {
|
tb.insert(0, "+");
|
}
|
|
int hours = offset / 3600;
|
int minutes = (offset % 3600) / 60;
|
|
tb.append(zeroPad(hours, 2));
|
tb.append(zeroPad(minutes, 2));
|
return tb.toString();
|
}
|
|
private static String getYearString(int year, int count) {
|
return (count <= 2) ? zeroPad(year % 100, 2)
|
: String.format(Locale.getDefault(), "%d", year);
|
}
|
|
|
/**
|
* Strips quotation marks from the {@code formatString} and appends the result back to the
|
* {@code formatString}.
|
*
|
* @param formatString the format string, as described in
|
* {@link android.text.format.DateFormat}, to be modified
|
* @param index index of the first quote
|
* @return the length of the quoted text that was appended.
|
* @hide
|
*/
|
public static int appendQuotedText(SpannableStringBuilder formatString, int index) {
|
int length = formatString.length();
|
if (index + 1 < length && formatString.charAt(index + 1) == QUOTE) {
|
formatString.delete(index, index + 1);
|
return 1;
|
}
|
|
int count = 0;
|
|
// delete leading quote
|
formatString.delete(index, index + 1);
|
length--;
|
|
while (index < length) {
|
char c = formatString.charAt(index);
|
|
if (c == QUOTE) {
|
// QUOTEQUOTE -> QUOTE
|
if (index + 1 < length && formatString.charAt(index + 1) == QUOTE) {
|
|
formatString.delete(index, index + 1);
|
length--;
|
count++;
|
index++;
|
} else {
|
// Closing QUOTE ends quoted text copying
|
formatString.delete(index, index + 1);
|
break;
|
}
|
} else {
|
index++;
|
count++;
|
}
|
}
|
|
return count;
|
}
|
|
private static String zeroPad(int inValue, int inMinDigits) {
|
return String.format(Locale.getDefault(), "%0" + inMinDigits + "d", inValue);
|
}
|
}
|
