277 * For example, 11:30 PM + 1 hour results in 12:30 AM. 278 */ 279 public static final int HOUR1_FIELD = 15; 280 /** 281 * Useful constant for zero-based HOUR field alignment. 282 * Used in FieldPosition of date/time formatting. 283 * HOUR0_FIELD is used for the zero-based 12-hour clock. 284 * For example, 11:30 PM + 1 hour results in 00:30 AM. 285 */ 286 public static final int HOUR0_FIELD = 16; 287 /** 288 * Useful constant for TIMEZONE field alignment. 289 * Used in FieldPosition of date/time formatting. 290 */ 291 public static final int TIMEZONE_FIELD = 17; 292 293 // Proclaim serial compatibility with 1.1 FCS 294 private static final long serialVersionUID = 7218322306649953788L; 295 296 /** 297 * Overrides Format. 298 * Formats a time object into a time string. Examples of time objects 299 * are a time value expressed in milliseconds and a Date object. 300 * @param obj must be a Number or a Date. 301 * @param toAppendTo the string buffer for the returning time string. 302 * @return the string buffer passed in as toAppendTo, with formatted text appended. 303 * @param fieldPosition keeps track of the position of the field 304 * within the returned string. 305 * On input: an alignment field, 306 * if desired. On output: the offsets of the alignment field. For 307 * example, given a time text "1996.07.10 AD at 15:08:56 PDT", 308 * if the given fieldPosition is DateFormat.YEAR_FIELD, the 309 * begin index and end index of fieldPosition will be set to 310 * 0 and 4, respectively. 311 * Notice that if the same time field appears 312 * more than once in a pattern, the fieldPosition will be set for the first 313 * occurrence of that time field. For instance, formatting a Date to 314 * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern 315 * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD, 316 * the begin index and end index of fieldPosition will be set to 317 * 5 and 8, respectively, for the first occurrence of the timezone 318 * pattern character 'z'. 319 * @exception IllegalArgumentException if the {@code Format} cannot format 320 * the given {@code obj}. 321 * @see java.text.Format 322 */ 323 public final StringBuffer format(Object obj, StringBuffer toAppendTo, 324 FieldPosition fieldPosition) 325 { 326 if (obj instanceof Date) 327 return format( (Date)obj, toAppendTo, fieldPosition ); 328 else if (obj instanceof Number) 329 return format( new Date(((Number)obj).longValue()), 330 toAppendTo, fieldPosition ); 331 else 332 throw new IllegalArgumentException("Cannot format given Object as a Date"); 333 } 334 335 /** 336 * Formats a Date into a date/time string. 337 * @param date a Date to be formatted into a date/time string. 338 * @param toAppendTo the string buffer for the returning date/time string. 339 * @param fieldPosition keeps track of the position of the field 340 * within the returned string. 341 * On input: an alignment field, 342 * if desired. On output: the offsets of the alignment field. For 343 * example, given a time text "1996.07.10 AD at 15:08:56 PDT", 344 * if the given fieldPosition is DateFormat.YEAR_FIELD, the 345 * begin index and end index of fieldPosition will be set to 346 * 0 and 4, respectively. 347 * Notice that if the same time field appears 348 * more than once in a pattern, the fieldPosition will be set for the first 349 * occurrence of that time field. For instance, formatting a Date to 350 * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern 351 * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD, 352 * the begin index and end index of fieldPosition will be set to 353 * 5 and 8, respectively, for the first occurrence of the timezone 354 * pattern character 'z'. 355 * @return the string buffer passed in as toAppendTo, with formatted text appended. 356 */ 357 public abstract StringBuffer format(Date date, StringBuffer toAppendTo, 358 FieldPosition fieldPosition); 359 360 /** 361 * Formats a Date into a date/time string. 362 * @param date the time value to be formatted into a time string. 363 * @return the formatted time string. 364 */ 365 public final String format(Date date) 366 { 367 return format(date, new StringBuffer(), 368 DontCareFieldPosition.INSTANCE).toString(); 369 } 370 371 /** 372 * Parses text from the beginning of the given string to produce a date. 373 * The method may not use the entire text of the given string. 374 * <p> 375 * See the {@link #parse(String, ParsePosition)} method for more information 376 * on date parsing. 377 * 378 * @param source A <code>String</code> whose beginning should be parsed. 379 * @return A <code>Date</code> parsed from the string. 380 * @exception ParseException if the beginning of the specified string 381 * cannot be parsed. 382 */ 383 public Date parse(String source) throws ParseException | 277 * For example, 11:30 PM + 1 hour results in 12:30 AM. 278 */ 279 public static final int HOUR1_FIELD = 15; 280 /** 281 * Useful constant for zero-based HOUR field alignment. 282 * Used in FieldPosition of date/time formatting. 283 * HOUR0_FIELD is used for the zero-based 12-hour clock. 284 * For example, 11:30 PM + 1 hour results in 00:30 AM. 285 */ 286 public static final int HOUR0_FIELD = 16; 287 /** 288 * Useful constant for TIMEZONE field alignment. 289 * Used in FieldPosition of date/time formatting. 290 */ 291 public static final int TIMEZONE_FIELD = 17; 292 293 // Proclaim serial compatibility with 1.1 FCS 294 private static final long serialVersionUID = 7218322306649953788L; 295 296 /** 297 * Formats the given {@code Object} into a date-time string. The formatted 298 * string is appended to the given {@code StringBuffer}. 299 * 300 * @param obj Must be a {@code Date} or a {@code Number} representing a 301 * millisecond offset from the <a href="../util/Calendar.html#Epoch">Epoch</a>. 302 * @param toAppendTo The string buffer for the returning date-time string. 303 * @param fieldPosition keeps track on the position of the field within 304 * the returned string. For example, given a date-time text 305 * {@code "1996.07.10 AD at 15:08:56 PDT"}, if the given {@code fieldPosition} 306 * is {@link DateFormat#YEAR_FIELD}, the begin index and end index of 307 * {@code fieldPosition} will be set to 0 and 4, respectively. 308 * Notice that if the same date-time field appears more than once in a 309 * pattern, the {@code fieldPosition} will be set for the first occurrence 310 * of that date-time field. For instance, formatting a {@code Date} to the 311 * date-time string {@code "1 PM PDT (Pacific Daylight Time)"} using the 312 * pattern {@code "h a z (zzzz)"} and the alignment field 313 * {@link DateFormat#TIMEZONE_FIELD}, the begin index and end index of 314 * {@code fieldPosition} will be set to 5 and 8, respectively, for the 315 * first occurrence of the timezone pattern character {@code 'z'}. 316 * @return the string buffer passed in as {@code toAppendTo}, 317 * with formatted text appended. 318 * @exception IllegalArgumentException if the {@code Format} cannot format 319 * the given {@code obj}. 320 * @see java.text.Format 321 */ 322 public final StringBuffer format(Object obj, StringBuffer toAppendTo, 323 FieldPosition fieldPosition) 324 { 325 if (obj instanceof Date) 326 return format( (Date)obj, toAppendTo, fieldPosition ); 327 else if (obj instanceof Number) 328 return format( new Date(((Number)obj).longValue()), 329 toAppendTo, fieldPosition ); 330 else 331 throw new IllegalArgumentException("Cannot format given Object as a Date"); 332 } 333 334 /** 335 * Formats a {@link Date} into a date-time string. The formatted 336 * string is appended to the given {@code StringBuffer}. 337 * 338 * @param date a Date to be formatted into a date-time string. 339 * @param toAppendTo the string buffer for the returning date-time string. 340 * @param fieldPosition keeps track on the position of the field within 341 * the returned string. For example, given a date-time text 342 * {@code "1996.07.10 AD at 15:08:56 PDT"}, if the given {@code fieldPosition} 343 * is {@link DateFormat#YEAR_FIELD}, the begin index and end index of 344 * {@code fieldPosition} will be set to 0 and 4, respectively. 345 * Notice that if the same date-time field appears more than once in a 346 * pattern, the {@code fieldPosition} will be set for the first occurrence 347 * of that date-time field. For instance, formatting a {@code Date} to the 348 * date-time string {@code "1 PM PDT (Pacific Daylight Time)"} using the 349 * pattern {@code "h a z (zzzz)"} and the alignment field 350 * {@link DateFormat#TIMEZONE_FIELD}, the begin index and end index of 351 * {@code fieldPosition} will be set to 5 and 8, respectively, for the 352 * first occurrence of the timezone pattern character {@code 'z'}. 353 * @return the string buffer passed in as {@code toAppendTo}, with formatted 354 * text appended. 355 */ 356 public abstract StringBuffer format(Date date, StringBuffer toAppendTo, 357 FieldPosition fieldPosition); 358 359 /** 360 * Formats a {@link Date} into a date-time string. 361 * 362 * @param date the time value to be formatted into a date-time string. 363 * @return the formatted date-time string. 364 */ 365 public final String format(Date date) 366 { 367 return format(date, new StringBuffer(), 368 DontCareFieldPosition.INSTANCE).toString(); 369 } 370 371 /** 372 * Parses text from the beginning of the given string to produce a date. 373 * The method may not use the entire text of the given string. 374 * <p> 375 * See the {@link #parse(String, ParsePosition)} method for more information 376 * on date parsing. 377 * 378 * @param source A <code>String</code> whose beginning should be parsed. 379 * @return A <code>Date</code> parsed from the string. 380 * @exception ParseException if the beginning of the specified string 381 * cannot be parsed. 382 */ 383 public Date parse(String source) throws ParseException |