java.text Documentation Differences

This file contains all the changes in documentation in the package java.text as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

An AttributedCharacterIterator allows iteration through both text and related attribute information.

An attribute is a key/value pair identified by the key. No two attributes on a given character can have the same key.

The values for an attribute are immutable or must not be mutated by clients or storage. They are always passed by reference and not cloned.

A run with respect to an attribute is a maximum text range for which:

• the attribute is undefined or null for the entire range or
• the attribute value is defined and has the same non-null value for the entire range.

A run with respect to a set of attributes is a maximum text range for which this condition is met for each member attribute.

The returned indexes are limited to the range of the iterator.

The returned attribute information is limited to runs that contain the current character.

Attribute keys are instances of AttributedCharacterIterator.Attribute and its subclasses such as java.awt.font.TextAttribute. @see AttributedCharacterIterator.Attribute @see java.awt.font.TextAttribute @see AttributedString @see Annotation @since JDK11.2

Gets the character at the current position (as returned by getIndex()). @return the character at the current position or DONE if the current position is off the end of the text. @see #getIndex()

Sets the position to getBeginIndex() and returns the character at that position. @return the first character in the text or DONE if the text is empty @see #getBeginIndex()

Sets the position to getEndIndex()-1 (getEndIndex() if the text is empty) and returns the character at that position. @return the last character in the text or DONE if the text is empty @see #getEndIndex()

The CollationElementIterator class is used as an iterator to walk through each character of an international string. Use the iterator to return the ordering priority of the positioned character. The ordering priority of a character which we refer to as a key defines how a character is collated in the given collation object.

For example consider the following in Spanish:

 "ca" -> the first key is key('c') and second key is key('a'). "cha" -> the first key is key('ch') and second key is key('a'). 

And in German

 "äb"-> the first key is key('a') the second key is key('e') and the third key is key('b'). 

The key of a character is an integer composed of primary order(short) secondary order(byte) and tertiary order(byte). Java strictly defines the size and signedness of its primitive data types. Therefore the static functions primaryOrder secondaryOrder and tertiaryOrder return int short and short respectively to ensure the correctness of the key value.

Example of the iterator usage

 // get the first key of the string String str = "This is a test"; CollationElementIterator c = new CollationElementIterator(str 0 str.length() Collator.getInstance()); int primaryOrder = CollationElementIterator.primaryOrder(c->next()); 

CollationElementIterator.next returns the collation order of the next character. A collation order consists of primary order secondary order and tertiary order. The data type of the collation order is int. The first 16 bits of a collation order is its primary order; the next 8 bits is the secondary order and the last 8 bits is the tertiary order. @see Collator @see RuleBasedCollator @version 1.24 07/27/98 @author Helena Shih Laura Werner Richard Gillam

GetsReturns the character offset ofin the currentoriginal character in thetext corresponding to the sourcenext textcollation element. (That is getOffset() returns the position in the text corresponding to the collation element that will be returned by the next call to next().) This value will returnalways be the Collation element for thisindex of the FIRST character corresponding to the collation element (possiblya contracting character sequence is includingwhen two or more than onecharacters all charactercorrespond to the same collation element). This means if requiredyou do setOffset(x) followed immediately by thegetOffset() languagegetOffset() won't necessarily return x. @return The character offset in the original text corresponding to the collation element that will be returned ofsetby the next call to next().

Get the next collation element in the string.

This iterator iterates over a sequence of collation elements that were built from the string. Because there isn't necessarily a one-to-one mapping from characters to collation elements this doesn't mean the same thing as "return the collation element [or ordering priority] of the next character in the string".

@return

This function returns the nextcollation character'selement orderingthat the iterator is currently pointing to and then updates the internal pointer to point to the next element. Returnsprevious() updates the pointer first and NULLORDER ifthen returns the endelement. of stringThis means isthat when you change direction while iterating (i.e. call next() and then call previous() or call previous() and then call next()) you'll get back the same element reachedtwice.

Get the orderingprevious prioritycollation element in the string.

This iterator iterates over a sequence of collation elements that were built from the previousstring. Because there isn't necessarily a one-to-one mapping from characters to collation elements this doesn't mean the same thing as "return the collation element [or ordering priority] of the previous character in the string".

@return

This function updates the previousiterator's internal pointer to point to the collation element preceding the one it's ordering.currently pointing to and then returns that element Returnswhile NULLORDERnext() ifreturns the beginningcurrent ofelement stringand then updates the pointer. isThis means that when you change direction while iterating (i.e. call next() and then call previous() or call previous() and then call next()) you'll get back the same element reachedtwice.

GetReturn the primary ordercomponent of a collation orderelement. @param order the collation orderelement @return the primary order of aelement's collationprimary order.component

Resets the cursor to the beginning of the string. The next call to next() will return the first collation element in the string.

GetReturn the secondary ordercomponent of a collation orderelement. @param order the collation orderelement @return the secondary order of aelement's collationsecondary order.component

Sets the positioniterator to point to the collation element corresponding to the specified character (the parameter is a CHARACTER offset in the original string not an offset into withinits corresponding sequence of collation elements). The value returned by the next call to next() will be the collation element corresponding to the sourcespecified position in the text. If that position is in the middle of a contracting character sequence the result of the next call to next() is the collation element for that sequence. This means that getOffset() is not guaranteed to return the same value as was passed to a preceding call to setOffset(). @param newOffset The new offset relative tocharacter offset into the start of theoriginal text.

GetReturn the tertiary ordercomponent of a collation orderelement. @param order the collation orderelement @return the tertiary order of aelement's collationtertiary order.component

