Summary

Introduce public StringBuilder overloads for the formatting methods of java.text.Format and its implementing subclasses.

Problem

Format and its implementing subclasses define StringBuffer formatting methods, but do not have StringBuilder overloads since the classes predate StringBuilder. Synchronization is not a concern, as the Format classes are not synchronized.

Providing these overloads would allow for improved performance. In fact, the efforts done in JDK-8333396 lay the ground work to introduce new public API in this regard.

Solution

As Format, NumberFormat, and DateFormat are abstract, we cannot add these new overloads as abstract methods due to compatibility concerns. Instead, at the abstract class level, introduce these methods with a thrown exception as the default implementation, and specify that subclasses should override this method. At the implementing class level, such as DecimalFormat, introduce these methods with an implementation.

Beyond that, the general specification of the new methods follows the original StringBuffer version.

Specification

For further clarity, I have added the default implementation for the methods at the abstract class level.

In ChoiceFormat,

+    /**
+     * Specialization of format. This method really calls
+     * {@link #format(double, StringBuilder, FieldPosition)}.
+     * Thus, the range of longs that are supported is only equal to
+     * the range that can be stored by double. This will never be
+     * a practical limitation.
+     *
+     * @param number number to be formatted and substituted.
+     * @param toAppendTo where text is appended.
+     * @param status ignore no useful status is returned.
+     * @throws    ArrayIndexOutOfBoundsException if either the {@code limits}
+     *            or {@code formats} of this ChoiceFormat are empty
+     * @throws    NullPointerException if {@code toAppendTo}
+     *            is {@code null}
+     * @since 24
+     */
+    @Override
+    public StringBuilder format(long number,
+                                StringBuilder toAppendTo,
+                                FieldPosition status) {

+    /**
+     * Returns pattern with formatted double.
+     *
+     * @param number number to be formatted and substituted.
+     * @param toAppendTo where text is appended.
+     * @param status ignore no useful status is returned.
+     * @throws    ArrayIndexOutOfBoundsException if either the {@code limits}
+     *            or {@code formats} of this ChoiceFormat are empty
+     * @throws    NullPointerException if {@code toAppendTo}
+     *            is {@code null}
+     * @since 24
+     */
+    @Override
+    public StringBuilder format(double number,
+                                StringBuilder toAppendTo,
+                                FieldPosition status) {

In CompactNumberFormat,

+    /**
+     * Formats a number to produce a string representing its compact form.
+     * The number can be of any subclass of {@link java.lang.Number}.
+     * @param number     the number to format
+     * @param toAppendTo the {@code StringBuilder} to which the formatted
+     *                   text is to be appended
+     * @param fieldPosition    keeps track on the position of the field within
+     *                         the returned string. For example, for formatting
+     *                         a number {@code 123456789} in the
+     *                         {@link java.util.Locale#US US locale},
+     *                         if the given {@code fieldPosition} is
+     *                         {@link NumberFormat#INTEGER_FIELD}, the begin
+     *                         index and end index of {@code fieldPosition}
+     *                         will be set to 0 and 3, respectively for the
+     *                         output string {@code 123M}. Similarly, positions
+     *                         of the prefix and the suffix fields can be
+     *                         obtained using {@link NumberFormat.Field#PREFIX}
+     *                         and {@link NumberFormat.Field#SUFFIX} respectively.
+     * @return           the {@code StringBuilder} passed in as {@code toAppendTo}
+     * @throws           IllegalArgumentException if {@code number} is
+     *                   {@code null} or not an instance of {@code Number}
+     * @throws           NullPointerException if {@code toAppendTo} or
+     *                   {@code fieldPosition} is {@code null}
+     * @throws           ArithmeticException if rounding is needed with rounding
+     *                   mode being set to {@code RoundingMode.UNNECESSARY}
+     * @see              FieldPosition
+     * @since 24
+     */
+    @Override
+    public final StringBuilder format(Object number,
+                                     StringBuilder toAppendTo,
+                                     FieldPosition fieldPosition) {


+    /**
+     * Formats a double to produce a string representing its compact form.
+     * @param number    the double number to format
+     * @param result    where the text is to be appended
+     * @param fieldPosition    keeps track on the position of the field within
+     *                         the returned string. For example, to format
+     *                         a number {@code 1234567.89} in the
+     *                         {@link java.util.Locale#US US locale}
+     *                         if the given {@code fieldPosition} is
+     *                         {@link NumberFormat#INTEGER_FIELD}, the begin
+     *                         index and end index of {@code fieldPosition}
+     *                         will be set to 0 and 1, respectively for the
+     *                         output string {@code 1M}. Similarly, positions
+     *                         of the prefix and the suffix fields can be
+     *                         obtained using {@link NumberFormat.Field#PREFIX}
+     *                         and {@link NumberFormat.Field#SUFFIX} respectively.
+     * @return    the {@code StringBuilder} passed in as {@code result}
+     * @throws NullPointerException if {@code result} or
+     *            {@code fieldPosition} is {@code null}
+     * @throws ArithmeticException if rounding is needed with rounding
+     *            mode being set to {@code RoundingMode.UNNECESSARY}
+     * @see FieldPosition
+     * @since 24
+     */
+    @Override
+    public StringBuilder format(double number, StringBuilder result,
+                               FieldPosition fieldPosition) {

+    /**
+     * Formats a long to produce a string representing its compact form.
+     * @param number    the long number to format
+     * @param result    where the text is to be appended
+     * @param fieldPosition    keeps track on the position of the field within
+     *                         the returned string. For example, to format
+     *                         a number {@code 123456789} in the
+     *                         {@link java.util.Locale#US US locale},
+     *                         if the given {@code fieldPosition} is
+     *                         {@link NumberFormat#INTEGER_FIELD}, the begin
+     *                         index and end index of {@code fieldPosition}
+     *                         will be set to 0 and 3, respectively for the
+     *                         output string {@code 123M}. Similarly, positions
+     *                         of the prefix and the suffix fields can be
+     *                         obtained using {@link NumberFormat.Field#PREFIX}
+     *                         and {@link NumberFormat.Field#SUFFIX} respectively.
+     * @return       the {@code StringBuilder} passed in as {@code result}
+     * @throws       NullPointerException if {@code result} or
+     *               {@code fieldPosition} is {@code null}
+     * @throws       ArithmeticException if rounding is needed with rounding
+     *               mode being set to {@code RoundingMode.UNNECESSARY}
+     * @see FieldPosition
+     * @since 24
+     */
+    @Override
+    public StringBuilder format(long number, StringBuilder result,
+                               FieldPosition fieldPosition) {

In DateFormat,

+    /**
+     * Formats the given {@code Object} into a date-time string. The formatted
+     * string is appended to the given {@code StringBuilder}.
+     *
+     * @apiNote Subclasses should override {@link #format(Date, StringBuilder, FieldPosition)}
+     * to support this operation.
+     * @implSpec This implementation calls {@link #format(Date, StringBuilder, FieldPosition)},
+     * which by default throws always throws {@code UnsupportedOperationException}.
+     * @param obj Must be a {@code Date} or a {@code Number} representing a
+     * millisecond offset from the <a href="../util/Calendar.html#Epoch">Epoch</a>.
+     * @param toAppendTo The string builder for the returning date-time string.
+     * @param fieldPosition keeps track on the position of the field within
+     * the returned 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 date-time field appears more than once in a
+     * pattern, the {@code fieldPosition} will be set for the first occurrence
+     * of that date-time field. For instance, formatting a {@code Date} to the
+     * date-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
+     * {@code fieldPosition} will be set to 5 and 8, respectively, for the
+     * first occurrence of the timezone pattern character {@code 'z'}.
+     * @return the string builder passed in as {@code toAppendTo},
+     *         with formatted text appended.
+     * @throws    IllegalArgumentException if the {@code Format} cannot format
+     *            the given {@code obj}.
+     * @throws    UnsupportedOperationException if the implementation of this
+     *            method does not support this operation
+     * @see java.text.Format
+     * @since 24
+     */
+    @Override
+    public final StringBuilder format(Object obj, StringBuilder toAppendTo,
+                                     FieldPosition fieldPosition) {


+    /**
+     * Formats a {@link Date} into a date-time string. The formatted
+     * string is appended to the given {@code StringBuilder}.
+     *
+     * @apiNote Subclasses should override this method to support this operation.
+     * @implSpec The default implementation always throws {@code
+     * UnsupportedOperationException}.
+     * @param date a Date to be formatted into a date-time string.
+     * @param toAppendTo the string builder for the returning date-time string.
+     * @param fieldPosition keeps track on the position of the field within
+     * the returned 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 date-time field appears more than once in a
+     * pattern, the {@code fieldPosition} will be set for the first occurrence
+     * of that date-time field. For instance, formatting a {@code Date} to the
+     * date-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
+     * {@code fieldPosition} will be set to 5 and 8, respectively, for the
+     * first occurrence of the timezone pattern character {@code 'z'}.
+     * @return the string builder passed in as {@code toAppendTo}, with formatted
+     * text appended.
+     * @throws    UnsupportedOperationException if the implementation of this
+     *            method does not support this operation
+     * @since 24
+     */
+    public StringBuilder format(Date date, StringBuilder toAppendTo,
+                                FieldPosition fieldPosition) {
+        throw new UnsupportedOperationException("Subclasses should override this method");

In DecimalFormat,

+    /**
+     * Formats a number and appends the resulting text to the given string
+     * builder.
+     * The number can be of any subclass of {@link java.lang.Number}.
+     *
+     * This implementation uses the maximum precision permitted.
+     * @param number     the number to format
+     * @param toAppendTo the {@code StringBuilder} to which the formatted
+     *                   text is to be appended
+     * @param pos        keeps track on the position of the field within the
+     *                   returned string. For example, for formatting a number
+     *                   {@code 1234567.89} in {@code Locale.US} locale,
+     *                   if the given {@code fieldPosition} is
+     *                   {@link NumberFormat#INTEGER_FIELD}, the begin index
+     *                   and end index of {@code fieldPosition} will be set
+     *                   to 0 and 9, respectively for the output string
+     *                   {@code 1,234,567.89}.
+     * @return           the value passed in as {@code toAppendTo}
+     * @throws           IllegalArgumentException if {@code number} is
+     *                   null or not an instance of {@code Number}.
+     * @throws           NullPointerException if {@code toAppendTo} or
+     *                   {@code pos} is null
+     * @throws           ArithmeticException if rounding is needed with rounding
+     *                   mode being set to RoundingMode.UNNECESSARY
+     * @see              java.text.FieldPosition
+     * @since 24
+     */
+    @Override
+    public final StringBuilder format(Object number,
+                               StringBuilder toAppendTo,
+                               FieldPosition pos) {


+    /**
+     * Formats a double to produce a string.
+     * @param number    The double to format
+     * @param result    where the text is to be appended
+     * @param fieldPosition    keeps track on the position of the field within
+     *                         the returned string. For example, for formatting
+     *                         a number {@code 1234567.89} in {@code Locale.US}
+     *                         locale, if the given {@code fieldPosition} is
+     *                         {@link NumberFormat#INTEGER_FIELD}, the begin index
+     *                         and end index of {@code fieldPosition} will be set
+     *                         to 0 and 9, respectively for the output string
+     *                         {@code 1,234,567.89}.
+     * @throws    NullPointerException if {@code result} or
+     *            {@code fieldPosition} is {@code null}
+     * @throws    ArithmeticException if rounding is needed with rounding
+     *            mode being set to RoundingMode.UNNECESSARY
+     * @return The formatted number string
+     * @see java.text.FieldPosition
+     * @since 24
+     */
+    @Override
+    public StringBuilder format(double number, StringBuilder result,
+                               FieldPosition fieldPosition) {


+    /**
+     * Format a long to produce a string.
+     * @param number    The long to format
+     * @param result    where the text is to be appended
+     * @param fieldPosition    keeps track on the position of the field within
+     *                         the returned string. For example, for formatting
+     *                         a number {@code 123456789} in {@code Locale.US}
+     *                         locale, if the given {@code fieldPosition} is
+     *                         {@link NumberFormat#INTEGER_FIELD}, the begin index
+     *                         and end index of {@code fieldPosition} will be set
+     *                         to 0 and 11, respectively for the output string
+     *                         {@code 123,456,789}.
+     * @throws          NullPointerException if {@code result} or
+     *                  {@code fieldPosition} is {@code null}
+     * @throws          ArithmeticException if rounding is needed with rounding
+     *                  mode being set to RoundingMode.UNNECESSARY
+     * @return The formatted number string
+     * @see java.text.FieldPosition
+     * @since 24
+     */
+    @Override
+    public StringBuilder format(long number, StringBuilder result,
+                               FieldPosition fieldPosition) {

In Format,

+    /**
+     * Formats an object and appends the resulting text to a given string
+     * builder.
+     * If the {@code pos} argument identifies a field used by the format,
+     * then its indices are set to the beginning and end of the first such
+     * field encountered.
+     *
+     * @apiNote Subclasses should override this method to support this operation.
+     * @implSpec The default implementation always throws {@code
+     * UnsupportedOperationException}.
+     * @param obj    The object to format
+     * @param toAppendTo    where the text is to be appended
+     * @param pos    A {@code FieldPosition} identifying a field
+     *               in the formatted text
+     * @return       the string builder passed in as {@code toAppendTo},
+     *               with formatted text appended
+     * @throws    NullPointerException if {@code toAppendTo} or
+     *            {@code pos} is null
+     * @throws    IllegalArgumentException if the Format cannot format the given
+     *            object
+     * @throws    UnsupportedOperationException if the implementation of this
+     *            method does not support this operation
+     * @since 24
+     */
+    public StringBuilder format(Object obj,
+                                StringBuilder toAppendTo,
+                                FieldPosition pos) {
+       throw new UnsupportedOperationException("Subclasses should override this method");

In ListFormat,

+    /**
+     * Formats an object and appends the resulting text to a given string
+     * builder. The object should either be a List or an array of Objects.
+     *
+     * @apiNote Formatting the string from an excessively long list or array
+     *          may exceed memory or string sizes.
+     * @param obj    The object to format. Must be a List or an array
+     *               of Object.
+     * @param toAppendTo    where the text is to be appended
+     * @param pos    Ignored. Not used in ListFormat. May be null
+     * @return       the string builder passed in as {@code toAppendTo},
+     *               with formatted text appended
+     * @throws    NullPointerException if {@code obj} or {@code toAppendTo} is null
+     * @throws    IllegalArgumentException if {@code obj} is neither a {@code List}
+     *               nor an array of {@code Object}s, or its length is zero.
+     * @since 24
+     */
+    @Override
+    public StringBuilder format(Object obj, StringBuilder toAppendTo, FieldPosition pos) {

In MessageFormat,

+    /**
+     * Formats an array of objects and appends the {@code MessageFormat}'s
+     * pattern, with format elements replaced by the formatted objects, to the
+     * provided {@code StringBuilder}.
+     * <p>
+     * The text substituted for the individual format elements is derived from
+     * the current subformat of the format element and the
+     * {@code arguments} element at the format element's argument index
+     * as indicated by the first matching line of the following table. An
+     * argument is <i>unavailable</i> if {@code arguments} is
+     * {@code null} or has fewer than argumentIndex+1 elements.
+     * Refer to the following {@link ##text_derivation_table table} for a more
+     * detailed view of this derivation.
+     * <p>
+     * If {@code pos} is non-null, and refers to
+     * {@code Field.ARGUMENT}, the location of the first formatted
+     * string will be returned.
+     *
+     * @param arguments an array of objects to be formatted and substituted.
+     * @param result where text is appended.
+     * @param pos keeps track on the position of the first replaced argument
+     *            in the output string.
+     * @return the string builder passed in as {@code result}, with formatted
+     * text appended
+     * @throws    IllegalArgumentException if an argument in the
+     *            {@code arguments} array is not of the type
+     *            expected by the format element(s) that use it.
+     * @throws    NullPointerException if {@code result} is {@code null} or
+     *            if the {@code MessageFormat} instance that calls this method
+     *            has locale set to null, and the implementation
+     *            uses a locale-dependent subformat.
+     * @since 24
+     */
+    public final StringBuilder format(Object[] arguments, StringBuilder result,
+                                     FieldPosition pos)
+    {


+    /**
+     * Formats an array of objects and appends the {@code MessageFormat}'s
+     * pattern, with format elements replaced by the formatted objects, to the
+     * provided {@code StringBuilder}.
+     * This is equivalent to
+     * <blockquote>
+     *     <code>{@link #format(java.lang.Object[], java.lang.StringBuilder, java.text.FieldPosition) format}((Object[]) arguments, result, pos)</code>
+     * </blockquote>
+     *
+     * @param arguments an array of objects to be formatted and substituted.
+     * @param result where text is appended.
+     * @param pos keeps track on the position of the first replaced argument
+     *            in the output string.
+     * @throws    IllegalArgumentException if an argument in the
+     *            {@code arguments} array is not of the type
+     *            expected by the format element(s) that use it.
+     * @throws    NullPointerException if {@code result} is {@code null} or
+     *            if the {@code MessageFormat} instance that calls this method
+     *            has locale set to null, and the implementation
+     *            uses a locale-dependent subformat.
+     * @since 24
+     */
+    @Override
+    public final StringBuilder format(Object arguments, StringBuilder result,
+                                     FieldPosition pos)
+    {

In NumberFormat,

+    /**
+     * Formats a number and appends the resulting text to the given string
+     * builder.
+     * The number can be of any subclass of {@link java.lang.Number}.
+     *
+     * @apiNote Subclasses should override {@link #format(long,
+     * java.lang.StringBuilder, java.text.FieldPosition)} and {@link #format(double,
+     * java.lang.StringBuilder, java.text.FieldPosition)} to support this operation.
+     * @implSpec This implementation may call {@link #format(long,
+     * java.lang.StringBuilder, java.text.FieldPosition)} or {@link #format(double,
+     * java.lang.StringBuilder, java.text.FieldPosition)}, which by default always
+     * throws {@code UnsupportedOperationException}.
+     * Additionally, this implementation extracts the number's value using
+     * {@link java.lang.Number#longValue()} for all integral type values that
+     * can be converted to {@code long} without loss of information,
+     * including {@code BigInteger} values with a
+     * {@link java.math.BigInteger#bitLength() bit length} of less than 64,
+     * and {@link java.lang.Number#doubleValue()} for all other types. It
+     * then calls {@link #format(long,java.lang.StringBuilder,java.text.FieldPosition)}
+     * or {@link #format(double,java.lang.StringBuilder,java.text.FieldPosition)}.
+     * This may result in loss of magnitude information and precision for
+     * {@code BigInteger} and {@code BigDecimal} values.
+     * @param number     the number to format
+     * @param toAppendTo the {@code StringBuilder} to which the formatted
+     *                   text is to be appended
+     * @param pos        keeps track on the position of the field within the
+     *                   returned string. For example, for formatting a number
+     *                   {@code 1234567.89} in {@code Locale.US} locale,
+     *                   if the given {@code fieldPosition} is
+     *                   {@link NumberFormat#INTEGER_FIELD}, the begin index
+     *                   and end index of {@code fieldPosition} will be set
+     *                   to 0 and 9, respectively for the output string
+     *                   {@code 1,234,567.89}.
+     * @return           the value passed in as {@code toAppendTo}
+     * @throws           IllegalArgumentException if {@code number} is
+     *                   null or not an instance of {@code Number}.
+     * @throws           NullPointerException if {@code toAppendTo} or
+     *                   {@code pos} is null
+     * @throws           ArithmeticException if rounding is needed with rounding
+     *                   mode being set to RoundingMode.UNNECESSARY
+     * @throws           UnsupportedOperationException if the implementation of this
+     *                   method does not support this operation
+     * @see              java.text.FieldPosition
+     * @since 24
+     */
+    @Override
+    public StringBuilder format(Object number,
+                               StringBuilder toAppendTo,
+                               FieldPosition pos) {


+    /**
+     * Specialization of format.
+     *
+     * @apiNote Subclasses should override this method to support this operation.
+     * @implSpec The default implementation always throws {@code
+     * UnsupportedOperationException}.
+     * @param number     the double number to format
+     * @param toAppendTo the StringBuilder to which the formatted text is to be
+     *                   appended
+     * @param pos        keeps track on the position of the field within the
+     *                   returned string. For example, for formatting a number
+     *                   {@code 1234567.89} in {@code Locale.US} locale,
+     *                   if the given {@code fieldPosition} is
+     *                   {@link NumberFormat#INTEGER_FIELD}, the begin index
+     *                   and end index of {@code fieldPosition} will be set
+     *                   to 0 and 9, respectively for the output string
+     *                   {@code 1,234,567.89}.
+     * @return           the formatted StringBuilder
+     * @throws           ArithmeticException if rounding is needed with rounding
+     *                   mode being set to RoundingMode.UNNECESSARY
+     * @throws           UnsupportedOperationException if the implementation of this
+     *                   method does not support this operation
+     * @see java.text.Format#format
+     * @since 24
+     */
+    public StringBuilder format(double number,
+                                StringBuilder toAppendTo,
+                                FieldPosition pos) {
+       throw new UnsupportedOperationException("Subclasses should override this method");


+    /**
+     * Specialization of format.
+     *
+     * @apiNote Subclasses should override this method to support this operation.
+     * @implSpec The default implementation always throws {@code
+     * UnsupportedOperationException}.
+     * @param number     the long number to format
+     * @param toAppendTo the StringBuilder to which the formatted text is to be
+     *                   appended
+     * @param pos        keeps track on the position of the field within the
+     *                   returned string. For example, for formatting a number
+     *                   {@code 123456789} in {@code Locale.US} locale,
+     *                   if the given {@code fieldPosition} is
+     *                   {@link NumberFormat#INTEGER_FIELD}, the begin index
+     *                   and end index of {@code fieldPosition} will be set
+     *                   to 0 and 11, respectively for the output string
+     *                   {@code 123,456,789}.
+     * @return           the formatted StringBuilder
+     * @throws           ArithmeticException if rounding is needed with rounding
+     *                   mode being set to RoundingMode.UNNECESSARY
+     * @throws           UnsupportedOperationException if the implementation of this
+     *                   method does not support this operation
+     * @see java.text.Format#format
+     * @since 24
+     */
+    public StringBuilder format(long number,
+                                StringBuilder toAppendTo,
+                                FieldPosition pos) {
+       throw new UnsupportedOperationException("Subclasses should override this method");

In SimpleDateFormat,

+    /**
+     * Formats the given {@code Date} into a date/time string and appends
+     * the result to the given {@code StringBuilder}.
+     *
+     * @param date the date-time value to be formatted into a date-time string.
+     * @param toAppendTo where the new date-time text is to be appended.
+     * @param pos keeps track on the position of the field within
+     * the returned 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 date-time field appears more than once in a
+     * pattern, the {@code fieldPosition} will be set for the first occurrence
+     * of that date-time field. For instance, formatting a {@code Date} to the
+     * date-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
+     * {@code fieldPosition} will be set to 5 and 8, respectively, for the
+     * first occurrence of the timezone pattern character {@code 'z'}.
+     * @return the formatted date-time string.
+     * @throws    NullPointerException if any of the parameters is {@code null}.
+     * @since 24
+     */
+    @Override
+    public StringBuilder format(Date date, StringBuilder toAppendTo,
+                               FieldPosition pos) {