DateFormat


1   /*
2   *   Copyright (C) 1996-2006, International Business Machines
3   *   Corporation and others.  All Rights Reserved.
4   */
5   
6   package com.ibm.icu.text;
7   
8   //import com.ibm.icu.impl.ICULocaleData;
9   import com.ibm.icu.util.Calendar;
10  import com.ibm.icu.util.TimeZone;
11  import com.ibm.icu.util.ULocale;
12  import com.ibm.icu.impl.ICUResourceBundle;
13  import com.ibm.icu.text.UFormat;
14  
15  import java.text.FieldPosition  ;
16  import java.text.ParseException  ;
17  import java.text.ParsePosition  ;
18  import java.util.Date  ;
19  import java.util.Locale  ;
20  import java.util.MissingResourceException  ;
21  
22  /**
23   * DateFormat is an abstract class for date/time formatting subclasses which
24   * formats and parses dates or time in a language-independent manner.
25   * The date/time formatting subclass, such as SimpleDateFormat, allows for
26   * formatting (i.e., date -> text), parsing (text -> date), and
27   * normalization.  The date is represented as a <code>Date</code> object or
28   * as the milliseconds since January 1, 1970, 00:00:00 GMT.
29   *
30   * <p>DateFormat provides many class methods for obtaining default date/time
31   * formatters based on the default or a given loacle and a number of formatting
32   * styles. The formatting styles include FULL, LONG, MEDIUM, and SHORT. More
33   * detail and examples of using these styles are provided in the method
34   * descriptions.
35   *
36   * <p>DateFormat helps you to format and parse dates for any locale.
37   * Your code can be completely independent of the locale conventions for
38   * months, days of the week, or even the calendar format: lunar vs. solar.
39   *
40   * <p>To format a date for the current Locale, use one of the
41   * static factory methods:
42   * <pre>
43   *  myString = DateFormat.getDateInstance().format(myDate);
44   * </pre>
45   * <p>If you are formatting multiple numbers, it is
46   * more efficient to get the format and use it multiple times so that
47   * the system doesn't have to fetch the information about the local
48   * language and country conventions multiple times.
49   * <pre>
50   *  DateFormat df = DateFormat.getDateInstance();
51   *  for (int i = 0; i < a.length; ++i) {
52   *    output.println(df.format(myDate[i]) + "; ");
53   *  }
54   * </pre>
55   * <p>To format a number for a different Locale, specify it in the
56   * call to getDateInstance().
57   * <pre>
58   *  DateFormat df = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE);
59   * </pre>
60   * <p>You can use a DateFormat to parse also.
61   * <pre>
62   *  myDate = df.parse(myString);
63   * </pre>
64   * <p>Use getDateInstance to get the normal date format for that country.
65   * There are other static factory methods available.
66   * Use getTimeInstance to get the time format for that country.
67   * Use getDateTimeInstance to get a date and time format. You can pass in 
68   * different options to these factory methods to control the length of the
69   * result; from SHORT to MEDIUM to LONG to FULL. The exact result depends
70   * on the locale, but generally:
71   * <ul><li>SHORT is completely numeric, such as 12.13.52 or 3:30pm
72   * <li>MEDIUM is longer, such as Jan 12, 1952
73   * <li>LONG is longer, such as January 12, 1952 or 3:30:32pm
74   * <li>FULL is pretty completely specified, such as
75   * Tuesday, April 12, 1952 AD or 3:30:42pm PST.
76   * </ul>
77   *
78   * <p>You can also set the time zone on the format if you wish.
79   * If you want even more control over the format or parsing,
80   * (or want to give your users more control),
81   * you can try casting the DateFormat you get from the factory methods
82   * to a SimpleDateFormat. This will work for the majority
83   * of countries; just remember to put it in a try block in case you
84   * encounter an unusual one.
85   *
86   * <p>You can also use forms of the parse and format methods with
87   * ParsePosition and FieldPosition to
88   * allow you to
89   * <ul><li>progressively parse through pieces of a string.
90   * <li>align any particular field, or find out where it is for selection
91   * on the screen.
92   * </ul>
93   *
94   * <h4>Synchronization</h4>
95   *
96   * Date formats are not synchronized. It is recommended to create separate 
97   * format instances for each thread. If multiple threads access a format 
98   * concurrently, it must be synchronized externally. 
99   *
100  * @see          UFormat
101  * @see          NumberFormat
102  * @see          SimpleDateFormat
103  * @see          com.ibm.icu.util.Calendar
104  * @see          com.ibm.icu.util.GregorianCalendar
105  * @see          com.ibm.icu.util.TimeZone
106  * @author       Mark Davis, Chen-Lieh Huang, Alan Liu
107  * @stable ICU 2.0
108  */
109 public abstract class DateFormat extends UFormat {
110 
111     /**
112      * The calendar that <code>DateFormat</code> uses to produce the time field
113      * values needed to implement date and time formatting.  Subclasses should
114      * initialize this to a calendar appropriate for the locale associated with
115      * this <code>DateFormat</code>.
116      * @serial
117      * @stable ICU 2.0
118      */
119     protected Calendar calendar;
120 
121     /**
122      * The number formatter that <code>DateFormat</code> uses to format numbers
123      * in dates and times.  Subclasses should initialize this to a number format
124      * appropriate for the locale associated with this <code>DateFormat</code>.
125      * @serial
126      * @stable ICU 2.0
127      */
128     protected NumberFormat numberFormat;
129 
130     /**
131      * FieldPosition selector for 'G' field alignment,
132      * corresponding to the {@link Calendar#ERA} field.
133      * @stable ICU 2.0
134      */
135     public final static int ERA_FIELD = 0;
136 
137     /**
138      * FieldPosition selector for 'y' field alignment,
139      * corresponding to the {@link Calendar#YEAR} field.
140      * @stable ICU 2.0
141      */
142     public final static int YEAR_FIELD = 1;
143 
144     /**
145      * FieldPosition selector for 'M' field alignment,
146      * corresponding to the {@link Calendar#MONTH} field.
147      * @stable ICU 2.0
148      */
149     public final static int MONTH_FIELD = 2;
150 
151     /**
152      * FieldPosition selector for 'd' field alignment,
153      * corresponding to the {@link Calendar#DATE} field.
154      * @stable ICU 2.0
155      */
156     public final static int DATE_FIELD = 3;
157 
158     /**
159      * FieldPosition selector for 'k' field alignment,
160      * corresponding to the {@link Calendar#HOUR_OF_DAY} field.
161      * HOUR_OF_DAY1_FIELD is used for the one-based 24-hour clock.
162      * For example, 23:59 + 01:00 results in 24:59.
163      * @stable ICU 2.0
164      */
165     public final static int HOUR_OF_DAY1_FIELD = 4;
166 
167     /**
168      * FieldPosition selector for 'H' field alignment,
169      * corresponding to the {@link Calendar#HOUR_OF_DAY} field.
170      * HOUR_OF_DAY0_FIELD is used for the zero-based 24-hour clock.
171      * For example, 23:59 + 01:00 results in 00:59.
172      * @stable ICU 2.0
173      */
174     public final static int HOUR_OF_DAY0_FIELD = 5;
175 
176     /**
177      * FieldPosition selector for 'm' field alignment,
178      * corresponding to the {@link Calendar#MINUTE} field.
179      * @stable ICU 2.0
180      */
181     public final static int MINUTE_FIELD = 6;
182 
183     /**
184      * FieldPosition selector for 's' field alignment,
185      * corresponding to the {@link Calendar#SECOND} field.
186      * @stable ICU 2.0
187      */
188     public final static int SECOND_FIELD = 7;
189 
190     /**
191      * FieldPosition selector for 'S' field alignment,
192      * corresponding to the {@link Calendar#MILLISECOND} field.
193      * @stable ICU 3.0
194      */
195     public final static int FRACTIONAL_SECOND_FIELD = 8;
196 
197     /**
198      * Alias for FRACTIONAL_SECOND_FIELD.
199      * @deprecated ICU 3.0 use FRACTIONAL_SECOND_FIELD.
200      */
201     public final static int MILLISECOND_FIELD = FRACTIONAL_SECOND_FIELD;
202 
203     /**
204      * FieldPosition selector for 'E' field alignment,
205      * corresponding to the {@link Calendar#DAY_OF_WEEK} field.
206      * @stable ICU 2.0
207      */
208     public final static int DAY_OF_WEEK_FIELD = 9;
209 
210     /**
211      * FieldPosition selector for 'D' field alignment,
212      * corresponding to the {@link Calendar#DAY_OF_YEAR} field.
213      * @stable ICU 2.0
214      */
215     public final static int DAY_OF_YEAR_FIELD = 10;
216 
217     /**
218      * FieldPosition selector for 'F' field alignment,
219      * corresponding to the {@link Calendar#DAY_OF_WEEK_IN_MONTH} field.
220      * @stable ICU 2.0
221      */
222     public final static int DAY_OF_WEEK_IN_MONTH_FIELD = 11;
223 
224     /**
225      * FieldPosition selector for 'w' field alignment,
226      * corresponding to the {@link Calendar#WEEK_OF_YEAR} field.
227      * @stable ICU 2.0
228      */
229     public final static int WEEK_OF_YEAR_FIELD = 12;
230 
231     /**
232      * FieldPosition selector for 'W' field alignment,
233      * corresponding to the {@link Calendar#WEEK_OF_MONTH} field.
234      * @stable ICU 2.0
235      */
236     public final static int WEEK_OF_MONTH_FIELD = 13;
237 
238     /**
239      * FieldPosition selector for 'a' field alignment,
240      * corresponding to the {@link Calendar#AM_PM} field.
241      * @stable ICU 2.0
242      */
243     public final static int AM_PM_FIELD = 14;
244 
245     /**
246      * FieldPosition selector for 'h' field alignment,
247      * corresponding to the {@link Calendar#HOUR} field.
248      * HOUR1_FIELD is used for the one-based 12-hour clock.
249      * For example, 11:30 PM + 1 hour results in 12:30 AM.
250      * @stable ICU 2.0
251      */
252     public final static int HOUR1_FIELD = 15;
253 
254     /**
255      * FieldPosition selector for 'K' field alignment,
256      * corresponding to the {@link Calendar#HOUR} field.
257      * HOUR0_FIELD is used for the zero-based 12-hour clock.
258      * For example, 11:30 PM + 1 hour results in 00:30 AM.
259      * @stable ICU 2.0
260      */
261     public final static int HOUR0_FIELD = 16;
262 
263     /**
264      * FieldPosition selector for 'z' field alignment,
265      * corresponding to the {@link Calendar#ZONE_OFFSET} and
266      * {@link Calendar#DST_OFFSET} fields.
267      * @stable ICU 2.0
268      */
269     public final static int TIMEZONE_FIELD = 17;
270 
271     /**
272      * FieldPosition selector for 'Y' field alignment,
273      * corresponding to the {@link Calendar#YEAR_WOY} field.
274      * @stable ICU 3.0
275      */
276     public final static int YEAR_WOY_FIELD = 18;
277 
278     /**
279      * FieldPosition selector for 'e' field alignment,
280      * corresponding to the {@link Calendar#DOW_LOCAL} field.
281      * @stable ICU 3.0
282      */
283     public final static int DOW_LOCAL_FIELD = 19;
284 
285     /**
286      * FieldPosition selector for 'u' field alignment,
287      * corresponding to the {@link Calendar#EXTENDED_YEAR} field.
288      * @stable ICU 3.0
289      */
290     public final static int EXTENDED_YEAR_FIELD = 20;
291 
292     /**
293      * FieldPosition selector for 'g' field alignment,
294      * corresponding to the {@link Calendar#JULIAN_DAY} field.
295      * @stable ICU 3.0
296      */
297     public final static int JULIAN_DAY_FIELD = 21;
298 
299     /**
300      * FieldPosition selector for 'A' field alignment,
301      * corresponding to the {@link Calendar#MILLISECONDS_IN_DAY} field.
302      * @stable ICU 3.0
303      */
304     public final static int MILLISECONDS_IN_DAY_FIELD = 22;
305 
306     /**
307      * FieldPosition selector for 'Z' field alignment,
308      * corresponding to the {@link Calendar#ZONE_OFFSET} and
309      * {@link Calendar#DST_OFFSET} fields.
310      * @stable ICU 3.0
311      */
312     public final static int TIMEZONE_RFC_FIELD = 23;
313 
314     /**
315      * FieldPosition selector for 'v' field alignment,
316      * corresponding to the {@link Calendar#ZONE_OFFSET} and
317      * {@link Calendar#DST_OFFSET} fields.  This displays the generic zone
318      * name, if available.
319      * @draft ICU 3.4
320      * @provisional This API might change or be removed in a future release.
321      */
322     public final static int TIMEZONE_GENERIC_FIELD = 24;
323  
324 
325     
326     /**
327      * FieldPosition selector for 'c' field alignment,
328      * corresponding to the {@link Calendar#DAY_OF_WEEK} field. 
329      * This displays the stand alone day name, if available.
330      * @draft ICU 3.4
331      * @provisional This API might change or be removed in a future release.
332      */
333     public final static int STANDALONE_DAY_FIELD = 25;
334     
335     /**
336      * FieldPosition selector for 'L' field alignment,
337      * corresponding to the {@link Calendar#MONTH} field.  
338      * This displays the stand alone month name, if available.
339      * @draft ICU 3.4
340      * @provisional This API might change or be removed in a future release.
341      */
342     public final static int STANDALONE_MONTH_FIELD = 26;
343     
344     /**
345      * FieldPosition selector for 'Q' field alignment,
346      * corresponding to the {@link Calendar#MONTH} field.  
347      * This displays the quarter.
348      * @draft ICU 3.6
349      * @provisional This API might change or be removed in a future release.
350      */
351     public final static int QUARTER_FIELD = 27;
352     
353     /**
354      * FieldPosition selector for 'q' field alignment,
355      * corresponding to the {@link Calendar#MONTH} field.  
356      * This displays the stand alone quarter, if available.
357      * @draft ICU 3.6
358      * @provisional This API might change or be removed in a future release.
359      */
360     public final static int STANDALONE_QUARTER_FIELD = 28;
361     
362     /**
363      * Number of FieldPosition selectors for DateFormat.
364      * Valid selectors range from 0 to FIELD_COUNT-1.
365      * @stable ICU 3.0
366      */
367     public final static int FIELD_COUNT = 29; // must == DateFormatSymbols.patternChars.length()
368 
369     // Proclaim serial compatibility with 1.1 FCS
370     private static final long serialVersionUID = 7218322306649953788L;
371 
372     /**
373      * Overrides Format.
374      * Formats a time object into a time string. Examples of time objects
375      * are a time value expressed in milliseconds and a Date object.
376      * @param obj must be a Number or a Date or a Calendar.
377      * @param toAppendTo the string buffer for the returning time string.
378      * @return the formatted time string.
379      * @param fieldPosition keeps track of the position of the field
380      * within the returned string.
381      * On input: an alignment field,
382      * if desired. On output: the offsets of the alignment field. For
383      * example, given a time text "1996.07.10 AD at 15:08:56 PDT",
384      * if the given fieldPosition is DateFormat.YEAR_FIELD, the
385      * begin index and end index of fieldPosition will be set to
386      * 0 and 4, respectively.
387      * Notice that if the same time field appears
388      * more than once in a pattern, the fieldPosition will be set for the first
389      * occurence of that time field. For instance, formatting a Date to
390      * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern
391      * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD,
392      * the begin index and end index of fieldPosition will be set to
393      * 5 and 8, respectively, for the first occurence of the timezone
394      * pattern character 'z'.
395      * @see java.text.Format
396      * @stable ICU 2.0
397      */
398     public final StringBuffer   format(Object   obj, StringBuffer   toAppendTo,
399                                      FieldPosition   fieldPosition)
400     {
401         if (obj instanceof Calendar)
402             return format( (Calendar)obj, toAppendTo, fieldPosition );
403         else if (obj instanceof Date  )
404             return format( (Date  )obj, toAppendTo, fieldPosition );
405         else if (obj instanceof Number  )
406             return format( new Date  (((Number  )obj).longValue()),
407                           toAppendTo, fieldPosition );
408         else 
409             throw new IllegalArgumentException  ("Cannot format given Object as a Date");
410     }
411 
412     /**
413      * Formats a date into a date/time string.
414      * @param cal a Calendar set to the date and time to be formatted
415      * into a date/time string.
416      * @param toAppendTo the string buffer for the returning date/time string.
417      * @param fieldPosition keeps track of the position of the field
418      * within the returned string.
419      * On input: an alignment field,
420      * if desired. On output: the offsets of the alignment field. For
421      * example, given a time text "1996.07.10 AD at 15:08:56 PDT",
422      * if the given fieldPosition is DateFormat.YEAR_FIELD, the
423      * begin index and end index of fieldPosition will be set to
424      * 0 and 4, respectively.
425      * Notice that if the same time field appears
426      * more than once in a pattern, the fieldPosition will be set for the first
427      * occurence of that time field. For instance, formatting a Date to
428      * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern
429      * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD,
430      * the begin index and end index of fieldPosition will be set to
431      * 5 and 8, respectively, for the first occurence of the timezone
432      * pattern character 'z'.
433      * @return the formatted date/time string.
434      * @stable ICU 2.0
435      */
436     public abstract StringBuffer   format(Calendar cal, StringBuffer   toAppendTo,
437                                         FieldPosition   fieldPosition);
438 
439     /**
440      * Formats a Date into a date/time string.
441      * @param date a Date to be formatted into a date/time string.
442      * @param toAppendTo the string buffer for the returning date/time string.
443      * @param fieldPosition keeps track of the position of the field
444      * within the returned string.
445      * On input: an alignment field,
446      * if desired. On output: the offsets of the alignment field. For
447      * example, given a time text "1996.07.10 AD at 15:08:56 PDT",
448      * if the given fieldPosition is DateFormat.YEAR_FIELD, the
449      * begin index and end index of fieldPosition will be set to
450      * 0 and 4, respectively.
451      * Notice that if the same time field appears
452      * more than once in a pattern, the fieldPosition will be set for the first
453      * occurence of that time field. For instance, formatting a Date to
454      * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern
455      * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD,
456      * the begin index and end index of fieldPosition will be set to
457      * 5 and 8, respectively, for the first occurence of the timezone
458      * pattern character 'z'.
459      * @return the formatted date/time string.
460      * @stable ICU 2.0
461      */
462     public StringBuffer   format(Date   date, StringBuffer   toAppendTo,
463                                      FieldPosition   fieldPosition) {
464         // Use our Calendar object
465         calendar.setTime(date);
466         return format(calendar, toAppendTo, fieldPosition);
467     }
468 
469     /**
470      * Formats a Date into a date/time string.
471      * @param date the time value to be formatted into a time string.
472      * @return the formatted time string.
473      * @stable ICU 2.0
474      */
475     public final String   format(Date   date)
476     {
477         return format(date, new StringBuffer  (64),new FieldPosition  (0)).toString();
478     }
479 
480     /**
481      * Parse a date/time string.
482      *
483      * @param text  The date/time string to be parsed
484      *
485      * @return      A Date, or null if the input could not be parsed
486      *
487      * @exception  ParseException  If the given string cannot be parsed as a date.
488      *
489      * @see #parse(String, ParsePosition)
490      * @stable ICU 2.0
491      */
492     public Date   parse(String   text) throws ParseException  
493     {
494         ParsePosition   pos = new ParsePosition  (0);
495         Date   result = parse(text, pos);
496         if (pos.getIndex() == 0) // ICU4J
497             throw new ParseException  ("Unparseable date: \"" + text + "\"" ,
498                                      pos.getErrorIndex()); // ICU4J
499         return result;
500     }
501 
502     /**
503      * Parse a date/time string according to the given parse position.
504      * For example, a time text "07/10/96 4:5 PM, PDT" will be parsed
505      * into a Calendar that is equivalent to Date(837039928046).  The
506      * caller should clear the calendar before calling this method,
507      * unless existing field information is to be kept.
508      *
509      * <p> By default, parsing is lenient: If the input is not in the form used
510      * by this object's format method but can still be parsed as a date, then
511      * the parse succeeds.  Clients may insist on strict adherence to the
512      * format by calling setLenient(false).
513      *
514      * @see #setLenient(boolean)
515      *
516      * @param text  The date/time string to be parsed
517      *
518      * @param cal   The calendar into which parsed data will be stored.
519      *              In general, this should be cleared before calling this
520      *              method.  If this parse fails, the calendar may still
521      *              have been modified.
522      *
523      * @param pos   On input, the position at which to start parsing; on
524      *              output, the position at which parsing terminated, or the
525      *              start position if the parse failed.
526      * @stable ICU 2.0
527      */
528     public abstract void parse(String   text, Calendar cal, ParsePosition   pos);
529 
530     /**
531      * Parse a date/time string according to the given parse position.  For
532      * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date
533      * that is equivalent to Date(837039928046).
534      *
535      * <p> By default, parsing is lenient: If the input is not in the form used
536      * by this object's format method but can still be parsed as a date, then
537      * the parse succeeds.  Clients may insist on strict adherence to the
538      * format by calling setLenient(false).
539      *
540      * @see #setLenient(boolean)
541      *
542      * @param text  The date/time string to be parsed
543      *
544      * @param pos   On input, the position at which to start parsing; on
545      *              output, the position at which parsing terminated, or the
546      *              start position if the parse failed.
547      *
548      * @return      A Date, or null if the input could not be parsed
549      * @stable ICU 2.0
550      */
551     public Date   parse(String   text, ParsePosition   pos) {
552         int start = pos.getIndex();
553         calendar.clear();
554         parse(text, calendar, pos);
555         if (pos.getIndex() != start) {
556             try {
557                 return calendar.getTime();
558             } catch (IllegalArgumentException   e) {
559                 // This occurs if the calendar is non-lenient and there is
560                 // an out-of-range field.  We don't know which field was
561                 // illegal so we set the error index to the start.
562                 pos.setIndex(start);
563                 pos.setErrorIndex(start);
564             }
565         }
566         return null;
567     }
568 
569     /**
570      * Parse a date/time string into an Object.  This convenience method simply
571      * calls parse(String, ParsePosition).
572      *
573      * @see #parse(String, ParsePosition)
574      * @stable ICU 2.0
575      */
576     public Object   parseObject (String   source, ParsePosition   pos)
577     {
578         return parse(source, pos);
579     }
580 
581     /**
582      * Constant for full style pattern.
583      * @stable ICU 2.0
584      */
585     public static final int FULL = 0;
586 
587     /**
588      * Constant for long style pattern.
589      * @stable ICU 2.0
590      */
591     public static final int LONG = 1;
592 
593     /**
594      * Constant for medium style pattern.
595      * @stable ICU 2.0
596      */
597     public static final int MEDIUM = 2;
598 
599     /**
600      * Constant for short style pattern.
601      * @stable ICU 2.0
602      */
603     public static final int SHORT = 3;
604 
605     /**
606      * Constant for default style pattern.  Its value is MEDIUM.
607      * @stable ICU 2.0
608      */
609     public static final int DEFAULT = MEDIUM;
610 
611     /**
612      * Gets the time formatter with the default formatting style
613      * for the default locale.
614      * @return a time formatter.
615      * @stable ICU 2.0
616      */
617     public final static DateFormat getTimeInstance()
618     {
619         return get(-1, DEFAULT, ULocale.getDefault());
620     }
621 
622     /**
623      * Gets the time formatter with the given formatting style
624      * for the default locale.
625      * @param style the given formatting style. For example,
626      * SHORT for "h:mm a" in the US locale.
627      * @return a time formatter.
628      * @stable ICU 2.0
629      */
630     public final static DateFormat getTimeInstance(int style)
631     {
632         return get(-1, style, ULocale.getDefault());
633     }
634 
635     /**
636      * Gets the time formatter with the given formatting style
637      * for the given locale.
638      * @param style the given formatting style. For example,
639      * SHORT for "h:mm a" in the US locale.
640      * @param aLocale the given locale.
641      * @return a time formatter.
642      * @stable ICU 2.0
643      */
644     public final static DateFormat getTimeInstance(int style,
645                                                  Locale aLocale)
646     {
647         return get(-1, style, ULocale.forLocale(aLocale));
648     }
649 
650     /**
651      * Gets the time formatter with the given formatting style
652      * for the given locale.
653      * @param style the given formatting style. For example,
654      * SHORT for "h:mm a" in the US locale.
655      * @param locale the given ulocale.
656      * @return a time formatter.
657      * @draft ICU 3.2
658      * @provisional This API might change or be removed in a future release.
659      */
660     public final static DateFormat getTimeInstance(int style,
661                                                  ULocale locale)
662     {
663         return get(-1, style, locale);
664     }
665 
666     /**
667      * Gets the date formatter with the default formatting style
668      * for the default locale.
669      * @return a date formatter.
670      * @stable ICU 2.0
671      */
672     public final static DateFormat getDateInstance()
673     {
674         return get(DEFAULT, -1, ULocale.getDefault());
675     }
676 
677     /**
678      * Gets the date formatter with the given formatting style
679      * for the default locale.
680      * @param style the given formatting style. For example,
681      * SHORT for "M/d/yy" in the US locale.
682      * @return a date formatter.
683      * @stable ICU 2.0
684      */
685     public final static DateFormat getDateInstance(int style)
686     {
687         return get(style, -1, ULocale.getDefault());
688     }
689 
690     /**
691      * Gets the date formatter with the given formatting style
692      * for the given locale.
693      * @param style the given formatting style. For example,
694      * SHORT for "M/d/yy" in the US locale.
695      * @param aLocale the given locale.
696      * @return a date formatter.
697      * @stable ICU 2.0
698      */
699     public final static DateFormat getDateInstance(int style,
700                                                  Locale aLocale)
701     {
702         return get(style, -1, ULocale.forLocale(aLocale));
703     }
704 
705     /**
706      * Gets the date formatter with the given formatting style
707      * for the given locale.
708      * @param style the given formatting style. For example,
709      * SHORT for "M/d/yy" in the US locale.
710      * @param locale the given ulocale.
711      * @return a date formatter.
712      * @draft ICU 3.2
713      * @provisional This API might change or be removed in a future release.
714      */
715     public final static DateFormat getDateInstance(int style,
716                                                  ULocale locale)
717     {
718         return get(style, -1, locale);
719     }
720 
721     /**
722      * Gets the date/time formatter with the default formatting style
723      * for the default locale.
724      * @return a date/time formatter.
725      * @stable ICU 2.0
726      */
727     public final static DateFormat getDateTimeInstance()
728     {
729         return get(DEFAULT, DEFAULT, ULocale.getDefault());
730     }
731 
732     /**
733      * Gets the date/time formatter with the given date and time
734      * formatting styles for the default locale.
735      * @param dateStyle the given date formatting style. For example,
736      * SHORT for "M/d/yy" in the US locale.
737      * @param timeStyle the given time formatting style. For example,
738      * SHORT for "h:mm a" in the US locale.
739      * @return a date/time formatter.
740      * @stable ICU 2.0
741      */
742     public final static DateFormat getDateTimeInstance(int dateStyle,
743                                                        int timeStyle)
744     {
745         return get(dateStyle, timeStyle, ULocale.getDefault());
746     }
747 
748     /**
749      * Gets the date/time formatter with the given formatting styles
750      * for the given locale.
751      * @param dateStyle the given date formatting style.
752      * @param timeStyle the given time formatting style.
753      * @param aLocale the given locale.
754      * @return a date/time formatter.
755      * @stable ICU 2.0
756      */
757     public final static DateFormat
758         getDateTimeInstance(int dateStyle, int timeStyle, Locale aLocale)
759     {
760         return get(dateStyle, timeStyle, ULocale.forLocale(aLocale));
761     }
762 
763     /**
764      * Gets the date/time formatter with the given formatting styles
765      * for the given locale.
766      * @param dateStyle the given date formatting style.
767      * @param timeStyle the given time formatting style.
768      * @param locale the given ulocale.
769      * @return a date/time formatter.
770      * @draft ICU 3.2
771      * @provisional This API might change or be removed in a future release.
772      */
773     public final static DateFormat
774         getDateTimeInstance(int dateStyle, int timeStyle, ULocale locale)
775     {
776         return get(dateStyle, timeStyle, locale);
777     }
778 
779     /**
780      * Get a default date/time formatter that uses the SHORT style for both the
781      * date and the time.
782      * @stable ICU 2.0
783      */
784     public final static DateFormat getInstance() {
785         return getDateTimeInstance(SHORT, SHORT);
786     }
787 
788     /**
789      * Gets the set of locales for which DateFormats are installed.
790      * @return the set of locales for which DateFormats are installed.
791      * @stable ICU 2.0
792      */
793     public static Locale[] getAvailableLocales()
794     {
795         return ICUResourceBundle.getAvailableLocales(ICUResourceBundle.ICU_BASE_NAME);
796     }
797 
798     /**
799      * Gets the set of locales for which DateFormats are installed.
800      * @return the set of locales for which DateFormats are installed.
801      * @draft ICU 3.2
802      * @provisional This API might change or be removed in a future release.
803      */
804     public static ULocale[] getAvailableULocales()
805     {
806         return ICUResourceBundle.getAvailableULocales(ICUResourceBundle.ICU_BASE_NAME);
807     }
808 
809     /**
810      * Set the calendar to be used by this date format.  Initially, the default
811      * calendar for the specified or default locale is used.
812      * @param newCalendar the new Calendar to be used by the date format
813      * @stable ICU 2.0
814      */
815     public void setCalendar(Calendar newCalendar)
816     {
817         this.calendar = newCalendar;
818     }
819 
820     /**
821      * Gets the calendar associated with this date/time formatter.
822      * @return the calendar associated with this date/time formatter.
823      * @stable ICU 2.0
824      */
825     public Calendar getCalendar()
826     {
827         return calendar;
828     }
829 
830     /**
831      * Allows you to set the number formatter.
832      * @param newNumberFormat the given new NumberFormat.
833      * @stable ICU 2.0
834      */
835     public void setNumberFormat(NumberFormat newNumberFormat)
836     {
837         this.numberFormat = newNumberFormat;
838         /*In order to parse String like "11.10.2001" to DateTime correctly 
839           in Locale("fr","CH") [Richard/GCL]
840         */
841         this.numberFormat.setParseIntegerOnly(true);
842     }
843 
844     /**
845      * Gets the number formatter which this date/time formatter uses to
846      * format and parse a time.
847      * @return the number formatter which this date/time formatter uses.
848      * @stable ICU 2.0
849      */
850     public NumberFormat getNumberFormat()
851     {
852         return numberFormat;
853     }
854 
855     /**
856      * Sets the time zone for the calendar of this DateFormat object.
857      * @param zone the given new time zone.
858      * @stable ICU 2.0
859      */
860     public void setTimeZone(TimeZone zone)
861     {
862         calendar.setTimeZone(zone);
863     }
864 
865     /**
866      * Gets the time zone.
867      * @return the time zone associated with the calendar of DateFormat.
868      * @stable ICU 2.0
869      */
870     public TimeZone getTimeZone()
871     {
872         return calendar.getTimeZone();
873     }
874 
875     /**
876      * Specify whether or not date/time parsing is to be lenient.  With
877      * lenient parsing, the parser may use heuristics to interpret inputs that
878      * do not precisely match this object's format.  With strict parsing,
879      * inputs must match this object's format.
880      * @param lenient when true, parsing is lenient
881      * @see com.ibm.icu.util.Calendar#setLenient
882      * @stable ICU 2.0
883      */
884     public void setLenient(boolean lenient)
885     {
886         calendar.setLenient(lenient);
887     }
888 
889     /**
890      * Tell whether date/time parsing is to be lenient.
891      * @stable ICU 2.0
892      */
893     public boolean isLenient()
894     {
895         return calendar.isLenient();
896     }
897 
898     /**
899      * Overrides hashCode
900      * @stable ICU 2.0
901      */
902     ///CLOVER:OFF
903     // turn off code coverage since all subclasses override this
904     public int hashCode() {
905         return numberFormat.hashCode();
906         // just enough fields for a reasonable distribution
907     }
908     ///CLOVER:ON
909 
910     /**
911      * Overrides equals
912      * @stable ICU 2.0
913      */
914     public boolean equals(Object   obj) {
915         if (this == obj) return true;
916         if (obj == null || getClass() != obj.getClass()) return false;
917         DateFormat other = (DateFormat) obj;
918         return (calendar.isEquivalentTo(other.calendar) &&
919                 numberFormat.equals(other.numberFormat));
920     }
921 
922     /**
923      * Overrides Cloneable
924      * @stable ICU 2.0
925      */
926     public Object   clone()
927     {
928         DateFormat other = (DateFormat) super.clone();
929         other.calendar = (Calendar) calendar.clone();
930         other.numberFormat = (NumberFormat) numberFormat.clone();
931         return other;
932     }
933 
934     /**
935      * Creates a DateFormat with the given time and/or date style in the given
936      * locale.
937      * @param dateStyle a value from 0 to 3 indicating the time format,
938      * or -1 to indicate no date
939      * @param timeStyle a value from 0 to 3 indicating the time format,
940      * or -1 to indicate no time
941      * @param loc the locale for the format
942      */
943     private static DateFormat get(int dateStyle, int timeStyle, ULocale loc) {
944         if (timeStyle < -1 || timeStyle > 3) {
945             throw new IllegalArgumentException  ("Illegal time style " + timeStyle);
946         }
947         if (dateStyle < -1 || dateStyle > 3) {
948             throw new IllegalArgumentException  ("Illegal date style " + dateStyle);
949         }
950         try {
951             Calendar cal = Calendar.getInstance(loc);
952             DateFormat result = cal.getDateTimeFormat(dateStyle, timeStyle, loc);
953         result.setLocale(cal.getLocale(ULocale.VALID_LOCALE),
954                  cal.getLocale(ULocale.ACTUAL_LOCALE));
955         return result;
956         } catch (MissingResourceException   e) {
957             ///CLOVER:OFF
958             // coverage requires separate run with no data, so skip
959             return new SimpleDateFormat("M/d/yy h:mm a");
960             ///CLOVER:ON
961         }
962     }
963 
964     /**
965      * Create a new date format.
966      * @stable ICU 2.0
967      */
968     protected DateFormat() {}
969 
970     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
971 
972     //-------------------------------------------------------------------------
973     // Public static interface for creating custon DateFormats for different
974     // types of Calendars.
975     //-------------------------------------------------------------------------
976     
977     /**
978      * Create a {@link DateFormat} object that can be used to format dates in
979      * the calendar system specified by <code>cal</code>.
980      * <p>
981      * @param cal   The calendar system for which a date format is desired.
982      *
983      * @param dateStyle The type of date format desired.  This can be
984      *              {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM},
985      *              etc.
986      *
987      * @param locale The locale for which the date format is desired.
988      * @stable ICU 2.0
989      */
990     static final public DateFormat getDateInstance(Calendar cal, int dateStyle, Locale locale)
991     {
992         return getDateTimeInstance(cal, dateStyle, -1, ULocale.forLocale(locale));
993     }
994     
995     /**
996      * Create a {@link DateFormat} object that can be used to format dates in
997      * the calendar system specified by <code>cal</code>.
998      * <p>
999      * @param cal   The calendar system for which a date format is desired.
1000     *
1001     * @param dateStyle The type of date format desired.  This can be
1002     *              {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM},
1003     *              etc.
1004     *
1005     * @param locale The locale for which the date format is desired.
1006     * @draft ICU 3.2
1007     * @provisional This API might change or be removed in a future release.
1008     */
1009    static final public DateFormat getDateInstance(Calendar cal, int dateStyle, ULocale locale)
1010    {
1011        return getDateTimeInstance(cal, dateStyle, -1, locale);
1012    }
1013    
1014    /**
1015     * Create a {@link DateFormat} object that can be used to format times in
1016     * the calendar system specified by <code>cal</code>.
1017     * <p>
1018     * <b>Note:</b> When this functionality is moved into the core JDK, this method
1019     * will probably be replaced by a new overload of {@link DateFormat#getInstance}.
1020     * <p>
1021     * @param cal   The calendar system for which a time format is desired.
1022     *
1023     * @param timeStyle The type of time format desired.  This can be
1024     *              {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM},
1025     *              etc.
1026     *
1027     * @param locale The locale for which the time format is desired.
1028     *
1029     * @see DateFormat#getTimeInstance
1030     * @stable ICU 2.0
1031     */
1032    static final public DateFormat getTimeInstance(Calendar cal, int timeStyle, Locale locale)
1033    {
1034        return getDateTimeInstance(cal, -1, timeStyle, ULocale.forLocale(locale));
1035    }
1036    
1037    /**
1038     * Create a {@link DateFormat} object that can be used to format times in
1039     * the calendar system specified by <code>cal</code>.
1040     * <p>
1041     * <b>Note:</b> When this functionality is moved into the core JDK, this method
1042     * will probably be replaced by a new overload of {@link DateFormat#getInstance}.
1043     * <p>
1044     * @param cal   The calendar system for which a time format is desired.
1045     *
1046     * @param timeStyle The type of time format desired.  This can be
1047     *              {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM},
1048     *              etc.
1049     *
1050     * @param locale The locale for which the time format is desired.
1051     *
1052     * @see DateFormat#getTimeInstance
1053     * @draft ICU 3.2
1054     * @provisional This API might change or be removed in a future release.
1055     */
1056    static final public DateFormat getTimeInstance(Calendar cal, int timeStyle, ULocale locale)
1057    {
1058        return getDateTimeInstance(cal, -1, timeStyle, locale);
1059    }
1060    
1061    /**
1062     * Create a {@link DateFormat} object that can be used to format dates and times in
1063     * the calendar system specified by <code>cal</code>.
1064     * <p>
1065     * <b>Note:</b> When this functionality is moved into the core JDK, this method
1066     * will probably be replaced by a new overload of {@link DateFormat#getInstance}.
1067     * <p>
1068     * @param cal   The calendar system for which a date/time format is desired.
1069     *
1070     * @param dateStyle The type of date format desired.  This can be
1071     *              {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM},
1072     *              etc.
1073     *
1074     * @param timeStyle The type of time format desired.  This can be
1075     *              {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM},
1076     *              etc.
1077     *
1078     * @param locale The locale for which the date/time format is desired.
1079     *
1080     * @see DateFormat#getDateTimeInstance
1081     * @stable ICU 2.0
1082     */
1083    static final public DateFormat getDateTimeInstance(Calendar cal, int dateStyle,
1084                                                 int timeStyle, Locale locale)
1085    {
1086        return cal.getDateTimeFormat(dateStyle, timeStyle, ULocale.forLocale(locale));
1087    }
1088
1089    /**
1090     * Create a {@link DateFormat} object that can be used to format dates and times in
1091     * the calendar system specified by <code>cal</code>.
1092     * <p>
1093     * <b>Note:</b> When this functionality is moved into the core JDK, this method
1094     * will probably be replaced by a new overload of {@link DateFormat#getInstance}.
1095     * <p>
1096     * @param cal   The calendar system for which a date/time format is desired.
1097     *
1098     * @param dateStyle The type of date format desired.  This can be
1099     *              {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM},
1100     *              etc.
1101     *
1102     * @param timeStyle The type of time format desired.  This can be
1103     *              {@link DateFormat#SHORT}, {@link DateFormat#MEDIUM},
1104     *              etc.
1105     *
1106     * @param locale The locale for which the date/time format is desired.
1107     *
1108     * @see DateFormat#getDateTimeInstance
1109     * @draft ICU 3.2
1110     * @provisional This API might change or be removed in a future release.
1111     */
1112    static final public DateFormat getDateTimeInstance(Calendar cal, int dateStyle,
1113                                                 int timeStyle, ULocale locale)
1114    {
1115        return cal.getDateTimeFormat(dateStyle, timeStyle, locale);
1116    }
1117
1118    /**
1119     * Convenience overload
1120     * @stable ICU 2.0
1121     */
1122    static final public DateFormat getInstance(Calendar cal, Locale locale) {
1123        return getDateTimeInstance(cal, SHORT, SHORT, ULocale.forLocale(locale));
1124    }
1125
1126    /**
1127     * Convenience overload
1128     * @draft ICU 3.2
1129     * @provisional This API might change or be removed in a future release.
1130     */
1131    static final public DateFormat getInstance(Calendar cal, ULocale locale) {
1132        return getDateTimeInstance(cal, SHORT, SHORT, locale);
1133    }
1134
1135    /**
1136     * Convenience overload
1137     * @stable ICU 2.0
1138     */
1139    static final public DateFormat getInstance(Calendar cal) {
1140        return getInstance(cal, ULocale.getDefault());
1141    }
1142
1143    /**
1144     * Convenience overload
1145     * @stable ICU 2.0
1146     */
1147    static final public DateFormat getDateInstance(Calendar cal, int dateStyle) {
1148        return getDateInstance(cal, dateStyle, ULocale.getDefault());
1149    }
1150
1151    /**
1152     * Convenience overload
1153     * @stable ICU 2.0
1154     */
1155    static final public DateFormat getTimeInstance(Calendar cal, int timeStyle) {
1156        return getTimeInstance(cal, timeStyle, ULocale.getDefault());
1157    }
1158
1159    /**
1160     * Convenience overload
1161     * @stable ICU 2.0
1162     */
1163    static final public DateFormat getDateTimeInstance(Calendar cal, int dateStyle, int timeStyle) {
1164        return getDateTimeInstance(cal, dateStyle, timeStyle, ULocale.getDefault());
1165    }
1166}
1167
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags