1 /* 2 * Copyright (c) 1996, 2017, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 /* 27 * (C) Copyright Taligent, Inc. 1996, 1997 - All Rights Reserved 28 * (C) Copyright IBM Corp. 1996 - 1998 - All Rights Reserved 29 * 30 * The original version of this source code and documentation is copyrighted 31 * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These 32 * materials are provided under terms of a License Agreement between Taligent 33 * and Sun. This technology is protected by multiple US and International 34 * patents. This notice and attribution to Taligent may not be removed. 35 * Taligent is a registered trademark of Taligent, Inc. 36 * 37 */ 38 39 package java.text; 40 41 import java.io.InvalidObjectException; 42 import java.io.IOException; 43 import java.io.ObjectInputStream; 44 import java.io.ObjectOutputStream; 45 import java.math.BigInteger; 46 import java.math.RoundingMode; 47 import java.text.spi.NumberFormatProvider; 48 import java.util.Currency; 49 import java.util.HashMap; 50 import java.util.Hashtable; 51 import java.util.Locale; 52 import java.util.Map; 53 import java.util.ResourceBundle; 54 import java.util.concurrent.atomic.AtomicInteger; 55 import java.util.concurrent.atomic.AtomicLong; 56 import java.util.spi.LocaleServiceProvider; 57 import sun.util.locale.provider.LocaleProviderAdapter; 58 import sun.util.locale.provider.LocaleServiceProviderPool; 59 60 /** 61 * <code>NumberFormat</code> is the abstract base class for all number 62 * formats. This class provides the interface for formatting and parsing 63 * numbers. <code>NumberFormat</code> also provides methods for determining 64 * which locales have number formats, and what their names are. 65 * 66 * <p> 67 * <code>NumberFormat</code> helps you to format and parse numbers for any locale. 68 * Your code can be completely independent of the locale conventions for 69 * decimal points, thousands-separators, or even the particular decimal 70 * digits used, or whether the number format is even decimal. 71 * 72 * <p> 73 * To format a number for the current Locale, use one of the factory 74 * class methods: 75 * <blockquote> 76 * <pre>{@code 77 * myString = NumberFormat.getInstance().format(myNumber); 78 * }</pre> 79 * </blockquote> 80 * If you are formatting multiple numbers, it is 81 * more efficient to get the format and use it multiple times so that 82 * the system doesn't have to fetch the information about the local 83 * language and country conventions multiple times. 84 * <blockquote> 85 * <pre>{@code 86 * NumberFormat nf = NumberFormat.getInstance(); 87 * for (int i = 0; i < myNumber.length; ++i) { 88 * output.println(nf.format(myNumber[i]) + "; "); 89 * } 90 * }</pre> 91 * </blockquote> 92 * To format a number for a different Locale, specify it in the 93 * call to <code>getInstance</code>. 94 * <blockquote> 95 * <pre>{@code 96 * NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH); 97 * }</pre> 98 * </blockquote> 99 * You can also use a <code>NumberFormat</code> to parse numbers: 100 * <blockquote> 101 * <pre>{@code 102 * myNumber = nf.parse(myString); 103 * }</pre> 104 * </blockquote> 105 * Use <code>getInstance</code> or <code>getNumberInstance</code> to get the 106 * normal number format. Use <code>getIntegerInstance</code> to get an 107 * integer number format. Use <code>getCurrencyInstance</code> to get the 108 * currency number format. And use <code>getPercentInstance</code> to get a 109 * format for displaying percentages. With this format, a fraction like 110 * 0.53 is displayed as 53%. 111 * 112 * <p> 113 * You can also control the display of numbers with such methods as 114 * <code>setMinimumFractionDigits</code>. 115 * If you want even more control over the format or parsing, 116 * or want to give your users more control, 117 * you can try casting the <code>NumberFormat</code> you get from the factory methods 118 * to a <code>DecimalFormat</code>. This will work for the vast majority 119 * of locales; just remember to put it in a <code>try</code> block in case you 120 * encounter an unusual one. 121 * 122 * <p> 123 * NumberFormat and DecimalFormat are designed such that some controls 124 * work for formatting and others work for parsing. The following is 125 * the detailed description for each these control methods, 126 * <p> 127 * setParseIntegerOnly : only affects parsing, e.g. 128 * if true, "3456.78" → 3456 (and leaves the parse position just after index 6) 129 * if false, "3456.78" → 3456.78 (and leaves the parse position just after index 8) 130 * This is independent of formatting. If you want to not show a decimal point 131 * where there might be no digits after the decimal point, use 132 * setDecimalSeparatorAlwaysShown. 133 * <p> 134 * setDecimalSeparatorAlwaysShown : only affects formatting, and only where 135 * there might be no digits after the decimal point, such as with a pattern 136 * like "#,##0.##", e.g., 137 * if true, 3456.00 → "3,456." 138 * if false, 3456.00 → "3456" 139 * This is independent of parsing. If you want parsing to stop at the decimal 140 * point, use setParseIntegerOnly. 141 * 142 * <p> 143 * You can also use forms of the <code>parse</code> and <code>format</code> 144 * methods with <code>ParsePosition</code> and <code>FieldPosition</code> to 145 * allow you to: 146 * <ul> 147 * <li> progressively parse through pieces of a string 148 * <li> align the decimal point and other areas 149 * </ul> 150 * For example, you can align numbers in two ways: 151 * <ol> 152 * <li> If you are using a monospaced font with spacing for alignment, 153 * you can pass the <code>FieldPosition</code> in your format call, with 154 * <code>field</code> = <code>INTEGER_FIELD</code>. On output, 155 * <code>getEndIndex</code> will be set to the offset between the 156 * last character of the integer and the decimal. Add 157 * (desiredSpaceCount - getEndIndex) spaces at the front of the string. 158 * 159 * <li> If you are using proportional fonts, 160 * instead of padding with spaces, measure the width 161 * of the string in pixels from the start to <code>getEndIndex</code>. 162 * Then move the pen by 163 * (desiredPixelWidth - widthToAlignmentPoint) before drawing the text. 164 * It also works where there is no decimal, but possibly additional 165 * characters at the end, e.g., with parentheses in negative 166 * numbers: "(12)" for -12. 167 * </ol> 168 * 169 * <h3><a id="synchronization">Synchronization</a></h3> 170 * 171 * <p> 172 * Number formats are generally not synchronized. 173 * It is recommended to create separate format instances for each thread. 174 * If multiple threads access a format concurrently, it must be synchronized 175 * externally. 176 * 177 * @implSpec The {@link #format(double, StringBuffer, FieldPosition)}, 178 * {@link #format(long, StringBuffer, FieldPosition)} and 179 * {@link #parse(String, ParsePosition)} methods may throw 180 * {@code NullPointerException}, if any of their parameter is {@code null}. 181 * The subclass may provide its own implementation and specification about 182 * {@code NullPointerException}. 183 * 184 * <p> 185 * The default implementation provides rounding modes defined 186 * in {@link java.math.RoundingMode} for formatting numbers. It 187 * uses the {@linkplain java.math.RoundingMode#HALF_EVEN 188 * round half-even algorithm}. To change the rounding mode use 189 * {@link #setRoundingMode(java.math.RoundingMode) setRoundingMode}. 190 * The {@code NumberFormat} returned by the static factory methods is 191 * configured to round floating point numbers using half-even 192 * rounding (see {@link java.math.RoundingMode#HALF_EVEN 193 * RoundingMode.HALF_EVEN}) for formatting. 194 * 195 * @see DecimalFormat 196 * @see ChoiceFormat 197 * @author Mark Davis 198 * @author Helena Shih 199 * @since 1.1 200 */ 201 public abstract class NumberFormat extends Format { 202 203 /** 204 * Field constant used to construct a FieldPosition object. Signifies that 205 * the position of the integer part of a formatted number should be returned. 206 * @see java.text.FieldPosition 207 */ 208 public static final int INTEGER_FIELD = 0; 209 210 /** 211 * Field constant used to construct a FieldPosition object. Signifies that 212 * the position of the fraction part of a formatted number should be returned. 213 * @see java.text.FieldPosition 214 */ 215 public static final int FRACTION_FIELD = 1; 216 217 /** 218 * Sole constructor. (For invocation by subclass constructors, typically 219 * implicit.) 220 */ 221 protected NumberFormat() { 222 } 223 224 /** 225 * Formats a number and appends the resulting text to the given string 226 * buffer. 227 * The number can be of any subclass of {@link java.lang.Number}. 228 * <p> 229 * This implementation extracts the number's value using 230 * {@link java.lang.Number#longValue()} for all integral type values that 231 * can be converted to <code>long</code> without loss of information, 232 * including <code>BigInteger</code> values with a 233 * {@link java.math.BigInteger#bitLength() bit length} of less than 64, 234 * and {@link java.lang.Number#doubleValue()} for all other types. It 235 * then calls 236 * {@link #format(long,java.lang.StringBuffer,java.text.FieldPosition)} 237 * or {@link #format(double,java.lang.StringBuffer,java.text.FieldPosition)}. 238 * This may result in loss of magnitude information and precision for 239 * <code>BigInteger</code> and <code>BigDecimal</code> values. 240 * @param number the number to format 241 * @param toAppendTo the <code>StringBuffer</code> to which the formatted 242 * text is to be appended 243 * @param pos keeps track on the position of the field within the 244 * returned string. For example, for formatting a number 245 * {@code 1234567.89} in {@code Locale.US} locale, 246 * if the given {@code fieldPosition} is 247 * {@link NumberFormat#INTEGER_FIELD}, the begin index 248 * and end index of {@code fieldPosition} will be set 249 * to 0 and 9, respectively for the output string 250 * {@code 1,234,567.89}. 251 * @return the value passed in as <code>toAppendTo</code> 252 * @exception IllegalArgumentException if <code>number</code> is 253 * null or not an instance of <code>Number</code>. 254 * @exception NullPointerException if <code>toAppendTo</code> or 255 * <code>pos</code> is null 256 * @exception ArithmeticException if rounding is needed with rounding 257 * mode being set to RoundingMode.UNNECESSARY 258 * @see java.text.FieldPosition 259 */ 260 @Override 261 public StringBuffer format(Object number, 262 StringBuffer toAppendTo, 263 FieldPosition pos) { 264 if (number instanceof Long || number instanceof Integer || 265 number instanceof Short || number instanceof Byte || 266 number instanceof AtomicInteger || number instanceof AtomicLong || 267 (number instanceof BigInteger && 268 ((BigInteger)number).bitLength() < 64)) { 269 return format(((Number)number).longValue(), toAppendTo, pos); 270 } else if (number instanceof Number) { 271 return format(((Number)number).doubleValue(), toAppendTo, pos); 272 } else { 273 throw new IllegalArgumentException("Cannot format given Object as a Number"); 274 } 275 } 276 277 /** 278 * Parses text from a string to produce a <code>Number</code>. 279 * <p> 280 * The method attempts to parse text starting at the index given by 281 * <code>pos</code>. 282 * If parsing succeeds, then the index of <code>pos</code> is updated 283 * to the index after the last character used (parsing does not necessarily 284 * use all characters up to the end of the string), and the parsed 285 * number is returned. The updated <code>pos</code> can be used to 286 * indicate the starting point for the next call to this method. 287 * If an error occurs, then the index of <code>pos</code> is not 288 * changed, the error index of <code>pos</code> is set to the index of 289 * the character where the error occurred, and null is returned. 290 * <p> 291 * See the {@link #parse(String, ParsePosition)} method for more information 292 * on number parsing. 293 * 294 * @param source A <code>String</code>, part of which should be parsed. 295 * @param pos A <code>ParsePosition</code> object with index and error 296 * index information as described above. 297 * @return A <code>Number</code> parsed from the string. In case of 298 * error, returns null. 299 * @throws NullPointerException if {@code source} or {@code pos} is null. 300 */ 301 @Override 302 public final Object parseObject(String source, ParsePosition pos) { 303 return parse(source, pos); 304 } 305 306 /** 307 * Specialization of format. 308 * 309 * @param number the double number to format 310 * @return the formatted String 311 * @exception ArithmeticException if rounding is needed with rounding 312 * mode being set to RoundingMode.UNNECESSARY 313 * @see java.text.Format#format 314 */ 315 public final String format(double number) { 316 // Use fast-path for double result if that works 317 String result = fastFormat(number); 318 if (result != null) 319 return result; 320 321 return format(number, new StringBuffer(), 322 DontCareFieldPosition.INSTANCE).toString(); 323 } 324 325 /* 326 * fastFormat() is supposed to be implemented in concrete subclasses only. 327 * Default implem always returns null. 328 */ 329 String fastFormat(double number) { return null; } 330 331 /** 332 * Specialization of format. 333 * 334 * @param number the long number to format 335 * @return the formatted String 336 * @exception ArithmeticException if rounding is needed with rounding 337 * mode being set to RoundingMode.UNNECESSARY 338 * @see java.text.Format#format 339 */ 340 public final String format(long number) { 341 return format(number, new StringBuffer(), 342 DontCareFieldPosition.INSTANCE).toString(); 343 } 344 345 /** 346 * Specialization of format. 347 * 348 * @param number the double number to format 349 * @param toAppendTo the StringBuffer to which the formatted text is to be 350 * appended 351 * @param pos keeps track on the position of the field within the 352 * returned string. For example, for formatting a number 353 * {@code 1234567.89} in {@code Locale.US} locale, 354 * if the given {@code fieldPosition} is 355 * {@link NumberFormat#INTEGER_FIELD}, the begin index 356 * and end index of {@code fieldPosition} will be set 357 * to 0 and 9, respectively for the output string 358 * {@code 1,234,567.89}. 359 * @return the formatted StringBuffer 360 * @exception ArithmeticException if rounding is needed with rounding 361 * mode being set to RoundingMode.UNNECESSARY 362 * @see java.text.Format#format 363 */ 364 public abstract StringBuffer format(double number, 365 StringBuffer toAppendTo, 366 FieldPosition pos); 367 368 /** 369 * Specialization of format. 370 * 371 * @param number the long number to format 372 * @param toAppendTo the StringBuffer to which the formatted text is to be 373 * appended 374 * @param pos keeps track on the position of the field within the 375 * returned string. For example, for formatting a number 376 * {@code 123456789} in {@code Locale.US} locale, 377 * if the given {@code fieldPosition} is 378 * {@link NumberFormat#INTEGER_FIELD}, the begin index 379 * and end index of {@code fieldPosition} will be set 380 * to 0 and 11, respectively for the output string 381 * {@code 123,456,789}. 382 * @return the formatted StringBuffer 383 * @exception ArithmeticException if rounding is needed with rounding 384 * mode being set to RoundingMode.UNNECESSARY 385 * @see java.text.Format#format 386 */ 387 public abstract StringBuffer format(long number, 388 StringBuffer toAppendTo, 389 FieldPosition pos); 390 391 /** 392 * Returns a Long if possible (e.g., within the range [Long.MIN_VALUE, 393 * Long.MAX_VALUE] and with no decimals), otherwise a Double. 394 * If IntegerOnly is set, will stop at a decimal 395 * point (or equivalent; e.g., for rational numbers "1 2/3", will stop 396 * after the 1). 397 * Does not throw an exception; if no object can be parsed, index is 398 * unchanged! 399 * 400 * @param source the String to parse 401 * @param parsePosition the parse position 402 * @return the parsed value 403 * @see java.text.NumberFormat#isParseIntegerOnly 404 * @see java.text.Format#parseObject 405 */ 406 public abstract Number parse(String source, ParsePosition parsePosition); 407 408 /** 409 * Parses text from the beginning of the given string to produce a number. 410 * The method may not use the entire text of the given string. 411 * <p> 412 * See the {@link #parse(String, ParsePosition)} method for more information 413 * on number parsing. 414 * 415 * @param source A <code>String</code> whose beginning should be parsed. 416 * @return A <code>Number</code> parsed from the string. 417 * @exception ParseException if the beginning of the specified string 418 * cannot be parsed. 419 */ 420 public Number parse(String source) throws ParseException { 421 ParsePosition parsePosition = new ParsePosition(0); 422 Number result = parse(source, parsePosition); 423 if (parsePosition.index == 0) { 424 throw new ParseException("Unparseable number: \"" + source + "\"", 425 parsePosition.errorIndex); 426 } 427 return result; 428 } 429 430 /** 431 * Returns true if this format will parse numbers as integers only. 432 * For example in the English locale, with ParseIntegerOnly true, the 433 * string "1234." would be parsed as the integer value 1234 and parsing 434 * would stop at the "." character. Of course, the exact format accepted 435 * by the parse operation is locale dependent and determined by sub-classes 436 * of NumberFormat. 437 * 438 * @return {@code true} if numbers should be parsed as integers only; 439 * {@code false} otherwise 440 */ 441 public boolean isParseIntegerOnly() { 442 return parseIntegerOnly; 443 } 444 445 /** 446 * Sets whether or not numbers should be parsed as integers only. 447 * 448 * @param value {@code true} if numbers should be parsed as integers only; 449 * {@code false} otherwise 450 * @see #isParseIntegerOnly 451 */ 452 public void setParseIntegerOnly(boolean value) { 453 parseIntegerOnly = value; 454 } 455 456 //============== Locale Stuff ===================== 457 458 /** 459 * Returns a general-purpose number format for the current default 460 * {@link java.util.Locale.Category#FORMAT FORMAT} locale. 461 * This is the same as calling 462 * {@link #getNumberInstance() getNumberInstance()}. 463 * 464 * @return the {@code NumberFormat} instance for general-purpose number 465 * formatting 466 */ 467 public static final NumberFormat getInstance() { 468 return getInstance(Locale.getDefault(Locale.Category.FORMAT), NUMBERSTYLE); 469 } 470 471 /** 472 * Returns a general-purpose number format for the specified locale. 473 * This is the same as calling 474 * {@link #getNumberInstance(java.util.Locale) getNumberInstance(inLocale)}. 475 * 476 * @param inLocale the desired locale 477 * @return the {@code NumberFormat} instance for general-purpose number 478 * formatting 479 */ 480 public static NumberFormat getInstance(Locale inLocale) { 481 return getInstance(inLocale, NUMBERSTYLE); 482 } 483 484 /** 485 * Returns a general-purpose number format for the current default 486 * {@link java.util.Locale.Category#FORMAT FORMAT} locale. 487 * <p>This is equivalent to calling 488 * {@link #getNumberInstance(Locale) 489 * getNumberInstance(Locale.getDefault(Locale.Category.FORMAT))}. 490 * 491 * @return the {@code NumberFormat} instance for general-purpose number 492 * formatting 493 * @see java.util.Locale#getDefault(java.util.Locale.Category) 494 * @see java.util.Locale.Category#FORMAT 495 */ 496 public static final NumberFormat getNumberInstance() { 497 return getInstance(Locale.getDefault(Locale.Category.FORMAT), NUMBERSTYLE); 498 } 499 500 /** 501 * Returns a general-purpose number format for the specified locale. 502 * 503 * @param inLocale the desired locale 504 * @return the {@code NumberFormat} instance for general-purpose number 505 * formatting 506 */ 507 public static NumberFormat getNumberInstance(Locale inLocale) { 508 return getInstance(inLocale, NUMBERSTYLE); 509 } 510 511 /** 512 * Returns an integer number format for the current default 513 * {@link java.util.Locale.Category#FORMAT FORMAT} locale. The 514 * returned number format is configured to round floating point numbers 515 * to the nearest integer using half-even rounding (see {@link 516 * java.math.RoundingMode#HALF_EVEN RoundingMode.HALF_EVEN}) for formatting, 517 * and to parse only the integer part of an input string (see {@link 518 * #isParseIntegerOnly isParseIntegerOnly}). 519 * <p>This is equivalent to calling 520 * {@link #getIntegerInstance(Locale) 521 * getIntegerInstance(Locale.getDefault(Locale.Category.FORMAT))}. 522 * 523 * @see #getRoundingMode() 524 * @see java.util.Locale#getDefault(java.util.Locale.Category) 525 * @see java.util.Locale.Category#FORMAT 526 * @return a number format for integer values 527 * @since 1.4 528 */ 529 public static final NumberFormat getIntegerInstance() { 530 return getInstance(Locale.getDefault(Locale.Category.FORMAT), INTEGERSTYLE); 531 } 532 533 /** 534 * Returns an integer number format for the specified locale. The 535 * returned number format is configured to round floating point numbers 536 * to the nearest integer using half-even rounding (see {@link 537 * java.math.RoundingMode#HALF_EVEN RoundingMode.HALF_EVEN}) for formatting, 538 * and to parse only the integer part of an input string (see {@link 539 * #isParseIntegerOnly isParseIntegerOnly}). 540 * 541 * @param inLocale the desired locale 542 * @see #getRoundingMode() 543 * @return a number format for integer values 544 * @since 1.4 545 */ 546 public static NumberFormat getIntegerInstance(Locale inLocale) { 547 return getInstance(inLocale, INTEGERSTYLE); 548 } 549 550 /** 551 * Returns a currency format for the current default 552 * {@link java.util.Locale.Category#FORMAT FORMAT} locale. 553 * <p>This is equivalent to calling 554 * {@link #getCurrencyInstance(Locale) 555 * getCurrencyInstance(Locale.getDefault(Locale.Category.FORMAT))}. 556 * 557 * @return the {@code NumberFormat} instance for currency formatting 558 * @see java.util.Locale#getDefault(java.util.Locale.Category) 559 * @see java.util.Locale.Category#FORMAT 560 */ 561 public static final NumberFormat getCurrencyInstance() { 562 return getInstance(Locale.getDefault(Locale.Category.FORMAT), CURRENCYSTYLE); 563 } 564 565 /** 566 * Returns a currency format for the specified locale. 567 * 568 * @param inLocale the desired locale 569 * @return the {@code NumberFormat} instance for currency formatting 570 */ 571 public static NumberFormat getCurrencyInstance(Locale inLocale) { 572 return getInstance(inLocale, CURRENCYSTYLE); 573 } 574 575 /** 576 * Returns a percentage format for the current default 577 * {@link java.util.Locale.Category#FORMAT FORMAT} locale. 578 * <p>This is equivalent to calling 579 * {@link #getPercentInstance(Locale) 580 * getPercentInstance(Locale.getDefault(Locale.Category.FORMAT))}. 581 * 582 * @return the {@code NumberFormat} instance for percentage formatting 583 * @see java.util.Locale#getDefault(java.util.Locale.Category) 584 * @see java.util.Locale.Category#FORMAT 585 */ 586 public static final NumberFormat getPercentInstance() { 587 return getInstance(Locale.getDefault(Locale.Category.FORMAT), PERCENTSTYLE); 588 } 589 590 /** 591 * Returns a percentage format for the specified locale. 592 * 593 * @param inLocale the desired locale 594 * @return the {@code NumberFormat} instance for percentage formatting 595 */ 596 public static NumberFormat getPercentInstance(Locale inLocale) { 597 return getInstance(inLocale, PERCENTSTYLE); 598 } 599 600 /** 601 * Returns a scientific format for the current default locale. 602 */ 603 /*public*/ final static NumberFormat getScientificInstance() { 604 return getInstance(Locale.getDefault(Locale.Category.FORMAT), SCIENTIFICSTYLE); 605 } 606 607 /** 608 * Returns a scientific format for the specified locale. 609 * 610 * @param inLocale the desired locale 611 */ 612 /*public*/ static NumberFormat getScientificInstance(Locale inLocale) { 613 return getInstance(inLocale, SCIENTIFICSTYLE); 614 } 615 616 /** 617 * Returns an array of all locales for which the 618 * <code>get*Instance</code> methods of this class can return 619 * localized instances. 620 * The returned array represents the union of locales supported by the Java 621 * runtime and by installed 622 * {@link java.text.spi.NumberFormatProvider NumberFormatProvider} implementations. 623 * It must contain at least a <code>Locale</code> instance equal to 624 * {@link java.util.Locale#US Locale.US}. 625 * 626 * @return An array of locales for which localized 627 * <code>NumberFormat</code> instances are available. 628 */ 629 public static Locale[] getAvailableLocales() { 630 LocaleServiceProviderPool pool = 631 LocaleServiceProviderPool.getPool(NumberFormatProvider.class); 632 return pool.getAvailableLocales(); 633 } 634 635 /** 636 * Overrides hashCode. 637 */ 638 @Override 639 public int hashCode() { 640 return maximumIntegerDigits * 37 + maxFractionDigits; 641 // just enough fields for a reasonable distribution 642 } 643 644 /** 645 * Overrides equals. 646 */ 647 @Override 648 public boolean equals(Object obj) { 649 if (obj == null) { 650 return false; 651 } 652 if (this == obj) { 653 return true; 654 } 655 if (getClass() != obj.getClass()) { 656 return false; 657 } 658 NumberFormat other = (NumberFormat) obj; 659 return (maximumIntegerDigits == other.maximumIntegerDigits 660 && minimumIntegerDigits == other.minimumIntegerDigits 661 && maximumFractionDigits == other.maximumFractionDigits 662 && minimumFractionDigits == other.minimumFractionDigits 663 && groupingUsed == other.groupingUsed 664 && parseIntegerOnly == other.parseIntegerOnly); 665 } 666 667 /** 668 * Overrides Cloneable. 669 */ 670 @Override 671 public Object clone() { 672 NumberFormat other = (NumberFormat) super.clone(); 673 return other; 674 } 675 676 /** 677 * Returns true if grouping is used in this format. For example, in the 678 * English locale, with grouping on, the number 1234567 might be formatted 679 * as "1,234,567". The grouping separator as well as the size of each group 680 * is locale dependent and is determined by sub-classes of NumberFormat. 681 * 682 * @return {@code true} if grouping is used; 683 * {@code false} otherwise 684 * @see #setGroupingUsed 685 */ 686 public boolean isGroupingUsed() { 687 return groupingUsed; 688 } 689 690 /** 691 * Set whether or not grouping will be used in this format. 692 * 693 * @param newValue {@code true} if grouping is used; 694 * {@code false} otherwise 695 * @see #isGroupingUsed 696 */ 697 public void setGroupingUsed(boolean newValue) { 698 groupingUsed = newValue; 699 } 700 701 /** 702 * Returns the maximum number of digits allowed in the integer portion of a 703 * number. 704 * 705 * @return the maximum number of digits 706 * @see #setMaximumIntegerDigits 707 */ 708 public int getMaximumIntegerDigits() { 709 return maximumIntegerDigits; 710 } 711 712 /** 713 * Sets the maximum number of digits allowed in the integer portion of a 714 * number. maximumIntegerDigits must be ≥ minimumIntegerDigits. If the 715 * new value for maximumIntegerDigits is less than the current value 716 * of minimumIntegerDigits, then minimumIntegerDigits will also be set to 717 * the new value. 718 * 719 * @param newValue the maximum number of integer digits to be shown; if 720 * less than zero, then zero is used. The concrete subclass may enforce an 721 * upper limit to this value appropriate to the numeric type being formatted. 722 * @see #getMaximumIntegerDigits 723 */ 724 public void setMaximumIntegerDigits(int newValue) { 725 maximumIntegerDigits = Math.max(0,newValue); 726 if (minimumIntegerDigits > maximumIntegerDigits) { 727 minimumIntegerDigits = maximumIntegerDigits; 728 } 729 } 730 731 /** 732 * Returns the minimum number of digits allowed in the integer portion of a 733 * number. 734 * 735 * @return the minimum number of digits 736 * @see #setMinimumIntegerDigits 737 */ 738 public int getMinimumIntegerDigits() { 739 return minimumIntegerDigits; 740 } 741 742 /** 743 * Sets the minimum number of digits allowed in the integer portion of a 744 * number. minimumIntegerDigits must be ≤ maximumIntegerDigits. If the 745 * new value for minimumIntegerDigits exceeds the current value 746 * of maximumIntegerDigits, then maximumIntegerDigits will also be set to 747 * the new value 748 * 749 * @param newValue the minimum number of integer digits to be shown; if 750 * less than zero, then zero is used. The concrete subclass may enforce an 751 * upper limit to this value appropriate to the numeric type being formatted. 752 * @see #getMinimumIntegerDigits 753 */ 754 public void setMinimumIntegerDigits(int newValue) { 755 minimumIntegerDigits = Math.max(0,newValue); 756 if (minimumIntegerDigits > maximumIntegerDigits) { 757 maximumIntegerDigits = minimumIntegerDigits; 758 } 759 } 760 761 /** 762 * Returns the maximum number of digits allowed in the fraction portion of a 763 * number. 764 * 765 * @return the maximum number of digits. 766 * @see #setMaximumFractionDigits 767 */ 768 public int getMaximumFractionDigits() { 769 return maximumFractionDigits; 770 } 771 772 /** 773 * Sets the maximum number of digits allowed in the fraction portion of a 774 * number. maximumFractionDigits must be ≥ minimumFractionDigits. If the 775 * new value for maximumFractionDigits is less than the current value 776 * of minimumFractionDigits, then minimumFractionDigits will also be set to 777 * the new value. 778 * 779 * @param newValue the maximum number of fraction digits to be shown; if 780 * less than zero, then zero is used. The concrete subclass may enforce an 781 * upper limit to this value appropriate to the numeric type being formatted. 782 * @see #getMaximumFractionDigits 783 */ 784 public void setMaximumFractionDigits(int newValue) { 785 maximumFractionDigits = Math.max(0,newValue); 786 if (maximumFractionDigits < minimumFractionDigits) { 787 minimumFractionDigits = maximumFractionDigits; 788 } 789 } 790 791 /** 792 * Returns the minimum number of digits allowed in the fraction portion of a 793 * number. 794 * 795 * @return the minimum number of digits 796 * @see #setMinimumFractionDigits 797 */ 798 public int getMinimumFractionDigits() { 799 return minimumFractionDigits; 800 } 801 802 /** 803 * Sets the minimum number of digits allowed in the fraction portion of a 804 * number. minimumFractionDigits must be ≤ maximumFractionDigits. If the 805 * new value for minimumFractionDigits exceeds the current value 806 * of maximumFractionDigits, then maximumIntegerDigits will also be set to 807 * the new value 808 * 809 * @param newValue the minimum number of fraction digits to be shown; if 810 * less than zero, then zero is used. The concrete subclass may enforce an 811 * upper limit to this value appropriate to the numeric type being formatted. 812 * @see #getMinimumFractionDigits 813 */ 814 public void setMinimumFractionDigits(int newValue) { 815 minimumFractionDigits = Math.max(0,newValue); 816 if (maximumFractionDigits < minimumFractionDigits) { 817 maximumFractionDigits = minimumFractionDigits; 818 } 819 } 820 821 /** 822 * Gets the currency used by this number format when formatting 823 * currency values. The initial value is derived in a locale dependent 824 * way. The returned value may be null if no valid 825 * currency could be determined and no currency has been set using 826 * {@link #setCurrency(java.util.Currency) setCurrency}. 827 * <p> 828 * The default implementation throws 829 * <code>UnsupportedOperationException</code>. 830 * 831 * @return the currency used by this number format, or <code>null</code> 832 * @exception UnsupportedOperationException if the number format class 833 * doesn't implement currency formatting 834 * @since 1.4 835 */ 836 public Currency getCurrency() { 837 throw new UnsupportedOperationException(); 838 } 839 840 /** 841 * Sets the currency used by this number format when formatting 842 * currency values. This does not update the minimum or maximum 843 * number of fraction digits used by the number format. 844 * <p> 845 * The default implementation throws 846 * <code>UnsupportedOperationException</code>. 847 * 848 * @param currency the new currency to be used by this number format 849 * @exception UnsupportedOperationException if the number format class 850 * doesn't implement currency formatting 851 * @exception NullPointerException if <code>currency</code> is null 852 * @since 1.4 853 */ 854 public void setCurrency(Currency currency) { 855 throw new UnsupportedOperationException(); 856 } 857 858 /** 859 * Gets the {@link java.math.RoundingMode} used in this NumberFormat. 860 * The default implementation of this method in NumberFormat 861 * always throws {@link java.lang.UnsupportedOperationException}. 862 * Subclasses which handle different rounding modes should override 863 * this method. 864 * 865 * @exception UnsupportedOperationException The default implementation 866 * always throws this exception 867 * @return The <code>RoundingMode</code> used for this NumberFormat. 868 * @see #setRoundingMode(RoundingMode) 869 * @since 1.6 870 */ 871 public RoundingMode getRoundingMode() { 872 throw new UnsupportedOperationException(); 873 } 874 875 /** 876 * Sets the {@link java.math.RoundingMode} used in this NumberFormat. 877 * The default implementation of this method in NumberFormat always 878 * throws {@link java.lang.UnsupportedOperationException}. 879 * Subclasses which handle different rounding modes should override 880 * this method. 881 * 882 * @exception UnsupportedOperationException The default implementation 883 * always throws this exception 884 * @exception NullPointerException if <code>roundingMode</code> is null 885 * @param roundingMode The <code>RoundingMode</code> to be used 886 * @see #getRoundingMode() 887 * @since 1.6 888 */ 889 public void setRoundingMode(RoundingMode roundingMode) { 890 throw new UnsupportedOperationException(); 891 } 892 893 // =======================privates=============================== 894 895 private static NumberFormat getInstance(Locale desiredLocale, 896 int choice) { 897 LocaleProviderAdapter adapter; 898 adapter = LocaleProviderAdapter.getAdapter(NumberFormatProvider.class, 899 desiredLocale); 900 NumberFormat numberFormat = getInstance(adapter, desiredLocale, choice); 901 if (numberFormat == null) { 902 numberFormat = getInstance(LocaleProviderAdapter.forJRE(), 903 desiredLocale, choice); 904 } 905 return numberFormat; 906 } 907 908 private static NumberFormat getInstance(LocaleProviderAdapter adapter, 909 Locale locale, int choice) { 910 NumberFormatProvider provider = adapter.getNumberFormatProvider(); 911 NumberFormat numberFormat = null; 912 switch (choice) { 913 case NUMBERSTYLE: 914 numberFormat = provider.getNumberInstance(locale); 915 break; 916 case PERCENTSTYLE: 917 numberFormat = provider.getPercentInstance(locale); 918 break; 919 case CURRENCYSTYLE: 920 numberFormat = provider.getCurrencyInstance(locale); 921 break; 922 case INTEGERSTYLE: 923 numberFormat = provider.getIntegerInstance(locale); 924 break; 925 } 926 return numberFormat; 927 } 928 929 /** 930 * First, read in the default serializable data. 931 * 932 * Then, if <code>serialVersionOnStream</code> is less than 1, indicating that 933 * the stream was written by JDK 1.1, 934 * set the <code>int</code> fields such as <code>maximumIntegerDigits</code> 935 * to be equal to the <code>byte</code> fields such as <code>maxIntegerDigits</code>, 936 * since the <code>int</code> fields were not present in JDK 1.1. 937 * Finally, set serialVersionOnStream back to the maximum allowed value so that 938 * default serialization will work properly if this object is streamed out again. 939 * 940 * <p>If <code>minimumIntegerDigits</code> is greater than 941 * <code>maximumIntegerDigits</code> or <code>minimumFractionDigits</code> 942 * is greater than <code>maximumFractionDigits</code>, then the stream data 943 * is invalid and this method throws an <code>InvalidObjectException</code>. 944 * In addition, if any of these values is negative, then this method throws 945 * an <code>InvalidObjectException</code>. 946 * 947 * @since 1.2 948 */ 949 private void readObject(ObjectInputStream stream) 950 throws IOException, ClassNotFoundException 951 { 952 stream.defaultReadObject(); 953 if (serialVersionOnStream < 1) { 954 // Didn't have additional int fields, reassign to use them. 955 maximumIntegerDigits = maxIntegerDigits; 956 minimumIntegerDigits = minIntegerDigits; 957 maximumFractionDigits = maxFractionDigits; 958 minimumFractionDigits = minFractionDigits; 959 } 960 if (minimumIntegerDigits > maximumIntegerDigits || 961 minimumFractionDigits > maximumFractionDigits || 962 minimumIntegerDigits < 0 || minimumFractionDigits < 0) { 963 throw new InvalidObjectException("Digit count range invalid"); 964 } 965 serialVersionOnStream = currentSerialVersion; 966 } 967 968 /** 969 * Write out the default serializable data, after first setting 970 * the <code>byte</code> fields such as <code>maxIntegerDigits</code> to be 971 * equal to the <code>int</code> fields such as <code>maximumIntegerDigits</code> 972 * (or to <code>Byte.MAX_VALUE</code>, whichever is smaller), for compatibility 973 * with the JDK 1.1 version of the stream format. 974 * 975 * @since 1.2 976 */ 977 private void writeObject(ObjectOutputStream stream) 978 throws IOException 979 { 980 maxIntegerDigits = (maximumIntegerDigits > Byte.MAX_VALUE) ? 981 Byte.MAX_VALUE : (byte)maximumIntegerDigits; 982 minIntegerDigits = (minimumIntegerDigits > Byte.MAX_VALUE) ? 983 Byte.MAX_VALUE : (byte)minimumIntegerDigits; 984 maxFractionDigits = (maximumFractionDigits > Byte.MAX_VALUE) ? 985 Byte.MAX_VALUE : (byte)maximumFractionDigits; 986 minFractionDigits = (minimumFractionDigits > Byte.MAX_VALUE) ? 987 Byte.MAX_VALUE : (byte)minimumFractionDigits; 988 stream.defaultWriteObject(); 989 } 990 991 // Constants used by factory methods to specify a style of format. 992 private static final int NUMBERSTYLE = 0; 993 private static final int CURRENCYSTYLE = 1; 994 private static final int PERCENTSTYLE = 2; 995 private static final int SCIENTIFICSTYLE = 3; 996 private static final int INTEGERSTYLE = 4; 997 998 /** 999 * True if the grouping (i.e. thousands) separator is used when 1000 * formatting and parsing numbers. 1001 * 1002 * @serial 1003 * @see #isGroupingUsed 1004 */ 1005 private boolean groupingUsed = true; 1006 1007 /** 1008 * The maximum number of digits allowed in the integer portion of a 1009 * number. <code>maxIntegerDigits</code> must be greater than or equal to 1010 * <code>minIntegerDigits</code>. 1011 * <p> 1012 * <strong>Note:</strong> This field exists only for serialization 1013 * compatibility with JDK 1.1. In Java platform 2 v1.2 and higher, the new 1014 * <code>int</code> field <code>maximumIntegerDigits</code> is used instead. 1015 * When writing to a stream, <code>maxIntegerDigits</code> is set to 1016 * <code>maximumIntegerDigits</code> or <code>Byte.MAX_VALUE</code>, 1017 * whichever is smaller. When reading from a stream, this field is used 1018 * only if <code>serialVersionOnStream</code> is less than 1. 1019 * 1020 * @serial 1021 * @see #getMaximumIntegerDigits 1022 */ 1023 private byte maxIntegerDigits = 40; 1024 1025 /** 1026 * The minimum number of digits allowed in the integer portion of a 1027 * number. <code>minimumIntegerDigits</code> must be less than or equal to 1028 * <code>maximumIntegerDigits</code>. 1029 * <p> 1030 * <strong>Note:</strong> This field exists only for serialization 1031 * compatibility with JDK 1.1. In Java platform 2 v1.2 and higher, the new 1032 * <code>int</code> field <code>minimumIntegerDigits</code> is used instead. 1033 * When writing to a stream, <code>minIntegerDigits</code> is set to 1034 * <code>minimumIntegerDigits</code> or <code>Byte.MAX_VALUE</code>, 1035 * whichever is smaller. When reading from a stream, this field is used 1036 * only if <code>serialVersionOnStream</code> is less than 1. 1037 * 1038 * @serial 1039 * @see #getMinimumIntegerDigits 1040 */ 1041 private byte minIntegerDigits = 1; 1042 1043 /** 1044 * The maximum number of digits allowed in the fractional portion of a 1045 * number. <code>maximumFractionDigits</code> must be greater than or equal to 1046 * <code>minimumFractionDigits</code>. 1047 * <p> 1048 * <strong>Note:</strong> This field exists only for serialization 1049 * compatibility with JDK 1.1. In Java platform 2 v1.2 and higher, the new 1050 * <code>int</code> field <code>maximumFractionDigits</code> is used instead. 1051 * When writing to a stream, <code>maxFractionDigits</code> is set to 1052 * <code>maximumFractionDigits</code> or <code>Byte.MAX_VALUE</code>, 1053 * whichever is smaller. When reading from a stream, this field is used 1054 * only if <code>serialVersionOnStream</code> is less than 1. 1055 * 1056 * @serial 1057 * @see #getMaximumFractionDigits 1058 */ 1059 private byte maxFractionDigits = 3; // invariant, >= minFractionDigits 1060 1061 /** 1062 * The minimum number of digits allowed in the fractional portion of a 1063 * number. <code>minimumFractionDigits</code> must be less than or equal to 1064 * <code>maximumFractionDigits</code>. 1065 * <p> 1066 * <strong>Note:</strong> This field exists only for serialization 1067 * compatibility with JDK 1.1. In Java platform 2 v1.2 and higher, the new 1068 * <code>int</code> field <code>minimumFractionDigits</code> is used instead. 1069 * When writing to a stream, <code>minFractionDigits</code> is set to 1070 * <code>minimumFractionDigits</code> or <code>Byte.MAX_VALUE</code>, 1071 * whichever is smaller. When reading from a stream, this field is used 1072 * only if <code>serialVersionOnStream</code> is less than 1. 1073 * 1074 * @serial 1075 * @see #getMinimumFractionDigits 1076 */ 1077 private byte minFractionDigits = 0; 1078 1079 /** 1080 * True if this format will parse numbers as integers only. 1081 * 1082 * @serial 1083 * @see #isParseIntegerOnly 1084 */ 1085 private boolean parseIntegerOnly = false; 1086 1087 // new fields for 1.2. byte is too small for integer digits. 1088 1089 /** 1090 * The maximum number of digits allowed in the integer portion of a 1091 * number. <code>maximumIntegerDigits</code> must be greater than or equal to 1092 * <code>minimumIntegerDigits</code>. 1093 * 1094 * @serial 1095 * @since 1.2 1096 * @see #getMaximumIntegerDigits 1097 */ 1098 private int maximumIntegerDigits = 40; 1099 1100 /** 1101 * The minimum number of digits allowed in the integer portion of a 1102 * number. <code>minimumIntegerDigits</code> must be less than or equal to 1103 * <code>maximumIntegerDigits</code>. 1104 * 1105 * @serial 1106 * @since 1.2 1107 * @see #getMinimumIntegerDigits 1108 */ 1109 private int minimumIntegerDigits = 1; 1110 1111 /** 1112 * The maximum number of digits allowed in the fractional portion of a 1113 * number. <code>maximumFractionDigits</code> must be greater than or equal to 1114 * <code>minimumFractionDigits</code>. 1115 * 1116 * @serial 1117 * @since 1.2 1118 * @see #getMaximumFractionDigits 1119 */ 1120 private int maximumFractionDigits = 3; // invariant, >= minFractionDigits 1121 1122 /** 1123 * The minimum number of digits allowed in the fractional portion of a 1124 * number. <code>minimumFractionDigits</code> must be less than or equal to 1125 * <code>maximumFractionDigits</code>. 1126 * 1127 * @serial 1128 * @since 1.2 1129 * @see #getMinimumFractionDigits 1130 */ 1131 private int minimumFractionDigits = 0; 1132 1133 static final int currentSerialVersion = 1; 1134 1135 /** 1136 * Describes the version of <code>NumberFormat</code> present on the stream. 1137 * Possible values are: 1138 * <ul> 1139 * <li><b>0</b> (or uninitialized): the JDK 1.1 version of the stream format. 1140 * In this version, the <code>int</code> fields such as 1141 * <code>maximumIntegerDigits</code> were not present, and the <code>byte</code> 1142 * fields such as <code>maxIntegerDigits</code> are used instead. 1143 * 1144 * <li><b>1</b>: the 1.2 version of the stream format. The values of the 1145 * <code>byte</code> fields such as <code>maxIntegerDigits</code> are ignored, 1146 * and the <code>int</code> fields such as <code>maximumIntegerDigits</code> 1147 * are used instead. 1148 * </ul> 1149 * When streaming out a <code>NumberFormat</code>, the most recent format 1150 * (corresponding to the highest allowable <code>serialVersionOnStream</code>) 1151 * is always written. 1152 * 1153 * @serial 1154 * @since 1.2 1155 */ 1156 private int serialVersionOnStream = currentSerialVersion; 1157 1158 // Removed "implements Cloneable" clause. Needs to update serialization 1159 // ID for backward compatibility. 1160 static final long serialVersionUID = -2308460125733713944L; 1161 1162 1163 // 1164 // class for AttributedCharacterIterator attributes 1165 // 1166 /** 1167 * Defines constants that are used as attribute keys in the 1168 * <code>AttributedCharacterIterator</code> returned 1169 * from <code>NumberFormat.formatToCharacterIterator</code> and as 1170 * field identifiers in <code>FieldPosition</code>. 1171 * 1172 * @since 1.4 1173 */ 1174 public static class Field extends Format.Field { 1175 1176 // Proclaim serial compatibility with 1.4 FCS 1177 private static final long serialVersionUID = 7494728892700160890L; 1178 1179 // table of all instances in this class, used by readResolve 1180 private static final Map<String, Field> instanceMap = new HashMap<>(11); 1181 1182 /** 1183 * Creates a Field instance with the specified 1184 * name. 1185 * 1186 * @param name Name of the attribute 1187 */ 1188 protected Field(String name) { 1189 super(name); 1190 if (this.getClass() == NumberFormat.Field.class) { 1191 instanceMap.put(name, this); 1192 } 1193 } 1194 1195 /** 1196 * Resolves instances being deserialized to the predefined constants. 1197 * 1198 * @throws InvalidObjectException if the constant could not be resolved. 1199 * @return resolved NumberFormat.Field constant 1200 */ 1201 @Override 1202 protected Object readResolve() throws InvalidObjectException { 1203 if (this.getClass() != NumberFormat.Field.class) { 1204 throw new InvalidObjectException("subclass didn't correctly implement readResolve"); 1205 } 1206 1207 Object instance = instanceMap.get(getName()); 1208 if (instance != null) { 1209 return instance; 1210 } else { 1211 throw new InvalidObjectException("unknown attribute name"); 1212 } 1213 } 1214 1215 /** 1216 * Constant identifying the integer field. 1217 */ 1218 public static final Field INTEGER = new Field("integer"); 1219 1220 /** 1221 * Constant identifying the fraction field. 1222 */ 1223 public static final Field FRACTION = new Field("fraction"); 1224 1225 /** 1226 * Constant identifying the exponent field. 1227 */ 1228 public static final Field EXPONENT = new Field("exponent"); 1229 1230 /** 1231 * Constant identifying the decimal separator field. 1232 */ 1233 public static final Field DECIMAL_SEPARATOR = 1234 new Field("decimal separator"); 1235 1236 /** 1237 * Constant identifying the sign field. 1238 */ 1239 public static final Field SIGN = new Field("sign"); 1240 1241 /** 1242 * Constant identifying the grouping separator field. 1243 */ 1244 public static final Field GROUPING_SEPARATOR = 1245 new Field("grouping separator"); 1246 1247 /** 1248 * Constant identifying the exponent symbol field. 1249 */ 1250 public static final Field EXPONENT_SYMBOL = new 1251 Field("exponent symbol"); 1252 1253 /** 1254 * Constant identifying the percent field. 1255 */ 1256 public static final Field PERCENT = new Field("percent"); 1257 1258 /** 1259 * Constant identifying the permille field. 1260 */ 1261 public static final Field PERMILLE = new Field("per mille"); 1262 1263 /** 1264 * Constant identifying the currency field. 1265 */ 1266 public static final Field CURRENCY = new Field("currency"); 1267 1268 /** 1269 * Constant identifying the exponent sign field. 1270 */ 1271 public static final Field EXPONENT_SIGN = new Field("exponent sign"); 1272 } 1273 }