A CollationKey represents a String under the rules of a specific Collator object. Comparing two CollationKeys returns the relative order of the Strings they represent. Using CollationKeys to compare Strings is generally faster than using Collator.compare. Thus when the Strings must be compared multiple times for example when sorting a list of Strings. It's more efficient to use CollationKeys.

You can not create CollationKeys directly. Rather generate them by calling Collator.getCollationKey. You can only compare CollationKeys generated from the same Collator object.

Generating a CollationKey for a String involves examining the entire String and converting it to series of bits that can be compared bitwise. This allows fast comparisons once the keys are generated. The cost of generating keys is recouped in faster comparisons when Strings need to be compared many times. On the other hand the result of a comparison is often determined by the first couple of characters of each String. Collator.compare examines only as many characters as it needs which allows it to be faster when doing single comparisons.

The following example shows how CollationKeys might be used to sort a list of Strings.

 // Create an array of CollationKeys for the Strings to be sorted. Collator myCollator = Collator.getInstance(); CollationKey[] keys = new CollationKey[3]; keys[0] = myCollator.getCollationKey("Tom"); keys[1] = myCollator.getCollationKey("Dick"); keys[2] = myCollator.getCollationKey("Harry"); sort( keys ); 
 //... 
 // Inside body of sort routine compare keys this way if( keys[i].compareTo( keys[j] ) > 0 ) // swap keys[i] and keys[j] 
 //... 
 // Finally when we've returned from sort. System.out.println( keys[0].getSourceString() ); System.out.println( keys[1].getSourceString() ); System.out.println( keys[2].getSourceString() ); 

@see Collator @see RuleBasedCollator @version 1.414 28 Jan 199701/19/00 @author Helena Shih

Compares this CollationKey with the specified Object for order. Returns a negative integer zero or a positive integer as this CollationKey is less than equal to or greater than the given Object. @param o the Object to be compared. @return a negative integer zero or a positive integer as this Collation Key is less than equal to or greater than the given Object. @exception ClassCastException the specified Object is not a CollationKey. @see Comparable @since JDK11.2

The Collator class performs locale-sensitive String comparison. You use this class to build searching and sorting routines for natural language text.

Collator is an abstract base class. Subclasses implement specific collation strategies. One subclass RuleBasedCollator is currently provided with the JDKJava 2 platform and is applicable to a wide set of languages. Other subclasses may be created to handle more specialized needs.

Like other locale-sensitive classes you can use the static factory method getInstance to obtain the appropriate Collator object for a given locale. You will only need to look at the subclasses of Collator if you need to understand the details of a particular collation strategy or if you need to modify that strategy.

The following example shows how to compare two strings using the Collator for the default locale.

 // Compare two strings in the default locale Collator myCollator = Collator.getInstance(); if( myCollator.compare("abc" "ABC") <0 ) System.out.println("abc is less than ABC"); else System.out.println("abc is greater than or equal to ABC"); 

You can set a Collator's strength property to determine the level of difference considered significant in comparisons. Four strengths are provided: PRIMARY SECONDARY TERTIARY and IDENTICAL. The exact assignment of strengths to language features is locale dependant. For example in Czech "e" and "f" are considered primary differences while "e" and "ê" are secondary differences "e" and "E" are tertiary differences and "e" and "e" are identical. The following shows how both case and accents could be ignored for US English.

 //Get the Collator for US English and set its strength to PRIMARY Collator usCollator = Collator.getInstance(Locale.US); usCollator.setStrength(Collator.PRIMARY); if( usCollator.compare("abc" "ABC") == 0 ) { System.out.println("Strings are equivalent"); } 

For comparing Strings exactly once the compare method provides the best performance. When sorting a list of Strings however it is generally necessary to compare each String multiple times. In this case CollationKeys provide better performance. The CollationKey class converts a String to a series of bits that can be compared bitwise against other CollationKeys. A CollationKey is created by a Collator object for a given String.
Note: CollationKeys from different Collators can not be compared. See the class description for CollationKey for an example using CollationKeys. @see RuleBasedCollator @see CollationKey @see CollationElementIterator @see Locale @version 1.21 1127 01/1619/9800 @author Helena Shih Laura Werner Richard Gillam

Compares its two arguments for order. Returns a negative integer zero or a positive integer as the first argument is less than equal to or greater than the second.

This implementation merely returns compare((String)o1 (String)o2) . @return a negative integer zero or a positive integer as the first argument is less than equal to or greater than the second. @exception ClassCastException the arguments cannot be cast to Strings. @see java.util.Comparator @since JDK11.2

DateFormat is an abstract class for date/time formatting subclasses which formats and parses dates or time in a language-independent manner. The date/time formatting subclass such as SimpleDateFormat allows for formatting (i.e. date -> text) parsing (text -> date) and normalization. The date is represented as a Date object or as the milliseconds since January 1 1970 00:00:00 GMT.

DateFormat provides many class methods for obtaining default date/time formatters based on the default or a given loacle and a number of formatting styles. The formatting styles include FULL LONG MEDIUM and SHORT. More detail and examples of using these styles are provided in the method descriptions.

DateFormat helps you to format and parse dates for any locale. Your code can be completely independent of the locale conventions for months days of the week or even the calendar format: lunar vs. solar.

To format a date for the current Locale use one of the static factory methods:

 myString = DateFormat.getDateInstance().format(myDate); 

