jars/icu4j-4_4_2-src/main/classes/core/src/com/ibm/icu/text/DateFormat.java

   1 /*\r
   2  *   Copyright (C) 1996-2010, International Business Machines\r
   3  *   Corporation and others.  All Rights Reserved.\r
   4  */\r
   5 \r
   6 package com.ibm.icu.text;\r
   7 \r
   8 import java.io.InvalidObjectException;\r
   9 import java.text.FieldPosition;\r
  10 import java.text.Format;\r
  11 import java.text.ParseException;\r
  12 import java.text.ParsePosition;\r
  13 import java.util.Date;\r
  14 import java.util.HashMap;\r
  15 import java.util.Locale;\r
  16 import java.util.Map;\r
  17 import java.util.MissingResourceException;\r
  18 \r
  19 import com.ibm.icu.impl.ICUResourceBundle;\r
  20 import com.ibm.icu.impl.RelativeDateFormat;\r
  21 import com.ibm.icu.util.Calendar;\r
  22 import com.ibm.icu.util.GregorianCalendar;\r
  23 import com.ibm.icu.util.TimeZone;\r
  24 import com.ibm.icu.util.ULocale;\r
  25 \r
  26 /**\r
  27  * {@icuenhanced java.text.DateFormat}.{@icu _usage_}\r
  28  *\r
  29  * <p>DateFormat is an abstract class for date/time formatting subclasses which\r
  30  * formats and parses dates or time in a language-independent manner.\r
  31  * The date/time formatting subclass, such as SimpleDateFormat, allows for\r
  32  * formatting (i.e., date -> text), parsing (text -> date), and\r
  33  * normalization.  The date is represented as a <code>Date</code> object or\r
  34  * as the milliseconds since January 1, 1970, 00:00:00 GMT.\r
  35  *\r
  36  * <p>DateFormat provides many class methods for obtaining default date/time\r
  37  * formatters based on the default or a given locale and a number of formatting\r
  38  * styles. The formatting styles include FULL, LONG, MEDIUM, and SHORT. More\r
  39  * detail and examples of using these styles are provided in the method\r
  40  * descriptions.\r
  41  *\r
  42  * <p>DateFormat helps you to format and parse dates for any locale.\r
  43  * Your code can be completely independent of the locale conventions for\r
  44  * months, days of the week, or even the calendar format: lunar vs. solar.\r
  45  *\r
  46  * <p>To format a date for the current Locale, use one of the\r
  47  * static factory methods:\r
  48  * <pre>\r
  49  *  myString = DateFormat.getDateInstance().format(myDate);\r
  50  * </pre>\r
  51  * <p>If you are formatting multiple numbers, it is\r
  52  * more efficient to get the format and use it multiple times so that\r
  53  * the system doesn't have to fetch the information about the local\r
  54  * language and country conventions multiple times.\r
  55  * <pre>\r
  56  *  DateFormat df = DateFormat.getDateInstance();\r
  57  *  for (int i = 0; i < a.length; ++i) {\r
  58  *    output.println(df.format(myDate[i]) + "; ");\r
  59  *  }\r
  60  * </pre>\r
  61  * <p>To format a number for a different Locale, specify it in the\r
  62  * call to getDateInstance().\r
  63  * <pre>\r
  64  *  DateFormat df = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE);\r
  65  * </pre>\r
  66  * <p>You can use a DateFormat to parse also.\r
  67  * <pre>\r
  68  *  myDate = df.parse(myString);\r
  69  * </pre>\r
  70  * <p>Use getDateInstance to get the normal date format for that country.\r
  71  * There are other static factory methods available.\r
  72  * Use getTimeInstance to get the time format for that country.\r
  73  * Use getDateTimeInstance to get a date and time format. You can pass in\r
  74  * different options to these factory methods to control the length of the\r
  75  * result; from SHORT to MEDIUM to LONG to FULL. The exact result depends\r
  76  * on the locale, but generally:\r
  77  * <ul><li>SHORT is completely numeric, such as 12.13.52 or 3:30pm\r
  78  * <li>MEDIUM is longer, such as Jan 12, 1952\r
  79  * <li>LONG is longer, such as January 12, 1952 or 3:30:32pm\r
  80  * <li>FULL is pretty completely specified, such as\r
  81  * Tuesday, April 12, 1952 AD or 3:30:42pm PST.\r
  82  * </ul>\r
  83  *\r
  84  * <p>You can also set the time zone on the format if you wish.\r
  85  * If you want even more control over the format or parsing,\r
  86  * (or want to give your users more control),\r
  87  * you can try casting the DateFormat you get from the factory methods\r
  88  * to a SimpleDateFormat. This will work for the majority\r
  89  * of countries; just remember to put it in a try block in case you\r
  90  * encounter an unusual one.\r
  91  *\r
  92  * <p>You can also use forms of the parse and format methods with\r
  93  * ParsePosition and FieldPosition to\r
  94  * allow you to\r
  95  * <ul><li>progressively parse through pieces of a string.\r
  96  * <li>align any particular field, or find out where it is for selection\r
  97  * on the screen.\r
  98  * </ul>\r
  99  *\r
 100  * <h4>Synchronization</h4>\r
 101  *\r
 102  * Date formats are not synchronized. It is recommended to create separate\r
 103  * format instances for each thread. If multiple threads access a format\r
 104  * concurrently, it must be synchronized externally.\r
 105  *\r
 106  * @see          UFormat\r
 107  * @see          NumberFormat\r
 108  * @see          SimpleDateFormat\r
 109  * @see          com.ibm.icu.util.Calendar\r
 110  * @see          com.ibm.icu.util.GregorianCalendar\r
 111  * @see          com.ibm.icu.util.TimeZone\r
 112  * @author       Mark Davis, Chen-Lieh Huang, Alan Liu\r
 113  * @stable ICU 2.0\r
 114  */\r
 115 public abstract class DateFormat extends UFormat {\r
 116 \r
 117     /**\r
 118      * The calendar that <code>DateFormat</code> uses to produce the time field\r
 119      * values needed to implement date and time formatting.  Subclasses should\r
 120      * initialize this to a calendar appropriate for the locale associated with\r
 121      * this <code>DateFormat</code>.\r
 122      * @serial\r
 123      * @stable ICU 2.0\r
 124      */\r
 125     protected Calendar calendar;\r
 126 \r
 127     /**\r
 128      * The number formatter that <code>DateFormat</code> uses to format numbers\r
 129      * in dates and times.  Subclasses should initialize this to a number format\r
 130      * appropriate for the locale associated with this <code>DateFormat</code>.\r
 131      * @serial\r
 132      * @stable ICU 2.0\r
 133      */\r
 134     protected NumberFormat numberFormat;\r
 135 \r
 136     /**\r
 137      * FieldPosition selector for 'G' field alignment,\r
 138      * corresponding to the {@link Calendar#ERA} field.\r
 139      * @stable ICU 2.0\r
 140      */\r
 141     public final static int ERA_FIELD = 0;\r
 142 \r
 143     /**\r
 144      * FieldPosition selector for 'y' field alignment,\r
 145      * corresponding to the {@link Calendar#YEAR} field.\r
 146      * @stable ICU 2.0\r
 147      */\r
 148     public final static int YEAR_FIELD = 1;\r
 149 \r
 150     /**\r
 151      * FieldPosition selector for 'M' field alignment,\r
 152      * corresponding to the {@link Calendar#MONTH} field.\r
 153      * @stable ICU 2.0\r
 154      */\r
 155     public final static int MONTH_FIELD = 2;\r
 156 \r
 157     /**\r
 158      * FieldPosition selector for 'd' field alignment,\r
 159      * corresponding to the {@link Calendar#DATE} field.\r
 160      * @stable ICU 2.0\r
 161      */\r
 162     public final static int DATE_FIELD = 3;\r
 163 \r
 164     /**\r
 165      * FieldPosition selector for 'k' field alignment,\r
 166      * corresponding to the {@link Calendar#HOUR_OF_DAY} field.\r
 167      * HOUR_OF_DAY1_FIELD is used for the one-based 24-hour clock.\r
 168      * For example, 23:59 + 01:00 results in 24:59.\r
 169      * @stable ICU 2.0\r
 170      */\r
 171     public final static int HOUR_OF_DAY1_FIELD = 4;\r
 172 \r
 173     /**\r
 174      * FieldPosition selector for 'H' field alignment,\r
 175      * corresponding to the {@link Calendar#HOUR_OF_DAY} field.\r
 176      * HOUR_OF_DAY0_FIELD is used for the zero-based 24-hour clock.\r
 177      * For example, 23:59 + 01:00 results in 00:59.\r
 178      * @stable ICU 2.0\r
 179      */\r
 180     public final static int HOUR_OF_DAY0_FIELD = 5;\r
 181 \r
 182     /**\r
 183      * FieldPosition selector for 'm' field alignment,\r
 184      * corresponding to the {@link Calendar#MINUTE} field.\r
 185      * @stable ICU 2.0\r
 186      */\r
 187     public final static int MINUTE_FIELD = 6;\r
 188 \r
 189     /**\r
 190      * FieldPosition selector for 's' field alignment,\r
 191      * corresponding to the {@link Calendar#SECOND} field.\r
 192      * @stable ICU 2.0\r
 193      */\r
 194     public final static int SECOND_FIELD = 7;\r
 195 \r
 196     /**\r
 197      * {@icu} FieldPosition selector for 'S' field alignment,\r
 198      * corresponding to the {@link Calendar#MILLISECOND} field.\r
 199      * @stable ICU 3.0\r
 200      */\r
 201     public final static int FRACTIONAL_SECOND_FIELD = 8;\r
 202 \r
 203     /**\r
 204      * Alias for FRACTIONAL_SECOND_FIELD.\r
 205      * @deprecated ICU 3.0 use FRACTIONAL_SECOND_FIELD.\r
 206      */\r
 207     public final static int MILLISECOND_FIELD = FRACTIONAL_SECOND_FIELD;\r
 208 \r
 209     /**\r
 210      * FieldPosition selector for 'E' field alignment,\r
 211      * corresponding to the {@link Calendar#DAY_OF_WEEK} field.\r
 212      * @stable ICU 2.0\r
 213      */\r
 214     public final static int DAY_OF_WEEK_FIELD = 9;\r
 215 \r
 216     /**\r
 217      * FieldPosition selector for 'D' field alignment,\r
 218      * corresponding to the {@link Calendar#DAY_OF_YEAR} field.\r
 219      * @stable ICU 2.0\r
 220      */\r
 221     public final static int DAY_OF_YEAR_FIELD = 10;\r
 222 \r
 223     /**\r
 224      * FieldPosition selector for 'F' field alignment,\r
 225      * corresponding to the {@link Calendar#DAY_OF_WEEK_IN_MONTH} field.\r
 226      * @stable ICU 2.0\r
 227      */\r
 228     public final static int DAY_OF_WEEK_IN_MONTH_FIELD = 11;\r
 229 \r
 230     /**\r
 231      * FieldPosition selector for 'w' field alignment,\r
 232      * corresponding to the {@link Calendar#WEEK_OF_YEAR} field.\r
 233      * @stable ICU 2.0\r
 234      */\r
 235     public final static int WEEK_OF_YEAR_FIELD = 12;\r
 236 \r
 237     /**\r
 238      * FieldPosition selector for 'W' field alignment,\r
 239      * corresponding to the {@link Calendar#WEEK_OF_MONTH} field.\r
 240      * @stable ICU 2.0\r
 241      */\r
 242     public final static int WEEK_OF_MONTH_FIELD = 13;\r
 243 \r
 244     /**\r
 245      * FieldPosition selector for 'a' field alignment,\r
 246      * corresponding to the {@link Calendar#AM_PM} field.\r
 247      * @stable ICU 2.0\r
 248      */\r
 249     public final static int AM_PM_FIELD = 14;\r
 250 \r
 251     /**\r
 252      * FieldPosition selector for 'h' field alignment,\r
 253      * corresponding to the {@link Calendar#HOUR} field.\r
 254      * HOUR1_FIELD is used for the one-based 12-hour clock.\r
 255      * For example, 11:30 PM + 1 hour results in 12:30 AM.\r
 256      * @stable ICU 2.0\r
 257      */\r
 258     public final static int HOUR1_FIELD = 15;\r
 259 \r
 260     /**\r
 261      * FieldPosition selector for 'K' field alignment,\r
 262      * corresponding to the {@link Calendar#HOUR} field.\r
 263      * HOUR0_FIELD is used for the zero-based 12-hour clock.\r
 264      * For example, 11:30 PM + 1 hour results in 00:30 AM.\r
 265      * @stable ICU 2.0\r
 266      */\r
 267     public final static int HOUR0_FIELD = 16;\r
 268 \r
 269     /**\r
 270      * FieldPosition selector for 'z' field alignment,\r
 271      * corresponding to the {@link Calendar#ZONE_OFFSET} and\r
 272      * {@link Calendar#DST_OFFSET} fields.\r
 273      * @stable ICU 2.0\r
 274      */\r
 275     public final static int TIMEZONE_FIELD = 17;\r
 276 \r
 277     /**\r
 278      * {@icu} FieldPosition selector for 'Y' field alignment,\r
 279      * corresponding to the {@link Calendar#YEAR_WOY} field.\r
 280      * @stable ICU 3.0\r
 281      */\r
 282     public final static int YEAR_WOY_FIELD = 18;\r
 283 \r
 284     /**\r
 285      * {@icu} FieldPosition selector for 'e' field alignment,\r
 286      * corresponding to the {@link Calendar#DOW_LOCAL} field.\r
 287      * @stable ICU 3.0\r
 288      */\r
 289     public final static int DOW_LOCAL_FIELD = 19;\r
 290 \r
 291     /**\r
 292      * {@icu} FieldPosition selector for 'u' field alignment,\r
 293      * corresponding to the {@link Calendar#EXTENDED_YEAR} field.\r
 294      * @stable ICU 3.0\r
 295      */\r
 296     public final static int EXTENDED_YEAR_FIELD = 20;\r
 297 \r
 298     /**\r
 299      * {@icu} FieldPosition selector for 'g' field alignment,\r
 300      * corresponding to the {@link Calendar#JULIAN_DAY} field.\r
 301      * @stable ICU 3.0\r
 302      */\r
 303     public final static int JULIAN_DAY_FIELD = 21;\r
 304 \r
 305     /**\r
 306      * {@icu} FieldPosition selector for 'A' field alignment,\r
 307      * corresponding to the {@link Calendar#MILLISECONDS_IN_DAY} field.\r
 308      * @stable ICU 3.0\r
 309      */\r
 310     public final static int MILLISECONDS_IN_DAY_FIELD = 22;\r
 311 \r
 312     /**\r
 313      * {@icu} FieldPosition selector for 'Z' field alignment,\r
 314      * corresponding to the {@link Calendar#ZONE_OFFSET} and\r
 315      * {@link Calendar#DST_OFFSET} fields.\r
 316      * @stable ICU 3.0\r
 317      */\r
 318     public final static int TIMEZONE_RFC_FIELD = 23;\r
 319 \r
 320     /**\r
 321      * {@icu} FieldPosition selector for 'v' field alignment,\r
 322      * corresponding to the {@link Calendar#ZONE_OFFSET} and\r
 323      * {@link Calendar#DST_OFFSET} fields.  This displays the generic zone\r
 324      * name, if available.\r
 325      * @stable ICU 3.4\r
 326      */\r
 327     public final static int TIMEZONE_GENERIC_FIELD = 24;\r
 328 \r
 329     /**\r
 330      * {@icu} FieldPosition selector for 'c' field alignment,\r
 331      * corresponding to the {@link Calendar#DAY_OF_WEEK} field.\r
 332      * This displays the stand alone day name, if available.\r
 333      * @stable ICU 3.4\r
 334      */\r
 335     public final static int STANDALONE_DAY_FIELD = 25;\r
 336 \r
 337     /**\r
 338      * {@icu} FieldPosition selector for 'L' field alignment,\r
 339      * corresponding to the {@link Calendar#MONTH} field.\r
 340      * This displays the stand alone month name, if available.\r
 341      * @stable ICU 3.4\r
 342      */\r
 343     public final static int STANDALONE_MONTH_FIELD = 26;\r
 344 \r
 345     /**\r
 346      * {@icu} FieldPosition selector for 'Q' field alignment,\r
 347      * corresponding to the {@link Calendar#MONTH} field.\r
 348      * This displays the quarter.\r
 349      * @stable ICU 3.6\r
 350      */\r
 351     public final static int QUARTER_FIELD = 27;\r
 352 \r
 353     /**\r
 354      * {@icu} FieldPosition selector for 'q' field alignment,\r
 355      * corresponding to the {@link Calendar#MONTH} field.\r
 356      * This displays the stand alone quarter, if available.\r
 357      * @stable ICU 3.6\r
 358      */\r
 359     public final static int STANDALONE_QUARTER_FIELD = 28;\r
 360 \r
 361     /**\r
 362      * {@icu} FieldPosition selector for 'V' field alignment,\r
 363      * corresponding to the {@link Calendar#ZONE_OFFSET} and\r
 364      * {@link Calendar#DST_OFFSET} fields.  This displays the fallback timezone\r
 365      * name when VVVV is specified, and the short standard or daylight\r
 366      * timezone name ignoring commonlyUsed when a single V is specified.\r
 367      * @stable ICU 3.8\r
 368      */\r
 369     public final static int TIMEZONE_SPECIAL_FIELD = 29;\r
 370 \r
 371     /**\r
 372      * {@icu} Number of FieldPosition selectors for DateFormat.\r
 373      * Valid selectors range from 0 to FIELD_COUNT-1.\r
 374      * @stable ICU 3.0\r
 375      */\r
 376     public final static int FIELD_COUNT = 30; // must == DateFormatSymbols.patternChars.length()\r
 377 \r
 378     // Proclaim serial compatibility with 1.1 FCS\r
 379     private static final long serialVersionUID = 7218322306649953788L;\r
 380 \r
 381     /**\r
 382      * Formats a time object into a time string. Examples of time objects\r
 383      * are a time value expressed in milliseconds and a Date object.\r
 384      * @param obj must be a Number or a Date or a Calendar.\r
 385      * @param toAppendTo the string buffer for the returning time string.\r
 386      * @return the formatted time string.\r
 387      * @param fieldPosition keeps track of the position of the field\r
 388      * within the returned string.\r
 389      * On input: an alignment field,\r
 390      * if desired. On output: the offsets of the alignment field. For\r
 391      * example, given a time text "1996.07.10 AD at 15:08:56 PDT",\r
 392      * if the given fieldPosition is DateFormat.YEAR_FIELD, the\r
 393      * begin index and end index of fieldPosition will be set to\r
 394      * 0 and 4, respectively.\r
 395      * Notice that if the same time field appears\r
 396      * more than once in a pattern, the fieldPosition will be set for the first\r
 397      * occurrence of that time field. For instance, formatting a Date to\r
 398      * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern\r
 399      * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD,\r
 400      * the begin index and end index of fieldPosition will be set to\r
 401      * 5 and 8, respectively, for the first occurrence of the timezone\r
 402      * pattern character 'z'.\r
 403      * @see java.text.Format\r
 404      * @stable ICU 2.0\r
 405      */\r
 406     public final StringBuffer format(Object obj, StringBuffer toAppendTo,\r
 407                                      FieldPosition fieldPosition)\r
 408     {\r
 409         if (obj instanceof Calendar)\r
 410             return format( (Calendar)obj, toAppendTo, fieldPosition );\r
 411         else if (obj instanceof Date)\r
 412             return format( (Date)obj, toAppendTo, fieldPosition );\r
 413         else if (obj instanceof Number)\r
 414             return format( new Date(((Number)obj).longValue()),\r
 415                           toAppendTo, fieldPosition );\r
 416         else\r
 417             throw new IllegalArgumentException("Cannot format given Object (" +\r
 418                                                obj.getClass().getName() + ") as a Date");\r
 419     }\r
 420 \r
 421     /**\r
 422      * Formats a date into a date/time string.\r
 423      * @param cal a Calendar set to the date and time to be formatted\r
 424      * into a date/time string.  When the calendar type is different from\r
 425      * the internal calendar held by this DateFormat instance, the date\r
 426      * and the time zone will be inherited from the input calendar, but\r
 427      * other calendar field values will be calculated by the internal calendar.\r
 428      * @param toAppendTo the string buffer for the returning date/time string.\r
 429      * @param fieldPosition keeps track of the position of the field\r
 430      * within the returned string.\r
 431      * On input: an alignment field,\r
 432      * if desired. On output: the offsets of the alignment field. For\r
 433      * example, given a time text "1996.07.10 AD at 15:08:56 PDT",\r
 434      * if the given fieldPosition is DateFormat.YEAR_FIELD, the\r
 435      * begin index and end index of fieldPosition will be set to\r
 436      * 0 and 4, respectively.\r
 437      * Notice that if the same time field appears\r
 438      * more than once in a pattern, the fieldPosition will be set for the first\r
 439      * occurrence of that time field. For instance, formatting a Date to\r
 440      * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern\r
 441      * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD,\r
 442      * the begin index and end index of fieldPosition will be set to\r
 443      * 5 and 8, respectively, for the first occurrence of the timezone\r
 444      * pattern character 'z'.\r
 445      * @return the formatted date/time string.\r
 446      * @stable ICU 2.0\r
 447      */\r
 448     public abstract StringBuffer format(Calendar cal, StringBuffer toAppendTo,\r
 449                                         FieldPosition fieldPosition);\r
 450 \r
 451     /**\r
 452      * Formats a Date into a date/time string.\r
 453      * @param date a Date to be formatted into a date/time string.\r
 454      * @param toAppendTo the string buffer for the returning date/time string.\r
 455      * @param fieldPosition keeps track of the position of the field\r
 456      * within the returned string.\r
 457      * On input: an alignment field,\r
 458      * if desired. On output: the offsets of the alignment field. For\r
 459      * example, given a time text "1996.07.10 AD at 15:08:56 PDT",\r
 460      * if the given fieldPosition is DateFormat.YEAR_FIELD, the\r
 461      * begin index and end index of fieldPosition will be set to\r
 462      * 0 and 4, respectively.\r
 463      * Notice that if the same time field appears\r
 464      * more than once in a pattern, the fieldPosition will be set for the first\r
 465      * occurrence of that time field. For instance, formatting a Date to\r
 466      * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern\r
 467      * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD,\r
 468      * the begin index and end index of fieldPosition will be set to\r
 469      * 5 and 8, respectively, for the first occurrence of the timezone\r
 470      * pattern character 'z'.\r
 471      * @return the formatted date/time string.\r
 472      * @stable ICU 2.0\r
 473      */\r
 474     public StringBuffer format(Date date, StringBuffer toAppendTo,\r
 475                                      FieldPosition fieldPosition) {\r
 476         // Use our Calendar object\r
 477         calendar.setTime(date);\r
 478         return format(calendar, toAppendTo, fieldPosition);\r
 479     }\r
 480 \r
 481     /**\r
 482      * Formats a Date into a date/time string.\r
 483      * @param date the time value to be formatted into a time string.\r
 484      * @return the formatted time string.\r
 485      * @stable ICU 2.0\r
 486      */\r
 487     public final String format(Date date)\r
 488     {\r
 489         return format(date, new StringBuffer(64),new FieldPosition(0)).toString();\r
 490     }\r
 491 \r
 492     /**\r
 493      * Parses a date/time string.\r
 494      *\r
 495      * @param text  The date/time string to be parsed\r
 496      *\r
 497      * @return      A Date, or null if the input could not be parsed\r
 498      *\r
 499      * @exception  ParseException  If the given string cannot be parsed as a date.\r
 500      *\r
 501      * @see #parse(String, ParsePosition)\r
 502      * @stable ICU 2.0\r
 503      */\r
 504     public Date parse(String text) throws ParseException\r
 505     {\r
 506         ParsePosition pos = new ParsePosition(0);\r
 507         Date result = parse(text, pos);\r
 508         if (pos.getIndex() == 0) // ICU4J\r
 509             throw new ParseException("Unparseable date: \"" + text + "\"" ,\r
 510                                      pos.getErrorIndex()); // ICU4J\r
 511         return result;\r
 512     }\r
 513 \r
 514     /**\r
 515      * Parses a date/time string according to the given parse position.\r
 516      * For example, a time text "07/10/96 4:5 PM, PDT" will be parsed\r
 517      * into a Calendar that is equivalent to Date(837039928046).  The\r
 518      * caller should clear the calendar before calling this method,\r
 519      * unless existing field information is to be kept.\r
 520      *\r
 521      * <p> By default, parsing is lenient: If the input is not in the form used\r
 522      * by this object's format method but can still be parsed as a date, then\r
 523      * the parse succeeds.  Clients may insist on strict adherence to the\r
 524      * format by calling setLenient(false).\r
 525      *\r
 526      * @see #setLenient(boolean)\r
 527      *\r
 528      * @param text  The date/time string to be parsed\r
 529      *\r
 530      * @param cal   The calendar into which parsed data will be stored.\r
 531      *              In general, this should be cleared before calling this\r
 532      *              method.  If this parse fails, the calendar may still\r
 533      *              have been modified.  When the calendar type is different\r
 534      *              from the internal calendar held by this DateFormat\r
 535      *              instance, calendar field values will be parsed based\r
 536      *              on the internal calendar initialized with the time and\r
 537      *              the time zone taken from this calendar, then the\r
 538      *              parse result (time in milliseconds and time zone) will\r
 539      *              be set back to this calendar.\r
 540      *\r
 541      * @param pos   On input, the position at which to start parsing; on\r
 542      *              output, the position at which parsing terminated, or the\r
 543      *              start position if the parse failed.\r
 544      * @stable ICU 2.0\r
 545      */\r
 546     public abstract void parse(String text, Calendar cal, ParsePosition pos);\r
 547 \r
 548     /**\r
 549      * Parses a date/time string according to the given parse position.  For\r
 550      * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date\r
 551      * that is equivalent to Date(837039928046).\r
 552      *\r
 553      * <p> By default, parsing is lenient: If the input is not in the form used\r
 554      * by this object's format method but can still be parsed as a date, then\r
 555      * the parse succeeds.  Clients may insist on strict adherence to the\r
 556      * format by calling setLenient(false).\r
 557      *\r
 558      * @see #setLenient(boolean)\r
 559      *\r
 560      * @param text  The date/time string to be parsed\r
 561      *\r
 562      * @param pos   On input, the position at which to start parsing; on\r
 563      *              output, the position at which parsing terminated, or the\r
 564      *              start position if the parse failed.\r
 565      *\r
 566      * @return      A Date, or null if the input could not be parsed\r
 567      * @stable ICU 2.0\r
 568      */\r
 569     public Date parse(String text, ParsePosition pos) {\r
 570         Date result = null;\r
 571         int start = pos.getIndex();\r
 572         TimeZone tzsav = calendar.getTimeZone();\r
 573         calendar.clear();\r
 574         parse(text, calendar, pos);\r
 575         if (pos.getIndex() != start) {\r
 576             try {\r
 577                 result = calendar.getTime();\r
 578             } catch (IllegalArgumentException e) {\r
 579                 // This occurs if the calendar is non-lenient and there is\r
 580                 // an out-of-range field.  We don't know which field was\r
 581                 // illegal so we set the error index to the start.\r
 582                 pos.setIndex(start);\r
 583                 pos.setErrorIndex(start);\r
 584             }\r
 585         }\r
 586         // Restore TimeZone\r
 587         calendar.setTimeZone(tzsav);\r
 588         return result;\r
 589     }\r
 590 \r
 591     /**\r
 592      * Parses a date/time string into an Object.  This convenience method simply\r
 593      * calls parse(String, ParsePosition).\r
 594      *\r
 595      * @see #parse(String, ParsePosition)\r
 596      * @stable ICU 2.0\r
 597      */\r
 598     public Object parseObject (String source, ParsePosition pos)\r
 599     {\r
 600         return parse(source, pos);\r
 601     }\r
 602 \r
 603     /**\r
 604      * {@icu} Constant for empty style pattern.\r
 605      * @stable ICU 3.8\r
 606      */\r
 607     public static final int NONE = -1;\r
 608 \r
 609     /**\r
 610      * Constant for full style pattern.\r
 611      * @stable ICU 2.0\r
 612      */\r
 613     public static final int FULL = 0;\r
 614 \r
 615     /**\r
 616      * Constant for long style pattern.\r
 617      * @stable ICU 2.0\r
 618      */\r
 619     public static final int LONG = 1;\r
 620 \r
 621     /**\r
 622      * Constant for medium style pattern.\r
 623      * @stable ICU 2.0\r
 624      */\r
 625     public static final int MEDIUM = 2;\r
 626 \r
 627     /**\r
 628      * Constant for short style pattern.\r
 629      * @stable ICU 2.0\r
 630      */\r
 631     public static final int SHORT = 3;\r
 632 \r
 633     /**\r
 634      * Constant for default style pattern.  Its value is MEDIUM.\r
 635      * @stable ICU 2.0\r
 636      */\r
 637     public static final int DEFAULT = MEDIUM;\r
 638 \r
 639     /**\r
 640      * {@icu} Constant for relative style mask.\r
 641      * @stable ICU 3.8\r
 642      */\r
 643     public static final int RELATIVE = (1 << 7);\r
 644 \r
 645     /**\r
 646      * {@icu} Constant for relative full style pattern.\r
 647      * @stable ICU 3.8\r
 648      */\r
 649     public static final int RELATIVE_FULL = RELATIVE | FULL;\r
 650 \r
 651     /**\r
 652      * {@icu} Constant for relative style pattern.\r
 653      * @stable ICU 3.8\r
 654      */\r
 655     public static final int RELATIVE_LONG = RELATIVE | LONG;\r
 656 \r
 657     /**\r
 658      * {@icu} Constant for relative style pattern.\r
 659      * @stable ICU 3.8\r
 660      */\r
 661     public static final int RELATIVE_MEDIUM = RELATIVE | MEDIUM;\r
 662 \r
 663     /**\r
 664      * {@icu} Constant for relative style pattern.\r
 665      * @stable ICU 3.8\r
 666      */\r
 667     public static final int RELATIVE_SHORT = RELATIVE | SHORT;\r
 668 \r
 669     /**\r
 670      * {@icu} Constant for relative default style pattern.\r
 671      * @stable ICU 3.8\r
 672      */\r
 673     public static final int RELATIVE_DEFAULT = RELATIVE | DEFAULT;\r
 674 \r
 675     /* Below are pre-defined skeletons\r
 676      *\r
 677      * <P>\r
 678      * A skeleton\r
 679      * <ul>\r
 680      * <li>\r
 681      * 1. only keeps the field pattern letter and ignores all other parts\r
 682      *    in a pattern, such as space, punctuations, and string literals.\r
 683      * <li>\r
 684      * 2. hides the order of fields.\r
 685      * <li>\r
 686      * 3. might hide a field's pattern letter length.\r
 687      *\r
 688      *    For those non-digit calendar fields, the pattern letter length is\r
 689      *    important, such as MMM, MMMM, and MMMMM; E and EEEE,\r
 690      *    and the field's pattern letter length is honored.\r
 691      *\r
 692      *    For the digit calendar fields,  such as M or MM, d or dd, yy or yyyy,\r
 693      *    the field pattern length is ignored and the best match, which is\r
 694      *    defined in date time patterns, will be returned without honor\r
 695      *    the field pattern letter length in skeleton.\r
 696      * </ul>\r
 697      */\r
 698     /**\r
 699      * {@icu} Constant for date pattern with minute and second.\r
 700      * @stable ICU 4.0\r
 701      */\r
 702     public static final String MINUTE_SECOND = "ms";\r
 703 \r
 704     /**\r
 705      * {@icu} Constant for date pattern with hour and minute in 24-hour presentation.\r
 706      * @stable ICU 4.0\r
 707      */\r
 708     public static final String HOUR24_MINUTE = "Hm";\r
 709 \r
 710     /**\r
 711      * {@icu} Constant for date pattern with hour, minute, and second in\r
 712      * 24-hour presentation.\r
 713      * @stable ICU 4.0\r
 714      */\r
 715     public static final String HOUR24_MINUTE_SECOND = "Hms";\r
 716 \r
 717     /**\r
 718      * {@icu} Constant for date pattern with hour, minute, and second.\r
 719      * @stable ICU 4.0\r
 720      */\r
 721     public static final String HOUR_MINUTE_SECOND = "hms";\r
 722 \r
 723     /**\r
 724      * {@icu} Constant for date pattern with standalone month.\r
 725      * @stable ICU 4.0\r
 726      */\r
 727     public static final String STANDALONE_MONTH = "LLLL";\r
 728 \r
 729     /**\r
 730      * {@icu} Constant for date pattern with standalone abbreviated month.\r
 731      * @stable ICU 4.0\r
 732      */\r
 733     public static final String ABBR_STANDALONE_MONTH = "LLL";\r
 734 \r
 735     /**\r
 736      * {@icu} Constant for date pattern with year and quarter.\r
 737      * @stable ICU 4.0\r
 738      */\r
 739     public static final String YEAR_QUARTER = "yQQQ";\r
 740 \r
 741     /**\r
 742      * {@icu} Constant for date pattern with year and abbreviated quarter.\r
 743      * @stable ICU 4.0\r
 744      */\r
 745     public static final String YEAR_ABBR_QUARTER = "yQ";\r
 746 \r
 747 \r
 748     /* Below are skeletons that date interval pre-defined in resource file.\r
 749      * Users are encouraged to use them in date interval format factory methods.\r
 750      */\r
 751     /**\r
 752      * {@icu} Constant for date pattern with hour and minute.\r
 753      * @stable ICU 4.0\r
 754      */\r
 755     public static final String HOUR_MINUTE = "hm";\r
 756 \r
 757     /**\r
 758      * {@icu} Constant for date pattern with year.\r
 759      * @stable ICU 4.0\r
 760      */\r
 761     public static final String YEAR = "y";\r
 762 \r
 763     /**\r
 764      * {@icu} Constant for date pattern with day.\r
 765      * @stable ICU 4.0\r
 766      */\r
 767     public static final String DAY = "d";\r
 768 \r
 769     /**\r
 770      * {@icu} Constant for date pattern with numeric month, weekday, and day.\r
 771      * @stable ICU 4.0\r
 772      */\r
 773     public static final String NUM_MONTH_WEEKDAY_DAY = "MEd";\r
 774 \r
 775     /**\r
 776      * {@icu} Constant for date pattern with year and numeric month.\r
 777      * @stable ICU 4.0\r
 778      */\r
 779     public static final String YEAR_NUM_MONTH = "yM";\r
 780 \r
 781     /**\r
 782      * {@icu} Constant for date pattern with numeric month and day.\r
 783      * @stable ICU 4.0\r
 784      */\r
 785     public static final String NUM_MONTH_DAY = "Md";\r
 786 \r
 787     /**\r
 788      * {@icu} Constant for date pattern with year, numeric month, weekday, and day.\r
 789      * @stable ICU 4.0\r
 790      */\r
 791     public static final String YEAR_NUM_MONTH_WEEKDAY_DAY = "yMEd";\r
 792 \r
 793     /**\r
 794      * {@icu} Constant for date pattern with abbreviated month, weekday, and day.\r
 795      * @stable ICU 4.0\r
 796      */\r
 797     public static final String ABBR_MONTH_WEEKDAY_DAY = "MMMEd";\r
 798 \r
 799     /**\r
 800      * {@icu} Constant for date pattern with year and month.\r
 801      * @stable ICU 4.0\r
 802      */\r
 803     public static final String YEAR_MONTH = "yMMMM";\r
 804 \r
 805     /**\r
 806      * {@icu} Constant for date pattern with year and abbreviated month.\r
 807      * @stable ICU 4.0\r
 808      */\r
 809     public static final String YEAR_ABBR_MONTH = "yMMM";\r
 810 \r
 811     /**\r
 812      * {@icu} Constant for date pattern having month and day.\r
 813      * @stable ICU 4.0\r
 814      */\r
 815     public static final String MONTH_DAY = "MMMMd";\r
 816 \r
 817     /**\r
 818      * {@icu} Constant for date pattern with abbreviated month and day.\r
 819      * @stable ICU 4.0\r
 820      */\r
 821     public static final String ABBR_MONTH_DAY = "MMMd";\r
 822 \r
 823     /**\r
 824      * {@icu} Constant for date pattern with month, weekday, and day.\r
 825      * @stable ICU 4.0\r
 826      */\r
 827     public static final String MONTH_WEEKDAY_DAY = "MMMMEEEEd";\r
 828 \r
 829     /**\r
 830      * {@icu} Constant for date pattern with year, abbreviated month, weekday,\r
 831      * and day.\r
 832      * @stable ICU 4.0\r
 833      */\r
 834     public static final String YEAR_ABBR_MONTH_WEEKDAY_DAY = "yMMMEd";\r
 835 \r
 836     /**\r
 837      * {@icu} Constant for date pattern with year, month, weekday, and day.\r
 838      * @stable ICU 4.0\r
 839      */\r
 840     public static final String YEAR_MONTH_WEEKDAY_DAY = "yMMMMEEEEd";\r
 841 \r
 842     /**\r
 843      * {@icu} Constant for date pattern with year, month, and day.\r
 844      * @stable ICU 4.0\r
 845      */\r
 846     public static final String YEAR_MONTH_DAY = "yMMMMd";\r
 847 \r
 848     /**\r
 849      * {@icu} Constant for date pattern with year, abbreviated month, and day.\r
 850      * @stable ICU 4.0\r
 851      */\r
 852     public static final String YEAR_ABBR_MONTH_DAY = "yMMMd";\r
 853 \r
 854     /**\r
 855      * {@icu} Constant for date pattern with year, numeric month, and day.\r
 856      * @stable ICU 4.0\r
 857      */\r
 858     public static final String YEAR_NUM_MONTH_DAY = "yMd";\r
 859 \r
 860     /**\r
 861      * {@icu} Constant for date pattern with numeric month.\r
 862      * @stable ICU 4.0\r
 863      */\r
 864     public static final String NUM_MONTH = "M";\r
 865 \r
 866     /**\r
 867      * {@icu} Constant for date pattern with abbreviated month.\r
 868      * @stable ICU 4.0\r
 869      */\r
 870     public static final String ABBR_MONTH = "MMM";\r
 871 \r
 872     /**\r
 873      * {@icu} Constant for date pattern with month.\r
 874      * @stable ICU 4.0\r
 875      */\r
 876     public static final String MONTH = "MMMM";\r
 877 \r
 878     /**\r
 879      * {@icu} Constant for date pattern with hour, minute, and generic timezone.\r
 880      * @stable ICU 4.0\r
 881      */\r
 882     public static final String HOUR_MINUTE_GENERIC_TZ = "hmv";\r
 883 \r
 884     /**\r
 885      * {@icu} Constant for date pattern with hour, minute, and timezone.\r
 886      * @stable ICU 4.0\r
 887      */\r
 888     public static final String HOUR_MINUTE_TZ = "hmz";\r
 889 \r
 890     /**\r
 891      * {@icu} Constant for date pattern with hour.\r
 892      * @stable ICU 4.0\r
 893      */\r
 894     public static final String HOUR = "h";\r
 895 \r
 896     /**\r
 897      * {@icu} Constant for date pattern with hour and generic timezone.\r
 898      * @stable ICU 4.0\r
 899      */\r
 900     public static final String HOUR_GENERIC_TZ = "hv";\r
 901 \r
 902     /**\r
 903      * {@icu} Constant for date pattern with hour and timezone.\r
 904      * @stable ICU 4.0\r
 905      */\r
 906     public static final String HOUR_TZ = "hz";\r
 907 \r
 908     /**\r
 909      * Gets the time formatter with the default formatting style\r
 910      * for the default locale.\r
 911      * @return a time formatter.\r
 912      * @stable ICU 2.0\r
 913      */\r
 914     public final static DateFormat getTimeInstance()\r
 915     {\r
 916         return get(-1, DEFAULT, ULocale.getDefault());\r
 917     }\r
 918 \r
 919     /**\r
 920      * Returns the time formatter with the given formatting style\r
 921      * for the default locale.\r
 922      * @param style the given formatting style. For example,\r
 923      * SHORT for "h:mm a" in the US locale.\r
 924      * @return a time formatter.\r
 925      * @stable ICU 2.0\r
 926      */\r
 927     public final static DateFormat getTimeInstance(int style)\r
 928     {\r
 929         return get(-1, style, ULocale.getDefault());\r
 930     }\r
 931 \r
 932     /**\r
 933      * Returns the time formatter with the given formatting style\r
 934      * for the given locale.\r
 935      * @param style the given formatting style. For example,\r
 936      * SHORT for "h:mm a" in the US locale.\r
 937      * @param aLocale the given locale.\r
 938      * @return a time formatter.\r
 939      * @stable ICU 2.0\r
 940      */\r
 941     public final static DateFormat getTimeInstance(int style,\r
 942                                                  Locale aLocale)\r
 943     {\r
 944         return get(-1, style, ULocale.forLocale(aLocale));\r
 945     }\r
 946 \r
 947     /**\r
 948      * Returns the time formatter with the given formatting style\r
 949      * for the given locale.\r
 950      * @param style the given formatting style. For example,\r
 951      * SHORT for "h:mm a" in the US locale.\r
 952      * @param locale the given ulocale.\r
 953      * @return a time formatter.\r
 954      * @stable ICU 3.2\r
 955      */\r
 956     public final static DateFormat getTimeInstance(int style,\r
 957                                                  ULocale locale)\r
 958     {\r
 959         return get(-1, style, locale);\r
 960     }\r
 961 \r
 962     /**\r
 963      * Returns the date formatter with the default formatting style\r
 964      * for the default locale.\r
 965      * @return a date formatter.\r
 966      * @stable ICU 2.0\r
 967      */\r
 968     public final static DateFormat getDateInstance()\r
 969     {\r
 970         return get(DEFAULT, -1, ULocale.getDefault());\r
 971     }\r
 972 \r
 973     /**\r
 974      * Returns the date formatter with the given formatting style\r
 975      * for the default locale.\r
 976      * @param style the given formatting style. For example,\r
 977      * SHORT for "M/d/yy" in the US locale.\r
 978      * @return a date formatter.\r
 979      * @stable ICU 2.0\r
 980      */\r
 981     public final static DateFormat getDateInstance(int style)\r
 982     {\r
 983         return get(style, -1, ULocale.getDefault());\r
 984     }\r
 985 \r
 986     /**\r
 987      * Returns the date formatter with the given formatting style\r
 988      * for the given locale.\r
 989      * @param style the given formatting style. For example,\r
 990      * SHORT for "M/d/yy" in the US locale.\r
 991      * @param aLocale the given locale.\r
 992      * @return a date formatter.\r
 993      * @stable ICU 2.0\r
 994      */\r
 995     public final static DateFormat getDateInstance(int style,\r
 996                                                  Locale aLocale)\r
 997     {\r
 998         return get(style, -1, ULocale.forLocale(aLocale));\r
 999     }\r
1000 \r
1001     /**\r
1002      * Returns the date formatter with the given formatting style\r
1003      * for the given locale.\r
1004      * @param style the given formatting style. For example,\r
1005      * SHORT for "M/d/yy" in the US locale.\r
1006      * @param locale the given ulocale.\r
1007      * @return a date formatter.\r
1008      * @stable ICU 3.2\r
1009      */\r
1010     public final static DateFormat getDateInstance(int style,\r
1011                                                  ULocale locale)\r
1012     {\r
1013         return get(style, -1, locale);\r
1014     }\r
1015 \r
1016     /**\r
1017      * Returns the date/time formatter with the default formatting style\r
1018      * for the default locale.\r
1019      * @return a date/time formatter.\r
1020      * @stable ICU 2.0\r
1021      */\r
1022     public final static DateFormat getDateTimeInstance()\r
1023     {\r
1024         return get(DEFAULT, DEFAULT, ULocale.getDefault());\r
1025     }\r
1026 \r
1027     /**\r
1028      * Returns the date/time formatter with the given date and time\r
1029      * formatting styles for the default locale.\r
1030      * @param dateStyle the given date formatting style. For example,\r
1031      * SHORT for "M/d/yy" in the US locale.\r
1032      * @param timeStyle the given time formatting style. For example,\r
1033      * SHORT for "h:mm a" in the US locale.\r
1034      * @return a date/time formatter.\r
1035      * @stable ICU 2.0\r
1036      */\r
1037     public final static DateFormat getDateTimeInstance(int dateStyle,\r
1038                                                        int timeStyle)\r
1039     {\r
1040         return get(dateStyle, timeStyle, ULocale.getDefault());\r
1041     }\r
1042 \r
1043     /**\r
1044      * Returns the date/time formatter with the given formatting styles\r
1045      * for the given locale.\r
1046      * @param dateStyle the given date formatting style.\r
1047      * @param timeStyle the given time formatting style.\r
1048      * @param aLocale the given locale.\r
1049      * @return a date/time formatter.\r
1050      * @stable ICU 2.0\r
1051      */\r
1052     public final static DateFormat getDateTimeInstance(\r
1053         int dateStyle, int timeStyle, Locale aLocale)\r
1054     {\r
1055         return get(dateStyle, timeStyle, ULocale.forLocale(aLocale));\r
1056     }\r
1057 \r
1058     /**\r
1059      * Returns the date/time formatter with the given formatting styles\r
1060      * for the given locale.\r
1061      * @param dateStyle the given date formatting style.\r
1062      * @param timeStyle the given time formatting style.\r
1063      * @param locale the given ulocale.\r
1064      * @return a date/time formatter.\r
1065      * @stable ICU 3.2\r
1066      */\r
1067     public final static DateFormat getDateTimeInstance(\r
1068         int dateStyle, int timeStyle, ULocale locale)\r
1069     {\r
1070         return get(dateStyle, timeStyle, locale);\r
1071     }\r
1072 \r
1073     /**\r
1074      * Returns a default date/time formatter that uses the SHORT style for both the\r
1075      * date and the time.\r
1076      * @stable ICU 2.0\r
1077      */\r
1078     public final static DateFormat getInstance() {\r
1079         return getDateTimeInstance(SHORT, SHORT);\r
1080     }\r
1081 \r
1082     /**\r
1083      * Returns the set of locales for which DateFormats are installed.\r
1084      * @return the set of locales for which DateFormats are installed.\r
1085      * @stable ICU 2.0\r
1086      */\r
1087     public static Locale[] getAvailableLocales()\r
1088     {\r
1089         return ICUResourceBundle.getAvailableLocales();\r
1090     }\r
1091 \r
1092     /**\r
1093      * {@icu} Returns the set of locales for which DateFormats are installed.\r
1094      * @return the set of locales for which DateFormats are installed.\r
1095      * @draft ICU 3.2 (retain)\r
1096      * @provisional This API might change or be removed in a future release.\r
1097      */\r
1098     public static ULocale[] getAvailableULocales()\r
1099     {\r
1100         return ICUResourceBundle.getAvailableULocales();\r
1101     }\r
1102 \r
1103     /**\r
1104      * Sets the calendar to be used by this date format.  Initially, the default\r
1105      * calendar for the specified or default locale is used.\r
1106      * @param newCalendar the new Calendar to be used by the date format\r
1107      * @stable ICU 2.0\r
1108      */\r
1109     public void setCalendar(Calendar newCalendar)\r
1110     {\r
1111         this.calendar = newCalendar;\r
1112     }\r
1113 \r
1114     /**\r
1115      * Returns the calendar associated with this date/time formatter.\r
1116      * @return the calendar associated with this date/time formatter.\r
1117      * @stable ICU 2.0\r
1118      */\r
1119     public Calendar getCalendar()\r
1120     {\r
1121         return calendar;\r
1122     }\r
1123 \r
1124     /**\r
1125      * Sets the number formatter.\r
1126      * @param newNumberFormat the given new NumberFormat.\r
1127      * @stable ICU 2.0\r
1128      */\r
1129     public void setNumberFormat(NumberFormat newNumberFormat)\r
1130     {\r
1131         this.numberFormat = newNumberFormat;\r
1132         /*In order to parse String like "11.10.2001" to DateTime correctly\r
1133           in Locale("fr","CH") [Richard/GCL]\r
1134         */\r
1135         this.numberFormat.setParseIntegerOnly(true);\r
1136     }\r
1137 \r
1138     /**\r
1139      * Returns the number formatter which this date/time formatter uses to\r
1140      * format and parse a time.\r
1141      * @return the number formatter which this date/time formatter uses.\r
1142      * @stable ICU 2.0\r
1143      */\r
1144     public NumberFormat getNumberFormat()\r
1145     {\r
1146         return numberFormat;\r
1147     }\r
1148 \r
1149     /**\r
1150      * Sets the time zone for the calendar of this DateFormat object.\r
1151      * @param zone the given new time zone.\r
1152      * @stable ICU 2.0\r
1153      */\r
1154     public void setTimeZone(TimeZone zone)\r
1155     {\r
1156         calendar.setTimeZone(zone);\r
1157     }\r
1158 \r
1159     /**\r
1160      * Returns the time zone.\r
1161      * @return the time zone associated with the calendar of DateFormat.\r
1162      * @stable ICU 2.0\r
1163      */\r
1164     public TimeZone getTimeZone()\r
1165     {\r
1166         return calendar.getTimeZone();\r
1167     }\r
1168 \r
1169     /**\r
1170      * Specifies whether date/time parsing is to be lenient.  With\r
1171      * lenient parsing, the parser may use heuristics to interpret inputs that\r
1172      * do not precisely match this object's format.  With strict parsing,\r
1173      * inputs must match this object's format.\r
1174      * @param lenient when true, parsing is lenient\r
1175      * @see com.ibm.icu.util.Calendar#setLenient\r
1176      * @stable ICU 2.0\r
1177      */\r
1178     public void setLenient(boolean lenient)\r
1179     {\r
1180         calendar.setLenient(lenient);\r
1181     }\r
1182 \r
1183     /**\r
1184      * Returns whether date/time parsing is lenient.\r
1185      * @stable ICU 2.0\r
1186      */\r
1187     public boolean isLenient()\r
1188     {\r
1189         return calendar.isLenient();\r
1190     }\r
1191 \r
1192     /**\r
1193      * Overrides hashCode.\r
1194      * @stable ICU 2.0\r
1195      */\r
1196     ///CLOVER:OFF\r
1197     // turn off code coverage since all subclasses override this\r
1198     public int hashCode() {\r
1199         return numberFormat.hashCode();\r
1200         // just enough fields for a reasonable distribution\r
1201     }\r
1202     ///CLOVER:ON\r
1203 \r
1204     /**\r
1205      * Overrides equals.\r
1206      * @stable ICU 2.0\r
1207      */\r
1208     public boolean equals(Object obj) {\r
1209         if (this == obj) return true;\r
1210         if (obj == null || getClass() != obj.getClass()) return false;\r
1211         DateFormat other = (DateFormat) obj;\r
1212         return (calendar.isEquivalentTo(other.calendar) &&\r
1213                 numberFormat.equals(other.numberFormat));\r
1214     }\r
1215 \r
1216     /**\r
1217      * Overrides clone.\r
1218      * @stable ICU 2.0\r
1219      */\r
1220     public Object clone()\r
1221     {\r
1222         DateFormat other = (DateFormat) super.clone();\r
1223         other.calendar = (Calendar) calendar.clone();\r
1224         other.numberFormat = (NumberFormat) numberFormat.clone();\r
1225         return other;\r
1226     }\r
1227 \r
1228     /**\r
1229      * Creates a DateFormat with the given time and/or date style in the given\r
1230      * locale.\r
1231      * @param dateStyle a value from 0 to 3 indicating the time format,\r
1232      * or -1 to indicate no date\r
1233      * @param timeStyle a value from 0 to 3 indicating the time format,\r
1234      * or -1 to indicate no time\r
1235      * @param loc the locale for the format\r
1236      */\r
1237     private static DateFormat get(int dateStyle, int timeStyle, ULocale loc) {\r
1238         if((timeStyle != -1 && (timeStyle & RELATIVE)>0) ||\r
1239            (dateStyle != -1 && (dateStyle & RELATIVE)>0)) {\r
1240             RelativeDateFormat r = new RelativeDateFormat(timeStyle, dateStyle /* offset? */, loc);\r
1241             return r;\r
1242         }\r
1243 \r
1244         if (timeStyle < -1 || timeStyle > 3) {\r
1245             throw new IllegalArgumentException("Illegal time style " + timeStyle);\r
1246         }\r
1247         if (dateStyle < -1 || dateStyle > 3) {\r
1248             throw new IllegalArgumentException("Illegal date style " + dateStyle);\r
1249         }\r
1250         try {\r
1251             Calendar cal = Calendar.getInstance(loc);\r
1252             DateFormat result = cal.getDateTimeFormat(dateStyle, timeStyle, loc);\r
1253             result.setLocale(cal.getLocale(ULocale.VALID_LOCALE),\r
1254                  cal.getLocale(ULocale.ACTUAL_LOCALE));\r
1255             return result;\r
1256         } catch (MissingResourceException e) {\r
1257             ///CLOVER:OFF\r
1258             // coverage requires separate run with no data, so skip\r
1259             return new SimpleDateFormat("M/d/yy h:mm a");\r
1260             ///CLOVER:ON\r
1261         }\r
1262     }\r
1263 \r
1264     /**\r
1265      * Creates a new date format.\r
1266      * @stable ICU 2.0\r
1267      */\r
1268     protected DateFormat() {}\r
1269 \r
1270     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
1271 \r
1272     //-------------------------------------------------------------------------\r
1273     // Public static interface for creating custon DateFormats for different\r
1274     // types of Calendars.\r
1275     //-------------------------------------------------------------------------\r
1276 \r
1277     /**\r
1278      * Creates a {@link DateFormat} object that can be used to format dates in\r
1279      * the calendar system specified by <code>cal</code>.\r
1280      * <p>\r
1281      * @param cal   The calendar system for which a date format is desired.\r
1282      *\r
1283      * @param dateStyle The type of date format desired.  This can be\r
1284      *              {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM},\r
1285      *              etc.\r
1286      *\r
1287      * @param locale The locale for which the date format is desired.\r
1288      * @stable ICU 2.0\r
1289      */\r
1290     static final public DateFormat getDateInstance(Calendar cal, int dateStyle, Locale locale)\r
1291     {\r
1292         return getDateTimeInstance(cal, dateStyle, -1, ULocale.forLocale(locale));\r
1293     }\r
1294 \r
1295     /**\r
1296      * Creates a {@link DateFormat} object that can be used to format dates in\r
1297      * the calendar system specified by <code>cal</code>.\r
1298      * <p>\r
1299      * @param cal   The calendar system for which a date format is desired.\r
1300      *\r
1301      * @param dateStyle The type of date format desired.  This can be\r
1302      *              {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM},\r
1303      *              etc.\r
1304      *\r
1305      * @param locale The locale for which the date format is desired.\r
1306      * @stable ICU 3.2\r
1307      */\r
1308     static final public DateFormat getDateInstance(Calendar cal, int dateStyle, ULocale locale)\r
1309     {\r
1310         return getDateTimeInstance(cal, dateStyle, -1, locale);\r
1311     }\r
1312 \r
1313     /**\r
1314      * Creates a {@link DateFormat} object that can be used to format times in\r
1315      * the calendar system specified by <code>cal</code>.\r
1316      * <p>\r
1317      * <b>Note:</b> When this functionality is moved into the core JDK, this method\r
1318      * will probably be replaced by a new overload of {@link DateFormat#getInstance}.\r
1319      * <p>\r
1320      * @param cal   The calendar system for which a time format is desired.\r
1321      *\r
1322      * @param timeStyle The type of time format desired.  This can be\r
1323      *              {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM},\r
1324      *              etc.\r
1325      *\r
1326      * @param locale The locale for which the time format is desired.\r
1327      *\r
1328      * @see DateFormat#getTimeInstance\r
1329      * @stable ICU 2.0\r
1330      */\r
1331     static final public DateFormat getTimeInstance(Calendar cal, int timeStyle, Locale locale)\r
1332     {\r
1333         return getDateTimeInstance(cal, -1, timeStyle, ULocale.forLocale(locale));\r
1334     }\r
1335 \r
1336     /**\r
1337      * Creates a {@link DateFormat} object that can be used to format times in\r
1338      * the calendar system specified by <code>cal</code>.\r
1339      * <p>\r
1340      * <b>Note:</b> When this functionality is moved into the core JDK, this method\r
1341      * will probably be replaced by a new overload of {@link DateFormat#getInstance}.\r
1342      * <p>\r
1343      * @param cal   The calendar system for which a time format is desired.\r
1344      *\r
1345      * @param timeStyle The type of time format desired.  This can be\r
1346      *              {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM},\r
1347      *              etc.\r
1348      *\r
1349      * @param locale The locale for which the time format is desired.\r
1350      *\r
1351      * @see DateFormat#getTimeInstance\r
1352      * @stable ICU 3.2\r
1353      */\r
1354     static final public DateFormat getTimeInstance(Calendar cal, int timeStyle, ULocale locale)\r
1355     {\r
1356         return getDateTimeInstance(cal, -1, timeStyle, locale);\r
1357     }\r
1358 \r
1359     /**\r
1360      * Creates a {@link DateFormat} object that can be used to format dates and times in\r
1361      * the calendar system specified by <code>cal</code>.\r
1362      * <p>\r
1363      * <b>Note:</b> When this functionality is moved into the core JDK, this method\r
1364      * will probably be replaced by a new overload of {@link DateFormat#getInstance}.\r
1365      * <p>\r
1366      * @param cal   The calendar system for which a date/time format is desired.\r
1367      *\r
1368      * @param dateStyle The type of date format desired.  This can be\r
1369      *              {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM},\r
1370      *              etc.\r
1371      *\r
1372      * @param timeStyle The type of time format desired.  This can be\r
1373      *              {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM},\r
1374      *              etc.\r
1375      *\r
1376      * @param locale The locale for which the date/time format is desired.\r
1377      *\r
1378      * @see DateFormat#getDateTimeInstance\r
1379      * @stable ICU 2.0\r
1380      */\r
1381     static final public DateFormat getDateTimeInstance(Calendar cal, int dateStyle,\r
1382                                                  int timeStyle, Locale locale)\r
1383     {\r
1384         return cal.getDateTimeFormat(dateStyle, timeStyle, ULocale.forLocale(locale));\r
1385     }\r
1386 \r
1387     /**\r
1388      * Creates a {@link DateFormat} object that can be used to format dates and times in\r
1389      * the calendar system specified by <code>cal</code>.\r
1390      * <p>\r
1391      * <b>Note:</b> When this functionality is moved into the core JDK, this method\r
1392      * will probably be replaced by a new overload of {@link DateFormat#getInstance}.\r
1393      * <p>\r
1394      * @param cal   The calendar system for which a date/time format is desired.\r
1395      *\r
1396      * @param dateStyle The type of date format desired.  This can be\r
1397      *              {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM},\r
1398      *              etc.\r
1399      *\r
1400      * @param timeStyle The type of time format desired.  This can be\r
1401      *              {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM},\r
1402      *              etc.\r
1403      *\r
1404      * @param locale The locale for which the date/time format is desired.\r
1405      *\r
1406      * @see DateFormat#getDateTimeInstance\r
1407      * @stable ICU 3.2\r
1408      */\r
1409     static final public DateFormat getDateTimeInstance(Calendar cal, int dateStyle,\r
1410                                                  int timeStyle, ULocale locale)\r
1411     {\r
1412         return cal.getDateTimeFormat(dateStyle, timeStyle, locale);\r
1413     }\r
1414 \r
1415     /**\r
1416      * Convenience overload.\r
1417      * @stable ICU 2.0\r
1418      */\r
1419     static final public DateFormat getInstance(Calendar cal, Locale locale) {\r
1420         return getDateTimeInstance(cal, SHORT, SHORT, ULocale.forLocale(locale));\r
1421     }\r
1422 \r
1423     /**\r
1424      * Convenience overload.\r
1425      * @stable ICU 3.2\r
1426      * @provisional This API might change or be removed in a future release.\r
1427      */\r
1428     static final public DateFormat getInstance(Calendar cal, ULocale locale) {\r
1429         return getDateTimeInstance(cal, SHORT, SHORT, locale);\r
1430     }\r
1431 \r
1432     /**\r
1433      * Convenience overload.\r
1434      * @stable ICU 2.0\r
1435      */\r
1436     static final public DateFormat getInstance(Calendar cal) {\r
1437         return getInstance(cal, ULocale.getDefault());\r
1438     }\r
1439 \r
1440     /**\r
1441      * Convenience overload.\r
1442      * @stable ICU 2.0\r
1443      */\r
1444     static final public DateFormat getDateInstance(Calendar cal, int dateStyle) {\r
1445         return getDateInstance(cal, dateStyle, ULocale.getDefault());\r
1446     }\r
1447 \r
1448     /**\r
1449      * Convenience overload.\r
1450      * @stable ICU 2.0\r
1451      */\r
1452     static final public DateFormat getTimeInstance(Calendar cal, int timeStyle) {\r
1453         return getTimeInstance(cal, timeStyle, ULocale.getDefault());\r
1454     }\r
1455 \r
1456     /**\r
1457      * Convenience overload.\r
1458      * @stable ICU 2.0\r
1459      */\r
1460     static final public DateFormat getDateTimeInstance(Calendar cal, int dateStyle, int timeStyle) {\r
1461         return getDateTimeInstance(cal, dateStyle, timeStyle, ULocale.getDefault());\r
1462     }\r
1463 \r
1464     /**\r
1465      * {@icu} Convenience overload.\r
1466      * @stable ICU 4.0\r
1467      */\r
1468     public final static DateFormat getPatternInstance(String pattern) {\r
1469         return getPatternInstance(pattern, ULocale.getDefault());\r
1470     }\r
1471 \r
1472     /**\r
1473      * {@icu} Convenience overload.\r
1474      * @stable ICU 4.0\r
1475      */\r
1476     public final static DateFormat getPatternInstance(String pattern, Locale locale) {\r
1477         return getPatternInstance(pattern, ULocale.forLocale(locale));\r
1478     }\r
1479 \r
1480     /**\r
1481      * {@icu} Returns a {@link DateFormat} object that can be used to format dates and times in\r
1482      * the given locale.\r
1483      * <p>\r
1484      * <b>Note:</b> When this functionality is moved into the core JDK, this method\r
1485      * will probably be replaced by a new overload of {@link DateFormat#getInstance}.\r
1486      * <p>\r
1487      *\r
1488      * @param pattern The pattern that selects the fields to be formatted. (Uses the\r
1489      *              {@link DateTimePatternGenerator}.) This can be {@link DateFormat#ABBR_MONTH},\r
1490      *              {@link DateFormat#MONTH_WEEKDAY_DAY}, etc.\r
1491      *\r
1492      * @param locale The locale for which the date/time format is desired.\r
1493      *\r
1494      * @stable ICU 4.0\r
1495      */\r
1496     public final static DateFormat getPatternInstance(String pattern, ULocale locale) {\r
1497         DateTimePatternGenerator generator = DateTimePatternGenerator.getInstance(locale);\r
1498         final String bestPattern = generator.getBestPattern(pattern);\r
1499         return new SimpleDateFormat(bestPattern, locale);\r
1500     }\r
1501 \r
1502     /**\r
1503      * {@icu} Convenience overload.\r
1504      * @stable ICU 4.0\r
1505      */\r
1506     public final static DateFormat getPatternInstance(Calendar cal, String pattern, Locale locale) {\r
1507         return getPatternInstance(cal, pattern, ULocale.forLocale(locale));\r
1508     }\r
1509 \r
1510     /**\r
1511      * {@icu} Creates a {@link DateFormat} object that can be used to format dates and\r
1512      * times in the calendar system specified by <code>cal</code>.\r
1513      *\r
1514      * <p><b>Note:</b> When this functionality is moved into the core JDK, this method\r
1515      * will probably be replaced by a new overload of {@link DateFormat#getInstance}.\r
1516      *\r
1517      * @param cal   The calendar system for which a date/time format is desired.\r
1518      *\r
1519      * @param pattern The pattern that selects the fields to be formatted. (Uses the\r
1520      *              {@link DateTimePatternGenerator}.)  This can be\r
1521      *              {@link DateFormat#ABBR_MONTH}, {@link DateFormat#MONTH_WEEKDAY_DAY},\r
1522      *              etc.\r
1523      *\r
1524      * @param locale The locale for which the date/time format is desired.\r
1525      *\r
1526      * @stable ICU 4.0\r
1527      */\r
1528     public final static DateFormat getPatternInstance(\r
1529         Calendar cal, String pattern, ULocale locale) {\r
1530         DateTimePatternGenerator generator = DateTimePatternGenerator.getInstance(locale);\r
1531         final String bestPattern = generator.getBestPattern(pattern);\r
1532         SimpleDateFormat format = new SimpleDateFormat(bestPattern, locale);\r
1533         format.setCalendar(cal);\r
1534         return format;\r
1535     }\r
1536 \r
1537     /**\r
1538      * The instances of this inner class are used as attribute keys and values\r
1539      * in AttributedCharacterIterator that\r
1540      * DateFormat.formatToCharacterIterator() method returns.\r
1541      *\r
1542      * <p>There is no public constructor to this class, the only instances are the\r
1543      * constants defined here.\r
1544      * <p>\r
1545      * @stable ICU 3.8\r
1546      */\r
1547     public static class Field extends Format.Field {\r
1548 \r
1549         private static final long serialVersionUID = -3627456821000730829L;\r
1550 \r
1551         // Max number of calendar fields\r
1552         private static final int CAL_FIELD_COUNT;\r
1553 \r
1554         // Table for mapping calendar field number to DateFormat.Field\r
1555         private static final Field[] CAL_FIELDS;\r
1556 \r
1557         // Map for resolving DateFormat.Field by name\r
1558         private static final Map<String, Field> FIELD_NAME_MAP;\r
1559 \r
1560         static {\r
1561             GregorianCalendar cal = new GregorianCalendar();\r
1562             CAL_FIELD_COUNT = cal.getFieldCount();\r
1563             CAL_FIELDS = new Field[CAL_FIELD_COUNT];\r
1564             FIELD_NAME_MAP = new HashMap<String, Field>(CAL_FIELD_COUNT);\r
1565         }\r
1566 \r
1567         // Java fields -------------------\r
1568 \r
1569         /**\r
1570          * Constant identifying the time of day indicator(am/pm).\r
1571          * @stable ICU 3.8\r
1572          */\r
1573         public static final Field AM_PM = new Field("am pm", Calendar.AM_PM);\r
1574 \r
1575         /**\r
1576          * Constant identifying the day of month field.\r
1577          * @stable ICU 3.8\r
1578          */\r
1579         public static final Field DAY_OF_MONTH = new Field("day of month", Calendar.DAY_OF_MONTH);\r
1580 \r
1581         /**\r
1582          * Constant identifying the day of week field.\r
1583          * @stable ICU 3.8\r
1584          */\r
1585         public static final Field DAY_OF_WEEK = new Field("day of week", Calendar.DAY_OF_WEEK);\r
1586 \r
1587         /**\r
1588          * Constant identifying the day of week in month field.\r
1589          * @stable ICU 3.8\r
1590          */\r
1591         public static final Field DAY_OF_WEEK_IN_MONTH =\r
1592             new Field("day of week in month", Calendar.DAY_OF_WEEK_IN_MONTH);\r
1593 \r
1594         /**\r
1595          * Constant identifying the day of year field.\r
1596          * @stable ICU 3.8\r
1597          */\r
1598         public static final Field DAY_OF_YEAR = new Field("day of year", Calendar.DAY_OF_YEAR);\r
1599 \r
1600         /**\r
1601          * Constant identifying the era field.\r
1602          * @stable ICU 3.8\r
1603          */\r
1604         public static final Field ERA = new Field("era", Calendar.ERA);\r
1605 \r
1606         /**\r
1607          * Constant identifying the hour(0-23) of day field.\r
1608          * @stable ICU 3.8\r
1609          */\r
1610         public static final Field HOUR_OF_DAY0 = new Field("hour of day", Calendar.HOUR_OF_DAY);\r
1611 \r
1612         /**\r
1613          * Constant identifying the hour(1-24) of day field.\r
1614          * @stable ICU 3.8\r
1615          */\r
1616         public static final Field HOUR_OF_DAY1 = new Field("hour of day 1", -1);\r
1617 \r
1618         /**\r
1619          * Constant identifying the hour(0-11) field.\r
1620          * @stable ICU 3.8\r
1621          */\r
1622         public static final Field HOUR0 = new Field("hour", Calendar.HOUR);\r
1623 \r
1624         /**\r
1625          * Constant identifying the hour(1-12) field.\r
1626          * @stable ICU 3.8\r
1627          */\r
1628         public static final Field HOUR1 = new Field("hour 1", -1);\r
1629 \r
1630         /**\r
1631          * Constant identifying the millisecond field.\r
1632          * @stable ICU 3.8\r
1633          */\r
1634         public static final Field MILLISECOND = new Field("millisecond", Calendar.MILLISECOND);\r
1635 \r
1636         /**\r
1637          * Constant identifying the minute field.\r
1638          * @stable ICU 3.8\r
1639          */\r
1640         public static final Field MINUTE = new Field("minute", Calendar.MINUTE);\r
1641 \r
1642         /**\r
1643          * Constant identifying the month field.\r
1644          * @stable ICU 3.8\r
1645          */\r
1646         public static final Field MONTH = new Field("month", Calendar.MONTH);\r
1647 \r
1648         /**\r
1649          * Constant identifying the second field.\r
1650          * @stable ICU 3.8\r
1651          */\r
1652         public static final Field SECOND = new Field("second", Calendar.SECOND);\r
1653 \r
1654         /**\r
1655          * Constant identifying the time zone field.\r
1656          * @stable ICU 3.8\r
1657          */\r
1658         public static final Field TIME_ZONE = new Field("time zone", -1);\r
1659 \r
1660         /**\r
1661          * Constant identifying the week of month field.\r
1662          * @stable ICU 3.8\r
1663          */\r
1664         public static final Field WEEK_OF_MONTH =\r
1665             new Field("week of month", Calendar.WEEK_OF_MONTH);\r
1666 \r
1667         /**\r
1668          * Constant identifying the week of year field.\r
1669          * @stable ICU 3.8\r
1670          */\r
1671         public static final Field WEEK_OF_YEAR = new Field("week of year", Calendar.WEEK_OF_YEAR);\r
1672 \r
1673         /**\r
1674          * Constant identifying the year field.\r
1675          * @stable ICU 3.8\r
1676          */\r
1677         public static final Field YEAR = new Field("year", Calendar.YEAR);\r
1678 \r
1679 \r
1680         // ICU only fields -------------------\r
1681 \r
1682         /**\r
1683          * Constant identifying the local day of week field.\r
1684          * @stable ICU 3.8\r
1685          */\r
1686         public static final Field DOW_LOCAL = new Field("local day of week", Calendar.DOW_LOCAL);\r
1687 \r
1688         /**\r
1689          * Constant identifying the extended year field.\r
1690          * @stable ICU 3.8\r
1691          */\r
1692         public static final Field EXTENDED_YEAR = new Field("extended year", \r
1693                                                             Calendar.EXTENDED_YEAR);\r
1694 \r
1695         /**\r
1696          * Constant identifying the Julian day field.\r
1697          * @stable ICU 3.8\r
1698          */\r
1699         public static final Field JULIAN_DAY = new Field("Julian day", Calendar.JULIAN_DAY);\r
1700 \r
1701         /**\r
1702          * Constant identifying the milliseconds in day field.\r
1703          * @stable ICU 3.8\r
1704          */\r
1705         public static final Field MILLISECONDS_IN_DAY =\r
1706             new Field("milliseconds in day", Calendar.MILLISECONDS_IN_DAY);\r
1707 \r
1708         /**\r
1709          * Constant identifying the year used with week of year field.\r
1710          * @stable ICU 3.8\r
1711          */\r
1712         public static final Field YEAR_WOY = new Field("year for week of year", Calendar.YEAR_WOY);\r
1713 \r
1714         /**\r
1715          * Constant identifying the quarter field.\r
1716          * @stable ICU 3.8\r
1717          */\r
1718         public static final Field QUARTER = new Field("quarter", -1);\r
1719 \r
1720         // Stand alone types are variants for its base types.  So we do not define Field for\r
1721         // them.\r
1722         /*\r
1723         public static final Field STANDALONE_DAY =\r
1724             new Field("stand alone day of week", Calendar.DAY_OF_WEEK);\r
1725         public static final Field STANDALONE_MONTH = new Field("stand alone month", Calendar.MONTH);\r
1726         public static final Field STANDALONE_QUARTER = new Field("stand alone quarter", -1);\r
1727         */\r
1728 \r
1729         // Corresponding calendar field\r
1730         private final int calendarField;\r
1731 \r
1732         /**\r
1733          * Constructs a <code>DateFormat.Field</code> with the given name and\r
1734          * the <code>Calendar</code> field which this attribute represents.  Use -1 for\r
1735          * <code>calendarField</code> if this field does not have a corresponding\r
1736          * <code>Calendar</code> field.\r
1737          *\r
1738          * @param name          Name of the attribute\r
1739          * @param calendarField <code>Calendar</code> field constant\r
1740          *\r
1741          * @stable ICU 3.8\r
1742          */\r
1743         protected Field(String name, int calendarField) {\r
1744             super(name);\r
1745             this.calendarField = calendarField;\r
1746             if (this.getClass() == DateFormat.Field.class) {\r
1747                 FIELD_NAME_MAP.put(name, this);\r
1748                 if (calendarField >= 0 && calendarField < CAL_FIELD_COUNT) {\r
1749                     CAL_FIELDS[calendarField] = this;\r
1750                 }\r
1751             }\r
1752         }\r
1753 \r
1754         /**\r
1755          * Returns the <code>Field</code> constant that corresponds to the <code>\r
1756          * Calendar</code> field <code>calendarField</code>.  If there is no\r
1757          * corresponding <code>Field</code> is available, null is returned.\r
1758          *\r
1759          * @param calendarField <code>Calendar</code> field constant\r
1760          * @return <code>Field</code> associated with the <code>calendarField</code>,\r
1761          * or null if no associated <code>Field</code> is available.\r
1762          * @throws IllegalArgumentException if <code>calendarField</code> is not\r
1763          * a valid <code>Calendar</code> field constant.\r
1764          *\r
1765          * @stable ICU 3.8\r
1766          */\r
1767         public static DateFormat.Field ofCalendarField(int calendarField) {\r
1768             if (calendarField < 0 || calendarField >= CAL_FIELD_COUNT) {\r
1769                 throw new IllegalArgumentException("Calendar field number is out of range");\r
1770             }\r
1771             return CAL_FIELDS[calendarField];\r
1772         }\r
1773 \r
1774         /**\r
1775          * Returns the <code>Calendar</code> field associated with this attribute.\r
1776          * If there is no corresponding <code>Calendar</code> available, this will\r
1777          * return -1.\r
1778          *\r
1779          * @return <code>Calendar</code> constant for this attribute.\r
1780          *\r
1781          * @stable ICU 3.8\r
1782          */\r
1783         public int getCalendarField() {\r
1784             return calendarField;\r
1785         }\r
1786 \r
1787         /**\r
1788          * Resolves instances being deserialized to the predefined constants.\r
1789          *\r
1790          * @throws InvalidObjectException if the constant could not be resolved.\r
1791          *\r
1792          * @stable ICU 3.8\r
1793          */\r
1794         protected Object readResolve() throws InvalidObjectException {\r
1795             ///CLOVER:OFF\r
1796             if (this.getClass() != DateFormat.Field.class) {\r
1797                 throw new InvalidObjectException(\r
1798                     "A subclass of DateFormat.Field must implement readResolve.");\r
1799             }\r
1800             ///CLOVER:ON\r
1801             Object o = FIELD_NAME_MAP.get(this.getName());\r
1802             ///CLOVER:OFF\r
1803             if (o == null) {\r
1804                 throw new InvalidObjectException("Unknown attribute name.");\r
1805             }\r
1806             ///CLOVER:ON\r
1807             return o;\r
1808         }\r
1809     }\r
1810 }\r