292 |
292 |
293 // Proclaim serial compatibility with 1.1 FCS |
293 // Proclaim serial compatibility with 1.1 FCS |
294 private static final long serialVersionUID = 7218322306649953788L; |
294 private static final long serialVersionUID = 7218322306649953788L; |
295 |
295 |
296 /** |
296 /** |
297 * Overrides Format. |
297 * Formats the given {@code Object} into a date-time string. The formatted |
298 * Formats a time object into a time string. Examples of time objects |
298 * string is appended to the given {@code StringBuffer}. |
299 * are a time value expressed in milliseconds and a Date object. |
299 * |
300 * @param obj must be a Number or a Date. |
300 * @param obj Must be a {@code Date} or a {@code Number} representing a |
301 * @param toAppendTo the string buffer for the returning time string. |
301 * millisecond offset from the <a href="../util/Calendar.html#Epoch">Epoch</a>. |
302 * @return the string buffer passed in as toAppendTo, with formatted text appended. |
302 * @param toAppendTo The string buffer for the returning date-time string. |
303 * @param fieldPosition keeps track of the position of the field |
303 * @param fieldPosition keeps track on the position of the field within |
304 * within the returned string. |
304 * the returned string. For example, given a date-time text |
305 * On input: an alignment field, |
305 * {@code "1996.07.10 AD at 15:08:56 PDT"}, if the given {@code fieldPosition} |
306 * if desired. On output: the offsets of the alignment field. For |
306 * is {@link DateFormat#YEAR_FIELD}, the begin index and end index of |
307 * example, given a time text "1996.07.10 AD at 15:08:56 PDT", |
307 * {@code fieldPosition} will be set to 0 and 4, respectively. |
308 * if the given fieldPosition is DateFormat.YEAR_FIELD, the |
308 * Notice that if the same date-time field appears more than once in a |
309 * begin index and end index of fieldPosition will be set to |
309 * pattern, the {@code fieldPosition} will be set for the first occurrence |
310 * 0 and 4, respectively. |
310 * of that date-time field. For instance, formatting a {@code Date} to the |
311 * Notice that if the same time field appears |
311 * date-time string {@code "1 PM PDT (Pacific Daylight Time)"} using the |
312 * more than once in a pattern, the fieldPosition will be set for the first |
312 * pattern {@code "h a z (zzzz)"} and the alignment field |
313 * occurrence of that time field. For instance, formatting a Date to |
313 * {@link DateFormat#TIMEZONE_FIELD}, the begin index and end index of |
314 * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern |
314 * {@code fieldPosition} will be set to 5 and 8, respectively, for the |
315 * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD, |
315 * first occurrence of the timezone pattern character {@code 'z'}. |
316 * the begin index and end index of fieldPosition will be set to |
316 * @return the string buffer passed in as {@code toAppendTo}, |
317 * 5 and 8, respectively, for the first occurrence of the timezone |
317 * with formatted text appended. |
318 * pattern character 'z'. |
|
319 * @exception IllegalArgumentException if the {@code Format} cannot format |
318 * @exception IllegalArgumentException if the {@code Format} cannot format |
320 * the given {@code obj}. |
319 * the given {@code obj}. |
321 * @see java.text.Format |
320 * @see java.text.Format |
322 */ |
321 */ |
323 public final StringBuffer format(Object obj, StringBuffer toAppendTo, |
322 public final StringBuffer format(Object obj, StringBuffer toAppendTo, |
331 else |
330 else |
332 throw new IllegalArgumentException("Cannot format given Object as a Date"); |
331 throw new IllegalArgumentException("Cannot format given Object as a Date"); |
333 } |
332 } |
334 |
333 |
335 /** |
334 /** |
336 * Formats a Date into a date/time string. |
335 * Formats a {@link Date} into a date-time string. The formatted |
337 * @param date a Date to be formatted into a date/time string. |
336 * string is appended to the given {@code StringBuffer}. |
338 * @param toAppendTo the string buffer for the returning date/time string. |
337 * |
339 * @param fieldPosition keeps track of the position of the field |
338 * @param date a Date to be formatted into a date-time string. |
340 * within the returned string. |
339 * @param toAppendTo the string buffer for the returning date-time string. |
341 * On input: an alignment field, |
340 * @param fieldPosition keeps track on the position of the field within |
342 * if desired. On output: the offsets of the alignment field. For |
341 * the returned string. For example, given a date-time text |
343 * example, given a time text "1996.07.10 AD at 15:08:56 PDT", |
342 * {@code "1996.07.10 AD at 15:08:56 PDT"}, if the given {@code fieldPosition} |
344 * if the given fieldPosition is DateFormat.YEAR_FIELD, the |
343 * is {@link DateFormat#YEAR_FIELD}, the begin index and end index of |
345 * begin index and end index of fieldPosition will be set to |
344 * {@code fieldPosition} will be set to 0 and 4, respectively. |
346 * 0 and 4, respectively. |
345 * Notice that if the same date-time field appears more than once in a |
347 * Notice that if the same time field appears |
346 * pattern, the {@code fieldPosition} will be set for the first occurrence |
348 * more than once in a pattern, the fieldPosition will be set for the first |
347 * of that date-time field. For instance, formatting a {@code Date} to the |
349 * occurrence of that time field. For instance, formatting a Date to |
348 * date-time string {@code "1 PM PDT (Pacific Daylight Time)"} using the |
350 * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern |
349 * pattern {@code "h a z (zzzz)"} and the alignment field |
351 * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD, |
350 * {@link DateFormat#TIMEZONE_FIELD}, the begin index and end index of |
352 * the begin index and end index of fieldPosition will be set to |
351 * {@code fieldPosition} will be set to 5 and 8, respectively, for the |
353 * 5 and 8, respectively, for the first occurrence of the timezone |
352 * first occurrence of the timezone pattern character {@code 'z'}. |
354 * pattern character 'z'. |
353 * @return the string buffer passed in as {@code toAppendTo}, with formatted |
355 * @return the string buffer passed in as toAppendTo, with formatted text appended. |
354 * text appended. |
356 */ |
355 */ |
357 public abstract StringBuffer format(Date date, StringBuffer toAppendTo, |
356 public abstract StringBuffer format(Date date, StringBuffer toAppendTo, |
358 FieldPosition fieldPosition); |
357 FieldPosition fieldPosition); |
359 |
358 |
360 /** |
359 /** |
361 * Formats a Date into a date/time string. |
360 * Formats a {@link Date} into a date-time string. |
362 * @param date the time value to be formatted into a time string. |
361 * |
363 * @return the formatted time string. |
362 * @param date the time value to be formatted into a date-time string. |
|
363 * @return the formatted date-time string. |
364 */ |
364 */ |
365 public final String format(Date date) |
365 public final String format(Date date) |
366 { |
366 { |
367 return format(date, new StringBuffer(), |
367 return format(date, new StringBuffer(), |
368 DontCareFieldPosition.INSTANCE).toString(); |
368 DontCareFieldPosition.INSTANCE).toString(); |