< prev index next >

src/java.base/share/classes/java/text/MessageFormat.java

Print this page




 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('{') &gt;= 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('{') &gt;= 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     {


< prev index next >