{@code obj} must be a {@link Date} or a {@link Number} represending a + * millisecond offset from the Epoch. + * If {@code obj} is a {@code Number}, a {@code Date} is created with the + * {@code long} value of the {@code Number} and {@link + * #format(Date,StringBuffer,FieldPosition)} is called. If {@code obj} is a + * {@code Date}, {@link #format(Date,StringBuffer,FieldPosition)} is called. + * + *
{@code fieldPosition} specifies the field to track its position + * information in the formatted string. For example, given a date-time text + * {@code "1996.07.10 AD at 15:08:56 PDT"}, if the given {@code + * fieldPosition} is {@link DateFormat#YEAR_FIELD}, the begin index and end + * index of {@code fieldPosition} will be set to 0 and 4, respectively. + * Notice that if the same time field appears more than once in a pattern, + * the {@code fieldPosition} will be set for the first occurrence of that + * time field. For instance, formatting a {@code Date} to the time string + * {@code "1 PM PDT (Pacific Daylight Time)"} using the pattern {@code "h a + * z (zzzz)"} and the alignment field {@link DateFormat#TIMEZONE_FIELD}, the + * begin index and end index of fieldPosition will be set to 5 and 8, + * respectively, for the first occurrence of the timezone pattern character + * {@code 'z'}. + * + * @param obj must be a {@code Number} or a {@code Date}. + * @param toAppendTo the string buffer for the returning date-time string. + * @param fieldPosition the field for which the position information is + * set upon return. + * @return the string buffer passed in as {@code toAppendTo}, + * with formatted text appended. + * @throws IllegalArgumentException if {@code obj} is neither a {@code Number} + * nor a {@code Date} + * @see Format */ public final StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition fieldPosition) { - if (obj instanceof Date) - return format( (Date)obj, toAppendTo, fieldPosition ); - else if (obj instanceof Number) - return format( new Date(((Number)obj).longValue()), - toAppendTo, fieldPosition ); - else + if (obj instanceof Date) { + return format((Date) obj, toAppendTo, fieldPosition); + } + if (obj instanceof Number) { + return format(new Date(((Number) obj).longValue()), + toAppendTo, fieldPosition); + } throw new IllegalArgumentException("Cannot format given Object as a Date"); } /** - * Formats a Date into a date/time string. + * Formats a {@link Date} into a date-time string. The formatted + * string is appended to the given {@code StringBuffer}. + * + *
{@code fieldPosition} specifies the field to track its position + * information in the formatted string. For example, given a date-time text + * {@code "1996.07.10 AD at 15:08:56 PDT"}, if the given {@code + * fieldPosition} is {@link DateFormat#YEAR_FIELD}, the begin index and end + * index of {@code fieldPosition} will be set to 0 and 4, respectively. + * Notice that if the same time field appears more than once in a pattern, + * the {@code fieldPosition} will be set for the first occurrence of that + * time field. For instance, formatting a {@code Date} to the time string + * {@code "1 PM PDT (Pacific Daylight Time)"} using the pattern {@code "h a + * z (zzzz)"} and the alignment field {@link DateFormat#TIMEZONE_FIELD}, the + * begin index and end index of fieldPosition will be set to 5 and 8, + * respectively, for the first occurrence of the timezone pattern character + * {@code 'z'}. + * * @param date a Date to be formatted into a date/time string. * @param toAppendTo the string buffer for the returning date/time string. * @param fieldPosition keeps track of the position of the field * within the returned string. - * On input: an alignment field, - * if desired. On output: the offsets of the alignment field. For - * example, given a time text "1996.07.10 AD at 15:08:56 PDT", - * if the given fieldPosition is DateFormat.YEAR_FIELD, the - * begin index and end index of fieldPosition will be set to - * 0 and 4, respectively. - * Notice that if the same time field appears - * more than once in a pattern, the fieldPosition will be set for the first - * occurrence of that time field. For instance, formatting a Date to - * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern - * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD, - * the begin index and end index of fieldPosition will be set to - * 5 and 8, respectively, for the first occurrence of the timezone - * pattern character 'z'. * @return the string buffer passed in as toAppendTo, with formatted text appended. */ public abstract StringBuffer format(Date date, StringBuffer toAppendTo, FieldPosition fieldPosition); /** - * Formats a Date into a date/time string. - * @param date the time value to be formatted into a time string. - * @return the formatted time string. + * Formats a {@link Date} into a date-time string. + * + * @param date the time value to be formatted into a date-time string. + * @return the formatted date-time string. */ public final String format(Date date) {