android/text/format/DateFormat.java - platform/prebuilts/fullsdk/sources/android-30 - Git at Google

 /*
  * 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.compat.annotation.UnsupportedAppUsage;
 import android.content.Context;
 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);
     }
 }
	/*
	* 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.compat.annotation.UnsupportedAppUsage;
	import android.content.Context;
	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);
	}
	}