133 * bundle source files) which strings will be processed by {@code MessageFormat}.
134 * Note that localizers may need to use single quotes in translated
135 * strings where the original version doesn't have them.
136 * </dl>
137 * <p>
138 * The <i>ArgumentIndex</i> value is a non-negative integer written
139 * using the digits {@code '0'} through {@code '9'}, and represents an index into the
140 * {@code arguments} array passed to the {@code format} methods
141 * or the result array returned by the {@code parse} methods.
142 * <p>
143 * The <i>FormatType</i> and <i>FormatStyle</i> values are used to create
144 * a {@code Format} instance for the format element. The following
145 * table shows how the values map to {@code Format} instances. Combinations not
146 * shown in the table are illegal. A <i>SubformatPattern</i> must
147 * be a valid pattern string for the {@code Format} subclass used.
148 *
149 * <table class="plain">
150 * <caption style="display:none">Shows how FormatType and FormatStyle values map to Format instances</caption>
151 * <thead>
152 * <tr>
153 * <th id="ft" class="TableHeadingColor">FormatType
154 * <th id="fs" class="TableHeadingColor">FormatStyle
155 * <th id="sc" class="TableHeadingColor">Subformat Created
156 * </thead>
157 * <tbody>
158 * <tr>
159 * <td headers="ft"><i>(none)</i>
160 * <td headers="fs"><i>(none)</i>
161 * <td headers="sc"><code>null</code>
162 * <tr>
163 * <td headers="ft" rowspan=5><code>number</code>
164 * <td headers="fs"><i>(none)</i>
165 * <td headers="sc">{@link NumberFormat#getInstance(Locale) NumberFormat.getInstance}{@code (getLocale())}
166 * <tr>
167 * <td headers="fs"><code>integer</code>
168 * <td headers="sc">{@link NumberFormat#getIntegerInstance(Locale) NumberFormat.getIntegerInstance}{@code (getLocale())}
169 * <tr>
170 * <td headers="fs"><code>currency</code>
171 * <td headers="sc">{@link NumberFormat#getCurrencyInstance(Locale) NumberFormat.getCurrencyInstance}{@code (getLocale())}
172 * <tr>
173 * <td headers="fs"><code>percent</code>
174 * <td headers="sc">{@link NumberFormat#getPercentInstance(Locale) NumberFormat.getPercentInstance}{@code (getLocale())}
175 * <tr>
176 * <td headers="fs"><i>SubformatPattern</i>
177 * <td headers="sc">{@code new} {@link DecimalFormat#DecimalFormat(String,DecimalFormatSymbols) DecimalFormat}{@code (subformatPattern,} {@link DecimalFormatSymbols#getInstance(Locale) DecimalFormatSymbols.getInstance}{@code (getLocale()))}
178 * <tr>
179 * <td headers="ft" rowspan=6><code>date</code>
180 * <td headers="fs"><i>(none)</i>
181 * <td headers="sc">{@link DateFormat#getDateInstance(int,Locale) DateFormat.getDateInstance}{@code (}{@link DateFormat#DEFAULT}{@code , getLocale())}
182 * <tr>
183 * <td headers="fs"><code>short</code>
184 * <td headers="sc">{@link DateFormat#getDateInstance(int,Locale) DateFormat.getDateInstance}{@code (}{@link DateFormat#SHORT}{@code , getLocale())}
185 * <tr>
186 * <td headers="fs"><code>medium</code>
187 * <td headers="sc">{@link DateFormat#getDateInstance(int,Locale) DateFormat.getDateInstance}{@code (}{@link DateFormat#DEFAULT}{@code , getLocale())}
188 * <tr>
189 * <td headers="fs"><code>long</code>
190 * <td headers="sc">{@link DateFormat#getDateInstance(int,Locale) DateFormat.getDateInstance}{@code (}{@link DateFormat#LONG}{@code , getLocale())}
191 * <tr>
192 * <td headers="fs"><code>full</code>
193 * <td headers="sc">{@link DateFormat#getDateInstance(int,Locale) DateFormat.getDateInstance}{@code (}{@link DateFormat#FULL}{@code , getLocale())}
194 * <tr>
195 * <td headers="fs"><i>SubformatPattern</i>
196 * <td headers="sc">{@code new} {@link SimpleDateFormat#SimpleDateFormat(String,Locale) SimpleDateFormat}{@code (subformatPattern, getLocale())}
197 * <tr>
198 * <td headers="ft" rowspan=6><code>time</code>
199 * <td headers="fs"><i>(none)</i>
200 * <td headers="sc">{@link DateFormat#getTimeInstance(int,Locale) DateFormat.getTimeInstance}{@code (}{@link DateFormat#DEFAULT}{@code , getLocale())}
201 * <tr>
202 * <td headers="fs"><code>short</code>
203 * <td headers="sc">{@link DateFormat#getTimeInstance(int,Locale) DateFormat.getTimeInstance}{@code (}{@link DateFormat#SHORT}{@code , getLocale())}
204 * <tr>
205 * <td headers="fs"><code>medium</code>
206 * <td headers="sc">{@link DateFormat#getTimeInstance(int,Locale) DateFormat.getTimeInstance}{@code (}{@link DateFormat#DEFAULT}{@code , getLocale())}
207 * <tr>
208 * <td headers="fs"><code>long</code>
209 * <td headers="sc">{@link DateFormat#getTimeInstance(int,Locale) DateFormat.getTimeInstance}{@code (}{@link DateFormat#LONG}{@code , getLocale())}
210 * <tr>
211 * <td headers="fs"><code>full</code>
212 * <td headers="sc">{@link DateFormat#getTimeInstance(int,Locale) DateFormat.getTimeInstance}{@code (}{@link DateFormat#FULL}{@code , getLocale())}
213 * <tr>
214 * <td headers="fs"><i>SubformatPattern</i>
215 * <td headers="sc">{@code new} {@link SimpleDateFormat#SimpleDateFormat(String,Locale) SimpleDateFormat}{@code (subformatPattern, getLocale())}
216 * <tr>
217 * <td headers="ft"><code>choice</code>
218 * <td headers="fs"><i>SubformatPattern</i>
219 * <td headers="sc">{@code new} {@link ChoiceFormat#ChoiceFormat(String) ChoiceFormat}{@code (subformatPattern)}
220 * </tbody>
221 * </table>
222 *
223 * <h4>Usage Information</h4>
224 *
225 * <p>
226 * Here are some examples of usage.
227 * In real internationalized programs, the message format pattern and other
228 * static strings will, of course, be obtained from resource bundles.
229 * Other parameters will be dynamically determined at runtime.
230 * <p>
231 * The first example uses the static method <code>MessageFormat.format</code>,
232 * which internally creates a <code>MessageFormat</code> for one-time use:
233 * <blockquote><pre>
234 * int planet = 7;
235 * String event = "a disturbance in the Force";
236 *
237 * String result = MessageFormat.format(
238 * "At {1,time} on {1,date}, there was {2} on planet {0,number,integer}.",
239 * planet, new Date(), event);
759 System.arraycopy(formats, 0, resultArray, 0, maxOffset + 1);
760 return resultArray;
761 }
762
763 /**
764 * Formats an array of objects and appends the <code>MessageFormat</code>'s
765 * pattern, with format elements replaced by the formatted objects, to the
766 * provided <code>StringBuffer</code>.
767 * <p>
768 * The text substituted for the individual format elements is derived from
769 * the current subformat of the format element and the
770 * <code>arguments</code> element at the format element's argument index
771 * as indicated by the first matching line of the following table. An
772 * argument is <i>unavailable</i> if <code>arguments</code> is
773 * <code>null</code> or has fewer than argumentIndex+1 elements.
774 *
775 * <table class="plain">
776 * <caption style="display:none">Examples of subformat,argument,and formatted text</caption>
777 * <thead>
778 * <tr>
779 * <th>Subformat
780 * <th>Argument
781 * <th>Formatted Text
782 * </thead>
783 * <tbody>
784 * <tr>
785 * <td><i>any</i>
786 * <td><i>unavailable</i>
787 * <td><code>"{" + argumentIndex + "}"</code>
788 * <tr>
789 * <td><i>any</i>
790 * <td><code>null</code>
791 * <td><code>"null"</code>
792 * <tr>
793 * <td><code>instanceof ChoiceFormat</code>
794 * <td><i>any</i>
795 * <td><code>subformat.format(argument).indexOf('{') >= 0 ?<br>
796 * (new MessageFormat(subformat.format(argument), getLocale())).format(argument) :
797 * subformat.format(argument)</code>
798 * <tr>
799 * <td><code>!= null</code>
800 * <td><i>any</i>
801 * <td><code>subformat.format(argument)</code>
802 * <tr>
803 * <td><code>null</code>
804 * <td><code>instanceof Number</code>
805 * <td><code>NumberFormat.getInstance(getLocale()).format(argument)</code>
806 * <tr>
807 * <td><code>null</code>
808 * <td><code>instanceof Date</code>
809 * <td><code>DateFormat.getDateTimeInstance(DateFormat.SHORT, DateFormat.SHORT, getLocale()).format(argument)</code>
810 * <tr>
811 * <td><code>null</code>
812 * <td><code>instanceof String</code>
813 * <td><code>argument</code>
814 * <tr>
815 * <td><code>null</code>
816 * <td><i>any</i>
817 * <td><code>argument.toString()</code>
818 * </tbody>
819 * </table>
820 * <p>
821 * If <code>pos</code> is non-null, and refers to
822 * <code>Field.ARGUMENT</code>, the location of the first formatted
823 * string will be returned.
824 *
825 * @param arguments an array of objects to be formatted and substituted.
826 * @param result where text is appended.
827 * @param pos On input: an alignment field, if desired.
828 * On output: the offsets of the alignment field.
829 * @return the string buffer passed in as {@code result}, with formatted
830 * text appended
831 * @exception IllegalArgumentException if an argument in the
832 * <code>arguments</code> array is not of the type
833 * expected by the format element(s) that use it.
834 * @exception NullPointerException if {@code result} is {@code null}
835 */
836 public final StringBuffer format(Object[] arguments, StringBuffer result,
|
133 * bundle source files) which strings will be processed by {@code MessageFormat}.
134 * Note that localizers may need to use single quotes in translated
135 * strings where the original version doesn't have them.
136 * </dl>
137 * <p>
138 * The <i>ArgumentIndex</i> value is a non-negative integer written
139 * using the digits {@code '0'} through {@code '9'}, and represents an index into the
140 * {@code arguments} array passed to the {@code format} methods
141 * or the result array returned by the {@code parse} methods.
142 * <p>
143 * The <i>FormatType</i> and <i>FormatStyle</i> values are used to create
144 * a {@code Format} instance for the format element. The following
145 * table shows how the values map to {@code Format} instances. Combinations not
146 * shown in the table are illegal. A <i>SubformatPattern</i> must
147 * be a valid pattern string for the {@code Format} subclass used.
148 *
149 * <table class="plain">
150 * <caption style="display:none">Shows how FormatType and FormatStyle values map to Format instances</caption>
151 * <thead>
152 * <tr>
153 * <th scope="col" class="TableHeadingColor">FormatType
154 * <th scope="col" class="TableHeadingColor">FormatStyle
155 * <th scope="col" class="TableHeadingColor">Subformat Created
156 * </thead>
157 * <tbody>
158 * <tr>
159 * <th scope="row" style="text-weight: normal"><i>(none)</i>
160 * <th scope="row" style="text-weight: normal"><i>(none)</i>
161 * <td>{@code null}
162 * <tr>
163 * <th scope="row" style="text-weight: normal" rowspan=5>{@code number}
164 * <th scope="row" style="text-weight: normal"><i>(none)</i>
165 * <td>{@link NumberFormat#getInstance(Locale) NumberFormat.getInstance}{@code (getLocale())}
166 * <tr>
167 * <th scope="row" style="text-weight: normal">{@code integer}
168 * <td>{@link NumberFormat#getIntegerInstance(Locale) NumberFormat.getIntegerInstance}{@code (getLocale())}
169 * <tr>
170 * <th scope="row" style="text-weight: normal">{@code currency}
171 * <td>{@link NumberFormat#getCurrencyInstance(Locale) NumberFormat.getCurrencyInstance}{@code (getLocale())}
172 * <tr>
173 * <th scope="row" style="text-weight: normal">{@code percent}
174 * <td>{@link NumberFormat#getPercentInstance(Locale) NumberFormat.getPercentInstance}{@code (getLocale())}
175 * <tr>
176 * <th scope="row" style="text-weight: normal"><i>SubformatPattern</i>
177 * <td>{@code new} {@link DecimalFormat#DecimalFormat(String,DecimalFormatSymbols) DecimalFormat}{@code (subformatPattern,} {@link DecimalFormatSymbols#getInstance(Locale) DecimalFormatSymbols.getInstance}{@code (getLocale()))}
178 * <tr>
179 * <th scope="row" style="text-weight: normal" rowspan=6>{@code date}
180 * <th scope="row" style="text-weight: normal"><i>(none)</i>
181 * <td>{@link DateFormat#getDateInstance(int,Locale) DateFormat.getDateInstance}{@code (}{@link DateFormat#DEFAULT}{@code , getLocale())}
182 * <tr>
183 * <th scope="row" style="text-weight: normal">{@code short}
184 * <td>{@link DateFormat#getDateInstance(int,Locale) DateFormat.getDateInstance}{@code (}{@link DateFormat#SHORT}{@code , getLocale())}
185 * <tr>
186 * <th scope="row" style="text-weight: normal">{@code medium}
187 * <td>{@link DateFormat#getDateInstance(int,Locale) DateFormat.getDateInstance}{@code (}{@link DateFormat#DEFAULT}{@code , getLocale())}
188 * <tr>
189 * <th scope="row" style="text-weight: normal">{@code long}
190 * <td>{@link DateFormat#getDateInstance(int,Locale) DateFormat.getDateInstance}{@code (}{@link DateFormat#LONG}{@code , getLocale())}
191 * <tr>
192 * <th scope="row" style="text-weight: normal">{@code full}
193 * <td>{@link DateFormat#getDateInstance(int,Locale) DateFormat.getDateInstance}{@code (}{@link DateFormat#FULL}{@code , getLocale())}
194 * <tr>
195 * <th scope="row" style="text-weight: normal"><i>SubformatPattern</i>
196 * <td>{@code new} {@link SimpleDateFormat#SimpleDateFormat(String,Locale) SimpleDateFormat}{@code (subformatPattern, getLocale())}
197 * <tr>
198 * <th scope="row" style="text-weight: normal" rowspan=6>{@code time}
199 * <th scope="row" style="text-weight: normal"><i>(none)</i>
200 * <td>{@link DateFormat#getTimeInstance(int,Locale) DateFormat.getTimeInstance}{@code (}{@link DateFormat#DEFAULT}{@code , getLocale())}
201 * <tr>
202 * <th scope="row" style="text-weight: normal">{@code short}
203 * <td>{@link DateFormat#getTimeInstance(int,Locale) DateFormat.getTimeInstance}{@code (}{@link DateFormat#SHORT}{@code , getLocale())}
204 * <tr>
205 * <th scope="row" style="text-weight: normal">{@code medium}
206 * <td>{@link DateFormat#getTimeInstance(int,Locale) DateFormat.getTimeInstance}{@code (}{@link DateFormat#DEFAULT}{@code , getLocale())}
207 * <tr>
208 * <th scope="row" style="text-weight: normal">{@code long}
209 * <td>{@link DateFormat#getTimeInstance(int,Locale) DateFormat.getTimeInstance}{@code (}{@link DateFormat#LONG}{@code , getLocale())}
210 * <tr>
211 * <th scope="row" style="text-weight: normal">{@code full}
212 * <td>{@link DateFormat#getTimeInstance(int,Locale) DateFormat.getTimeInstance}{@code (}{@link DateFormat#FULL}{@code , getLocale())}
213 * <tr>
214 * <th scope="row" style="text-weight: normal"><i>SubformatPattern</i>
215 * <td>{@code new} {@link SimpleDateFormat#SimpleDateFormat(String,Locale) SimpleDateFormat}{@code (subformatPattern, getLocale())}
216 * <tr>
217 * <th scope="row" style="text-weight: normal">{@code choice}
218 * <th scope="row" style="text-weight: normal"><i>SubformatPattern</i>
219 * <td>{@code new} {@link ChoiceFormat#ChoiceFormat(String) ChoiceFormat}{@code (subformatPattern)}
220 * </tbody>
221 * </table>
222 *
223 * <h4>Usage Information</h4>
224 *
225 * <p>
226 * Here are some examples of usage.
227 * In real internationalized programs, the message format pattern and other
228 * static strings will, of course, be obtained from resource bundles.
229 * Other parameters will be dynamically determined at runtime.
230 * <p>
231 * The first example uses the static method <code>MessageFormat.format</code>,
232 * which internally creates a <code>MessageFormat</code> for one-time use:
233 * <blockquote><pre>
234 * int planet = 7;
235 * String event = "a disturbance in the Force";
236 *
237 * String result = MessageFormat.format(
238 * "At {1,time} on {1,date}, there was {2} on planet {0,number,integer}.",
239 * planet, new Date(), event);
759 System.arraycopy(formats, 0, resultArray, 0, maxOffset + 1);
760 return resultArray;
761 }
762
763 /**
764 * Formats an array of objects and appends the <code>MessageFormat</code>'s
765 * pattern, with format elements replaced by the formatted objects, to the
766 * provided <code>StringBuffer</code>.
767 * <p>
768 * The text substituted for the individual format elements is derived from
769 * the current subformat of the format element and the
770 * <code>arguments</code> element at the format element's argument index
771 * as indicated by the first matching line of the following table. An
772 * argument is <i>unavailable</i> if <code>arguments</code> is
773 * <code>null</code> or has fewer than argumentIndex+1 elements.
774 *
775 * <table class="plain">
776 * <caption style="display:none">Examples of subformat,argument,and formatted text</caption>
777 * <thead>
778 * <tr>
779 * <th scope="col">Subformat
780 * <th scope="col">Argument
781 * <th scope="col">Formatted Text
782 * </thead>
783 * <tbody>
784 * <tr>
785 * <th scope="row" style="text-weight-normal" rowspan=2><i>any</i>
786 * <th scope="row" style="text-weight-normal"><i>unavailable</i>
787 * <td><code>"{" + argumentIndex + "}"</code>
788 * <tr>
789 * <th scope="row" style="text-weight-normal"><code>null</code>
790 * <td><code>"null"</code>
791 * <tr>
792 * <th scope="row" style="text-weight-normal"><code>instanceof ChoiceFormat</code>
793 * <th scope="row" style="text-weight-normal"><i>any</i>
794 * <td><code>subformat.format(argument).indexOf('{') >= 0 ?<br>
795 * (new MessageFormat(subformat.format(argument), getLocale())).format(argument) :
796 * subformat.format(argument)</code>
797 * <tr>
798 * <th scope="row" style="text-weight-normal"><code>!= null</code>
799 * <th scope="row" style="text-weight-normal"><i>any</i>
800 * <td><code>subformat.format(argument)</code>
801 * <tr>
802 * <th scope="row" style="text-weight-normal" rowspan=4><code>null</code>
803 * <th scope="row" style="text-weight-normal"><code>instanceof Number</code>
804 * <td><code>NumberFormat.getInstance(getLocale()).format(argument)</code>
805 * <tr>
806 * <th scope="row" style="text-weight-normal"><code>instanceof Date</code>
807 * <td><code>DateFormat.getDateTimeInstance(DateFormat.SHORT, DateFormat.SHORT, getLocale()).format(argument)</code>
808 * <tr>
809 * <th scope="row" style="text-weight-normal"><code>instanceof String</code>
810 * <td><code>argument</code>
811 * <tr>
812 * <th scope="row" style="text-weight-normal"><i>any</i>
813 * <td><code>argument.toString()</code>
814 * </tbody>
815 * </table>
816 * <p>
817 * If <code>pos</code> is non-null, and refers to
818 * <code>Field.ARGUMENT</code>, the location of the first formatted
819 * string will be returned.
820 *
821 * @param arguments an array of objects to be formatted and substituted.
822 * @param result where text is appended.
823 * @param pos On input: an alignment field, if desired.
824 * On output: the offsets of the alignment field.
825 * @return the string buffer passed in as {@code result}, with formatted
826 * text appended
827 * @exception IllegalArgumentException if an argument in the
828 * <code>arguments</code> array is not of the type
829 * expected by the format element(s) that use it.
830 * @exception NullPointerException if {@code result} is {@code null}
831 */
832 public final StringBuffer format(Object[] arguments, StringBuffer result,
|