129 * format patterns unfortunately have shown to be somewhat confusing.
130 * In particular, it isn't always obvious to localizers whether single
131 * quotes need to be doubled or not. Make sure to inform localizers about
132 * the rules, and tell them (for example, by using comments in resource
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 border=1 summary="Shows how FormatType and FormatStyle values map to Format instances">
150 * <tr>
151 * <th id="ft" class="TableHeadingColor">FormatType
152 * <th id="fs" class="TableHeadingColor">FormatStyle
153 * <th id="sc" class="TableHeadingColor">Subformat Created
154 * <tr>
155 * <td headers="ft"><i>(none)</i>
156 * <td headers="fs"><i>(none)</i>
157 * <td headers="sc"><code>null</code>
158 * <tr>
159 * <td headers="ft" rowspan=5><code>number</code>
160 * <td headers="fs"><i>(none)</i>
161 * <td headers="sc">{@link NumberFormat#getInstance(Locale) NumberFormat.getInstance}{@code (getLocale())}
162 * <tr>
163 * <td headers="fs"><code>integer</code>
164 * <td headers="sc">{@link NumberFormat#getIntegerInstance(Locale) NumberFormat.getIntegerInstance}{@code (getLocale())}
165 * <tr>
166 * <td headers="fs"><code>currency</code>
167 * <td headers="sc">{@link NumberFormat#getCurrencyInstance(Locale) NumberFormat.getCurrencyInstance}{@code (getLocale())}
168 * <tr>
169 * <td headers="fs"><code>percent</code>
170 * <td headers="sc">{@link NumberFormat#getPercentInstance(Locale) NumberFormat.getPercentInstance}{@code (getLocale())}
171 * <tr>
172 * <td headers="fs"><i>SubformatPattern</i>
173 * <td headers="sc">{@code new} {@link DecimalFormat#DecimalFormat(String,DecimalFormatSymbols) DecimalFormat}{@code (subformatPattern,} {@link DecimalFormatSymbols#getInstance(Locale) DecimalFormatSymbols.getInstance}{@code (getLocale()))}
196 * <td headers="sc">{@link DateFormat#getTimeInstance(int,Locale) DateFormat.getTimeInstance}{@code (}{@link DateFormat#DEFAULT}{@code , getLocale())}
197 * <tr>
198 * <td headers="fs"><code>short</code>
199 * <td headers="sc">{@link DateFormat#getTimeInstance(int,Locale) DateFormat.getTimeInstance}{@code (}{@link DateFormat#SHORT}{@code , getLocale())}
200 * <tr>
201 * <td headers="fs"><code>medium</code>
202 * <td headers="sc">{@link DateFormat#getTimeInstance(int,Locale) DateFormat.getTimeInstance}{@code (}{@link DateFormat#DEFAULT}{@code , getLocale())}
203 * <tr>
204 * <td headers="fs"><code>long</code>
205 * <td headers="sc">{@link DateFormat#getTimeInstance(int,Locale) DateFormat.getTimeInstance}{@code (}{@link DateFormat#LONG}{@code , getLocale())}
206 * <tr>
207 * <td headers="fs"><code>full</code>
208 * <td headers="sc">{@link DateFormat#getTimeInstance(int,Locale) DateFormat.getTimeInstance}{@code (}{@link DateFormat#FULL}{@code , getLocale())}
209 * <tr>
210 * <td headers="fs"><i>SubformatPattern</i>
211 * <td headers="sc">{@code new} {@link SimpleDateFormat#SimpleDateFormat(String,Locale) SimpleDateFormat}{@code (subformatPattern, getLocale())}
212 * <tr>
213 * <td headers="ft"><code>choice</code>
214 * <td headers="fs"><i>SubformatPattern</i>
215 * <td headers="sc">{@code new} {@link ChoiceFormat#ChoiceFormat(String) ChoiceFormat}{@code (subformatPattern)}
216 * </table>
217 *
218 * <h4>Usage Information</h4>
219 *
220 * <p>
221 * Here are some examples of usage.
222 * In real internationalized programs, the message format pattern and other
223 * static strings will, of course, be obtained from resource bundles.
224 * Other parameters will be dynamically determined at runtime.
225 * <p>
226 * The first example uses the static method <code>MessageFormat.format</code>,
227 * which internally creates a <code>MessageFormat</code> for one-time use:
228 * <blockquote><pre>
229 * int planet = 7;
230 * String event = "a disturbance in the Force";
231 *
232 * String result = MessageFormat.format(
233 * "At {1,time} on {1,date}, there was {2} on planet {0,number,integer}.",
234 * planet, new Date(), event);
235 * </pre></blockquote>
749 * @return the formats used for the format elements in the pattern
750 */
751 public Format[] getFormats() {
752 Format[] resultArray = new Format[maxOffset + 1];
753 System.arraycopy(formats, 0, resultArray, 0, maxOffset + 1);
754 return resultArray;
755 }
756
757 /**
758 * Formats an array of objects and appends the <code>MessageFormat</code>'s
759 * pattern, with format elements replaced by the formatted objects, to the
760 * provided <code>StringBuffer</code>.
761 * <p>
762 * The text substituted for the individual format elements is derived from
763 * the current subformat of the format element and the
764 * <code>arguments</code> element at the format element's argument index
765 * as indicated by the first matching line of the following table. An
766 * argument is <i>unavailable</i> if <code>arguments</code> is
767 * <code>null</code> or has fewer than argumentIndex+1 elements.
768 *
769 * <table border=1 summary="Examples of subformat,argument,and formatted text">
770 * <tr>
771 * <th>Subformat
772 * <th>Argument
773 * <th>Formatted Text
774 * <tr>
775 * <td><i>any</i>
776 * <td><i>unavailable</i>
777 * <td><code>"{" + argumentIndex + "}"</code>
778 * <tr>
779 * <td><i>any</i>
780 * <td><code>null</code>
781 * <td><code>"null"</code>
782 * <tr>
783 * <td><code>instanceof ChoiceFormat</code>
784 * <td><i>any</i>
785 * <td><code>subformat.format(argument).indexOf('{') >= 0 ?<br>
786 * (new MessageFormat(subformat.format(argument), getLocale())).format(argument) :
787 * subformat.format(argument)</code>
788 * <tr>
789 * <td><code>!= null</code>
790 * <td><i>any</i>
791 * <td><code>subformat.format(argument)</code>
792 * <tr>
793 * <td><code>null</code>
794 * <td><code>instanceof Number</code>
795 * <td><code>NumberFormat.getInstance(getLocale()).format(argument)</code>
796 * <tr>
797 * <td><code>null</code>
798 * <td><code>instanceof Date</code>
799 * <td><code>DateFormat.getDateTimeInstance(DateFormat.SHORT, DateFormat.SHORT, getLocale()).format(argument)</code>
800 * <tr>
801 * <td><code>null</code>
802 * <td><code>instanceof String</code>
803 * <td><code>argument</code>
804 * <tr>
805 * <td><code>null</code>
806 * <td><i>any</i>
807 * <td><code>argument.toString()</code>
808 * </table>
809 * <p>
810 * If <code>pos</code> is non-null, and refers to
811 * <code>Field.ARGUMENT</code>, the location of the first formatted
812 * string will be returned.
813 *
814 * @param arguments an array of objects to be formatted and substituted.
815 * @param result where text is appended.
816 * @param pos On input: an alignment field, if desired.
817 * On output: the offsets of the alignment field.
818 * @return the string buffer passed in as {@code result}, with formatted
819 * text appended
820 * @exception IllegalArgumentException if an argument in the
821 * <code>arguments</code> array is not of the type
822 * expected by the format element(s) that use it.
823 * @exception NullPointerException if {@code result} is {@code null}
824 */
825 public final StringBuffer format(Object[] arguments, StringBuffer result,
826 FieldPosition pos)
827 {
|
129 * format patterns unfortunately have shown to be somewhat confusing.
130 * In particular, it isn't always obvious to localizers whether single
131 * quotes need to be doubled or not. Make sure to inform localizers about
132 * the rules, and tell them (for example, by using comments in resource
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()))}
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);
240 * </pre></blockquote>
754 * @return the formats used for the format elements in the pattern
755 */
756 public Format[] getFormats() {
757 Format[] resultArray = new Format[maxOffset + 1];
758 System.arraycopy(formats, 0, resultArray, 0, maxOffset + 1);
759 return resultArray;
760 }
761
762 /**
763 * Formats an array of objects and appends the <code>MessageFormat</code>'s
764 * pattern, with format elements replaced by the formatted objects, to the
765 * provided <code>StringBuffer</code>.
766 * <p>
767 * The text substituted for the individual format elements is derived from
768 * the current subformat of the format element and the
769 * <code>arguments</code> element at the format element's argument index
770 * as indicated by the first matching line of the following table. An
771 * argument is <i>unavailable</i> if <code>arguments</code> is
772 * <code>null</code> or has fewer than argumentIndex+1 elements.
773 *
774 * <table class="plain">
775 * <caption style="display:none">Examples of subformat,argument,and formatted text</caption>
776 * <thead>
777 * <tr>
778 * <th>Subformat
779 * <th>Argument
780 * <th>Formatted Text
781 * </thead>
782 * <tbody>
783 * <tr>
784 * <td><i>any</i>
785 * <td><i>unavailable</i>
786 * <td><code>"{" + argumentIndex + "}"</code>
787 * <tr>
788 * <td><i>any</i>
789 * <td><code>null</code>
790 * <td><code>"null"</code>
791 * <tr>
792 * <td><code>instanceof ChoiceFormat</code>
793 * <td><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 * <td><code>!= null</code>
799 * <td><i>any</i>
800 * <td><code>subformat.format(argument)</code>
801 * <tr>
802 * <td><code>null</code>
803 * <td><code>instanceof Number</code>
804 * <td><code>NumberFormat.getInstance(getLocale()).format(argument)</code>
805 * <tr>
806 * <td><code>null</code>
807 * <td><code>instanceof Date</code>
808 * <td><code>DateFormat.getDateTimeInstance(DateFormat.SHORT, DateFormat.SHORT, getLocale()).format(argument)</code>
809 * <tr>
810 * <td><code>null</code>
811 * <td><code>instanceof String</code>
812 * <td><code>argument</code>
813 * <tr>
814 * <td><code>null</code>
815 * <td><i>any</i>
816 * <td><code>argument.toString()</code>
817 * </tbody>
818 * </table>
819 * <p>
820 * If <code>pos</code> is non-null, and refers to
821 * <code>Field.ARGUMENT</code>, the location of the first formatted
822 * string will be returned.
823 *
824 * @param arguments an array of objects to be formatted and substituted.
825 * @param result where text is appended.
826 * @param pos On input: an alignment field, if desired.
827 * On output: the offsets of the alignment field.
828 * @return the string buffer passed in as {@code result}, with formatted
829 * text appended
830 * @exception IllegalArgumentException if an argument in the
831 * <code>arguments</code> array is not of the type
832 * expected by the format element(s) that use it.
833 * @exception NullPointerException if {@code result} is {@code null}
834 */
835 public final StringBuffer format(Object[] arguments, StringBuffer result,
836 FieldPosition pos)
837 {
|