306 * string is appended to the given {@code StringBuffer}.
307 *
308 * @param obj Must be a {@code Date} or a {@code Number} representing a
309 * millisecond offset from the <a href="../util/Calendar.html#Epoch">Epoch</a>.
310 * @param toAppendTo The string buffer for the returning date-time string.
311 * @param fieldPosition keeps track on the position of the field within
312 * the returned string. For example, given a date-time text
313 * {@code "1996.07.10 AD at 15:08:56 PDT"}, if the given {@code fieldPosition}
314 * is {@link DateFormat#YEAR_FIELD}, the begin index and end index of
315 * {@code fieldPosition} will be set to 0 and 4, respectively.
316 * Notice that if the same date-time field appears more than once in a
317 * pattern, the {@code fieldPosition} will be set for the first occurrence
318 * of that date-time field. For instance, formatting a {@code Date} to the
319 * date-time string {@code "1 PM PDT (Pacific Daylight Time)"} using the
320 * pattern {@code "h a z (zzzz)"} and the alignment field
321 * {@link DateFormat#TIMEZONE_FIELD}, the begin index and end index of
322 * {@code fieldPosition} will be set to 5 and 8, respectively, for the
323 * first occurrence of the timezone pattern character {@code 'z'}.
324 * @return the string buffer passed in as {@code toAppendTo},
325 * with formatted text appended.
326 * @exception IllegalArgumentException if the {@code Format} cannot format
327 * the given {@code obj}.
328 * @see java.text.Format
329 */
330 public final StringBuffer format(Object obj, StringBuffer toAppendTo,
331 FieldPosition fieldPosition)
332 {
333 if (obj instanceof Date)
334 return format( (Date)obj, toAppendTo, fieldPosition );
335 else if (obj instanceof Number)
336 return format( new Date(((Number)obj).longValue()),
337 toAppendTo, fieldPosition );
338 else
339 throw new IllegalArgumentException("Cannot format given Object as a Date");
340 }
341
342 /**
343 * Formats a {@link Date} into a date-time string. The formatted
344 * string is appended to the given {@code StringBuffer}.
345 *
346 * @param date a Date to be formatted into a date-time string.
368 * Formats a {@link Date} into a date-time string.
369 *
370 * @param date the time value to be formatted into a date-time string.
371 * @return the formatted date-time string.
372 */
373 public final String format(Date date)
374 {
375 return format(date, new StringBuffer(),
376 DontCareFieldPosition.INSTANCE).toString();
377 }
378
379 /**
380 * Parses text from the beginning of the given string to produce a date.
381 * The method may not use the entire text of the given string.
382 * <p>
383 * See the {@link #parse(String, ParsePosition)} method for more information
384 * on date parsing.
385 *
386 * @param source A <code>String</code> whose beginning should be parsed.
387 * @return A <code>Date</code> parsed from the string.
388 * @exception ParseException if the beginning of the specified string
389 * cannot be parsed.
390 */
391 public Date parse(String source) throws ParseException
392 {
393 ParsePosition pos = new ParsePosition(0);
394 Date result = parse(source, pos);
395 if (pos.index == 0)
396 throw new ParseException("Unparseable date: \"" + source + "\"" ,
397 pos.errorIndex);
398 return result;
399 }
400
401 /**
402 * Parse a date/time string according to the given parse position. For
403 * example, a time text {@code "07/10/96 4:5 PM, PDT"} will be parsed into a {@code Date}
404 * that is equivalent to {@code Date(837039900000L)}.
405 *
406 * <p> By default, parsing is lenient: If the input is not in the form used
407 * by this object's format method but can still be parsed as a date, then
408 * the parse succeeds. Clients may insist on strict adherence to the
|
306 * string is appended to the given {@code StringBuffer}.
307 *
308 * @param obj Must be a {@code Date} or a {@code Number} representing a
309 * millisecond offset from the <a href="../util/Calendar.html#Epoch">Epoch</a>.
310 * @param toAppendTo The string buffer for the returning date-time string.
311 * @param fieldPosition keeps track on the position of the field within
312 * the returned string. For example, given a date-time text
313 * {@code "1996.07.10 AD at 15:08:56 PDT"}, if the given {@code fieldPosition}
314 * is {@link DateFormat#YEAR_FIELD}, the begin index and end index of
315 * {@code fieldPosition} will be set to 0 and 4, respectively.
316 * Notice that if the same date-time field appears more than once in a
317 * pattern, the {@code fieldPosition} will be set for the first occurrence
318 * of that date-time field. For instance, formatting a {@code Date} to the
319 * date-time string {@code "1 PM PDT (Pacific Daylight Time)"} using the
320 * pattern {@code "h a z (zzzz)"} and the alignment field
321 * {@link DateFormat#TIMEZONE_FIELD}, the begin index and end index of
322 * {@code fieldPosition} will be set to 5 and 8, respectively, for the
323 * first occurrence of the timezone pattern character {@code 'z'}.
324 * @return the string buffer passed in as {@code toAppendTo},
325 * with formatted text appended.
326 * @throws IllegalArgumentException if the {@code Format} cannot format
327 * the given {@code obj}.
328 * @see java.text.Format
329 */
330 public final StringBuffer format(Object obj, StringBuffer toAppendTo,
331 FieldPosition fieldPosition)
332 {
333 if (obj instanceof Date)
334 return format( (Date)obj, toAppendTo, fieldPosition );
335 else if (obj instanceof Number)
336 return format( new Date(((Number)obj).longValue()),
337 toAppendTo, fieldPosition );
338 else
339 throw new IllegalArgumentException("Cannot format given Object as a Date");
340 }
341
342 /**
343 * Formats a {@link Date} into a date-time string. The formatted
344 * string is appended to the given {@code StringBuffer}.
345 *
346 * @param date a Date to be formatted into a date-time string.
368 * Formats a {@link Date} into a date-time string.
369 *
370 * @param date the time value to be formatted into a date-time string.
371 * @return the formatted date-time string.
372 */
373 public final String format(Date date)
374 {
375 return format(date, new StringBuffer(),
376 DontCareFieldPosition.INSTANCE).toString();
377 }
378
379 /**
380 * Parses text from the beginning of the given string to produce a date.
381 * The method may not use the entire text of the given string.
382 * <p>
383 * See the {@link #parse(String, ParsePosition)} method for more information
384 * on date parsing.
385 *
386 * @param source A <code>String</code> whose beginning should be parsed.
387 * @return A <code>Date</code> parsed from the string.
388 * @throws ParseException if the beginning of the specified string
389 * cannot be parsed.
390 */
391 public Date parse(String source) throws ParseException
392 {
393 ParsePosition pos = new ParsePosition(0);
394 Date result = parse(source, pos);
395 if (pos.index == 0)
396 throw new ParseException("Unparseable date: \"" + source + "\"" ,
397 pos.errorIndex);
398 return result;
399 }
400
401 /**
402 * Parse a date/time string according to the given parse position. For
403 * example, a time text {@code "07/10/96 4:5 PM, PDT"} will be parsed into a {@code Date}
404 * that is equivalent to {@code Date(837039900000L)}.
405 *
406 * <p> By default, parsing is lenient: If the input is not in the form used
407 * by this object's format method but can still be parsed as a date, then
408 * the parse succeeds. Clients may insist on strict adherence to the
|