1/* GENERATED SOURCE. DO NOT MODIFY. */ 2// © 2016 and later: Unicode, Inc. and others. 3// License & terms of use: http://www.unicode.org/copyright.html#License 4/* 5 * Copyright (C) 1996-2016, International Business Machines 6 * Corporation and others. All Rights Reserved. 7 */ 8 9package android.icu.text; 10 11import java.io.IOException; 12import java.io.InvalidObjectException; 13import java.io.ObjectInputStream; 14import java.text.FieldPosition; 15import java.text.Format; 16import java.text.ParseException; 17import java.text.ParsePosition; 18import java.util.Arrays; 19import java.util.Date; 20import java.util.EnumSet; 21import java.util.HashMap; 22import java.util.List; 23import java.util.Locale; 24import java.util.Map; 25import java.util.MissingResourceException; 26 27import android.icu.impl.ICUResourceBundle; 28import android.icu.impl.RelativeDateFormat; 29import android.icu.util.Calendar; 30import android.icu.util.GregorianCalendar; 31import android.icu.util.TimeZone; 32import android.icu.util.ULocale; 33import android.icu.util.ULocale.Category; 34 35/** 36 * <strong>[icu enhancement]</strong> ICU's replacement for {@link java.text.DateFormat}. Methods, fields, and other functionality specific to ICU are labeled '<strong>[icu]</strong>'. 37 * 38 * <p> 39 * DateFormat is an abstract class for date/time formatting subclasses which formats and parses dates or time in a 40 * language-independent manner. The date/time formatting subclass, such as SimpleDateFormat, allows for formatting 41 * (i.e., date -> text), parsing (text -> date), and normalization. The date is represented as a <code>Date</code> 42 * object or as the milliseconds since January 1, 1970, 00:00:00 GMT. 43 * 44 * <p> 45 * DateFormat helps you to format and parse dates for any locale. Your code can be completely independent of the locale 46 * conventions for months, days of the week, or even the calendar format: lunar vs. solar. It provides many class 47 * methods for obtaining default date/time formatters based on the default for a given locale and a number of formatting 48 * styles or arbitrary "skeletons". 49 * <ol> 50 * <li>The formatting styles include FULL, LONG, MEDIUM, and SHORT. More detail and examples of using these styles are 51 * provided in the method descriptions. 52 * <li>The formatting styles only cover a fraction of the necessary usage. You often need to have just certain 53 * combinations of fields, like Month and Year, but have it to be formatted appropriate to a given locale. This is done 54 * using the (misnamed) getPatternInstance() method, supplying a skeleton. There are a number of constants that have 55 * common pre-defined skeletons, such as {@link #MINUTE_SECOND} for something like "13:45" or {@link #YEAR_ABBR_MONTH} 56 * for something like "Sept 2012". 57 * </ol> 58 * 59 * <p> 60 * To format a date for the current Locale, use one of the static factory methods: 61 * 62 * <pre> 63 * myString = DateFormat.getDateInstance().format(myDate); 64 * myString = DateFormat.getPatternInstance(DateFormat.YEAR_ABBR_MONTH).format(myDate); 65 * </pre> 66 * <p> 67 * If you are formatting multiple numbers, it is more efficient to get the format and use it multiple times so that the 68 * system doesn't have to fetch the information about the local language and country conventions multiple times. 69 * 70 * <pre> 71 * DateFormat df = DateFormat.getDateInstance(); 72 * for (int i = 0; i < a.length; ++i) { 73 * output.println(df.format(myDate[i]) + "; "); 74 * } 75 * </pre> 76 * <p> 77 * To format a date for a different Locale, specify it in the call to getDateInstance(). 78 * 79 * <pre> 80 * DateFormat df = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE); 81 * </pre> 82 * <p> 83 * You can use a DateFormat to parse also. 84 * 85 * <pre> 86 * myDate = df.parse(myString); 87 * </pre> 88 * <p> 89 * There are many static factory methods available. Use getDateInstance to get the normal date format for that country. 90 * Use getTimeInstance to get the time format for that country. Use getDateTimeInstance to get a date and time format. 91 * You can pass in different options to these factory methods to control the length of the result; from SHORT to MEDIUM 92 * to LONG to FULL. The exact result depends on the locale, but generally: 93 * <ul> 94 * <li>SHORT is completely numeric, such as 12.13.52 or 3:30pm 95 * <li>MEDIUM is longer, such as Jan 12, 1952 96 * <li>LONG is longer, such as January 12, 1952 or 3:30:32pm 97 * <li>FULL is pretty completely specified, such as Tuesday, April 12, 1952 AD or 3:30:42pm PST. 98 * </ul> 99 * 100 * <p> 101 * Use getPatternInstance to format with a skeleton. Typically this is with a predefined skeleton, like 102 * {@link #YEAR_ABBR_MONTH} for something like "Sept 2012". If you don't want to use one of the predefined skeletons, 103 * you can supply your own. The skeletons are like the patterns in SimpleDateFormat, except they: 104 * <ol> 105 * <li>only keep the field pattern letter and ignore all other parts in a pattern, such as space, punctuation, and 106 * string literals. 107 * <li>are independent of the order of fields. 108 * <li>ignore certain differences in the field's pattern letter length: 109 * <ol> 110 * <li>For those non-digit calendar fields, the pattern letter length is important, such as MMM, MMMM, and MMMMM; E and 111 * EEEE, and the field's pattern letter length is honored. 112 * <li>For the digit calendar fields, such as M or MM, d or dd, yy or yyyy, the field pattern length is ignored and the 113 * best match, which is defined in date time patterns, will be returned without honor the field pattern letter length in 114 * skeleton. 115 * </ol> 116 * </ol> 117 * 118 * <p> 119 * You can also set the time zone on the format if you wish. If you want even more control over the format or parsing, 120 * (or want to give your users more control), you can try casting the DateFormat you get from the factory methods to a 121 * SimpleDateFormat. This will work for the majority of countries; just remember to put it in a try block in case you 122 * encounter an unusual one. 123 * 124 * <p> 125 * You can also use forms of the parse and format methods with ParsePosition and FieldPosition to allow you to 126 * <ul> 127 * <li>progressively parse through pieces of a string. 128 * <li>align any particular field, or find out where it is for selection on the screen. 129 * </ul> 130 * 131 * <h3>Synchronization</h3> 132 * 133 * Date formats are not synchronized. It is recommended to create separate format instances for each thread. If multiple 134 * threads access a format concurrently, it must be synchronized externally. 135 * 136 * @see UFormat 137 * @see NumberFormat 138 * @see SimpleDateFormat 139 * @see android.icu.util.Calendar 140 * @see android.icu.util.GregorianCalendar 141 * @see android.icu.util.TimeZone 142 * @author Mark Davis, Chen-Lieh Huang, Alan Liu 143 */ 144public abstract class DateFormat extends UFormat { 145 146 /** 147 * The calendar that <code>DateFormat</code> uses to produce the time field 148 * values needed to implement date and time formatting. Subclasses should 149 * initialize this to a calendar appropriate for the locale associated with 150 * this <code>DateFormat</code>. 151 * @serial 152 */ 153 protected Calendar calendar; 154 155 /** 156 * The number formatter that <code>DateFormat</code> uses to format numbers 157 * in dates and times. Subclasses should initialize this to a number format 158 * appropriate for the locale associated with this <code>DateFormat</code>. 159 * @serial 160 */ 161 protected NumberFormat numberFormat; 162 163 /** 164 * FieldPosition selector for 'G' field alignment, 165 * corresponding to the {@link Calendar#ERA} field. 166 */ 167 public final static int ERA_FIELD = 0; 168 169 /** 170 * FieldPosition selector for 'y' field alignment, 171 * corresponding to the {@link Calendar#YEAR} field. 172 */ 173 public final static int YEAR_FIELD = 1; 174 175 /** 176 * FieldPosition selector for 'M' field alignment, 177 * corresponding to the {@link Calendar#MONTH} field. 178 */ 179 public final static int MONTH_FIELD = 2; 180 181 /** 182 * FieldPosition selector for 'd' field alignment, 183 * corresponding to the {@link Calendar#DATE} field. 184 */ 185 public final static int DATE_FIELD = 3; 186 187 /** 188 * FieldPosition selector for 'k' field alignment, 189 * corresponding to the {@link Calendar#HOUR_OF_DAY} field. 190 * HOUR_OF_DAY1_FIELD is used for the one-based 24-hour clock. 191 * For example, 23:59 + 01:00 results in 24:59. 192 */ 193 public final static int HOUR_OF_DAY1_FIELD = 4; 194 195 /** 196 * FieldPosition selector for 'H' field alignment, 197 * corresponding to the {@link Calendar#HOUR_OF_DAY} field. 198 * HOUR_OF_DAY0_FIELD is used for the zero-based 24-hour clock. 199 * For example, 23:59 + 01:00 results in 00:59. 200 */ 201 public final static int HOUR_OF_DAY0_FIELD = 5; 202 203 /** 204 * FieldPosition selector for 'm' field alignment, 205 * corresponding to the {@link Calendar#MINUTE} field. 206 */ 207 public final static int MINUTE_FIELD = 6; 208 209 /** 210 * FieldPosition selector for 's' field alignment, 211 * corresponding to the {@link Calendar#SECOND} field. 212 */ 213 public final static int SECOND_FIELD = 7; 214 215 /** 216 * <strong>[icu]</strong> FieldPosition selector for 'S' field alignment, 217 * corresponding to the {@link Calendar#MILLISECOND} field. 218 * 219 * Note: Time formats that use 'S' can display a maximum of three 220 * significant digits for fractional seconds, corresponding to millisecond 221 * resolution and a fractional seconds sub-pattern of SSS. If the 222 * sub-pattern is S or SS, the fractional seconds value will be truncated 223 * (not rounded) to the number of display places specified. If the 224 * fractional seconds sub-pattern is longer than SSS, the additional 225 * display places will be filled with zeros. 226 */ 227 public final static int FRACTIONAL_SECOND_FIELD = 8; 228 229 /** 230 * Alias for FRACTIONAL_SECOND_FIELD. 231 */ 232 public final static int MILLISECOND_FIELD = FRACTIONAL_SECOND_FIELD; 233 234 /** 235 * FieldPosition selector for 'E' field alignment, 236 * corresponding to the {@link Calendar#DAY_OF_WEEK} field. 237 */ 238 public final static int DAY_OF_WEEK_FIELD = 9; 239 240 /** 241 * FieldPosition selector for 'D' field alignment, 242 * corresponding to the {@link Calendar#DAY_OF_YEAR} field. 243 */ 244 public final static int DAY_OF_YEAR_FIELD = 10; 245 246 /** 247 * FieldPosition selector for 'F' field alignment, 248 * corresponding to the {@link Calendar#DAY_OF_WEEK_IN_MONTH} field. 249 */ 250 public final static int DAY_OF_WEEK_IN_MONTH_FIELD = 11; 251 252 /** 253 * FieldPosition selector for 'w' field alignment, 254 * corresponding to the {@link Calendar#WEEK_OF_YEAR} field. 255 */ 256 public final static int WEEK_OF_YEAR_FIELD = 12; 257 258 /** 259 * FieldPosition selector for 'W' field alignment, 260 * corresponding to the {@link Calendar#WEEK_OF_MONTH} field. 261 */ 262 public final static int WEEK_OF_MONTH_FIELD = 13; 263 264 /** 265 * FieldPosition selector for 'a' field alignment, 266 * corresponding to the {@link Calendar#AM_PM} field. 267 */ 268 public final static int AM_PM_FIELD = 14; 269 270 /** 271 * FieldPosition selector for 'h' field alignment, 272 * corresponding to the {@link Calendar#HOUR} field. 273 * HOUR1_FIELD is used for the one-based 12-hour clock. 274 * For example, 11:30 PM + 1 hour results in 12:30 AM. 275 */ 276 public final static int HOUR1_FIELD = 15; 277 278 /** 279 * FieldPosition selector for 'K' field alignment, 280 * corresponding to the {@link Calendar#HOUR} field. 281 * HOUR0_FIELD is used for the zero-based 12-hour clock. 282 * For example, 11:30 PM + 1 hour results in 00:30 AM. 283 */ 284 public final static int HOUR0_FIELD = 16; 285 286 /** 287 * FieldPosition selector for 'z' field alignment, 288 * corresponding to the {@link Calendar#ZONE_OFFSET} and 289 * {@link Calendar#DST_OFFSET} fields. 290 */ 291 public final static int TIMEZONE_FIELD = 17; 292 293 /** 294 * <strong>[icu]</strong> FieldPosition selector for 'Y' field alignment, 295 * corresponding to the {@link Calendar#YEAR_WOY} field. 296 */ 297 public final static int YEAR_WOY_FIELD = 18; 298 299 /** 300 * <strong>[icu]</strong> FieldPosition selector for 'e' field alignment, 301 * corresponding to the {@link Calendar#DOW_LOCAL} field. 302 */ 303 public final static int DOW_LOCAL_FIELD = 19; 304 305 /** 306 * <strong>[icu]</strong> FieldPosition selector for 'u' field alignment, 307 * corresponding to the {@link Calendar#EXTENDED_YEAR} field. 308 */ 309 public final static int EXTENDED_YEAR_FIELD = 20; 310 311 /** 312 * <strong>[icu]</strong> FieldPosition selector for 'g' field alignment, 313 * corresponding to the {@link Calendar#JULIAN_DAY} field. 314 */ 315 public final static int JULIAN_DAY_FIELD = 21; 316 317 /** 318 * <strong>[icu]</strong> FieldPosition selector for 'A' field alignment, 319 * corresponding to the {@link Calendar#MILLISECONDS_IN_DAY} field. 320 */ 321 public final static int MILLISECONDS_IN_DAY_FIELD = 22; 322 323 /** 324 * <strong>[icu]</strong> FieldPosition selector for 'Z' field alignment, 325 * corresponding to the {@link Calendar#ZONE_OFFSET} and 326 * {@link Calendar#DST_OFFSET} fields. 327 */ 328 public final static int TIMEZONE_RFC_FIELD = 23; 329 330 /** 331 * <strong>[icu]</strong> FieldPosition selector for 'v' field alignment, 332 * corresponding to the {@link Calendar#ZONE_OFFSET} and 333 * {@link Calendar#DST_OFFSET} fields. This displays the generic zone 334 * name, if available. 335 */ 336 public final static int TIMEZONE_GENERIC_FIELD = 24; 337 338 /** 339 * <strong>[icu]</strong> FieldPosition selector for 'c' field alignment, 340 * corresponding to the {@link Calendar#DAY_OF_WEEK} field. 341 * This displays the stand alone day name, if available. 342 */ 343 public final static int STANDALONE_DAY_FIELD = 25; 344 345 /** 346 * <strong>[icu]</strong> FieldPosition selector for 'L' field alignment, 347 * corresponding to the {@link Calendar#MONTH} field. 348 * This displays the stand alone month name, if available. 349 */ 350 public final static int STANDALONE_MONTH_FIELD = 26; 351 352 /** 353 * <strong>[icu]</strong> FieldPosition selector for 'Q' field alignment, 354 * corresponding to the {@link Calendar#MONTH} field. 355 * This displays the quarter. 356 */ 357 public final static int QUARTER_FIELD = 27; 358 359 /** 360 * <strong>[icu]</strong> FieldPosition selector for 'q' field alignment, 361 * corresponding to the {@link Calendar#MONTH} field. 362 * This displays the stand alone quarter, if available. 363 */ 364 public final static int STANDALONE_QUARTER_FIELD = 28; 365 366 /** 367 * <strong>[icu]</strong> FieldPosition selector for 'V' field alignment, 368 * corresponding to the {@link Calendar#ZONE_OFFSET} and 369 * {@link Calendar#DST_OFFSET} fields. This displays the fallback timezone 370 * name when VVVV is specified, and the short standard or daylight 371 * timezone name ignoring commonlyUsed when a single V is specified. 372 */ 373 public final static int TIMEZONE_SPECIAL_FIELD = 29; 374 375 /** 376 * <strong>[icu]</strong> FieldPosition selector for 'U' field alignment, 377 * corresponding to the {@link Calendar#YEAR} field. 378 * This displays the cyclic year name, if available. 379 */ 380 public final static int YEAR_NAME_FIELD = 30; 381 382 /** 383 * <strong>[icu]</strong> FieldPosition selector for 'O' field alignment, 384 * corresponding to the {@link Calendar#ZONE_OFFSET} and 385 * {@link Calendar#DST_OFFSET} fields. This displays the 386 * localized GMT format. 387 */ 388 public final static int TIMEZONE_LOCALIZED_GMT_OFFSET_FIELD = 31; 389 390 /** 391 * <strong>[icu]</strong> FieldPosition selector for 'X' field alignment, 392 * corresponding to the {@link Calendar#ZONE_OFFSET} and 393 * {@link Calendar#DST_OFFSET} fields. This displays the 394 * ISO 8601 local time offset format or UTC indicator ("Z"). 395 */ 396 public final static int TIMEZONE_ISO_FIELD = 32; 397 398 /** 399 * <strong>[icu]</strong> FieldPosition selector for 'x' field alignment, 400 * corresponding to the {@link Calendar#ZONE_OFFSET} and 401 * {@link Calendar#DST_OFFSET} fields. This displays the 402 * ISO 8601 local time offset format. 403 */ 404 public final static int TIMEZONE_ISO_LOCAL_FIELD = 33; 405 406 /** 407 * <strong>[icu]</strong> FieldPosition selector for 'r' field alignment, 408 * corresponding to the {@link Calendar#EXTENDED_YEAR} field 409 * of the *related* calendar which may be different than the 410 * one used by the DateFormat. 411 * @deprecated This API is ICU internal only. 412 * @hide draft / provisional / internal are hidden on Android 413 */ 414 @Deprecated 415 final static int RELATED_YEAR = 34; 416 417 /** 418 * <strong>[icu]</strong> FieldPosition selector for 'b' field alignment. 419 * No related Calendar field. 420 * This displays the fixed day period (am/pm/midnight/noon). 421 * @hide draft / provisional / internal are hidden on Android 422 */ 423 final static int AM_PM_MIDNIGHT_NOON_FIELD = 35; 424 425 /** 426 * <strong>[icu]</strong> FieldPosition selector for 'B' field alignment. 427 * No related Calendar field. 428 * This displays the flexible day period. 429 * @hide draft / provisional / internal are hidden on Android 430 */ 431 final static int FLEXIBLE_DAY_PERIOD_FIELD = 36; 432 433 /** 434 * <strong>[icu]</strong> FieldPosition selector time separator, 435 * no related Calendar field. No pattern character is currently 436 * defined for this. 437 * @deprecated This API is ICU internal only. 438 * @hide draft / provisional / internal are hidden on Android 439 */ 440 @Deprecated 441 public final static int TIME_SEPARATOR = 37; 442 443 /** 444 * <strong>[icu]</strong> Number of FieldPosition selectors for DateFormat. 445 * Valid selectors range from 0 to FIELD_COUNT-1. 446 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 447 * @hide unsupported on Android 448 */ 449 @Deprecated 450 public final static int FIELD_COUNT = 38; 451 // A previous comment for the above stated that we must have 452 // DateFormat.FIELD_COUNT == DateFormatSymbols.patternChars.length() 453 // but that does not seem to be the case, and in fact since there is 454 // no pattern character currently defined for TIME_SEPARATOR it is 455 // currently the case that 456 // DateFormat.FIELD_COUNT == DateFormatSymbols.patternChars.length() + 1 457 458 459 /** 460 * boolean attributes 461 */ 462 public enum BooleanAttribute { 463 /** 464 * indicates whitespace tolerance. Also included is trailing dot tolerance. 465 */ 466 PARSE_ALLOW_WHITESPACE, 467 /** 468 * indicates tolerance of numeric data when String data may be assumed. 469 * e.g. YEAR_NAME_FIELD 470 */ 471 PARSE_ALLOW_NUMERIC, 472 /** 473 * indicates tolerance of pattern mismatch between input data and specified format pattern. 474 * e.g. accepting "September" for a month pattern of MMM ("Sep") 475 */ 476 PARSE_MULTIPLE_PATTERNS_FOR_MATCH, 477 /** 478 * indicates tolerance of a partial literal match 479 * e.g. accepting "--mon-02-march-2011" for a pattern of "'--: 'EEE-WW-MMMM-yyyy" 480 */ 481 PARSE_PARTIAL_LITERAL_MATCH, 482 /** 483 * alias of PARSE_PARTIAL_LITERAL_MATCH 484 * @deprecated 485 * @hide draft / provisional / internal are hidden on Android 486 */ 487 @Deprecated 488 PARSE_PARTIAL_MATCH 489 }; 490 491 /** 492 * boolean attributes for this instance. Inclusion in this is indicates a true condition. 493 */ 494 private EnumSet<BooleanAttribute> booleanAttributes = EnumSet.allOf(BooleanAttribute.class); 495 496 /* 497 * Capitalization setting, hoisted to DateFormat ICU 53 498 * Note that SimpleDateFormat serialization may call getContext/setContext to read/write 499 * this for compatibility with serialization for its old copy of capitalizationSetting. 500 * @serial 501 */ 502 private DisplayContext capitalizationSetting = DisplayContext.CAPITALIZATION_NONE; 503 504 static final int currentSerialVersion = 1; 505 506 /** 507 * Describes the version of <code>DateFormat</code> present on the stream. 508 * Possible values are: 509 * <ul> 510 * <li><b>0</b> (or uninitialized): the pre-ICU-53 version 511 * 512 * <li><b>1</b>: ICU 53, adds serialVersionOnStream and capitalizationSetting 513 * </ul> 514 * When streaming out a <code>DateFormat</code>, the most recent format 515 * (corresponding to the highest allowable <code>serialVersionOnStream</code>) 516 * is always written. 517 * 518 * @serial 519 */ 520 private int serialVersionOnStream = currentSerialVersion; 521 522 // Proclaim serial compatibility with 1.1 FCS 523 private static final long serialVersionUID = 7218322306649953788L; 524 525 /** 526 * Formats a time object into a time string. Examples of time objects 527 * are a time value expressed in milliseconds and a Date object. 528 * @param obj must be a Number or a Date or a Calendar. 529 * @param toAppendTo the string buffer for the returning time string. 530 * @return the formatted time string. 531 * @param fieldPosition keeps track of the position of the field 532 * within the returned string. 533 * On input: an alignment field, 534 * if desired. On output: the offsets of the alignment field. For 535 * example, given a time text "1996.07.10 AD at 15:08:56 PDT", 536 * if the given fieldPosition is DateFormat.YEAR_FIELD, the 537 * begin index and end index of fieldPosition will be set to 538 * 0 and 4, respectively. 539 * Notice that if the same time field appears 540 * more than once in a pattern, the fieldPosition will be set for the first 541 * occurrence of that time field. For instance, formatting a Date to 542 * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern 543 * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD, 544 * the begin index and end index of fieldPosition will be set to 545 * 5 and 8, respectively, for the first occurrence of the timezone 546 * pattern character 'z'. 547 * @see java.text.Format 548 */ 549 @Override 550 public final StringBuffer format(Object obj, StringBuffer toAppendTo, 551 FieldPosition fieldPosition) 552 { 553 if (obj instanceof Calendar) 554 return format( (Calendar)obj, toAppendTo, fieldPosition ); 555 else if (obj instanceof Date) 556 return format( (Date)obj, toAppendTo, fieldPosition ); 557 else if (obj instanceof Number) 558 return format( new Date(((Number)obj).longValue()), 559 toAppendTo, fieldPosition ); 560 else 561 throw new IllegalArgumentException("Cannot format given Object (" + 562 obj.getClass().getName() + ") as a Date"); 563 } 564 565 /** 566 * Formats a date into a date/time string. 567 * @param cal a Calendar set to the date and time to be formatted 568 * into a date/time string. When the calendar type is different from 569 * the internal calendar held by this DateFormat instance, the date 570 * and the time zone will be inherited from the input calendar, but 571 * other calendar field values will be calculated by the internal calendar. 572 * @param toAppendTo the string buffer for the returning date/time string. 573 * @param fieldPosition keeps track of the position of the field 574 * within the returned string. 575 * On input: an alignment field, 576 * if desired. On output: the offsets of the alignment field. For 577 * example, given a time text "1996.07.10 AD at 15:08:56 PDT", 578 * if the given fieldPosition is DateFormat.YEAR_FIELD, the 579 * begin index and end index of fieldPosition will be set to 580 * 0 and 4, respectively. 581 * Notice that if the same time field appears 582 * more than once in a pattern, the fieldPosition will be set for the first 583 * occurrence of that time field. For instance, formatting a Date to 584 * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern 585 * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD, 586 * the begin index and end index of fieldPosition will be set to 587 * 5 and 8, respectively, for the first occurrence of the timezone 588 * pattern character 'z'. 589 * @return the formatted date/time string. 590 */ 591 public abstract StringBuffer format(Calendar cal, StringBuffer toAppendTo, 592 FieldPosition fieldPosition); 593 594 /** 595 * Formats a Date into a date/time string. 596 * @param date a Date to be formatted into a date/time string. 597 * @param toAppendTo the string buffer for the returning date/time string. 598 * @param fieldPosition keeps track of the position of the field 599 * within the returned string. 600 * On input: an alignment field, 601 * if desired. On output: the offsets of the alignment field. For 602 * example, given a time text "1996.07.10 AD at 15:08:56 PDT", 603 * if the given fieldPosition is DateFormat.YEAR_FIELD, the 604 * begin index and end index of fieldPosition will be set to 605 * 0 and 4, respectively. 606 * Notice that if the same time field appears 607 * more than once in a pattern, the fieldPosition will be set for the first 608 * occurrence of that time field. For instance, formatting a Date to 609 * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern 610 * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD, 611 * the begin index and end index of fieldPosition will be set to 612 * 5 and 8, respectively, for the first occurrence of the timezone 613 * pattern character 'z'. 614 * @return the formatted date/time string. 615 */ 616 public StringBuffer format(Date date, StringBuffer toAppendTo, 617 FieldPosition fieldPosition) { 618 // Use our Calendar object 619 calendar.setTime(date); 620 return format(calendar, toAppendTo, fieldPosition); 621 } 622 623 /** 624 * Formats a Date into a date/time string. 625 * @param date the time value to be formatted into a time string. 626 * @return the formatted time string. 627 */ 628 public final String format(Date date) 629 { 630 return format(date, new StringBuffer(64),new FieldPosition(0)).toString(); 631 } 632 633 /** 634 * Parses a date/time string. For example, a time text "07/10/96 4:5 PM, PDT" 635 * will be parsed into a Date that is equivalent to Date(837039928046). 636 * Parsing begins at the beginning of the string and proceeds as far as 637 * possible. Assuming no parse errors were encountered, this function 638 * doesn't return any information about how much of the string was consumed 639 * by the parsing. If you need that information, use a version of 640 * parse() that takes a ParsePosition. 641 * 642 * <p> By default, parsing is lenient: If the input is not in the form used 643 * by this object's format method but can still be parsed as a date, then 644 * the parse succeeds. Clients may insist on strict adherence to the 645 * format by calling setLenient(false). 646 * 647 * <p> Note that the normal date formats associated with some calendars - such 648 * as the Chinese lunar calendar - do not specify enough fields to enable 649 * dates to be parsed unambiguously. In the case of the Chinese lunar 650 * calendar, while the year within the current 60-year cycle is specified, 651 * the number of such cycles since the start date of the calendar (in the 652 * ERA field of the Calendar object) is not normally part of the format, 653 * and parsing may assume the wrong era. For cases such as this it is 654 * recommended that clients parse using the parse method that takes a Calendar 655 * with the Calendar passed in set to the current date, or to a date 656 * within the era/cycle that should be assumed if absent in the format. 657 * 658 * @param text The date/time string to be parsed 659 * 660 * @return A Date, or null if the input could not be parsed 661 * 662 * @exception ParseException If the given string cannot be parsed as a date. 663 * 664 * @see #parse(String, ParsePosition) 665 */ 666 public Date parse(String text) throws ParseException 667 { 668 ParsePosition pos = new ParsePosition(0); 669 Date result = parse(text, pos); 670 if (pos.getIndex() == 0) // ICU4J 671 throw new ParseException("Unparseable date: \"" + text + "\"" , 672 pos.getErrorIndex()); // ICU4J 673 return result; 674 } 675 676 /** 677 * Parses a date/time string according to the given parse position. 678 * For example, a time text "07/10/96 4:5 PM, PDT" will be parsed 679 * into a Calendar that is equivalent to Date(837039928046). Before 680 * calling this method the caller should initialize the calendar 681 * in one of two ways (unless existing field information is to be kept): 682 * (1) clear the calendar, or (2) set the calendar to the current date 683 * (or to any date whose fields should be used to supply values that 684 * are missing in the parsed date). For example, Chinese calendar dates 685 * do not normally provide an era/cycle; in this case the calendar that 686 * is passed in should be set to a date within the era that should be 687 * assumed, normally the current era. 688 * 689 * <p> By default, parsing is lenient: If the input is not in the form used 690 * by this object's format method but can still be parsed as a date, then 691 * the parse succeeds. Clients may insist on strict adherence to the 692 * format by calling setLenient(false). 693 * 694 * @see #setLenient(boolean) 695 * 696 * @param text The date/time string to be parsed 697 * 698 * @param cal The calendar set on input to the date and time to be used 699 * for missing values in the date/time string being parsed, 700 * and set on output to the parsed date/time. In general, this 701 * should be initialized before calling this method - either 702 * cleared or set to the current date, depending on desired 703 * behavior. If this parse fails, the calendar may still 704 * have been modified. When the calendar type is different 705 * from the internal calendar held by this DateFormat 706 * instance, calendar field values will be parsed based 707 * on the internal calendar initialized with the time and 708 * the time zone taken from this calendar, then the 709 * parse result (time in milliseconds and time zone) will 710 * be set back to this calendar. 711 * 712 * @param pos On input, the position at which to start parsing; on 713 * output, the position at which parsing terminated, or the 714 * start position if the parse failed. 715 */ 716 public abstract void parse(String text, Calendar cal, ParsePosition pos); 717 718 /** 719 * Parses a date/time string according to the given parse position. For 720 * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date 721 * that is equivalent to Date(837039928046). 722 * 723 * <p> By default, parsing is lenient: If the input is not in the form used 724 * by this object's format method but can still be parsed as a date, then 725 * the parse succeeds. Clients may insist on strict adherence to the 726 * format by calling setLenient(false). 727 * 728 * <p> Note that the normal date formats associated with some calendars - such 729 * as the Chinese lunar calendar - do not specify enough fields to enable 730 * dates to be parsed unambiguously. In the case of the Chinese lunar 731 * calendar, while the year within the current 60-year cycle is specified, 732 * the number of such cycles since the start date of the calendar (in the 733 * ERA field of the Calendar object) is not normally part of the format, 734 * and parsing may assume the wrong era. For cases such as this it is 735 * recommended that clients parse using the parse method that takes a Calendar 736 * with the Calendar passed in set to the current date, or to a date 737 * within the era/cycle that should be assumed if absent in the format. 738 * 739 * @see #setLenient(boolean) 740 * 741 * @param text The date/time string to be parsed 742 * 743 * @param pos On input, the position at which to start parsing; on 744 * output, the position at which parsing terminated, or the 745 * start position if the parse failed. 746 * 747 * @return A Date, or null if the input could not be parsed 748 */ 749 public Date parse(String text, ParsePosition pos) { 750 Date result = null; 751 int start = pos.getIndex(); 752 TimeZone tzsav = calendar.getTimeZone(); 753 calendar.clear(); 754 parse(text, calendar, pos); 755 if (pos.getIndex() != start) { 756 try { 757 result = calendar.getTime(); 758 } catch (IllegalArgumentException e) { 759 // This occurs if the calendar is non-lenient and there is 760 // an out-of-range field. We don't know which field was 761 // illegal so we set the error index to the start. 762 pos.setIndex(start); 763 pos.setErrorIndex(start); 764 } 765 } 766 // Restore TimeZone 767 calendar.setTimeZone(tzsav); 768 return result; 769 } 770 771 /** 772 * Parses a date/time string into an Object. This convenience method simply 773 * calls parse(String, ParsePosition). 774 * 775 * @see #parse(String, ParsePosition) 776 */ 777 @Override 778 public Object parseObject (String source, ParsePosition pos) 779 { 780 return parse(source, pos); 781 } 782 783 /** 784 * <strong>[icu]</strong> Constant for empty style pattern. 785 */ 786 public static final int NONE = -1; 787 788 /** 789 * Constant for full style pattern. 790 */ 791 public static final int FULL = 0; 792 793 /** 794 * Constant for long style pattern. 795 */ 796 public static final int LONG = 1; 797 798 /** 799 * Constant for medium style pattern. 800 */ 801 public static final int MEDIUM = 2; 802 803 /** 804 * Constant for short style pattern. 805 */ 806 public static final int SHORT = 3; 807 808 /** 809 * Constant for default style pattern. Its value is MEDIUM. 810 */ 811 public static final int DEFAULT = MEDIUM; 812 813 /** 814 * <strong>[icu]</strong> Constant for relative style mask. 815 */ 816 public static final int RELATIVE = (1 << 7); 817 818 /** 819 * <strong>[icu]</strong> Constant for relative full style pattern. 820 */ 821 public static final int RELATIVE_FULL = RELATIVE | FULL; 822 823 /** 824 * <strong>[icu]</strong> Constant for relative style pattern. 825 */ 826 public static final int RELATIVE_LONG = RELATIVE | LONG; 827 828 /** 829 * <strong>[icu]</strong> Constant for relative style pattern. 830 */ 831 public static final int RELATIVE_MEDIUM = RELATIVE | MEDIUM; 832 833 /** 834 * <strong>[icu]</strong> Constant for relative style pattern. 835 */ 836 public static final int RELATIVE_SHORT = RELATIVE | SHORT; 837 838 /** 839 * <strong>[icu]</strong> Constant for relative default style pattern. 840 */ 841 public static final int RELATIVE_DEFAULT = RELATIVE | DEFAULT; 842 843 /* 844 * DATES 845 */ 846 847 /** 848 * <strong>[icu]</strong> Constant for date skeleton with year. 849 */ 850 public static final String YEAR = "y"; 851 852 /** 853 * <strong>[icu]</strong> Constant for date skeleton with quarter. 854 */ 855 public static final String QUARTER = "QQQQ"; 856 857 /** 858 * <strong>[icu]</strong> Constant for date skeleton with abbreviated quarter. 859 */ 860 public static final String ABBR_QUARTER = "QQQ"; 861 862 /** 863 * <strong>[icu]</strong> Constant for date skeleton with year and quarter. 864 */ 865 public static final String YEAR_QUARTER = "yQQQQ"; 866 867 /** 868 * <strong>[icu]</strong> Constant for date skeleton with year and abbreviated quarter. 869 */ 870 public static final String YEAR_ABBR_QUARTER = "yQQQ"; 871 872 /** 873 * <strong>[icu]</strong> Constant for date skeleton with month. 874 */ 875 public static final String MONTH = "MMMM"; 876 877 /** 878 * <strong>[icu]</strong> Constant for date skeleton with abbreviated month. 879 */ 880 public static final String ABBR_MONTH = "MMM"; 881 882 /** 883 * <strong>[icu]</strong> Constant for date skeleton with numeric month. 884 */ 885 public static final String NUM_MONTH = "M"; 886 887 /** 888 * <strong>[icu]</strong> Constant for date skeleton with year and month. 889 */ 890 public static final String YEAR_MONTH = "yMMMM"; 891 892 /** 893 * <strong>[icu]</strong> Constant for date skeleton with year and abbreviated month. 894 */ 895 public static final String YEAR_ABBR_MONTH = "yMMM"; 896 897 /** 898 * <strong>[icu]</strong> Constant for date skeleton with year and numeric month. 899 */ 900 public static final String YEAR_NUM_MONTH = "yM"; 901 902 /** 903 * <strong>[icu]</strong> Constant for date skeleton with day. 904 */ 905 public static final String DAY = "d"; 906 907 /** 908 * <strong>[icu]</strong> Constant for date skeleton with year, month, and day. 909 * Used in combinations date + time, date + time + zone, or time + zone. 910 */ 911 public static final String YEAR_MONTH_DAY = "yMMMMd"; 912 913 /** 914 * <strong>[icu]</strong> Constant for date skeleton with year, abbreviated month, and day. 915 * Used in combinations date + time, date + time + zone, or time + zone. 916 */ 917 public static final String YEAR_ABBR_MONTH_DAY = "yMMMd"; 918 919 /** 920 * <strong>[icu]</strong> Constant for date skeleton with year, numeric month, and day. 921 * Used in combinations date + time, date + time + zone, or time + zone. 922 */ 923 public static final String YEAR_NUM_MONTH_DAY = "yMd"; 924 925 /** 926 * <strong>[icu]</strong> Constant for date skeleton with weekday. 927 */ 928 public static final String WEEKDAY = "EEEE"; 929 930 /** 931 * <strong>[icu]</strong> Constant for date skeleton with abbreviated weekday. 932 */ 933 public static final String ABBR_WEEKDAY = "E"; 934 935 /** 936 * <strong>[icu]</strong> Constant for date skeleton with year, month, weekday, and day. 937 * Used in combinations date + time, date + time + zone, or time + zone. 938 */ 939 public static final String YEAR_MONTH_WEEKDAY_DAY = "yMMMMEEEEd"; 940 941 /** 942 * <strong>[icu]</strong> Constant for date skeleton with year, abbreviated month, weekday, and day. 943 * Used in combinations date + time, date + time + zone, or time + zone. 944 */ 945 public static final String YEAR_ABBR_MONTH_WEEKDAY_DAY = "yMMMEd"; 946 947 /** 948 * <strong>[icu]</strong> Constant for date skeleton with year, numeric month, weekday, and day. 949 * Used in combinations date + time, date + time + zone, or time + zone. 950 */ 951 public static final String YEAR_NUM_MONTH_WEEKDAY_DAY = "yMEd"; 952 953 /** 954 * <strong>[icu]</strong> Constant for date skeleton with long month and day. 955 * Used in combinations date + time, date + time + zone, or time + zone. 956 */ 957 public static final String MONTH_DAY = "MMMMd"; 958 959 /** 960 * <strong>[icu]</strong> Constant for date skeleton with abbreviated month and day. 961 * Used in combinations date + time, date + time + zone, or time + zone. 962 */ 963 public static final String ABBR_MONTH_DAY = "MMMd"; 964 965 /** 966 * <strong>[icu]</strong> Constant for date skeleton with numeric month and day. 967 * Used in combinations date + time, date + time + zone, or time + zone. 968 */ 969 public static final String NUM_MONTH_DAY = "Md"; 970 971 /** 972 * <strong>[icu]</strong> Constant for date skeleton with month, weekday, and day. 973 * Used in combinations date + time, date + time + zone, or time + zone. 974 */ 975 public static final String MONTH_WEEKDAY_DAY = "MMMMEEEEd"; 976 977 /** 978 * <strong>[icu]</strong> Constant for date skeleton with abbreviated month, weekday, and day. 979 * Used in combinations date + time, date + time + zone, or time + zone. 980 */ 981 public static final String ABBR_MONTH_WEEKDAY_DAY = "MMMEd"; 982 983 /** 984 * <strong>[icu]</strong> Constant for date skeleton with numeric month, weekday, and day. 985 * Used in combinations date + time, date + time + zone, or time + zone. 986 */ 987 public static final String NUM_MONTH_WEEKDAY_DAY = "MEd"; 988 989 /** 990 * List of all of the date skeleton constants for iteration. 991 * Note that this is fragile; be sure to add any values that are added above. 992 * @deprecated This API is ICU internal only. 993 * @hide original deprecated declaration 994 * @hide draft / provisional / internal are hidden on Android 995 */ 996 @Deprecated 997 public static final List<String> DATE_SKELETONS = Arrays.asList( 998 YEAR, 999 QUARTER, 1000 ABBR_QUARTER, 1001 YEAR_QUARTER, 1002 YEAR_ABBR_QUARTER, 1003 MONTH, 1004 ABBR_MONTH, 1005 NUM_MONTH, 1006 YEAR_MONTH, 1007 YEAR_ABBR_MONTH, 1008 YEAR_NUM_MONTH, 1009 DAY, 1010 YEAR_MONTH_DAY, 1011 YEAR_ABBR_MONTH_DAY, 1012 YEAR_NUM_MONTH_DAY, 1013 WEEKDAY, 1014 ABBR_WEEKDAY, 1015 YEAR_MONTH_WEEKDAY_DAY, 1016 YEAR_ABBR_MONTH_WEEKDAY_DAY, 1017 YEAR_NUM_MONTH_WEEKDAY_DAY, 1018 MONTH_DAY, 1019 ABBR_MONTH_DAY, 1020 NUM_MONTH_DAY, 1021 MONTH_WEEKDAY_DAY, 1022 ABBR_MONTH_WEEKDAY_DAY, 1023 NUM_MONTH_WEEKDAY_DAY); 1024 1025 /* 1026 * TIMES 1027 */ 1028 1029 /** 1030 * <strong>[icu]</strong> Constant for date skeleton with hour, with the locale's preferred hour format (12 or 24). 1031 */ 1032 public static final String HOUR = "j"; 1033 1034 /** 1035 * <strong>[icu]</strong> Constant for date skeleton with hour in 24-hour presentation. 1036 */ 1037 public static final String HOUR24 = "H"; 1038 1039 /** 1040 * <strong>[icu]</strong> Constant for date skeleton with minute. 1041 */ 1042 public static final String MINUTE = "m"; 1043 1044 /** 1045 * <strong>[icu]</strong> Constant for date skeleton with hour and minute, with the locale's preferred hour format (12 or 24). 1046 * Used in combinations date + time, date + time + zone, or time + zone. 1047 */ 1048 public static final String HOUR_MINUTE = "jm"; 1049 1050 /** 1051 * <strong>[icu]</strong> Constant for date skeleton with hour and minute in 24-hour presentation. 1052 * Used in combinations date + time, date + time + zone, or time + zone. 1053 */ 1054 public static final String HOUR24_MINUTE = "Hm"; 1055 1056 /** 1057 * <strong>[icu]</strong> Constant for date skeleton with second. 1058 */ 1059 public static final String SECOND = "s"; 1060 1061 /** 1062 * <strong>[icu]</strong> Constant for date skeleton with hour, minute, and second, 1063 * with the locale's preferred hour format (12 or 24). 1064 * Used in combinations date + time, date + time + zone, or time + zone. 1065 */ 1066 public static final String HOUR_MINUTE_SECOND = "jms"; 1067 1068 /** 1069 * <strong>[icu]</strong> Constant for date skeleton with hour, minute, and second in 1070 * 24-hour presentation. 1071 * Used in combinations date + time, date + time + zone, or time + zone. 1072 */ 1073 public static final String HOUR24_MINUTE_SECOND = "Hms"; 1074 1075 /** 1076 * <strong>[icu]</strong> Constant for date skeleton with minute and second. 1077 * Used in combinations date + time, date + time + zone, or time + zone. 1078 */ 1079 public static final String MINUTE_SECOND = "ms"; 1080 1081 /** 1082 * List of all of the time skeleton constants for iteration. 1083 * Note that this is fragile; be sure to add any values that are added above. 1084 * @deprecated This API is ICU internal only. 1085 * @hide original deprecated declaration 1086 * @hide draft / provisional / internal are hidden on Android 1087 */ 1088 @Deprecated 1089 public static final List<String> TIME_SKELETONS = Arrays.asList( 1090 HOUR, 1091 HOUR24, 1092 MINUTE, 1093 HOUR_MINUTE, 1094 HOUR24_MINUTE, 1095 SECOND, 1096 HOUR_MINUTE_SECOND, 1097 HOUR24_MINUTE_SECOND, 1098 MINUTE_SECOND); 1099 1100 /* 1101 * TIMEZONES 1102 */ 1103 1104 /** 1105 * <strong>[icu]</strong> Constant for <i>generic location format</i>, such as Los Angeles Time; 1106 * used in combinations date + time + zone, or time + zone. 1107 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a> 1108 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a> 1109 */ 1110 public static final String LOCATION_TZ = "VVVV"; 1111 1112 /** 1113 * <strong>[icu]</strong> Constant for <i>generic non-location format</i>, such as Pacific Time; 1114 * used in combinations date + time + zone, or time + zone. 1115 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a> 1116 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a> 1117 */ 1118 public static final String GENERIC_TZ = "vvvv"; 1119 1120 /** 1121 * <strong>[icu]</strong> Constant for <i>generic non-location format</i>, abbreviated if possible, such as PT; 1122 * used in combinations date + time + zone, or time + zone. 1123 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a> 1124 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a> 1125 */ 1126 public static final String ABBR_GENERIC_TZ = "v"; 1127 1128 /** 1129 * <strong>[icu]</strong> Constant for <i>specific non-location format</i>, such as Pacific Daylight Time; 1130 * used in combinations date + time + zone, or time + zone. 1131 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a> 1132 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a> 1133 */ 1134 public static final String SPECIFIC_TZ = "zzzz"; 1135 1136 /** 1137 * <strong>[icu]</strong> Constant for <i>specific non-location format</i>, abbreviated if possible, such as PDT; 1138 * used in combinations date + time + zone, or time + zone. 1139 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a> 1140 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a> 1141 */ 1142 public static final String ABBR_SPECIFIC_TZ = "z"; 1143 1144 /** 1145 * <strong>[icu]</strong> Constant for <i>localized GMT/UTC format</i>, such as GMT+8:00 or HPG-8:00; 1146 * used in combinations date + time + zone, or time + zone. 1147 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a> 1148 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a> 1149 */ 1150 public static final String ABBR_UTC_TZ = "ZZZZ"; 1151 1152 /** 1153 * List of all of the zone skeleton constants for iteration. 1154 * Note that this is fragile; be sure to add any values that are added above. 1155 * @deprecated This API is ICU internal only. 1156 * @hide original deprecated declaration 1157 * @hide draft / provisional / internal are hidden on Android 1158 */ 1159 @Deprecated 1160 public static final List<String> ZONE_SKELETONS = Arrays.asList( 1161 LOCATION_TZ, 1162 GENERIC_TZ, 1163 ABBR_GENERIC_TZ, 1164 SPECIFIC_TZ, 1165 ABBR_SPECIFIC_TZ, 1166 ABBR_UTC_TZ); 1167 1168 /* 1169 * deprecated skeleton constants 1170 */ 1171 1172 /** 1173 * <strong>[icu]</strong> Constant for date skeleton with standalone month. 1174 * @deprecated ICU 50 Use {@link #MONTH} instead. 1175 * @hide original deprecated declaration 1176 */ 1177 @Deprecated 1178 public static final String STANDALONE_MONTH = "LLLL"; 1179 1180 /** 1181 * <strong>[icu]</strong> Constant for date skeleton with standalone abbreviated month. 1182 * @deprecated ICU 50 Use {@link #ABBR_MONTH} instead. 1183 * @hide original deprecated declaration 1184 */ 1185 @Deprecated 1186 public static final String ABBR_STANDALONE_MONTH = "LLL"; 1187 1188 /** 1189 * <strong>[icu]</strong> Constant for date skeleton with hour, minute, and generic timezone. 1190 * @deprecated ICU 50 Use instead {@link #HOUR_MINUTE}+{@link #ABBR_GENERIC_TZ} or some other timezone presentation. 1191 * @hide original deprecated declaration 1192 */ 1193 @Deprecated 1194 public static final String HOUR_MINUTE_GENERIC_TZ = "jmv"; 1195 1196 /** 1197 * <strong>[icu]</strong> Constant for date skeleton with hour, minute, and timezone. 1198 * @deprecated ICU 50 Use instead {@link #HOUR_MINUTE}+{@link #ABBR_SPECIFIC_TZ} or some other timezone presentation. 1199 * @hide original deprecated declaration 1200 */ 1201 @Deprecated 1202 public static final String HOUR_MINUTE_TZ = "jmz"; 1203 1204 /** 1205 * <strong>[icu]</strong> Constant for date skeleton with hour and generic timezone. 1206 * @deprecated ICU 50 Use instead {@link #HOUR}+{@link #ABBR_GENERIC_TZ} or some other timezone presentation. 1207 * @hide original deprecated declaration 1208 */ 1209 @Deprecated 1210 public static final String HOUR_GENERIC_TZ = "jv"; 1211 1212 /** 1213 * <strong>[icu]</strong> Constant for date skeleton with hour and timezone. 1214 * @deprecated ICU 50 Use instead {@link #HOUR}+{@link #ABBR_SPECIFIC_TZ} or some other timezone presentation. 1215 * @hide original deprecated declaration 1216 */ 1217 @Deprecated 1218 public static final String HOUR_TZ = "jz"; 1219 1220 1221 /** 1222 * Gets the time formatter with the default formatting style 1223 * for the default <code>FORMAT</code> locale. 1224 * @return a time formatter. 1225 * @see Category#FORMAT 1226 */ 1227 public final static DateFormat getTimeInstance() 1228 { 1229 return get(-1, DEFAULT, ULocale.getDefault(Category.FORMAT), null); 1230 } 1231 1232 /** 1233 * Returns the time formatter with the given formatting style 1234 * for the default <code>FORMAT</code> locale. 1235 * @param style the given formatting style. For example, 1236 * SHORT for "h:mm a" in the US locale. Relative time styles are not currently 1237 * supported, and behave just like the corresponding non-relative style. 1238 * @return a time formatter. 1239 * @see Category#FORMAT 1240 */ 1241 public final static DateFormat getTimeInstance(int style) 1242 { 1243 return get(-1, style, ULocale.getDefault(Category.FORMAT), null); 1244 } 1245 1246 /** 1247 * Returns the time formatter with the given formatting style 1248 * for the given locale. 1249 * @param style the given formatting style. For example, 1250 * SHORT for "h:mm a" in the US locale. Relative time styles are not currently 1251 * supported, and behave just like the corresponding non-relative style. 1252 * @param aLocale the given locale. 1253 * @return a time formatter. 1254 */ 1255 public final static DateFormat getTimeInstance(int style, 1256 Locale aLocale) 1257 { 1258 return get(-1, style, ULocale.forLocale(aLocale), null); 1259 } 1260 1261 /** 1262 * Returns the time formatter with the given formatting style 1263 * for the given locale. 1264 * @param style the given formatting style. For example, 1265 * SHORT for "h:mm a" in the US locale. Relative time styles are not currently 1266 * supported, and behave just like the corresponding non-relative style. 1267 * @param locale the given ulocale. 1268 * @return a time formatter. 1269 */ 1270 public final static DateFormat getTimeInstance(int style, 1271 ULocale locale) 1272 { 1273 return get(-1, style, locale, null); 1274 } 1275 1276 /** 1277 * Returns the date formatter with the default formatting style 1278 * for the default <code>FORMAT</code> locale. 1279 * @return a date formatter. 1280 * @see Category#FORMAT 1281 */ 1282 public final static DateFormat getDateInstance() 1283 { 1284 return get(DEFAULT, -1, ULocale.getDefault(Category.FORMAT), null); 1285 } 1286 1287 /** 1288 * Returns the date formatter with the given formatting style 1289 * for the default <code>FORMAT</code> locale. 1290 * @param style the given formatting style. For example, 1291 * SHORT for "M/d/yy" in the US locale. As currently implemented, relative date 1292 * formatting only affects a limited range of calendar days before or after the 1293 * current date, based on the CLDR <field type="day">/<relative> data: For example, 1294 * in English, "Yesterday", "Today", and "Tomorrow". Outside of this range, relative 1295 * dates are formatted using the corresponding non-relative style. 1296 * @return a date formatter. 1297 * @see Category#FORMAT 1298 */ 1299 public final static DateFormat getDateInstance(int style) 1300 { 1301 return get(style, -1, ULocale.getDefault(Category.FORMAT), null); 1302 } 1303 1304 /** 1305 * Returns the date formatter with the given formatting style 1306 * for the given locale. 1307 * @param style the given formatting style. For example, 1308 * SHORT for "M/d/yy" in the US locale. As currently implemented, relative date 1309 * formatting only affects a limited range of calendar days before or after the 1310 * current date, based on the CLDR <field type="day">/<relative> data: For example, 1311 * in English, "Yesterday", "Today", and "Tomorrow". Outside of this range, relative 1312 * dates are formatted using the corresponding non-relative style. 1313 * @param aLocale the given locale. 1314 * @return a date formatter. 1315 */ 1316 public final static DateFormat getDateInstance(int style, 1317 Locale aLocale) 1318 { 1319 return get(style, -1, ULocale.forLocale(aLocale), null); 1320 } 1321 1322 /** 1323 * Returns the date formatter with the given formatting style 1324 * for the given locale. 1325 * @param style the given formatting style. For example, 1326 * SHORT for "M/d/yy" in the US locale. As currently implemented, relative date 1327 * formatting only affects a limited range of calendar days before or after the 1328 * current date, based on the CLDR <field type="day">/<relative> data: For example, 1329 * in English, "Yesterday", "Today", and "Tomorrow". Outside of this range, relative 1330 * dates are formatted using the corresponding non-relative style. 1331 * @param locale the given ulocale. 1332 * @return a date formatter. 1333 */ 1334 public final static DateFormat getDateInstance(int style, 1335 ULocale locale) 1336 { 1337 return get(style, -1, locale, null); 1338 } 1339 1340 /** 1341 * Returns the date/time formatter with the default formatting style 1342 * for the default <code>FORMAT</code> locale. 1343 * @return a date/time formatter. 1344 * @see Category#FORMAT 1345 */ 1346 public final static DateFormat getDateTimeInstance() 1347 { 1348 return get(DEFAULT, DEFAULT, ULocale.getDefault(Category.FORMAT), null); 1349 } 1350 1351 /** 1352 * Returns the date/time formatter with the given date and time 1353 * formatting styles for the default <code>FORMAT</code> locale. 1354 * @param dateStyle the given date formatting style. For example, 1355 * SHORT for "M/d/yy" in the US locale. As currently implemented, relative date 1356 * formatting only affects a limited range of calendar days before or after the 1357 * current date, based on the CLDR <field type="day">/<relative> data: For example, 1358 * in English, "Yesterday", "Today", and "Tomorrow". Outside of this range, relative 1359 * dates are formatted using the corresponding non-relative style. 1360 * @param timeStyle the given time formatting style. For example, 1361 * SHORT for "h:mm a" in the US locale. Relative time styles are not currently 1362 * supported, and behave just like the corresponding non-relative style. 1363 * @return a date/time formatter. 1364 * @see Category#FORMAT 1365 */ 1366 public final static DateFormat getDateTimeInstance(int dateStyle, 1367 int timeStyle) 1368 { 1369 return get(dateStyle, timeStyle, ULocale.getDefault(Category.FORMAT), null); 1370 } 1371 1372 /** 1373 * Returns the date/time formatter with the given formatting styles 1374 * for the given locale. 1375 * @param dateStyle the given date formatting style. As currently implemented, relative date 1376 * formatting only affects a limited range of calendar days before or after the 1377 * current date, based on the CLDR <field type="day">/<relative> data: For example, 1378 * in English, "Yesterday", "Today", and "Tomorrow". Outside of this range, relative 1379 * dates are formatted using the corresponding non-relative style. 1380 * @param timeStyle the given time formatting style. Relative time styles are not 1381 * currently supported, and behave just like the corresponding non-relative style. 1382 * @param aLocale the given locale. 1383 * @return a date/time formatter. 1384 */ 1385 public final static DateFormat getDateTimeInstance( 1386 int dateStyle, int timeStyle, Locale aLocale) 1387 { 1388 return get(dateStyle, timeStyle, ULocale.forLocale(aLocale), null); 1389 } 1390 1391 /** 1392 * Returns the date/time formatter with the given formatting styles 1393 * for the given locale. 1394 * @param dateStyle the given date formatting style. As currently implemented, relative date 1395 * formatting only affects a limited range of calendar days before or after the 1396 * current date, based on the CLDR <field type="day">/<relative> data: For example, 1397 * in English, "Yesterday", "Today", and "Tomorrow". Outside of this range, relative 1398 * dates are formatted using the corresponding non-relative style. 1399 * @param timeStyle the given time formatting style. Relative time styles are not 1400 * currently supported, and behave just like the corresponding non-relative style. 1401 * @param locale the given ulocale. 1402 * @return a date/time formatter. 1403 */ 1404 public final static DateFormat getDateTimeInstance( 1405 int dateStyle, int timeStyle, ULocale locale) 1406 { 1407 return get(dateStyle, timeStyle, locale, null); 1408 } 1409 1410 /** 1411 * Returns a default date/time formatter that uses the SHORT style for both the 1412 * date and the time. 1413 */ 1414 public final static DateFormat getInstance() { 1415 return getDateTimeInstance(SHORT, SHORT); 1416 } 1417 1418 /** 1419 * Returns the set of locales for which DateFormats are installed. 1420 * @return the set of locales for which DateFormats are installed. 1421 */ 1422 public static Locale[] getAvailableLocales() 1423 { 1424 return ICUResourceBundle.getAvailableLocales(); 1425 } 1426 1427 /** 1428 * <strong>[icu]</strong> Returns the set of locales for which DateFormats are installed. 1429 * @return the set of locales for which DateFormats are installed. 1430 * @hide draft / provisional / internal are hidden on Android 1431 */ 1432 public static ULocale[] getAvailableULocales() 1433 { 1434 return ICUResourceBundle.getAvailableULocales(); 1435 } 1436 1437 /** 1438 * Sets the calendar to be used by this date format. Initially, the default 1439 * calendar for the specified or default locale is used. 1440 * @param newCalendar the new Calendar to be used by the date format 1441 */ 1442 public void setCalendar(Calendar newCalendar) 1443 { 1444 this.calendar = newCalendar; 1445 } 1446 1447 /** 1448 * Returns the calendar associated with this date/time formatter. 1449 * @return the calendar associated with this date/time formatter. 1450 */ 1451 public Calendar getCalendar() 1452 { 1453 return calendar; 1454 } 1455 1456 /** 1457 * Sets the number formatter. 1458 * @param newNumberFormat the given new NumberFormat. 1459 */ 1460 public void setNumberFormat(NumberFormat newNumberFormat) 1461 { 1462 this.numberFormat = newNumberFormat; 1463 /*In order to parse String like "11.10.2001" to DateTime correctly 1464 in Locale("fr","CH") [Richard/GCL] 1465 */ 1466 this.numberFormat.setParseIntegerOnly(true); 1467 } 1468 1469 /** 1470 * Returns the number formatter which this date/time formatter uses to 1471 * format and parse a time. 1472 * @return the number formatter which this date/time formatter uses. 1473 */ 1474 public NumberFormat getNumberFormat() 1475 { 1476 return numberFormat; 1477 } 1478 1479 /** 1480 * Sets the time zone for the calendar of this DateFormat object. 1481 * @param zone the given new time zone. 1482 */ 1483 public void setTimeZone(TimeZone zone) 1484 { 1485 calendar.setTimeZone(zone); 1486 } 1487 1488 /** 1489 * Returns the time zone. 1490 * @return the time zone associated with the calendar of DateFormat. 1491 */ 1492 public TimeZone getTimeZone() 1493 { 1494 return calendar.getTimeZone(); 1495 } 1496 1497 /** 1498 * Specifies whether date/time parsing is to be lenient. With 1499 * lenient parsing, the parser may use heuristics to interpret inputs that 1500 * do not precisely match this object's format. Without lenient parsing, 1501 * inputs must match this object's format more closely. 1502 * <br><br> 1503 * <b>Note:</b> ICU 53 introduced finer grained control of leniency (and added 1504 * new control points) making the preferred method a combination of 1505 * setCalendarLenient() & setBooleanAttribute() calls. 1506 * This method supports prior functionality but may not support all 1507 * future leniency control & behavior of DateFormat. For control of pre 53 leniency, 1508 * Calendar and DateFormat whitespace & numeric tolerance, this method is safe to 1509 * use. However, mixing leniency control via this method and modification of the 1510 * newer attributes via setBooleanAttribute() may produce undesirable 1511 * results. 1512 * 1513 * @param lenient True specifies date/time interpretation to be lenient. 1514 * @see android.icu.util.Calendar#setLenient 1515 * @see #setBooleanAttribute(BooleanAttribute, boolean) 1516 * @see #setCalendarLenient(boolean) 1517 */ 1518 public void setLenient(boolean lenient) 1519 { 1520 calendar.setLenient(lenient); 1521 setBooleanAttribute(BooleanAttribute.PARSE_ALLOW_NUMERIC, lenient); 1522 setBooleanAttribute(BooleanAttribute.PARSE_ALLOW_WHITESPACE, lenient); 1523 } 1524 1525 /** 1526 * Returns whether both date/time parsing in the encapsulated Calendar object and DateFormat whitespace & 1527 * numeric processing is lenient. 1528 */ 1529 public boolean isLenient() 1530 { 1531 return calendar.isLenient() 1532 && getBooleanAttribute(BooleanAttribute.PARSE_ALLOW_NUMERIC) 1533 && getBooleanAttribute(BooleanAttribute.PARSE_ALLOW_WHITESPACE); 1534 } 1535 1536 /** 1537 * Specifies whether date/time parsing in the encapsulated Calendar object should be lenient. 1538 * With lenient parsing, the parser may use heuristics to interpret inputs that 1539 * do not precisely match this object's format. Without lenient parsing, 1540 * inputs must match this object's format more closely. 1541 * @param lenient when true, Calendar parsing is lenient 1542 * @see android.icu.util.Calendar#setLenient 1543 */ 1544 public void setCalendarLenient(boolean lenient) 1545 { 1546 calendar.setLenient(lenient); 1547 } 1548 1549 1550 /** 1551 * Returns whether date/time parsing in the encapsulated Calendar object is lenient. 1552 */ 1553 public boolean isCalendarLenient() 1554 { 1555 return calendar.isLenient(); 1556 } 1557 1558 /** 1559 * Sets a boolean attribute for this instance. Aspects of DateFormat leniency are controlled by 1560 * boolean attributes. 1561 * 1562 * @see BooleanAttribute 1563 */ 1564 public DateFormat setBooleanAttribute(BooleanAttribute key, boolean value) 1565 { 1566 if(key.equals(DateFormat.BooleanAttribute.PARSE_PARTIAL_MATCH)) { 1567 key = DateFormat.BooleanAttribute.PARSE_PARTIAL_LITERAL_MATCH; 1568 } 1569 if(value) 1570 { 1571 booleanAttributes.add(key); 1572 } 1573 else 1574 { 1575 booleanAttributes.remove(key); 1576 } 1577 1578 return this; 1579 } 1580 1581 /** 1582 * Returns the current value for the specified BooleanAttribute for this instance 1583 * 1584 * if attribute is missing false is returned. 1585 * 1586 * @see BooleanAttribute 1587 */ 1588 public boolean getBooleanAttribute(BooleanAttribute key) 1589 { 1590 if(key == DateFormat.BooleanAttribute.PARSE_PARTIAL_MATCH) { 1591 key = DateFormat.BooleanAttribute.PARSE_PARTIAL_LITERAL_MATCH; 1592 } 1593 return booleanAttributes.contains(key); 1594 } 1595 1596 1597 /** 1598 * <strong>[icu]</strong> Set a particular DisplayContext value in the formatter, 1599 * such as CAPITALIZATION_FOR_STANDALONE. 1600 * 1601 * @param context The DisplayContext value to set. 1602 */ 1603 public void setContext(DisplayContext context) { 1604 if (context.type() == DisplayContext.Type.CAPITALIZATION) { 1605 capitalizationSetting = context; 1606 } 1607 } 1608 1609 /** 1610 * <strong>[icu]</strong> Get the formatter's DisplayContext value for the specified DisplayContext.Type, 1611 * such as CAPITALIZATION. 1612 * 1613 * @param type the DisplayContext.Type whose value to return 1614 * @return the current DisplayContext setting for the specified type 1615 */ 1616 public DisplayContext getContext(DisplayContext.Type type) { 1617 return (type == DisplayContext.Type.CAPITALIZATION && capitalizationSetting != null)? 1618 capitalizationSetting: DisplayContext.CAPITALIZATION_NONE; 1619 } 1620 1621 /** 1622 * Overrides hashCode. 1623 */ 1624 ///CLOVER:OFF 1625 // turn off code coverage since all subclasses override this 1626 @Override 1627 public int hashCode() { 1628 return numberFormat.hashCode(); 1629 // just enough fields for a reasonable distribution 1630 } 1631 ///CLOVER:ON 1632 1633 /** 1634 * Overrides equals. 1635 */ 1636 @Override 1637 public boolean equals(Object obj) { 1638 if (this == obj) return true; 1639 if (obj == null || getClass() != obj.getClass()) return false; 1640 DateFormat other = (DateFormat) obj; 1641 return (((calendar==null && other.calendar==null) || 1642 (calendar!=null && other.calendar!=null && calendar.isEquivalentTo(other.calendar))) && 1643 ((numberFormat==null && other.numberFormat==null) || 1644 (numberFormat!=null && other.numberFormat!=null && numberFormat.equals(other.numberFormat))) && 1645 capitalizationSetting == other.capitalizationSetting); 1646 } 1647 1648 /** 1649 * Overrides clone. 1650 */ 1651 @Override 1652 public Object clone() 1653 { 1654 DateFormat other = (DateFormat) super.clone(); 1655 other.calendar = (Calendar) calendar.clone(); 1656 if (numberFormat != null) { 1657 other.numberFormat = (NumberFormat) numberFormat.clone(); 1658 } 1659 return other; 1660 } 1661 1662 /** 1663 * Creates a DateFormat with the given time and/or date style in the given 1664 * locale. 1665 * @param dateStyle a value from 0 to 3 indicating the time format, 1666 * or -1 to indicate no date 1667 * @param timeStyle a value from 0 to 3 indicating the time format, 1668 * or -1 to indicate no time 1669 * @param loc the locale for the format 1670 * @param cal the calendar to be used, or null 1671 */ 1672 private static DateFormat get(int dateStyle, int timeStyle, ULocale loc, Calendar cal) { 1673 if((timeStyle != DateFormat.NONE && (timeStyle & RELATIVE)>0) || 1674 (dateStyle != DateFormat.NONE && (dateStyle & RELATIVE)>0)) { 1675 RelativeDateFormat r = new RelativeDateFormat(timeStyle, dateStyle /* offset? */, loc, cal); 1676 return r; 1677 } 1678 1679 if (timeStyle < DateFormat.NONE || timeStyle > DateFormat.SHORT) { 1680 throw new IllegalArgumentException("Illegal time style " + timeStyle); 1681 } 1682 if (dateStyle < DateFormat.NONE || dateStyle > DateFormat.SHORT) { 1683 throw new IllegalArgumentException("Illegal date style " + dateStyle); 1684 } 1685 1686 if (cal == null) { 1687 cal = Calendar.getInstance(loc); 1688 } 1689 1690 try { 1691 DateFormat result = cal.getDateTimeFormat(dateStyle, timeStyle, loc); 1692 result.setLocale(cal.getLocale(ULocale.VALID_LOCALE), 1693 cal.getLocale(ULocale.ACTUAL_LOCALE)); 1694 return result; 1695 } catch (MissingResourceException e) { 1696 ///CLOVER:OFF 1697 // coverage requires separate run with no data, so skip 1698 return new SimpleDateFormat("M/d/yy h:mm a"); 1699 ///CLOVER:ON 1700 } 1701 } 1702 1703 /** 1704 * First, read in the default serializable data. 1705 * 1706 * Then, if <code>serialVersionOnStream</code> is less than 1, indicating that 1707 * the stream was written by a pre-ICU-53 version, 1708 * set capitalizationSetting to a default value. 1709 * Finally, set serialVersionOnStream back to the maximum allowed value so that 1710 * default serialization will work properly if this object is streamed out again. 1711 */ 1712 private void readObject(ObjectInputStream stream) 1713 throws IOException, ClassNotFoundException 1714 { 1715 stream.defaultReadObject(); 1716 if (serialVersionOnStream < 1) { 1717 // Didn't have capitalizationSetting, set it to default 1718 capitalizationSetting = DisplayContext.CAPITALIZATION_NONE; 1719 } 1720 1721 // if deserialized from a release that didn't have booleanAttributes, add them all 1722 if(booleanAttributes == null) { 1723 booleanAttributes = EnumSet.allOf(BooleanAttribute.class); 1724 } 1725 1726 serialVersionOnStream = currentSerialVersion; 1727 } 1728 1729 /** 1730 * Creates a new date format. 1731 */ 1732 protected DateFormat() {} 1733 1734 //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1735 1736 //------------------------------------------------------------------------- 1737 // Public static interface for creating custon DateFormats for different 1738 // types of Calendars. 1739 //------------------------------------------------------------------------- 1740 1741 /** 1742 * Creates a {@link DateFormat} object that can be used to format dates in 1743 * the calendar system specified by <code>cal</code>. 1744 * <p> 1745 * @param cal The calendar system for which a date format is desired. 1746 * 1747 * @param dateStyle The type of date format desired. This can be 1748 * {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM}, 1749 * etc. 1750 * 1751 * @param locale The locale for which the date format is desired. 1752 */ 1753 static final public DateFormat getDateInstance(Calendar cal, int dateStyle, Locale locale) 1754 { 1755 return getDateTimeInstance(cal, dateStyle, -1, ULocale.forLocale(locale)); 1756 } 1757 1758 /** 1759 * Creates a {@link DateFormat} object that can be used to format dates in 1760 * the calendar system specified by <code>cal</code>. 1761 * <p> 1762 * @param cal The calendar system for which a date format is desired. 1763 * 1764 * @param dateStyle The type of date format desired. This can be 1765 * {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM}, 1766 * etc. 1767 * 1768 * @param locale The locale for which the date format is desired. 1769 */ 1770 static final public DateFormat getDateInstance(Calendar cal, int dateStyle, ULocale locale) 1771 { 1772 return getDateTimeInstance(cal, dateStyle, -1, locale); 1773 } 1774 1775 /** 1776 * Creates a {@link DateFormat} object that can be used to format times in 1777 * the calendar system specified by <code>cal</code>. 1778 * @param cal The calendar system for which a time format is desired. 1779 * 1780 * @param timeStyle The type of time format desired. This can be 1781 * {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM}, 1782 * etc. 1783 * 1784 * @param locale The locale for which the time format is desired. 1785 * 1786 * @see DateFormat#getTimeInstance 1787 */ 1788 static final public DateFormat getTimeInstance(Calendar cal, int timeStyle, Locale locale) 1789 { 1790 return getDateTimeInstance(cal, -1, timeStyle, ULocale.forLocale(locale)); 1791 } 1792 1793 /** 1794 * Creates a {@link DateFormat} object that can be used to format times in 1795 * the calendar system specified by <code>cal</code>. 1796 * @param cal The calendar system for which a time format is desired. 1797 * 1798 * @param timeStyle The type of time format desired. This can be 1799 * {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM}, 1800 * etc. 1801 * 1802 * @param locale The locale for which the time format is desired. 1803 * 1804 * @see DateFormat#getTimeInstance 1805 */ 1806 static final public DateFormat getTimeInstance(Calendar cal, int timeStyle, ULocale locale) 1807 { 1808 return getDateTimeInstance(cal, -1, timeStyle, locale); 1809 } 1810 1811 /** 1812 * Creates a {@link DateFormat} object that can be used to format dates and times in 1813 * the calendar system specified by <code>cal</code>. 1814 * @param cal The calendar system for which a date/time format is desired. 1815 * 1816 * @param dateStyle The type of date format desired. This can be 1817 * {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM}, 1818 * etc. 1819 * 1820 * @param timeStyle The type of time format desired. This can be 1821 * {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM}, 1822 * etc. 1823 * 1824 * @param locale The locale for which the date/time format is desired. 1825 * 1826 * @see DateFormat#getDateTimeInstance 1827 */ 1828 static final public DateFormat getDateTimeInstance(Calendar cal, int dateStyle, 1829 int timeStyle, Locale locale) 1830 { 1831 return getDateTimeInstance(dateStyle, timeStyle, ULocale.forLocale(locale)); 1832 } 1833 1834 /** 1835 * Creates a {@link DateFormat} object that can be used to format dates and times in 1836 * the calendar system specified by <code>cal</code>. 1837 * @param cal The calendar system for which a date/time format is desired. 1838 * 1839 * @param dateStyle The type of date format desired. This can be 1840 * {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM}, 1841 * etc. 1842 * 1843 * @param timeStyle The type of time format desired. This can be 1844 * {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM}, 1845 * etc. 1846 * 1847 * @param locale The locale for which the date/time format is desired. 1848 * 1849 * @see DateFormat#getDateTimeInstance 1850 */ 1851 static final public DateFormat getDateTimeInstance(Calendar cal, int dateStyle, 1852 int timeStyle, ULocale locale) 1853 { 1854 if (cal == null) { 1855 throw new IllegalArgumentException("Calendar must be supplied"); 1856 } 1857 return get(dateStyle, timeStyle, locale, cal); 1858 } 1859 1860 /** 1861 * Returns a date/time formatter that uses the SHORT style 1862 * for both the date and the time. 1863 * 1864 * @param cal The calendar system for which a date/time format is desired. 1865 * @param locale The locale for which the date/time format is desired. 1866 */ 1867 static final public DateFormat getInstance(Calendar cal, Locale locale) { 1868 return getDateTimeInstance(cal, SHORT, SHORT, ULocale.forLocale(locale)); 1869 } 1870 1871 /** 1872 * Returns a date/time formatter that uses the SHORT style 1873 * for both the date and the time. 1874 * 1875 * @param cal The calendar system for which a date/time format is desired. 1876 * @param locale The locale for which the date/time format is desired. 1877 * @hide draft / provisional / internal are hidden on Android 1878 */ 1879 static final public DateFormat getInstance(Calendar cal, ULocale locale) { 1880 return getDateTimeInstance(cal, SHORT, SHORT, locale); 1881 } 1882 1883 /** 1884 * Returns a default date/time formatter that uses the SHORT style for both the 1885 * date and the time. 1886 * 1887 * @param cal The calendar system for which a date/time format is desired. 1888 */ 1889 static final public DateFormat getInstance(Calendar cal) { 1890 return getInstance(cal, ULocale.getDefault(Category.FORMAT)); 1891 } 1892 1893 /** 1894 * Creates a {@link DateFormat} object for the default locale that can be used 1895 * to format dates in the calendar system specified by <code>cal</code>. 1896 * <p> 1897 * @param cal The calendar system for which a date format is desired. 1898 * 1899 * @param dateStyle The type of date format desired. This can be 1900 * {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM}, 1901 * etc. 1902 */ 1903 static final public DateFormat getDateInstance(Calendar cal, int dateStyle) { 1904 return getDateInstance(cal, dateStyle, ULocale.getDefault(Category.FORMAT)); 1905 } 1906 1907 /** 1908 * Creates a {@link DateFormat} object that can be used to format times in 1909 * the calendar system specified by <code>cal</code>. 1910 * @param cal The calendar system for which a time format is desired. 1911 * 1912 * @param timeStyle The type of time format desired. This can be 1913 * {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM}, 1914 * etc. 1915 * 1916 * @see DateFormat#getTimeInstance 1917 */ 1918 static final public DateFormat getTimeInstance(Calendar cal, int timeStyle) { 1919 return getTimeInstance(cal, timeStyle, ULocale.getDefault(Category.FORMAT)); 1920 } 1921 1922 /** 1923 * Creates a {@link DateFormat} object for the default locale that can be used to format 1924 * dates and times in the calendar system specified by <code>cal</code>. 1925 * @param cal The calendar system for which a date/time format is desired. 1926 * 1927 * @param dateStyle The type of date format desired. This can be 1928 * {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM}, 1929 * etc. 1930 * 1931 * @param timeStyle The type of time format desired. This can be 1932 * {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM}, 1933 * etc. 1934 * 1935 * @see DateFormat#getDateTimeInstance 1936 */ 1937 static final public DateFormat getDateTimeInstance(Calendar cal, int dateStyle, int timeStyle) { 1938 return getDateTimeInstance(cal, dateStyle, timeStyle, ULocale.getDefault(Category.FORMAT)); 1939 } 1940 1941 /** 1942 * <strong>[icu]</strong> Returns a {@link DateFormat} object that can be used to format dates and times in 1943 * the default locale. 1944 * 1945 * @param skeleton The skeleton that selects the fields to be formatted. (Uses the 1946 * {@link DateTimePatternGenerator}.) This can be {@link DateFormat#ABBR_MONTH}, 1947 * {@link DateFormat#MONTH_WEEKDAY_DAY}, etc. 1948 */ 1949 public final static DateFormat getInstanceForSkeleton(String skeleton) { 1950 return getPatternInstance(skeleton, ULocale.getDefault(Category.FORMAT)); 1951 } 1952 1953 /** 1954 * <strong>[icu]</strong> Returns a {@link DateFormat} object that can be used to format dates and times in 1955 * the given locale. 1956 * 1957 * @param skeleton The skeleton that selects the fields to be formatted. (Uses the 1958 * {@link DateTimePatternGenerator}.) This can be {@link DateFormat#ABBR_MONTH}, 1959 * {@link DateFormat#MONTH_WEEKDAY_DAY}, etc. 1960 * 1961 * @param locale The locale for which the date/time format is desired. 1962 */ 1963 public final static DateFormat getInstanceForSkeleton(String skeleton, Locale locale) { 1964 return getPatternInstance(skeleton, ULocale.forLocale(locale)); 1965 } 1966 1967 /** 1968 * <strong>[icu]</strong> Returns a {@link DateFormat} object that can be used to format dates and times in 1969 * the given locale. 1970 * 1971 * @param skeleton The skeleton that selects the fields to be formatted. (Uses the 1972 * {@link DateTimePatternGenerator}.) This can be {@link DateFormat#ABBR_MONTH}, 1973 * {@link DateFormat#MONTH_WEEKDAY_DAY}, etc. 1974 * 1975 * @param locale The locale for which the date/time format is desired. 1976 */ 1977 public final static DateFormat getInstanceForSkeleton(String skeleton, ULocale locale) { 1978 DateTimePatternGenerator generator = DateTimePatternGenerator.getInstance(locale); 1979 final String bestPattern = generator.getBestPattern(skeleton); 1980 return new SimpleDateFormat(bestPattern, locale); 1981 } 1982 1983 /** 1984 * <strong>[icu]</strong> Creates a {@link DateFormat} object that can be used to format dates and 1985 * times in the calendar system specified by <code>cal</code>. 1986 * 1987 * @param cal The calendar system for which a date/time format is desired. 1988 * 1989 * @param skeleton The skeleton that selects the fields to be formatted. (Uses the 1990 * {@link DateTimePatternGenerator}.) This can be 1991 * {@link DateFormat#ABBR_MONTH}, {@link DateFormat#MONTH_WEEKDAY_DAY}, 1992 * etc. 1993 * 1994 * @param locale The locale for which the date/time format is desired. 1995 */ 1996 public final static DateFormat getInstanceForSkeleton(Calendar cal, String skeleton, Locale locale) { 1997 return getPatternInstance(cal, skeleton, ULocale.forLocale(locale)); 1998 } 1999 2000 /** 2001 * <strong>[icu]</strong> Creates a {@link DateFormat} object that can be used to format dates and 2002 * times in the calendar system specified by <code>cal</code>. 2003 * 2004 * @param cal The calendar system for which a date/time format is desired. 2005 * 2006 * @param skeleton The skeleton that selects the fields to be formatted. (Uses the 2007 * {@link DateTimePatternGenerator}.) This can be 2008 * {@link DateFormat#ABBR_MONTH}, {@link DateFormat#MONTH_WEEKDAY_DAY}, 2009 * etc. 2010 * 2011 * @param locale The locale for which the date/time format is desired. 2012 */ 2013 public final static DateFormat getInstanceForSkeleton( 2014 Calendar cal, String skeleton, ULocale locale) { 2015 DateTimePatternGenerator generator = DateTimePatternGenerator.getInstance(locale); 2016 final String bestPattern = generator.getBestPattern(skeleton); 2017 SimpleDateFormat format = new SimpleDateFormat(bestPattern, locale); 2018 format.setCalendar(cal); 2019 return format; 2020 } 2021 2022 2023 /** 2024 * <strong>[icu]</strong> Returns a {@link DateFormat} object that can be used to format dates and times in 2025 * the default locale. 2026 * The getInstanceForSkeleton methods are preferred over the getPatternInstance methods. 2027 * 2028 * @param skeleton The skeleton that selects the fields to be formatted. (Uses the 2029 * {@link DateTimePatternGenerator}.) This can be {@link DateFormat#ABBR_MONTH}, 2030 * {@link DateFormat#MONTH_WEEKDAY_DAY}, etc. 2031 */ 2032 public final static DateFormat getPatternInstance(String skeleton) { 2033 return getInstanceForSkeleton(skeleton); 2034 } 2035 2036 /** 2037 * <strong>[icu]</strong> Returns a {@link DateFormat} object that can be used to format dates and times in 2038 * the given locale. 2039 * The getInstanceForSkeleton methods are preferred over the getPatternInstance methods. 2040 * 2041 * @param skeleton The skeleton that selects the fields to be formatted. (Uses the 2042 * {@link DateTimePatternGenerator}.) This can be {@link DateFormat#ABBR_MONTH}, 2043 * {@link DateFormat#MONTH_WEEKDAY_DAY}, etc. 2044 * 2045 * @param locale The locale for which the date/time format is desired. 2046 */ 2047 public final static DateFormat getPatternInstance(String skeleton, Locale locale) { 2048 return getInstanceForSkeleton(skeleton, locale); 2049 } 2050 2051 /** 2052 * <strong>[icu]</strong> Returns a {@link DateFormat} object that can be used to format dates and times in 2053 * the given locale. 2054 * The getInstanceForSkeleton methods are preferred over the getPatternInstance methods. 2055 * 2056 * @param skeleton The skeleton that selects the fields to be formatted. (Uses the 2057 * {@link DateTimePatternGenerator}.) This can be {@link DateFormat#ABBR_MONTH}, 2058 * {@link DateFormat#MONTH_WEEKDAY_DAY}, etc. 2059 * 2060 * @param locale The locale for which the date/time format is desired. 2061 */ 2062 public final static DateFormat getPatternInstance(String skeleton, ULocale locale) { 2063 return getInstanceForSkeleton(skeleton, locale); 2064 } 2065 2066 /** 2067 * <strong>[icu]</strong> Creates a {@link DateFormat} object that can be used to format dates and 2068 * times in the calendar system specified by <code>cal</code>. 2069 * The getInstanceForSkeleton methods are preferred over the getPatternInstance methods. 2070 * 2071 * @param cal The calendar system for which a date/time format is desired. 2072 * 2073 * @param skeleton The skeleton that selects the fields to be formatted. (Uses the 2074 * {@link DateTimePatternGenerator}.) This can be 2075 * {@link DateFormat#ABBR_MONTH}, {@link DateFormat#MONTH_WEEKDAY_DAY}, 2076 * etc. 2077 * 2078 * @param locale The locale for which the date/time format is desired. 2079 */ 2080 public final static DateFormat getPatternInstance(Calendar cal, String skeleton, Locale locale) { 2081 return getInstanceForSkeleton(cal, skeleton, locale); 2082 } 2083 2084 /** 2085 * <strong>[icu]</strong> Creates a {@link DateFormat} object that can be used to format dates and 2086 * times in the calendar system specified by <code>cal</code>. 2087 * The getInstanceForSkeleton methods are preferred over the getPatternInstance methods. 2088 * 2089 * @param cal The calendar system for which a date/time format is desired. 2090 * 2091 * @param skeleton The skeleton that selects the fields to be formatted. (Uses the 2092 * {@link DateTimePatternGenerator}.) This can be 2093 * {@link DateFormat#ABBR_MONTH}, {@link DateFormat#MONTH_WEEKDAY_DAY}, 2094 * etc. 2095 * 2096 * @param locale The locale for which the date/time format is desired. 2097 */ 2098 public final static DateFormat getPatternInstance( 2099 Calendar cal, String skeleton, ULocale locale) { 2100 return getInstanceForSkeleton(cal, skeleton, locale); 2101 } 2102 2103 /** 2104 * The instances of this inner class are used as attribute keys and values 2105 * in AttributedCharacterIterator that 2106 * DateFormat.formatToCharacterIterator() method returns. 2107 * 2108 * <p>There is no public constructor to this class, the only instances are the 2109 * constants defined here. 2110 * <p> 2111 */ 2112 public static class Field extends Format.Field { 2113 2114 private static final long serialVersionUID = -3627456821000730829L; 2115 2116 // Max number of calendar fields 2117 private static final int CAL_FIELD_COUNT; 2118 2119 // Table for mapping calendar field number to DateFormat.Field 2120 private static final Field[] CAL_FIELDS; 2121 2122 // Map for resolving DateFormat.Field by name 2123 private static final Map<String, Field> FIELD_NAME_MAP; 2124 2125 static { 2126 GregorianCalendar cal = new GregorianCalendar(); 2127 CAL_FIELD_COUNT = cal.getFieldCount(); 2128 CAL_FIELDS = new Field[CAL_FIELD_COUNT]; 2129 FIELD_NAME_MAP = new HashMap<String, Field>(CAL_FIELD_COUNT); 2130 } 2131 2132 // Java fields ------------------- 2133 2134 /** 2135 * Constant identifying the time of day indicator(am/pm). 2136 */ 2137 public static final Field AM_PM = new Field("am pm", Calendar.AM_PM); 2138 2139 /** 2140 * Constant identifying the day of month field. 2141 */ 2142 public static final Field DAY_OF_MONTH = new Field("day of month", Calendar.DAY_OF_MONTH); 2143 2144 /** 2145 * Constant identifying the day of week field. 2146 */ 2147 public static final Field DAY_OF_WEEK = new Field("day of week", Calendar.DAY_OF_WEEK); 2148 2149 /** 2150 * Constant identifying the day of week in month field. 2151 */ 2152 public static final Field DAY_OF_WEEK_IN_MONTH = 2153 new Field("day of week in month", Calendar.DAY_OF_WEEK_IN_MONTH); 2154 2155 /** 2156 * Constant identifying the day of year field. 2157 */ 2158 public static final Field DAY_OF_YEAR = new Field("day of year", Calendar.DAY_OF_YEAR); 2159 2160 /** 2161 * Constant identifying the era field. 2162 */ 2163 public static final Field ERA = new Field("era", Calendar.ERA); 2164 2165 /** 2166 * Constant identifying the hour(0-23) of day field. 2167 */ 2168 public static final Field HOUR_OF_DAY0 = new Field("hour of day", Calendar.HOUR_OF_DAY); 2169 2170 /** 2171 * Constant identifying the hour(1-24) of day field. 2172 */ 2173 public static final Field HOUR_OF_DAY1 = new Field("hour of day 1", -1); 2174 2175 /** 2176 * Constant identifying the hour(0-11) field. 2177 */ 2178 public static final Field HOUR0 = new Field("hour", Calendar.HOUR); 2179 2180 /** 2181 * Constant identifying the hour(1-12) field. 2182 */ 2183 public static final Field HOUR1 = new Field("hour 1", -1); 2184 2185 /** 2186 * Constant identifying the millisecond field. 2187 */ 2188 public static final Field MILLISECOND = new Field("millisecond", Calendar.MILLISECOND); 2189 2190 /** 2191 * Constant identifying the minute field. 2192 */ 2193 public static final Field MINUTE = new Field("minute", Calendar.MINUTE); 2194 2195 /** 2196 * Constant identifying the month field. 2197 */ 2198 public static final Field MONTH = new Field("month", Calendar.MONTH); 2199 2200 /** 2201 * Constant identifying the second field. 2202 */ 2203 public static final Field SECOND = new Field("second", Calendar.SECOND); 2204 2205 /** 2206 * Constant identifying the time zone field. 2207 */ 2208 public static final Field TIME_ZONE = new Field("time zone", -1); 2209 2210 /** 2211 * Constant identifying the week of month field. 2212 */ 2213 public static final Field WEEK_OF_MONTH = 2214 new Field("week of month", Calendar.WEEK_OF_MONTH); 2215 2216 /** 2217 * Constant identifying the week of year field. 2218 */ 2219 public static final Field WEEK_OF_YEAR = new Field("week of year", Calendar.WEEK_OF_YEAR); 2220 2221 /** 2222 * Constant identifying the year field. 2223 */ 2224 public static final Field YEAR = new Field("year", Calendar.YEAR); 2225 2226 2227 // ICU only fields ------------------- 2228 2229 /** 2230 * Constant identifying the local day of week field. 2231 */ 2232 public static final Field DOW_LOCAL = new Field("local day of week", Calendar.DOW_LOCAL); 2233 2234 /** 2235 * Constant identifying the extended year field. 2236 */ 2237 public static final Field EXTENDED_YEAR = new Field("extended year", 2238 Calendar.EXTENDED_YEAR); 2239 2240 /** 2241 * Constant identifying the Julian day field. 2242 */ 2243 public static final Field JULIAN_DAY = new Field("Julian day", Calendar.JULIAN_DAY); 2244 2245 /** 2246 * Constant identifying the milliseconds in day field. 2247 */ 2248 public static final Field MILLISECONDS_IN_DAY = 2249 new Field("milliseconds in day", Calendar.MILLISECONDS_IN_DAY); 2250 2251 /** 2252 * Constant identifying the year used with week of year field. 2253 */ 2254 public static final Field YEAR_WOY = new Field("year for week of year", Calendar.YEAR_WOY); 2255 2256 /** 2257 * Constant identifying the quarter field. 2258 */ 2259 public static final Field QUARTER = new Field("quarter", -1); 2260 2261 /** 2262 * Constant identifying the related year field. 2263 * @deprecated This API is ICU internal only. 2264 * @hide draft / provisional / internal are hidden on Android 2265 */ 2266 @Deprecated 2267 public static final Field RELATED_YEAR = new Field("related year", -1); 2268 2269 /** 2270 * <strong>[icu]</strong> Constant identifying the am/pm/midnight/noon field. 2271 * @hide draft / provisional / internal are hidden on Android 2272 */ 2273 public static final Field AM_PM_MIDNIGHT_NOON = new Field("am/pm/midnight/noon", -1); 2274 2275 /** 2276 * <strong>[icu]</strong> Constant identifying the flexible day period field. 2277 * @hide draft / provisional / internal are hidden on Android 2278 */ 2279 public static final Field FLEXIBLE_DAY_PERIOD = new Field("flexible day period", -1); 2280 2281 /** 2282 * Constant identifying the time separator field. 2283 * @deprecated This API is ICU internal only. 2284 * @hide draft / provisional / internal are hidden on Android 2285 */ 2286 @Deprecated 2287 public static final Field TIME_SEPARATOR = new Field("time separator", -1); 2288 2289 // Stand alone types are variants for its base types. So we do not define Field for 2290 // them. 2291 /* 2292 public static final Field STANDALONE_DAY = 2293 new Field("stand alone day of week", Calendar.DAY_OF_WEEK); 2294 public static final Field STANDALONE_MONTH = new Field("stand alone month", Calendar.MONTH); 2295 public static final Field STANDALONE_QUARTER = new Field("stand alone quarter", -1); 2296 */ 2297 2298 // Corresponding calendar field 2299 private final int calendarField; 2300 2301 /** 2302 * Constructs a <code>DateFormat.Field</code> with the given name and 2303 * the <code>Calendar</code> field which this attribute represents. Use -1 for 2304 * <code>calendarField</code> if this field does not have a corresponding 2305 * <code>Calendar</code> field. 2306 * 2307 * @param name Name of the attribute 2308 * @param calendarField <code>Calendar</code> field constant 2309 */ 2310 protected Field(String name, int calendarField) { 2311 super(name); 2312 this.calendarField = calendarField; 2313 if (this.getClass() == DateFormat.Field.class) { 2314 FIELD_NAME_MAP.put(name, this); 2315 if (calendarField >= 0 && calendarField < CAL_FIELD_COUNT) { 2316 CAL_FIELDS[calendarField] = this; 2317 } 2318 } 2319 } 2320 2321 /** 2322 * Returns the <code>Field</code> constant that corresponds to the <code> 2323 * Calendar</code> field <code>calendarField</code>. If there is no 2324 * corresponding <code>Field</code> is available, null is returned. 2325 * 2326 * @param calendarField <code>Calendar</code> field constant 2327 * @return <code>Field</code> associated with the <code>calendarField</code>, 2328 * or null if no associated <code>Field</code> is available. 2329 * @throws IllegalArgumentException if <code>calendarField</code> is not 2330 * a valid <code>Calendar</code> field constant. 2331 */ 2332 public static DateFormat.Field ofCalendarField(int calendarField) { 2333 if (calendarField < 0 || calendarField >= CAL_FIELD_COUNT) { 2334 throw new IllegalArgumentException("Calendar field number is out of range"); 2335 } 2336 return CAL_FIELDS[calendarField]; 2337 } 2338 2339 /** 2340 * Returns the <code>Calendar</code> field associated with this attribute. 2341 * If there is no corresponding <code>Calendar</code> available, this will 2342 * return -1. 2343 * 2344 * @return <code>Calendar</code> constant for this attribute. 2345 */ 2346 public int getCalendarField() { 2347 return calendarField; 2348 } 2349 2350 /** 2351 * Resolves instances being deserialized to the predefined constants. 2352 * 2353 * @throws InvalidObjectException if the constant could not be resolved. 2354 */ 2355 @Override 2356 protected Object readResolve() throws InvalidObjectException { 2357 ///CLOVER:OFF 2358 if (this.getClass() != DateFormat.Field.class) { 2359 throw new InvalidObjectException( 2360 "A subclass of DateFormat.Field must implement readResolve."); 2361 } 2362 ///CLOVER:ON 2363 Object o = FIELD_NAME_MAP.get(this.getName()); 2364 ///CLOVER:OFF 2365 if (o == null) { 2366 throw new InvalidObjectException("Unknown attribute name."); 2367 } 2368 ///CLOVER:ON 2369 return o; 2370 } 2371 } 2372} 2373