1 /* DateFormat.java -- Class for formatting/parsing date/times
2 Copyright (C) 1998, 1999, 2000, 2001, 2003, 2004, 2005
3 Free Software Foundation, Inc.
5 This file is part of GNU Classpath.
7 GNU Classpath is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 2, or (at your option)
12 GNU Classpath is distributed in the hope that it will be useful, but
13 WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with GNU Classpath; see the file COPYING. If not, write to the
19 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
22 Linking this library statically or dynamically with other modules is
23 making a combined work based on this library. Thus, the terms and
24 conditions of the GNU General Public License cover the whole
27 As a special exception, the copyright holders of this library give you
28 permission to link this library with independent modules to produce an
29 executable, regardless of the license terms of these independent
30 modules, and to copy and distribute the resulting executable under
31 terms of your choice, provided that you also meet, for each linked
32 independent module, the terms and conditions of the license of that
33 module. An independent module is a module which is not derived from
34 or based on this library. If you modify this library, you may extend
35 this exception to your version of the library, but you are not
36 obligated to do so. If you do not wish to do so, delete this
37 exception statement from your version. */
42 import java
.io
.InvalidObjectException
;
43 import java
.util
.Calendar
;
44 import java
.util
.Date
;
45 import java
.util
.Locale
;
46 import java
.util
.MissingResourceException
;
47 import java
.util
.ResourceBundle
;
48 import java
.util
.TimeZone
;
51 * @author Per Bothner (bothner@cygnus.com)
52 * @date October 25, 1998.
54 /* Written using "Java Class Libraries", 2nd edition, plus online
55 * API docs for JDK 1.2 beta from http://www.javasoft.com.
56 * Status: Mostly complete; search for FIXME to see omissions.
59 public abstract class DateFormat
extends Format
implements Cloneable
61 protected Calendar calendar
;
62 protected NumberFormat numberFormat
;
64 // (Values determined using a test program.)
65 public static final int FULL
= 0;
66 public static final int LONG
= 1;
67 public static final int MEDIUM
= 2;
68 public static final int SHORT
= 3;
69 public static final int DEFAULT
= MEDIUM
;
71 /* These constants need to have these exact values. They
72 * correspond to index positions within the localPatternChars
73 * string for a given locale. Each locale may specify its
74 * own character for a particular field, but the position
75 * of these characters must correspond to an appropriate field
76 * number (as listed below), in order for their meaning to
77 * be determined. For example, the US locale uses
78 * the string "GyMdkHmsSEDFwWahKzYeugAZ", where 'G' is the character
79 * for era, 'y' for year, and so on down to 'Z' for time zone.
82 * Represents the position of the era
83 * pattern character in the array of
84 * localized pattern characters.
85 * For example, 'AD' is an era used
86 * in the Gregorian calendar system.
87 * In the U.S. locale, this is 'G'.
89 public static final int ERA_FIELD
= 0;
91 * Represents the position of the year
92 * pattern character in the array of
93 * localized pattern characters.
94 * In the U.S. locale, this is 'y'.
96 public static final int YEAR_FIELD
= 1;
98 * Represents the position of the month
99 * pattern character in the array of
100 * localized pattern characters.
101 * In the U.S. locale, this is 'M'.
103 public static final int MONTH_FIELD
= 2;
105 * Represents the position of the date
106 * or day of the month pattern character
107 * in the array of localized pattern
108 * characters. In the U.S. locale,
111 public static final int DATE_FIELD
= 3;
113 * Represents the position of the 24
114 * hour pattern character in the array of
115 * localized pattern characters.
116 * In the U.S. locale, this is 'k'.
117 * This field numbers hours from 1 to 24.
119 public static final int HOUR_OF_DAY1_FIELD
= 4;
121 * Represents the position of the 24
122 * hour pattern character in the array of
123 * localized pattern characters.
124 * In the U.S. locale, this is 'H'.
125 * This field numbers hours from 0 to 23.
127 public static final int HOUR_OF_DAY0_FIELD
= 5;
129 * Represents the position of the minute
130 * pattern character in the array of
131 * localized pattern characters.
132 * In the U.S. locale, this is 'm'.
134 public static final int MINUTE_FIELD
= 6;
136 * Represents the position of the second
137 * pattern character in the array of
138 * localized pattern characters.
139 * In the U.S. locale, this is 's'.
141 public static final int SECOND_FIELD
= 7;
143 * Represents the position of the millisecond
144 * pattern character in the array of
145 * localized pattern characters.
146 * In the U.S. locale, this is 'S'.
148 public static final int MILLISECOND_FIELD
= 8;
150 * Represents the position of the day of the
151 * week pattern character in the array of
152 * localized pattern characters.
153 * In the U.S. locale, this is 'E'.
155 public static final int DAY_OF_WEEK_FIELD
= 9;
157 * Represents the position of the day of the
158 * year pattern character in the array of
159 * localized pattern characters.
160 * In the U.S. locale, this is 'D'.
162 public static final int DAY_OF_YEAR_FIELD
= 10;
164 * Represents the position of the day of the
165 * week in the month pattern character in the
166 * array of localized pattern characters.
167 * In the U.S. locale, this is 'F'.
169 public static final int DAY_OF_WEEK_IN_MONTH_FIELD
= 11;
171 * Represents the position of the week of the
172 * year pattern character in the array of
173 * localized pattern characters.
174 * In the U.S. locale, this is 'w'.
176 public static final int WEEK_OF_YEAR_FIELD
= 12;
178 * Represents the position of the week of the
179 * month pattern character in the array of
180 * localized pattern characters.
181 * In the U.S. locale, this is 'W'.
183 public static final int WEEK_OF_MONTH_FIELD
= 13;
185 * Represents the position of the am/pm
186 * pattern character in the array of
187 * localized pattern characters.
188 * In the U.S. locale, this is 'a'.
190 public static final int AM_PM_FIELD
= 14;
192 * Represents the position of the 12
193 * hour pattern character in the array of
194 * localized pattern characters.
195 * In the U.S. locale, this is 'h'.
196 * This field numbers hours from 1 to 12.
198 public static final int HOUR1_FIELD
= 15;
200 * Represents the position of the 12
201 * hour pattern character in the array of
202 * localized pattern characters.
203 * In the U.S. locale, this is 'K'.
204 * This field numbers hours from 0 to 11.
206 public static final int HOUR0_FIELD
= 16;
208 * Represents the position of the generic
209 * timezone pattern character in the array of
210 * localized pattern characters.
211 * In the U.S. locale, this is 'z'.
213 public static final int TIMEZONE_FIELD
= 17;
215 * Represents the position of the ISO year
216 * pattern character in the array of
217 * localized pattern characters.
218 * In the U.S. locale, this is 'Y'.
219 * This is a GNU extension in accordance with
220 * the CLDR data used. This value may
221 * differ from the normal year value.
223 public static final int ISO_YEAR_FIELD
= 18;
225 * Represents the position of the localized
226 * day of the week pattern character in the
227 * array of localized pattern characters.
228 * In the U.S. locale, this is 'e'.
229 * This is a GNU extension in accordance with
230 * the CLDR data used. This value only
231 * differs from the day of the week with
232 * numeric formatting, in which case the
233 * locale's first day of the week is used.
235 public static final int LOCALIZED_DAY_OF_WEEK_FIELD
= 19;
237 * Represents the position of the extended year
238 * pattern character in the array of
239 * localized pattern characters.
240 * In the U.S. locale, this is 'u'.
241 * This is a GNU extension in accordance with
242 * the CLDR data used. This value modifies
243 * the year value, so as to incorporate the era.
244 * For example, in the Gregorian calendar system,
245 * the extended year is negative instead of being
248 public static final int EXTENDED_YEAR_FIELD
= 20;
250 * Represents the position of the modified Julian
251 * day pattern character in the array of
252 * localized pattern characters.
253 * In the U.S. locale, this is 'g'.
254 * This is a GNU extension in accordance with
255 * the CLDR data used. This value differs
256 * from the standard Julian day in that days
257 * are marked from midnight onwards rather than
258 * noon, and the local time zone affects the value.
259 * In simple terms, it can be thought of as all
260 * the date fields represented as a single number.
262 public static final int MODIFIED_JULIAN_DAY_FIELD
= 21;
264 * Represents the position of the millisecond
265 * in the day pattern character in the array of
266 * localized pattern characters.
267 * In the U.S. locale, this is 'A'.
268 * This is a GNU extension in accordance with
269 * the CLDR data used. This value represents
270 * all the time fields (excluding the time zone)
271 * numerically, giving the number of milliseconds
272 * into the day (e.g. 10 in the morning would
273 * be 10 * 60 * 60 * 1000). Any daylight savings
274 * offset also affects this value.
276 public static final int MILLISECOND_IN_DAY_FIELD
= 22;
278 * Represents the position of the RFC822
279 * timezone pattern character in the array of
280 * localized pattern characters.
281 * In the U.S. locale, this is 'Z'.
282 * This is a GNU extension in accordance with
283 * the CLDR data used. The value is the offset
284 * of the current time from GMT e.g. -0500 would
285 * be five hours prior to GMT.
287 public static final int RFC822_TIMEZONE_FIELD
= 23;
289 public static class Field
extends Format
.Field
291 static final long serialVersionUID
= 7441350119349544720L;
293 private int calendarField
;
295 public static final DateFormat
.Field ERA
296 = new Field("era", Calendar
.ERA
);
297 public static final DateFormat
.Field YEAR
298 = new Field("year", Calendar
.YEAR
);
299 public static final DateFormat
.Field MONTH
300 = new Field("month", Calendar
.MONTH
);
301 public static final DateFormat
.Field DAY_OF_MONTH
302 = new Field("day of month", Calendar
.DAY_OF_MONTH
);
303 public static final DateFormat
.Field HOUR_OF_DAY1
304 = new Field("hour of day 1", Calendar
.HOUR_OF_DAY
);
305 public static final DateFormat
.Field HOUR_OF_DAY0
306 = new Field("hour of day 0", Calendar
.HOUR_OF_DAY
);
307 public static final DateFormat
.Field MINUTE
308 = new Field("minute", Calendar
.MINUTE
);
309 public static final DateFormat
.Field SECOND
310 = new Field("second", Calendar
.SECOND
);
311 public static final DateFormat
.Field MILLISECOND
312 = new Field("millisecond", Calendar
.MILLISECOND
);
313 public static final DateFormat
.Field DAY_OF_WEEK
314 = new Field("day of week", Calendar
.DAY_OF_WEEK
);
315 public static final DateFormat
.Field DAY_OF_YEAR
316 = new Field("day of year", Calendar
.DAY_OF_YEAR
);
317 public static final DateFormat
.Field DAY_OF_WEEK_IN_MONTH
318 = new Field("day of week in month", Calendar
.DAY_OF_WEEK_IN_MONTH
);
319 public static final DateFormat
.Field WEEK_OF_YEAR
320 = new Field("week of year", Calendar
.WEEK_OF_YEAR
);
321 public static final DateFormat
.Field WEEK_OF_MONTH
322 = new Field("week of month", Calendar
.WEEK_OF_MONTH
);
323 public static final DateFormat
.Field AM_PM
324 = new Field("am/pm", Calendar
.AM_PM
);
325 public static final DateFormat
.Field HOUR1
326 = new Field("hour1", Calendar
.HOUR
);
327 public static final DateFormat
.Field HOUR0
328 = new Field("hour0", Calendar
.HOUR
);
329 public static final DateFormat
.Field TIME_ZONE
330 = new Field("timezone", Calendar
.ZONE_OFFSET
);
331 public static final DateFormat
.Field ISO_YEAR
332 = new Field("iso year", Calendar
.YEAR
);
333 public static final DateFormat
.Field LOCALIZED_DAY_OF_WEEK
334 = new Field("localized day of week", Calendar
.DAY_OF_WEEK
);
335 public static final DateFormat
.Field EXTENDED_YEAR
336 = new Field("extended year", Calendar
.YEAR
);
337 public static final DateFormat
.Field MODIFIED_JULIAN_DAY
338 = new Field("julian day", -1);
339 public static final DateFormat
.Field MILLISECOND_IN_DAY
340 = new Field("millisecond in day", -1);
341 public static final DateFormat
.Field RFC822_TIME_ZONE
342 = new Field("rfc822 timezone", Calendar
.ZONE_OFFSET
);
344 static final DateFormat
.Field
[] allFields
=
346 ERA
, YEAR
, MONTH
, DAY_OF_MONTH
, HOUR_OF_DAY1
,
347 HOUR_OF_DAY0
, MINUTE
, SECOND
, MILLISECOND
,
348 DAY_OF_WEEK
, DAY_OF_YEAR
, DAY_OF_WEEK_IN_MONTH
,
349 WEEK_OF_YEAR
, WEEK_OF_MONTH
, AM_PM
, HOUR1
, HOUR0
,
350 TIME_ZONE
, ISO_YEAR
, LOCALIZED_DAY_OF_WEEK
,
351 EXTENDED_YEAR
, MODIFIED_JULIAN_DAY
, MILLISECOND_IN_DAY
,
355 // For deserialization
361 protected Field(String name
, int calendarField
)
364 this.calendarField
= calendarField
;
367 public int getCalendarField()
369 return calendarField
;
372 public static Field
ofCalendarField(int calendarField
)
374 if (calendarField
>= allFields
.length
|| calendarField
< 0)
375 throw new IllegalArgumentException("no such calendar field ("
376 + calendarField
+ ")");
378 return allFields
[calendarField
];
381 protected Object
readResolve() throws InvalidObjectException
383 String s
= getName();
385 for (int i
=0;i
<allFields
.length
;i
++)
386 if (s
.equals(allFields
[i
].getName()))
389 throw new InvalidObjectException("no such DateFormat field called " + s
);
394 * This method initializes a new instance of <code>DateFormat</code>.
396 protected DateFormat ()
401 * This method tests this object for equality against the specified object.
402 * The two objects will be considered equal if an only if the specified
406 * <li>Is not <code>null</code>.</li>
407 * <li>Is an instance of <code>DateFormat</code>.</li>
408 * <li>Has the same numberFormat field value as this object.</li>
411 * @param obj The object to test for equality against.
413 * @return <code>true</code> if the specified object is equal to this object,
414 * <code>false</code> otherwise.
416 public boolean equals (Object obj
)
418 if (!(obj
instanceof DateFormat
))
421 DateFormat d
= (DateFormat
) obj
;
423 return numberFormat
.equals(d
.numberFormat
);
427 * This method returns a copy of this object.
429 * @return A copy of this object.
431 public Object
clone ()
433 // We know the superclass just call's Object's generic cloner.
434 return super.clone ();
438 * This method formats the specified <code>Object</code> into a date string
439 * and appends it to the specified <code>StringBuffer</code>.
440 * The specified object must be an instance of <code>Number</code> or
441 * <code>Date</code> or an <code>IllegalArgumentException</code> will be
444 * @param obj The <code>Object</code> to format.
445 * @param toAppendTo The <code>StringBuffer</code> to append the resultant
446 * <code>String</code> to.
447 * @param fieldPosition Is updated to the start and end index of the
450 * @return The <code>StringBuffer</code> supplied on input, with the
451 * formatted date/time appended.
453 public final StringBuffer
format (Object obj
,
454 StringBuffer buf
, FieldPosition pos
)
456 if (obj
instanceof Number
)
457 obj
= new Date(((Number
) obj
).longValue());
458 else if (! (obj
instanceof Date
))
459 throw new IllegalArgumentException
460 ("Cannot format given Object as a Date");
462 return format ((Date
) obj
, buf
, pos
);
466 * Formats the date argument according to the pattern specified.
468 * @param date The formatted date.
470 public final String
format (Date date
)
472 StringBuffer sb
= new StringBuffer ();
473 format (date
, sb
, new FieldPosition (MONTH_FIELD
));
474 return sb
.toString();
478 * This method formats a <code>Date</code> into a string and appends it
479 * to the specified <code>StringBuffer</code>.
481 * @param date The <code>Date</code> value to format.
482 * @param toAppendTo The <code>StringBuffer</code> to append the resultant
483 * <code>String</code> to.
484 * @param fieldPosition Is updated to the start and end index of the
487 * @return The <code>StringBuffer</code> supplied on input, with the
488 * formatted date/time appended.
490 public abstract StringBuffer
format (Date date
,
491 StringBuffer buf
, FieldPosition pos
);
494 * This method returns a list of available locales supported by this
497 public static Locale
[] getAvailableLocales()
500 Locale
[] l
= new Locale
[1];
506 * This method returns the <code>Calendar</code> object being used by
507 * this object to parse/format datetimes.
509 * @return The <code>Calendar</code> being used by this object.
511 * @see java.util.Calendar
513 public Calendar
getCalendar ()
518 private static DateFormat
computeInstance (int style
, Locale loc
,
519 boolean use_date
, boolean use_time
)
521 return computeInstance (style
, style
, loc
, use_date
, use_time
);
524 private static DateFormat
computeInstance (int dateStyle
, int timeStyle
,
525 Locale loc
, boolean use_date
,
531 res
= ResourceBundle
.getBundle("gnu.java.locale.LocaleInformation",
532 loc
, ClassLoader
.getSystemClassLoader());
534 catch (MissingResourceException x
)
539 String pattern
= null;
546 name
= "fullDateFormat";
547 def
= "EEEE MMMM d, yyyy G";
550 name
= "longDateFormat";
551 def
= "MMMM d, yyyy";
554 name
= "mediumDateFormat";
558 name
= "shortDateFormat";
562 throw new IllegalArgumentException ();
566 pattern
= res
== null ? def
: res
.getString(name
);
568 catch (MissingResourceException x
)
585 name
= "fullTimeFormat";
586 def
= "h:mm:ss;S 'o''clock' a z";
589 name
= "longTimeFormat";
593 name
= "mediumTimeFormat";
597 name
= "shortTimeFormat";
601 throw new IllegalArgumentException ();
607 s
= res
== null ? def
: res
.getString(name
);
609 catch (MissingResourceException x
)
616 return new SimpleDateFormat (pattern
, loc
);
620 * This method returns an instance of <code>DateFormat</code> that will
621 * format using the default formatting style for dates.
623 * @return A new <code>DateFormat</code> instance.
625 public static final DateFormat
getDateInstance ()
627 return getDateInstance (DEFAULT
, Locale
.getDefault());
631 * This method returns an instance of <code>DateFormat</code> that will
632 * format using the specified formatting style for dates.
634 * @param style The type of formatting to perform.
636 * @return A new <code>DateFormat</code> instance.
638 public static final DateFormat
getDateInstance (int style
)
640 return getDateInstance (style
, Locale
.getDefault());
644 * This method returns an instance of <code>DateFormat</code> that will
645 * format using the specified formatting style for dates. The specified
646 * localed will be used in place of the default.
648 * @param style The type of formatting to perform.
649 * @param aLocale The desired locale.
651 * @return A new <code>DateFormat</code> instance.
653 public static final DateFormat
getDateInstance (int style
, Locale loc
)
655 return computeInstance (style
, loc
, true, false);
659 * This method returns a new instance of <code>DateFormat</code> that
660 * formats both dates and times using the <code>SHORT</code> style.
662 * @return A new <code>DateFormat</code>instance.
664 public static final DateFormat
getDateTimeInstance ()
666 return getDateTimeInstance (DEFAULT
, DEFAULT
, Locale
.getDefault());
670 * This method returns a new instance of <code>DateFormat</code> that
671 * formats both dates and times using the <code>DEFAULT</code> style.
673 * @return A new <code>DateFormat</code>instance.
675 public static final DateFormat
getDateTimeInstance (int dateStyle
,
678 return getDateTimeInstance (dateStyle
, timeStyle
, Locale
.getDefault());
682 * This method returns a new instance of <code>DateFormat</code> that
683 * formats both dates and times using the specified styles.
685 * @param dateStyle The desired style for date formatting.
686 * @param timeStyle The desired style for time formatting
688 * @return A new <code>DateFormat</code>instance.
690 public static final DateFormat
getDateTimeInstance (int dateStyle
,
694 return computeInstance (dateStyle
, timeStyle
, loc
, true, true);
698 * This method returns a new instance of <code>DateFormat</code> that
699 * formats both dates and times using the <code>SHORT</code> style.
701 * @return A new <code>DateFormat</code>instance.
703 public static final DateFormat
getInstance ()
705 // JCL book says SHORT.
706 return getDateTimeInstance (SHORT
, SHORT
, Locale
.getDefault());
710 * This method returns the <code>NumberFormat</code> object being used
711 * by this object to parse/format time values.
713 * @return The <code>NumberFormat</code> in use by this object.
715 public NumberFormat
getNumberFormat ()
721 * This method returns an instance of <code>DateFormat</code> that will
722 * format using the default formatting style for times.
724 * @return A new <code>DateFormat</code> instance.
726 public static final DateFormat
getTimeInstance ()
728 return getTimeInstance (DEFAULT
, Locale
.getDefault());
732 * This method returns an instance of <code>DateFormat</code> that will
733 * format using the specified formatting style for times.
735 * @param style The type of formatting to perform.
737 * @return A new <code>DateFormat</code> instance.
739 public static final DateFormat
getTimeInstance (int style
)
741 return getTimeInstance (style
, Locale
.getDefault());
745 * This method returns an instance of <code>DateFormat</code> that will
746 * format using the specified formatting style for times. The specified
747 * localed will be used in place of the default.
749 * @param style The type of formatting to perform.
750 * @param aLocale The desired locale.
752 * @return A new <code>DateFormat</code> instance.
754 public static final DateFormat
getTimeInstance (int style
, Locale loc
)
756 return computeInstance (style
, loc
, false, true);
760 * This method returns the <code>TimeZone</code> object being used by
763 * @return The time zone in use.
765 public TimeZone
getTimeZone ()
767 return calendar
.getTimeZone();
771 * This method returns a hash value for this object.
773 * @return A hash value for this object.
775 public int hashCode ()
777 if (numberFormat
!= null)
778 return numberFormat
.hashCode();
784 * This method indicates whether or not the parsing of date and time
785 * values should be done in a lenient value.
787 * @return <code>true</code> if date/time parsing is lenient,
788 * <code>false</code> otherwise.
790 public boolean isLenient ()
792 return calendar
.isLenient();
796 * This method parses the specified date/time string.
798 * @param source The string to parse.
799 * @return The resultant date.
801 * @exception ParseException If the specified string cannot be parsed.
803 public Date
parse (String source
) throws ParseException
805 ParsePosition pos
= new ParsePosition(0);
806 Date result
= parse (source
, pos
);
809 int index
= pos
.getErrorIndex();
811 index
= pos
.getIndex();
812 throw new ParseException("invalid Date syntax in \""
813 + source
+ '\"', index
);
819 * This method parses the specified <code>String</code> into a
820 * <code>Date</code>. The <code>pos</code> argument contains the
821 * starting parse position on method entry and the ending parse
822 * position on method exit.
824 * @param text The string to parse.
825 * @param pos The starting parse position in entry, the ending parse
828 * @return The parsed date, or <code>null</code> if the string cannot
831 public abstract Date
parse (String source
, ParsePosition pos
);
834 * This method is identical to <code>parse(String, ParsePosition)</code>,
835 * but returns its result as an <code>Object</code> instead of a
838 * @param source The string to parse.
839 * @param pos The starting parse position in entry, the ending parse
842 * @return The parsed date, or <code>null</code> if the string cannot
845 public Object
parseObject (String source
, ParsePosition pos
)
847 return parse(source
, pos
);
851 * This method specified the <code>Calendar</code> that should be used
852 * by this object to parse/format datetimes.
854 * @param The new <code>Calendar</code> for this object.
856 * @see java.util.Calendar
858 public void setCalendar (Calendar calendar
)
860 this.calendar
= calendar
;
864 * This method specifies whether or not this object should be lenient in
865 * the syntax it accepts while parsing date/time values.
867 * @param lenient <code>true</code> if parsing should be lenient,
868 * <code>false</code> otherwise.
870 public void setLenient (boolean lenient
)
872 calendar
.setLenient(lenient
);
876 * This method specifies the <code>NumberFormat</code> object that should
877 * be used by this object to parse/format times.
879 * @param The <code>NumberFormat</code> in use by this object.
881 public void setNumberFormat (NumberFormat numberFormat
)
883 this.numberFormat
= numberFormat
;
887 * This method sets the time zone that should be used by this object.
889 * @param The new time zone.
891 public void setTimeZone (TimeZone timeZone
)
893 calendar
.setTimeZone(timeZone
);