If you are formatting multiple numbers it is more efficient to get the format and use it multiple times so that the system doesn't have to fetch the information about the local language and country conventions multiple times.

 DateFormat df = DateFormat.getDateInstance(); for (int i = 0; i  
To format a number for a different Locale specify it in the call to getDateInstance(). 
 DateFormat df = DateFormat.getDateInstance(Locale.FRANCE); 
 
You can use a DateFormat to parse also. 
 myDate = df.parse(myString); 
 
Use getDategetDateInstance to get the normal date format for that country. There are other static factory methods available. Use getTimegetTimeInstance to get the time format for that country. Use getDateTimegetDateTimeInstance to get a date and time format. You can pass in different options to these factory methods to control the length of the result; from SHORT to MEDIUM to LONG to FULL. The exact result depends on the locale but generally: 
SHORT is completely numeric such as 12.13.52 or 3:30pm 
MEDIUM is longer such as Jan 12 1952 
LONG is longer such as January 12 1952 or 3:30:32pm 
FULL is pretty completely specified such as Tuesday April 12 1952 AD or 3:30:42pm PST. 
 
You can also set the time zone on the format if you wish. If you want even more control over the format or parsing (or want to give your users more control) you can try casting the DateFormat you get from the factory methods to a SimpleDateFormat. This will work for the majority of countries; just remember to put it in a try block in case you encounter an unusual one. 
You can also use forms of the parse and format methods with ParsePosition and FieldPosition to allow you to 
progressively parse through pieces of a string. 
align any particular field or find out where it is for selection on the screen. 
 @see Format @see NumberFormat @see SimpleDateFormat @see java.util.Calendar @see java.util.GregorianCalendar @see java.util.TimeZone @version 1.3238 0901/2319/9800 @author Mark Davis Chen-Lieh Huang Alan Liu

Constant for default style pattern. Its value is MEDIUM.

DateFormatSymbols is a public class for encapsulating localizable date-time formatting data such as the names of the months the names of the days of the week and the time zone data. DateFormat and SimpleDateFormat both use DateFormatSymbols to encapsulate this information.

Typically you shouldn't use DateFormatSymbols directly. Rather you are encouraged to create a date-time formatter with the DateFormat class's factory methods: getTimeInstance getDateInstance or getDateTimeInstance. These methods automatically create a DateFormatSymbols for the formatter so that you don't have to. After the formatter is created you may modify its format pattern using the setPattern method. For more information about creating formatters using DateFormat's factory methods see DateFormat

If you decide to create a date-time formatter with a specific format pattern for a specific locale you can do so with:

 new SimpleDateFormat(aPattern new DateFormatSymbols(aLocale)). 

DateFormatSymbols objects are clonable. When you obtain a DateFormatSymbols object feel free to modify the date-time formatting data. For instance you can replace the localized date-time format pattern characters with the ones that you feel easy to remember. Or you can change the representative cities to your favorite ones.

New DateFormatSymbols subclasses may be added to support SimpleDateFormat for date-time formatting for additional locales. @see DateFormat @see SimpleDateFormat @see java.util.SimpleTimeZone @version 1.30 0932 01/2319/9800 @author Chen-Lieh Huang

DecimalFormat is a concrete subclass of NumberFormat for formattingthat formats decimal numbers. This classIt allows forhas a variety of parameters andfeatures designed localizationto make it possible to parse and format numbers in any locale including support for Western Arabic orand Indic digits. It also supports different kinds of numbers including integers (123) fixed-point numbers (123.4) Normallyscientific notation you(1.23E4) getpercentages the(12%) and currency amounts ($123). All of these can be localized. proper

To obtain a NumberFormat for a specific locale (including the default locale) usingcall one of NumberFormat's factory methods such as getInstance(). You may then modify it from there (after testing toIn make sure it is ageneral do not call the DecimalFormat of course ) Eitherconstructors the prefixesdirectly orsince the suffixes must be differentNumberFormat for the parse to distinguish positive fromfactory methods may return subclasses other than negativeDecimalFormat. Parsing will be unreliable ifIf you need to customize the digits thousandsformat or decimal separators areobject do something like thethis: same

 or if anyNumberFormat f = ofNumberFormat.getInstance(loc); themif occur(f ininstanceof theDecimalFormat) prefixes{ or((DecimalFormat) suffixesf). setDecimalSeparatorAlwaysShown(true); Special} cases:

A NaNDecimalFormat is formatted ascomprises a singlepattern character typicallyand a \\uFFFD.set of +/-Infinitysymbols. is formatted as a single character typicallyThe pattern may be set directly using \\u221EapplyPattern() plus the positive and negativeor indirectly using the API pre/suffixesmethods. The symbols are stored in a Note:DecimalFormatSymbols this classobject. is designed forWhen using the commonNumberFormat users;factory for very large or small numbers use a formatmethods the pattern and symbols are read from localized thatResourceBundles can express exponentialin the package valuesjava.text.resource.

Example:

 // normallyPrint out we would have a GUI witha number using the localized number acurrency // and percent menuformat for thiseach locale Locale[] locales = NumberFormat.getAvailableLocales(); double myNumber = -1234.56; NumberFormat form; // just for fun we print out a number with the locale number currency // and percent format for each locale we can. for (int j = 0; j <3; ++j) { System.out.println("FORMAT"); for (int i = 0; i continue; // skipSkip language-only continue;locales } System.out.print(locales[i].getDisplayName()); switch (j) { defaultcase 0: form = NumberFormat.getInstance(locales[i]); break; case 1: form = NumberFormat.getCurrencyInstance(locales[i]); break; case 0default: form = NumberFormat.getPercentInstance(locales[i]); break; } try { // Assume form is a DecimalFormat System.out.print(": " + ((DecimalFormat) form).toPattern() + " -> " + form.format(myNumber)); } catch (IllegalArgumentException iaee) { } try { System.out.println(" -> " + form.parse(form.format(myNumber))); } catch (ParseException pee) { } } } 

ThePatterns following

A showsDecimalFormat the structure of thepattern contains a postive pattern.and patternnegative subpattern :=for subpattern{example "# ##0.00;subpattern}(# ##0.00)". Each subpattern :=has {prefix}integer{.fraction}{suffix}a prefix :=numeric '\\u0000'.part and suffix.'\\uFFFD' -The negative specialCharacters suffixsubpattern is :=optional; '\\u0000'..'\\uFFFD'if - specialCharacters integerabsent then the :=positive '#'*subpattern '0'*prefixed '0'with fractionthe :=localized '0'*minus sign ('#-'* Notation:in X*most 0locales) or more instances of Xis used as the negative (Xsubpattern. |That Y)is either"0.00" X oralone is Y.equivalent Xto "0.00;-0.00".Y any character from XIf there is an upexplicit negative subpattern it serves only to Yspecify inclusive.the S - Tnegative prefix and characterssuffix; in S except those in T The first subpattern isthe number of digits minimal digits and other characteristics are all forthe same as the positive numberspattern. TheThat means secondthat "# ##0.0#;(optional#)" subpattern is for negativeproduces precisely the same numbers.behavior as "# ##0.0#;(In# both##0.0#)". cases

The ' ' can occur inside the integerprefixes suffixes and various symbols used for portion--itinfinity isdigits thousands separators decimal separators etc. just too messymay be set to indicatearbitrary invalues and they will appear BNFproperly during formatting.) HereHowever care aremust be taken that the special characters usedsymbols and strings indo not conflict or parsing will be unreliable. For example either the partspositive ofand negative prefixes or the subpattern with notes on theirsuffixes must be distinct for usageDecimalFormat.parse() Symbol Meaning 0 a digit # ato be able to distinguish positive from negative digitvalues. zero(If showsthey are identical then DecimalFormat will behave as absentif no negative subpattern was specified.) placeholder forAnother example is that the decimal separator placeholder forand groupingthousands separator. E separates mantissa and exponent for exponentialshould be distinct characters or parsing will formatsbe impossible. ;

The separatesgrouping formats.separator - default negativeis commonly used prefix.for % multiply by 100 and show asthousands but in some countries it separates percentageten-thousands. # multiply by 1000 and show as per mille # currencyThe grouping size is a constant number of digits between the sign;grouping replaced by currencycharacters such as symbol;3 if doubled replaced by international currencyfor 100 000 000 or 4 symbolfor 1 0000 0000. If present inyou supply a pattern with multiple grouping characters the monetary decimal separator is usedinterval between the last one insteadand the end of the decimalinteger separatoris the one that is used. XSo any"# other## characters### can####" be== used"###### in####" the== prefix"## #### ####".

Illegal patterns such as "#.#.#" or suffix"#.### '###" usedwill cause DecimalFormat to quote specialthrow an charactersIllegalArgumentException inwith a prefixmessage orthat suffix.describes the problem.

NotesParsing

DecimalFormat If there is no explicit negative subpattern - is prefixedparses all Unicode characters that represent decimal digits as defined toby Character.digit(). In addition DecimalFormat also recognizes as digits the positiveten form.consecutive That ischaracters starting "0.00"with alone is equivalent tothe localized zero digit "0defined in the DecimalFormatSymbols object.00; During formatting the DecimalFormatSymbols-0based digits are output.00"

DecimalFormat.parse If there is anreturns a subclass of explicitjava.lang.Number negative subpattern it servesrepresenting the parsed numeric onlystring. toDecimalFormat specifychooses the negativemost prefix andeconomical subclass suffix;that the number of digitscan represent the numeric minimalstring. digits and otherThis means most characteristicsinteger values are all thereturned as sameLong as the positiveobjects no matter pattern.how That meansthey are thatwritten: "#17" ##0and "17.0#;000" both parse to Long(#17)". has precisely the same result asValues that cannot fit into a "#Long ##0are returned as Doubles.0#;(# ##This includes values with a fractional part infinite values NaN and the value -0.0#)". IfDecimalFormat does not decide whether to return a Double or a Long based on the maximumpresence numberof a decimal separator in the source string. Doing so would prevent integers that overflow the mantissa of fraction digits is lowera double such as than"10 000 000 000 000 000.00" from being parsed accurately. Currently the actual number ofonly classes that fractionDecimalFormat digits thenreturns are format()Long willand Double but callers should not rely on this. roundCallers may use the resultNumber methods doubleValue longValue etc. to obtain the maximum numbertype they ofwant. fraction

If digitsDecimalFormat.parse(String TheParsePosition) roundingfails isto parse performed accordinga string toit returns null leaves the IEEEParsePosition 754 default rounding mode knownindex unchanged and sets the asParsePosition halferror even:index. Numbers are roundedThe convenience method towardDecimalFormat.parse(String) the nearest truncated value unless bothindicates parse failure by throwing a truncatedParseException. values

Special areValues equidistant

NaN in which case the value ending inis formatted as a single character typically an\uFFFD. even digitThis character is chosendetermined by the DecimalFormatSymbols object. ForThis exampleis formattingthe only value for which the numberprefixes 1and suffixes are not used.2499 with

Infinity is formatted as a maximum of twosingle character typically fraction\u221E digits gives two possible valueswith the positive or negative 1.24prefixes and 1.25suffixes applied. The distance toinfinity 1.24character is 0.0099determined andby the distanceDecimalFormatSymbols object.

Negative zero ("-0") parses to 1Double(-0.250) unless isParseIntegerOnly() is true in which case it parses to Long(0).0001 so

1.25Scientific isNotation chosen.

Numbers in scientific notation are expressed Onas the otherproduct hand when roundingof a mantissa 1.245and to two fraction digits the two possible valuesa power of ten for example 1234 can arebe expressed againas 1.24234 andx 110^3.25 but the distance to each isThe mantissa is often in the same:range 01.0050 < x <10.0 In this casebut it need 1not be.24 DecimalFormat can be instructed to format and parse scientific notation only via a pattern; there is chosen because it ends in an evencurrently no factory method that creates a digitscientific notation format. The exponent character must beIn a pattern the exponent character immediately followed by one or more digit characters indicates scientific notation. Example: "0.###E0" formats the number 1234 as "1.234E3".

• The number of digit characters after the exponent character gives the minimum exponent digit count; there. There is no maximum. Negative exponents are denotedformatted using the samelocalized minus sign not the prefix and/or suffix specified forfrom the numberpattern. itselfThis allows patterns such as "0.###E0 m/s".
• The minimum number of integer digits is achieved by adjusting the exponent. Example: 0.00123 formatted with "00.###E0" yields "12.3E-4". This only happens if there is no maximum number of integer digits. If there is a maximum then the minimum number of integer digits is fixed at one.
• The maximum number of integer digits if any specifiespresent forces the exponent groupingto be a multiple of that number. For exampleThe most 12345common use of this is formattedto usinggenerate engineering notation in which the exponent is a multiple of three e.g. "##0.#####E0". asUsing this pattern the number 12345 formats to "12.345E3". Illegal patterns such asand 123456 formats to "#.#123.#456E3". or
• The mixingnumber '_'of andsignificant '*'digits in the same pattern will cause anmantissa is the sum of IllegalArgumentExceptionthe tominimum beinteger and maximum fraction digits and is unaffected by the maximum integer digits. For thrownexample 12345 formatted with "##0.##E0" is "12.3E3". FromTo show all digits set the messagesignificant digits count to zero. The number of IllegalArgumentExceptionsignificant you can find thedigits does not affect placeparsing. in
• Exponential the string where the error occurredpatterns may not contain grouping separators.

Pattern TheSyntax grouping separator

 pattern is:= commonlypos_pattern{';' usedneg_pattern} forpos_pattern thousands:= but{prefix}number{suffix} inneg_pattern some:= countries{prefix}number{suffix} fornumber ten:= integer{'.' fraction}{exponent} prefix := '\u0000'..'\uFFFD' -thousands special_characters suffix := '\u0000'..'\uFFFD' The- intervalspecial_characters isinteger a:= constantmin_int number| of'#' digits| between'#' the groupinginteger | characters'#' such as 100' ' integer 000min_int 000:= '0' | '0' min_int | '0' ' ' min_int fraction := '0'* '#'* exponent := 'E' '0' '0'*   Notation: X* 0 or more instances of X { X } 0 or 1 0000instances 0000of X X | Y either X or Y X..Y If youany character supplyfrom X up to Y inclusive S - T characters in S except those in T 

Special Pattern Characters

Many characters in a pattern with multipleare taken groupingliterally; they are matched during parsing and output unchanged during formatting. Special characters on the interval between the last one and theother hand stand for other characters strings endor classes of thecharacters. integerThey ismust be quoted unless noted otherwise if they are to appear in the one thatprefix or issuffix as literals.

The characters listed here are used in non-localized patterns. SoLocalized "#patterns ##use ###the ####"corresponding ==characters "######taken ####"from ==this "##formatter's ####DecimalFormatSymbols ####"object instead and these characters lose their special status. Two exceptions are the currency sign and quote which are not localized.

WhenDecimalFormatTheanconvenient

Symbol	Location	Localized calling	Meaning
0	Number	Y	Digit
#	Number	Y	Digit zero shows as absent
.parse(String	Number	Y	Decimal ParsePosition)separator or monetary decimal separator
-	Number	Y	Minus sign
	Number	Y	Grouping separator
E	Number	Y	Separates mantissa and parsing fails aexponent in scientific nullnotation. objectNeed willnot be returnedquoted in prefix or suffix.
;	Subpattern unchangedboundary	Y parse	Separates position also reflectspositive and negative thatsubpatterns
%	Prefix erroror hassuffix	Y	Multiply occurred duringby 100 parsing.and When callingshow as thepercentage
\u2030	Prefix methodor DecimalFormat.parsesuffix	Y	Multiply by 1000 and show as per mille
¤ (String\u00A4)	Prefix andor parsingsuffix	N fails	Currency a ParseException will be thrownsign replaced by currency symbol. If This class handles all Unicodedoubled replaced by international currency characterssymbol. thatIf representpresent in a pattern the monetary decimal digits.separator Thisis setused instead of the decimal separator.
'	Prefix or suffix	N	Used to quote special characters isin defineda prefix or suffix for example "'#'#" formats 123 to "#123". To create a single quote itself use two in thea Unicoderow: "# standardo''clock".

@see java.text.Format @see java.text.NumberFormat @see java.text.ChoiceFormat @see java.text.ParsePosition @version 1.5057 01/2819/9900 @author Mark Davis @author Alan Liu

This class represents the set of symbols (such as the decimal separator the grouping separator and so on) needed by DecimalFormat to format numbers. DecimalFormat creates for itself an instance of DecimalFormatSymbols from its locale data. If you need to change any of these symbols you can get the DecimalFormatSymbols object from your DecimalFormat and modify it. @see java.util.Locale @see DecimalFormat @version 1.1230 2901/19/00 Jan 1997 @author Mark Davis @author Alan Liu

Override equals.

Gets the character used for decimal sign. Different for French etc.

Gets the character used for a digit in a pattern.

Gets the character used for thousands separator. Different for French etc.

Gets the character used to represent infinity. Almost always left unchanged.

Gets the character used to represent minus sign. If no explicit negative format is specified one is formed by prefixing minusSign to the positive format.

Gets the character used to represent NaN. Almost always left unchanged.

Gets the character used to separate positive and negative subpatterns in a pattern.

Gets the character used for mille percent sign. Different for Arabic etc.

Gets the character used for percent sign. Different for Arabic etc.

Gets the character used for zero. Different for Arabic etc.

Override hashCode.

FieldPosition is a simple class used by Format and its subclasses to identify fields in formatted output. Fields are identified by constants whose names typically end with _FIELD defined in the various subclasses of Format. See ERA_FIELD and its friends in DateFormat for an example.

FieldPosition keeps track of the position of the field within the formatted output with two indices: the index of the first character of the field and the index of the last character of the field.

One version of the format method in the various Format classes requires a FieldPosition object as an argument. You use this format method to perform partial formatting or to get information about the formatted output (such as the position of a field). @version 1.15 0716 01/2419/9800 @author Mark Davis @see java.text.Format

Format is an abstract base class for formatting locale-sensitive information such as dates messages and numbers.

Format defines the programming interface for formatting locale-sensitive objects into Strings (the format method) and for parsing Strings back into objects (the parseObject method). Any String formatted by format is guaranteed to be parseable by parseObject.

If formatting is unsuccessful because the Format object cannot format the type of object specified format throws an IllegalArgumentException. Otherwise if there is something illformed about the object format returns the Unicode replacement character \\uFFFD.

If there is no match when parsing parseObject(String) throws a ParseException and parseObject(String ParsePosition) leaves the ParsePosition index member unchanged and returns null.

Subclassing: The JDKJava 2 platform provides three concrete subclasses of Format-- DateFormat MessageFormat and NumberFormat--for formatting dates messages and numbers respectively.

Concrete subclasses must implement these two methods:

1. format(Object obj StringBuffer toAppendTo FieldPosition pos)
2. parseObject (String source ParsePosition pos)

Most subclasses will also implement the following two methods:

1. getInstance for getting a useful format object appropriate for the current locale
2. getInstance(Locale) for getting a useful format object appropriate for the specified locale

In addition some subclasses may also choose to implement other getXxxxInstance methods for more specialized control. For example the NumberFormat class provides getPercentInstance and getCurrencyInstance methods for getting specialized number formatters.

Subclasses of Format that allow programmers to create objects for locales (with getInstance(Locale) for example) must also implement the following class method:

 public static Locale[] getAvailableLocales() 

And finally subclasses may define a set of constants to identify the various fields in the formatted output. These constants are used to create a FieldPosition object which identifies what information is contained in the field and its position in the formatted result. These constants should be named item_FIELD where item identifies the field. For examples of these constants see ERA_FIELD and its friends in DateFormat @see java.text.ParsePosition @see java.text.FieldPosition @see java.text.NumberFormat @see java.text.DateFormat @see java.text.MessageFormat @version 1.24 0728 01/1019/9800 @author Mark Davis

MessageFormat provides a means to produce concatenated messages in language-neutral way. Use this to construct messages displayed for end users.

MessageFormat takes a set of objects formats them then inserts the formatted strings into the pattern at the appropriate places.

Note: MessageFormat differs from the other Format classes in that you create a MessageFormat object with one of its constructors (not with a getInstance style factory method). The factory methods aren't necessary because MessageFormat doesn't require any complex setup for a given locale. In fact MessageFormat doesn't implement any locale specific behavior at all. It just needs to be set up on a sentence by sentence basis.

Here are some examples of usage:

 Object[] arguments = { new Integer(7) new Date(System.currentTimeMillis()) "a disturbance in the Force" }; String result = MessageFormat.format( "At {1 time} on {1 date} there was {2} on planet {0 number integer}." arguments); output: At 12:30 PM on Jul 3 2053 there was a disturbance in the Force on planet 7. 

Typically the message format will come from resources and the arguments will be dynamically set at runtime.

Example 2:

 Object[] testArgs = {new Long(3) "MyDisk"}; MessageFormat form = new MessageFormat( "The disk \"{1}\" contains {0} file(s)."); System.out.println(form.format(testArgs)); // output with different testArgs output: The disk "MyDisk" contains 0 file(s). output: The disk "MyDisk" contains 1 file(s). output: The disk "MyDisk" contains 1 273 file(s). 

The pattern is of the form:

 messageFormatPattern := string ( "{" messageFormatElement "}" string )* messageFormatElement := argument { " " elementFormat } elementFormat := "time" { " " datetimeStyle } | "date" { " " datetimeStyle } | "number" { " " numberStyle } | "choice" { " " choiceStyle } datetimeStyle := "short" | "medium" | "long" | "full" | dateFormatPattern numberStyle := "currency" | "percent" | "integer" | numberFormatPattern choiceStyle := choiceFormatPattern 

If there is no elementFormat then the argument must be a string which is substituted. If there is no dateTimeStyle or numberStyle then the default format is used (for example NumberFormat.getInstance DateFormat.getTimeInstance or DateFormat.getInstance).

In strings single quotes can be used to quote the "{" (curly brace) if necessary. A real single quote is represented by ''. Inside a messageFormatElement quotes are not removed. For example {1 number $'#' ##} will produce a number format with the pound-sign quoted with a result such as: "$#31 45".

If a pattern is used then unquoted braces in the pattern if any must match: that is "ab {0} de" and "ab '}' de" are ok but "ab {0'}' de" and "ab } de" are not.

The argument is a number from 0 to 9 which corresponds to the arguments presented in an array to be formatted.

It is ok to have unused arguments in the array. With missing arguments or arguments that are not of the right class for the specified format a ParseException is thrown. First format checks to see if a Format object has been specified for the argument with the setFormats method. If so then format uses that Format object to format the argument. Otherwise the argument is formatted based on the object's type. If the argument is a Number then format uses NumberFormat.getInstance to format the argument; if the argument is a Date then format uses DateFormat.getDateTimeInstance to format the argument. Otherwise it uses the toString method.

For more sophisticated patterns you can use a ChoiceFormat to get output such as:

 MessageFormat form = new MessageFormat("The disk \"{1}\" contains {0}."); double[] filelimits = {0 1 2}; String[] filepart = {"no files" "one file" "{0 number} files"}; ChoiceFormat fileform = new ChoiceFormat(filelimits filepart); form.setFormat(1 fileform); // NOT zero see below Object[] testArgs = {new Long(12373) "MyDisk"}; System.out.println(form.format(testArgs)); // output with different testArgs output: The disk "MyDisk" contains no files. output: The disk "MyDisk" contains one file. output: The disk "MyDisk" contains 1 273 files. 

You can either do this programmatically as in the above example or by using a pattern (see ChoiceFormat for more information) as in:

 form.applyPattern( "There {0 choice 0#are no files|1#is one file|1#are {0 number integer} files}."); 

Note: As we see above the string produced by a ChoiceFormat in MessageFormat is treated specially; occurances of '{' are used to indicated subformats and cause recursion. If you create both a MessageFormat and ChoiceFormat programmatically (instead of using the string patterns) then be careful not to produce a format that recurses on itself which will cause an infinite loop.

Note: formats are numbered by order of variable in the string. This is not the same as the argument numbering For example: with "abc{2}def{3}ghi{0}..."

• format0 affects the first variable {2}
• format1 affects the second variable {3}
• format2 affects the second variable {0}
• and so on.

When a single argument is parsed more than once in the string the last match will be the final result of the parsing. For example

 MessageFormat mf = new MessageFormat("{0 number #.##} {0 number #.#}"); Object[] objs = {new Double(3.1415)}; String result = mf.format( objs ); // result now equals "3.14 3.1" objs = null; objs = mf.parse(result new ParsePosition(0)); // objs now equals {new Double(3.1)} 

Likewise parsing with a MessageFormat object using patterns containing multiple occurances of the same argument would return the last match. For example

 MessageFormat mf = new MessageFormat("{0} {0} {0}"); String forParsing = "x y z"; Object[] objs = mf.parse(forParsing new ParsePosition(0)); // result now equals {new String("z")} 

You can use setLocale followed by applyPattern (and then possibly setFormat) to re-initialize a MessageFormat with a different locale. @see java.util.Locale @see Format @see NumberFormat @see DecimalFormat @see ChoiceFormat @version 1.1538 29 Jan 199701/19/00 @author Mark Davis

NumberFormat is the abstract base class for all number formats. This class provides the interface for formatting and parsing numbers. NumberFormat also provides methods for determining which locales have number formats and what their names are.

NumberFormat helps you to format and parse numbers for any locale. Your code can be completely independent of the locale conventions for decimal points thousands-separators or even the particular decimal digits used or whether the number format is even decimal.

To format a number for the current Locale use one of the factory class methods:

 myString = NumberFormat.getInstance().format(myNumber); 

If you are formatting multiple numbers it is more efficient to get the format and use it multiple times so that the system doesn't have to fetch the information about the local language and country conventions multiple times.

 NumberFormat nf = NumberFormat.getInstance(); for (int i = 0; i  

To format a number for a different Locale specify it in the call to getInstance.

 NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH); 

You can also use a NumberFormat to parse numbers:

 myNumber = nf.parse(myString); 

Use getInstance or getNumberInstance to get the normal number format. Use getCurrencyInstance to get the currency number format. And use getPercentInstance to get a format for displaying percentages. With this format a fraction like 0.53 is displayed as 53%.

You can also control the display of numbers with such methods as setMinimumFractionDigits. If you want even more control over the format or parsing or want to give your users more control you can try casting the NumberFormat you get from the factory methods to a DecimalNumberFormat. This will work for the vast majority of locales; just remember to put it in a try block in case you encounter an unusual one.

NumberFormat and DecimalFormat are designed such that some controls work for formatting and others work for parsing. The following is the detailed description for each these control methods

setParseIntegerOnly : only affects parsing e.g. if true "3456.78" -> 3456 (and leaves the parse position just after index 6) if false "3456.78" -> 3456.78 (and leaves the parse position just after index 8) This is independent of formatting. If you want to not show a decimal point where there might be no digits after the decimal point use setDecimalSeparatorAlwaysShown.

setDecimalSeparatorAlwaysShown : only affects formatting and only where there might be no digits after the decimal point such as with a pattern like "# ##0.##" e.g. if true 3456.00 -> "3 456." if false 3456.00 -> "3456" This is independent of parsing. If you want parsing to stop at the decimal point use setParseIntegerOnly.

You can also use forms of the parse and format methods with ParsePosition and FieldPosition to allow you to:

• progressively parse through pieces of a string
• align the decimal point and other areas

For example you can align numbers in two ways:

1. If you are using a monospaced font with spacing for alignment you can pass the FieldPosition in your format call with field = INTEGER_FIELD. On output getEndIndex will be set to the offset between the last character of the integer and the decimal. Add (desiredSpaceCount - getEndIndex) spaces at the front of the string.
2. If you are using proportional fonts instead of padding with spaces measure the width of the string in pixels from the start to getEndIndex. Then move the pen by (desiredPixelWidth - widthToAlignmentPoint) before drawing the text. It also works where there is no decimal but possibly additional characters at the end e.g. with parentheses in negative numbers: "(12)" for -12.

@see DecimalFormat @see ChoiceFormat @version 1.2247 29 Jan 199701/19/00 @author Mark Davis @author Helena Shih

Signals that an error has been reached unexpectedly while parsing. @see java.lang.Exception @see java.text.Format @see java.text.FieldPosition @version 1.12 1013 01/0219/9800 @author Mark Davis

ParsePosition is a simple class used by Format and its subclasses to keep track of the current position during parsing. The parseObject method in the various Format classes requires a ParsePosition object as an argument.

By design as you parse through a string with different formats you can use the same ParsePosition since the index parameter records the current position. @version 1.14 0715 01/2419/9800 @author Mark Davis @see java.text.Format

The RuleBasedCollator class is a concrete subclass of Collator that provides a simple data-driven table collator. With this class you can create a customized table-based Collator. RuleBasedCollator maps characters to sort keys.

RuleBasedCollator has the following restrictions for efficiency (other subclasses may be used for more complex languages) :

1. If a French secondary ordering is specified it applies to the whole collator object.
2. All non-mentioned Unicode characters are at the end of the collation order.

The collation table is composed of a list of collation rules where each rule is of three forms:

The following demonstrates how to create your own collation rules:

• Text-Argument: A text-argument is any sequence of characters excluding special characters (that is common whitespace characters [0009-000D 0020] and rule syntax characters [0021-002F 003A-0040 005B-0060 007B-007E]). If those characters are desired you can put them in single quotes (e.g. ampersand => '&'). Note that unquoted white space characters are ignored; e.g. b c is treated as bc.
• Modifier: There is a single modifier which is used to specify that all accents (secondary differences) are backwards.

  '@' : Indicates that accents are sorted backwards as in French.

• Relation: The relations are the following:
  • '< : Greater as a letter difference (primary)
  • ';' : Greater as an accent difference (secondary)
  • ' ' : Greater as a case difference (tertiary)
  • '=' : Equal
• Reset: There is a single reset which is used primarily for contractions and expansions but which can also be used to add a modification at the end of a set of rules.

  '&' : Indicates that the next rule follows the position to where the reset text-argument would be sorted.

This sounds more complicated than it is in practice. For example the following are equivalent ways of expressing the same thing:

 a  

Notice that the order is important as the subsequent item goes immediately after the text-argument. The following are not equivalent:

 a  

Either the text-argument must already be present in the sequence or some initial substring of the text-argument must be present. (e.g. "a "a" (a-umlaut) is treated as though it expanded to two characters (expressed as "a A a;ã & AE A;Ã"). [ã and à are of course the escape sequences for a-umlaut.]

Ignorable Characters

For ignorable characters the first rule must start with a relation (the examples we have used above are really fragments; "a Normalization and Accents

RuleBasedCollator automatically processes its rule table to include both pre-composed and combining-character versions of accented characters. Even if the provided rule string contains only base characters and separate combining accent characters the pre-composed accented characters matching all canonical combinations of characters from the rule string will be entered in the table.

This allows you to use a RuleBasedCollator to compare accented strings even when the collator is set to NO_DECOMPOSITION. There are two caveats however. First if the strings to be collated contain combining sequences that may not be in canonical order you should set the collator to CANONICAL_DECOMPOSITION or FULL_DECOMPOSITION to enable sorting of combining sequences. Second if the strings contain characters with compatibility decompositions (such as full-width and half-width forms) you must use FULL_DECOMPOSITION since the rule tables only include canonical mappings. For more information see The Unicode Standard Version 2.0.)

Errors

The following are errors:

• A text-argument contains unquoted punctuation symbols (e.g. "a A relation or reset character not followed by a text-argument (e.g. "a A reset where the text-argument (or an initial substring of the text-argument) is not already in the sequence. (e.g. "a If you produce one of these errors a RuleBasedCollator throws a ParseException.

  Examples

  Simple: "Norwegian: " Normally to create a rule-based Collator object you will use Collator's factory method getInstance. However to create a rule-based Collator object with specialized rules tailored to your needs you construct the RuleBasedCollator with the rules contained in a String object. For example:

   String Simple = " 

  Or:

   String Norwegian = " 

  Combining Collators is as simple as concatenating strings. Here's an example that combines two Collators from two different locales:

   // Create an en_US Collator object RuleBasedCollator en_USCollator = (RuleBasedCollator) Collator.getInstance(new Locale("en" "US" "")); // Create a da_DK Collator object RuleBasedCollator da_DKCollator = (RuleBasedCollator) Collator.getInstance(new Locale("da" "DK" "")); // Combine the two // First get the collation rules from en_USCollator String en_USRules = en_USCollator.getRules(); // Second get the collation rules from da_DKCollator String da_DKRules = da_DKCollator.getRules(); RuleBasedCollator newCollator = new RuleBasedCollator(en_USRules + da_DKRules); // newCollator has the combined rules 

  Another more interesting example would be to make changes on an existing table to create a new Collator object. For example add "& C en_USCollator object to create your own:

   // Create a new Collator object with additional rules String addRules = "& C  

  The following example demonstrates how to change the order of non-spacing accents

   // old rule String oldRules = "=#;#;#;#" // main accents + ";#;#;#;#" // main accents + ";#;#;#;#" // main accents + ";#;#;#;#" // main accents + ";#;#;#;#" // main accents + " 

  The last example shows how to put new primary ordering in before the default setting. For example in Japanese Collator you can either sort English characters before or after Japanese characters

   // get en_US Collator rules RuleBasedCollator en_USCollator = (RuleBasedCollator)Collator.getInstance(Locale.US); // add a few Japanese character to sort before English characters // suppose the last character before the first base letter 'a' in // the English collation rule is # String jaString = "& # <<"; RuleBasedCollator myJapaneseCollator = new RuleBasedCollator(en_USCollator.getRules() + jaString); 

  @see Collator @see CollationElementIterator @version 1.25 07/24/98 @author Helena Shih Laura Werner Richard Gillam